[joshistoast]

Summary

Make webv2 the default UI by switching its consumers; its source stays at invokeai/frontend/webv2. Rename the legacy directory from web to webv1 with git mv in a dedicated, content-identical rename commit, followed by the reference updates. Existing Git history is preserved; persisted formats are unchanged.

Default launch, Make targets, wheel/container builds, and the shared dependency-install action now select webv2. Frontend quality CI runs webv2 only. OpenAPI/type generation and drift checks move to a shared invokeai/frontend/api package with their own pinned tools and lockfile; CI no longer installs webv1 for contract generation. Both bundles are packaged; --web-legacy explicitly selects legacy web and --webv2 remains a compatibility alias. Legacy bootstrap releases this deployment's webv2 worker and cached assets before starting.

Related Issues / Discussions

Alternative to #374, which promotes the source directory names. These are competing approaches; merge only the selected one.

QA Instructions

Validated with Node v22.14.0 from .nvmrc, pnpm 10.12.4, and the existing Python environment:

• Frozen installs for all three frontend packages. The generator dependencies move from webv1 into the shared API package; webv2's TypeScript version is unchanged. Ruff, uv lock check, commit hooks, shell syntax, and Make dry runs pass.
• pnpm -C invokeai/frontend/webv2 lint: passes, including 72 architecture tests.
• pnpm -C invokeai/frontend/webv2 check:release: passes with 9,085 unit tests, 1,901 Chromium tests, and all fixture, production-build, architecture/performance, project-file, and accessibility gates.
• Browser regression fixes reset the native pointer between tests, exercise the partial-number edit in one keyboard sequence, and await visible lazy-loaded graph rows. Assertions and performance budgets remain intact.
• OMP_NUM_THREADS=1 uv run --no-sync pytest tests/backend/ideogram4 tests/app/api/test_frontend.py: 97 pass. The real-transformer conditioning test uses float64 to retain the encoder/model dtype distinction without the CPU bfloat16 instruction crash observed on Windows CI.
• pnpm -C invokeai/frontend/webv1 lint and production bundle: pass. The suite passes 2,368 tests initially; its one stale OpenAPI path is corrected and all 51 tests in that file pass on rerun. Legacy lint/test commands remain available locally.
• uv run --no-sync pytest tests/app/api/test_frontend.py tests/test_imports.py: 11 pass. Covers default/alias/legacy flags, conflicts, prefixed URLs, assets, API routing, documentation assets, and missing bundles.
• pnpm -C docs build: passes; 331 pages build with the updated paths.
• Regenerated OpenAPI and TypeScript types are byte-identical to the pre-extraction artifacts. pnpm -C invokeai/frontend/api test and lint pass; real TypeScript consumer fixtures cover binary uploads, nullability, metadata, enums, optional defaults, and invalid-input preservation.
• Built a fresh wheel and verified both bundles, the webv2 worker, and shared documentation assets. Fresh extraction serves the default UI, alias, legacy fallback, deep routes, JavaScript assets, and docs favicon. Both bundles are present at webv1 and webv2; the old web package path is absent.
• Started the real backend with an isolated temporary runtime. Chromium default launch and project creation work; switching the same origin to legacy preserves IndexedDB drafts, localStorage, sibling deployment cache entries, and unrelated caches. Default and fallback screenshots were captured and visually inspected locally. After the rename, the real legacy launchpad and docs routes were verified again in Chromium.

CI status: All 12 applicable hosted checks pass on 2a45334b6c, including webv2 release gates, shared OpenAPI/type generation, and Python suites on Linux, macOS, and Windows. The two legacy UI jobs are retired. Documentation build/deploy checks are skipped while draft; the local docs build passes. The PR is mergeable with a clean merge state.

Unavailable checks: Docker execution is unavailable because the current OS user cannot access the daemon socket; container wiring was inspected and both package builds pass. No hardware generation or model downloads were performed.

Manual verification from a checkout with both bundles built:

1. Launch uv run --no-sync invokeai-web and verify webv2 opens. --webv2 should select the same UI.
2. Close other editor tabs, stop the server, then launch with --web-legacy on the same origin. Verify legacy opens after worker cleanup and existing browser data remains.
3. Verify /docs, /static/docs/invoke-favicon-docs.svg, and a deep UI route in each mode. Confirm conflicting frontend flags are rejected.

Review

No material findings remain. Default consumer paths, shared contract ownership, CI installation/filter behavior, packaging, route ordering, and cache cleanup were checked. Stale release-guide descriptions were corrected. Browser timing and Windows CPU fixture failures were addressed without weakening assertions or budgets. The wheel build loop now selects webv2 and webv1 consistently with packaging and cleanup. Docker validation remains unavailable as described above.

Compatibility / Rollout

• Legacy source and Python package paths change from web to webv1; webv2 stays in place. Git history remains traceable with git log --follow. Use a merge commit or rebase merge to retain the dedicated rename commits. API schemas, database names, frontend package identities, localStorage/IndexedDB keys, queue origins, and project/export formats are unchanged. No persisted-data migration is required.
• Shared documentation static assets remain in legacy webv1. Generated contracts and tooling move with exact Git renames to frontend/api; webv1 keeps a type-only services/api/schema re-export for existing callers. Contract CI installs only the shared package. Its pinned TypeScript 5 peer is independent of webv2's TypeScript 7.
• Existing frontendv2-* Make targets remain aliases. frontend-* targets operate on webv2, with explicit frontend-legacy-* build/dev/install targets for fallback.
• Wheels and containers ship both bundles. Deploy matching backend and frontend builds together. Close other editor tabs before switching frontends on one origin; legacy startup unregisters only the matching webv2 worker and removes only this deployment's shell/asset/locale requests from known caches.
• The existing webv2 alpha notice remains visible. The full local release gate is clean; obtain container validation before release.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Meaningful regression coverage added / updated where needed; obsolete tests/code removed
• Persisted-state and API changes include required migrations / compatibility validation
• Relevant performance/efficiency opportunities considered; material claims have evidence
• Material review findings resolved and relevant checks rerun
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)