diff --git a/.github/actions/install-frontend-deps/action.yml b/.github/actions/install-frontend-deps/action.yml
index 1e6d3e6be80..530ab0a722c 100644
--- a/.github/actions/install-frontend-deps/action.yml
+++ b/.github/actions/install-frontend-deps/action.yml
@@ -1,5 +1,10 @@
 name: install frontend dependencies
 description: Installs frontend dependencies with pnpm, with caching
+inputs:
+  working-directory:
+    description: Directory to install dependencies in
+    required: false
+    default: invokeai/frontend/web
 runs:
   using: 'composite'
   steps:
@@ -30,4 +35,4 @@ runs:
     - name: install frontend dependencies
       run: pnpm install --prefer-frozen-lockfile
       shell: bash
-      working-directory: invokeai/frontend/web
+      working-directory: ${{ inputs.working-directory }}
diff --git a/.github/workflows/frontend-checks.yml b/.github/workflows/frontend-checks.yml
index b36fbeb650b..c287d45529d 100644
--- a/.github/workflows/frontend-checks.yml
+++ b/.github/workflows/frontend-checks.yml
@@ -30,14 +30,13 @@ on:
         type: boolean
         default: true
 
-defaults:
-  run:
-    working-directory: invokeai/frontend/web
-
 jobs:
   frontend-checks:
     runs-on: ubuntu-latest
     timeout-minutes: 10 # expected run time: <2 min
+    defaults:
+      run:
+        working-directory: invokeai/frontend/web
     steps:
       - uses: actions/checkout@v6
 
@@ -94,3 +93,37 @@ jobs:
         if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
         run: 'pnpm lint:knip'
         shell: bash
+
+  frontend-webv2-checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10 # expected run time: <2 min
+    defaults:
+      run:
+        working-directory: invokeai/frontend/webv2
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: check for changed webv2 files
+        if: ${{ inputs.always_run != true }}
+        id: changed-files
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96
+        with:
+          files_yaml: |
+            webv2:
+              - 'invokeai/frontend/webv2/**'
+
+      - name: install dependencies
+        if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
+        uses: ./.github/actions/install-frontend-deps
+        with:
+          working-directory: invokeai/frontend/webv2
+
+      - name: lint
+        if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
+        run: 'pnpm run lint'
+        shell: bash
+
+      - name: build
+        if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
+        run: 'pnpm run build'
+        shell: bash
diff --git a/.github/workflows/frontend-tests.yml b/.github/workflows/frontend-tests.yml
index abb1fb8419f..fd7df90a256 100644
--- a/.github/workflows/frontend-tests.yml
+++ b/.github/workflows/frontend-tests.yml
@@ -30,14 +30,13 @@ on:
         type: boolean
         default: true
 
-defaults:
-  run:
-    working-directory: invokeai/frontend/web
-
 jobs:
   frontend-tests:
     runs-on: ubuntu-latest
     timeout-minutes: 10 # expected run time: <2 min
+    defaults:
+      run:
+        working-directory: invokeai/frontend/web
     steps:
       - uses: actions/checkout@v6
 
@@ -63,3 +62,43 @@ jobs:
         if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
         run: 'pnpm test:no-watch'
         shell: bash
+
+  frontend-webv2-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10 # expected run time: <2 min
+    defaults:
+      run:
+        working-directory: invokeai/frontend/webv2
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: check for changed webv2 files
+        if: ${{ inputs.always_run != true }}
+        id: changed-files
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96
+        with:
+          files_yaml: |
+            webv2:
+              - '.github/workflows/frontend-tests.yml'
+              - 'invokeai/frontend/webv2/**'
+
+      - name: install dependencies
+        if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
+        uses: ./.github/actions/install-frontend-deps
+        with:
+          working-directory: invokeai/frontend/webv2
+
+      - name: vitest
+        if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
+        run: 'pnpm test'
+        shell: bash
+
+      - name: install Chromium
+        if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
+        run: 'pnpm exec playwright install chromium'
+        shell: bash
+
+      - name: vitest browser
+        if: ${{ steps.changed-files.outputs.webv2_any_changed == 'true' || inputs.always_run == true }}
+        run: 'pnpm test:browser'
+        shell: bash
diff --git a/.gitignore b/.gitignore
index cc037f09abd..cbb63f66c37 100644
--- a/.gitignore
+++ b/.gitignore
@@ -135,6 +135,16 @@ env/
 venv/
 ENV/
 
+# Generated stuff
+invokeai.yaml
+invokeai.example.yaml
+
+/models/
+/databases/
+/configs/
+/nodes/
+/outputs/
+
 # Spyder project settings
 .spyderproject
 .spyproject
diff --git a/docs/superpowers/specs/2026-07-15-canvas-context-menu-groups-design.md b/docs/superpowers/specs/2026-07-15-canvas-context-menu-groups-design.md
new file mode 100644
index 00000000000..b8485c4e75a
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-15-canvas-context-menu-groups-design.md
@@ -0,0 +1,27 @@
+# Canvas Context Menu Groups Design
+
+## Goal
+
+Restore the legacy canvas context-menu organization with labeled layer and canvas groups while keeping Delete as the final action.
+
+## Design
+
+- Canvas-surface context menus use Chakra `Menu.ItemGroup` and `Menu.ItemGroupLabel` primitives with the established uppercase, subtle label styling.
+- A context menu opened over a layer labels the layer-scoped actions with the singular layer type: Raster Layer, Control Layer, Inpaint Mask, or Regional Guidance.
+- Canvas-wide actions are labeled Canvas. Save to Gallery remains in this canvas group and appears before the terminal Delete action.
+- Delete remains a separated standalone danger action at the bottom so no non-destructive action appears beneath it.
+- A context menu opened over empty canvas space shows only the Canvas group.
+- Layer-panel kebab and row context menus remain unchanged because the legacy panel menus were ungrouped.
+
+## Boundaries
+
+- Reuse existing translations for Canvas and singular layer types.
+- Preserve all existing handlers, disabled states, submenu behavior, and menu positioning.
+- Add no state, effects, dependencies, or action-registry coupling.
+
+## Verification
+
+- Add regression coverage for the surface-menu group model and render order.
+- Verify each layer type resolves to the matching legacy label.
+- Verify the optional Canvas group precedes the terminal danger section and panel menus remain ungrouped when labels are omitted.
+- Run the focused context-menu tests, frontend typecheck, formatting check, and full frontend test suite.
diff --git a/invokeai/app/api/dependencies.py b/invokeai/app/api/dependencies.py
index 3092f5ab71a..67e80ff55e3 100644
--- a/invokeai/app/api/dependencies.py
+++ b/invokeai/app/api/dependencies.py
@@ -42,6 +42,7 @@
 from invokeai.app.services.names.names_default import SimpleNameService
 from invokeai.app.services.object_serializer.object_serializer_disk import ObjectSerializerDisk
 from invokeai.app.services.object_serializer.object_serializer_forward_cache import ObjectSerializerForwardCache
+from invokeai.app.services.project_records.project_records_sqlite import ProjectRecordsSqlite
 from invokeai.app.services.session_processor.session_processor_default import (
     DefaultSessionProcessor,
     DefaultSessionRunner,
@@ -189,6 +190,7 @@ def initialize(
         style_preset_image_files = StylePresetImageFileStorageDisk(style_presets_folder / "images")
         workflow_thumbnails = WorkflowThumbnailFileStorageDisk(workflow_thumbnails_folder)
         client_state_persistence = ClientStatePersistenceSqlite(db=db)
+        project_records = ProjectRecordsSqlite(db=db)
         users = UserService(db=db)
 
         services = InvocationServices(
@@ -223,6 +225,7 @@ def initialize(
             style_preset_image_files=style_preset_image_files,
             workflow_thumbnails=workflow_thumbnails,
             client_state_persistence=client_state_persistence,
+            project_records=project_records,
             users=users,
         )
 
diff --git a/invokeai/app/api/routers/_access.py b/invokeai/app/api/routers/_access.py
index fae3971a144..9e442c6dc29 100644
--- a/invokeai/app/api/routers/_access.py
+++ b/invokeai/app/api/routers/_access.py
@@ -22,6 +22,8 @@ def assert_image_owner(image_name: str, current_user: CurrentUserOrDefault) -> N
     """
     if current_user.is_admin:
         return
+    if not ApiDependencies.invoker.services.image_records.exists(image_name):
+        raise HTTPException(status_code=404, detail="Image not found")
     owner = ApiDependencies.invoker.services.image_records.get_user_id(image_name)
     if owner is not None and owner == current_user.user_id:
         return
@@ -50,6 +52,8 @@ def assert_image_read_access(image_name: str, current_user: CurrentUserOrDefault
     """
     if current_user.is_admin:
         return
+    if not ApiDependencies.invoker.services.image_records.exists(image_name):
+        raise HTTPException(status_code=404, detail="Image not found")
 
     owner = ApiDependencies.invoker.services.image_records.get_user_id(image_name)
     if owner is not None and owner == current_user.user_id:
diff --git a/invokeai/app/api/routers/app_info.py b/invokeai/app/api/routers/app_info.py
index 832e58f5e24..1ea8cbe494b 100644
--- a/invokeai/app/api/routers/app_info.py
+++ b/invokeai/app/api/routers/app_info.py
@@ -23,6 +23,7 @@
     load_external_api_keys,
 )
 from invokeai.app.services.external_generation.external_generation_common import ExternalProviderStatus
+from invokeai.app.services.external_generation.startup import sync_configured_external_starter_models
 from invokeai.app.services.invocation_cache.invocation_cache_common import InvocationCacheStatus
 from invokeai.app.services.model_records.model_records_base import UnknownModelException
 from invokeai.backend.image_util.infill_methods.patchmatch import PatchMatch
@@ -178,7 +179,7 @@ async def update_runtime_config(
     status_code=200,
     response_model=list[ExternalProviderStatusModel],
 )
-async def get_external_provider_statuses() -> list[ExternalProviderStatusModel]:
+async def get_external_provider_statuses(_: AdminUserOrDefault) -> list[ExternalProviderStatusModel]:
     statuses = ApiDependencies.invoker.services.external_generation.get_provider_statuses()
     return [status_to_model(status) for status in statuses.values()]
 
@@ -189,7 +190,7 @@ async def get_external_provider_statuses() -> list[ExternalProviderStatusModel]:
     status_code=200,
     response_model=list[ExternalProviderConfigModel],
 )
-async def get_external_provider_configs() -> list[ExternalProviderConfigModel]:
+async def get_external_provider_configs(_: AdminUserOrDefault) -> list[ExternalProviderConfigModel]:
     config = get_config()
     return [_build_external_provider_config(provider_id, config) for provider_id in EXTERNAL_PROVIDER_FIELDS]
 
@@ -219,9 +220,14 @@ async def set_external_provider_config(
         raise HTTPException(status_code=400, detail="No external provider config fields provided")
 
     api_key_removed = update.api_key is not None and updates.get(api_key_field) is None
+    api_key_set = update.api_key is not None and updates.get(api_key_field) is not None
     _apply_external_provider_update(updates)
     if api_key_removed:
         _remove_external_models_for_provider(provider_id)
+    elif api_key_set:
+        # Configuring a key should make the provider's models usable without a
+        # restart; queue its external starter models the same way startup does.
+        _sync_external_starter_models_for_provider(provider_id)
     return _build_external_provider_config(provider_id, get_config())
 
 
@@ -316,6 +322,19 @@ def _build_external_provider_config(provider_id: str, config: InvokeAIAppConfig)
     )
 
 
+def _sync_external_starter_models_for_provider(provider_id: str) -> None:
+    invoker = ApiDependencies.invoker
+    try:
+        sync_configured_external_starter_models(
+            configured_provider_ids={provider_id},
+            model_manager=invoker.services.model_manager,
+            logger=invoker.services.logger,
+        )
+    except Exception as error:
+        # Queuing installs must never fail the config save; surface and move on.
+        invoker.services.logger.warning(f"Failed queueing external starter models for '{provider_id}': {error}")
+
+
 def _remove_external_models_for_provider(provider_id: str) -> None:
     model_manager = ApiDependencies.invoker.services.model_manager
     external_models = model_manager.store.search_by_attr(
diff --git a/invokeai/app/api/routers/custom_nodes.py b/invokeai/app/api/routers/custom_nodes.py
index 3ee8c0ec99c..473d4c55f3b 100644
--- a/invokeai/app/api/routers/custom_nodes.py
+++ b/invokeai/app/api/routers/custom_nodes.py
@@ -1,8 +1,8 @@
 """FastAPI routes for custom node management."""
 
+import asyncio
 import json
 import shutil
-import subprocess
 import sys
 import traceback
 from importlib.util import module_from_spec, spec_from_file_location
@@ -28,6 +28,7 @@
 # were imported by that pack. Used on uninstall to delete only pack-imported workflows
 # — deleting by tag alone is unsafe because users can edit tags on their own workflows.
 PACK_MANIFEST_FILENAME = ".invokeai_pack_manifest.json"
+GIT_CLONE_TIMEOUT_SECONDS = 120
 
 
 class NodePackInfo(BaseModel):
@@ -126,6 +127,26 @@ def _get_installed_packs() -> list[NodePackInfo]:
     return packs
 
 
+async def _clone_node_pack(source: str, target_dir: Path) -> tuple[int, str]:
+    process = await asyncio.create_subprocess_exec(
+        "git",
+        "clone",
+        source,
+        str(target_dir),
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    try:
+        _stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=GIT_CLONE_TIMEOUT_SECONDS)
+    except asyncio.TimeoutError:
+        process.kill()
+        await process.communicate()
+        raise
+
+    return process.returncode or 0, stderr.decode(errors="replace").strip()
+
+
 @custom_nodes_router.get(
     "/",
     operation_id="list_custom_node_packs",
@@ -172,21 +193,16 @@ async def install_custom_node_pack(
 
     try:
         # Clone the repository
-        result = subprocess.run(
-            ["git", "clone", source, str(target_dir)],
-            capture_output=True,
-            text=True,
-            timeout=120,
-        )
+        returncode, stderr = await _clone_node_pack(source, target_dir)
 
-        if result.returncode != 0:
+        if returncode != 0:
             # Clean up on failure
             if target_dir.exists():
                 shutil.rmtree(target_dir)
             return InstallNodePackResponse(
                 name=pack_name,
                 success=False,
-                message=f"Git clone failed: {result.stderr.strip()}",
+                message=f"Git clone failed: {stderr}",
             )
 
         # Detect dependency manifests but do NOT install them automatically.
@@ -232,7 +248,7 @@ async def install_custom_node_pack(
             dependency_file=dependency_file,
         )
 
-    except subprocess.TimeoutExpired:
+    except asyncio.TimeoutError:
         if target_dir.exists():
             shutil.rmtree(target_dir)
         return InstallNodePackResponse(
diff --git a/invokeai/app/api/routers/model_manager.py b/invokeai/app/api/routers/model_manager.py
index bdd2e406444..a1c47b4e722 100644
--- a/invokeai/app/api/routers/model_manager.py
+++ b/invokeai/app/api/routers/model_manager.py
@@ -11,7 +11,7 @@
 from typing import List, Optional, Type
 
 import huggingface_hub
-from fastapi import Body, Path, Query, Response, UploadFile
+from fastapi import Body, Header, Path, Query, Response, UploadFile
 from fastapi.responses import FileResponse, HTMLResponse
 from fastapi.routing import APIRouter
 from PIL import Image
@@ -68,6 +68,11 @@ class ModelsList(BaseModel):
     model_config = ConfigDict(use_enum_values=True)
 
 
+class EmptyModelCacheResponse(BaseModel):
+    models_cleared: int
+    bytes_freed: int
+
+
 class CacheType(str, Enum):
     """Cache type - one of vram or ram."""
 
@@ -218,6 +223,20 @@ async def list_missing_models() -> ModelsList:
     return ModelsList(models=missing_models)
 
 
+@model_manager_router.get(
+    "/models_dir",
+    operation_id="get_models_dir",
+    responses={200: {"description": "The absolute path of the models directory"}},
+)
+async def get_models_dir() -> str:
+    """Get the absolute path of the directory managed models are stored in.
+
+    Model config `path` values are relative to this directory unless they are
+    absolute (in-place installs from outside it).
+    """
+    return ApiDependencies.invoker.services.configuration.models_path.resolve().as_posix()
+
+
 @model_manager_router.get(
     "/get_by_attrs",
     operation_id="get_model_records_by_attrs",
@@ -747,6 +766,11 @@ async def install_model(
     source: str = Query(description="Model source to install, can be a local path, repo_id, or remote URL"),
     inplace: Optional[bool] = Query(description="Whether or not to install a local model in place", default=False),
     access_token: Optional[str] = Query(description="access token for the remote resource", default=None),
+    source_access_token: Optional[str] = Header(
+        alias="X-Model-Source-Access-Token",
+        description="access token for the remote resource",
+        default=None,
+    ),
     config: ModelRecordChanges = Body(
         description="Object containing fields that override auto-probed values in the model config record, such as name, description and prediction_type ",
         examples=[{"name": "string", "description": "string"}],
@@ -786,7 +810,7 @@ async def install_model(
         result: ModelInstallJob = installer.heuristic_import(
             source=source,
             config=config,
-            access_token=access_token,
+            access_token=source_access_token or access_token,
             inplace=bool(inplace),
         )
         logger.info(f"Started installation of {source}")
@@ -1301,12 +1325,14 @@ async def get_stats() -> Optional[CacheStats]:
     "/empty_model_cache",
     operation_id="empty_model_cache",
     status_code=200,
+    response_model=EmptyModelCacheResponse,
 )
-async def empty_model_cache(current_admin: AdminUserOrDefault) -> None:
+async def empty_model_cache(current_admin: AdminUserOrDefault) -> EmptyModelCacheResponse:
     """Drop all models from the model cache to free RAM/VRAM. 'Locked' models that are in active use will not be dropped."""
     # Request 1000GB of room in order to force the cache to drop all models.
     ApiDependencies.invoker.services.logger.info("Emptying model cache.")
-    ApiDependencies.invoker.services.model_manager.load.ram_cache.make_room(1000 * 2**30)
+    result = ApiDependencies.invoker.services.model_manager.load.ram_cache.make_room(1000 * 2**30)
+    return EmptyModelCacheResponse(models_cleared=result.models_cleared, bytes_freed=result.bytes_freed)
 
 
 class HFTokenStatus(str, Enum):
@@ -1341,7 +1367,7 @@ def reset_token(cls) -> HFTokenStatus:
 
 
 @model_manager_router.get("/hf_login", operation_id="get_hf_login_status", response_model=HFTokenStatus)
-async def get_hf_login_status() -> HFTokenStatus:
+async def get_hf_login_status(_: AdminUserOrDefault) -> HFTokenStatus:
     token_status = HFTokenHelper.get_status()
 
     if token_status is HFTokenStatus.UNKNOWN:
diff --git a/invokeai/app/api/routers/projects.py b/invokeai/app/api/routers/projects.py
new file mode 100644
index 00000000000..6609c091235
--- /dev/null
+++ b/invokeai/app/api/routers/projects.py
@@ -0,0 +1,105 @@
+from typing import Any
+
+from fastapi import Body, HTTPException, Path, status
+from fastapi.routing import APIRouter
+from pydantic import BaseModel, Field
+
+from invokeai.app.api.auth_dependencies import CurrentUserOrDefault
+from invokeai.app.api.dependencies import ApiDependencies
+from invokeai.app.services.project_records.project_records_common import (
+    ProjectRecordConflictError,
+    ProjectRecordDTO,
+    ProjectRecordExistsError,
+    ProjectRecordNotFoundError,
+    ProjectSummaryDTO,
+)
+
+projects_router = APIRouter(prefix="/v1/projects", tags=["projects"])
+
+
+class ProjectCreateRequest(BaseModel):
+    """Request body for creating a project."""
+
+    project_id: str | None = Field(
+        default=None, description="Client-generated project id (e.g. for imports); generated when omitted"
+    )
+    name: str = Field(description="The project's display name")
+    data: dict[str, Any] = Field(description="The opaque client-owned project document")
+
+
+class ProjectUpdateRequest(BaseModel):
+    """Request body for saving a project with optimistic concurrency."""
+
+    name: str = Field(description="The project's display name")
+    data: dict[str, Any] = Field(description="The opaque client-owned project document")
+    expected_revision: int = Field(description="The revision this save is based on; mismatch returns 409")
+
+
+@projects_router.get("/", operation_id="list_projects", response_model=list[ProjectSummaryDTO])
+async def list_projects(current_user: CurrentUserOrDefault) -> list[ProjectSummaryDTO]:
+    """Lists the current user's projects as lightweight summaries (no documents)."""
+    return ApiDependencies.invoker.services.project_records.list(current_user.user_id)
+
+
+@projects_router.post(
+    "/", operation_id="create_project", response_model=ProjectRecordDTO, status_code=status.HTTP_201_CREATED
+)
+async def create_project(
+    current_user: CurrentUserOrDefault,
+    request: ProjectCreateRequest = Body(description="The project to create"),
+) -> ProjectRecordDTO:
+    """Creates a project for the current user."""
+    try:
+        return ApiDependencies.invoker.services.project_records.create(
+            user_id=current_user.user_id,
+            name=request.name,
+            data=request.data,
+            project_id=request.project_id,
+        )
+    except ProjectRecordExistsError as e:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e))
+
+
+@projects_router.get("/{project_id}", operation_id="get_project", response_model=ProjectRecordDTO)
+async def get_project(
+    current_user: CurrentUserOrDefault,
+    project_id: str = Path(description="The id of the project to get"),
+) -> ProjectRecordDTO:
+    """Gets one of the current user's projects, including its document."""
+    try:
+        return ApiDependencies.invoker.services.project_records.get(current_user.user_id, project_id)
+    except ProjectRecordNotFoundError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+
+
+@projects_router.put("/{project_id}", operation_id="update_project", response_model=ProjectRecordDTO)
+async def update_project(
+    current_user: CurrentUserOrDefault,
+    project_id: str = Path(description="The id of the project to save"),
+    request: ProjectUpdateRequest = Body(description="The project document and the revision it is based on"),
+) -> ProjectRecordDTO:
+    """Saves a project. Returns 409 with the current revision when the save is based on a stale revision."""
+    try:
+        return ApiDependencies.invoker.services.project_records.update(
+            user_id=current_user.user_id,
+            project_id=project_id,
+            expected_revision=request.expected_revision,
+            name=request.name,
+            data=request.data,
+        )
+    except ProjectRecordNotFoundError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+    except ProjectRecordConflictError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={"message": str(e), "current_revision": e.current_revision},
+        )
+
+
+@projects_router.delete("/{project_id}", operation_id="delete_project", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_project(
+    current_user: CurrentUserOrDefault,
+    project_id: str = Path(description="The id of the project to delete"),
+) -> None:
+    """Deletes one of the current user's projects. Idempotent."""
+    ApiDependencies.invoker.services.project_records.delete(current_user.user_id, project_id)
diff --git a/invokeai/app/api/routers/session_queue.py b/invokeai/app/api/routers/session_queue.py
index 89d2f9a7395..5e6dffce337 100644
--- a/invokeai/app/api/routers/session_queue.py
+++ b/invokeai/app/api/routers/session_queue.py
@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Callable, Optional
 
 from fastapi import Body, HTTPException, Path, Query
 from fastapi.routing import APIRouter
@@ -7,6 +7,7 @@
 from invokeai.app.api.auth_dependencies import AdminUserOrDefault, CurrentUserOrDefault
 from invokeai.app.api.dependencies import ApiDependencies
 from invokeai.app.api.routers.image_move_maintenance import assert_image_move_maintenance_inactive
+from invokeai.app.invocations.fields import ImageField
 from invokeai.app.services.session_processor.session_processor_common import SessionProcessorStatus
 from invokeai.app.services.session_queue.session_queue_common import (
     Batch,
@@ -39,6 +40,59 @@ class SessionQueueAndProcessorStatus(BaseModel):
     processor: SessionProcessorStatus
 
 
+def _image_record_exists(image_name: str) -> bool:
+    return ApiDependencies.invoker.services.image_records.exists(image_name)
+
+
+def strip_missing_image_results(
+    queue_item: SessionQueueItem, image_exists: Callable[[str], bool] | None = None
+) -> SessionQueueItem:
+    """Remove result outputs whose image records have been deleted.
+
+    Completed queue history can outlive its output images. API clients hydrate
+    images listed in `session.results`; returning stale names makes them loop on
+    404s. Keep the queue item/history, but do not advertise impossible outputs.
+    """
+    if not queue_item.session.results:
+        return queue_item
+
+    image_exists = image_exists or _image_record_exists
+    filtered_results = {}
+    did_filter = False
+    exists_cache: dict[str, bool] = {}
+
+    def cached_exists(image_name: str) -> bool:
+        if image_name not in exists_cache:
+            exists_cache[image_name] = image_exists(image_name)
+        return exists_cache[image_name]
+
+    for node_id, output in queue_item.session.results.items():
+        image = getattr(output, "image", None)
+        if isinstance(image, ImageField) and not cached_exists(image.image_name):
+            did_filter = True
+            continue
+
+        collection = getattr(output, "collection", None)
+        if isinstance(collection, list) and any(isinstance(item, ImageField) for item in collection):
+            filtered_collection = [
+                item for item in collection if not isinstance(item, ImageField) or cached_exists(item.image_name)
+            ]
+            if len(filtered_collection) != len(collection):
+                did_filter = True
+                if len(filtered_collection) == 0:
+                    continue
+                output = output.model_copy(update={"collection": filtered_collection})
+
+        filtered_results[node_id] = output
+
+    if not did_filter:
+        return queue_item
+
+    sanitized_item = queue_item.model_copy(deep=True)
+    sanitized_item.session.results = filtered_results
+    return sanitized_item
+
+
 def _get_workflow_call_root_queue_item(queue_item: SessionQueueItem) -> SessionQueueItem:
     if queue_item.root_item_id is None:
         return queue_item
@@ -64,7 +118,7 @@ def sanitize_queue_item_for_user(
     """
     # Admins and item owners can see everything
     if is_admin or queue_item.user_id == current_user_id:
-        return queue_item
+        return strip_missing_image_results(queue_item)
 
     # For non-admins viewing other users' items, strip everything except
     # item_id, queue_id, status, and timestamps
@@ -95,6 +149,18 @@ def sanitize_queue_item_for_user(
     return sanitized_item
 
 
+def get_queue_item_for_mutation(queue_id: str, item_id: int, current_user: CurrentUserOrDefault) -> SessionQueueItem:
+    queue_item = ApiDependencies.invoker.services.session_queue.get_queue_item(item_id)
+
+    if queue_item.queue_id != queue_id:
+        raise HTTPException(status_code=404, detail=f"Queue item with id {item_id} not found in queue {queue_id}")
+
+    if queue_item.user_id != current_user.user_id and not current_user.is_admin:
+        raise HTTPException(status_code=403, detail=f"You do not have permission to mutate queue item {item_id}")
+
+    return queue_item
+
+
 @session_queue_router.post(
     "/{queue_id}/enqueue_batch",
     operation_id="enqueue_batch",
@@ -154,6 +220,9 @@ async def get_queue_item_ids(
     current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     order_dir: SQLiteDirection = Query(default=SQLiteDirection.Descending, description="The order of sort"),
+    origin_prefix: Optional[str] = Query(
+        default=None, description="Only include queue items whose origin starts with this prefix"
+    ),
 ) -> ItemIdsResult:
     """Gets all queue item ids that match the given parameters.
 
@@ -166,7 +235,9 @@ async def get_queue_item_ids(
     current_user is required so the endpoint stays behind authentication in multiuser mode.
     """
     try:
-        return ApiDependencies.invoker.services.session_queue.get_queue_item_ids(queue_id=queue_id, order_dir=order_dir)
+        return ApiDependencies.invoker.services.session_queue.get_queue_item_ids(
+            queue_id=queue_id, order_dir=order_dir, origin_prefix=origin_prefix
+        )
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while listing all queue item ids: {e}")
 
@@ -425,10 +496,13 @@ async def prune(
 async def get_current_queue_item(
     current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
+    origin_prefix: Optional[str] = Query(
+        default=None, description="Only include queue items whose origin starts with this prefix"
+    ),
 ) -> Optional[SessionQueueItem]:
     """Gets the currently execution queue item"""
     try:
-        item = ApiDependencies.invoker.services.session_queue.get_current(queue_id)
+        item = ApiDependencies.invoker.services.session_queue.get_current(queue_id, origin_prefix=origin_prefix)
         if item is not None:
             item = sanitize_queue_item_for_user(item, current_user.user_id, current_user.is_admin)
         return item
@@ -446,10 +520,13 @@ async def get_current_queue_item(
 async def get_next_queue_item(
     current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
+    origin_prefix: Optional[str] = Query(
+        default=None, description="Only include queue items whose origin starts with this prefix"
+    ),
 ) -> Optional[SessionQueueItem]:
     """Gets the next queue item, without executing it"""
     try:
-        item = ApiDependencies.invoker.services.session_queue.get_next(queue_id)
+        item = ApiDependencies.invoker.services.session_queue.get_next(queue_id, origin_prefix=origin_prefix)
         if item is not None:
             item = sanitize_queue_item_for_user(item, current_user.user_id, current_user.is_admin)
         return item
@@ -467,13 +544,18 @@ async def get_next_queue_item(
 async def get_queue_status(
     current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
+    origin_prefix: Optional[str] = Query(
+        default=None, description="Only include queue items whose origin starts with this prefix"
+    ),
 ) -> SessionQueueAndProcessorStatus:
     """Gets the status of the session queue. Returns global counts; non-admin users additionally
     get their own pending/in_progress counts (so the UI can show an X/Y badge) and cannot see the
     current item's identifiers unless they own it."""
     try:
         user_id = None if current_user.is_admin else current_user.user_id
-        queue = ApiDependencies.invoker.services.session_queue.get_queue_status(queue_id, user_id=user_id)
+        queue = ApiDependencies.invoker.services.session_queue.get_queue_status(
+            queue_id, user_id=user_id, origin_prefix=origin_prefix
+        )
         processor = ApiDependencies.invoker.services.session_processor.get_status()
         return SessionQueueAndProcessorStatus(queue=queue, processor=processor)
     except Exception as e:
@@ -575,14 +657,7 @@ async def cancel_queue_item(
 ) -> SessionQueueItem:
     """Cancels a queue item. Users can only cancel their own items unless they are an admin."""
     try:
-        # Get the queue item to check ownership
-        queue_item = ApiDependencies.invoker.services.session_queue.get_queue_item(item_id)
-        if queue_item.queue_id != queue_id:
-            raise HTTPException(status_code=404, detail=f"Queue item with id {item_id} not found in queue {queue_id}")
-
-        # Check authorization: user must own the item or be an admin
-        if queue_item.user_id != current_user.user_id and not current_user.is_admin:
-            raise HTTPException(status_code=403, detail="You do not have permission to cancel this queue item")
+        get_queue_item_for_mutation(queue_id, item_id, current_user)
 
         return ApiDependencies.invoker.services.session_queue.cancel_queue_item(item_id)
     except SessionQueueItemNotFoundError:
diff --git a/invokeai/app/api/sockets.py b/invokeai/app/api/sockets.py
index bdaf641c1c1..19392a107bd 100644
--- a/invokeai/app/api/sockets.py
+++ b/invokeai/app/api/sockets.py
@@ -29,6 +29,7 @@
     ModelInstallCompleteEvent,
     ModelInstallDownloadProgressEvent,
     ModelInstallDownloadsCompleteEvent,
+    ModelInstallDownloadStartedEvent,
     ModelInstallErrorEvent,
     ModelInstallStartedEvent,
     ModelLoadCompleteEvent,
@@ -84,6 +85,7 @@ class BulkDownloadSubscriptionEvent(BaseModel):
     DownloadStartedEvent,
     ModelLoadStartedEvent,
     ModelLoadCompleteEvent,
+    ModelInstallDownloadStartedEvent,
     ModelInstallDownloadProgressEvent,
     ModelInstallDownloadsCompleteEvent,
     ModelInstallStartedEvent,
@@ -95,6 +97,16 @@ class BulkDownloadSubscriptionEvent(BaseModel):
 BULK_DOWNLOAD_EVENTS = {BulkDownloadStartedEvent, BulkDownloadCompleteEvent, BulkDownloadErrorEvent}
 WORKFLOW_EVENTS = {WorkflowCreatedEvent, WorkflowUpdatedEvent, WorkflowDeletedEvent}
 
+MODEL_INSTALL_EVENTS = (
+    ModelInstallDownloadStartedEvent,
+    ModelInstallDownloadProgressEvent,
+    ModelInstallDownloadsCompleteEvent,
+    ModelInstallStartedEvent,
+    ModelInstallCompleteEvent,
+    ModelInstallCancelledEvent,
+    ModelInstallErrorEvent,
+)
+
 
 class SocketIO:
     _sub_queue = "subscribe_queue"
@@ -490,7 +502,12 @@ async def _handle_queue_event(self, event: FastAPIEvent[QueueEventBase]):
             logger.error(f"Error handling queue event {event[0]}: {e}", exc_info=True)
 
     async def _handle_model_event(self, event: FastAPIEvent[ModelEventBase | DownloadEventBase]) -> None:
-        await self._sio.emit(event=event[0], data=event[1].model_dump(mode="json"))
+        event_name, event_data = event
+        if isinstance(event_data, MODEL_INSTALL_EVENTS):
+            await self._sio.emit(event=event_name, data=event_data.model_dump(mode="json"), room="admin")
+            return
+
+        await self._sio.emit(event=event_name, data=event_data.model_dump(mode="json"))
 
     async def _handle_bulk_image_download_event(self, event: FastAPIEvent[BulkDownloadEventBase]) -> None:
         event_name, event_data = event
diff --git a/invokeai/app/api_app.py b/invokeai/app/api_app.py
index ed02d75eae3..e56f2bdb91b 100644
--- a/invokeai/app/api_app.py
+++ b/invokeai/app/api_app.py
@@ -27,6 +27,7 @@
     images,
     model_manager,
     model_relationships,
+    projects,
     recall_parameters,
     session_queue,
     style_presets,
@@ -188,6 +189,7 @@ async def dispatch(self, request: Request, call_next: RequestResponseEndpoint):
 app.include_router(workflows.workflows_router, prefix="/api")
 app.include_router(style_presets.style_presets_router, prefix="/api")
 app.include_router(client_state.client_state_router, prefix="/api")
+app.include_router(projects.projects_router, prefix="/api")
 app.include_router(recall_parameters.recall_parameters_router, prefix="/api")
 app.include_router(custom_nodes.custom_nodes_router, prefix="/api")
 
diff --git a/invokeai/app/services/image_records/image_records_base.py b/invokeai/app/services/image_records/image_records_base.py
index 8c71dfba9e7..9e263522cd9 100644
--- a/invokeai/app/services/image_records/image_records_base.py
+++ b/invokeai/app/services/image_records/image_records_base.py
@@ -30,6 +30,11 @@ def get_metadata(self, image_name: str) -> Optional[MetadataField]:
         """Gets an image's metadata'."""
         pass
 
+    @abstractmethod
+    def exists(self, image_name: str) -> bool:
+        """Returns whether an image record exists."""
+        pass
+
     @abstractmethod
     def update(
         self,
diff --git a/invokeai/app/services/image_records/image_records_sqlite.py b/invokeai/app/services/image_records/image_records_sqlite.py
index 1eb3857dba6..8a6a7f47c68 100644
--- a/invokeai/app/services/image_records/image_records_sqlite.py
+++ b/invokeai/app/services/image_records/image_records_sqlite.py
@@ -84,6 +84,18 @@ def get_metadata(self, image_name: str) -> Optional[MetadataField]:
             metadata_raw = cast(Optional[str], as_dict.get("metadata", None))
             return MetadataFieldValidator.validate_json(metadata_raw) if metadata_raw is not None else None
 
+    def exists(self, image_name: str) -> bool:
+        with self._db.transaction() as cursor:
+            cursor.execute(
+                """--sql
+                SELECT 1 FROM images
+                WHERE image_name = ?
+                LIMIT 1;
+                """,
+                (image_name,),
+            )
+            return cursor.fetchone() is not None
+
     def update(
         self,
         image_name: str,
diff --git a/invokeai/app/services/images/images_default.py b/invokeai/app/services/images/images_default.py
index 4a190f37edc..dabc65fb9f6 100644
--- a/invokeai/app/services/images/images_default.py
+++ b/invokeai/app/services/images/images_default.py
@@ -132,6 +132,9 @@ def get_pil_image(self, image_name: str) -> PILImageType:
         try:
             record = self.__invoker.services.image_records.get(image_name)
             return self.__invoker.services.image_files.get(image_name, image_subfolder=record.image_subfolder)
+        except ImageRecordNotFoundException:
+            self.__invoker.services.logger.debug(f"Image record not found: {image_name}")
+            raise
         except ImageFileNotFoundException:
             self.__invoker.services.logger.error("Failed to get image file")
             raise
@@ -143,7 +146,7 @@ def get_record(self, image_name: str) -> ImageRecord:
         try:
             return self.__invoker.services.image_records.get(image_name)
         except ImageRecordNotFoundException:
-            self.__invoker.services.logger.error("Image record not found")
+            self.__invoker.services.logger.debug(f"Image record not found: {image_name}")
             raise
         except Exception as e:
             self.__invoker.services.logger.error("Problem getting image record")
@@ -162,7 +165,7 @@ def get_dto(self, image_name: str) -> ImageDTO:
 
             return image_dto
         except ImageRecordNotFoundException:
-            self.__invoker.services.logger.error("Image record not found")
+            self.__invoker.services.logger.debug(f"Image record not found: {image_name}")
             raise
         except Exception as e:
             self.__invoker.services.logger.error("Problem getting image DTO")
@@ -172,7 +175,7 @@ def get_metadata(self, image_name: str) -> Optional[MetadataField]:
         try:
             return self.__invoker.services.image_records.get_metadata(image_name)
         except ImageRecordNotFoundException:
-            self.__invoker.services.logger.error("Image record not found")
+            self.__invoker.services.logger.debug(f"Image record not found: {image_name}")
             raise
         except Exception as e:
             self.__invoker.services.logger.error("Problem getting image metadata")
@@ -182,6 +185,9 @@ def get_workflow(self, image_name: str) -> Optional[str]:
         try:
             record = self.__invoker.services.image_records.get(image_name)
             return self.__invoker.services.image_files.get_workflow(image_name, image_subfolder=record.image_subfolder)
+        except ImageRecordNotFoundException:
+            self.__invoker.services.logger.debug(f"Image record not found: {image_name}")
+            raise
         except ImageFileNotFoundException:
             self.__invoker.services.logger.error("Image file not found")
             raise
@@ -193,6 +199,9 @@ def get_graph(self, image_name: str) -> Optional[str]:
         try:
             record = self.__invoker.services.image_records.get(image_name)
             return self.__invoker.services.image_files.get_graph(image_name, image_subfolder=record.image_subfolder)
+        except ImageRecordNotFoundException:
+            self.__invoker.services.logger.debug(f"Image record not found: {image_name}")
+            raise
         except ImageFileNotFoundException:
             self.__invoker.services.logger.error("Image file not found")
             raise
@@ -208,6 +217,9 @@ def get_path(self, image_name: str, thumbnail: bool = False) -> str:
                     image_name, thumbnail, image_subfolder=record.image_subfolder
                 )
             )
+        except ImageRecordNotFoundException:
+            self.__invoker.services.logger.debug(f"Image record not found: {image_name}")
+            raise
         except Exception as e:
             self.__invoker.services.logger.error("Problem getting image path")
             raise e
diff --git a/invokeai/app/services/invocation_services.py b/invokeai/app/services/invocation_services.py
index 54f9d82b786..d46289a65e5 100644
--- a/invokeai/app/services/invocation_services.py
+++ b/invokeai/app/services/invocation_services.py
@@ -35,6 +35,7 @@
     )
     from invokeai.app.services.model_relationships.model_relationships_base import ModelRelationshipsServiceABC
     from invokeai.app.services.names.names_base import NameServiceBase
+    from invokeai.app.services.project_records.project_records_base import ProjectRecordsStorageBase
     from invokeai.app.services.session_processor.session_processor_base import SessionProcessorBase
     from invokeai.app.services.session_queue.session_queue_base import SessionQueueBase
     from invokeai.app.services.urls.urls_base import UrlServiceBase
@@ -79,6 +80,7 @@ def __init__(
         style_preset_image_files: "StylePresetImageFileStorageBase",
         workflow_thumbnails: "WorkflowThumbnailServiceBase",
         client_state_persistence: "ClientStatePersistenceABC",
+        project_records: "ProjectRecordsStorageBase",
         users: "UserServiceBase",
         image_moves: "ImageMoveService | None" = None,
     ):
@@ -113,4 +115,5 @@ def __init__(
         self.style_preset_image_files = style_preset_image_files
         self.workflow_thumbnails = workflow_thumbnails
         self.client_state_persistence = client_state_persistence
+        self.project_records = project_records
         self.users = users
diff --git a/invokeai/app/services/project_records/project_records_base.py b/invokeai/app/services/project_records/project_records_base.py
new file mode 100644
index 00000000000..0bc02b74d70
--- /dev/null
+++ b/invokeai/app/services/project_records/project_records_base.py
@@ -0,0 +1,62 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from invokeai.app.services.project_records.project_records_common import ProjectRecordDTO, ProjectSummaryDTO
+
+
+class ProjectRecordsStorageBase(ABC):
+    """Storage for per-user workbench project documents.
+
+    All operations are scoped by user_id; a user can never read or write
+    another user's projects. Saves use optimistic concurrency via the
+    project's monotonic revision.
+    """
+
+    @abstractmethod
+    def create(self, user_id: str, name: str, data: dict[str, Any], project_id: str | None = None) -> ProjectRecordDTO:
+        """Create a project for the user.
+
+        Args:
+            user_id: The owning user.
+            name: The project's display name.
+            data: The opaque client-owned project document.
+            project_id: Client-generated id (e.g. for imports); generated when omitted.
+
+        Returns:
+            The created project record.
+
+        Raises:
+            ProjectRecordExistsError: The user already has a project with this id.
+        """
+        pass
+
+    @abstractmethod
+    def get(self, user_id: str, project_id: str) -> ProjectRecordDTO:
+        """Get one of the user's projects, including its document.
+
+        Raises:
+            ProjectRecordNotFoundError: No such project for this user.
+        """
+        pass
+
+    @abstractmethod
+    def list(self, user_id: str) -> list[ProjectSummaryDTO]:
+        """List the user's projects as lightweight summaries, oldest first."""
+        pass
+
+    @abstractmethod
+    def update(
+        self, user_id: str, project_id: str, expected_revision: int, name: str, data: dict[str, Any]
+    ) -> ProjectRecordDTO:
+        """Save a project if the caller's revision is current.
+
+        Raises:
+            ProjectRecordNotFoundError: No such project for this user.
+            ProjectRecordConflictError: The stored revision differs from expected_revision.
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, user_id: str, project_id: str) -> None:
+        """Delete one of the user's projects. Idempotent: deleting a missing project is a no-op."""
+        pass
diff --git a/invokeai/app/services/project_records/project_records_common.py b/invokeai/app/services/project_records/project_records_common.py
new file mode 100644
index 00000000000..dc25b170174
--- /dev/null
+++ b/invokeai/app/services/project_records/project_records_common.py
@@ -0,0 +1,45 @@
+"""Common types and errors for the project records service."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ProjectRecordNotFoundError(Exception):
+    """Raised when a project record is not found for the requesting user."""
+
+    def __init__(self, project_id: str) -> None:
+        super().__init__(f"Project {project_id} not found")
+
+
+class ProjectRecordExistsError(Exception):
+    """Raised when creating a project with an id the user already has."""
+
+    def __init__(self, project_id: str) -> None:
+        super().__init__(f"Project {project_id} already exists")
+
+
+class ProjectRecordConflictError(Exception):
+    """Raised when a save carries a stale revision (another client saved first)."""
+
+    def __init__(self, project_id: str, expected_revision: int, current_revision: int) -> None:
+        self.current_revision = current_revision
+        super().__init__(
+            f"Project {project_id} is at revision {current_revision}; the save expected revision {expected_revision}"
+        )
+
+
+class ProjectSummaryDTO(BaseModel):
+    """Lightweight project listing entry; the document payload is omitted."""
+
+    project_id: str = Field(description="The project's client-generated identifier")
+    name: str = Field(description="The project's display name")
+    revision: int = Field(description="Monotonic revision, incremented on every save")
+    created_at: str = Field(description="When the project was created")
+    updated_at: str = Field(description="When the project was last saved")
+
+
+class ProjectRecordDTO(ProjectSummaryDTO):
+    """Full project record including the client-owned document."""
+
+    data: dict[str, Any] = Field(description="The opaque client-owned project document")
diff --git a/invokeai/app/services/project_records/project_records_sqlite.py b/invokeai/app/services/project_records/project_records_sqlite.py
new file mode 100644
index 00000000000..0369a626f45
--- /dev/null
+++ b/invokeai/app/services/project_records/project_records_sqlite.py
@@ -0,0 +1,134 @@
+import json
+import sqlite3
+import uuid
+from typing import Any
+
+from invokeai.app.services.invoker import Invoker
+from invokeai.app.services.project_records.project_records_base import ProjectRecordsStorageBase
+from invokeai.app.services.project_records.project_records_common import (
+    ProjectRecordConflictError,
+    ProjectRecordDTO,
+    ProjectRecordExistsError,
+    ProjectRecordNotFoundError,
+    ProjectSummaryDTO,
+)
+from invokeai.app.services.shared.sqlite.sqlite_database import SqliteDatabase
+
+
+class ProjectRecordsSqlite(ProjectRecordsStorageBase):
+    """SQLite implementation of per-user project document storage."""
+
+    def __init__(self, db: SqliteDatabase) -> None:
+        super().__init__()
+        self._db = db
+
+    def start(self, invoker: Invoker) -> None:
+        self._invoker = invoker
+
+    def create(self, user_id: str, name: str, data: dict[str, Any], project_id: str | None = None) -> ProjectRecordDTO:
+        project_id = project_id or uuid.uuid4().hex
+
+        try:
+            with self._db.transaction() as cursor:
+                cursor.execute(
+                    """--sql
+                    INSERT INTO projects (project_id, user_id, name, data)
+                    VALUES (?, ?, ?, ?);
+                    """,
+                    (project_id, user_id, name, json.dumps(data)),
+                )
+        except sqlite3.IntegrityError as e:
+            raise ProjectRecordExistsError(project_id) from e
+
+        return self.get(user_id, project_id)
+
+    def get(self, user_id: str, project_id: str) -> ProjectRecordDTO:
+        with self._db.transaction() as cursor:
+            cursor.execute(
+                """--sql
+                SELECT project_id, name, data, revision, created_at, updated_at
+                FROM projects
+                WHERE user_id = ? AND project_id = ?;
+                """,
+                (user_id, project_id),
+            )
+            row = cursor.fetchone()
+
+        if row is None:
+            raise ProjectRecordNotFoundError(project_id)
+
+        return ProjectRecordDTO(
+            project_id=row[0],
+            name=row[1],
+            data=json.loads(row[2]),
+            revision=row[3],
+            created_at=row[4],
+            updated_at=row[5],
+        )
+
+    def list(self, user_id: str) -> list[ProjectSummaryDTO]:
+        with self._db.transaction() as cursor:
+            cursor.execute(
+                """--sql
+                SELECT project_id, name, revision, created_at, updated_at
+                FROM projects
+                WHERE user_id = ?
+                -- rowid breaks ties between rows created in the same millisecond,
+                -- keeping the listing in true insertion order.
+                ORDER BY created_at ASC, rowid ASC;
+                """,
+                (user_id,),
+            )
+            rows = cursor.fetchall()
+
+        return [
+            ProjectSummaryDTO(
+                project_id=row[0],
+                name=row[1],
+                revision=row[2],
+                created_at=row[3],
+                updated_at=row[4],
+            )
+            for row in rows
+        ]
+
+    def update(
+        self, user_id: str, project_id: str, expected_revision: int, name: str, data: dict[str, Any]
+    ) -> ProjectRecordDTO:
+        with self._db.transaction() as cursor:
+            cursor.execute(
+                """--sql
+                UPDATE projects
+                SET name = ?, data = ?, revision = revision + 1
+                WHERE user_id = ? AND project_id = ? AND revision = ?;
+                """,
+                (name, json.dumps(data), user_id, project_id, expected_revision),
+            )
+
+            if cursor.rowcount == 0:
+                # Distinguish "gone" from "someone else saved first".
+                cursor.execute(
+                    """--sql
+                    SELECT revision FROM projects
+                    WHERE user_id = ? AND project_id = ?;
+                    """,
+                    (user_id, project_id),
+                )
+                row = cursor.fetchone()
+
+                if row is None:
+                    raise ProjectRecordNotFoundError(project_id)
+
+                raise ProjectRecordConflictError(project_id, expected_revision, row[0])
+
+        return self.get(user_id, project_id)
+
+    def delete(self, user_id: str, project_id: str) -> None:
+        with self._db.transaction() as cursor:
+            cursor.execute(
+                """--sql
+                DELETE FROM projects
+                WHERE user_id = ? AND project_id = ?;
+                """,
+                (user_id, project_id),
+            )
diff --git a/invokeai/app/services/session_queue/session_queue_base.py b/invokeai/app/services/session_queue/session_queue_base.py
index a07abf10ee1..a3882524fbb 100644
--- a/invokeai/app/services/session_queue/session_queue_base.py
+++ b/invokeai/app/services/session_queue/session_queue_base.py
@@ -44,12 +44,12 @@ def enqueue_batch(
         pass
 
     @abstractmethod
-    def get_current(self, queue_id: str) -> Optional[SessionQueueItem]:
+    def get_current(self, queue_id: str, origin_prefix: Optional[str] = None) -> Optional[SessionQueueItem]:
         """Gets the currently-executing session queue item"""
         pass
 
     @abstractmethod
-    def get_next(self, queue_id: str) -> Optional[SessionQueueItem]:
+    def get_next(self, queue_id: str, origin_prefix: Optional[str] = None) -> Optional[SessionQueueItem]:
         """Gets the next session queue item (does not dequeue it)"""
         pass
 
@@ -79,6 +79,7 @@ def get_queue_status(
         queue_id: str,
         user_id: Optional[str] = None,
         acting_user_id: Optional[str] = None,
+        origin_prefix: Optional[str] = None,
     ) -> SessionQueueStatus:
         """Gets the status of the queue.
 
@@ -207,6 +208,7 @@ def get_queue_item_ids(
         queue_id: str,
         order_dir: SQLiteDirection = SQLiteDirection.Descending,
         user_id: Optional[str] = None,
+        origin_prefix: Optional[str] = None,
     ) -> ItemIdsResult:
         """Gets all queue item ids that match the given parameters. If user_id is provided, only returns items for that user."""
         pass
diff --git a/invokeai/app/services/session_queue/session_queue_sqlite.py b/invokeai/app/services/session_queue/session_queue_sqlite.py
index 51980d68f3b..9f4f82817f7 100644
--- a/invokeai/app/services/session_queue/session_queue_sqlite.py
+++ b/invokeai/app/services/session_queue/session_queue_sqlite.py
@@ -279,7 +279,7 @@ async def enqueue_batch(
                     SELECT item_id
                     FROM session_queue
                     WHERE batch_id = ?
-                    ORDER BY item_id DESC;
+                    ORDER BY item_id ASC;
                     """,
                 (batch.batch_id,),
             )
@@ -310,10 +310,9 @@ def dequeue(self) -> Optional[SessionQueueItem]:
         queue_item = self._set_queue_item_status(item_id=queue_item.item_id, status="in_progress")
         return queue_item
 
-    def get_next(self, queue_id: str) -> Optional[SessionQueueItem]:
+    def get_next(self, queue_id: str, origin_prefix: Optional[str] = None) -> Optional[SessionQueueItem]:
         with self._db.transaction() as cursor:
-            cursor.execute(
-                """--sql
+            query = """--sql
                 SELECT
                     sq.*,
                     u.display_name as user_display_name,
@@ -323,22 +322,28 @@ def get_next(self, queue_id: str) -> Optional[SessionQueueItem]:
                 WHERE
                     sq.queue_id = ?
                     AND sq.status = 'pending'
+                """
+            params = [queue_id]
+            if origin_prefix is not None:
+                query += """--sql
+                    AND sq.origin LIKE ?
+                    """
+                params.append(f"{origin_prefix}%")
+            query += """--sql
                 ORDER BY
                     sq.priority DESC,
                     sq.created_at ASC
                 LIMIT 1
-                """,
-                (queue_id,),
-            )
+                """
+            cursor.execute(query, params)
             result = cast(Union[sqlite3.Row, None], cursor.fetchone())
         if result is None:
             return None
         return SessionQueueItem.queue_item_from_dict(dict(result))
 
-    def get_current(self, queue_id: str) -> Optional[SessionQueueItem]:
+    def get_current(self, queue_id: str, origin_prefix: Optional[str] = None) -> Optional[SessionQueueItem]:
         with self._db.transaction() as cursor:
-            cursor.execute(
-                """--sql
+            query = """--sql
                 SELECT
                     sq.*,
                     u.display_name as user_display_name,
@@ -348,10 +353,17 @@ def get_current(self, queue_id: str) -> Optional[SessionQueueItem]:
                 WHERE
                     sq.queue_id = ?
                     AND sq.status = 'in_progress'
+                """
+            params = [queue_id]
+            if origin_prefix is not None:
+                query += """--sql
+                    AND sq.origin LIKE ?
+                    """
+                params.append(f"{origin_prefix}%")
+            query += """--sql
                 LIMIT 1
-                """,
-                (queue_id,),
-            )
+                """
+            cursor.execute(query, params)
             result = cast(Union[sqlite3.Row, None], cursor.fetchone())
         if result is None:
             return None
@@ -1117,6 +1129,7 @@ def get_queue_item_ids(
         queue_id: str,
         order_dir: SQLiteDirection = SQLiteDirection.Descending,
         user_id: Optional[str] = None,
+        origin_prefix: Optional[str] = None,
     ) -> ItemIdsResult:
         with self._db.transaction() as cursor_:
             query = """--sql
@@ -1130,6 +1143,10 @@ def get_queue_item_ids(
                 query += " AND user_id = ?"
                 query_params.append(user_id)
 
+            if origin_prefix is not None:
+                query += " AND origin LIKE ?"
+                query_params.append(f"{origin_prefix}%")
+
             query += f" ORDER BY created_at {order_dir.value}"
 
             cursor_.execute(query, query_params)
@@ -1143,20 +1160,23 @@ def get_queue_status(
         queue_id: str,
         user_id: Optional[str] = None,
         acting_user_id: Optional[str] = None,
+        origin_prefix: Optional[str] = None,
     ) -> SessionQueueStatus:
         with self._db.transaction() as cursor:
-            # Aggregate counts are always global (across all users). This lets a non-admin's
-            # badge show "own / total" — their share of the whole queue — and lets the queue
-            # list surface (redacted) entries belonging to other users.
-            cursor.execute(
-                """--sql
+            # Aggregate counts are global across all users within the requested scope.
+            query = """--sql
                 SELECT status, count(*)
                 FROM session_queue
                 WHERE queue_id = ?
-                GROUP BY status
-                """,
-                (queue_id,),
-            )
+                """
+            params: list[str] = [queue_id]
+
+            if origin_prefix is not None:
+                query += " AND origin LIKE ?"
+                params.append(f"{origin_prefix}%")
+
+            query += " GROUP BY status"
+            cursor.execute(query, params)
             counts_result = cast(list[sqlite3.Row], cursor.fetchall())
 
             # When user_id is provided, additionally compute that user's own counts so the
@@ -1164,18 +1184,24 @@ def get_queue_status(
             # separate user_pending/user_in_progress fields and never replace the global counts.
             user_counts_result: list[sqlite3.Row] = []
             if user_id is not None:
-                cursor.execute(
-                    """--sql
+                user_query = """--sql
                     SELECT status, count(*)
                     FROM session_queue
                     WHERE queue_id = ? AND user_id = ?
+                    """
+                user_params = [queue_id, user_id]
+
+                if origin_prefix is not None:
+                    user_query += " AND origin LIKE ?"
+                    user_params.append(f"{origin_prefix}%")
+
+                user_query += """--sql
                     GROUP BY status
-                    """,
-                    (queue_id, user_id),
-                )
+                    """
+                cursor.execute(user_query, user_params)
                 user_counts_result = cast(list[sqlite3.Row], cursor.fetchall())
 
-        current_item = self.get_current(queue_id=queue_id)
+        current_item = self.get_current(queue_id=queue_id, origin_prefix=origin_prefix)
         total = sum(row[1] or 0 for row in counts_result)
         counts: dict[str, int] = {row[0]: row[1] for row in counts_result}
 
diff --git a/invokeai/app/services/shared/sqlite_migrator/migrations/migration_32.py b/invokeai/app/services/shared/sqlite_migrator/migrations/migration_32.py
index 9036048bced..4d64addc7d9 100644
--- a/invokeai/app/services/shared/sqlite_migrator/migrations/migration_32.py
+++ b/invokeai/app/services/shared/sqlite_migrator/migrations/migration_32.py
@@ -37,7 +37,6 @@ def _repair_model_relationships_fks(self, cursor: sqlite3.Cursor) -> None:
             # Foreign keys already point at the correct table, nothing to repair.
             return
 
-        # Rebuild the table with the correct foreign keys referencing models(id).
         cursor.execute("ALTER TABLE model_relationships RENAME TO model_relationships_old;")
         cursor.execute(
             """
@@ -55,7 +54,7 @@ def _repair_model_relationships_fks(self, cursor: sqlite3.Cursor) -> None:
             """
         )
 
-        # Copy over the existing links, dropping any orphaned rows whose model keys no
+        # Copy over existing links, dropping orphaned rows whose model keys no
         # longer exist -- these would violate the restored foreign keys.
         cursor.execute(
             """
diff --git a/invokeai/app/services/shared/sqlite_migrator/migrations/migration_33.py b/invokeai/app/services/shared/sqlite_migrator/migrations/migration_33.py
index 6f941154c58..44d54803d1f 100644
--- a/invokeai/app/services/shared/sqlite_migrator/migrations/migration_33.py
+++ b/invokeai/app/services/shared/sqlite_migrator/migrations/migration_33.py
@@ -1,70 +1,61 @@
+"""Migration 33: Add the projects table for server-side workbench project persistence.
+
+Projects are the v7 workbench's primary unit of work (spec: State Ownership).
+Each row stores one user-owned project document as opaque JSON, plus a
+monotonic revision used for optimistic concurrency: clients send the revision
+they loaded, and a save against a stale revision is rejected so concurrent
+tabs/devices cannot silently overwrite each other.
+"""
+
 import sqlite3
 
 from invokeai.app.services.shared.sqlite_migrator.sqlite_migrator_common import Migration
 
 
 class Migration33Callback:
+    """Migration to add the projects table."""
+
     def __call__(self, cursor: sqlite3.Cursor) -> None:
+        self._create_projects_table(cursor)
+
+    def _create_projects_table(self, cursor: sqlite3.Cursor) -> None:
         cursor.execute(
             """--sql
-            CREATE TABLE IF NOT EXISTS image_subfolder_move_jobs (
-                id INTEGER PRIMARY KEY,
-                state TEXT NOT NULL CHECK (
-                    state IN ('planned', 'moving', 'moved', 'committed', 'error')
-                ),
+            CREATE TABLE projects (
+                -- Client-generated identifier; unique per user, not globally.
+                project_id TEXT NOT NULL,
+                user_id TEXT NOT NULL,
+                name TEXT NOT NULL,
+                -- Opaque client-owned project document (JSON).
+                data TEXT NOT NULL,
+                -- Incremented on every update; used for optimistic concurrency.
+                revision INTEGER NOT NULL DEFAULT 1,
                 created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
                 updated_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
-                error_message TEXT
-            );
-            """
-        )
-        cursor.execute(
-            """--sql
-            CREATE TABLE IF NOT EXISTS image_subfolder_move_items (
-                job_id INTEGER NOT NULL REFERENCES image_subfolder_move_jobs(id),
-                image_name TEXT NOT NULL REFERENCES images(image_name),
-                old_subfolder TEXT NOT NULL,
-                new_subfolder TEXT NOT NULL,
-                is_intermediate BOOLEAN NOT NULL DEFAULT FALSE,
-                old_path TEXT,
-                new_path TEXT,
-                old_thumbnail_path TEXT,
-                new_thumbnail_path TEXT,
-                state TEXT NOT NULL CHECK (
-                    state IN ('planned', 'moved', 'committed', 'error')
-                ),
-                error_message TEXT,
-                PRIMARY KEY (job_id, image_name)
+                PRIMARY KEY (user_id, project_id),
+                FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
             );
             """
         )
         cursor.execute(
             """--sql
-            CREATE INDEX IF NOT EXISTS idx_image_subfolder_move_items_job_state
-            ON image_subfolder_move_items(job_id, state);
-            """
-        )
-        cursor.execute(
-            """--sql
-            CREATE INDEX IF NOT EXISTS idx_image_subfolder_move_items_image_name
-            ON image_subfolder_move_items(image_name);
-            """
-        )
-        cursor.execute(
-            """--sql
-            CREATE TRIGGER IF NOT EXISTS tg_image_subfolder_move_jobs_updated_at
-            AFTER UPDATE
-            ON image_subfolder_move_jobs FOR EACH ROW
+            CREATE TRIGGER tg_projects_updated_at
+            AFTER UPDATE ON projects
+            FOR EACH ROW
             BEGIN
-                UPDATE image_subfolder_move_jobs
+              UPDATE projects
                 SET updated_at = STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')
-                WHERE id = old.id;
+              WHERE user_id = OLD.user_id AND project_id = OLD.project_id;
             END;
             """
         )
 
 
 def build_migration_33() -> Migration:
+    """Builds the migration object for migrating from version 32 to version 33. This includes:
+    - Creating the `projects` table for per-user workbench project persistence.
+    - Adding a trigger to keep `updated_at` current.
+    """
     return Migration(
         from_version=32,
         to_version=33,
diff --git a/invokeai/app/services/shared/sqlite_migrator/migrations/migration_34.py b/invokeai/app/services/shared/sqlite_migrator/migrations/migration_34.py
new file mode 100644
index 00000000000..82d428ad248
--- /dev/null
+++ b/invokeai/app/services/shared/sqlite_migrator/migrations/migration_34.py
@@ -0,0 +1,72 @@
+import sqlite3
+
+from invokeai.app.services.shared.sqlite_migrator.sqlite_migrator_common import Migration
+
+
+class Migration34Callback:
+    def __call__(self, cursor: sqlite3.Cursor) -> None:
+        cursor.execute(
+            """--sql
+            CREATE TABLE IF NOT EXISTS image_subfolder_move_jobs (
+                id INTEGER PRIMARY KEY,
+                state TEXT NOT NULL CHECK (
+                    state IN ('planned', 'moving', 'moved', 'committed', 'error')
+                ),
+                created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+                updated_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+                error_message TEXT
+            );
+            """
+        )
+        cursor.execute(
+            """--sql
+            CREATE TABLE IF NOT EXISTS image_subfolder_move_items (
+                job_id INTEGER NOT NULL REFERENCES image_subfolder_move_jobs(id),
+                image_name TEXT NOT NULL REFERENCES images(image_name),
+                old_subfolder TEXT NOT NULL,
+                new_subfolder TEXT NOT NULL,
+                is_intermediate BOOLEAN NOT NULL DEFAULT FALSE,
+                old_path TEXT,
+                new_path TEXT,
+                old_thumbnail_path TEXT,
+                new_thumbnail_path TEXT,
+                state TEXT NOT NULL CHECK (
+                    state IN ('planned', 'moved', 'committed', 'error')
+                ),
+                error_message TEXT,
+                PRIMARY KEY (job_id, image_name)
+            );
+            """
+        )
+        cursor.execute(
+            """--sql
+            CREATE INDEX IF NOT EXISTS idx_image_subfolder_move_items_job_state
+            ON image_subfolder_move_items(job_id, state);
+            """
+        )
+        cursor.execute(
+            """--sql
+            CREATE INDEX IF NOT EXISTS idx_image_subfolder_move_items_image_name
+            ON image_subfolder_move_items(image_name);
+            """
+        )
+        cursor.execute(
+            """--sql
+            CREATE TRIGGER IF NOT EXISTS tg_image_subfolder_move_jobs_updated_at
+            AFTER UPDATE
+            ON image_subfolder_move_jobs FOR EACH ROW
+            BEGIN
+                UPDATE image_subfolder_move_jobs
+                SET updated_at = STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')
+                WHERE id = old.id;
+            END;
+            """
+        )
+
+
+def build_migration_34() -> Migration:
+    return Migration(
+        from_version=33,
+        to_version=34,
+        callback=Migration34Callback(),
+    )
diff --git a/invokeai/backend/image_util/segment_anything/segment_anything_2_pipeline.py b/invokeai/backend/image_util/segment_anything/segment_anything_2_pipeline.py
index 79a7d91a7bf..47fdc6c41e8 100644
--- a/invokeai/backend/image_util/segment_anything/segment_anything_2_pipeline.py
+++ b/invokeai/backend/image_util/segment_anything/segment_anything_2_pipeline.py
@@ -2,8 +2,6 @@
 
 import torch
 from PIL import Image
-
-# Import SAM2 components - these should be available in transformers 4.56.0+
 from transformers.models.sam2 import Sam2Model
 from transformers.models.sam2.processing_sam2 import Sam2Processor
 
@@ -101,7 +99,6 @@ def segment(
         masks = self._sam2_processor.post_process_masks(
             masks=outputs.pred_masks,
             original_sizes=processed_inputs.original_sizes,
-            reshaped_input_sizes=processed_inputs.reshaped_input_sizes,
         )
 
         # There should be only one batch.
diff --git a/invokeai/backend/model_manager/load/model_cache/cache_stats.py b/invokeai/backend/model_manager/load/model_cache/cache_stats.py
index 4998ac6c77a..c339d3b7ad1 100644
--- a/invokeai/backend/model_manager/load/model_cache/cache_stats.py
+++ b/invokeai/backend/model_manager/load/model_cache/cache_stats.py
@@ -9,6 +9,7 @@ class CacheStats(object):
     hits: int = 0  # cache hits
     misses: int = 0  # cache misses
     high_watermark: int = 0  # amount of cache used
+    cache_used: int = 0  # current amount of cache used
     in_cache: int = 0  # number of models in cache
     cleared: int = 0  # number of models cleared to make space
     cache_size: int = 0  # total size of cache
diff --git a/invokeai/backend/model_manager/load/model_cache/model_cache.py b/invokeai/backend/model_manager/load/model_cache/model_cache.py
index e3a0928e52b..6b5da659848 100644
--- a/invokeai/backend/model_manager/load/model_cache/model_cache.py
+++ b/invokeai/backend/model_manager/load/model_cache/model_cache.py
@@ -77,6 +77,12 @@ class CacheEntrySnapshot:
     current_vram_bytes: int
 
 
+@dataclass(frozen=True)
+class CacheClearResult:
+    models_cleared: int
+    bytes_freed: int
+
+
 class CacheMissCallback(Protocol):
     def __call__(
         self,
@@ -360,6 +366,7 @@ def put(self, key: str, model: AnyModel, execution_device: Optional[torch.device
         cache_record = CacheRecord(key=key, cached_model=wrapped_model)
         self._cached_models[key] = cache_record
         self._cache_stack.append(key)
+        self._sync_current_stats()
         self._logger.debug(
             f"Added model {key} (Type: {model.__class__.__name__}, Wrap mode: {wrapped_model.__class__.__name__}, Model size: {size / MB:.2f}MB)"
         )
@@ -378,6 +385,11 @@ def _get_cache_snapshot(self) -> dict[str, CacheEntrySnapshot]:
 
         return overview
 
+    def _sync_current_stats(self) -> None:
+        if self.stats:
+            self.stats.cache_used = self._get_ram_in_use()
+            self.stats.in_cache = len(self._cached_models)
+
     @synchronized
     @record_activity
     def get(self, key: str, stats_name: Optional[str] = None) -> CacheRecord:
@@ -405,6 +417,7 @@ def get(self, key: str, stats_name: Optional[str] = None) -> CacheRecord:
         if self.stats:
             stats_name = stats_name or key
             self.stats.high_watermark = max(self.stats.high_watermark, self._get_ram_in_use())
+            self.stats.cache_used = self._get_ram_in_use()
             self.stats.in_cache = len(self._cached_models)
             self.stats.loaded_model_sizes[stats_name] = max(
                 self.stats.loaded_model_sizes.get(stats_name, 0), cache_entry.cached_model.total_bytes()
@@ -485,6 +498,7 @@ def unlock(self, cache_entry: CacheRecord) -> None:
             self._delete_cache_entry(cache_entry)
             if self.stats:
                 self.stats.cleared = (self.stats.cleared or 0) + 1
+                self._sync_current_stats()
             snapshot = self._get_cache_snapshot()
             for cb in self._on_cache_models_cleared_callbacks:
                 cb(
@@ -820,16 +834,16 @@ def _log_cache_state(self, title: str = "Model cache state:", include_entry_deta
         self._logger.debug(log)
 
     @synchronized
-    def make_room(self, bytes_needed: int) -> None:
+    def make_room(self, bytes_needed: int) -> CacheClearResult:
         """Make enough room in the cache to accommodate a new model of indicated size.
 
         Note: This function deletes all of the cache's internal references to a model in order to free it. If there are
         external references to the model, there's nothing that the cache can do about it, and those models will not be
         garbage-collected.
         """
-        self._make_room_internal(bytes_needed)
+        return self._make_room_internal(bytes_needed)
 
-    def _make_room_internal(self, bytes_needed: int) -> None:
+    def _make_room_internal(self, bytes_needed: int) -> CacheClearResult:
         """Internal implementation of make_room(). Assumes the lock is already held."""
         self._logger.debug(f"Making room for {bytes_needed / MB:.2f}MB of RAM.")
         self._log_cache_state(title="Before dropping models:")
@@ -878,9 +892,12 @@ def _make_room_internal(self, bytes_needed: int) -> None:
                 )
             gc.collect()
 
+        self._sync_current_stats()
+
         TorchDevice.empty_cache()
         self._logger.debug(f"Dropped {models_cleared} models to free {ram_bytes_freed / MB:.2f}MB of RAM.")
         self._log_cache_state(title="After dropping models:")
+        return CacheClearResult(models_cleared=models_cleared, bytes_freed=ram_bytes_freed)
 
     def _delete_cache_entry(self, cache_entry: CacheRecord) -> None:
         """Delete cache_entry from the cache if it exists. No exception is thrown if it doesn't exist."""
@@ -918,6 +935,7 @@ def drop_model(self, model_key: str) -> int:
         if dropped:
             if self.stats:
                 self.stats.cleared = len(dropped)
+                self._sync_current_stats()
             snapshot = self._get_cache_snapshot()
             for cb in self._on_cache_models_cleared_callbacks:
                 cb(
diff --git a/invokeai/frontend/web/openapi.json b/invokeai/frontend/web/openapi.json
index e2801e9e39a..4191149397c 100644
--- a/invokeai/frontend/web/openapi.json
+++ b/invokeai/frontend/web/openapi.json
@@ -728,6 +728,27 @@
         }
       }
     },
+    "/api/v2/models/models_dir": {
+      "get": {
+        "tags": ["model_manager"],
+        "summary": "Get Models Dir",
+        "description": "Get the absolute path of the directory managed models are stored in.\n\nModel config `path` values are relative to this directory unless they are\nabsolute (in-place installs from outside it).",
+        "operationId": "get_models_dir",
+        "responses": {
+          "200": {
+            "description": "The absolute path of the models directory",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "string",
+                  "title": "Response Get Models Dir"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v2/models/get_by_attrs": {
       "get": {
         "tags": ["model_manager"],
@@ -2905,6 +2926,24 @@
               "title": "Access Token"
             },
             "description": "access token for the remote resource"
+          },
+          {
+            "name": "X-Model-Source-Access-Token",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "access token for the remote resource",
+              "title": "X-Model-Source-Access-Token"
+            },
+            "description": "access token for the remote resource"
           }
         ],
         "requestBody": {
@@ -3795,7 +3834,9 @@
             "description": "Successful Response",
             "content": {
               "application/json": {
-                "schema": {}
+                "schema": {
+                  "$ref": "#/components/schemas/EmptyModelCacheResponse"
+                }
               }
             }
           }
@@ -3823,7 +3864,12 @@
               }
             }
           }
-        }
+        },
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ]
       },
       "post": {
         "tags": ["model_manager"],
@@ -6621,7 +6667,12 @@
               }
             }
           }
-        }
+        },
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ]
       }
     },
     "/api/v1/app/external_providers/config": {
@@ -6644,7 +6695,12 @@
               }
             }
           }
-        }
+        },
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ]
       }
     },
     "/api/v1/app/external_providers/config/{provider_id}": {
@@ -7054,6 +7110,24 @@
               "default": "DESC"
             },
             "description": "The order of sort"
+          },
+          {
+            "name": "origin_prefix",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Only include queue items whose origin starts with this prefix",
+              "title": "Origin Prefix"
+            },
+            "description": "Only include queue items whose origin starts with this prefix"
           }
         ],
         "responses": {
@@ -7632,6 +7706,24 @@
               "title": "Queue Id"
             },
             "description": "The queue id to perform this operation on"
+          },
+          {
+            "name": "origin_prefix",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Only include queue items whose origin starts with this prefix",
+              "title": "Origin Prefix"
+            },
+            "description": "Only include queue items whose origin starts with this prefix"
           }
         ],
         "responses": {
@@ -7694,6 +7786,24 @@
               "title": "Queue Id"
             },
             "description": "The queue id to perform this operation on"
+          },
+          {
+            "name": "origin_prefix",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Only include queue items whose origin starts with this prefix",
+              "title": "Origin Prefix"
+            },
+            "description": "Only include queue items whose origin starts with this prefix"
           }
         ],
         "responses": {
@@ -7756,6 +7866,24 @@
               "title": "Queue Id"
             },
             "description": "The queue id to perform this operation on"
+          },
+          {
+            "name": "origin_prefix",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Only include queue items whose origin starts with this prefix",
+              "title": "Origin Prefix"
+            },
+            "description": "Only include queue items whose origin starts with this prefix"
           }
         ],
         "responses": {
@@ -9697,6 +9825,223 @@
         }
       }
     },
+    "/api/v1/projects/": {
+      "get": {
+        "tags": ["projects"],
+        "summary": "List Projects",
+        "description": "Lists the current user's projects as lightweight summaries (no documents).",
+        "operationId": "list_projects",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": {
+                    "$ref": "#/components/schemas/ProjectSummaryDTO"
+                  },
+                  "type": "array",
+                  "title": "Response List Projects"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ]
+      },
+      "post": {
+        "tags": ["projects"],
+        "summary": "Create Project",
+        "description": "Creates a project for the current user.",
+        "operationId": "create_project",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProjectCreateRequest",
+                "description": "The project to create"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProjectRecordDTO"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ]
+      }
+    },
+    "/api/v1/projects/{project_id}": {
+      "get": {
+        "tags": ["projects"],
+        "summary": "Get Project",
+        "description": "Gets one of the current user's projects, including its document.",
+        "operationId": "get_project",
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "project_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "description": "The id of the project to get",
+              "title": "Project Id"
+            },
+            "description": "The id of the project to get"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProjectRecordDTO"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "tags": ["projects"],
+        "summary": "Update Project",
+        "description": "Saves a project. Returns 409 with the current revision when the save is based on a stale revision.",
+        "operationId": "update_project",
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "project_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "description": "The id of the project to save",
+              "title": "Project Id"
+            },
+            "description": "The id of the project to save"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProjectUpdateRequest",
+                "description": "The project document and the revision it is based on"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProjectRecordDTO"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": ["projects"],
+        "summary": "Delete Project",
+        "description": "Deletes one of the current user's projects. Idempotent.",
+        "operationId": "delete_project",
+        "security": [
+          {
+            "HTTPBearer": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "project_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "description": "The id of the project to delete",
+              "title": "Project Id"
+            },
+            "description": "The id of the project to delete"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/recall/{queue_id}": {
       "post": {
         "tags": ["recall"],
@@ -14722,6 +15067,11 @@
             "title": "High Watermark",
             "default": 0
           },
+          "cache_used": {
+            "type": "integer",
+            "title": "Cache Used",
+            "default": 0
+          },
           "in_cache": {
             "type": "integer",
             "title": "In Cache",
@@ -22597,6 +22947,21 @@
         "required": ["node_id", "field"],
         "title": "EdgeConnection"
       },
+      "EmptyModelCacheResponse": {
+        "properties": {
+          "models_cleared": {
+            "type": "integer",
+            "title": "Models Cleared"
+          },
+          "bytes_freed": {
+            "type": "integer",
+            "title": "Bytes Freed"
+          }
+        },
+        "type": "object",
+        "required": ["models_cleared", "bytes_freed"],
+        "title": "EmptyModelCacheResponse"
+      },
       "EnqueueBatchResult": {
         "properties": {
           "queue_id": {
@@ -59795,6 +60160,133 @@
         "title": "ProgressImage",
         "type": "object"
       },
+      "ProjectCreateRequest": {
+        "properties": {
+          "project_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Project Id",
+            "description": "Client-generated project id (e.g. for imports); generated when omitted"
+          },
+          "name": {
+            "type": "string",
+            "title": "Name",
+            "description": "The project's display name"
+          },
+          "data": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Data",
+            "description": "The opaque client-owned project document"
+          }
+        },
+        "type": "object",
+        "required": ["name", "data"],
+        "title": "ProjectCreateRequest",
+        "description": "Request body for creating a project."
+      },
+      "ProjectRecordDTO": {
+        "properties": {
+          "project_id": {
+            "type": "string",
+            "title": "Project Id",
+            "description": "The project's client-generated identifier"
+          },
+          "name": {
+            "type": "string",
+            "title": "Name",
+            "description": "The project's display name"
+          },
+          "revision": {
+            "type": "integer",
+            "title": "Revision",
+            "description": "Monotonic revision, incremented on every save"
+          },
+          "created_at": {
+            "type": "string",
+            "title": "Created At",
+            "description": "When the project was created"
+          },
+          "updated_at": {
+            "type": "string",
+            "title": "Updated At",
+            "description": "When the project was last saved"
+          },
+          "data": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Data",
+            "description": "The opaque client-owned project document"
+          }
+        },
+        "type": "object",
+        "required": ["project_id", "name", "revision", "created_at", "updated_at", "data"],
+        "title": "ProjectRecordDTO",
+        "description": "Full project record including the client-owned document."
+      },
+      "ProjectSummaryDTO": {
+        "properties": {
+          "project_id": {
+            "type": "string",
+            "title": "Project Id",
+            "description": "The project's client-generated identifier"
+          },
+          "name": {
+            "type": "string",
+            "title": "Name",
+            "description": "The project's display name"
+          },
+          "revision": {
+            "type": "integer",
+            "title": "Revision",
+            "description": "Monotonic revision, incremented on every save"
+          },
+          "created_at": {
+            "type": "string",
+            "title": "Created At",
+            "description": "When the project was created"
+          },
+          "updated_at": {
+            "type": "string",
+            "title": "Updated At",
+            "description": "When the project was last saved"
+          }
+        },
+        "type": "object",
+        "required": ["project_id", "name", "revision", "created_at", "updated_at"],
+        "title": "ProjectSummaryDTO",
+        "description": "Lightweight project listing entry; the document payload is omitted."
+      },
+      "ProjectUpdateRequest": {
+        "properties": {
+          "name": {
+            "type": "string",
+            "title": "Name",
+            "description": "The project's display name"
+          },
+          "data": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Data",
+            "description": "The opaque client-owned project document"
+          },
+          "expected_revision": {
+            "type": "integer",
+            "title": "Expected Revision",
+            "description": "The revision this save is based on; mismatch returns 409"
+          }
+        },
+        "type": "object",
+        "required": ["name", "data", "expected_revision"],
+        "title": "ProjectUpdateRequest",
+        "description": "Request body for saving a project with optimistic concurrency."
+      },
       "PromptTemplateInvocation": {
         "category": "prompt",
         "class": "invocation",
diff --git a/invokeai/frontend/web/src/features/controlLayers/components/StagingArea/__mocks__/mockStagingAreaApp.ts b/invokeai/frontend/web/src/features/controlLayers/components/StagingArea/__mocks__/mockStagingAreaApp.ts
index e0b56d5a439..bd848127756 100644
--- a/invokeai/frontend/web/src/features/controlLayers/components/StagingArea/__mocks__/mockStagingAreaApp.ts
+++ b/invokeai/frontend/web/src/features/controlLayers/components/StagingArea/__mocks__/mockStagingAreaApp.ts
@@ -165,6 +165,7 @@ export const createMockQueueItemStatusChangedEvent = (
       status: 'completed',
       error_type: null,
       error_message: null,
+      error_traceback: null,
     } as S['QueueItemStatusChangedEvent'],
     overrides
   );
diff --git a/invokeai/frontend/web/src/services/api/schema.ts b/invokeai/frontend/web/src/services/api/schema.ts
index f938b7f0f2c..6ec09bef539 100644
--- a/invokeai/frontend/web/src/services/api/schema.ts
+++ b/invokeai/frontend/web/src/services/api/schema.ts
@@ -388,6 +388,29 @@ export type paths = {
         patch?: never;
         trace?: never;
     };
+    "/api/v2/models/models_dir": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Models Dir
+         * @description Get the absolute path of the directory managed models are stored in.
+         *
+         *     Model config `path` values are relative to this directory unless they are
+         *     absolute (in-place installs from outside it).
+         */
+        get: operations["get_models_dir"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v2/models/get_by_attrs": {
         parameters: {
             query?: never;
@@ -2704,6 +2727,58 @@ export type paths = {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/projects/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List Projects
+         * @description Lists the current user's projects as lightweight summaries (no documents).
+         */
+        get: operations["list_projects"];
+        put?: never;
+        /**
+         * Create Project
+         * @description Creates a project for the current user.
+         */
+        post: operations["create_project"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/projects/{project_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Project
+         * @description Gets one of the current user's projects, including its document.
+         */
+        get: operations["get_project"];
+        /**
+         * Update Project
+         * @description Saves a project. Returns 409 with the current revision when the save is based on a stale revision.
+         */
+        put: operations["update_project"];
+        post?: never;
+        /**
+         * Delete Project
+         * @description Deletes one of the current user's projects. Idempotent.
+         */
+        delete: operations["delete_project"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/recall/{queue_id}": {
         parameters: {
             query?: never;
@@ -5349,6 +5424,11 @@ export type components = {
              * @default 0
              */
             high_watermark?: number;
+            /**
+             * Cache Used
+             * @default 0
+             */
+            cache_used?: number;
             /**
              * In Cache
              * @default 0
@@ -9325,6 +9405,13 @@ export type components = {
              */
             field: string;
         };
+        /** EmptyModelCacheResponse */
+        EmptyModelCacheResponse: {
+            /** Models Cleared */
+            models_cleared: number;
+            /** Bytes Freed */
+            bytes_freed: number;
+        };
         /** EnqueueBatchResult */
         EnqueueBatchResult: {
             /**
@@ -25266,6 +25353,121 @@ export type components = {
              */
             dataURL: string;
         };
+        /**
+         * ProjectCreateRequest
+         * @description Request body for creating a project.
+         */
+        ProjectCreateRequest: {
+            /**
+             * Project Id
+             * @description Client-generated project id (e.g. for imports); generated when omitted
+             */
+            project_id?: string | null;
+            /**
+             * Name
+             * @description The project's display name
+             */
+            name: string;
+            /**
+             * Data
+             * @description The opaque client-owned project document
+             */
+            data: {
+                [key: string]: unknown;
+            };
+        };
+        /**
+         * ProjectRecordDTO
+         * @description Full project record including the client-owned document.
+         */
+        ProjectRecordDTO: {
+            /**
+             * Project Id
+             * @description The project's client-generated identifier
+             */
+            project_id: string;
+            /**
+             * Name
+             * @description The project's display name
+             */
+            name: string;
+            /**
+             * Revision
+             * @description Monotonic revision, incremented on every save
+             */
+            revision: number;
+            /**
+             * Created At
+             * @description When the project was created
+             */
+            created_at: string;
+            /**
+             * Updated At
+             * @description When the project was last saved
+             */
+            updated_at: string;
+            /**
+             * Data
+             * @description The opaque client-owned project document
+             */
+            data: {
+                [key: string]: unknown;
+            };
+        };
+        /**
+         * ProjectSummaryDTO
+         * @description Lightweight project listing entry; the document payload is omitted.
+         */
+        ProjectSummaryDTO: {
+            /**
+             * Project Id
+             * @description The project's client-generated identifier
+             */
+            project_id: string;
+            /**
+             * Name
+             * @description The project's display name
+             */
+            name: string;
+            /**
+             * Revision
+             * @description Monotonic revision, incremented on every save
+             */
+            revision: number;
+            /**
+             * Created At
+             * @description When the project was created
+             */
+            created_at: string;
+            /**
+             * Updated At
+             * @description When the project was last saved
+             */
+            updated_at: string;
+        };
+        /**
+         * ProjectUpdateRequest
+         * @description Request body for saving a project with optimistic concurrency.
+         */
+        ProjectUpdateRequest: {
+            /**
+             * Name
+             * @description The project's display name
+             */
+            name: string;
+            /**
+             * Data
+             * @description The opaque client-owned project document
+             */
+            data: {
+                [key: string]: unknown;
+            };
+            /**
+             * Expected Revision
+             * @description The revision this save is based on; mismatch returns 409
+             */
+            expected_revision: number;
+        };
         /**
          * Prompt Template
          * @description Applies a Style Preset template to positive and negative prompts.
@@ -34544,6 +34746,26 @@ export interface operations {
             };
         };
     };
+    get_models_dir: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The absolute path of the models directory */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": string;
+                };
+            };
+        };
+    };
     get_model_records_by_attrs: {
         parameters: {
             query: {
@@ -35158,7 +35380,10 @@ export interface operations {
                 /** @description access token for the remote resource */
                 access_token?: string | null;
             };
-            header?: never;
+            header?: {
+                /** @description access token for the remote resource */
+                "X-Model-Source-Access-Token"?: string | null;
+            };
             path?: never;
             cookie?: never;
         };
@@ -35655,7 +35880,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": unknown;
+                    "application/json": components["schemas"]["EmptyModelCacheResponse"];
                 };
             };
         };
@@ -37839,6 +38064,8 @@ export interface operations {
             query?: {
                 /** @description The order of sort */
                 order_dir?: components["schemas"]["SQLiteDirection"];
+                /** @description Only include queue items whose origin starts with this prefix */
+                origin_prefix?: string | null;
             };
             header?: never;
             path: {
@@ -38206,7 +38433,10 @@ export interface operations {
     };
     get_current_queue_item: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Only include queue items whose origin starts with this prefix */
+                origin_prefix?: string | null;
+            };
             header?: never;
             path: {
                 /** @description The queue id to perform this operation on */
@@ -38238,7 +38468,10 @@ export interface operations {
     };
     get_next_queue_item: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Only include queue items whose origin starts with this prefix */
+                origin_prefix?: string | null;
+            };
             header?: never;
             path: {
                 /** @description The queue id to perform this operation on */
@@ -38270,7 +38503,10 @@ export interface operations {
     };
     get_queue_status: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Only include queue items whose origin starts with this prefix */
+                origin_prefix?: string | null;
+            };
             header?: never;
             path: {
                 /** @description The queue id to perform this operation on */
@@ -39422,6 +39658,157 @@ export interface operations {
             };
         };
     };
+    list_projects: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProjectSummaryDTO"][];
+                };
+            };
+        };
+    };
+    create_project: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProjectCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProjectRecordDTO"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    get_project: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The id of the project to get */
+                project_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProjectRecordDTO"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    update_project: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The id of the project to save */
+                project_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProjectUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProjectRecordDTO"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    delete_project: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The id of the project to delete */
+                project_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     get_recall_parameters: {
         parameters: {
             query?: never;
diff --git a/invokeai/frontend/webv2/.gitignore b/invokeai/frontend/webv2/.gitignore
new file mode 100644
index 00000000000..22f1644ccfa
--- /dev/null
+++ b/invokeai/frontend/webv2/.gitignore
@@ -0,0 +1,3 @@
+dist/
+node_modules/
+stats.html
diff --git a/invokeai/frontend/webv2/.oxfmtrc.json b/invokeai/frontend/webv2/.oxfmtrc.json
new file mode 100644
index 00000000000..a261d816261
--- /dev/null
+++ b/invokeai/frontend/webv2/.oxfmtrc.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "arrowParens": "always",
+  "bracketSameLine": false,
+  "bracketSpacing": true,
+  "endOfLine": "lf",
+  "ignorePatterns": ["dist/**", "node_modules/**", "stats.html"],
+  "printWidth": 120,
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "sortImports": {
+    "groups": [
+      "type-import",
+      ["value-builtin", "value-external"],
+      ["type-internal", "value-internal"],
+      ["type-parent", "type-sibling", "type-index"],
+      ["value-parent", "value-sibling", "value-index"],
+      "unknown"
+    ]
+  },
+  "sortPackageJson": {
+    "sortScripts": true
+  }
+}
diff --git a/invokeai/frontend/webv2/.oxlintrc.json b/invokeai/frontend/webv2/.oxlintrc.json
new file mode 100644
index 00000000000..aba3b3877a9
--- /dev/null
+++ b/invokeai/frontend/webv2/.oxlintrc.json
@@ -0,0 +1,137 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "react", "import", "unicorn", "oxc", "react-perf", "eslint"],
+  "categories": {
+    "correctness": "error"
+  },
+  "rules": {
+    "curly": "error",
+    "eqeqeq": "error",
+
+    "import/no-cycle": "error",
+    "import/no-duplicates": "error",
+    "import/no-relative-parent-imports": "error",
+    "import/no-absolute-path": "error",
+    "import/no-amd": "error",
+    "import/no-commonjs": "error",
+    "import/no-mutable-exports": "error",
+
+    "no-console": "warn",
+    "no-eval": "error",
+    "no-extend-native": "error",
+    "no-implied-eval": "error",
+    "no-label-var": "error",
+    "no-promise-executor-return": "error",
+    "no-return-assign": "error",
+    "no-sequences": "error",
+    "no-template-curly-in-string": "error",
+    "no-throw-literal": "error",
+    "no-unmodified-loop-condition": "error",
+    "no-var": "error",
+
+    "prefer-template": "error",
+    "radix": "error",
+    "no-restricted-exports": "error",
+
+    // "eslint/complexity": [
+    //   "error",
+    //   {
+    //     "max": 3
+    //   }
+    // ],
+
+    "react/jsx-curly-brace-presence": [
+      "error",
+      {
+        "props": "never",
+        "children": "never"
+      }
+    ],
+    "react/no-children-prop": "error",
+    "react/no-danger": "error",
+    "react/no-unknown-property": "error",
+    "react/jsx-no-useless-fragment": "error",
+    "react/exhaustive-deps": "error",
+    "react/react-compiler": "error",
+
+    "react-hooks/exhaustive-deps": "error",
+    "react-hooks/rules-of-hooks": "error",
+
+    "react-perf/jsx-no-new-object-as-prop": [
+      "error",
+      {
+        "nativeAllowList": "all"
+      }
+    ],
+    "react-perf/jsx-no-new-function-as-prop": [
+      "error",
+      {
+        "nativeAllowList": "all"
+      }
+    ],
+    "react-perf/jsx-no-new-array-as-prop": [
+      "error",
+      {
+        "nativeAllowList": "all"
+      }
+    ],
+    "react-perf/jsx-no-jsx-as-prop": [
+      "error",
+      {
+        "nativeAllowList": "all"
+      }
+    ],
+
+    "require-await": "error",
+
+    "typescript/consistent-type-imports": [
+      "error",
+      {
+        "fixStyle": "separate-type-imports",
+        "prefer": "type-imports"
+      }
+    ],
+    "typescript/no-empty-interface": [
+      "error",
+      {
+        "allowSingleExtends": true
+      }
+    ],
+    "typescript/consistent-type-assertions": [
+      "error",
+      {
+        "assertionStyle": "as"
+      }
+    ],
+    "typescript/ban-ts-comment": "error",
+    "typescript/no-import-type-side-effects": "error",
+
+    "unicorn/no-abusive-eslint-disable": "error",
+    "unicorn/error-message": "error",
+    "unicorn/throw-new-error": "error",
+    "unicorn/prefer-type-error": "error",
+
+    "vitest/require-mock-type-parameters": "off"
+  },
+  "env": {
+    "browser": true,
+    "builtin": true,
+    "es2022": true,
+    "node": true
+  },
+  "globals": {
+    "GlobalCompositeOperation": "readonly",
+    "RequestInit": "readonly"
+  },
+  "ignorePatterns": [
+    "dist/**",
+    "node_modules/**",
+    "static/**",
+    ".husky/**",
+    "patches/**",
+    "stats.html",
+    "index.html",
+    ".yarn/**",
+    "**/*.scss"
+  ]
+}
diff --git a/invokeai/frontend/webv2/AGENTS.md b/invokeai/frontend/webv2/AGENTS.md
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/invokeai/frontend/webv2/OXC_RULE_COMPATIBILITY.md b/invokeai/frontend/webv2/OXC_RULE_COMPATIBILITY.md
new file mode 100644
index 00000000000..2af36ab0b91
--- /dev/null
+++ b/invokeai/frontend/webv2/OXC_RULE_COMPATIBILITY.md
@@ -0,0 +1,23 @@
+# OXC Rule Compatibility
+
+`webv2` uses `oxlint` and `oxfmt` instead of ESLint and Prettier.
+
+The config mirrors the existing Invoke web lint intent where OXC supports equivalent rules:
+
+- React and hooks checks: `react/jsx-no-bind`, `react/jsx-curly-brace-presence`, `react-hooks/*`.
+- TypeScript checks: `typescript/consistent-type-imports`, `typescript/no-empty-interface`, plus TypeScript compile checks through `tsc --noEmit`.
+- Import checks: `import/no-duplicates`, `import/no-cycle`.
+- General correctness/style checks: `curly`, `no-var`, `prefer-template`, `radix`, `eqeqeq`, `no-eval`, `no-extend-native`, `no-implied-eval`, `no-label-var`, `no-return-assign`, `no-sequences`, `no-template-curly-in-string`, `no-throw-literal`, `no-unmodified-loop-condition`, `no-console`, `no-promise-executor-return`, and `require-await`.
+- Formatting: `oxfmt` uses the same print width, tab width, semicolon, single quote, and trailing comma preferences as the existing web formatter. It uses `lf` line endings because `oxfmt` does not support Prettier's `auto` value.
+
+Known unsupported or intentionally deferred equivalents:
+
+- `brace-style`, `one-var`, and `react/jsx-no-bind`: oxlint 1.69.0 does not expose these ESLint/plugin rule names.
+- `simple-import-sort/*`: oxlint does not currently provide the same configurable import sorting behavior.
+- `unused-imports/no-unused-imports`: oxlint reports unused bindings, but it is not the same plugin rule.
+- `@typescript-eslint/ban-ts-comment`: no exact oxlint equivalent is configured yet.
+- `@typescript-eslint/no-import-type-side-effects`: no exact oxlint equivalent is configured yet.
+- `@typescript-eslint/consistent-type-assertions`: no exact oxlint equivalent is configured yet.
+- `path/no-relative-imports`: no exact oxlint equivalent is configured yet.
+- `no-restricted-syntax`, `no-restricted-properties`, `no-restricted-imports`: no exact oxlint config equivalent is configured yet.
+- `i18next/no-literal-string` and Storybook-specific overrides: not configured for the initial `webv2` shell.
diff --git a/invokeai/frontend/webv2/index.html b/invokeai/frontend/webv2/index.html
new file mode 100644
index 00000000000..ef74665c231
--- /dev/null
+++ b/invokeai/frontend/webv2/index.html
@@ -0,0 +1,54 @@
+<!doctype html>
+<html lang="en" class="dark" style="color-scheme: dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Invoke V7 Workbench</title>
+    <script>
+      // Apply the saved theme before first paint so non-default themes don't
+      // flash the default dark surfaces. ThemeController re-applies it on mount.
+      // The theme hint key is user-agnostic (the workbench snapshot is per-user
+      // on multi-user backends); the snapshot read is a legacy fallback.
+      (function () {
+        try {
+          var themeColorSchemes = {
+            classic: 'dark',
+            forest: 'dark',
+            light: 'light',
+            mono: 'dark',
+            ultradark: 'dark',
+          };
+          var id = localStorage.getItem('invokeai:v7:webv2:theme');
+          if (!id) {
+            var raw = localStorage.getItem('invokeai:v7:webv2:workbench');
+            id = raw && JSON.parse(raw).state.account.preferences.themeId;
+          }
+          var colorScheme = themeColorSchemes[id];
+          var root = document.documentElement;
+          if (colorScheme) {
+            var isLight = colorScheme === 'light';
+            root.setAttribute('data-theme', id);
+            root.style.colorScheme = colorScheme;
+            root.classList.toggle('dark', !isLight);
+            root.classList.toggle('light', isLight);
+          }
+          if (localStorage.getItem('invokeai:v7:webv2:reduce-motion') === 'true') {
+            root.setAttribute('data-reduce-motion', 'true');
+          }
+          var language = localStorage.getItem('invokeai:v7:webv2:language');
+          if (language) {
+            root.setAttribute('lang', language);
+            var direction = language === 'ar' || language === 'he' ? 'rtl' : 'ltr';
+            root.setAttribute('dir', direction);
+          }
+        } catch (error) {
+          /* ignore malformed storage */
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/invokeai/frontend/webv2/package.json b/invokeai/frontend/webv2/package.json
new file mode 100644
index 00000000000..e3b8b58ae21
--- /dev/null
+++ b/invokeai/frontend/webv2/package.json
@@ -0,0 +1,70 @@
+{
+  "name": "@invoke-ai/invoke-ai-webv2",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "pnpm run lint && vite build",
+    "dev": "vite dev",
+    "dev:host": "vite dev --host",
+    "fix": "pnpm run lint:oxc:fix && pnpm run format:write",
+    "format:check": "oxfmt --check .",
+    "format:write": "oxfmt --write .",
+    "i18n:report": "node scripts/i18n-report.mjs",
+    "i18n:report:verbose": "node scripts/i18n-report.mjs --verbose",
+    "lint": "pnpm run format:check && pnpm run lint:oxc && pnpm run lint:tsc",
+    "lint:oxc": "oxlint --react-plugin --import-plugin --deny-warnings .",
+    "lint:oxc:fix": "oxlint --react-plugin --import-plugin --fix .",
+    "lint:tsc": "tsc --noEmit",
+    "preview": "vite preview",
+    "test": "vitest run --config vitest.config.mts",
+    "test:all": "pnpm run test && pnpm run test:browser",
+    "test:browser": "vitest run --config vitest.browser.config.mts"
+  },
+  "dependencies": {
+    "@chakra-ui/react": "^3.36.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@emotion/react": "^11.14.0",
+    "@fontsource/inter": "^5.2.8",
+    "@tanstack/react-router": "^1.170.16",
+    "@tanstack/react-virtual": "^3.14.3",
+    "@xyflow/react": "^12.11.1",
+    "ag-psd": "^31.0.1",
+    "i18next": "^25.7.3",
+    "i18next-http-backend": "^3.0.2",
+    "lucide-react": "^1.21.0",
+    "perfect-freehand": "^1.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-hook-tanstack-virtual": "^0.0.4",
+    "react-i18next": "^16.5.0",
+    "react-icons": "^5.6.0",
+    "socket.io-client": "^4.8.3",
+    "tinykeys": "^4.0.0",
+    "use-sync-external-store": "^1.6.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@types/node": "^26.0.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@types/use-sync-external-store": "^1.5.0",
+    "@vitejs/plugin-react": "^6.0.3",
+    "@vitest/browser-playwright": "4.1.9",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "oxfmt": "^0.56.0",
+    "oxlint": "^1.71.0",
+    "playwright": "1.61.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.0",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "pnpm": "10"
+  },
+  "packageManager": "pnpm@10.12.4"
+}
diff --git a/invokeai/frontend/webv2/pnpm-lock.yaml b/invokeai/frontend/webv2/pnpm-lock.yaml
new file mode 100644
index 00000000000..5dcfad18af3
--- /dev/null
+++ b/invokeai/frontend/webv2/pnpm-lock.yaml
@@ -0,0 +1,3949 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@chakra-ui/react':
+        specifier: ^3.36.0
+        version: 3.36.0(@emotion/react@11.14.0(@types/react@19.2.17)(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/core':
+        specifier: ^6.3.1
+        version: 6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/modifiers':
+        specifier: ^9.0.0
+        version: 9.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/sortable':
+        specifier: ^10.0.0
+        version: 10.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/utilities':
+        specifier: ^3.2.2
+        version: 3.2.2(react@19.2.7)
+      '@emotion/react':
+        specifier: ^11.14.0
+        version: 11.14.0(@types/react@19.2.17)(react@19.2.7)
+      '@fontsource/inter':
+        specifier: ^5.2.8
+        version: 5.2.8
+      '@tanstack/react-router':
+        specifier: ^1.170.16
+        version: 1.170.16(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@tanstack/react-virtual':
+        specifier: ^3.14.3
+        version: 3.14.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@xyflow/react':
+        specifier: ^12.11.1
+        version: 12.11.1(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      ag-psd:
+        specifier: ^31.0.1
+        version: 31.0.1
+      i18next:
+        specifier: ^25.7.3
+        version: 25.10.10(typescript@6.0.3)
+      i18next-http-backend:
+        specifier: ^3.0.2
+        version: 3.0.6
+      lucide-react:
+        specifier: ^1.21.0
+        version: 1.21.0(react@19.2.7)
+      perfect-freehand:
+        specifier: ^1.2.3
+        version: 1.2.3
+      react:
+        specifier: ^19.2.7
+        version: 19.2.7
+      react-dom:
+        specifier: ^19.2.7
+        version: 19.2.7(react@19.2.7)
+      react-hook-tanstack-virtual:
+        specifier: ^0.0.4
+        version: 0.0.4(@tanstack/react-virtual@3.14.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@tanstack/virtual-core@3.17.1)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react-i18next:
+        specifier: ^16.5.0
+        version: 16.6.6(i18next@25.10.10(typescript@6.0.3))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(typescript@6.0.3)
+      react-icons:
+        specifier: ^5.6.0
+        version: 5.6.0(react@19.2.7)
+      socket.io-client:
+        specifier: ^4.8.3
+        version: 4.8.3
+      tinykeys:
+        specifier: ^4.0.0
+        version: 4.0.0
+      use-sync-external-store:
+        specifier: ^1.6.0
+        version: 1.6.0(react@19.2.7)
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@rolldown/plugin-babel':
+        specifier: ^0.2.3
+        version: 0.2.3(@babel/core@7.29.7)(@babel/runtime@7.29.7)(rolldown@1.1.3)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+      '@types/node':
+        specifier: ^26.0.1
+        version: 26.0.1
+      '@types/react':
+        specifier: ^19.2.17
+        version: 19.2.17
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.17)
+      '@types/use-sync-external-store':
+        specifier: ^1.5.0
+        version: 1.5.0
+      '@vitejs/plugin-react':
+        specifier: ^6.0.3
+        version: 6.0.3(@rolldown/plugin-babel@0.2.3(@babel/core@7.29.7)(@babel/runtime@7.29.7)(rolldown@1.1.3)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7)))(babel-plugin-react-compiler@1.0.0)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+      '@vitest/browser-playwright':
+        specifier: 4.1.9
+        version: 4.1.9(playwright@1.61.1)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))(vitest@4.1.9)
+      babel-plugin-react-compiler:
+        specifier: ^1.0.0
+        version: 1.0.0
+      oxfmt:
+        specifier: ^0.56.0
+        version: 0.56.0
+      oxlint:
+        specifier: ^1.71.0
+        version: 1.71.0
+      playwright:
+        specifier: 1.61.1
+        version: 1.61.1
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
+      vite:
+        specifier: ^8.1.0
+        version: 8.1.0(@types/node@26.0.1)(esbuild@0.27.7)
+      vitest:
+        specifier: ^4.1.9
+        version: 4.1.9(@types/node@26.0.1)(@vitest/browser-playwright@4.1.9)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+
+packages:
+
+  '@ark-ui/react@5.37.2':
+    resolution: {integrity: sha512-Q0R2Ah50kUhup0Ljxg65zGJq5yBV52BLm1coRkjHHid40d1yclaDGfhPL48kcF/xtjAFlGLkL6SiENkGvfh+mw==}
+    peerDependencies:
+      react: '>=18.0.0'
+      react-dom: '>=18.0.0'
+
+  '@babel/code-frame@7.29.7':
+    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/compat-data@7.29.7':
+    resolution: {integrity: sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@7.29.7':
+    resolution: {integrity: sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.7':
+    resolution: {integrity: sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-compilation-targets@7.29.7':
+    resolution: {integrity: sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-globals@7.29.7':
+    resolution: {integrity: sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.29.7':
+    resolution: {integrity: sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.29.7':
+    resolution: {integrity: sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-option@7.29.7':
+    resolution: {integrity: sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@7.29.7':
+    resolution: {integrity: sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/runtime@7.29.7':
+    resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@7.29.7':
+    resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.7':
+    resolution: {integrity: sha512-EhlfNQtZ+NK22w5BM61ciuiq1m58ed33Wr1Xan//ZRTy6hgjnwyCffRYwzsGXdASJSUJ1guZILsErh1eQcl+zw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
+    engines: {node: '>=6.9.0'}
+
+  '@blazediff/core@1.9.1':
+    resolution: {integrity: sha512-ehg3jIkYKulZh+8om/O25vkvSsXXwC+skXmyA87FFx6A/45eqOkZsBltMw/TVteb0mloiGT8oGRTcjRAz66zaA==}
+
+  '@chakra-ui/react@3.36.0':
+    resolution: {integrity: sha512-6AxUbJsC6yyTzPeYL8sxyAL07lflT0NA+S6tcPzEuwdMux+benRMFOpPktnkifWKl/Vq/JD7fhxDyMuDQ4M0gA==}
+    peerDependencies:
+      '@emotion/react': '>=11'
+      react: '>=18'
+      react-dom: '>=18'
+
+  '@dnd-kit/accessibility@3.1.1':
+    resolution: {integrity: sha512-2P+YgaXF+gRsIihwwY1gCsQSYnu9Zyj2py8kY5fFvUM1qm2WA2u639R6YNVfU4GWr+ZM5mqEsfHZZLoRONbemw==}
+    peerDependencies:
+      react: '>=16.8.0'
+
+  '@dnd-kit/core@6.3.1':
+    resolution: {integrity: sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@dnd-kit/modifiers@9.0.0':
+    resolution: {integrity: sha512-ybiLc66qRGuZoC20wdSSG6pDXFikui/dCNGthxv4Ndy8ylErY0N3KVxY2bgo7AWwIbxDmXDg3ylAFmnrjcbVvw==}
+    peerDependencies:
+      '@dnd-kit/core': ^6.3.0
+      react: '>=16.8.0'
+
+  '@dnd-kit/sortable@10.0.0':
+    resolution: {integrity: sha512-+xqhmIIzvAYMGfBYYnbKuNicfSsk4RksY2XdmJhT+HAC01nix6fHCztU68jooFiMUB01Ky3F0FyOvhG/BZrWkg==}
+    peerDependencies:
+      '@dnd-kit/core': ^6.3.0
+      react: '>=16.8.0'
+
+  '@dnd-kit/utilities@3.2.2':
+    resolution: {integrity: sha512-+MKAJEOfaBe5SmV6t34p80MMKhjvUz0vRrvVJbPT0WElzaOJ/1xs+D+KDv+tD/NE5ujfrChEcshd4fLn0wpiqg==}
+    peerDependencies:
+      react: '>=16.8.0'
+
+  '@emnapi/core@1.11.1':
+    resolution: {integrity: sha512-RSvbQmHzdKzNsLYa/wHrbc3KN4sYLKAdPZxqiM2HATqv/SBk2/ENSHpvXGaLOMcsAyz0poEGqkmmKYG3OWiJEQ==}
+
+  '@emnapi/runtime@1.11.1':
+    resolution: {integrity: sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==}
+
+  '@emnapi/wasi-threads@1.2.2':
+    resolution: {integrity: sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==}
+
+  '@emotion/babel-plugin@11.13.5':
+    resolution: {integrity: sha512-pxHCpT2ex+0q+HH91/zsdHkw/lXd468DIN2zvfvLtPKLLMo6gQj7oLObq8PhkrxOZb/gGCq03S3Z7PDhS8pduQ==}
+
+  '@emotion/cache@11.14.0':
+    resolution: {integrity: sha512-L/B1lc/TViYk4DcpGxtAVbx0ZyiKM5ktoIyafGkH6zg/tj+mA+NE//aPYKG0k8kCHSHVJrpLpcAlOBEXQ3SavA==}
+
+  '@emotion/hash@0.9.2':
+    resolution: {integrity: sha512-MyqliTZGuOm3+5ZRSaaBGP3USLw6+EGykkwZns2EPC5g8jJ4z9OrdZY9apkl3+UP9+sdz76YYkwCKP5gh8iY3g==}
+
+  '@emotion/is-prop-valid@1.4.0':
+    resolution: {integrity: sha512-QgD4fyscGcbbKwJmqNvUMSE02OsHUa+lAWKdEUIJKgqe5IwRSKd7+KhibEWdaKwgjLj0DRSHA9biAIqGBk05lw==}
+
+  '@emotion/memoize@0.9.0':
+    resolution: {integrity: sha512-30FAj7/EoJ5mwVPOWhAyCX+FPfMDrVecJAM+Iw9NRoSl4BBAQeqj4cApHHUXOVvIPgLVDsCFoz/hGD+5QQD1GQ==}
+
+  '@emotion/react@11.14.0':
+    resolution: {integrity: sha512-O000MLDBDdk/EohJPFUqvnp4qnHeYkVP5B0xEG0D/L7cOKP9kefu2DXn8dj74cQfsEzUqh+sr1RzFqiL1o+PpA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: '>=16.8.0'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@emotion/serialize@1.3.3':
+    resolution: {integrity: sha512-EISGqt7sSNWHGI76hC7x1CksiXPahbxEOrC5RjmFRJTqLyEK9/9hZvBbiYn70dw4wuwMKiEMCUlR6ZXTSWQqxA==}
+
+  '@emotion/sheet@1.4.0':
+    resolution: {integrity: sha512-fTBW9/8r2w3dXWYM4HCB1Rdp8NLibOw2+XELH5m5+AkWiL/KqYX6dc0kKYlaYyKjrQ6ds33MCdMPEwgs2z1rqg==}
+
+  '@emotion/unitless@0.10.0':
+    resolution: {integrity: sha512-dFoMUuQA20zvtVTuxZww6OHoJYgrzfKM1t52mVySDJnMSEa08ruEvdYQbhvyu6soU+NeLVd3yKfTfT0NeV6qGg==}
+
+  '@emotion/use-insertion-effect-with-fallbacks@1.2.0':
+    resolution: {integrity: sha512-yJMtVdH59sxi/aVJBpk9FQq+OR8ll5GT8oWd57UpeaKEVGab41JWaCFA7FRLoMLloOZF/c/wsPoe+bfGmRKgDg==}
+    peerDependencies:
+      react: '>=16.8.0'
+
+  '@emotion/utils@1.4.2':
+    resolution: {integrity: sha512-3vLclRofFziIa3J2wDh9jjbkUz9qk5Vi3IZ/FSTKViB0k+ef0fPV7dYrUIugbgupYDx7v9ud/SjrtEP8Y4xLoA==}
+
+  '@emotion/weak-memoize@0.4.0':
+    resolution: {integrity: sha512-snKqtPW01tN0ui7yu9rGv69aJXr/a/Ywvl11sUjNtEcRc+ng/mQriFL0wLXMef74iHa/EkftbDzU9F8iFbH+zg==}
+
+  '@esbuild/aix-ppc64@0.27.7':
+    resolution: {integrity: sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.7':
+    resolution: {integrity: sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.7':
+    resolution: {integrity: sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.7':
+    resolution: {integrity: sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.7':
+    resolution: {integrity: sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.7':
+    resolution: {integrity: sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    resolution: {integrity: sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.7':
+    resolution: {integrity: sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.7':
+    resolution: {integrity: sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.7':
+    resolution: {integrity: sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.7':
+    resolution: {integrity: sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.7':
+    resolution: {integrity: sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.7':
+    resolution: {integrity: sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.7':
+    resolution: {integrity: sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.7':
+    resolution: {integrity: sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.7':
+    resolution: {integrity: sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.7':
+    resolution: {integrity: sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.7':
+    resolution: {integrity: sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.7':
+    resolution: {integrity: sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    resolution: {integrity: sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.7':
+    resolution: {integrity: sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.7':
+    resolution: {integrity: sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.7':
+    resolution: {integrity: sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.7':
+    resolution: {integrity: sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@floating-ui/core@1.7.5':
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
+
+  '@floating-ui/dom@1.7.6':
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
+
+  '@floating-ui/utils@0.2.11':
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
+
+  '@fontsource/inter@5.2.8':
+    resolution: {integrity: sha512-P6r5WnJoKiNVV+zvW2xM13gNdFhAEpQ9dQJHt3naLvfg+LkF2ldgSLiF4T41lf1SQCM9QmkqPTn4TH568IRagg==}
+
+  '@internationalized/date@3.12.2':
+    resolution: {integrity: sha512-FY1Y+H64NDs+HAF6omlnWxm3mEpfgaCSWtL5l551ZZfImA+kGjPFgrnJrGjH6lfmLL0g8Z/mBu1R3kufeCp6Jw==}
+
+  '@internationalized/number@3.6.6':
+    resolution: {integrity: sha512-iFgmQaXHE0vytNfpLZWOC2mEJCBRzcUxt53Xf/yCXG93lRvqas237i3r7X4RKMwO3txiyZD4mQjKAByFv6UGSQ==}
+
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
+
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@napi-rs/wasm-runtime@1.1.6':
+    resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
+
+  '@oxc-project/types@0.137.0':
+    resolution: {integrity: sha512-WT+Gb24i8hmvo85AIv2oEYouEXkRlKAlT9WaCa3TfLgNCN+GhrJOGZuIlMouAh38Qe4QOx26eUOVsq70qXrywA==}
+
+  '@oxfmt/binding-android-arm-eabi@0.56.0':
+    resolution: {integrity: sha512-CSCxi7ovYojgfdPOdUb9T508HKeAdDIKeRGg7x8IZwVJrWz9gVgX7MbUnFqtQAE4QvoNo07mj2JlwnOzJw4qqA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [android]
+
+  '@oxfmt/binding-android-arm64@0.56.0':
+    resolution: {integrity: sha512-HYJFnd+PkDwf6S9ZPGzXXtjNqvRWFnnhdbWaouh4mi/SxU8wmDuzlMn3xo/wDTGnr4Q1VA7ZzOaE/D4biW0W6A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@oxfmt/binding-darwin-arm64@0.56.0':
+    resolution: {integrity: sha512-sftR/bEOr+t1gs+evwsHi/Xbq2FAPA2uU3VMr8n6ZU9PoK/IMSfnfu7+OEe/uy1+knhrFl4Wvy7Vkm3uo9mJ7g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@oxfmt/binding-darwin-x64@0.56.0':
+    resolution: {integrity: sha512-z66SdjLqa3MUPKvTp3Mbb5nSjKSbnYxJGeB+Wx987s8T5hPcIRiBMfnJ6zcPgYtQn3x5xjvdzNVkXrSeYH6ZFg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@oxfmt/binding-freebsd-x64@0.56.0':
+    resolution: {integrity: sha512-t2tkrV1vtZyaItSQ71dTi2ZVKZEI39b/LqLT12V5KMfIeXK6N32TUC1jhOXKVQmhECq9j2ZXMQV3JeT1kh9Vmg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@oxfmt/binding-linux-arm-gnueabihf@0.56.0':
+    resolution: {integrity: sha512-+gCy+Tp3RHeXQ9y/QrS76lXIpZkbziTyp6hIgjB2MssCwfMph3vG/GEfkhO34Rai1vhYIaUkvv8UT1BcDorJPw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxfmt/binding-linux-arm-musleabihf@0.56.0':
+    resolution: {integrity: sha512-0kKkVvQ2I+FJ2sxQyUu1zJ0yWP5kcWse/yVFnGQSFCXMwSSkfEaUGu0dW774O7nyy3jrcBGap7OSc8dZmU/CdA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxfmt/binding-linux-arm64-gnu@0.56.0':
+    resolution: {integrity: sha512-npkA2siMbyWRh+wEhi1aTAx4RirukGcGNt8V4Ch86pG+xU9aurqS1MZOnKYMu03ISwat3rB6zkQx51SsB9obNw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@oxfmt/binding-linux-arm64-musl@0.56.0':
+    resolution: {integrity: sha512-UekqOjGkV4/MkqreCV9SPIB2jlR3/HbXrmhV1rVXJZ9wfDXMyCMriLtq3tHqLY4PkbVWNtfcm1kMojJ26KLSJw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@oxfmt/binding-linux-ppc64-gnu@0.56.0':
+    resolution: {integrity: sha512-XSzveSpeZMD5XJpew5lRFVtNnT04xd3rJxENXmk7wkZzN9oWzv2aFJyoNDhOtoz69BYaS/fg4SYl+CfEZRpB0Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@oxfmt/binding-linux-riscv64-gnu@0.56.0':
+    resolution: {integrity: sha512-EkQ0nJa7k7HDDIVuPF7WY+k4k+bzdclLYtyIXNt7/OqVghfNiMym6YGppFBgx1XRIHW6QylxBz5OogumPjPJbQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@oxfmt/binding-linux-riscv64-musl@0.56.0':
+    resolution: {integrity: sha512-dyjAGW8jKRge0ik6U/dgvQG0nVpA3iBlRskQTz5qJLvQWIrySxX5jpqzPetLBNIIZ231KA82fDdi1nLTk8ENCw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@oxfmt/binding-linux-s390x-gnu@0.56.0':
+    resolution: {integrity: sha512-60ZGH3LtfqlW8X6vcLdSFY4lvCQYINurttYBKaALnHCDVAUCYJ1LsUgS6p1XOzVlzEDx3yNUZvDF1Lvt59zoZw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+
+  '@oxfmt/binding-linux-x64-gnu@0.56.0':
+    resolution: {integrity: sha512-u1suj1tgJHK4ZqB7buCtdbNef2n8+d0lXTPJwLHNmtyK6p+DTpsaoDvmqhQrA56fgKYv4LuRxNtL8YooebKOew==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@oxfmt/binding-linux-x64-musl@0.56.0':
+    resolution: {integrity: sha512-aYGLvlQHt80y+qKEtfJY/Nm27G0125Lv+qyh9SJ4Cjc6lXnXjD+ndfhqQnbV24POpMi7rNRi0jvx/0d70FRpCQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@oxfmt/binding-openharmony-arm64@0.56.0':
+    resolution: {integrity: sha512-H/re/gO+7ysVc+kywHNuzY3C33EN9sQcZhg0kp1ZwOZl7y998ZE5mhnBiuGR/nYI0pqLL5xQfrHVUOJ/cIJsCA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@oxfmt/binding-win32-arm64-msvc@0.56.0':
+    resolution: {integrity: sha512-6qLNXfXmtAs8jXDvYMkxk6Wec5SUJoew+ZX1uOZmqaR7ks0EJFbAohuOCELDyJMWyVlxotVG8Xf8m74Bfq0O2w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@oxfmt/binding-win32-ia32-msvc@0.56.0':
+    resolution: {integrity: sha512-UXEXuKphAe15bsob4AswNMArCw38XSmUIs3wk1s6e6MX9OWGW/IRWU95s1hZDiVg09STy1jHgyN2qkqbu1FT0w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@oxfmt/binding-win32-x64-msvc@0.56.0':
+    resolution: {integrity: sha512-HPyNDjky+NIOuaMvHZflR+kst3YWdUOH2JUQYkf99grqZ5mEBTQM6h9iGy501Z8Xt5xMScrwHOuVCOlqDrktRw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@oxlint/binding-android-arm-eabi@1.71.0':
+    resolution: {integrity: sha512-ImGmd1njEg4FEJH03jhRnveEegtO3czCtfptvaHivKAZQIYATbVFBrrzbaYMYv0oJioTnxZAZVSyV+oL7W8S2g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [android]
+
+  '@oxlint/binding-android-arm64@1.71.0':
+    resolution: {integrity: sha512-4A5BEexBrwY1YFF8Kiq/lp/wQPRG79G3BWIE1FuWaM5MvmpYSd+7ZySVcKkHdwo0UDzdQGddp6pD9mpctMqLnw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@oxlint/binding-darwin-arm64@1.71.0':
+    resolution: {integrity: sha512-9wJA9GJulLwS2usU3CEisI/ESDO1n1z9eyTCvApMDrAkbJ1ve0mORgTMjcWWsKxkzkeZ2N/Gpra5IQE7x8tYgQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@oxlint/binding-darwin-x64@1.71.0':
+    resolution: {integrity: sha512-PlLCjS06V0PeJMAJwzjrExw1sYNW9Gch3JtNlcwwZDXGlTYDuwHNN89zYH8LTXFfgkVtsYvs2nv0FqrzyuFDzg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@oxlint/binding-freebsd-x64@1.71.0':
+    resolution: {integrity: sha512-Lhil7bWre0ncxbUoDoxfS0JzpTz17BRQKW7iwoAUY8GJ66+WwJEfYPCFJ1P0WgVZR5/O/b3Q2pENlHOjeXLOGQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@oxlint/binding-linux-arm-gnueabihf@1.71.0':
+    resolution: {integrity: sha512-Oo9/L58PYD3RC0x05d2upAPLllHytTjHQGsnC06P6Ynn7jKkp5mdImQxXdJ3+FnBaKspNpGogzgVsi6g872LiA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxlint/binding-linux-arm-musleabihf@1.71.0':
+    resolution: {integrity: sha512-mSHfyfgJrEbyIR29ejaeS50BdPk+GoNPlC1dckpDiUZbJAIel68sjSMdOt4WY0/gva+ECC7FNITQkxMJU+vSBw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxlint/binding-linux-arm64-gnu@1.71.0':
+    resolution: {integrity: sha512-n9yY4M2tiy3aij4AqtlnspzpfdpeT5JQfK2/w2d8oyp5W0FRwOb1dIeX99nORNcxGr08iD9bH8N5XFz3I2iy8w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@oxlint/binding-linux-arm64-musl@1.71.0':
+    resolution: {integrity: sha512-fJZrs5sDZtTaPIOiemRQQmo82Ezy+vOGXemPc4Ok7iVVsYsFa7SlW6Z5XN819VfsqBHRm3NJ3rTdnR8+bJYJdQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@oxlint/binding-linux-ppc64-gnu@1.71.0':
+    resolution: {integrity: sha512-cwl7VKGERIy9p+G+AvZdfy/06q0aHXaTt/mMRReC751iuNYJgqKjB7NydXSS30nBT9vtr2tunciOtrR4fD6FUA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@oxlint/binding-linux-riscv64-gnu@1.71.0':
+    resolution: {integrity: sha512-eZ8ieVXvzGi8jr7+ybQGPK2STw3mldfxZlgA2738iflfB/rzA69sE6m5rDRpQaxC7dpm745Enlh1Tod0QAk9Gg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@oxlint/binding-linux-riscv64-musl@1.71.0':
+    resolution: {integrity: sha512-puMDbQYe6+NXwfMusojoA7CXGn2b3utukmd23PQqc1E3XhVCwyZ+FueSMzDYeNgDV2dUfIVXAAKZBcFDeCL6sA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@oxlint/binding-linux-s390x-gnu@1.71.0':
+    resolution: {integrity: sha512-4NJLxBs1ujISCt3L/1FcywLs73PWtJuw+piD6feK2V6h6OS6P7xu9/sWt1DTRLibe6QCzmfZzmM/2HPORoV/Lg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+
+  '@oxlint/binding-linux-x64-gnu@1.71.0':
+    resolution: {integrity: sha512-cFDaiR8L3430qp88tfZnvFlt3KotFhR/DlbIL0nHOMMYiG/9Wy4l+6f7t8G8pTa9bd8Lt8+M0y/qjRQ/xcB74g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@oxlint/binding-linux-x64-musl@1.71.0':
+    resolution: {integrity: sha512-orfixdt76KlpNly9z0PkWBBNfwjKz+JFVLP/7wnVchlKNU9Dpt9InU/ZggeSej6fC7qwHmHNOGlhLnQXcYoGuA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@oxlint/binding-openharmony-arm64@1.71.0':
+    resolution: {integrity: sha512-9emQu2lAp6yhPB3XuI+++vR+l/o6JR1X+EpxwcumPdQXBWXEPAsquPGL7l158EqU8SebQMXTUa/S5zN98juyHw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@oxlint/binding-win32-arm64-msvc@1.71.0':
+    resolution: {integrity: sha512-bd5kI8spYwTm3BILDtGhi73zoup5dw8MlPQNT8YB3BD5UIsjNe3K9/4ctrzQMX4SZMoK5HgzVLkLJzacEXB7fA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@oxlint/binding-win32-ia32-msvc@1.71.0':
+    resolution: {integrity: sha512-W4HvOHGzVLHcrmFu+bMrJlho+/yrlX5ZNdJZqGe8MEldkQG+RHYhxxad9P4jvWAYFmIqUA5i9DQ8QsJqSU9GIw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@oxlint/binding-win32-x64-msvc@1.71.0':
+    resolution: {integrity: sha512-D2kyEIPHk/G/wiZLnwTVC/sVst+T/lKldVOjAFpgTIBUAOlry72e5OiapDbDBF4LfJLkN5ypJb/8Eu6yJzkveQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@pandacss/is-valid-prop@1.11.3':
+    resolution: {integrity: sha512-YaHK+p5DaN8AUpsRx5OqqGxaZzn8uNIdVhP+K1cjvjv3+Qa9D/75/A1dPyLmfKrSRJc8UoR9WN9fxQX0rVzhzQ==}
+    engines: {node: '>=20'}
+
+  '@polka/url@1.0.0-next.29':
+    resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==}
+
+  '@rolldown/binding-android-arm64@1.1.3':
+    resolution: {integrity: sha512-DT6Z3PhvioeHMvxo+xHc3KtqggrI7CCTXCmC2h/5zUlp5jVitv7XEy+9q5/7v8IolhlioawpMo8Kg0EEBy7J0g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.1.3':
+    resolution: {integrity: sha512-0NwgwsjM7LrsuVnXMK3koTpagBNOhloc/BNjKqZjv4V5zI5r13qx69uVhRx+o5Z0yy4Hzq+lpy7TAgUG/ocvrw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.1.3':
+    resolution: {integrity: sha512-YtiBp4disu6V560loT6PjMdiRaWmVvDNrUunAalbiFx2ggeJwxdAsgZMcoGP17uyAsTwAj5V1niksxlHnVQ1Sw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.1.3':
+    resolution: {integrity: sha512-yD3EkEdXk2LypPxnf/kSZHirarsI8gcPzc62SukhR9VJTyvV+F9Q/GxWNuCojc7sXyuVC4DxRGhdDK4X8VSsbw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.1.3':
+    resolution: {integrity: sha512-c+8vieQbsD7HNAHKIA34w0GJ9FedFFuJGD+7E6vz7Q3uqAIugL5p45fhlsj4UaAsHpcmlqugBWMhA0/j7o0sIg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.1.3':
+    resolution: {integrity: sha512-50jD0uUwLvur7Zz9LHz17kaAdTPjn5wN93hEgjvmYFRZwiR7ZJYovTd5ipyWJDAnXKvZ+wgc+/Ika6dwSF5OcA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-musl@1.1.3':
+    resolution: {integrity: sha512-BO9+oPL8K9poZJBfYPsXNtYjPE5uM3qeehT3aFcW4LITOl+iSqhp0abzjR2nWBUNjIZeKXjAEWBZ64WjNoHd6w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.1.3':
+    resolution: {integrity: sha512-f3VpLB1vQ0Eo6ecr/6cekLnvYMFF4YBFoVGkfkvPLq1bAkbAwHYQPZKoAmG6OJyTcxxoC+AvezGx/S1obNC0Mw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rolldown/binding-linux-s390x-gnu@1.1.3':
+    resolution: {integrity: sha512-AmurZ26Pqx/RI9N1gzEOCklkKXl927yjfXWUUS0O7Puh8ARM/Ob8qfrD3qnWksScdw6cSrW5PSHE9DyLu7+PtA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rolldown/binding-linux-x64-gnu@1.1.3':
+    resolution: {integrity: sha512-JJpqs8bRGITDOdbkNKnlojzBabbOHrqjSvDr0IVsZObE1lBcPjxItUEY9eWIDbxaJ3cGrXPWGfGkIxFijg/URg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@rolldown/binding-linux-x64-musl@1.1.3':
+    resolution: {integrity: sha512-rSJcdjPxzA/by/6/rYs+v+bXU7UjvnbUWz8MJb6kh6+knqB1dCrtHg0uu7C/4haqJvqdkYHQ5IGn+tCH9GLW/g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@rolldown/binding-openharmony-arm64@1.1.3':
+    resolution: {integrity: sha512-hQ3/PYkDJICgevvyNcVrihVeqq7k1Pp3VZ9lY+dauAYUJKO+auqApvANhvR1An9BhmqYKvW2Mu1F9u4DXSMLxQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-wasm32-wasi@1.1.3':
+    resolution: {integrity: sha512-Elcv/BtML9lXrV6JuKITc/grN2kYV9gjsQpW8Jfw4ioK0TOkjBjye0nnyqQNy9STNaI20lXNaQBRrD5gSgR0Yg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [wasm32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.1.3':
+    resolution: {integrity: sha512-2DrEfhluH9yhiaFApmsjsjwrSYbNcY1oFTzYSP1a535jDbV98zCFanA/96TBUd0iDFcxGmw9QRExwGCXz3U+/g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.1.3':
+    resolution: {integrity: sha512-OL4OMk7UPXOeVGGd3qo5zJyPIljf4AFgk5QAkPPS+OoLuOOozhuaQGC18MxVTnw/06q93gShAJzlwnSCY9YtqA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/plugin-babel@0.2.3':
+    resolution: {integrity: sha512-+zEk16yGlz1F9STiRr6uG9hmIXb6nprjLczV/htGptYuLoCuxb+itZ03RKCEeOhBpDDd1NU7qF6x1VLMUp62bw==}
+    engines: {node: '>=22.12.0 || ^24.0.0'}
+    peerDependencies:
+      '@babel/core': ^7.29.0 || ^8.0.0-rc.1
+      '@babel/plugin-transform-runtime': ^7.29.0 || ^8.0.0-rc.1
+      '@babel/runtime': ^7.27.0 || ^8.0.0-rc.1
+      rolldown: ^1.0.0-rc.5
+      vite: ^8.0.0
+    peerDependenciesMeta:
+      '@babel/plugin-transform-runtime':
+        optional: true
+      '@babel/runtime':
+        optional: true
+      vite:
+        optional: true
+
+  '@rolldown/pluginutils@1.0.1':
+    resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+
+  '@socket.io/component-emitter@3.1.2':
+    resolution: {integrity: sha512-9BCxFwvbGg/RsZK9tjXd8s4UcwR0MWeFQ1XEKIQVVvAGJyINdrqKMcTRyLoK8Rse1GjzLV9cwjWV1olXRWEXVA==}
+
+  '@standard-schema/spec@1.1.0':
+    resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+
+  '@swc/helpers@0.5.23':
+    resolution: {integrity: sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==}
+
+  '@tanstack/history@1.162.0':
+    resolution: {integrity: sha512-79pf/RkhteYZTRgcR4F9kbk84P2N8rugQJswxfIqovlbRiT3yI7eBE+5QorIrZaOKktsgzRlXh1l/du/xpl4iA==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/react-router@1.170.16':
+    resolution: {integrity: sha512-w6eq1IJklujs1tESazaK/FxH0+H2l8vm/QPuu1cD3oRW/ubgKneQpd7b64ti/8gUyEimzimJQZDmJr6YHfP5+g==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      react: '>=18.0.0 || >=19.0.0'
+      react-dom: '>=18.0.0 || >=19.0.0'
+
+  '@tanstack/react-store@0.9.3':
+    resolution: {integrity: sha512-y2iHd/N9OkoQbFJLUX1T9vbc2O9tjH0pQRgTcx1/Nz4IlwLvkgpuglXUx+mXt0g5ZDFrEeDnONPqkbfxXJKwRg==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@tanstack/react-virtual@3.14.3':
+    resolution: {integrity: sha512-k/cnHPVaOfn46hSbiY6n4Dzf4QjCGWSF40zR5QIIYUqPAjpA6TN7InfYmcMiDVQGP2iUn9xsRbAl8u1v3UmeVQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@tanstack/router-core@1.171.13':
+    resolution: {integrity: sha512-+NOwEj1kO/6IGmpHRIZHasYxYWpyBQGNIZAST9aNrk9Q3YlU9SgqVnl1pbLa9qAKfeNdXQIRve0RQb/0kyDeDA==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/store@0.9.3':
+    resolution: {integrity: sha512-8reSzl/qGWGGVKhBoxXPMWzATSbZLZFWhwBAFO9NAyp0TxzfBP0mIrGb8CP8KrQTmvzXlR/vFPPUrHTLBGyFyw==}
+
+  '@tanstack/virtual-core@3.17.1':
+    resolution: {integrity: sha512-VZyW2Uiml5tmBZwPGrSD3Sz73OxzljQMCmzYHsUTPEuTsERf5xwa+uWb01xEzkz3ZSYTjj8NEb/mKHvgKxyZdA==}
+
+  '@tybys/wasm-util@0.10.3':
+    resolution: {integrity: sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg==}
+
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
+  '@types/d3-color@3.1.3':
+    resolution: {integrity: sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==}
+
+  '@types/d3-drag@3.0.7':
+    resolution: {integrity: sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==}
+
+  '@types/d3-interpolate@3.0.4':
+    resolution: {integrity: sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==}
+
+  '@types/d3-selection@3.0.11':
+    resolution: {integrity: sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==}
+
+  '@types/d3-transition@3.0.9':
+    resolution: {integrity: sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==}
+
+  '@types/d3-zoom@3.0.8':
+    resolution: {integrity: sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==}
+
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
+  '@types/node@26.0.1':
+    resolution: {integrity: sha512-fc3KiUoBt6kie0N9bIW3E47vZsuaMf0PM2AaUpLCLT0s/LvX1nxAim6Fc049cNxODPpGm6qRAuUOB86SkRuPQw==}
+
+  '@types/parse-json@4.0.2':
+    resolution: {integrity: sha512-dISoDXWWQwUquiKsyZ4Ng+HX2KsPL7LyHKHQwgGFEA3IaKac4Obd+h2a/a6waisAoepJlBcx9paWqjA8/HVjCw==}
+
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react@19.2.17':
+    resolution: {integrity: sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==}
+
+  '@types/use-sync-external-store@1.5.0':
+    resolution: {integrity: sha512-5dyB8nLC/qogMrlCizZnYWQTA4lnb/v+It+sqNl5YnSRAPMlIqY/X0Xn+gZw8vOL+TgTTr28VEbn3uf8fUtAkw==}
+
+  '@vitejs/plugin-react@6.0.3':
+    resolution: {integrity: sha512-vmFvco5/QuC2f9Oj+wTk0+9XeDFkHxSamwZKYc7MxYwKICfvUvlMhqKI0VuICPltGqh1neqBKDvO4kes1ya8vg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      '@rolldown/plugin-babel': ^0.1.7 || ^0.2.0
+      babel-plugin-react-compiler: ^1.0.0
+      vite: ^8.0.0
+    peerDependenciesMeta:
+      '@rolldown/plugin-babel':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+
+  '@vitest/browser-playwright@4.1.9':
+    resolution: {integrity: sha512-Bq1rOGf9waevzG3EOkO/dene6bvKTUsZMVg8S1i+WH3JcMjuXEjiahP9rAqZRELUqjBySOJsvvSWqK/B3wjKQw==}
+    peerDependencies:
+      playwright: '*'
+      vitest: 4.1.9
+
+  '@vitest/browser@4.1.9':
+    resolution: {integrity: sha512-j1BKtWmPcqpMhmx/L9EPLgAJpCb0zKfwoWLmqBbxaogCXHjOwHFSEoHCBfnGtx93xKQwilZ26m+UOsHqHMkRNg==}
+    peerDependencies:
+      vitest: 4.1.9
+
+  '@vitest/expect@4.1.9':
+    resolution: {integrity: sha512-vl/rYsUKcBr3SnQn166+XR5ZQcgMx3DQhFWdfli/cWpLnLUmbxZvyrJZotLFUryib+LtArYMSTJ5RbQ57ZqrlA==}
+
+  '@vitest/mocker@4.1.9':
+    resolution: {integrity: sha512-EVkXzBjrPGM+cK8/ANWgBrkUCfJfb38/EfTSO8h7pWvKkyPkpWxvR7BkD2MyItMF62C97zAEoqdpUixwR/e+Rw==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/pretty-format@4.1.9':
+    resolution: {integrity: sha512-s0iufns3iIFitdgm+YR7g1whCAaGtXz459VS9/PqyKDEEFgYIhsHOQmXgIgDuYCt7DeQmiZT0Qe2OA2p4ZPu5A==}
+
+  '@vitest/runner@4.1.9':
+    resolution: {integrity: sha512-KXLMDtc7oe70+3mJfGrPUWPesswH+3sTxAMAMl8DG7I8IUQT4XW718dY5ID3vPUcmlu27CcKfY4P3h3I29SLJg==}
+
+  '@vitest/snapshot@4.1.9':
+    resolution: {integrity: sha512-Jc7RKGNBo8Z28WYIm0Niej4xdSPByRf6mU58VpHQkd6Zh05rlnA+twjbK5HyeIGHxrzsc3mJgS43uM0CZKzaIA==}
+
+  '@vitest/spy@4.1.9':
+    resolution: {integrity: sha512-fHpsS6mIi+PiEW+vcRVOMkX1oSaPKne3VOclSFICPcGOmfKgXPU5iAah+wcNcj2xPrCCmfq99IDGf+EojhhvhA==}
+
+  '@vitest/utils@4.1.9':
+    resolution: {integrity: sha512-A51o8ymO5PpqlWNnBP9ZHPXDIpuMtTLlGSjN7la4US+LJzoUMyhwjA5QXlm39JexgwHKW4Xjs8Z2d3dLCXOeuA==}
+
+  '@xyflow/react@12.11.1':
+    resolution: {integrity: sha512-L+zBoLGSXham0MnlY8QqjfR7/C5JNw0zxkaey5aZ5XmCgJBAdH4+WRIu8CR40d3l/BdU635V6YbhBK1jMo8/6Q==}
+    peerDependencies:
+      '@types/react': '>=17'
+      '@types/react-dom': '>=17'
+      react: '>=17'
+      react-dom: '>=17'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@xyflow/system@0.0.78':
+    resolution: {integrity: sha512-lY0z2qP33fUhTva9Vaxrk0lqZta2pkbxB1trHAx1omnJqRtPvDlAQYV2r5fhS6AdpkulYmbNW0svy+A4/t4B/g==}
+
+  '@zag-js/accordion@1.41.2':
+    resolution: {integrity: sha512-7G//V7svGGT8k5avw7bbQvbRC0Q/9QtX51b4iyAB1alR9E5mFd6Ch8q4njwcXClMQ7xePS3jUfVnzVGiRInEiQ==}
+
+  '@zag-js/anatomy@1.41.2':
+    resolution: {integrity: sha512-Fm9hqdrvaCzCsdcf19G8WZxYtHElKltkGHdhqMEt4XU+ULTr1DK7KbOtDDv9J27CuzqSLALUz5QfRjPftoKHwg==}
+
+  '@zag-js/angle-slider@1.41.2':
+    resolution: {integrity: sha512-+7bZHAZx0MEbjTMr2tD+meFJ0EJwFfUEcTqmdLzFGr/ySAMCWlcadDBz+ZmrSn03aKLps8FxliVLzsFJNgUqIQ==}
+
+  '@zag-js/aria-hidden@1.41.2':
+    resolution: {integrity: sha512-qEcYmwlQr3qjA0T/IZ5a/o7fRUxfQ14tXjAFhR3GXCtxBKaqS+wnq/LN09Xw4bin3QWTINU+Z0oXFs9spWtNwA==}
+
+  '@zag-js/async-list@1.41.2':
+    resolution: {integrity: sha512-NZZEIGFdeDp2uHjsLVegLAGJOYGwI9HPJI1V2c/P1TQmfmrfWyWELAvnnW4kWYVUKYD9TxKQkm6LvqpHrQzgfQ==}
+
+  '@zag-js/auto-resize@1.41.2':
+    resolution: {integrity: sha512-CYq+JQ1TTkEiK7OcNcMTS0f4wFvtmManvUltije5o50gDQ7vFYA81oQh4A9pAB1keUi9Zv06CNefFARaTcne5w==}
+
+  '@zag-js/avatar@1.41.2':
+    resolution: {integrity: sha512-+4K0tRtIQysMGuERh5JRmn46uq7gJ6IjJd5DKj74VBtVVY8T6HGk0D0DZxmOIgADHP1qSvowLDoOX8kUyBHarQ==}
+
+  '@zag-js/carousel@1.41.2':
+    resolution: {integrity: sha512-H6sDxyWIzkvtHN4M/BYvFy7pi8j+kLEtfPZvgNl2+gRnfAHVK9/XqpoUsjw1DAo5Fh25pPuaTnh52Kml9OK0iA==}
+
+  '@zag-js/cascade-select@1.41.2':
+    resolution: {integrity: sha512-dBByZmIAJU/B+YIAzczng05lCJXEwEm4df6GmUZtioKHZdeN+WEKUP4qzFDFZdytXympGfJCIBvtgf87gACYVQ==}
+
+  '@zag-js/checkbox@1.41.2':
+    resolution: {integrity: sha512-aQ5dZWHUHRIw4cbLtzrR+dc8M0N6wSiiCml/zbU3ciHOTBXSrs2rKnp/L99xhi97Lj2uCEhpIZ704Ou/MjGuCg==}
+
+  '@zag-js/clipboard@1.41.2':
+    resolution: {integrity: sha512-FM+PNGEeY+YpF1dVr9d8kg3DQM66LRnkR4Mva1oprqnrCXTYWj+k7uig893ubSG2xw1GO5b/WJd27kSmNoKnmw==}
+
+  '@zag-js/collapsible@1.41.2':
+    resolution: {integrity: sha512-uMIp4rqd3iI6VFPMAOcbu9dh9WV4l85nNPYQiBtMKRHgbkfaZdfzF+E+NX3KquIeHW6JiBFUiIyCU0Sf2Cscdw==}
+
+  '@zag-js/collection@1.41.2':
+    resolution: {integrity: sha512-ZZWuvfPZI8ccWd4aLpuU47k1jSc9eO+F3FM3iBJuvgegCH6g3+HDEwGN6wdePHnYfv7zyIKCGKr816zXcIWQbw==}
+
+  '@zag-js/color-picker@1.41.2':
+    resolution: {integrity: sha512-UynyJ/bTBeSlq6ziHr9GVrFycDjVxfLFIb8Aivu/XvihrAAvkhXUxwy+1ax+hj7peGlTY590xoQAvQixV+McBA==}
+
+  '@zag-js/color-utils@1.41.2':
+    resolution: {integrity: sha512-Lsi5c2ztGZqud0oeDtAn3xFhgrYMaeaz1zi4p+mr0zXOuQNuZzfsrJ0stQ45s8L/xT8UJtGhYyEVy1+xjE4ARA==}
+
+  '@zag-js/combobox@1.41.2':
+    resolution: {integrity: sha512-V9jQteyQHs8ZNQx/FcA98P1NVZas/yjiW1V7s4L+h8MnRS3AK97+FAHAT83KCiZ34/vkpLF6ZEHI2zkcQpNXcg==}
+
+  '@zag-js/core@1.41.2':
+    resolution: {integrity: sha512-xXTN3zKwOtMI4+5dG2cG+T1B4WR3X9alXiYaPJKaGd4N2eYRj9JEPte3Hv9gtFm+RM0b9VIwksHEg25rqE4apw==}
+
+  '@zag-js/date-input@1.41.2':
+    resolution: {integrity: sha512-J8PdpEpM9TBxZBEE8/Nxi39LNJOZY7lilTbgcDABR5uiviZUk5++5GSdUTspcjFUIXx5SvqmdCk2RF7hsUEHVQ==}
+    peerDependencies:
+      '@internationalized/date': '>=3.0.0'
+
+  '@zag-js/date-picker@1.41.2':
+    resolution: {integrity: sha512-j9LaznCV4QCfrq/y/mNAN9XgIRFFg+414TxGT4TK8mfWouIaFvxEoKdGP0l/LL4DFv1NRDaRdSBBcw3eXtMVnA==}
+    peerDependencies:
+      '@internationalized/date': '>=3.0.0'
+
+  '@zag-js/date-utils@1.41.2':
+    resolution: {integrity: sha512-jdcWLa5fYLTsvGWJkx4v/9Hzqf6UHdvJDeP6NxHpwoEmzYy7+AghYKBNSnRrJIBCQJgl1vM9OkpMvYrLNHr9jw==}
+    peerDependencies:
+      '@internationalized/date': '>=3.0.0'
+
+  '@zag-js/dialog@1.41.2':
+    resolution: {integrity: sha512-t1N72snpFGiKj7cg2PivPdsy+X1YdgXPv7bzovpqjMLy0kN+gYTPoV1Iy/hQA+g021dz9XGgXzkDuU45sJqsFA==}
+
+  '@zag-js/dismissable@1.41.2':
+    resolution: {integrity: sha512-hO/tFhRZ7S+LOOljGOQJIubbc3MXg41+iWR1yUXKl76cAenbxaCit1LZmUCwQPvRN0GndK6bDQo5ETjHZz/k7A==}
+
+  '@zag-js/dom-query@1.41.2':
+    resolution: {integrity: sha512-+eBk1nlJA312mNmY/GSThLRwcCRqMIL+A1pLsWvTlQLQjmH1/UxoAuv6l2yvRCT33XmC8FBlBIKnXhOCpDvIZA==}
+
+  '@zag-js/drawer@1.41.2':
+    resolution: {integrity: sha512-aJql6L0cfHd1wXbemfLcNnjqTA/CbwVgQdWEVn5Qci6zhy4UJXPQeBBfxfgPgEOAbW60gL/gaaXG3d9Vx6+6oA==}
+
+  '@zag-js/editable@1.41.2':
+    resolution: {integrity: sha512-loTM1lrHBBqYfR8SJZrYayVdWHMpXCLVir+aDTQ8/d4bb/Gfl/L8CJNs3BRj3yt9zvLoWTLO+4LOY3hLyQSR2w==}
+
+  '@zag-js/file-upload@1.41.2':
+    resolution: {integrity: sha512-WFwIaKvHpCUjyYMvp42VoydT1WIP5DhDlpmG/nrF4i0ro7pLGb1A4dvyBrAfGcozCB88yR1y1iZKPDY1I9/uUw==}
+
+  '@zag-js/file-utils@1.41.2':
+    resolution: {integrity: sha512-Ih+8ULbId0M+CFR4IsqG5y/0VLCk2l+1rgPH+21L40dlSB6z6qKSP2tG7W69Cj2/3vryZsn67ibn26iCPG/vOw==}
+
+  '@zag-js/floating-panel@1.41.2':
+    resolution: {integrity: sha512-nJP3oZ4YrJh+7H5YdwNccSzPGXFqjQN1ujZ/xGDhegjz4XtL48QMFnAasxlRI8VGjse9Tj8VXlQZxXPrASGzlA==}
+
+  '@zag-js/focus-trap@1.41.2':
+    resolution: {integrity: sha512-3QTtGUjFU2OLbyrDlyoYWvKZecCmtn/+bsfsHW159jJHiEGHVYK6CY8AI1ePsMk9gVay48bXh008j+lVli7gAw==}
+
+  '@zag-js/focus-visible@1.41.2':
+    resolution: {integrity: sha512-oRjwtgafUdGVwLJUN6mKsnBQbez/CHYAPkPg1FxOnr5GFpEpr8oMTOZJ3wdPM2U1ynS9QnUUu/sXc3KQv/jX0Q==}
+
+  '@zag-js/highlight-word@1.41.2':
+    resolution: {integrity: sha512-95zcZKqNrL7JlqAckfzHa+LRbnfoz1lj6skUhq/uHSnni1vH6+8fNWT8ruo9G7vpGopbyRmmcie5p41SbAwQjQ==}
+
+  '@zag-js/hover-card@1.41.2':
+    resolution: {integrity: sha512-Xn9RVzgTkKaVzyJTDdBJiXmCleNi1/hmW8z73tC0vOiQvSSvPejg/JkzqTOLFODvQHK3NOw54QHZvmjYp9Mubw==}
+
+  '@zag-js/i18n-utils@1.41.2':
+    resolution: {integrity: sha512-f1xqaEY79awBxgUyjFso0UEpIoEHZq+zRvB0nUVFHJRW7Ds/QhaFHKSRnf2QBTlP/ObvCT225R+piNAAc17Aaw==}
+
+  '@zag-js/image-cropper@1.41.2':
+    resolution: {integrity: sha512-750aT4U+J/TJw/Z1QVoLU9JG0luCtf9CyvShtJFIxeS+i25aUoBI9pOKgSFABsOutIqNJTPq4gYpqtuxFjSxRw==}
+
+  '@zag-js/interact-outside@1.41.2':
+    resolution: {integrity: sha512-dM4Fn9iyqQeqkCMRYZP+bAgWEPKRVQRqMmcPsN0OXBhhFKC31Em15LTIZXaOtVKAjH+iwx+UvSYFRiWwEjkOEA==}
+
+  '@zag-js/json-tree-utils@1.41.2':
+    resolution: {integrity: sha512-gNaOzsbCwmTd2HM3/u0xQdWX5UDBfl8tCXFavzbamkFH0iYQOXJb7cqUXBVuI4KScIbHPCKwrzZjqA5Sg9qzAQ==}
+
+  '@zag-js/listbox@1.41.2':
+    resolution: {integrity: sha512-iDGrZleP3ui2Q6Jgmr9RYlbd7njdJHs8Qb3IJrSIZBIeYyYmFvVUfAFjk0g/z/amjTx6uYxRASWSPy/RETd4ug==}
+
+  '@zag-js/live-region@1.41.2':
+    resolution: {integrity: sha512-7ubIW5AQt1wx9S/gFN+rU4TyvuFWJrL/DhnDWPNlH5g3luDVHSNeYGeeqf4d4tkcibtpYZa0pg9CbXxRxrfwVA==}
+
+  '@zag-js/marquee@1.41.2':
+    resolution: {integrity: sha512-cT77aMhrtAK3oe2O6+X3TLtQs8wupdPUtZgHMWVxCcQOwagrk7RUBEQwU3Cx7cTswpBdTKSuDYgUggfgCs96wg==}
+
+  '@zag-js/menu@1.41.2':
+    resolution: {integrity: sha512-wwix8hcAUSi0scpWXCiDppfdZV01Za8nN0gqLt9GdhCiVSlr0rs9pK1ROgPKJTyc43UZfyFPqtTWVHvEHMM70w==}
+
+  '@zag-js/navigation-menu@1.41.2':
+    resolution: {integrity: sha512-aROB9CHzskZpnoFuGFkp7dbkZdsXvp2nxQgsgld02I1sDqiwcQd+YMdB0/6Ik0oz6X8I70RKdUuQM9WQFQfDnA==}
+
+  '@zag-js/number-input@1.41.2':
+    resolution: {integrity: sha512-QoQWCiVHO+ciUbq8uL8Kxhtk4o3UpwzYpJkfsOfitzsZoYpPc7V/A6+n5yABV2SOwpqBODwNASZdxiEa60kfow==}
+
+  '@zag-js/pagination@1.41.2':
+    resolution: {integrity: sha512-vZTxz4DrIDfedMcTjDeEkOc1iXD9wkP8eKuEcDieHOodnjSnNNwtmoFw5DCWv+yEa/TByIamXBZ8ZxHY144JgA==}
+
+  '@zag-js/password-input@1.41.2':
+    resolution: {integrity: sha512-OWKFl0S12Qnlf4R4WbMCJ/YU0kGfezm5tP0UiyubMO/Fixv6H0twDFaJSPg2F6POv5uomCcGubc1H7gO+fIhsQ==}
+
+  '@zag-js/pin-input@1.41.2':
+    resolution: {integrity: sha512-Wrn3YDbmWL3qvUIzN4QyLO7PzEhunX7z8DwBpmrK04p7HxR9pniTLVIPk27xk2MzyAPYcl4mwd9/Mc88tBxHsg==}
+
+  '@zag-js/popover@1.41.2':
+    resolution: {integrity: sha512-h/LlVMIERM+NWzYV0ZHURlJuaqkT8XxwyEV96XfVzjknDRFNoPSl5IttVYtoaPoUqC0p/Y4oTSiee4mUZKOLHw==}
+
+  '@zag-js/popper@1.41.2':
+    resolution: {integrity: sha512-Iz4D5YAIiIPn4IHGjhX3QatR/RyGaDt43lBSZv0RYcPQYtFg9sUuek3wizjW9qXgdvItevvNMqRdpl7f3es09g==}
+
+  '@zag-js/presence@1.41.2':
+    resolution: {integrity: sha512-OhOLPAf/DYPmgoEntrlrf3LOrkwA+Y0J3K03NXHXPnkRB7h8jyIbHqzHS0jRTb1pvsO2P/yowRyoYtptY2Zmog==}
+
+  '@zag-js/progress@1.41.2':
+    resolution: {integrity: sha512-SnzrqN+Z568NoO4rrgjrIc/S4EXMEne5CDgWwt2kQ8yq9VysdH8TtHAjyciFRIio7cdgEZNHKw9jSccpMWgRwA==}
+
+  '@zag-js/qr-code@1.41.2':
+    resolution: {integrity: sha512-+JLswCNnzf58aQTaX0SMUA9wRC8Hb/a/ZveJIXTz6853Siemay2HqOqB2WQIeF33HNldUFD/a4+4Q8ugg93ubA==}
+
+  '@zag-js/radio-group@1.41.2':
+    resolution: {integrity: sha512-EZjos61jKHZlNw8ez80vG2T9gUwpooxcVpYOKS2hyhuEXn3wEoefS5v1WFbmpoA/8TUpUQnYxisAeNuQfEQCuQ==}
+
+  '@zag-js/rating-group@1.41.2':
+    resolution: {integrity: sha512-SbJP4HiK5XRy/oC3xRowjZOCThq1n/QA2Z/XAkvKLJArVQCYjrH3MoWwWvMVNfNC5+ZJluborR2AGF7tlVLzxA==}
+
+  '@zag-js/react@1.41.2':
+    resolution: {integrity: sha512-5Bx7mQAron4LFWI8Hhs/uw5kwQ19s2Tn30HhctozLqmCu4nnJSTSh7GRvX+uwRZnztGXBXoOrgBWIepU4RXFGg==}
+    peerDependencies:
+      react: '>=18.0.0'
+      react-dom: '>=18.0.0'
+
+  '@zag-js/rect-utils@1.41.2':
+    resolution: {integrity: sha512-GWBTamaMLMG1p7Fe6V0dsXeTEmk+tqG3ciovzmjxURCJ3Yq2EkAMRhS0v5DG0oo+PyrPEIzEWukGBQkh/XRgYQ==}
+
+  '@zag-js/remove-scroll@1.41.2':
+    resolution: {integrity: sha512-ieIrOgPKlCikAGEBIboQJoU7oxrL5BEY670tDOu7Eg7rNOdAwGXLEKPX2A/q+lREhOiVYjx0D3//vHTvdte80Q==}
+
+  '@zag-js/scroll-area@1.41.2':
+    resolution: {integrity: sha512-hJFAwfIFuS7XmNsS3nB5rPm9OWXfB4d98sID7fjurcaZtDH5LqFriqfXhceNvs7rz7K4f/u8rufXrb6tcvATIA==}
+
+  '@zag-js/scroll-snap@1.41.2':
+    resolution: {integrity: sha512-+70Al6LSASyEZtFyyffUJlDbE88KgYJDud05z8oZTqyEOLlTqnlSNkXq/P3siO7r3sNykg9H+TmAKn+/dVSKuw==}
+
+  '@zag-js/select@1.41.2':
+    resolution: {integrity: sha512-3wGaKABILexoNBJ1bJiHqLLTctR/VMZaNA4cyKiqZeBEWtAkdMhgyY2xKobrP6KtUTqAeUFNVSTu4yCDrAQnUw==}
+
+  '@zag-js/signature-pad@1.41.2':
+    resolution: {integrity: sha512-iNrOxY4gtqhsZdXYvlhF7s+LiOvwV7/kBpNnq8tJ1oYhgTs8wvKtJHrP86/CR05irEXQTaLfmeAJZuBEys9iRA==}
+
+  '@zag-js/slider@1.41.2':
+    resolution: {integrity: sha512-mKK2BwoDbIGxAdkdKkPZJA1SHtEQt3lS9hJ6WghefYU2vyd0BXoIKvcDV3xJOzly5LXYhH5cJITn6JtGK8353A==}
+
+  '@zag-js/splitter@1.41.2':
+    resolution: {integrity: sha512-Ubp4hkmzvVysU31jCINYbBXVqruu7rEPGqugWMzeXC5Hwda648aHpbg4Jix/wRtaGLjsyh6KOVEwAmoJU9NwhQ==}
+
+  '@zag-js/steps@1.41.2':
+    resolution: {integrity: sha512-m0t2r8+FWwa2b2aU5JiNrHVdYHyNZYHK0G3Tq9lCOSQoDeoJIkyta+sIVehLVSY+0Ba9kOlkRUmYLbsnfXaW+Q==}
+
+  '@zag-js/store@1.41.2':
+    resolution: {integrity: sha512-dVZF7E1ezXzynrKhMH3rfSr2rBbCfvTjvXbXz7//1PNULuq58UU5dG93V+9l834npCZxI2+PrpY45wZLJPTsIA==}
+
+  '@zag-js/switch@1.41.2':
+    resolution: {integrity: sha512-qHbQK95UUHN0tj+bf9LLphLcMo/uTg2Pvs0c1Gs03Zh4g3NtHf0uYIhMZKYlCH0hNVlKrmdzLKWgeoDxv9gySw==}
+
+  '@zag-js/tabs@1.41.2':
+    resolution: {integrity: sha512-7YVj2mCcxRbn1wMXP9anaTOVf+J0fa5uaPScr8e4+e2xc+/1WKzqN6V8IDeKS5wV/xzi1r3Ny307sX7Xz4ZJVQ==}
+
+  '@zag-js/tags-input@1.41.2':
+    resolution: {integrity: sha512-aIPEndSO+9LHxyoXLUr0Uttxw2cYMyDuii5w50wn/N7lFJD49U3Sj+6XaB/oJSbDAwn10WrsRDtb7Gs2kmU+Qw==}
+
+  '@zag-js/timer@1.41.2':
+    resolution: {integrity: sha512-PRYLWaip0+1FeVGEMNk5wMGAAIYgBIWwulZ4U5I+2Ayjohzp2NUAfwJ3sqoYvRrfjNYUNAPdU4eGu1zetC+oVQ==}
+
+  '@zag-js/toast@1.41.2':
+    resolution: {integrity: sha512-+F3PsAo6EIz4rh73IOMCb/+FOUp7e3VjUY2q5sdU4IbfOzJBIbVSJxn0PQmHkuxkzWdCom0Lv0qSPFg/UTplnQ==}
+
+  '@zag-js/toggle-group@1.41.2':
+    resolution: {integrity: sha512-C6wn3A89h24hTs0BN9ryEuKatfR493u7QqxS06TeK9oI/KZBvm5Rwm8FPHSUJvsUTkAkow4PsXC0Ra19duzEdQ==}
+
+  '@zag-js/toggle@1.41.2':
+    resolution: {integrity: sha512-EFB9pb3pEtwXt7RSivVLWXV64dKUF8gsn75tt8TbYBgfy+zW85MsRLu8U48TXZN5teQWAKKNujr9bxQsW/CWvQ==}
+
+  '@zag-js/tooltip@1.41.2':
+    resolution: {integrity: sha512-68okWJCFXfW8r0h97kEcU2yKPkq6e0S6QkiYh09ifMXoYjrQw/shPol8PgrS1poqKJigUWtsKm+bw73abhMn3w==}
+
+  '@zag-js/tour@1.41.2':
+    resolution: {integrity: sha512-Q7UsvuHYYBo1Cs4b4OS0e/D8lxd2GpSRII93s5BQPi5HTcBjaWhVysAykmCFbat6Z56z0NBmFHNdhZ8oVPls1A==}
+
+  '@zag-js/tree-view@1.41.2':
+    resolution: {integrity: sha512-QNi0VpV+RyzF4NP72+kSleUpauF9SMAzOAe59nxvs8jAUHqV5diDCInnbQos4+cyFDXFzGq3lElot26A1yI+7Q==}
+
+  '@zag-js/types@1.41.2':
+    resolution: {integrity: sha512-L6CNvK06lIVpy0X8eG3kbDIx8Uuv+3KHElxXYSzRXSJ7/OLCv1sTRgEvnxNtdIWOrksGgxF4JtT7PXtoClGqNQ==}
+
+  '@zag-js/utils@1.41.2':
+    resolution: {integrity: sha512-Yj8FSrR7vGA6ahUhjrThfHAF+PM2Y1Yv2lkXkqZZd60mPBhixcot1+SHOfEMV63JimQcWrmQ8QbeYYMmF+ZpLQ==}
+
+  ag-psd@31.0.1:
+    resolution: {integrity: sha512-/byWVGIrKv0Jqq3lleaRji2QdrCsAhbG4Ansc9nWkH1ghOBbujnhdlRXMfK2A750mInXbPLsgpHhrtfq9lLWkA==}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
+
+  babel-plugin-macros@3.1.0:
+    resolution: {integrity: sha512-Cg7TFGpIr01vOQNODXOOaGz2NpCU5gl8x1qJFbb6hbZxR7XrcE2vtbAsTAbJ7/xwJtUuJEw8K8Zr/AE0LHlesg==}
+    engines: {node: '>=10', npm: '>=6'}
+
+  babel-plugin-react-compiler@1.0.0:
+    resolution: {integrity: sha512-Ixm8tFfoKKIPYdCCKYTsqv+Fd4IJ0DQqMyEimo+pxUOMUR9cVPlwTrFt9Avu+3cb6Zp3mAzl+t1MrG2fxxKsxw==}
+
+  base64-js@1.5.1:
+    resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
+
+  baseline-browser-mapping@2.10.40:
+    resolution: {integrity: sha512-BSSLZ9/Cjjv7Gtj5B68ZzXcXUg8iOf3fme+FCuh8rC/Go+Kmh8cox7M3A8dolou16s64QjLPOSdngh7GxXvkSw==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  browserslist@4.28.4:
+    resolution: {integrity: sha512-MTc8i/x9jBQd1iMw2CFGS+rwMa07eYjLR0CCTLDACl9xhxy+nIs3KeML/biicXtk9JrZ6dnnTatmc7ErPXIxqw==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
+  callsites@3.1.0:
+    resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
+    engines: {node: '>=6'}
+
+  caniuse-lite@1.0.30001799:
+    resolution: {integrity: sha512-hG1bReV+OUU+MOqK4t/ZWI0tZOyz3rqS9XuhOUz1cIcbwBKjOyJEJuw9ER5JuNyqxNk8u/JUVbGibBOL1yrjFw==}
+
+  chai@6.2.2:
+    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
+    engines: {node: '>=18'}
+
+  classcat@5.0.5:
+    resolution: {integrity: sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==}
+
+  convert-source-map@1.9.0:
+    resolution: {integrity: sha512-ASFBup0Mz1uyiIjANan1jzLQami9z1PoYSZCiiYW2FczPbenXc45FZdBZLzOT+r6+iciuEModtmCti+hjaAk0A==}
+
+  convert-source-map@2.0.0:
+    resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
+
+  cookie-es@3.1.1:
+    resolution: {integrity: sha512-UaXxwISYJPTr9hwQxMFYZ7kNhSXboMXP+Z3TRX6f1/NyaGPfuNUZOWP1pUEb75B2HjfklIYLVRfWiFZJyC6Npg==}
+
+  cosmiconfig@7.1.0:
+    resolution: {integrity: sha512-AdmX6xUzdNASswsFtmwSt7Vj8po9IuqXm0UXz7QKPuEUmPB4XyjGfaAr2PSuELMwkRMVH1EpIkX5bTZGRB3eCA==}
+    engines: {node: '>=10'}
+
+  cross-fetch@4.1.0:
+    resolution: {integrity: sha512-uKm5PU+MHTootlWEY+mZ4vvXoCn4fLQxT9dSc1sXVMSFkINTJVN8cAQROpwcKm8bJ/c7rgZVIBWzH5T78sNZZw==}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  d3-color@3.1.0:
+    resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
+    engines: {node: '>=12'}
+
+  d3-dispatch@3.0.1:
+    resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
+    engines: {node: '>=12'}
+
+  d3-drag@3.0.0:
+    resolution: {integrity: sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==}
+    engines: {node: '>=12'}
+
+  d3-ease@3.0.1:
+    resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
+    engines: {node: '>=12'}
+
+  d3-interpolate@3.0.1:
+    resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
+    engines: {node: '>=12'}
+
+  d3-selection@3.0.0:
+    resolution: {integrity: sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==}
+    engines: {node: '>=12'}
+
+  d3-timer@3.0.1:
+    resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
+    engines: {node: '>=12'}
+
+  d3-transition@3.0.1:
+    resolution: {integrity: sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      d3-selection: 2 - 3
+
+  d3-zoom@3.0.0:
+    resolution: {integrity: sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==}
+    engines: {node: '>=12'}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  electron-to-chromium@1.5.379:
+    resolution: {integrity: sha512-v/qV5aV5EUA2pGilzUCq5/eyOloZAqDZBu9UMBIzgPpLlprjSR6zswsWBTv0KpqxLGUAZEwhO95ZCt7srymNVA==}
+
+  engine.io-client@6.6.6:
+    resolution: {integrity: sha512-iY6QdftLQ9pyiPoX082bpf/u1UewnOaJrtJIF9T0++QB34lZrj0uP+Q/bj8AlUsAxqhnkTV2BS8SBZSxOmoV5Q==}
+
+  engine.io-parser@5.2.3:
+    resolution: {integrity: sha512-HqD3yTBfnBxIrbnM1DoD6Pcq8NECnh8d4As1Qgh0z5Gg3jRRIqijury0CL3ghu/edArpUYiYqQiDUQBIs4np3Q==}
+    engines: {node: '>=10.0.0'}
+
+  error-ex@1.3.4:
+    resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
+  es-module-lexer@2.1.0:
+    resolution: {integrity: sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==}
+
+  esbuild@0.27.7:
+    resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
+  escape-string-regexp@4.0.0:
+    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
+    engines: {node: '>=10'}
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
+  expect-type@1.4.0:
+    resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
+    engines: {node: '>=12.0.0'}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  find-root@1.1.0:
+    resolution: {integrity: sha512-NKfW6bec6GfKc0SGx1e07QZY9PE99u0Bft/0rzSD5k3sO/vwkVUpDUKVm5Gpp5Ue3YfShPFTX2070tDs5kB9Ng==}
+
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+
+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
+  hasown@2.0.4:
+    resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==}
+    engines: {node: '>= 0.4'}
+
+  hoist-non-react-statics@3.3.2:
+    resolution: {integrity: sha512-/gGivxi8JPKWNm/W0jSmzcMPpfpPLc3dY/6GxhX2hQ9iGj3aDfklV4ET7NjKpSinLpJ5vafa9iiGIEZg10SfBw==}
+
+  html-parse-stringify@3.0.1:
+    resolution: {integrity: sha512-KknJ50kTInJ7qIScF3jeaFRpMpE8/lfiTdzf/twXyPBLAGrLRTmkz3AdTnKeh40X8k9L2fdYwEp/42WGXIRGcg==}
+
+  i18next-http-backend@3.0.6:
+    resolution: {integrity: sha512-mBOqy8993jtqAoj6XaI1XeC/8/9v6EPS+681ziegrPvTB0DoaCY7PpTS0SpY56qLMoS4OI1TZEM2Zf59zNh05w==}
+
+  i18next@25.10.10:
+    resolution: {integrity: sha512-cqUW2Z3EkRx7NqSyywjkgCLK7KLCL6IFVFcONG7nVYIJ3ekZ1/N5jUsihHV6Bq37NfhgtczxJcxduELtjTwkuQ==}
+    peerDependencies:
+      typescript: ^5 || ^6
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  import-fresh@3.3.1:
+    resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==}
+    engines: {node: '>=6'}
+
+  is-arrayish@0.2.1:
+    resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==}
+
+  is-core-module@2.16.2:
+    resolution: {integrity: sha512-evOr8xfXKxE6qSR0hSXL2r3sd7ALj8+7jQEUvPYcm5sgZFdJ+AYzT6yNmJenvIYQBgIGwfwz08sL8zoL7yq2BA==}
+    engines: {node: '>= 0.4'}
+
+  isbot@5.1.44:
+    resolution: {integrity: sha512-PGEHtwMnKbZpeSEXW2Utx+/JWed7dp6DiH0WWg33vGSDA7RUvpUeJSVlLrVkQ1RCpvDOUc/eH9ql7VsdbBZ8pA==}
+    engines: {node: '>=18'}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  json-parse-even-better-errors@2.3.1:
+    resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==}
+
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
+  lines-and-columns@1.2.4:
+    resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
+
+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
+  lucide-react@1.21.0:
+    resolution: {integrity: sha512-reEZMXq8Qdd5jg5XYkQ5TR1fB/GiQ7ih4vcrthYDtgjSDwh0i6/YLiGjsWsIwgN49gpAnd4J2elSNzncMEEUUQ==}
+    peerDependencies:
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  mrmime@2.0.1:
+    resolution: {integrity: sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==}
+    engines: {node: '>=10'}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  nanoid@3.3.15:
+    resolution: {integrity: sha512-y7Wygv/7mEOvxTuEQDB8StXdMRBWf1kR/tlhAzBRUFkB2jfcLOAxO/SHmOO2zgz1pVgK29/kyupn059/bCHdjA==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+
+  node-releases@2.0.50:
+    resolution: {integrity: sha512-J6l92tKHX6w8Jy5nO1Vuc01NoIiRGi/d6qBKVxh+IQ8Cr3b6HbVNfKiF8ZpFKufTwpwxMmce2W3iQZ861ZRyTg==}
+    engines: {node: '>=18'}
+
+  obug@2.1.3:
+    resolution: {integrity: sha512-9miFgM2OFba7hB+pRgvtV84pYTBaoTHohvmIgiRt6dRIzbwEOIaNaP+dIlGs2fNFoB0SeISs0Jz5WFVRid6Xyg==}
+    engines: {node: '>=12.20.0'}
+
+  oxfmt@0.56.0:
+    resolution: {integrity: sha512-9Dv0wV3zKiyvhjD7bRKaInKmHQ1sPx3RGOjQkGFJbbdQ16576yf8qhMSO9Q9cvHcs+1NpBsRTkuDDYFFPTJ6gw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      svelte: ^5.0.0
+      vite-plus: '*'
+    peerDependenciesMeta:
+      svelte:
+        optional: true
+      vite-plus:
+        optional: true
+
+  oxlint@1.71.0:
+    resolution: {integrity: sha512-U1m1X+C0vDj7DC1e13IoZULzEcPczE7UOMTs8VlZGHUEIUaSTZKo5qkPsQEfzpgnQ29Pea/w3Xntk62UCecxZw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      oxlint-tsgolint: '>=0.22.1'
+      vite-plus: '*'
+    peerDependenciesMeta:
+      oxlint-tsgolint:
+        optional: true
+      vite-plus:
+        optional: true
+
+  pako@2.1.0:
+    resolution: {integrity: sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug==}
+
+  parent-module@1.0.1:
+    resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
+    engines: {node: '>=6'}
+
+  parse-json@5.2.0:
+    resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
+    engines: {node: '>=8'}
+
+  path-parse@1.0.7:
+    resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==}
+
+  path-type@4.0.0:
+    resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
+    engines: {node: '>=8'}
+
+  pathe@2.0.3:
+    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
+
+  perfect-freehand@1.2.3:
+    resolution: {integrity: sha512-bHZSfqDHGNlPpgH2yxXgPHlQSPpEbo+qg7li0M78J9vNAi2yjwLeA4x79BEQhX44lEWpCLSFCeRZwpw0niiXPA==}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
+    engines: {node: '>=12'}
+
+  playwright-core@1.61.1:
+    resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.61.1:
+    resolution: {integrity: sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  pngjs@7.0.0:
+    resolution: {integrity: sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==}
+    engines: {node: '>=14.19.0'}
+
+  postcss@8.5.15:
+    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  proxy-compare@3.0.1:
+    resolution: {integrity: sha512-V9plBAt3qjMlS1+nC8771KNf6oJ12gExvaxnNzN/9yVRLdTv/lc+oJlnSzrdYDAvBfTStPCoiaCOTmTs0adv7Q==}
+
+  proxy-memoize@3.0.1:
+    resolution: {integrity: sha512-VDdG/VYtOgdGkWJx7y0o7p+zArSf2383Isci8C+BP3YXgMYDoPd3cCBjw0JdWb6YBb9sFiOPbAADDVTPJnh+9g==}
+
+  react-dom@19.2.7:
+    resolution: {integrity: sha512-t0BRVXvbiE/o20Hfw669rLbMCDWtYZLvmJigy2f0MxsXF+71pxhR3xOkspmsO8h3ZlNzyibAmtCa3l4lYKk6gQ==}
+    peerDependencies:
+      react: ^19.2.7
+
+  react-hook-tanstack-virtual@0.0.4:
+    resolution: {integrity: sha512-N6OnfdklUygY6K9Ik7SGZlAlc3uVOVm8kp3OP7d4m+0ELGgABm4W/f8kJPcda8CkgQUkFvDO8t8lOzbEsdJG3w==}
+    peerDependencies:
+      '@tanstack/react-virtual': ^3.14.2
+      '@tanstack/virtual-core': ^3.17.0
+      react: ^19.2.0
+      react-dom: ^19.2.0
+
+  react-i18next@16.6.6:
+    resolution: {integrity: sha512-ZgL2HUoW34UKUkOV7uSQFE1CDnRPD+tCR3ywSuWH7u2iapnz86U8Bi3Vrs620qNDzCf1F47NxglCEkchCTDOHw==}
+    peerDependencies:
+      i18next: '>= 25.10.9'
+      react: '>= 16.8.0'
+      react-dom: '*'
+      react-native: '*'
+      typescript: ^5 || ^6
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+      react-native:
+        optional: true
+      typescript:
+        optional: true
+
+  react-icons@5.6.0:
+    resolution: {integrity: sha512-RH93p5ki6LfOiIt0UtDyNg/cee+HLVR6cHHtW3wALfo+eOHTp8RnU2kRkI6E+H19zMIs03DyxUG/GfZMOGvmiA==}
+    peerDependencies:
+      react: '*'
+
+  react-is@16.13.1:
+    resolution: {integrity: sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==}
+
+  react@19.2.7:
+    resolution: {integrity: sha512-HNe9WslTbXmFK8o8cmwgAeJFSBvt1bPdHCVKtaaV+WlAN36mpT4hcRpwbf3fY56ar2oIXzsBpOAiIRHAdY0OlQ==}
+    engines: {node: '>=0.10.0'}
+
+  resolve-from@4.0.0:
+    resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
+    engines: {node: '>=4'}
+
+  resolve@1.22.12:
+    resolution: {integrity: sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA==}
+    engines: {node: '>= 0.4'}
+    hasBin: true
+
+  rolldown@1.1.3:
+    resolution: {integrity: sha512-1F1eEtUBtFvcGm1HQ9TiUIUHPQG7mSAODrhIzjxoUEFuo8OcbrGLiVLkevNgj84TE4lnHvnumwFjhJO5Eu135g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
+  seroval-plugins@1.5.4:
+    resolution: {integrity: sha512-S0xQPhUTefAhNvNWFg0c1J8qJArHt5KdtJ/cFAofo06KD1MVSeFWyl4iiu+ApDIuw0WhjpOfCdgConOfAnLgkw==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      seroval: ^1.0
+
+  seroval@1.5.4:
+    resolution: {integrity: sha512-46uFvgrXTVxZcUorgSSRZ4y+ieqLLQRMlG4bnCZKW3qI6BZm7Rg4ntMW4p1mILEEBZWrFlcpp0AyIIlM6jD9iw==}
+    engines: {node: '>=10'}
+
+  siginfo@2.0.0:
+    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
+
+  sirv@3.0.2:
+    resolution: {integrity: sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==}
+    engines: {node: '>=18'}
+
+  socket.io-client@4.8.3:
+    resolution: {integrity: sha512-uP0bpjWrjQmUt5DTHq9RuoCBdFJF10cdX9X+a368j/Ft0wmaVgxlrjvK3kjvgCODOMMOz9lcaRzxmso0bTWZ/g==}
+    engines: {node: '>=10.0.0'}
+
+  socket.io-parser@4.2.6:
+    resolution: {integrity: sha512-asJqbVBDsBCJx0pTqw3WfesSY0iRX+2xzWEWzrpcH7L6fLzrhyF8WPI8UaeM4YCuDfpwA/cgsdugMsmtz8EJeg==}
+    engines: {node: '>=10.0.0'}
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.5.7:
+    resolution: {integrity: sha512-LbrmJOMUSdEVxIKvdcJzQC+nQhe8FUZQTXQy6+I75skNgn3OoQ0DZA8YnFa7gp8tqtL3KPf1kmo0R5DoApeSGQ==}
+    engines: {node: '>=0.10.0'}
+
+  stackback@0.0.2:
+    resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
+
+  std-env@4.1.0:
+    resolution: {integrity: sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==}
+
+  stylis@4.2.0:
+    resolution: {integrity: sha512-Orov6g6BB1sDfYgzWfTHDOxamtX1bE/zo104Dh9e6fqJ3PooipYyfJ0pUmrZO2wAvO8YbEyeFrkV91XTsGMSrw==}
+
+  supports-preserve-symlinks-flag@1.0.0:
+    resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==}
+    engines: {node: '>= 0.4'}
+
+  tinybench@2.9.0:
+    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+
+  tinyexec@1.2.4:
+    resolution: {integrity: sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==}
+    engines: {node: '>=18'}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
+  tinykeys@4.0.0:
+    resolution: {integrity: sha512-z5bQRQHL1PSx3lGOZEAMM2oKp0EBtn5T5f7HJnaKPOzk6vEH0wUPvdHLeQ7F4tmkek8AgoTQISUFmn/5SNF2xA==}
+    engines: {node: '>=22'}
+
+  tinypool@2.1.0:
+    resolution: {integrity: sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw==}
+    engines: {node: ^20.0.0 || >=22.0.0}
+
+  tinyrainbow@3.1.0:
+    resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==}
+    engines: {node: '>=14.0.0'}
+
+  totalist@3.0.1:
+    resolution: {integrity: sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==}
+    engines: {node: '>=6'}
+
+  tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  typescript@6.0.3:
+    resolution: {integrity: sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@8.3.0:
+    resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
+
+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
+  uqr@0.1.3:
+    resolution: {integrity: sha512-0rjE8iEJe4YmT9TOhwsZtqCMRLc5DXZUI2UEYUUg63ikBkqqE5EYWaI0etFe/5KUcmcYwLih2RND1kq+hrUJXA==}
+
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  vite@8.1.0:
+    resolution: {integrity: sha512-BuJcQK/56NQTWDGn4ABea3q4SSBdNPWwNZKTkkUpcMPnLoquSYH8llRtSUIgoL1KSCpHt5eghLShn50mH36y7Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.3.0
+      esbuild: ^0.27.0 || ^0.28.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vitest@4.1.9:
+    resolution: {integrity: sha512-nE3/LEyc0z87uHYLZebqCUOaJr2hdtuPp7BQ4BosVFnfltxgAvMG08NyrSGlPpOUWvR27c5flSmYFTNr78L9GQ==}
+    engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 4.1.9
+      '@vitest/browser-preview': 4.1.9
+      '@vitest/browser-webdriverio': 4.1.9
+      '@vitest/coverage-istanbul': 4.1.9
+      '@vitest/coverage-v8': 4.1.9
+      '@vitest/ui': 4.1.9
+      happy-dom: '*'
+      jsdom: '*'
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/coverage-istanbul':
+        optional: true
+      '@vitest/coverage-v8':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  void-elements@3.1.0:
+    resolution: {integrity: sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==}
+    engines: {node: '>=0.10.0'}
+
+  webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
+  whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
+  why-is-node-running@2.3.0:
+    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
+    engines: {node: '>=8'}
+    hasBin: true
+
+  ws@8.21.0:
+    resolution: {integrity: sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+
+  xmlhttprequest-ssl@2.1.2:
+    resolution: {integrity: sha512-TEU+nJVUUnA4CYJFLvK5X9AOeH4KvDvhIfm0vV1GaQRtchnG0hgK5p8hw/xjv8cunWYCsiPCSDzObPyhEwq3KQ==}
+    engines: {node: '>=0.4.0'}
+
+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
+  yaml@1.10.3:
+    resolution: {integrity: sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==}
+    engines: {node: '>= 6'}
+
+  zod@4.4.3:
+    resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
+
+  zustand@4.5.7:
+    resolution: {integrity: sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==}
+    engines: {node: '>=12.7.0'}
+    peerDependencies:
+      '@types/react': '>=16.8'
+      immer: '>=9.0.6'
+      react: '>=16.8'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      immer:
+        optional: true
+      react:
+        optional: true
+
+snapshots:
+
+  '@ark-ui/react@5.37.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@zag-js/accordion': 1.41.2
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/angle-slider': 1.41.2
+      '@zag-js/async-list': 1.41.2
+      '@zag-js/auto-resize': 1.41.2
+      '@zag-js/avatar': 1.41.2
+      '@zag-js/carousel': 1.41.2
+      '@zag-js/cascade-select': 1.41.2
+      '@zag-js/checkbox': 1.41.2
+      '@zag-js/clipboard': 1.41.2
+      '@zag-js/collapsible': 1.41.2
+      '@zag-js/collection': 1.41.2
+      '@zag-js/color-picker': 1.41.2
+      '@zag-js/color-utils': 1.41.2
+      '@zag-js/combobox': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/date-input': 1.41.2(@internationalized/date@3.12.2)
+      '@zag-js/date-picker': 1.41.2(@internationalized/date@3.12.2)
+      '@zag-js/date-utils': 1.41.2(@internationalized/date@3.12.2)
+      '@zag-js/dialog': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/drawer': 1.41.2
+      '@zag-js/editable': 1.41.2
+      '@zag-js/file-upload': 1.41.2
+      '@zag-js/file-utils': 1.41.2
+      '@zag-js/floating-panel': 1.41.2
+      '@zag-js/focus-trap': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/highlight-word': 1.41.2
+      '@zag-js/hover-card': 1.41.2
+      '@zag-js/i18n-utils': 1.41.2
+      '@zag-js/image-cropper': 1.41.2
+      '@zag-js/json-tree-utils': 1.41.2
+      '@zag-js/listbox': 1.41.2
+      '@zag-js/marquee': 1.41.2
+      '@zag-js/menu': 1.41.2
+      '@zag-js/navigation-menu': 1.41.2
+      '@zag-js/number-input': 1.41.2
+      '@zag-js/pagination': 1.41.2
+      '@zag-js/password-input': 1.41.2
+      '@zag-js/pin-input': 1.41.2
+      '@zag-js/popover': 1.41.2
+      '@zag-js/presence': 1.41.2
+      '@zag-js/progress': 1.41.2
+      '@zag-js/qr-code': 1.41.2
+      '@zag-js/radio-group': 1.41.2
+      '@zag-js/rating-group': 1.41.2
+      '@zag-js/react': 1.41.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@zag-js/scroll-area': 1.41.2
+      '@zag-js/select': 1.41.2
+      '@zag-js/signature-pad': 1.41.2
+      '@zag-js/slider': 1.41.2
+      '@zag-js/splitter': 1.41.2
+      '@zag-js/steps': 1.41.2
+      '@zag-js/switch': 1.41.2
+      '@zag-js/tabs': 1.41.2
+      '@zag-js/tags-input': 1.41.2
+      '@zag-js/timer': 1.41.2
+      '@zag-js/toast': 1.41.2
+      '@zag-js/toggle': 1.41.2
+      '@zag-js/toggle-group': 1.41.2
+      '@zag-js/tooltip': 1.41.2
+      '@zag-js/tour': 1.41.2
+      '@zag-js/tree-view': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  '@babel/code-frame@7.29.7':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.29.7
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/compat-data@7.29.7': {}
+
+  '@babel/core@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-compilation-targets': 7.29.7
+      '@babel/helper-module-transforms': 7.29.7(@babel/core@7.29.7)
+      '@babel/helpers': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/generator@7.29.7':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/helper-compilation-targets@7.29.7':
+    dependencies:
+      '@babel/compat-data': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      browserslist: 4.28.4
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-globals@7.29.7': {}
+
+  '@babel/helper-module-imports@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+      '@babel/traverse': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-string-parser@7.29.7': {}
+
+  '@babel/helper-validator-identifier@7.29.7': {}
+
+  '@babel/helper-validator-option@7.29.7': {}
+
+  '@babel/helpers@7.29.7':
+    dependencies:
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/runtime@7.29.7': {}
+
+  '@babel/template@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/traverse@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-globals': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
+  '@blazediff/core@1.9.1': {}
+
+  '@chakra-ui/react@3.36.0(@emotion/react@11.14.0(@types/react@19.2.17)(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@ark-ui/react': 5.37.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@emotion/is-prop-valid': 1.4.0
+      '@emotion/react': 11.14.0(@types/react@19.2.17)(react@19.2.7)
+      '@emotion/serialize': 1.3.3
+      '@emotion/use-insertion-effect-with-fallbacks': 1.2.0(react@19.2.7)
+      '@emotion/utils': 1.4.2
+      '@pandacss/is-valid-prop': 1.11.3
+      csstype: 3.2.3
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  '@dnd-kit/accessibility@3.1.1(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+      tslib: 2.8.1
+
+  '@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@dnd-kit/accessibility': 3.1.1(react@19.2.7)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      tslib: 2.8.1
+
+  '@dnd-kit/modifiers@9.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@dnd-kit/core': 6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.7)
+      react: 19.2.7
+      tslib: 2.8.1
+
+  '@dnd-kit/sortable@10.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@dnd-kit/core': 6.3.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.7)
+      react: 19.2.7
+      tslib: 2.8.1
+
+  '@dnd-kit/utilities@3.2.2(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+      tslib: 2.8.1
+
+  '@emnapi/core@1.11.1':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.2
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.11.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/wasi-threads@1.2.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emotion/babel-plugin@11.13.5':
+    dependencies:
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/runtime': 7.29.7
+      '@emotion/hash': 0.9.2
+      '@emotion/memoize': 0.9.0
+      '@emotion/serialize': 1.3.3
+      babel-plugin-macros: 3.1.0
+      convert-source-map: 1.9.0
+      escape-string-regexp: 4.0.0
+      find-root: 1.1.0
+      source-map: 0.5.7
+      stylis: 4.2.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@emotion/cache@11.14.0':
+    dependencies:
+      '@emotion/memoize': 0.9.0
+      '@emotion/sheet': 1.4.0
+      '@emotion/utils': 1.4.2
+      '@emotion/weak-memoize': 0.4.0
+      stylis: 4.2.0
+
+  '@emotion/hash@0.9.2': {}
+
+  '@emotion/is-prop-valid@1.4.0':
+    dependencies:
+      '@emotion/memoize': 0.9.0
+
+  '@emotion/memoize@0.9.0': {}
+
+  '@emotion/react@11.14.0(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@emotion/babel-plugin': 11.13.5
+      '@emotion/cache': 11.14.0
+      '@emotion/serialize': 1.3.3
+      '@emotion/use-insertion-effect-with-fallbacks': 1.2.0(react@19.2.7)
+      '@emotion/utils': 1.4.2
+      '@emotion/weak-memoize': 0.4.0
+      hoist-non-react-statics: 3.3.2
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+    transitivePeerDependencies:
+      - supports-color
+
+  '@emotion/serialize@1.3.3':
+    dependencies:
+      '@emotion/hash': 0.9.2
+      '@emotion/memoize': 0.9.0
+      '@emotion/unitless': 0.10.0
+      '@emotion/utils': 1.4.2
+      csstype: 3.2.3
+
+  '@emotion/sheet@1.4.0': {}
+
+  '@emotion/unitless@0.10.0': {}
+
+  '@emotion/use-insertion-effect-with-fallbacks@1.2.0(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+
+  '@emotion/utils@1.4.2': {}
+
+  '@emotion/weak-memoize@0.4.0': {}
+
+  '@esbuild/aix-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm@0.27.7':
+    optional: true
+
+  '@esbuild/android-x64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.7':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.7':
+    optional: true
+
+  '@floating-ui/core@1.7.5':
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/dom@1.7.6':
+    dependencies:
+      '@floating-ui/core': 1.7.5
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/utils@0.2.11': {}
+
+  '@fontsource/inter@5.2.8': {}
+
+  '@internationalized/date@3.12.2':
+    dependencies:
+      '@swc/helpers': 0.5.23
+
+  '@internationalized/number@3.6.6':
+    dependencies:
+      '@swc/helpers': 0.5.23
+
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
+    dependencies:
+      '@emnapi/core': 1.11.1
+      '@emnapi/runtime': 1.11.1
+      '@tybys/wasm-util': 0.10.3
+    optional: true
+
+  '@oxc-project/types@0.137.0': {}
+
+  '@oxfmt/binding-android-arm-eabi@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-android-arm64@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-darwin-arm64@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-darwin-x64@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-freebsd-x64@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-arm-gnueabihf@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-arm-musleabihf@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-arm64-gnu@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-arm64-musl@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-ppc64-gnu@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-riscv64-gnu@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-riscv64-musl@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-s390x-gnu@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-x64-gnu@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-linux-x64-musl@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-openharmony-arm64@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-win32-arm64-msvc@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-win32-ia32-msvc@0.56.0':
+    optional: true
+
+  '@oxfmt/binding-win32-x64-msvc@0.56.0':
+    optional: true
+
+  '@oxlint/binding-android-arm-eabi@1.71.0':
+    optional: true
+
+  '@oxlint/binding-android-arm64@1.71.0':
+    optional: true
+
+  '@oxlint/binding-darwin-arm64@1.71.0':
+    optional: true
+
+  '@oxlint/binding-darwin-x64@1.71.0':
+    optional: true
+
+  '@oxlint/binding-freebsd-x64@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm-gnueabihf@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm-musleabihf@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm64-gnu@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm64-musl@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-ppc64-gnu@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-riscv64-gnu@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-riscv64-musl@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-s390x-gnu@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-x64-gnu@1.71.0':
+    optional: true
+
+  '@oxlint/binding-linux-x64-musl@1.71.0':
+    optional: true
+
+  '@oxlint/binding-openharmony-arm64@1.71.0':
+    optional: true
+
+  '@oxlint/binding-win32-arm64-msvc@1.71.0':
+    optional: true
+
+  '@oxlint/binding-win32-ia32-msvc@1.71.0':
+    optional: true
+
+  '@oxlint/binding-win32-x64-msvc@1.71.0':
+    optional: true
+
+  '@pandacss/is-valid-prop@1.11.3': {}
+
+  '@polka/url@1.0.0-next.29': {}
+
+  '@rolldown/binding-android-arm64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.1.3':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.1.3':
+    dependencies:
+      '@emnapi/core': 1.11.1
+      '@emnapi/runtime': 1.11.1
+      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.1.3':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.1.3':
+    optional: true
+
+  '@rolldown/plugin-babel@0.2.3(@babel/core@7.29.7)(@babel/runtime@7.29.7)(rolldown@1.1.3)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))':
+    dependencies:
+      '@babel/core': 7.29.7
+      picomatch: 4.0.4
+      rolldown: 1.1.3
+    optionalDependencies:
+      '@babel/runtime': 7.29.7
+      vite: 8.1.0(@types/node@26.0.1)(esbuild@0.27.7)
+
+  '@rolldown/pluginutils@1.0.1': {}
+
+  '@socket.io/component-emitter@3.1.2': {}
+
+  '@standard-schema/spec@1.1.0': {}
+
+  '@swc/helpers@0.5.23':
+    dependencies:
+      tslib: 2.8.1
+
+  '@tanstack/history@1.162.0': {}
+
+  '@tanstack/react-router@1.170.16(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/history': 1.162.0
+      '@tanstack/react-store': 0.9.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@tanstack/router-core': 1.171.13
+      isbot: 5.1.44
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  '@tanstack/react-store@0.9.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/store': 0.9.3
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      use-sync-external-store: 1.6.0(react@19.2.7)
+
+  '@tanstack/react-virtual@3.14.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/virtual-core': 3.17.1
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  '@tanstack/router-core@1.171.13':
+    dependencies:
+      '@tanstack/history': 1.162.0
+      cookie-es: 3.1.1
+      seroval: 1.5.4
+      seroval-plugins: 1.5.4(seroval@1.5.4)
+
+  '@tanstack/store@0.9.3': {}
+
+  '@tanstack/virtual-core@3.17.1': {}
+
+  '@tybys/wasm-util@0.10.3':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
+  '@types/d3-color@3.1.3': {}
+
+  '@types/d3-drag@3.0.7':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-interpolate@3.0.4':
+    dependencies:
+      '@types/d3-color': 3.1.3
+
+  '@types/d3-selection@3.0.11': {}
+
+  '@types/d3-transition@3.0.9':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-zoom@3.0.8':
+    dependencies:
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-selection': 3.0.11
+
+  '@types/deep-eql@4.0.2': {}
+
+  '@types/estree@1.0.9': {}
+
+  '@types/node@26.0.1':
+    dependencies:
+      undici-types: 8.3.0
+
+  '@types/parse-json@4.0.2': {}
+
+  '@types/react-dom@19.2.3(@types/react@19.2.17)':
+    dependencies:
+      '@types/react': 19.2.17
+
+  '@types/react@19.2.17':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/use-sync-external-store@1.5.0': {}
+
+  '@vitejs/plugin-react@6.0.3(@rolldown/plugin-babel@0.2.3(@babel/core@7.29.7)(@babel/runtime@7.29.7)(rolldown@1.1.3)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7)))(babel-plugin-react-compiler@1.0.0)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))':
+    dependencies:
+      '@rolldown/pluginutils': 1.0.1
+      vite: 8.1.0(@types/node@26.0.1)(esbuild@0.27.7)
+    optionalDependencies:
+      '@rolldown/plugin-babel': 0.2.3(@babel/core@7.29.7)(@babel/runtime@7.29.7)(rolldown@1.1.3)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+      babel-plugin-react-compiler: 1.0.0
+
+  '@vitest/browser-playwright@4.1.9(playwright@1.61.1)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))(vitest@4.1.9)':
+    dependencies:
+      '@vitest/browser': 4.1.9(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))(vitest@4.1.9)
+      '@vitest/mocker': 4.1.9(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+      playwright: 1.61.1
+      tinyrainbow: 3.1.0
+      vitest: 4.1.9(@types/node@26.0.1)(@vitest/browser-playwright@4.1.9)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+    transitivePeerDependencies:
+      - bufferutil
+      - msw
+      - utf-8-validate
+      - vite
+
+  '@vitest/browser@4.1.9(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))(vitest@4.1.9)':
+    dependencies:
+      '@blazediff/core': 1.9.1
+      '@vitest/mocker': 4.1.9(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+      '@vitest/utils': 4.1.9
+      magic-string: 0.30.21
+      pngjs: 7.0.0
+      sirv: 3.0.2
+      tinyrainbow: 3.1.0
+      vitest: 4.1.9(@types/node@26.0.1)(@vitest/browser-playwright@4.1.9)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+      ws: 8.21.0
+    transitivePeerDependencies:
+      - bufferutil
+      - msw
+      - utf-8-validate
+      - vite
+
+  '@vitest/expect@4.1.9':
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      '@types/chai': 5.2.3
+      '@vitest/spy': 4.1.9
+      '@vitest/utils': 4.1.9
+      chai: 6.2.2
+      tinyrainbow: 3.1.0
+
+  '@vitest/mocker@4.1.9(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))':
+    dependencies:
+      '@vitest/spy': 4.1.9
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 8.1.0(@types/node@26.0.1)(esbuild@0.27.7)
+
+  '@vitest/pretty-format@4.1.9':
+    dependencies:
+      tinyrainbow: 3.1.0
+
+  '@vitest/runner@4.1.9':
+    dependencies:
+      '@vitest/utils': 4.1.9
+      pathe: 2.0.3
+
+  '@vitest/snapshot@4.1.9':
+    dependencies:
+      '@vitest/pretty-format': 4.1.9
+      '@vitest/utils': 4.1.9
+      magic-string: 0.30.21
+      pathe: 2.0.3
+
+  '@vitest/spy@4.1.9': {}
+
+  '@vitest/utils@4.1.9':
+    dependencies:
+      '@vitest/pretty-format': 4.1.9
+      convert-source-map: 2.0.0
+      tinyrainbow: 3.1.0
+
+  '@xyflow/react@12.11.1(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@xyflow/system': 0.0.78
+      classcat: 5.0.5
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      zustand: 4.5.7(@types/react@19.2.17)(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+    transitivePeerDependencies:
+      - immer
+
+  '@xyflow/system@0.0.78':
+    dependencies:
+      '@types/d3-drag': 3.0.7
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-selection': 3.0.11
+      '@types/d3-transition': 3.0.9
+      '@types/d3-zoom': 3.0.8
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-zoom: 3.0.0
+
+  '@zag-js/accordion@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/anatomy@1.41.2': {}
+
+  '@zag-js/angle-slider@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/rect-utils': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/aria-hidden@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+
+  '@zag-js/async-list@1.41.2':
+    dependencies:
+      '@zag-js/core': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/auto-resize@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+
+  '@zag-js/avatar@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/carousel@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/scroll-snap': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/cascade-select@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/collection': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/rect-utils': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/checkbox@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/clipboard@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/collapsible@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/collection@1.41.2':
+    dependencies:
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/color-picker@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/color-utils': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/color-utils@1.41.2':
+    dependencies:
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/combobox@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/collection': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/live-region': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/core@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/date-input@1.41.2(@internationalized/date@3.12.2)':
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/date-utils': 1.41.2(@internationalized/date@3.12.2)
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/live-region': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/date-picker@1.41.2(@internationalized/date@3.12.2)':
+    dependencies:
+      '@internationalized/date': 3.12.2
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/date-utils': 1.41.2(@internationalized/date@3.12.2)
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/live-region': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/date-utils@1.41.2(@internationalized/date@3.12.2)':
+    dependencies:
+      '@internationalized/date': 3.12.2
+
+  '@zag-js/dialog@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/aria-hidden': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-trap': 1.41.2
+      '@zag-js/remove-scroll': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/dismissable@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/interact-outside': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/dom-query@1.41.2':
+    dependencies:
+      '@zag-js/types': 1.41.2
+
+  '@zag-js/drawer@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/aria-hidden': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-trap': 1.41.2
+      '@zag-js/remove-scroll': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/editable@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/interact-outside': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/file-upload@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/file-utils': 1.41.2
+      '@zag-js/i18n-utils': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/file-utils@1.41.2':
+    dependencies:
+      '@zag-js/i18n-utils': 1.41.2
+
+  '@zag-js/floating-panel@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/rect-utils': 1.41.2
+      '@zag-js/store': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/focus-trap@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+
+  '@zag-js/focus-visible@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+
+  '@zag-js/highlight-word@1.41.2': {}
+
+  '@zag-js/hover-card@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/i18n-utils@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+
+  '@zag-js/image-cropper@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/interact-outside@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/json-tree-utils@1.41.2': {}
+
+  '@zag-js/listbox@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/collection': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/live-region@1.41.2': {}
+
+  '@zag-js/marquee@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/menu@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/rect-utils': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/navigation-menu@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/number-input@1.41.2':
+    dependencies:
+      '@internationalized/number': 3.6.6
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/pagination@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/password-input@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/pin-input@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/popover@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/aria-hidden': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-trap': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/remove-scroll': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/popper@1.41.2':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/presence@1.41.2':
+    dependencies:
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+
+  '@zag-js/progress@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/qr-code@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+      proxy-memoize: 3.0.1
+      uqr: 0.1.3
+
+  '@zag-js/radio-group@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/rating-group@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/react@1.41.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@zag-js/core': 1.41.2
+      '@zag-js/store': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  '@zag-js/rect-utils@1.41.2': {}
+
+  '@zag-js/remove-scroll@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+
+  '@zag-js/scroll-area@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/scroll-snap@1.41.2':
+    dependencies:
+      '@zag-js/dom-query': 1.41.2
+
+  '@zag-js/select@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/collection': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/signature-pad@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+      perfect-freehand: 1.2.3
+
+  '@zag-js/slider@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/splitter@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/steps@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/store@1.41.2':
+    dependencies:
+      proxy-compare: 3.0.1
+
+  '@zag-js/switch@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/tabs@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/tags-input@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/auto-resize': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/interact-outside': 1.41.2
+      '@zag-js/live-region': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/timer@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/toast@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/toggle-group@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/toggle@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/tooltip@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-visible': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/tour@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dismissable': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/focus-trap': 1.41.2
+      '@zag-js/interact-outside': 1.41.2
+      '@zag-js/popper': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/tree-view@1.41.2':
+    dependencies:
+      '@zag-js/anatomy': 1.41.2
+      '@zag-js/collection': 1.41.2
+      '@zag-js/core': 1.41.2
+      '@zag-js/dom-query': 1.41.2
+      '@zag-js/types': 1.41.2
+      '@zag-js/utils': 1.41.2
+
+  '@zag-js/types@1.41.2':
+    dependencies:
+      csstype: 3.2.3
+
+  '@zag-js/utils@1.41.2': {}
+
+  ag-psd@31.0.1:
+    dependencies:
+      base64-js: 1.5.1
+      pako: 2.1.0
+
+  assertion-error@2.0.1: {}
+
+  babel-plugin-macros@3.1.0:
+    dependencies:
+      '@babel/runtime': 7.29.7
+      cosmiconfig: 7.1.0
+      resolve: 1.22.12
+
+  babel-plugin-react-compiler@1.0.0:
+    dependencies:
+      '@babel/types': 7.29.7
+
+  base64-js@1.5.1: {}
+
+  baseline-browser-mapping@2.10.40: {}
+
+  browserslist@4.28.4:
+    dependencies:
+      baseline-browser-mapping: 2.10.40
+      caniuse-lite: 1.0.30001799
+      electron-to-chromium: 1.5.379
+      node-releases: 2.0.50
+      update-browserslist-db: 1.2.3(browserslist@4.28.4)
+
+  callsites@3.1.0: {}
+
+  caniuse-lite@1.0.30001799: {}
+
+  chai@6.2.2: {}
+
+  classcat@5.0.5: {}
+
+  convert-source-map@1.9.0: {}
+
+  convert-source-map@2.0.0: {}
+
+  cookie-es@3.1.1: {}
+
+  cosmiconfig@7.1.0:
+    dependencies:
+      '@types/parse-json': 4.0.2
+      import-fresh: 3.3.1
+      parse-json: 5.2.0
+      path-type: 4.0.0
+      yaml: 1.10.3
+
+  cross-fetch@4.1.0:
+    dependencies:
+      node-fetch: 2.7.0
+    transitivePeerDependencies:
+      - encoding
+
+  csstype@3.2.3: {}
+
+  d3-color@3.1.0: {}
+
+  d3-dispatch@3.0.1: {}
+
+  d3-drag@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-selection: 3.0.0
+
+  d3-ease@3.0.1: {}
+
+  d3-interpolate@3.0.1:
+    dependencies:
+      d3-color: 3.1.0
+
+  d3-selection@3.0.0: {}
+
+  d3-timer@3.0.1: {}
+
+  d3-transition@3.0.1(d3-selection@3.0.0):
+    dependencies:
+      d3-color: 3.1.0
+      d3-dispatch: 3.0.1
+      d3-ease: 3.0.1
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-timer: 3.0.1
+
+  d3-zoom@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  detect-libc@2.1.2: {}
+
+  electron-to-chromium@1.5.379: {}
+
+  engine.io-client@6.6.6:
+    dependencies:
+      '@socket.io/component-emitter': 3.1.2
+      debug: 4.4.3
+      engine.io-parser: 5.2.3
+      ws: 8.21.0
+      xmlhttprequest-ssl: 2.1.2
+    transitivePeerDependencies:
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
+  engine.io-parser@5.2.3: {}
+
+  error-ex@1.3.4:
+    dependencies:
+      is-arrayish: 0.2.1
+
+  es-errors@1.3.0: {}
+
+  es-module-lexer@2.1.0: {}
+
+  esbuild@0.27.7:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.7
+      '@esbuild/android-arm': 0.27.7
+      '@esbuild/android-arm64': 0.27.7
+      '@esbuild/android-x64': 0.27.7
+      '@esbuild/darwin-arm64': 0.27.7
+      '@esbuild/darwin-x64': 0.27.7
+      '@esbuild/freebsd-arm64': 0.27.7
+      '@esbuild/freebsd-x64': 0.27.7
+      '@esbuild/linux-arm': 0.27.7
+      '@esbuild/linux-arm64': 0.27.7
+      '@esbuild/linux-ia32': 0.27.7
+      '@esbuild/linux-loong64': 0.27.7
+      '@esbuild/linux-mips64el': 0.27.7
+      '@esbuild/linux-ppc64': 0.27.7
+      '@esbuild/linux-riscv64': 0.27.7
+      '@esbuild/linux-s390x': 0.27.7
+      '@esbuild/linux-x64': 0.27.7
+      '@esbuild/netbsd-arm64': 0.27.7
+      '@esbuild/netbsd-x64': 0.27.7
+      '@esbuild/openbsd-arm64': 0.27.7
+      '@esbuild/openbsd-x64': 0.27.7
+      '@esbuild/openharmony-arm64': 0.27.7
+      '@esbuild/sunos-x64': 0.27.7
+      '@esbuild/win32-arm64': 0.27.7
+      '@esbuild/win32-ia32': 0.27.7
+      '@esbuild/win32-x64': 0.27.7
+    optional: true
+
+  escalade@3.2.0: {}
+
+  escape-string-regexp@4.0.0: {}
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  expect-type@1.4.0: {}
+
+  fdir@6.5.0(picomatch@4.0.4):
+    optionalDependencies:
+      picomatch: 4.0.4
+
+  find-root@1.1.0: {}
+
+  fsevents@2.3.2:
+    optional: true
+
+  fsevents@2.3.3:
+    optional: true
+
+  function-bind@1.1.2: {}
+
+  gensync@1.0.0-beta.2: {}
+
+  hasown@2.0.4:
+    dependencies:
+      function-bind: 1.1.2
+
+  hoist-non-react-statics@3.3.2:
+    dependencies:
+      react-is: 16.13.1
+
+  html-parse-stringify@3.0.1:
+    dependencies:
+      void-elements: 3.1.0
+
+  i18next-http-backend@3.0.6:
+    dependencies:
+      cross-fetch: 4.1.0
+    transitivePeerDependencies:
+      - encoding
+
+  i18next@25.10.10(typescript@6.0.3):
+    dependencies:
+      '@babel/runtime': 7.29.7
+    optionalDependencies:
+      typescript: 6.0.3
+
+  import-fresh@3.3.1:
+    dependencies:
+      parent-module: 1.0.1
+      resolve-from: 4.0.0
+
+  is-arrayish@0.2.1: {}
+
+  is-core-module@2.16.2:
+    dependencies:
+      hasown: 2.0.4
+
+  isbot@5.1.44: {}
+
+  js-tokens@4.0.0: {}
+
+  jsesc@3.1.0: {}
+
+  json-parse-even-better-errors@2.3.1: {}
+
+  json5@2.2.3: {}
+
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
+  lines-and-columns@1.2.4: {}
+
+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
+  lucide-react@1.21.0(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  mrmime@2.0.1: {}
+
+  ms@2.1.3: {}
+
+  nanoid@3.3.15: {}
+
+  node-fetch@2.7.0:
+    dependencies:
+      whatwg-url: 5.0.0
+
+  node-releases@2.0.50: {}
+
+  obug@2.1.3: {}
+
+  oxfmt@0.56.0:
+    dependencies:
+      tinypool: 2.1.0
+    optionalDependencies:
+      '@oxfmt/binding-android-arm-eabi': 0.56.0
+      '@oxfmt/binding-android-arm64': 0.56.0
+      '@oxfmt/binding-darwin-arm64': 0.56.0
+      '@oxfmt/binding-darwin-x64': 0.56.0
+      '@oxfmt/binding-freebsd-x64': 0.56.0
+      '@oxfmt/binding-linux-arm-gnueabihf': 0.56.0
+      '@oxfmt/binding-linux-arm-musleabihf': 0.56.0
+      '@oxfmt/binding-linux-arm64-gnu': 0.56.0
+      '@oxfmt/binding-linux-arm64-musl': 0.56.0
+      '@oxfmt/binding-linux-ppc64-gnu': 0.56.0
+      '@oxfmt/binding-linux-riscv64-gnu': 0.56.0
+      '@oxfmt/binding-linux-riscv64-musl': 0.56.0
+      '@oxfmt/binding-linux-s390x-gnu': 0.56.0
+      '@oxfmt/binding-linux-x64-gnu': 0.56.0
+      '@oxfmt/binding-linux-x64-musl': 0.56.0
+      '@oxfmt/binding-openharmony-arm64': 0.56.0
+      '@oxfmt/binding-win32-arm64-msvc': 0.56.0
+      '@oxfmt/binding-win32-ia32-msvc': 0.56.0
+      '@oxfmt/binding-win32-x64-msvc': 0.56.0
+
+  oxlint@1.71.0:
+    optionalDependencies:
+      '@oxlint/binding-android-arm-eabi': 1.71.0
+      '@oxlint/binding-android-arm64': 1.71.0
+      '@oxlint/binding-darwin-arm64': 1.71.0
+      '@oxlint/binding-darwin-x64': 1.71.0
+      '@oxlint/binding-freebsd-x64': 1.71.0
+      '@oxlint/binding-linux-arm-gnueabihf': 1.71.0
+      '@oxlint/binding-linux-arm-musleabihf': 1.71.0
+      '@oxlint/binding-linux-arm64-gnu': 1.71.0
+      '@oxlint/binding-linux-arm64-musl': 1.71.0
+      '@oxlint/binding-linux-ppc64-gnu': 1.71.0
+      '@oxlint/binding-linux-riscv64-gnu': 1.71.0
+      '@oxlint/binding-linux-riscv64-musl': 1.71.0
+      '@oxlint/binding-linux-s390x-gnu': 1.71.0
+      '@oxlint/binding-linux-x64-gnu': 1.71.0
+      '@oxlint/binding-linux-x64-musl': 1.71.0
+      '@oxlint/binding-openharmony-arm64': 1.71.0
+      '@oxlint/binding-win32-arm64-msvc': 1.71.0
+      '@oxlint/binding-win32-ia32-msvc': 1.71.0
+      '@oxlint/binding-win32-x64-msvc': 1.71.0
+
+  pako@2.1.0: {}
+
+  parent-module@1.0.1:
+    dependencies:
+      callsites: 3.1.0
+
+  parse-json@5.2.0:
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      error-ex: 1.3.4
+      json-parse-even-better-errors: 2.3.1
+      lines-and-columns: 1.2.4
+
+  path-parse@1.0.7: {}
+
+  path-type@4.0.0: {}
+
+  pathe@2.0.3: {}
+
+  perfect-freehand@1.2.3: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@4.0.4: {}
+
+  playwright-core@1.61.1: {}
+
+  playwright@1.61.1:
+    dependencies:
+      playwright-core: 1.61.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
+  pngjs@7.0.0: {}
+
+  postcss@8.5.15:
+    dependencies:
+      nanoid: 3.3.15
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  proxy-compare@3.0.1: {}
+
+  proxy-memoize@3.0.1:
+    dependencies:
+      proxy-compare: 3.0.1
+
+  react-dom@19.2.7(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      scheduler: 0.27.0
+
+  react-hook-tanstack-virtual@0.0.4(@tanstack/react-virtual@3.14.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@tanstack/virtual-core@3.17.1)(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      '@tanstack/react-virtual': 3.14.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@tanstack/virtual-core': 3.17.1
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  react-i18next@16.6.6(i18next@25.10.10(typescript@6.0.3))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(typescript@6.0.3):
+    dependencies:
+      '@babel/runtime': 7.29.7
+      html-parse-stringify: 3.0.1
+      i18next: 25.10.10(typescript@6.0.3)
+      react: 19.2.7
+      use-sync-external-store: 1.6.0(react@19.2.7)
+    optionalDependencies:
+      react-dom: 19.2.7(react@19.2.7)
+      typescript: 6.0.3
+
+  react-icons@5.6.0(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+
+  react-is@16.13.1: {}
+
+  react@19.2.7: {}
+
+  resolve-from@4.0.0: {}
+
+  resolve@1.22.12:
+    dependencies:
+      es-errors: 1.3.0
+      is-core-module: 2.16.2
+      path-parse: 1.0.7
+      supports-preserve-symlinks-flag: 1.0.0
+
+  rolldown@1.1.3:
+    dependencies:
+      '@oxc-project/types': 0.137.0
+      '@rolldown/pluginutils': 1.0.1
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.1.3
+      '@rolldown/binding-darwin-arm64': 1.1.3
+      '@rolldown/binding-darwin-x64': 1.1.3
+      '@rolldown/binding-freebsd-x64': 1.1.3
+      '@rolldown/binding-linux-arm-gnueabihf': 1.1.3
+      '@rolldown/binding-linux-arm64-gnu': 1.1.3
+      '@rolldown/binding-linux-arm64-musl': 1.1.3
+      '@rolldown/binding-linux-ppc64-gnu': 1.1.3
+      '@rolldown/binding-linux-s390x-gnu': 1.1.3
+      '@rolldown/binding-linux-x64-gnu': 1.1.3
+      '@rolldown/binding-linux-x64-musl': 1.1.3
+      '@rolldown/binding-openharmony-arm64': 1.1.3
+      '@rolldown/binding-wasm32-wasi': 1.1.3
+      '@rolldown/binding-win32-arm64-msvc': 1.1.3
+      '@rolldown/binding-win32-x64-msvc': 1.1.3
+
+  scheduler@0.27.0: {}
+
+  semver@6.3.1: {}
+
+  seroval-plugins@1.5.4(seroval@1.5.4):
+    dependencies:
+      seroval: 1.5.4
+
+  seroval@1.5.4: {}
+
+  siginfo@2.0.0: {}
+
+  sirv@3.0.2:
+    dependencies:
+      '@polka/url': 1.0.0-next.29
+      mrmime: 2.0.1
+      totalist: 3.0.1
+
+  socket.io-client@4.8.3:
+    dependencies:
+      '@socket.io/component-emitter': 3.1.2
+      debug: 4.4.3
+      engine.io-client: 6.6.6
+      socket.io-parser: 4.2.6
+    transitivePeerDependencies:
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
+  socket.io-parser@4.2.6:
+    dependencies:
+      '@socket.io/component-emitter': 3.1.2
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  source-map-js@1.2.1: {}
+
+  source-map@0.5.7: {}
+
+  stackback@0.0.2: {}
+
+  std-env@4.1.0: {}
+
+  stylis@4.2.0: {}
+
+  supports-preserve-symlinks-flag@1.0.0: {}
+
+  tinybench@2.9.0: {}
+
+  tinyexec@1.2.4: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+
+  tinykeys@4.0.0: {}
+
+  tinypool@2.1.0: {}
+
+  tinyrainbow@3.1.0: {}
+
+  totalist@3.0.1: {}
+
+  tr46@0.0.3: {}
+
+  tslib@2.8.1: {}
+
+  typescript@6.0.3: {}
+
+  undici-types@8.3.0: {}
+
+  update-browserslist-db@1.2.3(browserslist@4.28.4):
+    dependencies:
+      browserslist: 4.28.4
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
+  uqr@0.1.3: {}
+
+  use-sync-external-store@1.6.0(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+
+  vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.15
+      rolldown: 1.1.3
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 26.0.1
+      esbuild: 0.27.7
+      fsevents: 2.3.3
+
+  vitest@4.1.9(@types/node@26.0.1)(@vitest/browser-playwright@4.1.9)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7)):
+    dependencies:
+      '@vitest/expect': 4.1.9
+      '@vitest/mocker': 4.1.9(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))
+      '@vitest/pretty-format': 4.1.9
+      '@vitest/runner': 4.1.9
+      '@vitest/snapshot': 4.1.9
+      '@vitest/spy': 4.1.9
+      '@vitest/utils': 4.1.9
+      es-module-lexer: 2.1.0
+      expect-type: 1.4.0
+      magic-string: 0.30.21
+      obug: 2.1.3
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 4.1.0
+      tinybench: 2.9.0
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      tinyrainbow: 3.1.0
+      vite: 8.1.0(@types/node@26.0.1)(esbuild@0.27.7)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 26.0.1
+      '@vitest/browser-playwright': 4.1.9(playwright@1.61.1)(vite@8.1.0(@types/node@26.0.1)(esbuild@0.27.7))(vitest@4.1.9)
+    transitivePeerDependencies:
+      - msw
+
+  void-elements@3.1.0: {}
+
+  webidl-conversions@3.0.1: {}
+
+  whatwg-url@5.0.0:
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1
+
+  why-is-node-running@2.3.0:
+    dependencies:
+      siginfo: 2.0.0
+      stackback: 0.0.2
+
+  ws@8.21.0: {}
+
+  xmlhttprequest-ssl@2.1.2: {}
+
+  yallist@3.1.1: {}
+
+  yaml@1.10.3: {}
+
+  zod@4.4.3: {}
+
+  zustand@4.5.7(@types/react@19.2.17)(react@19.2.7):
+    dependencies:
+      use-sync-external-store: 1.6.0(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      react: 19.2.7
diff --git a/invokeai/frontend/webv2/public/locales/ar.json b/invokeai/frontend/webv2/public/locales/ar.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/ar.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/az.json b/invokeai/frontend/webv2/public/locales/az.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/az.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/bg.json b/invokeai/frontend/webv2/public/locales/bg.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/bg.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/de.json b/invokeai/frontend/webv2/public/locales/de.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/de.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/en-GB.json b/invokeai/frontend/webv2/public/locales/en-GB.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/en-GB.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/en.json b/invokeai/frontend/webv2/public/locales/en.json
new file mode 100644
index 00000000000..844d3da2bd9
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/en.json
@@ -0,0 +1,1654 @@
+{
+  "common": {
+    "actions": "Actions",
+    "active": "Active",
+    "add": "Add",
+    "all": "All",
+    "apply": "Apply",
+    "archived": "Archived",
+    "asc": "Asc",
+    "assets": "Assets",
+    "cancel": "Cancel",
+    "cancelFailed": "Cancel failed",
+    "canceled": "Canceled",
+    "clear": "Clear",
+    "clearSearch": "Clear search",
+    "close": "Close",
+    "configure": "Configure",
+    "copy": "Copy",
+    "crop": "Crop",
+    "clipboardBlocked": "Clipboard access was blocked by the browser.",
+    "couldNotCopy": "Could not copy",
+    "countOfTotal": "{{count}} of {{total}}",
+    "created": "Created",
+    "delete": "Delete",
+    "desc": "Desc",
+    "discard": "Discard",
+    "discardAll": "Discard All",
+    "done": "Done",
+    "duplicate": "Duplicate",
+    "edit": "Edit",
+    "error": "Error",
+    "export": "Export",
+    "failed": "Failed",
+    "generating": "Generating",
+    "graph": "Graph",
+    "images": "Images",
+    "import": "Import",
+    "id": "ID",
+    "item": "Item",
+    "json": "JSON",
+    "lastSaved": "Last saved",
+    "loadingApplication": "Loading Application",
+    "negative": "Negative",
+    "name": "Name",
+    "nothingHereYet": "Nothing here yet.",
+    "none": "None",
+    "notYet": "Not yet",
+    "open": "Open",
+    "pageNumber": "Page {{page}}",
+    "pages": "Pages",
+    "previousPage": "Previous page",
+    "prompt": "Prompt",
+    "project": "Project",
+    "rename": "Rename",
+    "required": "Required",
+    "refresh": "Refresh",
+    "reload": "Reload",
+    "reset": "Reset",
+    "retry": "Retry",
+    "saved": "Saved",
+    "save": "Save",
+    "seed": "Seed",
+    "settings": "Settings",
+    "nextPage": "Next page",
+    "somethingWentWrong": "Something went wrong.",
+    "swap": "Swap",
+    "status": {
+      "canceled": "Canceled",
+      "completed": "Completed",
+      "failed": "Failed",
+      "pending": "Pending"
+    },
+    "total": "Total",
+    "unknownTime": "Unknown time",
+    "view": "View",
+    "viewJson": "View JSON",
+    "widgetViewUnavailable": "Widget view unavailable."
+  },
+  "app": {
+    "name": "Invoke AI",
+    "nameWithVersion": "{{name}} {{version}}"
+  },
+  "auth": {
+    "account": "Account",
+    "accountSettings": "Account settings",
+    "accountUpdated": "Account updated",
+    "administrator": "Administrator",
+    "changePassword": "Change password",
+    "confirmNewPassword": "Confirm new password",
+    "confirmPassword": "Confirm password",
+    "couldNotCreateAdmin": "Could not create the administrator account.",
+    "couldNotUpdateAccount": "Could not update your account.",
+    "createAdminAccount": "Create administrator account",
+    "currentPassword": "Current password",
+    "displayNameHelp": "Optional — shown instead of your email.",
+    "hidePassword": "Hide password",
+    "keepSignedIn": "Keep me signed in for a week",
+    "leaveBlankKeepPassword": "Leave blank to keep your password.",
+    "password": "Password",
+    "passwordGeneratedDescription": "Reveal it with the eye icon and store it somewhere safe.",
+    "passwordStrength": {
+      "moderate": "Moderate",
+      "strong": "Strong",
+      "weak": "Weak"
+    },
+    "profileDisplayNameHelp": "Shown instead of your email across the workspace.",
+    "sessionExpired": "Your session expired. Sign in again to continue.",
+    "setupFooter": "You can add more users later from the user menu.",
+    "setupSubtitle": "Create the administrator account to get started.",
+    "setupTitle": "Set up Invoke",
+    "showPassword": "Show password",
+    "signIn": "Sign in",
+    "signInFailed": "Sign-in failed. Check your email and password.",
+    "signInSubtitle": "Sign in to your workspace to continue.",
+    "signedInAs": "Signed in as {{email}}",
+    "signOut": "Sign out",
+    "welcomeTitle": "Welcome to Invoke",
+    "yourPassword": "Your password"
+  },
+  "splash": {
+    "artworkBy": "Artwork by {{artist}}",
+    "copyright": "© {{year}} Invoke AI | All rights reserved",
+    "loadingApplication": "Loading Application",
+    "loadingWorkspace": "Loading workspace",
+    "openingProject": "Opening project",
+    "tagline": "Image Generation for Creatives"
+  },
+  "notifications": {
+    "empty": "Successful operations, errors, and system messages appear here.",
+    "labelWithCount": "Notifications: {{label}}",
+    "newCount_one": "{{count}} new",
+    "newCount_other": "{{count}} new",
+    "totalCount_one": "{{count}} total",
+    "totalCount_other": "{{count}} total",
+    "kind": {
+      "error": "Error",
+      "info": "Info",
+      "success": "Success"
+    },
+    "markRead": "Mark Read"
+  },
+  "projects": {
+    "allSavedAlreadyOpen": "All saved projects are already open.",
+    "closeProjectLabel": "Close {{name}}",
+    "couldNotOpen": "Could not open project",
+    "couldNotOpenDescription": "\"{{name}}\" could not be loaded from the server.",
+    "createNewProject": "Create new project",
+    "deleteFailed": "Delete failed",
+    "deleteProject": "Delete project",
+    "deleteProjectQuestion": "Delete project?",
+    "deleteProjectCardBody": "Delete \"{{name}}\"? The project is removed from the server permanently.",
+    "deleteProjectTabBody": "Delete \"{{name}}\"? The project and its saved copy on the server are removed permanently. To keep it in your library, close the tab instead.",
+    "deleteProjectWithEllipsis": "Delete project…",
+    "duplicateFailed": "Duplicate failed",
+    "editedRelative": "Edited {{time}}",
+    "exportFailed": "Export failed",
+    "failedToLoad": "Failed to load your projects.",
+    "importFailed": "Import failed",
+    "importWithEllipsis": "Import…",
+    "newProject": "New project",
+    "noSavedProjects": "No saved projects yet.",
+    "openProject": "Open project",
+    "openProjectLabel": "Open {{name}}",
+    "projectDetails": "Project details",
+    "renameFailed": "Rename failed",
+    "renameWithEllipsis": "Rename…",
+    "projectDuplicated": "Project duplicated",
+    "projectDuplicatedDescription": "\"{{name}}\" was created."
+  },
+  "users": {
+    "accountCount_one": "{{count}} account in this workspace.",
+    "accountCount_other": "{{count}} accounts in this workspace.",
+    "activeLabel": "{{name}} active",
+    "addUser": "Add user",
+    "admin": "Admin",
+    "adminOnly": "User management is available to administrators only.",
+    "administrator": "Administrator",
+    "administratorHelp": "Can manage users and all workspace settings.",
+    "backendRejectedChange": "The backend rejected the change.",
+    "backendRejectedRequest": "The backend rejected the request.",
+    "cannotChangeSelfRole": "You cannot change your own role.",
+    "cannotDeactivateSelf": "You cannot deactivate your own account.",
+    "cannotDeleteSelf": "You cannot delete your own account.",
+    "couldNotActivate": "Could not activate the user",
+    "couldNotCreate": "Could not create the user.",
+    "couldNotDeactivate": "Could not deactivate the user",
+    "couldNotDelete": "Could not delete the user",
+    "couldNotGeneratePassword": "Could not generate a password",
+    "couldNotLoad": "Could not load users.",
+    "couldNotUpdate": "Could not update the user.",
+    "createUser": "Create user",
+    "created": "User created",
+    "deleted": "User deleted",
+    "deleteBody": "Delete {{name}}? Their account is removed permanently.",
+    "deleteTitle": "Delete user?",
+    "deleteUser": "Delete user",
+    "deleteUserNamed": "Delete {{name}}",
+    "description": "Manage workspace accounts and roles.",
+    "displayName": "Display name",
+    "displayNameHelp": "Optional — shown instead of the email.",
+    "editUser": "Edit user",
+    "editUserNamed": "Edit {{name}}",
+    "email": "Email",
+    "generate": "Generate",
+    "lastSignIn": "Last sign-in",
+    "leaveBlankPassword": "Leave blank to keep the current password.",
+    "manageUsers": "Manage users",
+    "management": "User management",
+    "never": "Never",
+    "newPassword": "New password",
+    "password": "Password",
+    "passwordGenerated": "Password generated",
+    "passwordGeneratedDescription": "Reveal it with the eye icon and share it with the user securely.",
+    "role": "Role",
+    "saveChanges": "Save changes",
+    "thisUser": "this user",
+    "title": "Users",
+    "updated": "User updated",
+    "user": "User",
+    "you": "You"
+  },
+  "graphPreview": {
+    "graphJsonLabel": "{{title}} graph JSON",
+    "inputCount_one": "{{count}} input",
+    "inputCount_other": "{{count}} inputs",
+    "invokeRoute": "Invoke {{route}}",
+    "noCompiledGraph": "No compiled graph is available for \"{{graphId}}\" yet.",
+    "nodes": "Nodes",
+    "title": "{{title}} Graph Preview"
+  },
+  "hotkeys": {
+    "addHotkey": "Add hotkey",
+    "bindings": "Hotkey bindings",
+    "cancelEdit": "Cancel hotkey edit",
+    "categories": {
+      "app": "App",
+      "canvas": "Canvas",
+      "gallery": "Gallery",
+      "viewer": "Viewer",
+      "workflows": "Workflows"
+    },
+    "conflictsWith": "Conflicts with {{title}}",
+    "custom": "Custom",
+    "deleteHotkey": "Delete hotkey",
+    "description": "Account-bound keybinds. Project-level overrides can layer on later without changing hotkey ids.",
+    "disable": "Disable",
+    "disabled": "Disabled",
+    "duplicateBinding": "Duplicate binding in this hotkey",
+    "pending": "Pending",
+    "pressKeys": "Press keys",
+    "resetAll": "Reset all",
+    "resetHotkey": "Reset hotkey",
+    "saveEdit": "Save hotkey edit",
+    "searchPlaceholder": "Search hotkeys",
+    "title": "Hotkeys"
+  },
+  "models": {
+    "accessToken": "Access Token",
+    "accessTokenForDownload": "Access token for this download",
+    "accessTokenHelp": "Attached to the next Pull only. For saved HuggingFace, Civitai, and provider keys, use the API Keys tab.",
+    "accessTokenPlaceholder": "Only needed for protected sources",
+    "actions": "Model actions",
+    "addImage": "Add image",
+    "addModels": "Add Models",
+    "addModelsResults": "Add models results",
+    "addTriggerPhrase": "Add a trigger phrase...",
+    "allBases": "All bases",
+    "allModels": "All models",
+    "apiKey": "API key",
+    "apiKeyConfigured": "API key configured",
+    "apiKeyFor": "{{title}} API key",
+    "apiKeys": "API Keys",
+    "apiKeysDescription": "Keys are used when installing protected models and when generating with external API models.",
+    "base": "Base",
+    "baseArchitecture": "Base Architecture",
+    "baseUrlFor": "{{title}} base URL",
+    "backendDisconnectedProgressStale": "Backend disconnected. Progress may be stale.",
+    "bundleInstallQueued": "Bundle install queued",
+    "bundleInstallQueuedDescription_one": "{{name}}: {{count}} install queued.",
+    "bundleInstallQueuedDescription_other": "{{name}}: {{count}} installs queued.",
+    "bytePlusApiKeyPlaceholder": "API key from BytePlus console",
+    "bulkDeleteBody_one": "Delete {{count}} selected model? Database records are removed, and files inside the InvokeAI models directory are deleted.",
+    "bulkDeleteBody_other": "Delete {{count}} selected models? Database records are removed, and files inside the InvokeAI models directory are deleted.",
+    "bulkDeleteConfirm_one": "Delete {{count}} Model",
+    "bulkDeleteConfirm_other": "Delete {{count}} Models",
+    "bulkDeleteFailed": "Bulk delete failed",
+    "bulkDeletePartialDescription": "{{deleted}} deleted; {{failed}} failed: {{error}}",
+    "cacheEmptied": "Model cache emptied",
+    "cleanupOrphaned": "Clean up orphaned models…",
+    "clearSelection": "Clear selection",
+    "convert": "Convert",
+    "convertBody": "Convert \"{{name}}\" to the diffusers format in place? The original checkpoint file is replaced by a diffusers folder.",
+    "convertToDiffusers": "Convert to diffusers",
+    "couldNotLoad": "Could not load models",
+    "couldNotLoadInstallQueue": "Could not load the install queue",
+    "couldNotLoadStarterModels": "Could not load starter models",
+    "customizedForThisModel": "Customized for this model",
+    "customizeDefaultField": "Customize {{field}} for this model",
+    "civitaiKey": "Civitai key",
+    "civitaiKeyDescription": "Attached automatically when installing civitai.com models that require login. Stored in this browser only.",
+    "civitaiKeyPlaceholder": "32-character key from civitai.com/user/account",
+    "cancelAllInstalls": "Cancel all installs",
+    "cancelFailed": "Cancel failed",
+    "cancelInstall": "Cancel install",
+    "clearFinished": "Clear finished",
+    "defaultFieldInherited": {
+      "cfgRescale": "App default: 0 (off)",
+      "cfgScale": "App default: 7",
+      "guidance": "Uses the generator default",
+      "height": "App default: 1024",
+      "preprocessor": "Chosen automatically per image",
+      "scheduler": "App default: euler_a",
+      "steps": "App default: 30",
+      "vaePrecision": "App default: fp16",
+      "weight": "App default: 0.75",
+      "width": "App default: 1024"
+    },
+    "defaultFields": {
+      "cfgRescale": "CFG Rescale",
+      "cfgScale": "CFG Scale",
+      "guidance": "Guidance",
+      "height": "Height",
+      "preprocessor": "Preprocessor",
+      "scheduler": "Scheduler",
+      "steps": "Steps",
+      "vaePrecision": "VAE Precision",
+      "weight": "Weight",
+      "width": "Width"
+    },
+    "defaultSettings": "Default Settings",
+    "defaultSettingsHelp": "Applied automatically when this model is selected. Off = use the app default.",
+    "defaultSettingsSaved": "Default settings saved",
+    "deleteBody": "Delete \"{{name}}\"? The database record is removed, and the model files are deleted if they live inside the InvokeAI models directory.",
+    "deleteModel": "Delete model",
+    "deleted": "Models deleted",
+    "deletedDescription_one": "{{count}} model deleted.",
+    "deletedDescription_other": "{{count}} models deleted.",
+    "deleteSelectedTitle": "Delete selected models",
+    "deleteSelectedWithBytes": "Delete Selected ({{bytes}})",
+    "description": "Description",
+    "details": "Model Details",
+    "dismissResults": "Dismiss results",
+    "dismissScanResults": "Dismiss scan results",
+    "downloadProgress": "Download progress",
+    "editing": "Editing",
+    "emptyCache": "Empty model cache",
+    "failedToEmptyCache": "Failed to empty model cache",
+    "failedToLinkModels": "Failed to link models.",
+    "failedToLoadExternalProviders": "Failed to load external providers.",
+    "failedToLoadRelatedModels": "Failed to load related models.",
+    "failedToRemoveModelImage": "Failed to remove model image.",
+    "failedToSaveDefaults": "Failed to save default settings.",
+    "failedToScanOrphaned": "Failed to scan for orphaned models.",
+    "failedToUnlink": "Failed to unlink models.",
+    "failedToUpdateTriggerPhrases": "Failed to update trigger phrases.",
+    "failedToUploadModelImage": "Failed to upload model image.",
+    "fileNotFoundOnDisk": "The file for this model was not found on disk.",
+    "fileCount_one": "{{count}} file",
+    "fileCount_other": "{{count}} files",
+    "filesInRepo_one": "{{count}} file in {{repo}}",
+    "filesInRepo_other": "{{count}} files in {{repo}}",
+    "fileSize": "File Size",
+    "filterAndSortStarterModels": "Filter and sort starter models",
+    "filterFiles": "Filter files",
+    "filterAndSort": "Filter and sort models",
+    "filterResults": "Filter results",
+    "hash": "Hash",
+    "huggingFaceKeyDescription": "For gated repos like FLUX. Stored on the InvokeAI server and verified with HuggingFace.",
+    "huggingFaceRejectedToken": "HuggingFace rejected this token. Check that it has read access.",
+    "huggingFaceToken": "HuggingFace token",
+    "installAll": "Install all",
+    "installAllCount": "Install all ({{count}})",
+    "installFailed": "Install failed",
+    "installJobs": "Install jobs",
+    "installJobSummary_one": "{{count}} job · no active installs",
+    "installJobSummary_other": "{{count}} jobs · no active installs",
+    "installInPlace": "Install in place",
+    "installQueue": "Install Queue",
+    "installed": "Installed",
+    "installsDependencies_one": " (installs {{count}} dependency)",
+    "installsDependencies_other": " (installs {{count}} dependencies)",
+    "invalidDefaultSettings": "Invalid default settings.",
+    "invalidTriggerPhrase": "Invalid trigger phrase.",
+    "keyStatus": {
+      "configured": "Configured",
+      "invalid": "Invalid",
+      "saved": "Saved",
+      "unknown": "Not set",
+      "valid": "Valid"
+    },
+    "library": "Model library",
+    "libraryMaintenance": "Model library maintenance",
+    "manager": "Model Manager",
+    "manageApiKeys": "Manage API keys",
+    "missingFilesCount": "Missing files ({{count}})",
+    "modelAndDependenciesQueued_one": "{{name}} and {{count}} dependency",
+    "modelAndDependenciesQueued_other": "{{name}} and {{count}} dependencies",
+    "modelCoverAlt": "{{name}} cover",
+    "modelImage": "Model image",
+    "modelImageUpdated": "Model image updated",
+    "modelInstallQueued": "Model install queued",
+    "modelManager": "Model manager",
+    "modelUpdated": "Model updated",
+    "modelType": "Model Type",
+    "noInstallableModelFiles": "This HuggingFace repo has no installable model files.",
+    "noInstallsDescription": "Model installs appear here while they download and import.",
+    "noInstallsYet": "No installs yet",
+    "noModelFilesFound": "No model files found in {{path}}.",
+    "noModelFilesFoundTitle": "No model files found",
+    "noRelatedModels": "No related models linked yet.",
+    "noStarterModelsPull": "No starter models match - press Pull to install the source you entered.",
+    "noStarterModelsSearch": "No starter models match your search.",
+    "noneInstalled": "No models installed",
+    "noneInstalledDescription": "Use Add Models to install your first model.",
+    "noneMatchFilters": "No models match your filters",
+    "noneMatchFiltersDescription": "Try clearing the search or filters.",
+    "noOrphaned": "No orphaned model folders found — your library is clean.",
+    "orphanedCleanup": "Orphaned model cleanup",
+    "orphanedCleanupFailed": "Orphaned model cleanup failed",
+    "orphanedCleanupPartialDescription": "{{deleted}} deleted, {{failed}} failed: {{error}}",
+    "orphanedDeletedDescription_one": "{{count}} orphaned model folder deleted.",
+    "orphanedDeletedDescription_other": "{{count}} orphaned model folders deleted.",
+    "orphanedDescription": "Folders in the models directory with no database record — usually leftovers from failed installs or external deletes.",
+    "orphanedTitle": "Orphaned Models",
+    "predictionType": "Prediction Type",
+    "overrideBaseUrl": "Override base URL",
+    "path": "Path",
+    "pauseAllDownloads": "Pause all downloads",
+    "pauseAllInstalls": "Pause all installs",
+    "pauseDownload": "Pause download",
+    "pauseFailed": "Pause failed",
+    "pauseInstall": "Pause install",
+    "plusMore": " +{{count}} more",
+    "pruneFailed": "Prune failed",
+    "press": "Press",
+    "pull": "Pull",
+    "queueActionFailed": "Queue action failed",
+    "refreshList": "Refresh model list",
+    "reidentify": "Re-identify model",
+    "relatedModels": "Related Models",
+    "relatedModelsHelp": "Link the models that pair well with this one - they are suggested together elsewhere in the app.",
+    "removeImage": "Remove image",
+    "removeModelImage": "Remove model image",
+    "removeTriggerPhrase": "Remove trigger phrase {{phrase}}",
+    "restartFile": "Restart file",
+    "restartFileFailed": "Restart file failed",
+    "restartThisFile": "Restart this file",
+    "resumeAllInstalls": "Resume all installs",
+    "resumeAllPausedDownloads": "Resume all paused downloads",
+    "resumeDownload": "Resume download",
+    "resumeFailed": "Resume failed",
+    "resumeInstall": "Resume install",
+    "resumeRequired": "Resume required",
+    "retryFailed": "Retry failed",
+    "retryFailedDownload": "Retry failed download",
+    "retryInstall": "Retry install",
+    "saveDefaults": "Save Defaults",
+    "scan": "Scan",
+    "scanFailed": "Scan failed",
+    "scanFolderTooltip": "Scan this folder for model files",
+    "scanSummary_one": "{{count}} file in {{path}} · {{notInstalled}} not installed",
+    "scanSummary_other": "{{count}} files in {{path}} · {{notInstalled}} not installed",
+    "searchModels": "Search models",
+    "searchModelsPlaceholder": "Search models…",
+    "searchCompatibleToLink": "Search compatible models to link...",
+    "searchOrAdd": "Search or add a model",
+    "searchOrAddPlaceholder": "Search models, or paste a URL, file path, or Hugging Face repo",
+    "selectAllCount": "Select all ({{count}})",
+    "selectedCount_one": "{{count}} selected",
+    "selectedCount_other": "{{count}} selected",
+    "selectModel": "Select a model",
+    "selectModelDescription": "Pick a model from the library to view details, edit metadata, set per-model defaults, and manage trigger phrases.",
+    "someCouldNotBeDeleted": "Some models could not be deleted",
+    "sortBase": "Base",
+    "sortDefault": "Default",
+    "sortFormat": "Format",
+    "sortName": "Name",
+    "sortSize": "Size",
+    "sort": {
+      "base": "Base",
+      "default": "Default",
+      "format": "Format",
+      "name": "Name",
+      "size": "Size"
+    },
+    "sortBy": "Sort By",
+    "source": "Source",
+    "sourceUrl": "Source URL",
+    "sourceUrlHelp": "Model page or download URL.",
+    "title": "Models",
+    "toFindModelsInFolder": "to find models in this folder.",
+    "toInstallFrom": "to install from {{source}}.",
+    "type": "Type",
+    "triggerPhraseDuplicate": "That trigger phrase is already on this model.",
+    "triggerPhrases": "Trigger Phrases",
+    "triggerPhrasesHelp": "Phrases that activate this model, surfaced in the prompt editor.",
+    "unlink": "Unlink",
+    "unlinkNamed": "Unlink {{name}}",
+    "uploadCoverImageFor": "Upload cover image for {{name}}",
+    "useSupportedImage": "Use a PNG, JPEG, or WebP image.",
+    "variant": "Variant",
+    "variantHelp": "Architecture variant, e.g. inpaint or dev.",
+    "waitingForDownload": "Waiting for download"
+  },
+  "nodes": {
+    "addCustomNodes": "Add custom nodes",
+    "addNodes": "Add Nodes",
+    "couldNotReloadCustomNodes": "Could not reload custom nodes.",
+    "couldNotLoadPacks": "Could not load custom node packs",
+    "customNodesReloaded": "Custom nodes reloaded",
+    "dependenciesRequired": "Dependencies required",
+    "dependenciesRequiredDescription": "{{name}} requires dependencies from {{dependencyFile}}. Install them, then restart InvokeAI.",
+    "details": "Node Pack Details",
+    "fieldName": "Field: {{name}}",
+    "fieldType": "Type: {{type}}",
+    "gitUrl": "Git URL",
+    "gitUrlHelp": "Paste a public Git repository URL. InvokeAI clones it into your custom nodes directory.",
+    "input": "Input",
+    "install": "Install",
+    "installActivity": "Custom node install activity",
+    "installFailed": "Install failed.",
+    "installing": "Installing",
+    "installedPacks": "Installed custom node packs",
+    "manager": "Nodes Manager",
+    "message": "Message",
+    "nodeCategory": "Category: {{category}}",
+    "nodeCount_one": "{{count}} node",
+    "nodeCount_other": "{{count}} nodes",
+    "nodePack": "node pack",
+    "nodePacks": "Node Packs",
+    "nodeType": "Type: {{type}}",
+    "nodeVersion": "Version: {{version}}",
+    "nodesDirectory": "Nodes Directory",
+    "nodesInPack": "Nodes in this pack",
+    "noPacks": "No custom node packs",
+    "noPacksDescription": "Install from a Git URL or place packs in your custom nodes directory, then reload.",
+    "noPacksMatch": "No packs match",
+    "noPreviews": "No node previews available",
+    "noPreviewsDescription": "The backend has no node definitions for this pack yet. Reload nodes or restart InvokeAI to load them.",
+    "noRecentActivity": "No recent activity",
+    "noRecentActivityDescription": "Install or uninstall a node pack and the outcome shows up here.",
+    "output": "Output",
+    "recentActivitySummary_one": "{{count}} recent activity",
+    "recentActivitySummary_other": "{{count}} recent activities",
+    "reloadFailed": "Reload failed",
+    "reloading": "Reloading",
+    "scanFolder": "Scan Folder",
+    "scanFolderDescription": "Add node packs directly to the custom nodes directory, then reload nodes. InvokeAI scans this folder on startup and reload.",
+    "searchPacks": "Search node packs",
+    "searchPacksPlaceholder": "Search packs…",
+    "selectPack": "Select a node pack",
+    "selectPackDescription": "Choose a pack from the library to see its path, manage it, and preview every node it adds.",
+    "status": "Status",
+    "trustWarning": "Custom nodes execute Python code. Only install packs from authors you trust.",
+    "tryDifferentSearch": "Try a different search.",
+    "uninstall": "Uninstall",
+    "uninstallBody": "Remove this pack from the custom nodes directory? A restart is required for removal to fully apply.",
+    "uninstallPack": "Uninstall Node Pack",
+    "uninstallTitle": "Uninstall {{name}}?",
+    "uninstalled": "Uninstalled"
+  },
+  "launchpad": {
+    "projectsGreeting": "Welcome to Invoke",
+    "projectsGreetingWithName": "Welcome back, {{name}}",
+    "projectsSubtitle": "Pick up where you left off, or start something new.",
+    "sections": {
+      "models": "Models",
+      "nodes": "Nodes",
+      "projects": "Projects",
+      "users": "Users"
+    },
+    "sectionsLabel": "Launchpad sections"
+  },
+  "settings": {
+    "title": "Settings",
+    "descriptionGlobal": "Global preferences for this single-user install. Project settings apply only to the active project.",
+    "descriptionUser": "Preferences for the signed-in user. Project settings apply only to the active project.",
+    "enableHighlightFocusedRegions": "Highlight focused region",
+    "language": "Language",
+    "languageDescription": "Interface language. New workbench copy falls back to English until translators add coverage.",
+    "tabs": {
+      "appearance": "Appearance",
+      "behavior": "Behavior",
+      "developer": "Developer",
+      "hotkeys": "Hotkeys",
+      "project": "Project",
+      "queue": "Queue",
+      "workflow": "Workflow",
+      "workspace": "Workspace"
+    }
+  },
+  "shell": {
+    "addCurrentLayout": "Add current layout...",
+    "builtInPresets": "Built-in presets",
+    "customLayout": "Custom layout {{number}}",
+    "customPresets": "Custom presets",
+    "deleteLayoutPreset": "Delete preset",
+    "deleteLayoutPresetBody": "Delete \"{{name}}\"? This only removes the saved preset.",
+    "deleteLayoutPresetQuestion": "Delete layout preset?",
+    "layoutPresetName": "Preset name",
+    "renameLayoutPreset": "Rename layout preset"
+  },
+  "widgets": {
+    "actionsLabel": "{{label}} actions",
+    "removeWidget": "Remove {{label}}",
+    "resizePanel": "Resize {{region}} widget panel",
+    "settingsLabel": "{{label}} settings",
+    "visibilityLabel": "{{region}} widget visibility",
+    "groupLabel": "Widgets",
+    "labels": {
+      "autosaveStatus": "Autosave",
+      "canvas": "Canvas",
+      "diagnostics": "Diagnostics",
+      "gallery": "Gallery",
+      "generate": "Generate",
+      "layers": "Layers",
+      "notifications": "Notifications",
+      "preview": "Preview",
+      "project": "Project",
+      "queue": "Queue",
+      "serverStatus": "Server Status",
+      "versionStatus": "Version",
+      "workflow": "Workflow"
+    },
+    "generate": {
+      "addPromptTrigger": "Add prompt trigger",
+      "activeCount_one": "{{count}} active",
+      "activeCount_other": "{{count}} active",
+      "advanced": "Advanced",
+      "addConcept": "Add concept",
+      "addConceptsHelp": "Add LoRAs/concepts here to blend them into this generation.",
+      "aspectRatio": "Aspect ratio",
+      "cfgRescale": "CFG rescale",
+      "clipSkip": "CLIP skip",
+      "colorCompensation": "Color compensation",
+      "components": "Components",
+      "compositing": "Compositing",
+      "concepts": "Concepts",
+      "conceptWeight": "{{name}} weight",
+      "compatibleEmbeddings": "Compatible embeddings",
+      "couldNotExpandPrompt": "Could not expand the prompt.",
+      "couldNotGeneratePromptFromImage": "Could not generate a prompt from the selected image.",
+      "deletePromptHistoryItem": "Delete prompt history item",
+      "denoisingStrength": "Denoising strength",
+      "denoisingStrengthHelp": "How much the generation reworks the existing canvas content. Only applies to image-to-image (when content fills the generation frame).",
+      "dimensions": "Dimensions",
+      "disableConcept": "Disable {{name}}",
+      "enableNegativePrompt": "Enable negative prompt",
+      "enableConcept": "Enable {{name}}",
+      "expand": "Expand",
+      "expandPrompt": "Expand prompt",
+      "generatePrompt": "Generate Prompt",
+      "imageToPrompt": "Image to prompt",
+      "height": "Height",
+      "incompatible": "Incompatible",
+      "incompatibleSettingsCleared": "Incompatible settings cleared",
+      "incompatibleSettingsClearedDescription_one": "{{labels}} was not compatible with {{name}}.",
+      "incompatibleSettingsClearedDescription_other": "{{labels}} were not compatible with {{name}}.",
+      "installTextLlmToExpandPrompts": "Install a Text LLM model to expand prompts.",
+      "installVisionModelToGeneratePrompts": "Install a LLaVA OneVision model to generate prompts from images.",
+      "lockAspectRatio": "Lock aspect ratio",
+      "mainModel": "Main model",
+      "model": "Model",
+      "modelDefault": "Model default",
+      "multipleOf": "Multiple of {{value}}",
+      "negativePrompt": "Negative prompt",
+      "noMatchingPrompts": "No matching prompts.",
+      "noMatchingTriggers": "No matching triggers.",
+      "noPromptHistoryYet": "No prompt history yet.",
+      "noPromptTriggersAvailable": "No prompt triggers available.",
+      "noTextLlmInstalled": "No Text LLM installed",
+      "noVisionModelInstalled": "No vision model installed",
+      "offCount_one": "{{count}} off",
+      "offCount_other": "{{count}} off",
+      "positivePrompt": "Positive prompt",
+      "promptHistory": "Prompt history",
+      "promptHistoryEntries": "Prompt history entries",
+      "promptHistoryKeyboardHelp": "Alt+Up/Down switches between prompts while focused.",
+      "promptTemplate": "Prompt Template",
+      "promptTriggerOptions": "Prompt trigger options",
+      "random": "Random",
+      "activeSteps": "Active steps",
+      "clearReferenceImages": "Remove all",
+      "collapseReferenceImage": "Collapse reference image",
+      "cropReferenceImage": "Crop reference image",
+      "cropReferenceImageHelp": "Drag the crop box to move it, or drag its handles to resize. Apply to create a cropped reference image.",
+      "disableReferenceImage": "Disable reference image",
+      "enableReferenceImage": "Enable reference image",
+      "expandReferenceImage": "Expand reference image",
+      "imageInfluence": "Image influence",
+      "mode": "Mode",
+      "modeBoth": "Both",
+      "modeComposition": "Composition",
+      "modeStyle": "Style",
+      "pullBboxIntoReferenceImage": "Pull Bbox into Reference Image",
+      "referenceImage": "Reference Image",
+      "referenceImageModel": "Reference image model",
+      "referenceImages": "Reference images",
+      "referenceImagesHelp": "Upload an image or drag images from Gallery here.",
+      "referenceImagesUnsupported": "Reference images are not supported by the selected model.",
+      "removeReferenceImage": "Remove reference image",
+      "styleVariant": "Style variant",
+      "styleVariantPrecise": "Precise",
+      "styleVariantPreciseDesc": "Applies a precise visual style, eliminating subject influence.",
+      "styleVariantStandard": "Standard",
+      "styleVariantStandardDesc": "Applies visual style (colors, textures) without considering its layout. Previously called Style Only.",
+      "styleVariantStrong": "Strong",
+      "styleVariantStrongDesc": "Applies a strong visual style, with a slightly reduced composition influence.",
+      "useSize": "Use size",
+      "removeConcept": "Remove concept",
+      "removeConceptNamed": "Remove {{name}}",
+      "resizeNegativePrompt": "Resize negative prompt",
+      "resizePositivePrompt": "Resize positive prompt",
+      "scheduler": "Scheduler",
+      "searchPromptHistory": "Search prompt history",
+      "searchPromptTriggers": "Search prompt triggers",
+      "searchCompatibleConcepts": "Search compatible concepts...",
+      "seamlessTiling": "Seamless tiling",
+      "selectImageFirst": "Select an image in Gallery or Preview first.",
+      "selectMainModelBeforeConcepts": "Select a main model before adding concepts.",
+      "selectModel": "Select a model…",
+      "selectModelFirst": "Select a model first",
+      "selectTextLlm": "Select Text LLM",
+      "selectVisionModel": "Select vision model",
+      "setOptimalSize": "Set optimal size",
+      "setOptimalSizeDescription": "Set size to the model's optimal pixel count",
+      "shuffleSeed": "Shuffle seed",
+      "showDynamicPrompts": "Show dynamic prompts",
+      "steps": "Steps",
+      "swapWidthAndHeight": "Swap width and height",
+      "tileX": "Tile X",
+      "tileY": "Tile Y",
+      "unlockAspectRatio": "Unlock aspect ratio",
+      "useModelDefault": "Use model default",
+      "useConceptDefaultWeight": "Use concept default weight",
+      "useModelDefaultCfgRescale": "Use model default CFG rescale",
+      "useModelDefaultField": "Use model default {{field}}",
+      "useModelDefaultHeight": "Use model default height",
+      "useModelDefaultScheduler": "Use model default scheduler",
+      "useModelDefaultSteps": "Use model default steps",
+      "useModelDefaultVae": "Use model default VAE",
+      "useModelDefaultVaePrecision": "Use model default VAE precision",
+      "useModelDefaultWidth": "Use model default width",
+      "usePrompt": "Use prompt",
+      "usingBundledVae": "Using the VAE bundled with the model.",
+      "upload": "Upload",
+      "vae": "VAE",
+      "vaePrecision": "VAE precision",
+      "weight": "Weight",
+      "width": "Width",
+      "xAxis": "X axis",
+      "yAxis": "Y axis",
+      "compositingOptions": {
+        "infillMethod": "Infill method",
+        "infillMethods": {
+          "patchmatch": "PatchMatch",
+          "lama": "LaMa",
+          "cv2": "OpenCV",
+          "color": "Solid color",
+          "tile": "Tile"
+        },
+        "coherenceMode": "Coherence pass mode",
+        "coherenceModes": {
+          "Gaussian Blur": "Gaussian Blur",
+          "Box Blur": "Box Blur",
+          "Staged": "Staged"
+        },
+        "coherenceEdgeSize": "Coherence edge size",
+        "coherenceMinDenoise": "Coherence min denoise",
+        "maskBlur": "Mask blur"
+      }
+    },
+    "graph": {
+      "setSource": "Set Source",
+      "viewGraph": "View Graph"
+    },
+    "project": {
+      "copyId": "Copy project id",
+      "deleteRecovery": "Delete recovery",
+      "deleteRecoveryAria": "Delete {{name}}",
+      "deleteRecoveryBody": "Delete \"{{name}}\"? The recovery copy is removed permanently.",
+      "deleteRecoveryTitle": "Delete recovery?",
+      "events": "Events",
+      "graphNodes": "Graph nodes",
+      "idCopied": "Project id copied",
+      "nameHelp": "Saved with the project.",
+      "nameLabel": "Project name",
+      "openOriginal": "Open original \"{{name}}\"",
+      "openRecovery": "Open {{name}}",
+      "queueItems": "Queue items",
+      "recoveries": "Recoveries",
+      "recoveryCopy": "Recovery copy",
+      "recoveryForkedDescription": "Forked {{time}} after this project was changed elsewhere.",
+      "sync": "Sync",
+      "syncOffline": "Offline — saved in this browser",
+      "syncSynced": "Synced (revision {{revision}})",
+      "syncWaiting": "Waiting to sync"
+    },
+    "preview": {
+      "commands": {
+        "deletePreviewImage": "Delete preview image",
+        "nextComparisonMode": "Next comparison mode",
+        "swapComparisonImages": "Swap comparison images",
+        "togglePreview": "Toggle preview"
+      },
+      "compare": "Compare",
+      "emptyDescription": "Generate to Gallery, then select a thumbnail in the Gallery widget to inspect it here.",
+      "exitCompare": "Exit Compare",
+      "hideInProgressDiffusion": "Hide in-progress diffusion",
+      "imageCount_one": "{{count}} image",
+      "imageCount_other": "{{count}} images",
+      "loadingBoard": "Loading board",
+      "nextImageInBoard": "Next image in board",
+      "noGallerySelection": "No gallery selection",
+      "previousImageInBoard": "Previous image in board",
+      "showInProgressDiffusion": "Show in-progress diffusion",
+      "sideBySide": "Side by Side",
+      "slider": "Slider",
+      "sourceRun": "Source run {{id}}",
+      "viewing": "Viewing"
+    },
+    "queue": {
+      "allScopedItemsRequested": "All scoped queue items were requested.",
+      "actionConfirmationTitle": "{{action}}?",
+      "backendItem": "Backend queue item {{id}}.",
+      "batch": "Batch",
+      "cancelAllExceptCurrent": "Cancel all except current item",
+      "cancelAllExceptCurrentRequested": "All pending scoped items except the current item were requested.",
+      "cancelAllItems": "Cancel All Items",
+      "cancelConfirmationBody": "This requests cancellation for queue work in the current scope. In-progress items may stop after the backend acknowledges cancellation.",
+      "cancelCurrent": "Cancel Current",
+      "cancelCurrentItem": "Cancel Current Item",
+      "cancelItem": "Cancel queue item #{{id}}",
+      "cancellationRequested": "Cancellation requested",
+      "clearAllItems": "Clear All Items",
+      "clearFailedConfirmationBody": "This permanently removes failed queue items in the current queue scope.",
+      "clearFailedItems": "Clear Failed Items",
+      "clearFailedTitle": "Clear failed queue items?",
+      "clearQueue": "Clear Queue",
+      "clearQueueConfirmationBody": "This permanently clears queue items in the current queue scope.",
+      "clearQueueTitle": "Clear queue?",
+      "couldNotCancelCurrentItem": "Could not cancel the current item.",
+      "couldNotCancelItem": "Could not cancel this item.",
+      "couldNotCancelItems": "Could not cancel scoped queue items.",
+      "couldNotChangeProcessor": "Could not change the queue processor.",
+      "couldNotClearFailedItems": "Could not clear failed queue items.",
+      "couldNotClearQueue": "Could not clear the queue.",
+      "currentBatch": "Current Batch",
+      "failedItemsCleared": "Failed queue items cleared",
+      "failedToCancelCurrentItem": "Failed to cancel current item",
+      "failedToCancelItems": "Failed to cancel queue items",
+      "failedToClearItems": "Failed to clear queue items",
+      "failedToClearQueue": "Failed to clear queue",
+      "failedToPauseProcessor": "Failed to pause processor",
+      "failedToResumeProcessor": "Failed to resume processor",
+      "filterRecentByStatus": "Filter recent queue items by status",
+      "generating_one": "{{count}} generating",
+      "generating_other": "{{count}} generating",
+      "itemJsonLabel": "Queue item {{id}} JSON",
+      "itemProgress": "Queue item progress",
+      "itemTitle": "Queue item #{{id}}",
+      "loadSettingsIntoGenerate": "Load these settings into Generate",
+      "loading": "Loading queue…",
+      "modelCache": {
+        "clear": "Clear cache",
+        "clearFailed": "Clear cache failed",
+        "cleared": "Model cache cleared",
+        "clearedDescription_one": "Cleared {{count}} cached model and freed {{bytes}}.",
+        "clearedDescription_other": "Cleared {{count}} cached models and freed {{bytes}}.",
+        "couldNotClear": "Could not clear the model cache.",
+        "hits": "Hits",
+        "label": "Model Cache",
+        "loaded": "Loaded",
+        "misses": "Misses",
+        "noModelsCleared": "No cached models cleared",
+        "noModelsClearedDescription": "No unlocked cached models were available to clear. Active models stay loaded until they are no longer in use.",
+        "usage": "Model cache usage",
+        "usedOfTotal": "{{used}} of {{total}} used"
+      },
+      "noCurrentItem": "No current item",
+      "noCurrentItemDescription": "The scoped queue has no in-progress item to cancel.",
+      "noPrompt": "No prompt",
+      "openQueue": "Open Queue",
+      "pauseProcessor": "Pause Processor",
+      "processorPaused": "Processor paused",
+      "processorResumed": "Processor resumed",
+      "queueCancellationRequested": "Queue cancellation requested",
+      "queueCleared": "Queue cleared",
+      "queued_one": "{{count}} queued",
+      "queued_other": "{{count}} queued",
+      "recallAll": "Recall All",
+      "recallFromGallery": "Recall this generation from the gallery",
+      "resumeProcessor": "Resume Processor",
+      "sendToCanvas": "Send to canvas",
+      "sendToCanvasComingSoon": "Sending queue results to the canvas is coming soon.",
+      "settingsRecalled": "Settings recalled",
+      "settingsRecalledDescription": "Loaded these settings into Generate.",
+      "took": "Took",
+      "waiting_one": "{{count}} waiting",
+      "waiting_other": "{{count}} waiting"
+    },
+    "autosaveStatus": {
+      "chipLabel": "Autosave: {{status}}",
+      "label": "Autosave",
+      "lastSaved": "Last saved: {{time}}",
+      "status": "Status: {{status}}"
+    },
+    "canvas": {
+      "acceptToLayer": "Accept to Layer",
+      "candidateCount": "{{current}} of {{total}}",
+      "commands": {
+        "decreaseBrushSize": "Decrease brush/eraser size",
+        "deleteLayer": "Delete layer",
+        "deleteSelected": "Delete selected canvas item",
+        "deselect": "Deselect",
+        "duplicateLayer": "Duplicate layer",
+        "fitBbox": "Fit generation frame",
+        "increaseBrushSize": "Increase brush/eraser size",
+        "invertSelection": "Invert selection",
+        "layerBackward": "Send layer backward",
+        "layerForward": "Bring layer forward",
+        "layerToBack": "Send layer to back",
+        "layerToFront": "Bring layer to front",
+        "mergeDown": "Merge layer down",
+        "nextEntity": "Next canvas entity",
+        "nudgeDown": "Nudge layer down",
+        "nudgeDownLarge": "Nudge layer down 10px",
+        "nudgeLeft": "Nudge layer left",
+        "nudgeLeftLarge": "Nudge layer left 10px",
+        "nudgeRight": "Nudge layer right",
+        "nudgeRightLarge": "Nudge layer right 10px",
+        "nudgeUp": "Nudge layer up",
+        "nudgeUpLarge": "Nudge layer up 10px",
+        "previousEntity": "Previous canvas entity",
+        "redo": "Redo canvas edit",
+        "reorderLayer": "Reorder layer",
+        "resetSelected": "Clear selected mask",
+        "selectAll": "Select all",
+        "selectBboxTool": "Select generation frame tool",
+        "selectBrushTool": "Select brush tool",
+        "selectEraserTool": "Select eraser tool",
+        "selectGradientTool": "Select gradient tool",
+        "selectLassoTool": "Select lasso tool",
+        "selectMoveTool": "Select move tool",
+        "selectShapeTool": "Select shape tool",
+        "selectTextTool": "Select text tool",
+        "selectTransformTool": "Select transform tool",
+        "selectViewTool": "Select view tool",
+        "undo": "Undo canvas edit"
+      },
+      "contextMenu": {
+        "empty": "This region has no visible raster content.",
+        "notReady": "The canvas is still preparing image data.",
+        "saveBboxToGallery": "Save BBox to Gallery",
+        "saveCanvasToGallery": "Save Canvas to Gallery",
+        "saveError": "Couldn't save to gallery",
+        "saveToGallery": "Save to Gallery",
+        "saved": "Saved to gallery",
+        "savedDescription": "{{name}} was added to your gallery.",
+        "stale": "The canvas changed while saving. Try again."
+      },
+      "controls": {
+        "fitBboxToLayers": "Fit frame to layers",
+        "fitBboxToMasks": "Fit frame to masks",
+        "fitToView": "Fit to view",
+        "frameSize": "Generation frame size",
+        "newCanvas": "New canvas",
+        "newCanvasConfirm": "Clear all layers and start a fresh canvas? This cannot be undone.",
+        "newSession": "New session",
+        "zoomLevel": "Zoom level"
+      },
+      "hideStagedResultPreview": "Hide staged result preview",
+      "hideStagingThumbnails": "Hide staging thumbnails",
+      "import": {
+        "blocked": "Finish the current canvas operation before adding images.",
+        "control": "Control Layer",
+        "dropControl": "Add as Control Layer",
+        "dropInpaintMask": "Add as Inpaint Mask",
+        "dropRaster": "Add as Raster Layer",
+        "dropRegionalReference": "Add as Regional Reference Image",
+        "dropResizedControl": "Add as Resized Control Layer",
+        "empty": "No gallery images were available to add.",
+        "failed": "Couldn't add images to canvas",
+        "inpaintMask": "Inpaint Mask",
+        "newLayerFromImage": "New Layer from Image",
+        "partial_one": "Added {{successCount}} image; {{failedCount}} could not be prepared.",
+        "partial_other": "Added {{successCount}} images; {{failedCount}} could not be prepared.",
+        "raster": "Raster Layer",
+        "regionalGuidance": "Regional Guidance",
+        "regionalReference": "Regional Reference Image",
+        "resizedControl": "Resized Control Layer",
+        "staleDocument": "The canvas changed while the images were being prepared. Try again.",
+        "staleProject": "The destination project was closed before the images were ready.",
+        "success_one": "Added {{count}} image as canvas layers",
+        "success_other": "Added {{count}} images as canvas layers"
+      },
+      "nextStagedCandidate": "Next staged candidate",
+      "previousStagedCandidate": "Previous staged candidate",
+      "selectStagedCandidate": "Select staged candidate {{number}}",
+      "settings": {
+        "bboxOverlay": "Show bbox overlay",
+        "checkerboard": "Checkerboard background",
+        "clearCaches": "Clear caches",
+        "clearHistory": "Clear history",
+        "grid": "Show grid",
+        "invertBrushScroll": "Invert scroll for brush size",
+        "label": "Canvas settings",
+        "logDebugInfo": "Log debug info",
+        "ruleOfThirds": "Rule of thirds",
+        "sections": {
+          "behavior": "Behavior",
+          "debug": "Debug",
+          "display": "Display",
+          "grid": "Grid"
+        },
+        "showBbox": "Show generation frame",
+        "showProgressOnCanvas": "Show progress on canvas",
+        "snapToGrid": "Snap to grid"
+      },
+      "showStagedResultPreview": "Show staged result preview",
+      "showStagingThumbnails": "Show staging thumbnails",
+      "staging": {
+        "autoSwitch": "Auto-switch",
+        "autoSwitchLatest": "Newest",
+        "autoSwitchOff": "Off",
+        "autoSwitchProgress": "In progress",
+        "generating": "Generating…",
+        "saveError": "Couldn't save to gallery",
+        "saveToGallery": "Save to gallery",
+        "saved": "Saved to gallery",
+        "savedDescription": "{{name}} added to your gallery."
+      },
+      "surface": "Canvas surface",
+      "toolOptions": {
+        "applyTransform": "Apply",
+        "aspectRatio": "Aspect ratio",
+        "brushColor": "Brush color",
+        "brushSize": "Brush size",
+        "cancelTransform": "Cancel",
+        "deselect": "Deselect",
+        "eraseSelection": "Erase",
+        "eraserSize": "Eraser size",
+        "fillSelection": "Fill",
+        "frameHeight": "H",
+        "frameWidth": "W",
+        "gradientAngle": "Angle",
+        "gradientEdit": "Edit gradient",
+        "gradientEnd": "End",
+        "gradientEndOpacity": "End opacity",
+        "gradientKind": "Gradient type",
+        "gradientLinear": "Linear",
+        "gradientRadial": "Radial",
+        "gradientStart": "Start",
+        "gradientStartOpacity": "Start opacity",
+        "invertSelection": "Invert",
+        "lassoHint": "Draw a shape to select. Shift adds, Alt subtracts.",
+        "lockAspect": "Lock aspect ratio",
+        "movePosition": "Move layer",
+        "opacity": "Opacity",
+        "positionX": "X",
+        "positionY": "Y",
+        "pressureSensitivity": "Pressure sensitivity",
+        "rotation": "Rotation",
+        "scaleHeight": "H %",
+        "scaleWidth": "W %",
+        "selectionAdd": "Add",
+        "selectionIntersect": "Intersect",
+        "selectionMode": "Selection mode",
+        "selectionReplace": "Replace",
+        "selectionSubtract": "Subtract",
+        "setFrame": "Set generation frame",
+        "shapeEdit": "Edit shape",
+        "shapeEllipse": "Ellipse",
+        "shapeFill": "Fill",
+        "shapeHint": "Drag to draw a shape.",
+        "shapeKind": "Shape type",
+        "shapeRect": "Rectangle",
+        "shapeStroke": "Stroke",
+        "shapeStrokeWidth": "Stroke width",
+        "textAlignCenter": "Align center",
+        "textAlignLeft": "Align left",
+        "textAlignRight": "Align right",
+        "textColor": "Text color",
+        "textEdit": "Edit text",
+        "textFont": "Font",
+        "textLineHeight": "Line height",
+        "textSize": "Font size",
+        "textWeight": "Weight"
+      },
+      "tools": {
+        "bbox": "Generation frame",
+        "brush": "Brush",
+        "eraser": "Eraser",
+        "gradient": "Gradient",
+        "label": "Tools",
+        "lasso": "Lasso select",
+        "move": "Move",
+        "shape": "Shape",
+        "text": "Text",
+        "transform": "Transform",
+        "view": "View"
+      }
+    },
+    "workflow": {
+      "about": "About",
+      "addNode": "Add node",
+      "author": "Author",
+      "class": "Class",
+      "connectorNode": "Connector node",
+      "contact": "Contact",
+      "copyJson": "Copy workflow JSON",
+      "copyJsonFailed": "Failed to copy workflow JSON",
+      "copyJsonSuccess": "Workflow JSON copied",
+      "currentImageNode": "Current Image node",
+      "declaredOutputs": "Declared outputs",
+      "description": "Description",
+      "details": "Details",
+      "detailsWithEllipsis": "Workflow details…",
+      "exportJson": "Export workflow JSON",
+      "form": "Form",
+      "graphHistorySnapshots": "Graph History Snapshots",
+      "importJsonWithEllipsis": "Import workflow JSON…",
+      "inspectorTabs": {
+        "data": "Data",
+        "details": "Details",
+        "outputs": "Outputs",
+        "template": "Template"
+      },
+      "library": "Workflow library",
+      "name": "Workflow name",
+      "nodeData": "Node data",
+      "nodeInspector": "Node Inspector",
+      "nodeNotes": "Node notes",
+      "nodeNotesPlaceholder": "Notes about this node…",
+      "nodeTemplate": "Node template",
+      "notes": "Notes",
+      "notesNode": "Notes node",
+      "noTemplateKnown": "No template is known for \"{{type}}\" on this backend.",
+      "pack": "Pack",
+      "panelContent": "Workflow panel content",
+      "resizeNodeInspector": "Resize node inspector",
+      "runOutputsNotRecorded": "Run outputs are not recorded per node yet; results currently route to the Gallery or Canvas. This tab will show the node's outputs from its most recent run once run records land.",
+      "newWorkflowWithEllipsis": "New workflow…",
+      "saveGraphSnapshot": "Save graph snapshot",
+      "selectNodeToInspect": "Select a node in the Workflow editor to inspect it.",
+      "selectedNodeInspector": "Selected node inspector",
+      "tags": "Tags",
+      "title": "Title",
+      "type": "Type",
+      "version": "Version",
+      "workflowJson": "Workflow JSON",
+      "untitled": "Untitled Workflow"
+    },
+    "layers": {
+      "actions": {
+        "addControlLayer": "Control layer",
+        "addDenoiseLimit": "Add denoise limit",
+        "addImageNoise": "Add image noise",
+        "addInpaintMask": "Inpaint mask",
+        "addNegativePrompt": "Add negative prompt",
+        "addPositivePrompt": "Add positive prompt",
+        "addRasterLayer": "Raster layer",
+        "addReferenceImage": "Add reference image",
+        "addRegionalGuidance": "Regional guidance",
+        "addRegionalReferenceImage": "Regional reference image",
+        "actionFailed": "Layer action failed",
+        "adjustments": "Adjustments",
+        "blendMode": "Blend mode",
+        "busy": "The canvas is busy. Try again when the current action finishes.",
+        "copyFailed": "The layer could not be copied.",
+        "copyLayerToClipboard": "Copy layer to clipboard",
+        "copyToControl": "Copy to control layer",
+        "copyToInpaintMask": "Copy to inpaint mask",
+        "copyToRasterLayer": "Copy to raster layer",
+        "copyToRegionalGuidance": "Copy to regional guidance",
+        "convertToControl": "Convert to control layer",
+        "convertToInpaintMask": "Convert to inpaint mask",
+        "convertToRaster": "Convert to raster layer",
+        "convertToRegionalGuidance": "Convert to regional guidance",
+        "cropBusy": "Finish the current canvas action before cropping this layer.",
+        "cropFailed": "The layer could not be cropped.",
+        "cropLayerToBbox": "Crop layer to bbox",
+        "cropUnsupported": "This layer cannot be cropped.",
+        "cropped": "Layer cropped to bbox.",
+        "cutaway": "Cutaway with layer below",
+        "cutout": "Cutout with layer below",
+        "delete": "Delete layer",
+        "disableAutoNegative": "Disable auto-negative",
+        "disableTransparencyEffect": "Disable transparency effect",
+        "disabled": "Enable the layer before using this action.",
+        "duplicate": "Duplicate layer",
+        "empty": "This layer has no content.",
+        "enableAutoNegative": "Enable auto-negative",
+        "enableTransparencyEffect": "Enable transparency effect",
+        "exclude": "Exclude layer below",
+        "extractMaskedArea": "Extract masked area",
+        "fitToBbox": "Fit to bbox",
+        "hide": "Hide layer",
+        "intersect": "Intersect with layer below",
+        "lock": "Lock layer",
+        "locked": "Unlock the layer before using this action.",
+        "mergeDown": "Merge down",
+        "missing": "The layer no longer exists.",
+        "moveBackward": "Move backward",
+        "moveForward": "Move forward",
+        "moveToBack": "Move to back",
+        "moveToFront": "Move to front",
+        "notReady": "The layer content is still loading. Try again shortly.",
+        "opacity": "Opacity",
+        "rasterize": "Rasterize layer",
+        "rename": "Rename layer",
+        "reorder": "Reorder layer",
+        "runWorkflow": "Run workflow",
+        "saveLayerToAssets": "Save layer to assets",
+        "selectObject": "Select object",
+        "show": "Show layer",
+        "toggleAutoNegative": "Toggle auto-negative",
+        "toggleLock": "Toggle lock",
+        "toggleTransparencyEffect": "Toggle transparency effect",
+        "toggleVisibility": "Toggle visibility",
+        "transform": "Transform",
+        "unsupported": "This action is not supported for this layer.",
+        "unlock": "Unlock layer"
+      },
+      "control": {
+        "apply": "Apply",
+        "applyFilter": "Apply filter",
+        "beginStep": "Begin step",
+        "cancel": "Cancel",
+        "endStep": "End step",
+        "filter": "Filter",
+        "filterParams": {
+          "amount": "Amount",
+          "autoScale": "Autoscale",
+          "blur_type": "Blur type",
+          "channel": "Channel",
+          "coarse": "Coarse",
+          "distance_threshold": "Distance threshold",
+          "draw_body": "Draw body",
+          "draw_face": "Draw face",
+          "draw_hands": "Draw hands",
+          "high_threshold": "High threshold",
+          "low_threshold": "Low threshold",
+          "max_faces": "Max faces",
+          "min_confidence": "Min confidence",
+          "model": "Image-to-image model",
+          "model_size": "Model size",
+          "quantize_edges": "Quantize edges",
+          "scale_factor": "Scale factor",
+          "scale": "Scale",
+          "scale_values": "Multiply values",
+          "score_threshold": "Score threshold",
+          "scribble": "Scribble",
+          "tile_size": "Tile size",
+          "noise_color": "Color noise",
+          "noise_type": "Noise type",
+          "radius": "Radius",
+          "size": "Size",
+          "value": "Value"
+        },
+        "filterOptions": {
+          "blur_type": {
+            "box": "Box",
+            "gaussian": "Gaussian"
+          },
+          "channel": {
+            "alpha": "Alpha (RGBA)",
+            "black": "Black (CMYK)",
+            "blue": "Blue (RGBA)",
+            "cb": "Cb (YCbCr)",
+            "cr": "Cr (YCbCr)",
+            "cyan": "Cyan (CMYK)",
+            "green": "Green (RGBA)",
+            "hue": "Hue (HSV)",
+            "lab_a": "A (LAB)",
+            "lab_b": "B (LAB)",
+            "luminosity": "Luminosity (LAB)",
+            "magenta": "Magenta (CMYK)",
+            "red": "Red (RGBA)",
+            "saturation": "Saturation (HSV)",
+            "value": "Value (HSV)",
+            "y": "Y (YCbCr)",
+            "yellow": "Yellow (CMYK)"
+          },
+          "model_size": {
+            "base": "Base",
+            "large": "Large",
+            "small": "Small",
+            "small_v2": "Small v2"
+          },
+          "noise_type": {
+            "gaussian": "Gaussian",
+            "salt_and_pepper": "Salt and pepper"
+          }
+        },
+        "filters": {
+          "adjust_image": "Adjust image",
+          "canny_edge_detection": "Canny",
+          "color_map": "Color map",
+          "content_shuffle": "Content shuffle",
+          "depth_anything_depth_estimation": "Depth Anything",
+          "dw_openpose_detection": "DW Openpose",
+          "hed_edge_detection": "HED",
+          "img_blur": "Blur",
+          "img_noise": "Noise",
+          "lineart_anime_edge_detection": "Lineart Anime",
+          "lineart_edge_detection": "Lineart",
+          "mediapipe_face_detection": "Mediapipe Face",
+          "mlsd_detection": "MLSD",
+          "normal_map": "Normal map",
+          "pidi_edge_detection": "PiDiNet",
+          "spandrel_filter": "Spandrel"
+        },
+        "kind": "Adapter type",
+        "kinds": {
+          "control_lora": "Control LoRA",
+          "controlnet": "ControlNet",
+          "t2i_adapter": "T2I Adapter",
+          "z_image_control": "Z-Image ControlNet"
+        },
+        "mode": "Control mode",
+        "model": "Model",
+        "modes": {
+          "balanced": "Balanced",
+          "more_control": "More control",
+          "more_prompt": "More prompt",
+          "unbalanced": "Unbalanced"
+        },
+        "preview": "Preview filter",
+        "selectModel": "Select a model",
+        "stepRange": "Step range",
+        "transparencyEffect": "Transparency effect",
+        "validation": {
+          "control_lora_limit": "Only one Control LoRA can be used at a time.",
+          "flux_fill_control_lora": "Control LoRA is not compatible with FLUX Fill.",
+          "incompatible_adapter": "The selected model does not match this adapter type.",
+          "incompatible_base": "The control model is incompatible with the selected base model.",
+          "invalid_adapter_values": "Control weight and step range must be valid before generating.",
+          "missing_model": "Select a control model before generating.",
+          "unsupported_adapter": "This control adapter is not supported by the selected base model.",
+          "z_image_control_limit": "Only one Z-Image control can be used at a time."
+        },
+        "weight": "Weight"
+      },
+      "rasterFilter": {
+        "autoProcess": "Auto",
+        "autoProcessDescription": "Process automatically when settings change",
+        "busy": "Finish the current canvas interaction, then try again.",
+        "cancel": "Cancel",
+        "commitFailure": "The filtered pixels could not be committed: {{message}}",
+        "copy": "Copy",
+        "durabilityFailure": "The filtered image could not be preserved: {{message}}",
+        "graphFailure": "The filter failed: {{message}}",
+        "locked": "Unlock the layer before applying the filter.",
+        "preview": "Preview",
+        "replace": "Replace",
+        "running": "Running filter…",
+        "statusCommitting": "Applying filter…",
+        "statusError": "Filter needs attention.",
+        "stale": "The layer changed while filtering. Preview it again.",
+        "title": "Filter",
+        "unsupported": "This layer content cannot be filtered."
+      },
+      "selectObject": {
+        "autoProcess": "Auto Process",
+        "bbox": "BBox",
+        "bboxActive": "Bounding box active",
+        "bboxInactive": "No bounding box",
+        "errorDecode": "The object preview could not be decoded.",
+        "errorEmpty": "The layer has no visible content to select.",
+        "errorInvalid": "Add an object prompt, point, or bounding box before processing.",
+        "errorLocked": "Select Object cannot finish while canvas editing is locked.",
+        "errorNoOutput": "Select Object finished without producing an image.",
+        "errorNotReady": "The layer source is not ready. Try again when it finishes loading.",
+        "errorOutputDimension": "The Select Object result dimensions do not match the layer source.",
+        "errorQueue": "Select Object processing failed on the backend.",
+        "errorReconcile": "The completed Select Object result could not be retrieved.",
+        "errorUnknown": "Select Object could not finish.",
+        "errorUpload": "The layer source could not be uploaded for Select Object.",
+        "exclude": "Exclude",
+        "excludeCount": "Exclude {{count}}",
+        "include": "Include",
+        "includeCount": "Include {{count}}",
+        "invert": "Invert",
+        "isolatedPreview": "Isolated Preview",
+        "model": "Model",
+        "modelHuge": "SAM Huge",
+        "modelSam2Large": "SAM 2 Large",
+        "mode": "Selection mode",
+        "prompt": "Object prompt",
+        "promptGuidance": "Describe the object you want to select.",
+        "promptMode": "Prompt",
+        "pointType": "Point type",
+        "process": "Process",
+        "refine": "Refine",
+        "reset": "Reset",
+        "saveAs": "Save As",
+        "saveAs_control": "Control layer",
+        "saveAs_inpaint_mask": "Inpaint mask",
+        "saveAs_raster": "Raster layer",
+        "saveAs_regional_guidance": "Regional guidance",
+        "saveAs_selection": "Selection",
+        "settings": "Select Object settings",
+        "sourceLayerLabel": "{{name}} · {{type}} · {{width}} × {{height}}",
+        "statusCommitting": "Applying object result…",
+        "statusError": "Select Object needs attention.",
+        "statusPreparingSource": "Preparing layer source…",
+        "statusProcessingSam": "Finding object…",
+        "statusReady": "Ready",
+        "statusRenderingPreview": "Rendering object preview…",
+        "statusScheduled": "Waiting to process object…",
+        "statusUploading": "Uploading layer source…",
+        "technicalDetails": "Technical details",
+        "title": "Select Object",
+        "visual": "Visual",
+        "visualGuidance": "Click to add · drag to move · Shift flips type"
+      },
+      "runWorkflow": {
+        "aborted": "Workflow run was canceled.",
+        "busy": "Finish the current canvas interaction, then try again.",
+        "cancel": "Cancel",
+        "copyRaster": "Copy as raster layer",
+        "copySuccess": "Added the workflow result as a raster layer.",
+        "destination": "Destination",
+        "disabled": "Enable the layer before running the workflow.",
+        "durabilityFailure": "The workflow output could not be preserved: {{message}}",
+        "empty": "This layer has no content to run through the workflow.",
+        "failed": "Workflow run failed: {{message}}",
+        "gallery": "Gallery",
+        "gallerySuccess": "Saved the workflow result to Gallery.",
+        "graphFailure": "The active workflow failed: {{message}}",
+        "hydrationFailure": "The workflow output could not be loaded: {{message}}",
+        "input": "Workflow image input",
+        "locked": "Unlock the layer before running the workflow.",
+        "missing": "The source layer no longer exists.",
+        "noBindings": "The active workflow has no compatible image input and output.",
+        "notReady": "The active workflow is not ready with this layer input.",
+        "output": "Workflow image output",
+        "replace": "Replace layer",
+        "replaceSuccess": "Replaced the layer with the workflow result.",
+        "run": "Run",
+        "running": "Running workflow…",
+        "staging": "Canvas staging",
+        "stagingSuccess": "Added the workflow result to canvas staging.",
+        "stale": "The layer or project changed while the workflow was running. Run it again.",
+        "title": "Run workflow from layer",
+        "unsupported": "This layer cannot be used as a workflow image input."
+      },
+      "addLayer": "Add layer",
+      "adjustments": {
+        "brightness": "Brightness",
+        "channel": "Channel",
+        "channels": {
+          "b": "Blue",
+          "g": "Green",
+          "r": "Red"
+        },
+        "contrast": "Contrast",
+        "curves": "Curves",
+        "curvesHint": "Drag points to bend the curve. Double-click empty space to add a point; double-click a point to remove it.",
+        "reset": "Reset adjustments",
+        "saturation": "Saturation",
+        "title": "Adjustments",
+        "transparencyLock": "Lock transparency"
+      },
+      "blendModes": {
+        "color": "Color",
+        "color-burn": "Color burn",
+        "color-dodge": "Color dodge",
+        "darken": "Darken",
+        "difference": "Difference",
+        "exclusion": "Exclusion",
+        "hard-light": "Hard light",
+        "hue": "Hue",
+        "lighten": "Lighten",
+        "luminosity": "Luminosity",
+        "multiply": "Multiply",
+        "normal": "Normal",
+        "overlay": "Overlay",
+        "saturation": "Saturation",
+        "screen": "Screen",
+        "soft-light": "Soft light"
+      },
+      "denoisingStrength": "Denoising strength",
+      "denoisingStrengthHelp": "How much the canvas image is changed. Lower keeps more of the original; higher allows bigger changes.",
+      "empty": "No layers yet. Add a layer or paint on the canvas to get started.",
+      "groupActions": {
+        "collapse": "Collapse group",
+        "expand": "Expand group",
+        "exportNothing": "No raster layer content to export",
+        "exportNotReady": "Layers are still loading — try exporting again in a moment",
+        "exportOverBudget": "Not enough raster memory is available to export this PSD",
+        "exportStale": "The canvas changed during export — try again",
+        "exportAborted": "PSD export was canceled",
+        "exportFailed": "PSD export failed",
+        "exportPsd": "Export to PSD",
+        "exportTooLarge": "Canvas is too large to export to PSD",
+        "hideAll": "Hide all",
+        "mergeNotReady": "Layers are still loading — try merging again in a moment",
+        "mergeVisible": "Merge visible",
+        "new": "New layer",
+        "showAll": "Show all",
+        "toggleVisibility": "Toggle group visibility"
+      },
+      "groups": {
+        "control": "Control Layers",
+        "inpaint_mask": "Inpaint Masks",
+        "raster": "Raster Layers",
+        "regional_guidance": "Regional Guidance"
+      },
+      "maskFill": {
+        "color": "Fill color",
+        "denoiseLimit": "Denoise limit",
+        "fill": "Fill",
+        "invert": "Invert mask",
+        "noiseLevel": "Noise level",
+        "style": "Fill style",
+        "styles": {
+          "crosshatch": "Crosshatch",
+          "diagonal": "Diagonal",
+          "grid": "Grid",
+          "horizontal": "Horizontal",
+          "solid": "Solid",
+          "vertical": "Vertical"
+        }
+      },
+      "menuGroups": {
+        "layers": "Layers",
+        "regional": "Regional"
+      },
+      "menu": {
+        "add": "Add",
+        "addModifiers": "Add modifiers",
+        "arrange": "Arrange",
+        "booleanOperations": "Boolean operations",
+        "convertTo": "Convert to",
+        "copyTo": "Copy to"
+      },
+      "options": "Layer options",
+      "properties": "Layer properties",
+      "regionalGuidance": {
+        "addReferenceImage": "Add reference image",
+        "autoNegative": "Auto-Negative",
+        "clearReferenceImage": "Clear reference image",
+        "method": "Method",
+        "methods": {
+          "composition": "Composition",
+          "full": "Full",
+          "style": "Style",
+          "style_precise": "Style (precise)",
+          "style_strong": "Style (strong)"
+        },
+        "model": "Model",
+        "negativePrompt": "Negative prompt",
+        "negativePromptPlaceholder": "Region negative prompt",
+        "positivePrompt": "Positive prompt",
+        "positivePromptPlaceholder": "Region positive prompt",
+        "referenceImage": "Reference image",
+        "referenceImageHelp": "Upload or drag an image from the gallery.",
+        "referenceImages": "Reference images",
+        "removeReferenceImage": "Remove reference image",
+        "selectModel": "Select a model",
+        "setReferenceImage": "Set reference image",
+        "weight": "Weight"
+      },
+      "types": {
+        "control": "Control",
+        "image": "Image",
+        "inpaint_mask": "Inpaint",
+        "paint": "Paint",
+        "regional_guidance": "Region"
+      }
+    },
+    "gallery": {
+      "alwaysShowDimensions": "Always show dimensions",
+      "archiveBoard": "Archive Board",
+      "boardActionsForBoard": "Board actions for {{name}}",
+      "boardGroups": {
+        "boards": "Boards",
+        "byDate": "By Date"
+      },
+      "boardItemCounts": "{{images}} images | {{assets}} assets",
+      "boardName": "Board name",
+      "commands": {
+        "clearSelection": "Clear gallery selection",
+        "deleteSelection": "Delete gallery selection",
+        "navigationDown": "Gallery navigation down",
+        "navigationLeft": "Gallery navigation left",
+        "navigationRight": "Gallery navigation right",
+        "navigationUp": "Gallery navigation up",
+        "selectAllOnPage": "Select all gallery images on page",
+        "toggleStarImage": "Toggle gallery image star"
+      },
+      "createBoardNamed": "Create board \"{{name}}\"",
+      "deleteBoard": "Delete Board",
+      "deleteBoardAndImages": "Delete Board and Images",
+      "deleteBoardDescription": "Deleted boards cannot be restored. Choose whether the board's images move to Uncategorized or are permanently deleted with it.",
+      "deleteBoardOnly": "Delete Board Only",
+      "deleteBoardQuestion": "Delete board \"{{name}}\"?",
+      "downloadBoard": "Download Board",
+      "dropImagesToUploadToBoard": "Drop images to upload to {{name}}",
+      "generationProgress": "Generation progress",
+      "generationProgressPercent": "Generation {{percentage}}%",
+      "hideArchivedBoards": "Hide archived boards",
+      "hideDateBoards": "Hide date boards",
+      "imageDensity": "Image density",
+      "imagesAriaLabel": "Gallery images",
+      "imageSort": "Image Sort",
+      "infinite": "Infinite",
+      "loadingBackendGallery": "Loading backend gallery...",
+      "loadingBoard": "Loading board...",
+      "newest": "Newest",
+      "noBoardsMatchSearch": "No boards match this search.",
+      "noImagesMatch": "No images match this board, tab, or search.",
+      "oldest": "Oldest",
+      "pagination": "Pagination",
+      "renameBoard": "Rename board",
+      "searchImagesAriaLabel": "Search gallery images",
+      "searchImagesPlaceholder": "Search images",
+      "searchOrCreateBoards": "Search or create boards",
+      "selectImageForPreview": "Select {{name}} for preview",
+      "selectedBoardFallback": "selected board",
+      "settings": "Gallery settings",
+      "settingsGridDensity": "Grid Density",
+      "settingsThumbnails": "Thumbnails",
+      "showArchivedBoards": "Show archived boards",
+      "showDateBoards": "Show date boards",
+      "showStarredImagesFirst": "Show starred images first",
+      "sortBoardsAscending": "Sort boards ascending",
+      "sortBoardsDescending": "Sort boards descending",
+      "starImage": "Star {{name}}",
+      "thumbnailFitAspect": "Aspect",
+      "thumbnailFitSquare": "Square",
+      "uncategorized": "Uncategorized",
+      "unarchiveBoard": "Unarchive Board",
+      "unknownBoard": "Unknown board",
+      "unstarImage": "Unstar {{name}}",
+      "uploadImagesToBoard": "Upload images to {{name}}",
+      "uploadsUnavailableForDateBoards": "Uploads are unavailable for date boards"
+    },
+    "serverStatus": {
+      "connected": "Connected to Server",
+      "connecting": "Connecting to Server",
+      "disconnected": "Disconnected from Server",
+      "label": "Server Status",
+      "labelWithError": "{{label}}: {{error}}"
+    },
+    "versionStatus": {
+      "chipLabel": "Version 7.0",
+      "description": "Invoke V7 shell version 7.0.",
+      "label": "Version"
+    }
+  }
+}
diff --git a/invokeai/frontend/webv2/public/locales/es.json b/invokeai/frontend/webv2/public/locales/es.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/es.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/fi.json b/invokeai/frontend/webv2/public/locales/fi.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/fi.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/fr.json b/invokeai/frontend/webv2/public/locales/fr.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/fr.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/he.json b/invokeai/frontend/webv2/public/locales/he.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/he.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/hu.json b/invokeai/frontend/webv2/public/locales/hu.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/hu.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/it.json b/invokeai/frontend/webv2/public/locales/it.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/it.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/ja.json b/invokeai/frontend/webv2/public/locales/ja.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/ja.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/ko.json b/invokeai/frontend/webv2/public/locales/ko.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/ko.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/mn.json b/invokeai/frontend/webv2/public/locales/mn.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/mn.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/nl.json b/invokeai/frontend/webv2/public/locales/nl.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/nl.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/pl.json b/invokeai/frontend/webv2/public/locales/pl.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/pl.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/pt-BR.json b/invokeai/frontend/webv2/public/locales/pt-BR.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/pt-BR.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/pt.json b/invokeai/frontend/webv2/public/locales/pt.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/pt.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/ro.json b/invokeai/frontend/webv2/public/locales/ro.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/ro.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/ru.json b/invokeai/frontend/webv2/public/locales/ru.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/ru.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/sv.json b/invokeai/frontend/webv2/public/locales/sv.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/sv.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/tr.json b/invokeai/frontend/webv2/public/locales/tr.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/tr.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/uk.json b/invokeai/frontend/webv2/public/locales/uk.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/uk.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/vi.json b/invokeai/frontend/webv2/public/locales/vi.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/vi.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/zh-CN.json b/invokeai/frontend/webv2/public/locales/zh-CN.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/zh-CN.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/public/locales/zh-Hant.json b/invokeai/frontend/webv2/public/locales/zh-Hant.json
new file mode 100644
index 00000000000..0967ef424bc
--- /dev/null
+++ b/invokeai/frontend/webv2/public/locales/zh-Hant.json
@@ -0,0 +1 @@
+{}
diff --git a/invokeai/frontend/webv2/scripts/i18n-report.mjs b/invokeai/frontend/webv2/scripts/i18n-report.mjs
new file mode 100644
index 00000000000..4c16f00b7de
--- /dev/null
+++ b/invokeai/frontend/webv2/scripts/i18n-report.mjs
@@ -0,0 +1,51 @@
+/* eslint-disable no-console */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const localeDir = join(process.cwd(), 'public/locales');
+const verbose = process.argv.includes('--verbose');
+
+const flattenKeys = (value, prefix = '') => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return prefix ? [prefix] : [];
+  }
+
+  return Object.entries(value).flatMap(([key, child]) => flattenKeys(child, prefix ? `${prefix}.${key}` : key));
+};
+
+const readJson = async (fileName) => JSON.parse(await readFile(join(localeDir, fileName), 'utf8'));
+
+const localeFiles = (await readdir(localeDir)).filter((fileName) => fileName.endsWith('.json')).sort();
+const english = await readJson('en.json');
+const englishKeys = flattenKeys(english);
+const englishKeySet = new Set(englishKeys);
+let missingCount = 0;
+
+for (const fileName of localeFiles) {
+  if (fileName === 'en.json') {
+    continue;
+  }
+
+  const locale = await readJson(fileName);
+  const localeKeys = new Set(flattenKeys(locale));
+  const missing = englishKeys.filter((key) => !localeKeys.has(key));
+  const extra = [...localeKeys].filter((key) => !englishKeySet.has(key));
+
+  missingCount += missing.length;
+  console.log(`\n${fileName}`);
+  console.log(`  missing: ${missing.length}`);
+  console.log(`  extra: ${extra.length}`);
+
+  if (verbose) {
+    for (const key of missing) {
+      console.log(`    - ${key}`);
+    }
+
+    for (const key of extra) {
+      console.log(`    + ${key}`);
+    }
+  }
+}
+
+console.log(`\nTotal missing keys: ${missingCount}`);
diff --git a/invokeai/frontend/webv2/src/App.tsx b/invokeai/frontend/webv2/src/App.tsx
new file mode 100644
index 00000000000..9826a01e033
--- /dev/null
+++ b/invokeai/frontend/webv2/src/App.tsx
@@ -0,0 +1,17 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { RouterProvider } from '@tanstack/react-router';
+
+import { router } from './router';
+import { system } from './theme/system';
+import { AppToaster } from './workbench/components/ui/toaster';
+import { I18nController } from './workbench/i18n';
+import { ThemeController } from './workbench/ThemeController';
+
+export const App = () => (
+  <ChakraProvider value={system}>
+    <ThemeController />
+    <I18nController />
+    <AppToaster />
+    <RouterProvider router={router} />
+  </ChakraProvider>
+);
diff --git a/invokeai/frontend/webv2/src/WorkbenchApp.tsx b/invokeai/frontend/webv2/src/WorkbenchApp.tsx
new file mode 100644
index 00000000000..6ffc11d4c6c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/WorkbenchApp.tsx
@@ -0,0 +1,41 @@
+import { useSearch } from '@tanstack/react-router';
+import { WorkbenchShell } from '@workbench/shell';
+import { useMemo } from 'react';
+
+import type { WorkbenchSearch } from './workbench/projects/session';
+
+import { SessionExpiryGuard } from './workbench/auth/components/SessionExpiryGuard';
+import { WorkbenchHotkeyRuntime } from './workbench/hotkeys/WorkbenchHotkeyRuntime';
+import { WidgetHosts } from './workbench/widget-frame/WidgetHosts';
+import { WorkbenchProvider } from './workbench/WorkbenchContext';
+import { WorkbenchRuntime } from './workbench/WorkbenchRuntime';
+import { WorkbenchSessionController } from './workbench/WorkbenchSessionController';
+
+/**
+ * The authenticated editor: providers, editor-only runtimes, and the shell.
+ * The shared backend socket is mounted above this route; `WorkbenchRuntime`
+ * attaches the generation queue listeners while the editor is open.
+ *
+ * The route's search params shape the boot: ?project deep-links a library
+ * project into the session, ?new starts a fresh draft. Both are consumed by
+ * the persistence load; the session controller handles params that change
+ * while the editor is already mounted.
+ */
+export const WorkbenchApp = () => {
+  const search = useSearch({ strict: false }) as WorkbenchSearch;
+  const loadOptions = useMemo(
+    () => ({ createNew: search.new, openProjectId: search.project }),
+    [search.new, search.project]
+  );
+
+  return (
+    <WorkbenchProvider loadOptions={loadOptions}>
+      <SessionExpiryGuard />
+      <WorkbenchHotkeyRuntime />
+      <WorkbenchRuntime />
+      <WorkbenchSessionController search={search} />
+      <WidgetHosts />
+      <WorkbenchShell />
+    </WorkbenchProvider>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/appMetadata.ts b/invokeai/frontend/webv2/src/appMetadata.ts
new file mode 100644
index 00000000000..c3e51ede928
--- /dev/null
+++ b/invokeai/frontend/webv2/src/appMetadata.ts
@@ -0,0 +1 @@
+export const APP_VERSION = '7.0';
diff --git a/invokeai/frontend/webv2/src/assets/SplashImage.webp b/invokeai/frontend/webv2/src/assets/SplashImage.webp
new file mode 100644
index 00000000000..02ab32d523c
Binary files /dev/null and b/invokeai/frontend/webv2/src/assets/SplashImage.webp differ
diff --git a/invokeai/frontend/webv2/src/i18n.ts b/invokeai/frontend/webv2/src/i18n.ts
new file mode 100644
index 00000000000..9d014a8cbb1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/i18n.ts
@@ -0,0 +1,20 @@
+import i18n from 'i18next';
+import Backend from 'i18next-http-backend';
+import { initReactI18next } from 'react-i18next';
+
+void i18n
+  .use(Backend)
+  .use(initReactI18next)
+  .init({
+    backend: {
+      loadPath: `${import.meta.env.BASE_URL}locales/{{lng}}.json`,
+    },
+    debug: false,
+    fallbackLng: 'en',
+    interpolation: {
+      escapeValue: false,
+    },
+    returnNull: false,
+  });
+
+export default i18n;
diff --git a/invokeai/frontend/webv2/src/lucide-icons.d.ts b/invokeai/frontend/webv2/src/lucide-icons.d.ts
new file mode 100644
index 00000000000..0330f2f1c87
--- /dev/null
+++ b/invokeai/frontend/webv2/src/lucide-icons.d.ts
@@ -0,0 +1,6 @@
+declare module 'lucide-react/dist/esm/icons/*.mjs' {
+  import type { ComponentType, SVGProps } from 'react';
+
+  const Icon: ComponentType<SVGProps<SVGSVGElement>>;
+  export default Icon;
+}
diff --git a/invokeai/frontend/webv2/src/main.tsx b/invokeai/frontend/webv2/src/main.tsx
new file mode 100644
index 00000000000..6c81cc73d19
--- /dev/null
+++ b/invokeai/frontend/webv2/src/main.tsx
@@ -0,0 +1,18 @@
+import '@fontsource/inter/index.css';
+import './i18n';
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { App } from './App';
+
+const rootElement = document.getElementById('root');
+
+if (!rootElement) {
+  throw new Error('Unable to mount Invoke V7: root element was not found.');
+}
+
+createRoot(rootElement).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);
diff --git a/invokeai/frontend/webv2/src/router.tsx b/invokeai/frontend/webv2/src/router.tsx
new file mode 100644
index 00000000000..141bb865a3e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/router.tsx
@@ -0,0 +1,203 @@
+import {
+  createHashHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  lazyRouteComponent,
+  Navigate,
+  Outlet,
+  redirect,
+} from '@tanstack/react-router';
+
+import { getCapabilities, type Capabilities } from './workbench/auth/capabilities';
+import { LoginScreen } from './workbench/auth/components/LoginScreen';
+import { SetupScreen } from './workbench/auth/components/SetupScreen';
+import { ensureAuthSession } from './workbench/auth/session';
+import { SocketHubRuntime } from './workbench/backend/SocketHubRuntime';
+import { WorkbenchSplashScreen } from './workbench/components/WorkbenchSplashScreen';
+import { Launchpad } from './workbench/launchpad/Launchpad';
+import { peekOpenProjectIds, type WorkbenchSearch } from './workbench/projects/session';
+import { loadWorkbenchSettings } from './workbench/settings/store';
+
+/**
+ * Code-based route tree. The authenticated layout route owns the auth guard,
+ * which resolves the backend's multi-user status once per app load:
+ *
+ * - multi-user off → authenticated routes render directly; /login + /setup bounce home
+ * - setup required → everything funnels to /setup
+ * - signed out     → authenticated routes redirect to /login
+ *
+ * Under it, `/` is the Launchpad (project library, model manager, profile,
+ * resources) and `/app` is the editor. The editor bundle — canvas, workflow,
+ * widgets — is code-split behind `lazyRouteComponent`, so the Launchpad stays
+ * light; `defaultPreload: 'intent'` starts fetching that chunk the moment a
+ * project card is hovered.
+ *
+ * Hash history is used because the bundle is served with a relative base
+ * (`./`), so the app cannot rely on server-side fallback for deep paths.
+ */
+
+const rootRoute = createRootRoute({ component: Outlet });
+
+/**
+ * Wraps every authenticated route with the shared backend socket transport.
+ * Feature runtimes attach their own listeners only where needed, keeping the
+ * light Launchpad bundle free of editor/model-manager code.
+ */
+const AuthenticatedLayout = () => (
+  <>
+    <SocketHubRuntime />
+    <Outlet />
+  </>
+);
+
+const authenticatedRoute = createRoute({
+  beforeLoad: async () => {
+    const session = await ensureAuthSession();
+
+    if (session.multiuserEnabled) {
+      if (session.setupRequired) {
+        throw redirect({ to: '/setup' });
+      }
+
+      if (session.user === null) {
+        throw redirect({ to: '/login' });
+      }
+    }
+
+    await loadWorkbenchSettings();
+  },
+  component: AuthenticatedLayout,
+  getParentRoute: () => rootRoute,
+  id: 'authenticated',
+});
+
+const requireLaunchpadCapability = async (capability: keyof Capabilities): Promise<void> => {
+  const session = await ensureAuthSession();
+
+  if (!getCapabilities(session)[capability]) {
+    throw redirect({ to: '/projects' });
+  }
+};
+
+// `/` plus a deep-link alias per Launchpad section. All render the same shell;
+// it reads the path to pick the active page.
+const homeRoute = createRoute({
+  component: Launchpad,
+  getParentRoute: () => authenticatedRoute,
+  path: '/',
+});
+
+const projectsHomeRoute = createRoute({
+  component: Launchpad,
+  getParentRoute: () => authenticatedRoute,
+  path: 'projects',
+});
+
+const modelsHomeRoute = createRoute({
+  beforeLoad: () => requireLaunchpadCapability('canManageModels'),
+  component: Launchpad,
+  getParentRoute: () => authenticatedRoute,
+  path: 'models',
+});
+
+const nodesHomeRoute = createRoute({
+  beforeLoad: () => requireLaunchpadCapability('canManageNodes'),
+  component: Launchpad,
+  getParentRoute: () => authenticatedRoute,
+  path: 'nodes',
+});
+
+const usersHomeRoute = createRoute({
+  beforeLoad: () => requireLaunchpadCapability('canManageUsers'),
+  component: Launchpad,
+  getParentRoute: () => authenticatedRoute,
+  path: 'users',
+});
+
+const workbenchRoute = createRoute({
+  beforeLoad: async ({ cause, search }) => {
+    // Photoshop semantics: the editor without documents is Home. A definite
+    // empty session redirects unless the URL explicitly asks for a project or
+    // a fresh draft; an unknowable session (first run, legacy blob, backend
+    // unreachable) falls through and the editor boots from what it can find.
+    //
+    // Only actual entries are checked: search-only changes ('stay', e.g. the
+    // session controller stripping ?new before the draft has autosaved) must
+    // not re-evaluate a blob that is still catching up, and hover preloads
+    // should not hit the session endpoint at all.
+    if (cause !== 'enter' || search.project || search.new) {
+      return;
+    }
+
+    const openProjectIds = await peekOpenProjectIds();
+
+    if (openProjectIds !== null && openProjectIds.length === 0) {
+      throw redirect({ to: '/' });
+    }
+  },
+  component: lazyRouteComponent(() => import('./WorkbenchApp'), 'WorkbenchApp'),
+  getParentRoute: () => authenticatedRoute,
+  path: '/app',
+  validateSearch: (search: Record<string, unknown>): WorkbenchSearch => ({
+    new: search.new === true || search.new === 'true' || search.new === 1 ? true : undefined,
+    project: typeof search.project === 'string' && search.project.length > 0 ? search.project : undefined,
+  }),
+});
+
+const loginRoute = createRoute({
+  beforeLoad: async () => {
+    const session = await ensureAuthSession();
+
+    if (session.multiuserEnabled && session.setupRequired) {
+      throw redirect({ to: '/setup' });
+    }
+
+    if (!session.multiuserEnabled || session.user !== null) {
+      throw redirect({ to: '/' });
+    }
+  },
+  component: LoginScreen,
+  getParentRoute: () => rootRoute,
+  path: '/login',
+});
+
+const setupRoute = createRoute({
+  beforeLoad: async () => {
+    const session = await ensureAuthSession();
+
+    if (!session.multiuserEnabled || !session.setupRequired) {
+      throw redirect({ to: '/' });
+    }
+  },
+  component: SetupScreen,
+  getParentRoute: () => rootRoute,
+  path: '/setup',
+});
+
+const RouterPending = () => <WorkbenchSplashScreen messageKey="splash.loadingApplication" />;
+
+export const router = createRouter({
+  defaultNotFoundComponent: () => <Navigate to="/" />,
+  defaultPendingComponent: RouterPending,
+  defaultPreload: 'intent',
+  history: createHashHistory(),
+  routeTree: rootRoute.addChildren([
+    authenticatedRoute.addChildren([
+      homeRoute,
+      projectsHomeRoute,
+      modelsHomeRoute,
+      nodesHomeRoute,
+      usersHomeRoute,
+      workbenchRoute,
+    ]),
+    loginRoute,
+    setupRoute,
+  ]),
+});
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/theme/__fixtures__/legacyTokenBaseline.json b/invokeai/frontend/webv2/src/theme/__fixtures__/legacyTokenBaseline.json
new file mode 100644
index 00000000000..906dba0ba17
--- /dev/null
+++ b/invokeai/frontend/webv2/src/theme/__fixtures__/legacyTokenBaseline.json
@@ -0,0 +1,237 @@
+{
+  "classic": {
+    "bg": "oklch(21.074% 0.0087 264.37)",
+    "bg.subtle": "oklch(26.279% 0.0123 264.34)",
+    "bg.muted": "oklch(31.237% 0.0157 264.32)",
+    "bg.panel": "oklch(31.237% 0.0157 264.32)",
+    "bg.emphasized": "oklch(36.004% 0.019 264.3)",
+    "bg.inset": "oklch(21.074% 0.0087 264.37)",
+    "bg.error": "color-mix(in oklab, oklch(70.61% 0.0841 19.38) 14%, oklch(26.279% 0.0123 264.34))",
+    "bg.success": "color-mix(in oklab, oklch(79.8% 0.1132 141.63) 14%, oklch(26.279% 0.0123 264.34))",
+    "bg.warning": "color-mix(in oklab, oklch(76.62% 0.0612 62.9) 14%, oklch(26.279% 0.0123 264.34))",
+    "fg": "oklch(96.017% 0.0029 264.54)",
+    "fg.muted": "oklch(73.736% 0.0202 264.44)",
+    "fg.subtle": "oklch(57.965% 0.0337 264.27)",
+    "fg.grid": "oklch(40.619% 0.0221 264.29)",
+    "fg.error": "oklch(70.61% 0.0841 19.38)",
+    "fg.success": "oklch(79.8% 0.1132 141.63)",
+    "fg.warning": "oklch(76.62% 0.0612 62.9)",
+    "border": "oklch(40.619% 0.0221 264.29)",
+    "border.subtle": "oklch(40.619% 0.0221 264.29)",
+    "border.muted": "oklch(40.619% 0.0221 264.29)",
+    "border.emphasized": "oklch(45.106% 0.0251 264.28)",
+    "border.error": "oklch(70.61% 0.0841 19.38)",
+    "gray.contrast": "oklch(21.074% 0.0087 264.37)",
+    "gray.fg": "oklch(96.017% 0.0029 264.54)",
+    "gray.subtle": "oklch(31.237% 0.0157 264.32)",
+    "gray.muted": "oklch(36.004% 0.019 264.3)",
+    "gray.emphasized": "oklch(45.106% 0.0251 264.28)",
+    "gray.solid": "oklch(96.017% 0.0029 264.54)",
+    "gray.focusRing": "oklch(77.738% 0.1 231.76)",
+    "gray.border": "oklch(45.106% 0.0251 264.28)",
+    "brand.solid": "oklch(92.041% 0.2103 116.59)",
+    "brand.contrast": "oklch(21.074% 0.0087 264.37)",
+    "brand.fg": "oklch(92.041% 0.2103 116.59)",
+    "brand.subtle": "color-mix(in oklab, oklch(92.041% 0.2103 116.59) 16%, oklch(26.279% 0.0123 264.34))",
+    "brand.muted": "color-mix(in oklab, oklch(92.041% 0.2103 116.59) 26%, oklch(26.279% 0.0123 264.34))",
+    "brand.emphasized": "color-mix(in oklab, oklch(92.041% 0.2103 116.59) 36%, oklch(26.279% 0.0123 264.34))",
+    "brand.focusRing": "oklch(77.738% 0.1 231.76)",
+    "brand.border": "oklch(92.041% 0.2103 116.59)",
+    "accent.solid": "oklch(77.738% 0.1 231.76)",
+    "accent.contrast": "oklch(21.074% 0.0087 264.37)",
+    "accent.fg": "oklch(77.738% 0.1 231.76)",
+    "accent.subtle": "color-mix(in oklab, oklch(77.738% 0.1 231.76) 16%, oklch(26.279% 0.0123 264.34))",
+    "accent.muted": "color-mix(in oklab, oklch(77.738% 0.1 231.76) 26%, oklch(26.279% 0.0123 264.34))",
+    "accent.emphasized": "color-mix(in oklab, oklch(77.738% 0.1 231.76) 36%, oklch(26.279% 0.0123 264.34))",
+    "accent.focusRing": "oklch(77.738% 0.1 231.76)",
+    "accent.border": "oklch(77.738% 0.1 231.76)"
+  },
+  "light": {
+    "bg": "oklch(96% 0.0038 264)",
+    "bg.subtle": "oklch(99.4% 0.002 264)",
+    "bg.muted": "oklch(97% 0.003 264)",
+    "bg.panel": "oklch(97% 0.003 264)",
+    "bg.emphasized": "oklch(93.5% 0.005 264)",
+    "bg.inset": "oklch(96% 0.0038 264)",
+    "bg.error": "color-mix(in oklab, oklch(55.509% 0.1707 24.62) 14%, oklch(99.4% 0.002 264))",
+    "bg.success": "color-mix(in oklab, oklch(53% 0.15 150) 14%, oklch(99.4% 0.002 264))",
+    "bg.warning": "color-mix(in oklab, oklch(60% 0.13 72) 14%, oklch(99.4% 0.002 264))",
+    "fg": "oklch(22.5% 0.013 264)",
+    "fg.muted": "oklch(45% 0.017 264)",
+    "fg.subtle": "oklch(63% 0.014 264)",
+    "fg.grid": "oklch(88.5% 0.0075 264)",
+    "fg.error": "oklch(55.509% 0.1707 24.62)",
+    "fg.success": "oklch(53% 0.15 150)",
+    "fg.warning": "oklch(60% 0.13 72)",
+    "border": "oklch(90.5% 0.0065 264)",
+    "border.subtle": "oklch(90.5% 0.0065 264)",
+    "border.muted": "oklch(90.5% 0.0065 264)",
+    "border.emphasized": "oklch(84% 0.0095 264)",
+    "border.error": "oklch(55.509% 0.1707 24.62)",
+    "gray.contrast": "oklch(96% 0.0038 264)",
+    "gray.fg": "oklch(22.5% 0.013 264)",
+    "gray.subtle": "oklch(95.5% 0.005 264)",
+    "gray.muted": "oklch(93.5% 0.005 264)",
+    "gray.emphasized": "oklch(84% 0.0095 264)",
+    "gray.solid": "oklch(22.5% 0.013 264)",
+    "gray.focusRing": "oklch(54.615% 0.2152 262.88)",
+    "gray.border": "oklch(84% 0.0095 264)",
+    "brand.solid": "oklch(92.041% 0.2103 116.59)",
+    "brand.contrast": "oklch(22.5% 0.013 264)",
+    "brand.fg": "oklch(92.041% 0.2103 116.59)",
+    "brand.subtle": "color-mix(in oklab, oklch(92.041% 0.2103 116.59) 16%, oklch(99.4% 0.002 264))",
+    "brand.muted": "color-mix(in oklab, oklch(92.041% 0.2103 116.59) 26%, oklch(99.4% 0.002 264))",
+    "brand.emphasized": "color-mix(in oklab, oklch(92.041% 0.2103 116.59) 36%, oklch(99.4% 0.002 264))",
+    "brand.focusRing": "oklch(54.615% 0.2152 262.88)",
+    "brand.border": "oklch(92.041% 0.2103 116.59)",
+    "accent.solid": "oklch(54.615% 0.2152 262.88)",
+    "accent.contrast": "oklch(100% 0 0)",
+    "accent.fg": "oklch(54.615% 0.2152 262.88)",
+    "accent.subtle": "color-mix(in oklab, oklch(54.615% 0.2152 262.88) 16%, oklch(99.4% 0.002 264))",
+    "accent.muted": "color-mix(in oklab, oklch(54.615% 0.2152 262.88) 26%, oklch(99.4% 0.002 264))",
+    "accent.emphasized": "color-mix(in oklab, oklch(54.615% 0.2152 262.88) 36%, oklch(99.4% 0.002 264))",
+    "accent.focusRing": "oklch(54.615% 0.2152 262.88)",
+    "accent.border": "oklch(54.615% 0.2152 262.88)"
+  },
+  "forest": {
+    "bg": "oklch(17.349% 0.0154 144.88)",
+    "bg.subtle": "oklch(19.03% 0.0175 144.85)",
+    "bg.muted": "oklch(20.99% 0.0219 144.74)",
+    "bg.panel": "oklch(20.99% 0.0219 144.74)",
+    "bg.emphasized": "oklch(25.62% 0.03 144.64)",
+    "bg.inset": "oklch(17.349% 0.0154 144.88)",
+    "bg.error": "color-mix(in oklab, oklch(69.305% 0.1467 35.44) 14%, oklch(19.03% 0.0175 144.85))",
+    "bg.success": "color-mix(in oklab, oklch(78% 0.16 148) 14%, oklch(19.03% 0.0175 144.85))",
+    "bg.warning": "color-mix(in oklab, oklch(80% 0.12 76) 14%, oklch(19.03% 0.0175 144.85))",
+    "fg": "oklch(90.57% 0.0511 134.45)",
+    "fg.muted": "oklch(71.619% 0.0575 135.25)",
+    "fg.subtle": "oklch(53.577% 0.0538 136.73)",
+    "fg.grid": "oklch(34.825% 0.0526 141.63)",
+    "fg.error": "oklch(69.305% 0.1467 35.44)",
+    "fg.success": "oklch(78% 0.16 148)",
+    "fg.warning": "oklch(80% 0.12 76)",
+    "border": "oklch(27.425% 0.0354 143.04)",
+    "border.subtle": "oklch(27.425% 0.0354 143.04)",
+    "border.muted": "oklch(27.425% 0.0354 143.04)",
+    "border.emphasized": "oklch(36.133% 0.0575 141.06)",
+    "border.error": "oklch(69.305% 0.1467 35.44)",
+    "gray.contrast": "oklch(17.349% 0.0154 144.88)",
+    "gray.fg": "oklch(90.57% 0.0511 134.45)",
+    "gray.subtle": "oklch(28.489% 0.0483 141.22)",
+    "gray.muted": "oklch(25.62% 0.03 144.64)",
+    "gray.emphasized": "oklch(36.133% 0.0575 141.06)",
+    "gray.solid": "oklch(90.57% 0.0511 134.45)",
+    "gray.focusRing": "oklch(70.437% 0.1101 178.23)",
+    "gray.border": "oklch(36.133% 0.0575 141.06)",
+    "brand.solid": "oklch(79.714% 0.1784 136.37)",
+    "brand.contrast": "oklch(18.298% 0.0314 147.69)",
+    "brand.fg": "oklch(79.714% 0.1784 136.37)",
+    "brand.subtle": "color-mix(in oklab, oklch(79.714% 0.1784 136.37) 16%, oklch(19.03% 0.0175 144.85))",
+    "brand.muted": "color-mix(in oklab, oklch(79.714% 0.1784 136.37) 26%, oklch(19.03% 0.0175 144.85))",
+    "brand.emphasized": "color-mix(in oklab, oklch(79.714% 0.1784 136.37) 36%, oklch(19.03% 0.0175 144.85))",
+    "brand.focusRing": "oklch(70.437% 0.1101 178.23)",
+    "brand.border": "oklch(79.714% 0.1784 136.37)",
+    "accent.solid": "oklch(70.437% 0.1101 178.23)",
+    "accent.contrast": "oklch(17.44% 0.0258 171.89)",
+    "accent.fg": "oklch(70.437% 0.1101 178.23)",
+    "accent.subtle": "color-mix(in oklab, oklch(70.437% 0.1101 178.23) 16%, oklch(19.03% 0.0175 144.85))",
+    "accent.muted": "color-mix(in oklab, oklch(70.437% 0.1101 178.23) 26%, oklch(19.03% 0.0175 144.85))",
+    "accent.emphasized": "color-mix(in oklab, oklch(70.437% 0.1101 178.23) 36%, oklch(19.03% 0.0175 144.85))",
+    "accent.focusRing": "oklch(70.437% 0.1101 178.23)",
+    "accent.border": "oklch(70.437% 0.1101 178.23)"
+  },
+  "mono": {
+    "bg": "oklch(18.22% 0 0)",
+    "bg.subtle": "oklch(20.019% 0 0)",
+    "bg.muted": "oklch(22.213% 0 0)",
+    "bg.panel": "oklch(22.213% 0 0)",
+    "bg.emphasized": "oklch(27.274% 0 0)",
+    "bg.inset": "oklch(18.22% 0 0)",
+    "bg.error": "color-mix(in oklab, oklch(71.115% 0.0934 19.64) 14%, oklch(20.019% 0 0))",
+    "bg.success": "color-mix(in oklab, oklch(76% 0.06 150) 14%, oklch(20.019% 0 0))",
+    "bg.warning": "color-mix(in oklab, oklch(79% 0.07 80) 14%, oklch(20.019% 0 0))",
+    "fg": "oklch(93.1% 0 0)",
+    "fg.muted": "oklch(71.547% 0 0)",
+    "fg.subtle": "oklch(53.824% 0 0)",
+    "fg.grid": "oklch(32.897% 0 0)",
+    "fg.error": "oklch(71.115% 0.0934 19.64)",
+    "fg.success": "oklch(76% 0.06 150)",
+    "fg.warning": "oklch(79% 0.07 80)",
+    "border": "oklch(28.908% 0 0)",
+    "border.subtle": "oklch(28.908% 0 0)",
+    "border.muted": "oklch(28.908% 0 0)",
+    "border.emphasized": "oklch(34.846% 0 0)",
+    "border.error": "oklch(71.115% 0.0934 19.64)",
+    "gray.contrast": "oklch(18.22% 0 0)",
+    "gray.fg": "oklch(93.1% 0 0)",
+    "gray.subtle": "oklch(28.908% 0 0)",
+    "gray.muted": "oklch(27.274% 0 0)",
+    "gray.emphasized": "oklch(34.846% 0 0)",
+    "gray.solid": "oklch(93.1% 0 0)",
+    "gray.focusRing": "oklch(68.622% 0 0)",
+    "gray.border": "oklch(34.846% 0 0)",
+    "brand.solid": "oklch(93.1% 0 0)",
+    "brand.contrast": "oklch(18.22% 0 0)",
+    "brand.fg": "oklch(93.1% 0 0)",
+    "brand.subtle": "color-mix(in oklab, oklch(93.1% 0 0) 16%, oklch(20.019% 0 0))",
+    "brand.muted": "color-mix(in oklab, oklch(93.1% 0 0) 26%, oklch(20.019% 0 0))",
+    "brand.emphasized": "color-mix(in oklab, oklch(93.1% 0 0) 36%, oklch(20.019% 0 0))",
+    "brand.focusRing": "oklch(68.622% 0 0)",
+    "brand.border": "oklch(93.1% 0 0)",
+    "accent.solid": "oklch(68.622% 0 0)",
+    "accent.contrast": "oklch(18.22% 0 0)",
+    "accent.fg": "oklch(68.622% 0 0)",
+    "accent.subtle": "color-mix(in oklab, oklch(68.622% 0 0) 16%, oklch(20.019% 0 0))",
+    "accent.muted": "color-mix(in oklab, oklch(68.622% 0 0) 26%, oklch(20.019% 0 0))",
+    "accent.emphasized": "color-mix(in oklab, oklch(68.622% 0 0) 36%, oklch(20.019% 0 0))",
+    "accent.focusRing": "oklch(68.622% 0 0)",
+    "accent.border": "oklch(68.622% 0 0)"
+  },
+  "ultradark": {
+    "bg": "oklch(0% 0 0)",
+    "bg.subtle": "oklch(11.492% 0 0)",
+    "bg.muted": "oklch(14.479% 0 0)",
+    "bg.panel": "oklch(14.479% 0 0)",
+    "bg.emphasized": "oklch(19.125% 0 0)",
+    "bg.inset": "oklch(0% 0 0)",
+    "bg.error": "color-mix(in oklab, oklch(71.161% 0.1812 22.84) 14%, oklch(11.492% 0 0))",
+    "bg.success": "color-mix(in oklab, oklch(76.5% 0.16 150.5) 14%, oklch(11.492% 0 0))",
+    "bg.warning": "color-mix(in oklab, oklch(79.5% 0.13 80) 14%, oklch(11.492% 0 0))",
+    "fg": "oklch(88.901% 0.0317 120.83)",
+    "fg.muted": "oklch(66.382% 0.0192 131.96)",
+    "fg.subtle": "oklch(47.041% 0.0184 127.12)",
+    "fg.grid": "oklch(23.929% 0 0)",
+    "fg.error": "oklch(71.161% 0.1812 22.84)",
+    "fg.success": "oklch(76.5% 0.16 150.5)",
+    "fg.warning": "oklch(79.5% 0.13 80)",
+    "border": "oklch(20.904% 0 0)",
+    "border.subtle": "oklch(20.904% 0 0)",
+    "border.muted": "oklch(20.904% 0 0)",
+    "border.emphasized": "oklch(26.862% 0 0)",
+    "border.error": "oklch(71.161% 0.1812 22.84)",
+    "gray.contrast": "oklch(0% 0 0)",
+    "gray.fg": "oklch(88.901% 0.0317 120.83)",
+    "gray.subtle": "oklch(21.779% 0 0)",
+    "gray.muted": "oklch(19.125% 0 0)",
+    "gray.emphasized": "oklch(26.862% 0 0)",
+    "gray.solid": "oklch(88.901% 0.0317 120.83)",
+    "gray.focusRing": "oklch(80.623% 0.1248 228.24)",
+    "gray.border": "oklch(26.862% 0 0)",
+    "brand.solid": "oklch(93.444% 0.19 125.56)",
+    "brand.contrast": "oklch(15.913% 0.0233 128.66)",
+    "brand.fg": "oklch(93.444% 0.19 125.56)",
+    "brand.subtle": "color-mix(in oklab, oklch(93.444% 0.19 125.56) 16%, oklch(11.492% 0 0))",
+    "brand.muted": "color-mix(in oklab, oklch(93.444% 0.19 125.56) 26%, oklch(11.492% 0 0))",
+    "brand.emphasized": "color-mix(in oklab, oklch(93.444% 0.19 125.56) 36%, oklch(11.492% 0 0))",
+    "brand.focusRing": "oklch(80.623% 0.1248 228.24)",
+    "brand.border": "oklch(93.444% 0.19 125.56)",
+    "accent.solid": "oklch(80.623% 0.1248 228.24)",
+    "accent.contrast": "oklch(17.416% 0.0256 235.84)",
+    "accent.fg": "oklch(80.623% 0.1248 228.24)",
+    "accent.subtle": "color-mix(in oklab, oklch(80.623% 0.1248 228.24) 16%, oklch(11.492% 0 0))",
+    "accent.muted": "color-mix(in oklab, oklch(80.623% 0.1248 228.24) 26%, oklch(11.492% 0 0))",
+    "accent.emphasized": "color-mix(in oklab, oklch(80.623% 0.1248 228.24) 36%, oklch(11.492% 0 0))",
+    "accent.focusRing": "oklch(80.623% 0.1248 228.24)",
+    "accent.border": "oklch(80.623% 0.1248 228.24)"
+  }
+}
diff --git a/invokeai/frontend/webv2/src/theme/__tokenResolve.ts b/invokeai/frontend/webv2/src/theme/__tokenResolve.ts
new file mode 100644
index 00000000000..0bdd9a12b38
--- /dev/null
+++ b/invokeai/frontend/webv2/src/theme/__tokenResolve.ts
@@ -0,0 +1,130 @@
+/**
+ * Test-only helper: resolve every semantic color token to its FINAL literal value
+ * (following `var(--chakra-colors-…)` references) for each workbench theme, straight
+ * from `system.getTokenCss()`. This mirrors what the browser computes for a given
+ * `<html data-theme=… class="dark|light">`, so it is the ground truth used by the
+ * legacy-value gate in `system.test.ts`.
+ *
+ * Not imported by any app entry — excluded from the production bundle.
+ */
+
+type Block = Record<string, string>;
+type Layer = Record<string, Block>;
+
+export interface TokenSystem {
+  getTokenCss: () => Record<string, Layer>;
+  tokens: { getByName: (name: string) => { extensions: { cssVar: { var: string } } } | undefined };
+}
+
+const BASE_SEL = '&:where(html, .chakra-theme)';
+const DARK_SEL = '.dark &, .dark .chakra-theme:not(.light) &';
+const LIGHT_SEL = ':root &, .light &';
+const dataSel = (id: string): string => `&:root[data-theme=${id}]`;
+
+/** Selectors that apply to each theme, HIGHEST CSS priority first. */
+export const THEME_SELECTORS: Record<string, string[]> = {
+  classic: [DARK_SEL, BASE_SEL], // default theme: no [data-theme=classic] rule
+  light: [dataSel('light'), LIGHT_SEL, BASE_SEL],
+  forest: [dataSel('forest'), DARK_SEL, BASE_SEL],
+  mono: [dataSel('mono'), DARK_SEL, BASE_SEL],
+  ultradark: [dataSel('ultradark'), DARK_SEL, BASE_SEL],
+};
+
+export const THEMES = Object.keys(THEME_SELECTORS);
+
+const VAR_REF = /var\((--chakra-colors-[A-Za-z0-9\\.-]+)\)/g;
+
+const layerOf = (sys: TokenSystem): Layer => sys.getTokenCss()['@layer tokens'];
+
+const resolveVar = (layer: Layer, theme: string, varName: string, seen: Set<string>): string | undefined => {
+  for (const sel of THEME_SELECTORS[theme]) {
+    const block = layer[sel];
+    if (block && varName in block) {
+      return resolveValue(layer, theme, block[varName], seen);
+    }
+  }
+  return undefined;
+};
+
+const resolveValue = (layer: Layer, theme: string, value: string, seen: Set<string>): string =>
+  value.replace(VAR_REF, (whole, varName: string) => {
+    if (seen.has(varName)) {
+      return whole;
+    }
+    const resolved = resolveVar(layer, theme, varName, new Set(seen).add(varName));
+    return resolved ?? whole;
+  });
+
+/** Final literal value of `colors.<tokenName>` in `theme`. */
+export const resolveToken = (sys: TokenSystem, theme: string, tokenName: string): string => {
+  const token = sys.tokens.getByName(`colors.${tokenName}`);
+  if (!token) {
+    throw new Error(`token not found: colors.${tokenName}`);
+  }
+  const value = resolveVar(layerOf(sys), theme, token.extensions.cssVar.var, new Set());
+  if (value === undefined) {
+    throw new Error(`could not resolve colors.${tokenName} for theme ${theme}`);
+  }
+  return value;
+};
+
+/** Resolve every token across every theme → { [theme]: { [token]: value } }. */
+export const resolveAll = (sys: TokenSystem, tokens: readonly string[]): Record<string, Record<string, string>> => {
+  const out: Record<string, Record<string, string>> = {};
+  for (const theme of THEMES) {
+    out[theme] = {};
+    for (const token of tokens) {
+      out[theme][token] = resolveToken(sys, theme, token);
+    }
+  }
+  return out;
+};
+
+/** The frozen public color-token contract — every name a component/recipe may consume. */
+export const CONSUMER_TOKENS = [
+  'bg',
+  'bg.subtle',
+  'bg.muted',
+  'bg.panel',
+  'bg.emphasized',
+  'bg.inset',
+  'bg.error',
+  'bg.success',
+  'bg.warning',
+  'fg',
+  'fg.muted',
+  'fg.subtle',
+  'fg.grid',
+  'fg.error',
+  'fg.success',
+  'fg.warning',
+  'border',
+  'border.subtle',
+  'border.muted',
+  'border.emphasized',
+  'border.error',
+  'gray.contrast',
+  'gray.fg',
+  'gray.subtle',
+  'gray.muted',
+  'gray.emphasized',
+  'gray.solid',
+  'gray.focusRing',
+  'gray.border',
+  'brand.solid',
+  'brand.contrast',
+  'brand.fg',
+  'brand.subtle',
+  'brand.muted',
+  'brand.emphasized',
+  'brand.focusRing',
+  'brand.border',
+  'accent.solid',
+  'accent.contrast',
+  'accent.fg',
+  'accent.subtle',
+  'accent.muted',
+  'accent.emphasized',
+  'accent.focusRing',
+  'accent.border',
+] as const;
diff --git a/invokeai/frontend/webv2/src/theme/recipes.ts b/invokeai/frontend/webv2/src/theme/recipes.ts
new file mode 100644
index 00000000000..a3ca67514b1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/theme/recipes.ts
@@ -0,0 +1,361 @@
+import { defineRecipe, defineSlotRecipe } from '@chakra-ui/react';
+import { slotRecipes as chakraSlotRecipes } from '@chakra-ui/react/theme';
+
+/**
+ * Reusable, theme-aware recipes for the workbench design system.
+ *
+ * Recipes reference semantic tokens only, so every variant automatically tracks
+ * the active theme. Two kinds live here:
+ *
+ *   1. Overrides for Chakra's built-in component recipes (`tooltip`, `menu`,
+ *      `select`, `combobox`, `dialog`) — registered in `system.ts` so every
+ *      instance app-wide gets the workbench chrome with zero props at the call
+ *      site.
+ *   2. Workbench-specific recipes (`panel`, `row`, `chip`, `fieldLabel`,
+ *      `themeCard`) — consumed via the wrappers in `workbench/components/ui`
+ *      with `useRecipe({ recipe })` / `useSlotRecipe({ recipe })`, which keeps
+ *      them fully typed without the Chakra typegen step.
+ *
+ * Either way, this file is the single place where shared component styling is
+ * edited.
+ */
+
+/* -------------------------------------------------------------------------- *
+ * Built-in component overrides (registered in system.ts)
+ * -------------------------------------------------------------------------- */
+
+/** Tooltip chrome: raised surface with a hairline stroke instead of inverted fill. */
+export const tooltipSlotRecipe = defineSlotRecipe({
+  slots: ['content', 'arrowTip'],
+  base: {
+    content: {
+      '--tooltip-bg': 'colors.bg.muted',
+      bg: 'var(--tooltip-bg)',
+      borderColor: 'border.emphasized',
+      borderWidth: '1px',
+      boxShadow: 'lg',
+      color: 'fg',
+    },
+    arrowTip: {
+      borderColor: 'border.emphasized',
+    },
+  },
+});
+
+const dropdownContent = {
+  bg: 'bg.muted',
+  borderColor: 'border.emphasized',
+  borderRadius: 'lg',
+  borderWidth: '1px',
+  boxShadow: 'lg',
+  color: 'fg',
+};
+
+const dropdownItem = {
+  _highlighted: { bg: 'bg.subtle' },
+  _focusVisible: {
+    outline: '2px solid',
+    outlineColor: 'accent.solid',
+    outlineOffset: '-2px',
+  },
+};
+
+const dropdownGroupLabel = {
+  color: 'fg.subtle',
+  fontSize: '2xs',
+  fontWeight: '600',
+  letterSpacing: '0.02em',
+  textTransform: 'uppercase',
+};
+
+/** Menu / context-menu chrome: popover surface with an emphasized stroke. */
+export const menuSlotRecipe = defineSlotRecipe({
+  ...chakraSlotRecipes.menu,
+  base: {
+    ...chakraSlotRecipes.menu.base,
+    content: {
+      ...chakraSlotRecipes.menu.base?.content,
+      ...dropdownContent,
+    },
+    item: {
+      ...chakraSlotRecipes.menu.base?.item,
+      ...dropdownItem,
+    },
+    itemGroupLabel: {
+      ...chakraSlotRecipes.menu.base?.itemGroupLabel,
+      ...dropdownGroupLabel,
+    },
+    separator: {
+      ...chakraSlotRecipes.menu.base?.separator,
+      bg: 'border.subtle',
+    },
+  },
+  defaultVariants: {
+    ...chakraSlotRecipes.menu.defaultVariants,
+    size: 'sm',
+  },
+});
+
+/** Select dropdown chrome: same surface and item treatment as menus. */
+export const selectSlotRecipe = defineSlotRecipe({
+  ...chakraSlotRecipes.select,
+  base: {
+    ...chakraSlotRecipes.select.base,
+    content: {
+      ...chakraSlotRecipes.select.base?.content,
+      ...dropdownContent,
+    },
+    item: {
+      ...chakraSlotRecipes.select.base?.item,
+      ...dropdownItem,
+    },
+    itemGroupLabel: {
+      ...chakraSlotRecipes.select.base?.itemGroupLabel,
+      ...dropdownGroupLabel,
+    },
+  },
+});
+
+/** Combobox chrome: kept aligned with Select for future searchable fields. */
+export const comboboxSlotRecipe = defineSlotRecipe({
+  ...chakraSlotRecipes.combobox,
+  base: {
+    ...chakraSlotRecipes.combobox.base,
+    content: {
+      ...chakraSlotRecipes.combobox.base?.content,
+      ...dropdownContent,
+    },
+    input: {
+      ...chakraSlotRecipes.combobox.base?.input,
+      _hover: { borderColor: 'border.emphasized' },
+    },
+    item: {
+      ...chakraSlotRecipes.combobox.base?.item,
+      ...dropdownItem,
+    },
+    itemGroupLabel: {
+      ...chakraSlotRecipes.combobox.base?.itemGroupLabel,
+      ...dropdownGroupLabel,
+    },
+  },
+});
+
+/** Dialog chrome: panel surface with a hairline stroke. */
+export const dialogSlotRecipe = defineSlotRecipe({
+  ...chakraSlotRecipes.dialog,
+  base: {
+    ...chakraSlotRecipes.dialog.base,
+    content: {
+      ...chakraSlotRecipes.dialog.base?.content,
+      borderColor: 'border.subtle',
+      borderWidth: '1px',
+    },
+  },
+});
+
+/** Slider marks: compact auxiliary labels for dense widget controls. */
+export const sliderSlotRecipe = defineSlotRecipe({
+  ...chakraSlotRecipes.slider,
+  base: {
+    ...chakraSlotRecipes.slider.base,
+    markerLabel: {
+      ...chakraSlotRecipes.slider.base?.markerLabel,
+      color: 'fg.subtle',
+      fontSize: '0.5rem',
+      lineHeight: '1',
+    },
+  },
+});
+
+/** Progress circle: add a compact icon-sized variant for dense chrome like tabs. */
+export const progressCircleSlotRecipe = defineSlotRecipe({
+  ...chakraSlotRecipes.progressCircle,
+  variants: {
+    ...chakraSlotRecipes.progressCircle.variants,
+    size: {
+      ...chakraSlotRecipes.progressCircle.variants?.size,
+      '2xs': {
+        circle: {
+          '--size': '16px',
+          '--thickness': '3px',
+        },
+        valueText: {
+          textStyle: '2xs',
+        },
+      },
+    },
+  },
+});
+
+/* -------------------------------------------------------------------------- *
+ * Workbench recipes (consumed through workbench/components/ui wrappers)
+ * -------------------------------------------------------------------------- */
+
+/** Bordered surface container — panels, cards, wells. */
+export const panelRecipe = defineRecipe({
+  base: {
+    bg: 'bg.subtle',
+    borderColor: 'border.subtle',
+    borderRadius: 'md',
+    borderWidth: '1px',
+    display: 'flex',
+    flexDirection: 'column',
+    minH: '0',
+    minW: '0',
+  },
+  variants: {
+    tone: {
+      surface: {},
+      raised: { bg: 'bg.muted' },
+      inset: { bg: 'bg.inset' },
+      control: { bg: 'bg.emphasized', borderColor: 'transparent' },
+    },
+    density: {
+      none: {},
+      sm: { gap: '1.5', p: '2' },
+      md: { gap: '2', p: '3' },
+    },
+  },
+  defaultVariants: { tone: 'surface', density: 'none' },
+});
+
+/** Interactive list / table row with hover, focus, and active fills. */
+export const rowRecipe = defineRecipe({
+  base: {
+    alignItems: 'center',
+    borderRadius: 'sm',
+    cursor: 'pointer',
+    display: 'flex',
+    gap: '2',
+    textAlign: 'start',
+    transition: 'background var(--wb-motion-duration-fast) ease, color var(--wb-motion-duration-fast) ease',
+    w: 'full',
+    _hover: { bg: 'bg.muted' },
+    _focusVisible: {
+      outline: '2px solid',
+      outlineColor: 'accent.solid',
+      outlineOffset: '-2px',
+    },
+    _disabled: { cursor: 'not-allowed', opacity: 0.5 },
+  },
+  variants: {
+    active: {
+      none: {},
+      muted: { bg: 'bg.muted' },
+      brand: {
+        bg: 'brand.subtle',
+        color: 'brand.fg',
+        _hover: { bg: 'brand.subtle' },
+      },
+      accent: {
+        bg: 'accent.solid',
+        color: 'accent.contrast',
+        _hover: { bg: 'accent.solid' },
+      },
+    },
+  },
+  defaultVariants: { active: 'none' },
+});
+
+/** Compact status chip with intent tones — queue counts, server state, versions. */
+export const chipRecipe = defineRecipe({
+  base: {
+    alignItems: 'center',
+    borderRadius: 'sm',
+    display: 'inline-flex',
+    flexShrink: '0',
+    fontSize: '2xs',
+    fontWeight: '500',
+    gap: '1.5',
+    px: '2',
+    py: '0.5',
+    whiteSpace: 'nowrap',
+  },
+  variants: {
+    tone: {
+      neutral: {},
+      brand: { bg: 'brand.subtle', color: 'brand.fg' },
+      accent: { color: 'accent.solid' },
+      error: { color: 'fg.error' },
+      success: { color: 'fg.success' },
+      warning: { color: 'fg.warning' },
+    },
+  },
+  defaultVariants: { tone: 'neutral' },
+});
+
+/** Compact uppercase field label shared across widget forms and the settings modal. */
+export const fieldLabelRecipe = defineRecipe({
+  base: {
+    color: 'fg.muted',
+    fontSize: '2xs',
+    fontWeight: '600',
+    letterSpacing: '0.03em',
+  },
+});
+
+/** Selectable theme swatch card used by the Settings appearance picker. */
+export const themeCardRecipe = defineSlotRecipe({
+  slots: ['root', 'preview', 'swatch', 'body', 'name', 'description', 'indicator'],
+  base: {
+    root: {
+      alignItems: 'stretch',
+      bg: 'bg.subtle',
+      borderColor: 'border.subtle',
+      borderRadius: 'lg',
+      borderWidth: '1px',
+      cursor: 'pointer',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '2.5',
+      overflow: 'hidden',
+      p: '3',
+      textAlign: 'left',
+      transition:
+        'border-color var(--wb-motion-duration-fast) ease, background var(--wb-motion-duration-fast) ease, transform var(--wb-motion-duration-fast) ease',
+      _hover: { borderColor: 'border.emphasized' },
+      _focusVisible: {
+        outline: '2px solid',
+        outlineColor: 'accent.solid',
+        outlineOffset: '2px',
+      },
+    },
+    preview: {
+      borderColor: 'border.subtle',
+      borderRadius: 'md',
+      borderWidth: '1px',
+      display: 'flex',
+      h: '8',
+      overflow: 'hidden',
+    },
+    swatch: { flex: '1' },
+    body: {
+      alignItems: 'flex-start',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '0.5',
+    },
+    name: { color: 'fg', fontSize: 'sm', fontWeight: '600' },
+    description: { color: 'fg.subtle', fontSize: '2xs', lineHeight: '1.3' },
+    indicator: {
+      alignItems: 'center',
+      borderRadius: 'full',
+      color: 'accent.solid',
+      display: 'flex',
+      h: '4',
+      justifyContent: 'center',
+      opacity: 0,
+      w: '4',
+    },
+  },
+  variants: {
+    selected: {
+      true: {
+        root: { borderColor: 'accent.solid', bg: 'bg.muted' },
+        indicator: { opacity: 1 },
+      },
+      false: {},
+    },
+  },
+  defaultVariants: { selected: false },
+});
diff --git a/invokeai/frontend/webv2/src/theme/system.test.ts b/invokeai/frontend/webv2/src/theme/system.test.ts
new file mode 100644
index 00000000000..a4c76d9de1b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/theme/system.test.ts
@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest';
+
+import legacyBaseline from './__fixtures__/legacyTokenBaseline.json';
+import { CONSUMER_TOKENS, resolveToken, THEMES, type TokenSystem } from './__tokenResolve';
+import { progressCircleSlotRecipe } from './recipes';
+import { system } from './system';
+
+const sys = system as unknown as TokenSystem;
+const STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
+
+const lightnessOf = (oklch: string): number => {
+  const match = /oklch\(\s*([\d.]+)%/.exec(oklch);
+  if (!match) {
+    throw new Error(`not a plain oklch value: ${oklch}`);
+  }
+  return Number(match[1]);
+};
+
+describe('color token contract — legacy-value gate', () => {
+  // Primary gate: every consumer token must resolve to the EXACT value it had
+  // before the ramp refactor. The baseline was captured from the previous system
+  // on the working tree before any change (see __fixtures__/legacyTokenBaseline.json).
+  for (const theme of THEMES) {
+    for (const token of CONSUMER_TOKENS) {
+      it(`${theme}: ${token} is unchanged`, () => {
+        const expected = (legacyBaseline as Record<string, Record<string, string>>)[theme][token];
+        expect(resolveToken(sys, theme, token)).toBe(expected);
+      });
+    }
+  }
+});
+
+describe('ramp + mapping structure', () => {
+  it('emits every neutral ramp step for every theme', () => {
+    for (const theme of THEMES) {
+      for (const step of STEPS) {
+        expect(resolveToken(sys, theme, `neutral.${step}`)).toMatch(/^oklch\(/);
+      }
+    }
+  });
+
+  it('maps the light surface ladder to the corrected (non-mirrored) steps', () => {
+    // The point-1 fix: light bg sits at neutral.200, not the lightest step.
+    expect(resolveToken(sys, 'light', 'bg')).toBe(resolveToken(sys, 'light', 'neutral.200'));
+    expect(resolveToken(sys, 'light', 'bg.subtle')).toBe(resolveToken(sys, 'light', 'neutral.50'));
+    expect(resolveToken(sys, 'light', 'bg.muted')).toBe(resolveToken(sys, 'light', 'neutral.100'));
+    expect(resolveToken(sys, 'light', 'border')).toBe(resolveToken(sys, 'light', 'neutral.300'));
+    expect(resolveToken(sys, 'light', 'border.emphasized')).toBe(resolveToken(sys, 'light', 'neutral.400'));
+  });
+
+  it('maps the dark surface ladder onto the ramp', () => {
+    expect(resolveToken(sys, 'classic', 'bg')).toBe(resolveToken(sys, 'classic', 'neutral.950'));
+    expect(resolveToken(sys, 'classic', 'bg.subtle')).toBe(resolveToken(sys, 'classic', 'neutral.900'));
+    expect(resolveToken(sys, 'classic', 'fg')).toBe(resolveToken(sys, 'classic', 'neutral.50'));
+    expect(resolveToken(sys, 'classic', 'border')).toBe(resolveToken(sys, 'classic', 'neutral.600'));
+  });
+
+  it('emits surface/text/border tokens via per-theme conditions only — never the leaky mode selectors', () => {
+    // Chakra's `_light` selector (`:root &, .light &`) matches under EVERY theme via its
+    // `:root &` arm. A surface token placed there leaks its light value into the dark
+    // themes (the classic-renders-light regression). These tokens must live ONLY in the
+    // base + `[data-theme=…]` selectors.
+    const layer = sys.getTokenCss()['@layer tokens'];
+    const LEAKY = [':root &, .light &', '.dark &, .dark .chakra-theme:not(.light) &'];
+    const surfaceTokens = [
+      'bg',
+      'bg.subtle',
+      'bg.muted',
+      'bg.panel',
+      'fg',
+      'fg.muted',
+      'fg.subtle',
+      'border',
+      'border.subtle',
+      'border.muted',
+      'border.emphasized',
+    ];
+    for (const name of surfaceTokens) {
+      const token = sys.tokens.getByName(`colors.${name}`);
+      const cssVar = token?.extensions.cssVar.var ?? '';
+      for (const selector of LEAKY) {
+        expect(layer[selector]?.[cssVar], `${name} must not be emitted under "${selector}"`).toBeUndefined();
+      }
+    }
+  });
+
+  it('keeps each ramp strictly decreasing in lightness 50 → 950', () => {
+    for (const theme of THEMES) {
+      const ls = STEPS.map((step) => lightnessOf(resolveToken(sys, theme, `neutral.${step}`)));
+      for (let i = 1; i < ls.length; i++) {
+        expect(ls[i], `${theme} neutral.${STEPS[i]} should be darker than neutral.${STEPS[i - 1]}`).toBeLessThan(
+          ls[i - 1]
+        );
+      }
+    }
+  });
+});
+
+describe('native Chakra integration', () => {
+  it('adds an icon-sized progress circle variant', () => {
+    expect(progressCircleSlotRecipe.variants?.size?.['2xs']).toMatchObject({
+      circle: { '--size': '16px', '--thickness': '3px' },
+    });
+  });
+
+  it('resolves every gray virtual-palette key under both dark and light', () => {
+    const keys = ['contrast', 'fg', 'subtle', 'muted', 'emphasized', 'solid', 'focusRing', 'border'];
+    for (const theme of ['classic', 'light']) {
+      for (const key of keys) {
+        expect(resolveToken(sys, theme, `gray.${key}`)).toBeTruthy();
+      }
+    }
+  });
+
+  it('leaves stock Chakra hue palettes untouched in Phase 1', () => {
+    // Phase 2 will theme these; for now they must remain Chakra defaults so model
+    // badges / destructive actions keep their stock colors.
+    expect(sys.tokens.getByName('colors.red.500')).toBeTruthy();
+    expect(sys.tokens.getByName('colors.blue.500')).toBeTruthy();
+    expect(sys.tokens.getByName('colors.purple.500')).toBeTruthy();
+  });
+});
+
+describe('brand palette derives from its two seeds (like accent)', () => {
+  it('fg/border equal solid; subtle/muted/emphasized mix solid into the surface', () => {
+    for (const theme of THEMES) {
+      const solid = resolveToken(sys, theme, 'brand.solid');
+      const surface = resolveToken(sys, theme, 'bg.subtle');
+      expect(resolveToken(sys, theme, 'brand.fg')).toBe(solid);
+      expect(resolveToken(sys, theme, 'brand.border')).toBe(solid);
+      for (const [key, pct] of [
+        ['subtle', 16],
+        ['muted', 26],
+        ['emphasized', 36],
+      ] as const) {
+        expect(resolveToken(sys, theme, `brand.${key}`)).toBe(`color-mix(in oklab, ${solid} ${pct}%, ${surface})`);
+      }
+    }
+  });
+});
diff --git a/invokeai/frontend/webv2/src/theme/system.ts b/invokeai/frontend/webv2/src/theme/system.ts
new file mode 100644
index 00000000000..86a769dde05
--- /dev/null
+++ b/invokeai/frontend/webv2/src/theme/system.ts
@@ -0,0 +1,290 @@
+import { createSystem, defaultConfig, defineConfig } from '@chakra-ui/react';
+
+import {
+  comboboxSlotRecipe,
+  dialogSlotRecipe,
+  menuSlotRecipe,
+  progressCircleSlotRecipe,
+  selectSlotRecipe,
+  sliderSlotRecipe,
+  tooltipSlotRecipe,
+} from './recipes';
+import { DEFAULT_THEME, DEFAULT_THEME_ID, type NeutralStep, THEMES, type ThemeDefinition } from './themes';
+
+/**
+ * Workbench design system.
+ *
+ * Each theme (`themes.ts`) is authored as one neutral ramp (`neutral.50…neutral.950`,
+ * lightest → darkest) plus a few seeds (brand, accent, status) and four off-ramp
+ * neutrals (`inset`, `fill`, `grid`, `control`). This module turns that into two
+ * token layers:
+ *
+ *   1. The **ramp** is emitted verbatim as conditional semantic tokens
+ *      (`neutral.*`), one value per theme keyed on a custom `[data-theme=<id>]`
+ *      condition. Chakra base `tokens.colors` only hold plain strings, so anything
+ *      that varies per theme must live in `semanticTokens`.
+ *   2. The **semantic contract** (`bg`, `fg.muted`, `border.emphasized`, the
+ *      `gray`/`brand`/`accent` palettes, …) is theme-agnostic: it references ramp
+ *      steps and flips by light/dark mode only. `bg` is `neutral.950` in dark mode and
+ *      `neutral.200` in light — the light ramp is not a mirror of the dark one, because
+ *      light panels go *whiter* than the app background.
+ *
+ * `ThemeController` sets `data-theme` (and the `.dark`/`.light` class) on `<html>`,
+ * so switching themes is a single attribute change with zero React re-render.
+ * Components reference only the semantic tokens — never the ramp or a theme.
+ *
+ * Re-pointing Chakra's neutral `gray` palette at the ramp makes every built-in
+ * component (Dialog, Menu, Input, Button, Tooltip, Badge) follow the active theme
+ * with no per-component overrides.
+ */
+
+const NON_DEFAULT_THEMES = THEMES.filter((theme) => theme.id !== DEFAULT_THEME_ID);
+
+/** `light` -> `themeLight`, `ultradark` -> `themeUltradark`. */
+const conditionName = (id: string): string => `theme${id.charAt(0).toUpperCase()}${id.slice(1)}`;
+
+type TokenValue = { value: Record<string, string> };
+type Compute = (theme: ThemeDefinition) => string;
+
+/** Build a semantic-token value object: default theme as `base`, the rest as `[data-theme]` conditions. */
+const colorToken = (compute: Compute): TokenValue => {
+  const value: Record<string, string> = { base: compute(DEFAULT_THEME) };
+  for (const theme of NON_DEFAULT_THEMES) {
+    value[`_${conditionName(theme.id)}`] = compute(theme);
+  }
+  return { value };
+};
+
+/** Blend `pct`% of one computed color into another — used for derived hover/tint steps. */
+const mix = (top: Compute, pct: number, bottom: Compute): TokenValue =>
+  colorToken((theme) => `color-mix(in oklab, ${top(theme)} ${pct}%, ${bottom(theme)})`);
+
+const LIGHT_FALLBACK_THEME = THEMES.find((theme) => theme.colorScheme === 'light') ?? DEFAULT_THEME;
+
+/**
+ * Like `colorToken`, but additionally shadows Chakra's `_light`/`_dark`
+ * class-conditional values. Nested palette tokens (`gray.*`) deep-merge with
+ * `defaultConfig` instead of replacing it, so without these keys the default
+ * gray values would survive the merge and outrank our zero-specificity `base`
+ * value whenever `ThemeController` sets the `.dark`/`.light` class. The explicit
+ * `:root[data-theme=…]` conditions still win over both.
+ */
+const grayToken = (compute: Compute): TokenValue => {
+  const token = colorToken(compute);
+  token.value._light = compute(LIGHT_FALLBACK_THEME);
+  token.value._dark = compute(DEFAULT_THEME);
+  return token;
+};
+
+/**
+ * A token that reads a ramp step, chosen per theme by `colorScheme`. Emitted as
+ * per-`[data-theme]` conditions, NOT Chakra's `_light`/`_dark`: the built-in
+ * `_light` selector is `:root &, .light &`, and its `:root &` arm matches under
+ * EVERY theme — so a mode-flip token leaks its light value into the dark themes.
+ * Per-theme conditions sidestep the cascade entirely (this is how the pre-refactor
+ * system worked, and why dark themes rendered correctly).
+ */
+const ref = (step: NeutralStep): string => `{colors.neutral.${step}}`;
+const stepRef = (darkStep: NeutralStep, lightStep: NeutralStep): TokenValue =>
+  colorToken((theme) => ref(theme.colorScheme === 'light' ? lightStep : darkStep));
+
+const STEPS: NeutralStep[] = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+
+/** The default panel surface of a theme — `bg.subtle`'s step. Used as the floor for tints. */
+const surface: Compute = (theme) =>
+  theme.colorScheme === 'light' ? theme.colors.neutral[50] : theme.colors.neutral[900];
+
+// Seed accessors.
+const danger: Compute = (theme) => theme.colors.danger;
+const success: Compute = (theme) => theme.colors.success;
+const warning: Compute = (theme) => theme.colors.warning;
+const brandSolid: Compute = (theme) => theme.colors.brand.solid;
+const accentSolid: Compute = (theme) => theme.colors.accent.solid;
+
+/** The neutral ramp, emitted as `neutral.50…neutral.950`, one value per theme. */
+const neutralRamp = Object.fromEntries(STEPS.map((step) => [step, colorToken((theme) => theme.colors.neutral[step])]));
+
+/**
+ * The semantic-token contract. Backgrounds/foregrounds/borders reference ramp
+ * steps (`stepRef`); the four off-ramp neutrals and the status/identity hues read
+ * their per-theme seed directly. Where a Chakra built-in name exists we use it
+ * verbatim so built-ins inherit the theme for free.
+ */
+const semanticColors = {
+  neutral: neutralRamp,
+
+  // Surface ladder. Light panels are whiter than the app bg, so the light steps
+  // are not a mirror of the dark ones.
+  bg: stepRef(950, 200),
+  'bg.subtle': stepRef(900, 50),
+  'bg.muted': stepRef(800, 100),
+  'bg.panel': stepRef(800, 100),
+  'bg.emphasized': colorToken((theme) => theme.colors.control),
+  'bg.inset': colorToken((theme) => theme.colors.inset),
+  // Soft status fills for alerts/banners, mixed into the panel surface.
+  'bg.error': mix(danger, 14, surface),
+  'bg.success': mix(success, 14, surface),
+  'bg.warning': mix(warning, 14, surface),
+
+  // Foreground.
+  fg: stepRef(50, 950),
+  'fg.muted': stepRef(300, 700),
+  'fg.subtle': stepRef(400, 500),
+  'fg.grid': colorToken((theme) => theme.colors.grid),
+  'fg.error': colorToken(danger),
+  'fg.success': colorToken(success),
+  'fg.warning': colorToken(warning),
+
+  // Borders.
+  border: stepRef(600, 300),
+  'border.subtle': stepRef(600, 300),
+  'border.muted': stepRef(600, 300),
+  'border.emphasized': stepRef(500, 400),
+  'border.error': colorToken(danger),
+
+  /**
+   * Chakra's default `colorPalette` is `gray`; re-pointing its virtual-palette
+   * keys at the ramp makes every un-palettized component (ghost buttons, menu
+   * items, badges, …) theme-aware with zero props.
+   *
+   * Palette tokens must stay NESTED — the `colorPalette` virtual-token map is
+   * built from the nested structure and ignores flat dotted keys. Because nesting
+   * deep-merges with the defaults, every gray key shadows the default
+   * `_light`/`_dark` values via `grayToken`.
+   */
+  gray: {
+    contrast: grayToken((theme) =>
+      theme.colorScheme === 'light' ? theme.colors.neutral[200] : theme.colors.neutral[950]
+    ),
+    fg: grayToken((theme) => (theme.colorScheme === 'light' ? theme.colors.neutral[950] : theme.colors.neutral[50])),
+    subtle: grayToken((theme) => theme.colors.fill),
+    muted: grayToken((theme) => theme.colors.control),
+    emphasized: grayToken((theme) =>
+      theme.colorScheme === 'light' ? theme.colors.neutral[400] : theme.colors.neutral[500]
+    ),
+    solid: grayToken((theme) => (theme.colorScheme === 'light' ? theme.colors.neutral[950] : theme.colors.neutral[50])),
+    focusRing: grayToken(accentSolid),
+    border: grayToken((theme) =>
+      theme.colorScheme === 'light' ? theme.colors.neutral[400] : theme.colors.neutral[500]
+    ),
+  },
+  /**
+   * Invoke identity palette (lime). Authored from two seeds (`solid` + `contrast`),
+   * like `accent`; the rest derive. NOTE: `brand.fg` is the bright `solid` fill, so
+   * `brand.fg` on `brand.subtle` reads well on the dark themes but is low-contrast in
+   * the light theme — brand is meant for emphasis fills, not body text.
+   */
+  brand: {
+    solid: colorToken(brandSolid),
+    contrast: colorToken((theme) => theme.colors.brand.contrast),
+    fg: colorToken(brandSolid),
+    subtle: mix(brandSolid, 16, surface),
+    muted: mix(brandSolid, 26, surface),
+    emphasized: mix(brandSolid, 36, surface),
+    focusRing: colorToken(accentSolid),
+    border: colorToken(brandSolid),
+  },
+  /** Selection / focus palette (blue). Use via `accent.solid` or `colorPalette="accent"`. */
+  accent: {
+    solid: colorToken(accentSolid),
+    contrast: colorToken((theme) => theme.colors.accent.contrast),
+    fg: colorToken(accentSolid),
+    subtle: mix(accentSolid, 16, surface),
+    muted: mix(accentSolid, 26, surface),
+    emphasized: mix(accentSolid, 36, surface),
+    focusRing: colorToken(accentSolid),
+    border: colorToken(accentSolid),
+  },
+};
+
+// `:root` raises specificity above the `.dark`/`.light` colorScheme classes so
+// an explicit theme always beats the class-conditional fallback values.
+const themeConditions = Object.fromEntries(
+  NON_DEFAULT_THEMES.map((theme) => [conditionName(theme.id), `:root[data-theme=${theme.id}]`])
+);
+
+const motionDurationToken = (base: string): TokenValue => ({ value: { base, _reduceMotion: '1ms' } });
+const motionAnimationToken = (base: string): TokenValue => ({ value: { base, _reduceMotion: 'none' } });
+
+const config = defineConfig({
+  conditions: { ...themeConditions, reduceMotion: ':root[data-reduce-motion=true]' },
+  globalCss: {
+    'html, body, #root': {
+      height: '100%',
+    },
+    body: {
+      bg: 'bg',
+      color: 'fg',
+      fontFamily: 'body',
+      margin: 0,
+      minHeight: '720px',
+      minWidth: '960px',
+      overflow: 'hidden',
+    },
+    ':root': {
+      '--wb-motion-duration-fast': '0.12s',
+      '--wb-motion-duration-medium': '0.15s',
+      '--wb-motion-duration-slow': '0.2s',
+      '--wb-motion-animation-iteration-count': 'infinite',
+    },
+    // Keep durations non-zero: Ark presence waits for animation lifecycle events.
+    // Chakra recipe motion is covered by conditional duration/animation tokens below.
+    ':root[data-reduce-motion="true"]': {
+      '--wb-motion-duration-fast': '1ms',
+      '--wb-motion-duration-medium': '1ms',
+      '--wb-motion-duration-slow': '1ms',
+      '--wb-motion-animation-iteration-count': '1',
+      scrollBehavior: 'auto !important',
+    },
+    ':root[data-reduce-motion="true"] .chakra-skeleton': {
+      animation: 'none !important',
+    },
+  },
+  theme: {
+    tokens: {
+      fonts: {
+        body: {
+          value: "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        },
+        heading: {
+          value: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif",
+        },
+      },
+    },
+    semanticTokens: {
+      animations: {
+        bounce: motionAnimationToken('bounce 1s infinite'),
+        ping: motionAnimationToken('ping 1s cubic-bezier(0, 0, 0.2, 1) infinite'),
+        pulse: motionAnimationToken('pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite'),
+        spin: motionAnimationToken('spin 1s linear infinite'),
+      },
+      colors: semanticColors,
+      durations: {
+        fastest: motionDurationToken('50ms'),
+        faster: motionDurationToken('100ms'),
+        fast: motionDurationToken('150ms'),
+        moderate: motionDurationToken('200ms'),
+        slow: motionDurationToken('300ms'),
+        slower: motionDurationToken('400ms'),
+        slowest: motionDurationToken('500ms'),
+      },
+    },
+    // Chrome-level overrides for Chakra's built-in components, so popover and
+    // dialog surfaces are consistent everywhere without per-instance props.
+    slotRecipes: {
+      combobox: comboboxSlotRecipe,
+      dialog: dialogSlotRecipe,
+      menu: menuSlotRecipe,
+      progressCircle: progressCircleSlotRecipe,
+      select: selectSlotRecipe,
+      slider: sliderSlotRecipe,
+      tooltip: tooltipSlotRecipe,
+    },
+  },
+});
+
+export const system = createSystem(defaultConfig, config);
+
+/** Theme metadata re-exported so UI can import a single module. */
+export { THEMES, THEMES_BY_ID, DEFAULT_THEME, DEFAULT_THEME_ID, previewSwatches } from './themes';
+export type { ThemeColors, ThemeDefinition, NeutralStep } from './themes';
diff --git a/invokeai/frontend/webv2/src/theme/themes.ts b/invokeai/frontend/webv2/src/theme/themes.ts
new file mode 100644
index 00000000000..082823b5b89
--- /dev/null
+++ b/invokeai/frontend/webv2/src/theme/themes.ts
@@ -0,0 +1,265 @@
+import type { WorkbenchThemeId } from '@workbench/types';
+
+/**
+ * Steps of the neutral ramp. `50` is the lightest, `950` the darkest — the same
+ * absolute orientation Chakra/Tailwind use, so the ramp can be aliased onto the
+ * built-in `gray` palette without surprises.
+ */
+export type NeutralStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950;
+
+/**
+ * One workbench theme, expressed as a small set of concrete OKLch values.
+ *
+ * The bulk of a theme is the `base` ramp — a single neutral scale from which the
+ * semantic-token layer in `system.ts` derives every background, foreground, and
+ * border (`bg → neutral.950` in dark mode, `fg → neutral.50`, …). Everything else is a
+ * handful of seeds:
+ *
+ *   - `brand` / `accent` — the two identity hues (lime action, blue selection);
+ *   - `danger` / `success` / `warning` — status intents;
+ *   - `inset` / `fill` / `grid` / `control` — four neutrals whose *elevation rank*
+ *     differs from theme to theme, so they cannot sit on a single shared ramp step
+ *     (e.g. `inset` recesses below the app background in the light theme but lifts
+ *     above it in the dark themes). They are kept as explicit per-theme values and
+ *     consumed by name through `bg.inset`, `fg.grid`, `gray.subtle`, `bg.emphasized`.
+ *
+ * Adding a theme is therefore: author one ramp + the seeds. No component changes.
+ */
+export interface ThemeColors {
+  /** Neutral ramp, lightest (`50`) → darkest (`950`). Source of all bg/fg/border. */
+  neutral: Record<NeutralStep, string>;
+  /** Invoke identity (lime). Two seeds; the palette's other steps derive in `system.ts`. */
+  brand: { solid: string; contrast: string };
+  /** Selection / focus (blue). */
+  accent: { solid: string; contrast: string };
+  /** Destructive / error intent. */
+  danger: string;
+  /** Positive / success intent. */
+  success: string;
+  /** Caution / warning intent. */
+  warning: string;
+  /** Recessed work-area floor framed by the chrome (`bg.inset`). Off-ramp. */
+  inset: string;
+  /** Subtle neutral fill for hovered/ghost controls (`gray.subtle`). Off-ramp. */
+  fill: string;
+  /** Dot-grid decoration drawn on inset surfaces (`fg.grid`). Off-ramp. */
+  grid: string;
+  /** Control / chip fill inside panels (`bg.emphasized`). Off-ramp. */
+  control: string;
+}
+
+export interface ThemeDefinition {
+  id: WorkbenchThemeId;
+  label: string;
+  description: string;
+  /** Native color-scheme hint for form controls, scrollbars, and `<select>` popups. */
+  colorScheme: 'dark' | 'light';
+  colors: ThemeColors;
+}
+
+const classic: ThemeColors = {
+  neutral: {
+    50: 'oklch(96.017% 0.0029 264.54)',
+    100: 'oklch(91.561% 0.0064 264.52)',
+    200: 'oklch(82.648% 0.0133 264.48)',
+    300: 'oklch(73.736% 0.0202 264.44)',
+    400: 'oklch(57.965% 0.0337 264.27)',
+    500: 'oklch(45.106% 0.0251 264.28)',
+    600: 'oklch(40.619% 0.0221 264.29)',
+    700: 'oklch(36.004% 0.019 264.3)',
+    800: 'oklch(31.237% 0.0157 264.32)',
+    900: 'oklch(26.279% 0.0123 264.34)',
+    950: 'oklch(21.074% 0.0087 264.37)',
+  },
+  brand: { solid: 'oklch(92.041% 0.2103 116.59)', contrast: 'oklch(21.074% 0.0087 264.37)' },
+  accent: { solid: 'oklch(77.738% 0.1 231.76)', contrast: 'oklch(21.074% 0.0087 264.37)' },
+  danger: 'oklch(70.61% 0.0841 19.38)',
+  success: 'oklch(79.8% 0.1132 141.63)',
+  warning: 'oklch(76.62% 0.0612 62.9)',
+  inset: 'oklch(21.074% 0.0087 264.37)',
+  fill: 'oklch(31.237% 0.0157 264.32)',
+  grid: 'oklch(40.619% 0.0221 264.29)',
+  control: 'oklch(36.004% 0.019 264.3)',
+};
+
+// Cool blue-gray neutrals (hue 264, harmonizing with the blue accent): near-white
+// chrome floating on a soft-gray work floor, near-black cool text. Airy and clean.
+const light: ThemeColors = {
+  neutral: {
+    50: 'oklch(99.4% 0.002 264)',
+    100: 'oklch(97% 0.003 264)',
+    200: 'oklch(96% 0.0038 264)',
+    300: 'oklch(90.5% 0.0065 264)',
+    400: 'oklch(84% 0.0095 264)',
+    500: 'oklch(63% 0.014 264)',
+    600: 'oklch(53.5% 0.016 264)',
+    700: 'oklch(45% 0.017 264)',
+    800: 'oklch(35% 0.015 264)',
+    900: 'oklch(27% 0.013 264)',
+    950: 'oklch(22.5% 0.013 264)',
+  },
+  brand: { solid: 'oklch(92.041% 0.2103 116.59)', contrast: 'oklch(22.5% 0.013 264)' },
+  accent: { solid: 'oklch(54.615% 0.2152 262.88)', contrast: 'oklch(100% 0 0)' },
+  danger: 'oklch(55.509% 0.1707 24.62)',
+  success: 'oklch(53% 0.15 150)',
+  warning: 'oklch(60% 0.13 72)',
+  inset: 'oklch(96% 0.0038 264)',
+  fill: 'oklch(95.5% 0.005 264)',
+  grid: 'oklch(88.5% 0.0075 264)',
+  control: 'oklch(93.5% 0.005 264)',
+};
+
+const forest: ThemeColors = {
+  neutral: {
+    50: 'oklch(90.57% 0.0511 134.45)',
+    100: 'oklch(86.78% 0.0524 134.61)',
+    200: 'oklch(79.199% 0.0549 134.93)',
+    300: 'oklch(71.619% 0.0575 135.25)',
+    400: 'oklch(53.577% 0.0538 136.73)',
+    500: 'oklch(36.133% 0.0575 141.06)',
+    600: 'oklch(27.425% 0.0354 143.04)',
+    700: 'oklch(25.62% 0.03 144.64)',
+    800: 'oklch(20.99% 0.0219 144.74)',
+    900: 'oklch(19.03% 0.0175 144.85)',
+    950: 'oklch(17.349% 0.0154 144.88)',
+  },
+  brand: { solid: 'oklch(79.714% 0.1784 136.37)', contrast: 'oklch(18.298% 0.0314 147.69)' },
+  accent: { solid: 'oklch(70.437% 0.1101 178.23)', contrast: 'oklch(17.44% 0.0258 171.89)' },
+  danger: 'oklch(69.305% 0.1467 35.44)',
+  success: 'oklch(78% 0.16 148)',
+  warning: 'oklch(80% 0.12 76)',
+  inset: 'oklch(17.349% 0.0154 144.88)',
+  fill: 'oklch(28.489% 0.0483 141.22)',
+  grid: 'oklch(34.825% 0.0526 141.63)',
+  control: 'oklch(25.62% 0.03 144.64)',
+};
+
+const mono: ThemeColors = {
+  neutral: {
+    50: 'oklch(93.1% 0 0)',
+    100: 'oklch(88.789% 0 0)',
+    200: 'oklch(80.168% 0 0)',
+    300: 'oklch(71.547% 0 0)',
+    400: 'oklch(53.824% 0 0)',
+    500: 'oklch(34.846% 0 0)',
+    600: 'oklch(28.908% 0 0)',
+    700: 'oklch(27.274% 0 0)',
+    800: 'oklch(22.213% 0 0)',
+    900: 'oklch(20.019% 0 0)',
+    950: 'oklch(18.22% 0 0)',
+  },
+  brand: { solid: 'oklch(93.1% 0 0)', contrast: 'oklch(18.22% 0 0)' },
+  accent: { solid: 'oklch(68.622% 0 0)', contrast: 'oklch(18.22% 0 0)' },
+  danger: 'oklch(71.115% 0.0934 19.64)',
+  success: 'oklch(76% 0.06 150)',
+  warning: 'oklch(79% 0.07 80)',
+  inset: 'oklch(18.22% 0 0)',
+  fill: 'oklch(28.908% 0 0)',
+  grid: 'oklch(32.897% 0 0)',
+  control: 'oklch(27.274% 0 0)',
+};
+
+const ultradark: ThemeColors = {
+  neutral: {
+    50: 'oklch(88.901% 0.0317 120.83)',
+    100: 'oklch(84.397% 0.0292 123.06)',
+    200: 'oklch(75.39% 0.0242 127.51)',
+    300: 'oklch(66.382% 0.0192 131.96)',
+    400: 'oklch(47.041% 0.0184 127.12)',
+    500: 'oklch(26.862% 0 0)',
+    600: 'oklch(20.904% 0 0)',
+    700: 'oklch(19.125% 0 0)',
+    800: 'oklch(14.479% 0 0)',
+    900: 'oklch(11.492% 0 0)',
+    950: 'oklch(0% 0 0)',
+  },
+  brand: { solid: 'oklch(93.444% 0.19 125.56)', contrast: 'oklch(15.913% 0.0233 128.66)' },
+  accent: { solid: 'oklch(80.623% 0.1248 228.24)', contrast: 'oklch(17.416% 0.0256 235.84)' },
+  danger: 'oklch(71.161% 0.1812 22.84)',
+  success: 'oklch(76.5% 0.16 150.5)',
+  warning: 'oklch(79.5% 0.13 80)',
+  inset: 'oklch(0% 0 0)',
+  fill: 'oklch(21.779% 0 0)',
+  grid: 'oklch(23.929% 0 0)',
+  control: 'oklch(19.125% 0 0)',
+};
+
+/**
+ * Theme registry. Order here is the display order in the Settings picker.
+ * `THEMES` is the single source of truth consumed by both the token builder
+ * and the settings UI.
+ */
+export const THEMES: ThemeDefinition[] = [
+  {
+    id: 'classic',
+    label: 'Classic',
+    description: 'The legacy blue-on-graphite workbench.',
+    colorScheme: 'dark',
+    colors: classic,
+  },
+  {
+    id: 'light',
+    label: 'Light',
+    description: 'Bright, high-contrast surfaces for daylight work.',
+    colorScheme: 'light',
+    colors: light,
+  },
+  {
+    id: 'forest',
+    label: 'Forest',
+    description: 'Deep greens with a leafy accent.',
+    colorScheme: 'dark',
+    colors: forest,
+  },
+  {
+    id: 'mono',
+    label: 'Mono',
+    description: 'Neutral grayscale with no color cast.',
+    colorScheme: 'dark',
+    colors: mono,
+  },
+  {
+    id: 'ultradark',
+    label: 'Ultra Dark',
+    description: 'Pure-black OLED surfaces for low-light rooms.',
+    colorScheme: 'dark',
+    colors: ultradark,
+  },
+];
+
+const defaultTheme = THEMES[0];
+
+if (!defaultTheme) {
+  throw new Error('At least one workbench theme must be defined.');
+}
+
+/** The default theme. Its ramp/seeds are emitted as the semantic-token `base` value. */
+export const DEFAULT_THEME = defaultTheme;
+
+export const DEFAULT_THEME_ID: WorkbenchThemeId = DEFAULT_THEME.id;
+
+export const THEMES_BY_ID: Record<WorkbenchThemeId, ThemeDefinition> = THEMES.reduce(
+  (accumulator, theme) => {
+    accumulator[theme.id] = theme;
+    return accumulator;
+  },
+  {} as Record<WorkbenchThemeId, ThemeDefinition>
+);
+
+export const isWorkbenchThemeId = (value: unknown): value is WorkbenchThemeId =>
+  typeof value === 'string' && Object.prototype.hasOwnProperty.call(THEMES_BY_ID, value);
+
+/** The default panel surface of a theme (lightest end in light mode, near-darkest in dark). */
+const surfaceOf = (theme: ThemeDefinition): string =>
+  theme.colorScheme === 'light' ? theme.colors.neutral[50] : theme.colors.neutral[900];
+
+/**
+ * The four representative chips shown in the Settings appearance picker:
+ * surface, control fill, brand, accent — a compact read of the theme's identity.
+ */
+export const previewSwatches = (theme: ThemeDefinition): [string, string, string, string] => [
+  surfaceOf(theme),
+  theme.colors.control,
+  theme.colors.brand.solid,
+  theme.colors.accent.solid,
+];
diff --git a/invokeai/frontend/webv2/src/vite-env.d.ts b/invokeai/frontend/webv2/src/vite-env.d.ts
new file mode 100644
index 00000000000..11f02fe2a00
--- /dev/null
+++ b/invokeai/frontend/webv2/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/invokeai/frontend/webv2/src/workbench/ThemeController.tsx b/invokeai/frontend/webv2/src/workbench/ThemeController.tsx
new file mode 100644
index 00000000000..64124ffe83f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/ThemeController.tsx
@@ -0,0 +1,84 @@
+import { DEFAULT_THEME, THEMES_BY_ID } from '@theme/system';
+import { useLayoutEffect } from 'react';
+
+import { useWorkbenchSettingsSelector } from './settings/store';
+import { shallowEqual } from './WorkbenchContext';
+
+/**
+ * Applies the persisted appearance preferences to the document root.
+ *
+ * Theme switching is intentionally a DOM-attribute flip rather than a React
+ * re-theme: the semantic-token conditions in `theme/system.ts` key off
+ * `<html data-theme>`, so changing the attribute restyles the whole shell with
+ * no component re-render. `data-reduce-motion` is read by global CSS motion
+ * tokens. Renders nothing.
+ */
+/**
+ * Read by the pre-paint script in index.html. Dedicated hint keys (rather than
+ * the workbench snapshot, which is per-user on multi-user backends) let first
+ * paint apply last-used appearance without knowing who is signed in.
+ */
+const THEME_HINT_STORAGE_KEY = 'invokeai:v7:webv2:theme';
+const REDUCE_MOTION_HINT_STORAGE_KEY = 'invokeai:v7:webv2:reduce-motion';
+
+export const ThemeController = () => {
+  const { reduceMotion, status, themeId } = useWorkbenchSettingsSelector(
+    (snapshot) => ({
+      reduceMotion: snapshot.preferences.reduceMotion,
+      status: snapshot.status,
+      themeId: snapshot.preferences.themeId,
+    }),
+    shallowEqual
+  );
+  // Until the settings store has resolved, the pre-paint hint script owns the
+  // theme; applying the store's defaults here would flash and clobber it.
+  const hasResolved = status === 'ready' || status === 'error';
+
+  useLayoutEffect(() => {
+    if (!hasResolved) {
+      return;
+    }
+
+    const root = document.documentElement;
+    const theme = THEMES_BY_ID[themeId] ?? DEFAULT_THEME;
+
+    root.dataset.theme = theme.id;
+    root.style.colorScheme = theme.colorScheme;
+    // Keep the native color-mode class in sync for unthemed browser chrome
+    // (scrollbars, native pickers) and any Chakra defaults we don't override.
+    root.classList.toggle('dark', theme.colorScheme === 'dark');
+    root.classList.toggle('light', theme.colorScheme === 'light');
+
+    try {
+      window.localStorage.setItem(THEME_HINT_STORAGE_KEY, theme.id);
+    } catch {
+      // Storage unavailable — the next load just paints the default theme.
+    }
+  }, [hasResolved, themeId]);
+
+  useLayoutEffect(() => {
+    if (!hasResolved) {
+      return;
+    }
+
+    const root = document.documentElement;
+
+    if (reduceMotion) {
+      root.dataset.reduceMotion = 'true';
+    } else {
+      delete root.dataset.reduceMotion;
+    }
+
+    try {
+      if (reduceMotion) {
+        window.localStorage.setItem(REDUCE_MOTION_HINT_STORAGE_KEY, 'true');
+      } else {
+        window.localStorage.removeItem(REDUCE_MOTION_HINT_STORAGE_KEY);
+      }
+    } catch {
+      // Storage unavailable — the next load just waits for settings to resolve.
+    }
+  }, [hasResolved, reduceMotion]);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/WorkbenchContext.tsx b/invokeai/frontend/webv2/src/workbench/WorkbenchContext.tsx
new file mode 100644
index 00000000000..273c175c8a1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/WorkbenchContext.tsx
@@ -0,0 +1,450 @@
+import {
+  createContext,
+  use,
+  useEffect,
+  useEffectEvent,
+  useRef,
+  useSyncExternalStore,
+  useState,
+  type Dispatch,
+  type ReactNode,
+} from 'react';
+
+import type {
+  Project,
+  ProjectLayoutState,
+  ProjectSettings,
+  WidgetInstanceId,
+  WidgetTypeId,
+  WorkbenchState,
+} from './types';
+
+import { WorkbenchSplashScreen } from './components/WorkbenchSplashScreen';
+import {
+  syncedWorkbenchPersistence,
+  type WorkbenchLoadOptions,
+  type WorkbenchSaveResult,
+} from './projects/syncedPersistence';
+import { getProjectWidgetValues } from './widgetState';
+import { getAutosaveScheduleDecision, isAutosaveCompletionCurrent } from './workbenchAutosave';
+import { shallowEqual as selectorShallowEqual, useExternalStoreSelector } from './workbenchSelectors';
+import {
+  createWorkbenchStore,
+  type WorkbenchAction,
+  type WorkbenchSnapshot,
+  type WorkbenchStore,
+} from './workbenchStore';
+
+interface WorkbenchContextValue {
+  state: WorkbenchState;
+  activeProject: Project;
+  dispatch: Dispatch<WorkbenchAction>;
+  /**
+   * True once the persisted snapshot has been loaded (or found absent). Side
+   * effects that read or mutate the queue must wait for this, or they race the
+   * async hydration and act on state that is about to be replaced.
+   */
+  hasHydrated: boolean;
+}
+
+type EqualityFn<T> = (left: T, right: T) => boolean;
+type WorkbenchSelector<T> = (snapshot: WorkbenchSnapshot) => T;
+
+const WorkbenchStoreContext = createContext<WorkbenchStore | null>(null);
+const subscribeToNothing = (): (() => void) => () => {};
+const getNullSnapshot = (): null => null;
+
+export const shallowEqual = selectorShallowEqual;
+
+/**
+ * The reducer dispatch alone, on its own context. `dispatch` is stable for the
+ * provider's lifetime, so subscribers never re-render on state changes — the
+ * subscription of choice for hot, many-instance components (e.g. flow nodes)
+ * that only write.
+ */
+const WorkbenchDispatchContext = createContext<Dispatch<WorkbenchAction> | null>(null);
+
+const AUTOSAVE_DELAY_MS = 500;
+
+export const WorkbenchProvider = ({
+  children,
+  loadOptions,
+}: {
+  children: ReactNode;
+  /** Boot-time session options (deep-linked project, fresh draft). Read once at mount. */
+  loadOptions?: WorkbenchLoadOptions;
+}) => {
+  const [store] = useState(() => createWorkbenchStore());
+  const dispatch = store.dispatch;
+  const [hasHydrated, setHasHydrated] = useState(store.getSnapshot().hasHydrated);
+  const hasLoadedPersistenceRef = useRef(false);
+  const lastSavedPersistedRevisionRef = useRef(store.getPersistedRevision());
+  const failedPersistedRevisionRef = useRef<number | null>(null);
+  // Captured once: the options describe how this mount of the editor boots.
+  // Later search-param changes are handled live by WorkbenchSessionController.
+  const bootOptionsRef = useRef(loadOptions);
+
+  useEffect(() => {
+    let isCancelled = false;
+
+    const loadPersistedState = async () => {
+      const bootOptions = bootOptionsRef.current;
+
+      try {
+        const snapshot = await syncedWorkbenchPersistence.loadWorkbench(bootOptions);
+
+        if (isCancelled) {
+          return;
+        }
+
+        if (snapshot) {
+          const isPendingSnapshot = syncedWorkbenchPersistence.hasPendingChanges();
+
+          dispatch({ state: snapshot.state, type: 'hydrateWorkbench' });
+
+          if (!isPendingSnapshot) {
+            lastSavedPersistedRevisionRef.current = store.getPersistedRevision();
+          }
+        }
+
+        const requestedId = bootOptions?.openProjectId;
+        const projects = snapshot?.state.projects ?? store.getState().projects;
+
+        if (requestedId && !projects.some((project) => project.id === requestedId)) {
+          dispatch({
+            kind: 'info',
+            message: 'The linked project does not exist on this account — it may have been deleted.',
+            title: 'Project not found',
+            type: 'recordNotice',
+          });
+        }
+      } catch (error) {
+        dispatch({
+          area: 'persistence-load',
+          message: error instanceof Error ? error.message : 'Failed to load persisted workbench.',
+          namespace: 'system',
+          type: 'recordError',
+        });
+      } finally {
+        hasLoadedPersistenceRef.current = true;
+
+        if (!isCancelled) {
+          store.setHasHydrated(true);
+          setHasHydrated(true);
+        }
+      }
+    };
+
+    void loadPersistedState();
+
+    return () => {
+      isCancelled = true;
+    };
+  }, [dispatch, store]);
+
+  // Revision conflicts surfaced by a save are applied to state here: the
+  // server version adopts the project id and the local edits continue in a
+  // recovered fork. The follow-up autosave still persists the reconciled
+  // session/cache, while project document pushes are no-ops because the sync
+  // layer already acknowledged them.
+  const applySaveResult = useEffectEvent((result: WorkbenchSaveResult): void => {
+    for (const conflict of result.conflicts) {
+      dispatch({
+        projectId: conflict.projectId,
+        recoveredProject: conflict.recoveredProject,
+        serverProject: conflict.serverProject,
+        type: 'reconcileProjectConflict',
+      });
+    }
+  });
+
+  useEffect(() => {
+    let timeoutId: number | null = null;
+    let saveGeneration = 0;
+    let scheduledPersistedRevision: number | null = null;
+
+    const clearScheduledSave = (): void => {
+      if (timeoutId !== null) {
+        window.clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+    };
+
+    const scheduleSave = (): void => {
+      if (!hasLoadedPersistenceRef.current) {
+        return;
+      }
+
+      const persistedRevision = store.getPersistedRevision();
+      const decision = getAutosaveScheduleDecision({
+        failedPersistedRevision: failedPersistedRevisionRef.current,
+        lastSavedPersistedRevision: lastSavedPersistedRevisionRef.current,
+        persistedRevision,
+        scheduledPersistedRevision,
+      });
+
+      failedPersistedRevisionRef.current = decision.failedPersistedRevision;
+
+      if (!decision.shouldSchedule) {
+        return;
+      }
+
+      scheduledPersistedRevision = persistedRevision;
+      saveGeneration += 1;
+      const generation = saveGeneration;
+
+      clearScheduledSave();
+
+      timeoutId = window.setTimeout(() => {
+        const stateToSave = store.getState();
+        const revisionToSave = store.getPersistedRevision();
+
+        dispatch({ type: 'autosaveStarted' });
+
+        syncedWorkbenchPersistence
+          .saveWorkbench(stateToSave)
+          .then((result) => {
+            if (generation !== saveGeneration) {
+              return;
+            }
+
+            lastSavedPersistedRevisionRef.current = revisionToSave;
+            failedPersistedRevisionRef.current = null;
+            scheduledPersistedRevision = null;
+            dispatch({ savedAt: result.snapshot.savedAt, type: 'autosaveSucceeded' });
+            applySaveResult(result);
+          })
+          .catch((error: unknown) => {
+            if (generation !== saveGeneration) {
+              return;
+            }
+
+            failedPersistedRevisionRef.current = revisionToSave;
+            scheduledPersistedRevision = null;
+            dispatch({
+              error: error instanceof Error ? error.message : 'Failed to autosave workbench.',
+              type: 'autosaveFailed',
+            });
+          });
+      }, AUTOSAVE_DELAY_MS);
+    };
+
+    const unsubscribe = store.subscribe(scheduleSave);
+    scheduleSave();
+
+    return () => {
+      unsubscribe();
+      saveGeneration += 1;
+      clearScheduledSave();
+    };
+  }, [dispatch, store]);
+
+  // Replay changes that queued up while the backend was unreachable as soon
+  // as the socket reports it is back.
+  useEffect(() => {
+    let previousStatus = store.getState().backendConnection.status;
+
+    return store.subscribe(() => {
+      const status = store.getState().backendConnection.status;
+
+      if (status === previousStatus) {
+        return;
+      }
+
+      previousStatus = status;
+
+      if (
+        status !== 'connected' ||
+        !hasLoadedPersistenceRef.current ||
+        !syncedWorkbenchPersistence.hasPendingChanges()
+      ) {
+        return;
+      }
+
+      const stateToSave = store.getState();
+      const revisionToSave = store.getPersistedRevision();
+
+      void syncedWorkbenchPersistence
+        .saveWorkbench(stateToSave)
+        .then((result) => {
+          if (
+            !isAutosaveCompletionCurrent({
+              completedPersistedRevision: revisionToSave,
+              currentPersistedRevision: store.getPersistedRevision(),
+            })
+          ) {
+            return;
+          }
+
+          lastSavedPersistedRevisionRef.current = revisionToSave;
+          failedPersistedRevisionRef.current = null;
+          dispatch({ savedAt: result.snapshot.savedAt, type: 'autosaveSucceeded' });
+          applySaveResult(result);
+        })
+        .catch((error: unknown) => {
+          if (
+            !isAutosaveCompletionCurrent({
+              completedPersistedRevision: revisionToSave,
+              currentPersistedRevision: store.getPersistedRevision(),
+            })
+          ) {
+            return;
+          }
+
+          failedPersistedRevisionRef.current = revisionToSave;
+          dispatch({
+            error: error instanceof Error ? error.message : 'Failed to autosave workbench.',
+            type: 'autosaveFailed',
+          });
+        });
+    });
+  }, [dispatch, store]);
+
+  return (
+    <WorkbenchStoreContext value={store}>
+      <WorkbenchDispatchContext value={dispatch}>
+        {hasHydrated ? children : <WorkbenchSplashScreen messageKey="splash.openingProject" />}
+      </WorkbenchDispatchContext>
+    </WorkbenchStoreContext>
+  );
+};
+
+export const useWorkbenchStore = (): WorkbenchStore => {
+  const store = use(WorkbenchStoreContext);
+
+  if (!store) {
+    throw new Error('useWorkbenchStore must be used within a WorkbenchProvider.');
+  }
+
+  return store;
+};
+
+export const useOptionalWorkbenchStore = (): WorkbenchStore | null => use(WorkbenchStoreContext);
+
+export const useWorkbenchSelector = <Selected,>(
+  selector: WorkbenchSelector<Selected>,
+  isEqual: EqualityFn<Selected> = shallowEqual
+): Selected => {
+  const store = useWorkbenchStore();
+
+  return useExternalStoreSelector(store.subscribe, store.getSnapshot, selector, isEqual);
+};
+
+export const useDebouncedWorkbenchSelector = <Selected,>(
+  selector: WorkbenchSelector<Selected>,
+  debounceMs = 300,
+  isEqual: EqualityFn<Selected> = Object.is
+): Selected => {
+  const liveSelection = useWorkbenchSelector(selector, isEqual);
+  const [selection, setSelection] = useState(liveSelection);
+
+  useEffect(() => {
+    if (isEqual(selection, liveSelection)) {
+      return;
+    }
+
+    const timeoutId = window.setTimeout(() => {
+      setSelection(liveSelection);
+    }, debounceMs);
+
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [debounceMs, isEqual, liveSelection, selection]);
+
+  return selection;
+};
+
+export const useActiveProject = (): Project => useWorkbenchSelector((snapshot) => snapshot.activeProject);
+
+export const useActiveProjectSelector = <Selected,>(
+  selector: (project: Project) => Selected,
+  isEqual?: EqualityFn<Selected>
+): Selected => useWorkbenchSelector((snapshot) => selector(snapshot.activeProject), isEqual);
+
+export const useActiveProjectId = (): string => useWorkbenchSelector((snapshot) => snapshot.state.activeProjectId);
+
+export const useActiveProjectName = (): string => useActiveProjectSelector((project) => project.name);
+
+export const useActiveProjectLayoutSelector = <Selected,>(
+  selector: (layout: ProjectLayoutState) => Selected,
+  isEqual?: EqualityFn<Selected>
+): Selected => useActiveProjectSelector((project) => selector(project.layout), isEqual);
+
+export const useActiveProjectSettingsSelector = <Selected,>(
+  selector: (settings: ProjectSettings) => Selected,
+  isEqual?: EqualityFn<Selected>
+): Selected => useActiveProjectSelector((project) => selector(project.settings), isEqual);
+
+export const useWidgetValuesSelector = <Selected,>(
+  widgetId: WidgetTypeId,
+  selector: (values: Record<string, unknown>) => Selected,
+  isEqual?: EqualityFn<Selected>
+): Selected => useActiveProjectSelector((project) => selector(getProjectWidgetValues(project, widgetId)), isEqual);
+
+export const useWidgetInstanceValuesSelector = <Selected,>(
+  instanceId: WidgetInstanceId,
+  selector: (values: Record<string, unknown>) => Selected,
+  isEqual?: EqualityFn<Selected>
+): Selected =>
+  useActiveProjectSelector((project) => selector(project.widgetInstances[instanceId]?.state.values ?? {}), isEqual);
+
+export const useProjectWidgetInstanceValuesSelector = <Selected,>(
+  projectId: string,
+  instanceId: WidgetInstanceId,
+  selector: (values: Record<string, unknown>) => Selected,
+  isEqual?: EqualityFn<Selected>
+): Selected =>
+  useWorkbenchSelector((snapshot) => {
+    const project = snapshot.state.projects.find((candidate) => candidate.id === projectId);
+
+    return selector(project?.widgetInstances[instanceId]?.state.values ?? {});
+  }, isEqual);
+
+export const useWorkbenchHasHydrated = (): boolean => useWorkbenchSelector((snapshot) => snapshot.hasHydrated);
+
+export const useOptionalWorkbenchSelector = <Selected,>(
+  selector: WorkbenchSelector<Selected>,
+  fallback: Selected,
+  isEqual: EqualityFn<Selected> = shallowEqual
+): Selected => {
+  const store = useOptionalWorkbenchStore();
+
+  return useExternalStoreSelector(
+    store?.subscribe ?? subscribeToNothing,
+    store?.getSnapshot ?? getNullSnapshot,
+    (snapshot) => (snapshot ? selector(snapshot) : fallback),
+    isEqual
+  );
+};
+
+export const useOptionalWorkbenchDispatch = (): Dispatch<WorkbenchAction> | null =>
+  useOptionalWorkbenchStore()?.dispatch ?? null;
+
+export const useWorkbench = (): WorkbenchContextValue => {
+  const store = useWorkbenchStore();
+  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+
+  return { ...snapshot, dispatch: store.dispatch };
+};
+
+export const useOptionalWorkbench = (): WorkbenchContextValue | null => {
+  const store = useOptionalWorkbenchStore();
+  const snapshot = useSyncExternalStore(
+    store?.subscribe ?? subscribeToNothing,
+    store?.getSnapshot ?? getNullSnapshot,
+    store?.getSnapshot ?? getNullSnapshot
+  );
+
+  return store && snapshot ? { ...snapshot, dispatch: store.dispatch } : null;
+};
+
+export const useWorkbenchDispatch = (): Dispatch<WorkbenchAction> => {
+  const dispatch = use(WorkbenchDispatchContext);
+
+  if (!dispatch) {
+    throw new Error('useWorkbenchDispatch must be used within a WorkbenchProvider.');
+  }
+
+  return dispatch;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/WorkbenchRuntime.test.ts b/invokeai/frontend/webv2/src/workbench/WorkbenchRuntime.test.ts
new file mode 100644
index 00000000000..45fa97d01fd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/WorkbenchRuntime.test.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest';
+
+import type { GenerateWidgetValues, MainModelConfig } from './generation/types';
+import type { GraphContract, Project, QueueItem } from './types';
+
+import { getDefaultGenerateSettings } from './generation/baseGenerationPolicies';
+import { createQueueItemBackendSubmission, getQueueItemResultImageOptions } from './WorkbenchRuntime';
+import { createInitialWorkbenchState } from './workbenchState';
+
+const model: MainModelConfig = { base: 'sd-1', key: 'sd1', name: 'SD 1.5', type: 'main' };
+
+const createValues = (overrides: Partial<GenerateWidgetValues> = {}): GenerateWidgetValues => ({
+  ...getDefaultGenerateSettings(model),
+  model,
+  modelKey: model.key,
+  negativePrompt: 'low quality',
+  positivePrompt: 'a canvas prompt',
+  seed: 123,
+  shouldRandomizeSeed: true,
+  ...overrides,
+});
+
+const graph: GraphContract = {
+  backendGraph: { edges: [], id: 'backend-graph', nodes: {} },
+  edges: [],
+  id: 'graph-1',
+  label: 'Canvas',
+  nodes: [],
+  updatedAt: '2026-06-09T00:00:00.000Z',
+  version: 1,
+};
+
+const createProject = (): Project => createInitialWorkbenchState().projects[0]!;
+
+const createQueueItem = (project: Project, overrides: Partial<QueueItem['snapshot']>): QueueItem => ({
+  cancellable: true,
+  id: 'local-1',
+  snapshot: {
+    canvas: project.canvas,
+    destination: 'canvas',
+    graph,
+    sourceId: 'canvas',
+    submittedAt: '2026-06-09T00:00:00.000Z',
+    widgetInstances: project.widgetInstances,
+    widgetStates: Object.fromEntries(
+      Object.values(project.widgetInstances).map((instance) => [instance.typeId, instance.state])
+    ),
+    ...overrides,
+  },
+  status: 'pending',
+});
+
+describe('createQueueItemBackendSubmission', () => {
+  it('submits canvas queue items through the generate batch path with resolved prompt and seed metadata', () => {
+    const project = createProject();
+    const values = createValues({
+      batchCount: 4,
+      negativePrompt: 'avoid blur',
+      positivePrompt: 'inpaint prompt',
+      seed: 987,
+    });
+    const queueItem = createQueueItem(project, {
+      generate: {
+        negativePromptNodeId: 'canvas_negative_prompt',
+        positivePromptNodeId: 'canvas_positive_prompt',
+        seedNodeId: 'canvas_seed',
+        values,
+      },
+      sourceId: 'canvas',
+    });
+
+    const submission = createQueueItemBackendSubmission(project, queueItem);
+
+    expect(submission).toEqual({
+      kind: 'generate',
+      request: {
+        batchCount: 4,
+        destination: 'canvas',
+        graph: graph.backendGraph,
+        negativePrompt: 'avoid blur',
+        negativePromptNodeId: 'canvas_negative_prompt',
+        positivePrompt: 'inpaint prompt',
+        positivePromptNodeId: 'canvas_positive_prompt',
+        projectId: project.id,
+        seed: 987,
+        seedNodeId: 'canvas_seed',
+        shouldRandomizeSeed: true,
+        sourceQueueItemId: 'local-1',
+      },
+    });
+  });
+
+  it('falls back to legacy canvas widget-state metadata when a persisted snapshot has no generate payload', () => {
+    const project = createProject();
+    const values = createValues({
+      batchCount: 2,
+      negativePrompt: 'legacy negative',
+      positivePrompt: 'legacy prompt',
+      seed: 321,
+      shouldRandomizeSeed: false,
+    });
+    const queueItem = createQueueItem(project, {
+      sourceId: 'canvas',
+      widgetStates: {
+        ...createQueueItem(project, {}).snapshot.widgetStates,
+        generate: { id: 'generate', label: 'Generate', values: { ...values } as Record<string, unknown>, version: 1 },
+      },
+    });
+
+    const submission = createQueueItemBackendSubmission(project, queueItem);
+
+    expect(submission).toEqual({
+      kind: 'generate',
+      request: {
+        batchCount: 2,
+        destination: 'canvas',
+        graph: graph.backendGraph,
+        negativePrompt: 'legacy negative',
+        negativePromptNodeId: 'negative_prompt',
+        positivePrompt: 'legacy prompt',
+        positivePromptNodeId: 'positive_prompt',
+        projectId: project.id,
+        seed: 321,
+        seedNodeId: 'seed',
+        shouldRandomizeSeed: false,
+        sourceQueueItemId: 'local-1',
+      },
+    });
+  });
+
+  it('keeps workflow queue items on the workflow path', () => {
+    const project = createProject();
+    const queueItem = createQueueItem(project, { destination: 'gallery', sourceId: 'workflow' });
+
+    const submission = createQueueItemBackendSubmission(project, queueItem);
+
+    expect(submission).toEqual({
+      kind: 'workflow',
+      request: {
+        batchCount: 1,
+        destination: 'gallery',
+        graph: graph.backendGraph,
+        projectId: project.id,
+        sourceQueueItemId: 'local-1',
+      },
+    });
+  });
+});
+
+describe('getQueueItemResultImageOptions', () => {
+  it('limits generated and canvas queue items to the compiled graph output node', () => {
+    const project = createProject();
+
+    expect(getQueueItemResultImageOptions(createQueueItem(project, { sourceId: 'generate' }))).toEqual({
+      resultNodeIds: ['canvas_output'],
+    });
+    expect(getQueueItemResultImageOptions(createQueueItem(project, { sourceId: 'canvas' }))).toEqual({
+      resultNodeIds: ['canvas_output'],
+    });
+  });
+
+  it('leaves workflow result nodes unconstrained', () => {
+    const project = createProject();
+
+    expect(getQueueItemResultImageOptions(createQueueItem(project, { sourceId: 'workflow' }))).toBeUndefined();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/WorkbenchRuntime.tsx b/invokeai/frontend/webv2/src/workbench/WorkbenchRuntime.tsx
new file mode 100644
index 00000000000..c5cd158854d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/WorkbenchRuntime.tsx
@@ -0,0 +1,568 @@
+import { useEffect, useRef, useState, type Dispatch } from 'react';
+
+import type { EnqueueGenerateRequest, EnqueueWorkflowRequest } from './generation/types';
+import type { Project, QueueItem } from './types';
+import type { WorkbenchAction } from './workbenchState';
+
+import { getConnectionStatus, subscribeConnection } from './backend/connectionStore';
+import { getApiErrorMessage } from './backend/http';
+import {
+  createQueueCoordinator,
+  QueueItemCancelledError,
+  type QueueCoordinator,
+  type ReconcileInput,
+} from './backend/queueCoordinator';
+import { socketHub } from './backend/socketHub';
+import { createCanvasDimsSync } from './canvasDimsSync';
+import { configureDiagnostics } from './diagnostics/logger';
+import { addImagesToGalleryBoard } from './gallery/api';
+import { getQueueItemResultImages, resumeQueueProcessor, type QueueItemResultImageOptions } from './generation/api';
+import { sanitizeBatchCount } from './generation/batch';
+import { normalizeGenerateSettings } from './generation/settings';
+import { shouldSubmitPendingQueueItem } from './queueSubmission';
+import { useWorkbenchPreferenceSelector } from './settings/store';
+import {
+  useWorkbenchDispatch,
+  useWorkbenchHasHydrated,
+  useWorkbenchSelector,
+  useWorkbenchStore,
+} from './WorkbenchContext';
+import { createStableSelector } from './workbenchSelectors';
+import { ensureInvocationTemplatesLoaded } from './workflows/templates';
+
+const getSnapshotGalleryBoardId = (queueItem: QueueItem): string | null => {
+  const selectedBoardId = queueItem.snapshot.widgetStates.gallery.values.selectedBoardId;
+
+  return typeof selectedBoardId === 'string' ? selectedBoardId : null;
+};
+
+const toErrorMessage = (error: unknown): string =>
+  getApiErrorMessage(error, error instanceof Error ? error.message : String(error));
+
+const getSnapshotBatchCount = (queueItem: QueueItem): number => {
+  const batchCount = queueItem.snapshot.widgetStates.generate?.values.batchCount;
+
+  return sanitizeBatchCount(batchCount);
+};
+
+type QueueItemBackendSubmission =
+  | { kind: 'generate'; request: EnqueueGenerateRequest }
+  | { kind: 'workflow'; request: EnqueueWorkflowRequest }
+  | { error: string; kind: 'invalid' };
+
+const COMPILED_GENERATE_RESULT_NODE_ID = 'canvas_output';
+
+export const getQueueItemResultImageOptions = (queueItem: QueueItem): QueueItemResultImageOptions | undefined => {
+  if (queueItem.snapshot.sourceId === 'generate' || queueItem.snapshot.sourceId === 'canvas') {
+    return { resultNodeIds: [COMPILED_GENERATE_RESULT_NODE_ID] };
+  }
+
+  return undefined;
+};
+
+export const createQueueItemBackendSubmission = (
+  project: Project,
+  queueItem: QueueItem
+): QueueItemBackendSubmission => {
+  const graph = queueItem.snapshot.graph.backendGraph;
+
+  if (!graph) {
+    return { error: `${queueItem.snapshot.sourceId} queue item is missing a compiled backend graph.`, kind: 'invalid' };
+  }
+
+  if (queueItem.snapshot.sourceId === 'generate') {
+    const generateValues = normalizeGenerateSettings(queueItem.snapshot.widgetStates.generate?.values);
+
+    if (!generateValues) {
+      return { error: 'generate queue item is missing generation settings.', kind: 'invalid' };
+    }
+
+    return {
+      kind: 'generate',
+      request: {
+        batchCount: generateValues.batchCount,
+        destination: queueItem.snapshot.destination,
+        graph,
+        negativePrompt: generateValues.negativePromptEnabled ? generateValues.negativePrompt : '',
+        negativePromptNodeId: 'negative_prompt',
+        positivePrompt: generateValues.positivePrompt,
+        positivePromptNodeId: 'positive_prompt',
+        projectId: project.id,
+        seed: generateValues.seed,
+        seedNodeId: 'seed',
+        shouldRandomizeSeed: generateValues.shouldRandomizeSeed,
+        sourceQueueItemId: queueItem.id,
+      },
+    };
+  }
+
+  if (queueItem.snapshot.sourceId === 'canvas') {
+    const generate = queueItem.snapshot.generate;
+    // Persisted canvas queue items from before `snapshot.generate` existed still
+    // carry the generate widget snapshot; use it rather than falling back to
+    // backend primitive defaults for prompt/seed.
+    const generateValues = normalizeGenerateSettings(
+      generate ? generate.values : queueItem.snapshot.widgetStates.generate?.values
+    );
+
+    if (!generateValues) {
+      return { error: 'canvas queue item is missing generation submission metadata.', kind: 'invalid' };
+    }
+
+    return {
+      kind: 'generate',
+      request: {
+        batchCount: generateValues.batchCount,
+        destination: queueItem.snapshot.destination,
+        graph,
+        negativePrompt: generateValues.negativePromptEnabled ? generateValues.negativePrompt : '',
+        negativePromptNodeId: generate?.negativePromptNodeId ?? 'negative_prompt',
+        positivePrompt: generateValues.positivePrompt,
+        positivePromptNodeId: generate?.positivePromptNodeId ?? 'positive_prompt',
+        projectId: project.id,
+        seed: generateValues.seed,
+        seedNodeId: generate?.seedNodeId ?? 'seed',
+        shouldRandomizeSeed: generateValues.shouldRandomizeSeed,
+        sourceQueueItemId: queueItem.id,
+      },
+    };
+  }
+
+  return {
+    kind: 'workflow',
+    request: {
+      batchCount: getSnapshotBatchCount(queueItem),
+      destination: queueItem.snapshot.destination,
+      graph,
+      projectId: project.id,
+      sourceQueueItemId: queueItem.id,
+    },
+  };
+};
+
+const selectQueueRevision = createStableSelector((snapshot: { state: { projects: Project[] } }) =>
+  snapshot.state.projects
+    .map((project) =>
+      [
+        project.id,
+        project.queue.items
+          .map((item) =>
+            [
+              item.id,
+              item.status,
+              item.backendBatchId ?? '',
+              item.backendItemIds?.join('.') ?? '',
+              item.cancelledBackendItemIds?.join('.') ?? '',
+              item.completedBackendItemIds?.join('.') ?? '',
+            ].join(':')
+          )
+          .join(','),
+      ].join('=')
+    )
+    .join('|')
+);
+
+/**
+ * Await a tracked run's terminal outcome, route its images to the queue item's
+ * destination, and reflect the outcome in workbench state.
+ */
+const routeRunResults = async (
+  coordinator: QueueCoordinator,
+  projectId: string,
+  queueItem: QueueItem,
+  dispatch: Dispatch<WorkbenchAction>
+): Promise<void> => {
+  try {
+    const allImages = await coordinator.waitForResults(
+      queueItem.id,
+      queueItem.snapshot.submittedAt,
+      getQueueItemResultImageOptions(queueItem)
+    );
+    // A workflow session reports every image its nodes produced; only the
+    // non-intermediate outputs are user-facing results.
+    const images =
+      queueItem.snapshot.sourceId === 'workflow' ? allImages.filter((image) => !image.isIntermediate) : allImages;
+
+    if (queueItem.snapshot.destination === 'gallery') {
+      const selectedBoardId = getSnapshotGalleryBoardId(queueItem);
+
+      if (selectedBoardId && selectedBoardId !== 'none') {
+        await addImagesToGalleryBoard(
+          selectedBoardId,
+          images.map((image) => image.imageName)
+        );
+      }
+    }
+
+    dispatch({ images, projectId, queueItemId: queueItem.id, type: 'routeQueueItemResults' });
+    if (queueItem.snapshot.destination === 'gallery') {
+      dispatch({ type: 'refreshBackendData' });
+    }
+  } catch (error) {
+    if (error instanceof QueueItemCancelledError) {
+      dispatch({ projectId, queueItemId: queueItem.id, status: 'cancelled', type: 'setQueueItemStatus' });
+      return;
+    }
+
+    dispatch({
+      error: toErrorMessage(error),
+      projectId,
+      queueItemId: queueItem.id,
+      status: 'failed',
+      type: 'setQueueItemStatus',
+    });
+  }
+};
+
+/** Route one completed backend item from a still-running local batch into its destination. */
+const routeBackendItemResults = async (
+  projectId: string,
+  queueItem: QueueItem,
+  backendItemId: number,
+  dispatch: Dispatch<WorkbenchAction>
+): Promise<void> => {
+  try {
+    const resultImageOptions = getQueueItemResultImageOptions(queueItem);
+    const allImages = resultImageOptions
+      ? await getQueueItemResultImages(backendItemId, queueItem.id, queueItem.snapshot.submittedAt, resultImageOptions)
+      : await getQueueItemResultImages(backendItemId, queueItem.id, queueItem.snapshot.submittedAt);
+    const images =
+      queueItem.snapshot.sourceId === 'workflow' ? allImages.filter((image) => !image.isIntermediate) : allImages;
+    if (queueItem.snapshot.destination === 'gallery') {
+      const selectedBoardId = getSnapshotGalleryBoardId(queueItem);
+
+      if (selectedBoardId && selectedBoardId !== 'none') {
+        await addImagesToGalleryBoard(
+          selectedBoardId,
+          images.map((image) => image.imageName)
+        );
+      }
+    }
+
+    dispatch({ backendItemId, images, projectId, queueItemId: queueItem.id, type: 'routeQueueItemPartialResults' });
+    if (queueItem.snapshot.destination === 'gallery') {
+      dispatch({ type: 'refreshBackendData' });
+    }
+  } catch (error) {
+    dispatch({
+      area: 'queue-results',
+      message: toErrorMessage(error),
+      namespace: 'queue',
+      projectId,
+      type: 'recordError',
+    });
+  }
+};
+
+const submitQueueItem = (
+  coordinator: QueueCoordinator,
+  project: Project,
+  queueItem: QueueItem,
+  dispatch: Dispatch<WorkbenchAction>
+): void => {
+  const backendSubmission = createQueueItemBackendSubmission(project, queueItem);
+
+  if (backendSubmission.kind === 'invalid') {
+    dispatch({
+      error: backendSubmission.error,
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      status: 'failed',
+      type: 'setQueueItemStatus',
+    });
+    return;
+  }
+
+  const submission =
+    backendSubmission.kind === 'generate'
+      ? coordinator.submitGenerate(queueItem.id, backendSubmission.request)
+      : coordinator.submitWorkflow(queueItem.id, backendSubmission.request);
+
+  submission
+    .then(({ batchId, itemIds }) => {
+      dispatch({
+        backendBatchId: batchId,
+        backendItemIds: itemIds,
+        projectId: project.id,
+        queueItemId: queueItem.id,
+        type: 'markQueueItemBackendSubmitted',
+      });
+
+      // Enqueuing implies intent to run: a paused processor would otherwise leave
+      // the batch stuck "waiting for progress" forever. Mirrors the legacy app's
+      // `anyEnqueued` listener; `resume` is a no-op when already running.
+      void resumeQueueProcessor().catch(() => undefined);
+
+      return routeRunResults(coordinator, project.id, queueItem, dispatch);
+    })
+    .catch((error: unknown) => {
+      dispatch({
+        error: toErrorMessage(error),
+        projectId: project.id,
+        queueItemId: queueItem.id,
+        status: 'failed',
+        type: 'setQueueItemStatus',
+      });
+    });
+};
+
+/**
+ * Bridges workbench state to the backend queue coordinator: it submits pending
+ * queue items, forwards cancellations, and reflects connection status, while
+ * the coordinator owns the socket and event-driven settlement. Mounted once
+ * inside the WorkbenchProvider; renders nothing.
+ */
+export const WorkbenchRuntime = () => {
+  const store = useWorkbenchStore();
+  const dispatch = useWorkbenchDispatch();
+  const hasHydrated = useWorkbenchHasHydrated();
+  const backendConnectionStatus = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status);
+  const diagnosticsPreferences = useWorkbenchPreferenceSelector((preferences) => ({
+    enabled: preferences.developerLogEnabled,
+    level: preferences.developerLogLevel,
+    namespaces: preferences.developerLogNamespaces,
+    performanceTimingsEnabled: preferences.developerPerformanceTimingsEnabled,
+  }));
+  const queueRevision = useWorkbenchSelector(selectQueueRevision);
+  const coordinatorRef = useRef<QueueCoordinator | null>(null);
+  const stateRef = useRef(store.getState());
+  const startedQueueItemIdsRef = useRef(new Set<string>());
+  const cancelledQueueItemIdsRef = useRef(new Set<string>());
+  const reconcileStateRef = useRef<'idle' | 'running' | 'done'>('idle');
+  const [isReconciled, setIsReconciled] = useState(false);
+
+  useEffect(
+    () =>
+      store.subscribe(() => {
+        stateRef.current = store.getState();
+      }),
+    [store]
+  );
+
+  // Keep the canvas generation frame and the generate-widget dimensions in sync
+  // while a project invokes into the canvas (the frame is the generation size).
+  // Lives beside the other store subscriptions; renders nothing.
+  useEffect(() => {
+    const sync = createCanvasDimsSync(store);
+
+    return () => sync.dispose();
+  }, [store]);
+
+  useEffect(() => {
+    configureDiagnostics(diagnosticsPreferences);
+  }, [diagnosticsPreferences]);
+
+  // Mirror the shared socket's connection status (owned by the hub, above the
+  // workbench) into workbench state so the editor's many `backendConnection`
+  // consumers and the reconcile gate keep working unchanged. Seeds on mount so
+  // opening the editor over an already-live socket reconciles immediately.
+  useEffect(() => {
+    const syncConnection = () => {
+      const { error, status } = getConnectionStatus();
+
+      dispatch({ error, status, type: 'setBackendConnectionStatus' });
+    };
+
+    syncConnection();
+
+    return subscribeConnection(syncConnection);
+  }, [dispatch]);
+
+  useEffect(() => {
+    const coordinator = createQueueCoordinator(
+      {
+        onBackendItemComplete: (localQueueItemId, backendItemId) => {
+          const routeTarget = stateRef.current.projects
+            .map((project) => ({
+              project,
+              queueItem: project.queue.items.find((item) => item.id === localQueueItemId),
+            }))
+            .find((target) => target.queueItem !== undefined);
+
+          if (!routeTarget?.queueItem || routeTarget.queueItem.completedBackendItemIds?.includes(backendItemId)) {
+            return;
+          }
+
+          return routeBackendItemResults(routeTarget.project.id, routeTarget.queueItem, backendItemId, dispatch);
+        },
+        onBackendItemCancelled: (localQueueItemId, backendItemId) => {
+          const routeTarget = stateRef.current.projects
+            .map((project) => ({
+              project,
+              queueItem: project.queue.items.find((item) => item.id === localQueueItemId),
+            }))
+            .find((target) => target.queueItem !== undefined);
+
+          if (!routeTarget?.queueItem || routeTarget.queueItem.cancelledBackendItemIds?.includes(backendItemId)) {
+            return;
+          }
+
+          dispatch({
+            backendItemId,
+            projectId: routeTarget.project.id,
+            queueItemId: localQueueItemId,
+            type: 'markQueueItemBackendCancelled',
+          });
+        },
+        onGalleryRefresh: () => {
+          dispatch({ type: 'refreshBackendData' });
+        },
+      },
+      { hub: socketHub }
+    );
+
+    coordinatorRef.current = coordinator;
+    coordinator.connect();
+    // Node definitions back workflow route validation, which can be the
+    // persisted invocation source before any workflow surface has mounted.
+    ensureInvocationTemplatesLoaded();
+
+    return () => {
+      coordinatorRef.current = null;
+      coordinator.dispose();
+    };
+  }, [dispatch]);
+
+  // Reconcile persisted queue items against the live backend queue exactly
+  // once, after hydration and first connect. Until this finishes, submission
+  // is held back so an item the backend already accepted is not enqueued twice.
+  useEffect(() => {
+    const coordinator = coordinatorRef.current;
+
+    if (
+      !coordinator ||
+      !hasHydrated ||
+      backendConnectionStatus !== 'connected' ||
+      reconcileStateRef.current !== 'idle'
+    ) {
+      return;
+    }
+
+    reconcileStateRef.current = 'running';
+
+    const openItems = stateRef.current.projects.flatMap((project) =>
+      project.queue.items
+        .filter((queueItem) => queueItem.status === 'pending' || queueItem.status === 'running')
+        .map((queueItem) => ({ project, queueItem }))
+    );
+
+    for (const { queueItem } of openItems) {
+      startedQueueItemIdsRef.current.add(queueItem.id);
+    }
+
+    const inputs: ReconcileInput[] = openItems.map(({ queueItem }) => ({
+      backendBatchId: queueItem.backendBatchId,
+      backendItemIds: queueItem.backendItemIds,
+      id: queueItem.id,
+      status: queueItem.status === 'running' ? 'running' : 'pending',
+    }));
+
+    coordinator
+      .reconcile(inputs)
+      .then((outcomes) => {
+        for (const { project, queueItem } of openItems) {
+          const outcome = outcomes.get(queueItem.id);
+
+          switch (outcome?.kind) {
+            case 'enqueue': {
+              startedQueueItemIdsRef.current.delete(queueItem.id);
+              break;
+            }
+            case 'adopted': {
+              dispatch({
+                backendBatchId: outcome.backendBatchId,
+                backendItemIds: outcome.backendItemIds,
+                projectId: project.id,
+                queueItemId: queueItem.id,
+                type: 'markQueueItemBackendSubmitted',
+              });
+              void routeRunResults(coordinator, project.id, queueItem, dispatch);
+              break;
+            }
+            case 'resumed': {
+              void routeRunResults(coordinator, project.id, queueItem, dispatch);
+              break;
+            }
+            case 'missing': {
+              dispatch({
+                error: 'This run is no longer on the backend queue (it may have been cleared).',
+                notify: false,
+                projectId: project.id,
+                queueItemId: queueItem.id,
+                status: 'failed',
+                type: 'setQueueItemStatus',
+              });
+              break;
+            }
+          }
+        }
+      })
+      .catch((error: unknown) => {
+        // Release pending items to the normal submission path; running items
+        // cannot be re-attached without backend state, so fail them visibly
+        // rather than leaving them stuck as running forever.
+        dispatch({
+          area: 'queue-reconciliation',
+          message: `Queue reconciliation failed: ${toErrorMessage(error)}`,
+          namespace: 'queue',
+          type: 'recordError',
+        });
+
+        for (const { project, queueItem } of openItems) {
+          if (queueItem.status === 'pending') {
+            startedQueueItemIdsRef.current.delete(queueItem.id);
+            continue;
+          }
+
+          dispatch({
+            error: 'Could not reconcile this run with the backend queue after reload.',
+            projectId: project.id,
+            queueItemId: queueItem.id,
+            status: 'failed',
+            type: 'setQueueItemStatus',
+          });
+        }
+      })
+      .finally(() => {
+        reconcileStateRef.current = 'done';
+        setIsReconciled(true);
+      });
+  }, [backendConnectionStatus, dispatch, hasHydrated, queueRevision]);
+
+  useEffect(() => {
+    const coordinator = coordinatorRef.current;
+
+    if (!coordinator || !isReconciled) {
+      return;
+    }
+
+    for (const project of stateRef.current.projects) {
+      for (const queueItem of project.queue.items) {
+        if (shouldSubmitPendingQueueItem(queueItem) && !startedQueueItemIdsRef.current.has(queueItem.id)) {
+          startedQueueItemIdsRef.current.add(queueItem.id);
+          submitQueueItem(coordinator, project, queueItem, dispatch);
+        }
+
+        if (
+          queueItem.status === 'cancelled' &&
+          (queueItem.backendBatchId || queueItem.backendItemIds?.length) &&
+          !cancelledQueueItemIdsRef.current.has(queueItem.id)
+        ) {
+          cancelledQueueItemIdsRef.current.add(queueItem.id);
+          coordinator
+            .cancelRun({ backendBatchId: queueItem.backendBatchId, backendItemIds: queueItem.backendItemIds })
+            .catch((error: unknown) => {
+              dispatch({
+                area: 'queue-cancel',
+                message: toErrorMessage(error),
+                namespace: 'queue',
+                type: 'recordError',
+              });
+            });
+        }
+      }
+    }
+  }, [dispatch, isReconciled, queueRevision]);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/WorkbenchSessionController.tsx b/invokeai/frontend/webv2/src/workbench/WorkbenchSessionController.tsx
new file mode 100644
index 00000000000..ded91294fd7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/WorkbenchSessionController.tsx
@@ -0,0 +1,91 @@
+import { useNavigate } from '@tanstack/react-router';
+import { useEffect, useRef } from 'react';
+
+import type { WorkbenchSearch } from './projects/session';
+
+import { hydrateProjectFromServer } from './projects/syncedPersistence';
+import { flushGenerateDrafts } from './widgets/generate/generateDraftRegistry';
+import { useWorkbenchDispatch, useWorkbenchHasHydrated, useWorkbenchSelector } from './WorkbenchContext';
+import { areArraysEqual } from './workbenchSelectors';
+
+/**
+ * Keeps a mounted editor in line with the /app search params. Renders nothing.
+ *
+ * Boot is not its job — `WorkbenchProvider` consumes the params present at
+ * mount as load options. This covers what happens afterwards:
+ *
+ * - `?new` is stripped once hydration has consumed it, so a reload (or a
+ *   bookmark) does not mint another draft project.
+ * - `?project` changing while the editor is open (a deep link clicked from
+ *   elsewhere) focuses the tab if it is open, or hydrates it from the
+ *   library and opens it if not.
+ */
+export const WorkbenchSessionController = ({ search }: { search: WorkbenchSearch }) => {
+  const projectIds = useWorkbenchSelector(
+    (snapshot) => snapshot.state.projects.map((project) => project.id),
+    areArraysEqual
+  );
+  const dispatch = useWorkbenchDispatch();
+  const hasHydrated = useWorkbenchHasHydrated();
+  const navigate = useNavigate();
+  const latestProjectIdsRef = useRef(projectIds);
+  // The mount-time param was already handled by the boot load options.
+  const handledProjectIdRef = useRef<string | null>(search.project ?? null);
+
+  useEffect(() => {
+    latestProjectIdsRef.current = projectIds;
+  }, [projectIds]);
+
+  const isNewRequested = search.new === true;
+
+  useEffect(() => {
+    if (!hasHydrated || !isNewRequested) {
+      return;
+    }
+
+    void navigate({ replace: true, search: {}, to: '/app' });
+  }, [hasHydrated, isNewRequested, navigate]);
+
+  const requestedProjectId = search.project;
+
+  useEffect(() => {
+    if (!hasHydrated || !requestedProjectId || handledProjectIdRef.current === requestedProjectId) {
+      return undefined;
+    }
+
+    handledProjectIdRef.current = requestedProjectId;
+
+    if (latestProjectIdsRef.current.includes(requestedProjectId)) {
+      flushGenerateDrafts();
+      dispatch({ projectId: requestedProjectId, type: 'switchProject' });
+
+      return undefined;
+    }
+
+    let isCancelled = false;
+
+    void hydrateProjectFromServer(requestedProjectId).then((project) => {
+      if (isCancelled) {
+        return;
+      }
+
+      if (project) {
+        flushGenerateDrafts();
+        dispatch({ project, type: 'openProject' });
+      } else {
+        dispatch({
+          kind: 'info',
+          message: 'The linked project does not exist on this account — it may have been deleted.',
+          title: 'Project not found',
+          type: 'recordNotice',
+        });
+      }
+    });
+
+    return () => {
+      isCancelled = true;
+    };
+  }, [dispatch, hasHydrated, requestedProjectId]);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/WorkbenchWidgetRegistryContext.tsx b/invokeai/frontend/webv2/src/workbench/WorkbenchWidgetRegistryContext.tsx
new file mode 100644
index 00000000000..bd61387b53d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/WorkbenchWidgetRegistryContext.tsx
@@ -0,0 +1,40 @@
+import { createContext, use, useMemo, type ReactNode } from 'react';
+
+import type { RegisteredWidget, WidgetRegion, WidgetTypeId } from './types';
+
+interface WorkbenchWidgetRegistryContextValue {
+  getWidgetById: (widgetId: WidgetTypeId) => RegisteredWidget | undefined;
+  getWidgetsForRegion: (region: WidgetRegion) => RegisteredWidget[];
+}
+
+const WorkbenchWidgetRegistryContext = createContext<WorkbenchWidgetRegistryContextValue | null>(null);
+
+export const WorkbenchWidgetRegistryProvider = ({
+  children,
+  getWidgetById,
+  getWidgetsForRegion,
+}: {
+  children: ReactNode;
+  getWidgetById: (widgetId: WidgetTypeId) => RegisteredWidget | undefined;
+  getWidgetsForRegion: (region: WidgetRegion) => RegisteredWidget[];
+}) => {
+  const value = useMemo<WorkbenchWidgetRegistryContextValue>(
+    () => ({ getWidgetById, getWidgetsForRegion }),
+    [getWidgetById, getWidgetsForRegion]
+  );
+
+  return <WorkbenchWidgetRegistryContext value={value}>{children}</WorkbenchWidgetRegistryContext>;
+};
+
+export const useWorkbenchWidgetRegistry = (): WorkbenchWidgetRegistryContextValue => {
+  const context = use(WorkbenchWidgetRegistryContext);
+
+  if (!context) {
+    throw new Error('useWorkbenchWidgetRegistry must be used within a WorkbenchWidgetRegistryProvider.');
+  }
+
+  return context;
+};
+
+export const useOptionalWorkbenchWidgetRegistry = (): WorkbenchWidgetRegistryContextValue | null =>
+  use(WorkbenchWidgetRegistryContext);
diff --git a/invokeai/frontend/webv2/src/workbench/auth/api.ts b/invokeai/frontend/webv2/src/workbench/auth/api.ts
new file mode 100644
index 00000000000..b521e1489df
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/api.ts
@@ -0,0 +1,105 @@
+import { apiFetch, apiFetchJson } from '@workbench/backend/http';
+
+/**
+ * REST surface for the backend's multi-user endpoints (`/api/v1/auth`). Field
+ * names mirror the backend DTOs verbatim; the session store and components own
+ * any reshaping.
+ */
+
+const AUTH_BASE = '/api/v1/auth';
+
+export interface UserDTO {
+  user_id: string;
+  email: string;
+  display_name: string | null;
+  is_admin: boolean;
+  is_active: boolean;
+  created_at: string;
+  updated_at: string;
+  last_login_at: string | null;
+}
+
+export interface AuthStatus {
+  setup_required: boolean;
+  multiuser_enabled: boolean;
+  strict_password_checking: boolean;
+  admin_email: string | null;
+}
+
+export interface LoginRequest {
+  email: string;
+  password: string;
+  remember_me: boolean;
+}
+
+export interface LoginResult {
+  token: string;
+  user: UserDTO;
+  expires_in: number;
+}
+
+export interface SetupRequest {
+  email: string;
+  display_name: string | null;
+  password: string;
+}
+
+export interface ProfileUpdateRequest {
+  display_name?: string;
+  current_password?: string;
+  new_password?: string;
+}
+
+export interface UserCreateRequest {
+  email: string;
+  display_name: string | null;
+  password: string;
+  is_admin: boolean;
+}
+
+export interface UserUpdateRequest {
+  display_name?: string;
+  password?: string;
+  is_admin?: boolean;
+  is_active?: boolean;
+}
+
+export const getAuthStatus = (): Promise<AuthStatus> => apiFetchJson<AuthStatus>(`${AUTH_BASE}/status`);
+
+export const login = (request: LoginRequest): Promise<LoginResult> =>
+  apiFetchJson<LoginResult>(`${AUTH_BASE}/login`, { body: JSON.stringify(request), method: 'POST' });
+
+export const logout = (): Promise<{ success: boolean }> =>
+  apiFetchJson<{ success: boolean }>(`${AUTH_BASE}/logout`, { method: 'POST' });
+
+export const getCurrentUser = (): Promise<UserDTO> => apiFetchJson<UserDTO>(`${AUTH_BASE}/me`);
+
+export const setupAdmin = (request: SetupRequest): Promise<{ success: boolean; user: UserDTO }> =>
+  apiFetchJson<{ success: boolean; user: UserDTO }>(`${AUTH_BASE}/setup`, {
+    body: JSON.stringify(request),
+    method: 'POST',
+  });
+
+export const updateCurrentUser = (request: ProfileUpdateRequest): Promise<UserDTO> =>
+  apiFetchJson<UserDTO>(`${AUTH_BASE}/me`, { body: JSON.stringify(request), method: 'PATCH' });
+
+export const listUsers = (): Promise<UserDTO[]> => apiFetchJson<UserDTO[]>(`${AUTH_BASE}/users`);
+
+export const createUser = (request: UserCreateRequest): Promise<UserDTO> =>
+  apiFetchJson<UserDTO>(`${AUTH_BASE}/users`, { body: JSON.stringify(request), method: 'POST' });
+
+export const updateUser = (userId: string, changes: UserUpdateRequest): Promise<UserDTO> =>
+  apiFetchJson<UserDTO>(`${AUTH_BASE}/users/${encodeURIComponent(userId)}`, {
+    body: JSON.stringify(changes),
+    method: 'PATCH',
+  });
+
+export const deleteUser = async (userId: string): Promise<void> => {
+  await apiFetch(`${AUTH_BASE}/users/${encodeURIComponent(userId)}`, { method: 'DELETE' });
+};
+
+export const generatePassword = async (): Promise<string> => {
+  const body = await apiFetchJson<{ password: string }>(`${AUTH_BASE}/generate-password`);
+
+  return body.password;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/auth/capabilities.ts b/invokeai/frontend/webv2/src/workbench/auth/capabilities.ts
new file mode 100644
index 00000000000..92c61cfd257
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/capabilities.ts
@@ -0,0 +1,20 @@
+import { useAuthSession, type AuthSession } from './session';
+
+export interface Capabilities {
+  canManageModels: boolean;
+  canManageNodes: boolean;
+  canManageUsers: boolean;
+}
+
+export const getCapabilities = (session: AuthSession): Capabilities => {
+  const isSingleUser = !session.multiuserEnabled;
+  const isAdmin = isSingleUser || session.user?.is_admin === true;
+
+  return {
+    canManageModels: isAdmin,
+    canManageNodes: isAdmin,
+    canManageUsers: session.multiuserEnabled && session.user?.is_admin === true,
+  };
+};
+
+export const useCapabilities = (): Capabilities => getCapabilities(useAuthSession());
diff --git a/invokeai/frontend/webv2/src/workbench/auth/components/AccountMenu.tsx b/invokeai/frontend/webv2/src/workbench/auth/components/AccountMenu.tsx
new file mode 100644
index 00000000000..4145911c710
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/components/AccountMenu.tsx
@@ -0,0 +1,115 @@
+import { Avatar, Badge, Box, chakra, HStack, Icon, Menu, Portal, Stack, Text } from '@chakra-ui/react';
+import { useNavigate } from '@tanstack/react-router';
+import { logoutSession, useAuthSession } from '@workbench/auth/session';
+import { MenuContent } from '@workbench/components/ui';
+import { ChevronDownIcon, LogOutIcon, UserRoundCogIcon, UsersIcon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { ProfileDialog } from './ProfileDialog';
+
+const MENU_POSITIONING = { placement: 'bottom-end' } as const;
+const TRIGGER_HOVER = { bg: 'bg.subtle' } as const;
+
+/**
+ * The signed-in user's avatar menu — account settings, user management, and
+ * sign-out — shown on both the Launchpad and the workbench shell. Renders only
+ * in a multi-user session; the settings gear is a separate control that each
+ * surface's top bar places alongside it.
+ */
+export const AccountMenu = () => {
+  const { t } = useTranslation();
+  const session = useAuthSession();
+  const navigate = useNavigate();
+  const [isProfileOpen, setIsProfileOpen] = useState(false);
+
+  // User management is a Launchpad page (`/users`), not a workbench widget —
+  // so this navigates there, working the same from Home and the editor.
+  const openUserManagement = useCallback(() => {
+    void navigate({ to: '/users' });
+  }, [navigate]);
+
+  const signOut = useCallback(async () => {
+    await logoutSession();
+    await navigate({ to: '/login' });
+  }, [navigate]);
+
+  const openProfile = useCallback(() => setIsProfileOpen(true), []);
+  const closeProfile = useCallback(() => setIsProfileOpen(false), []);
+
+  if (!session.multiuserEnabled || session.user === null) {
+    return;
+  }
+
+  const user = session.user;
+  const label = user.display_name?.trim() || user.email;
+
+  return (
+    <>
+      <Menu.Root positioning={MENU_POSITIONING}>
+        <Menu.Trigger asChild>
+          <chakra.button
+            alignItems="center"
+            color="fg"
+            display="flex"
+            flexShrink={0}
+            gap="1.5"
+            px="1.5"
+            py="1"
+            rounded="md"
+            type="button"
+            _hover={TRIGGER_HOVER}
+          >
+            <Avatar.Root bg="accent.subtle" color="fg" size="2xs">
+              <Avatar.Fallback fontSize="2xs" name={label} />
+            </Avatar.Root>
+            <Text fontSize="xs" fontWeight="600">
+              {label}
+            </Text>
+            <Icon as={ChevronDownIcon} boxSize="3" color="fg.muted" />
+          </chakra.button>
+        </Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent minW="56">
+              <Box px="3" py="2">
+                <HStack justify="space-between">
+                  <Stack gap="0">
+                    <Text fontSize="xs" fontWeight="600">
+                      {label}
+                    </Text>
+                    <Text color="fg.muted" fontSize="2xs">
+                      {user.email}
+                    </Text>
+                  </Stack>
+                  {user.is_admin ? (
+                    <Badge colorPalette="purple" fontSize="2xs" variant="surface">
+                      {t('users.admin')}
+                    </Badge>
+                  ) : null}
+                </HStack>
+              </Box>
+              <Menu.Separator />
+              <Menu.Item value="account" onClick={openProfile}>
+                <Icon as={UserRoundCogIcon} boxSize="3.5" />
+                {t('auth.accountSettings')}
+              </Menu.Item>
+              {user.is_admin ? (
+                <Menu.Item value="users" onClick={openUserManagement}>
+                  <Icon as={UsersIcon} boxSize="3.5" />
+                  {t('users.manageUsers')}
+                </Menu.Item>
+              ) : null}
+              <Menu.Separator />
+              <Menu.Item value="sign-out" onClick={signOut}>
+                <Icon as={LogOutIcon} boxSize="3.5" />
+                {t('auth.signOut')}
+              </Menu.Item>
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <ProfileDialog isOpen={isProfileOpen} user={user} onClose={closeProfile} />
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/auth/components/AuthScreen.tsx b/invokeai/frontend/webv2/src/workbench/auth/components/AuthScreen.tsx
new file mode 100644
index 00000000000..6ff8eaabb8a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/components/AuthScreen.tsx
@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+
+import { Alert, Flex, Heading, Stack, Text } from '@chakra-ui/react';
+import { InvokeMark } from '@workbench/components/InvokeMark';
+
+/**
+ * Centered scaffold shared by the login and first-run setup screens. These
+ * render outside the workbench shell (and its providers), so they rely only on
+ * semantic tokens.
+ */
+export const AuthScreen = ({
+  children,
+  footer,
+  subtitle,
+  title,
+}: {
+  children: ReactNode;
+  footer?: ReactNode;
+  subtitle: string;
+  title: string;
+}) => (
+  <Flex align="center" bg="bg" color="fg" justify="center" minH="100dvh" p="6">
+    <Stack gap="6" maxW="sm" w="full">
+      <Stack align="center" gap="4">
+        <InvokeMark />
+        <Stack align="center" gap="1">
+          <Heading fontSize="lg" fontWeight="700">
+            {title}
+          </Heading>
+          <Text color="fg.muted" fontSize="sm" textAlign="center">
+            {subtitle}
+          </Text>
+        </Stack>
+      </Stack>
+      <Stack bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" gap="4" p="6" rounded="xl" shadow="lg">
+        {children}
+      </Stack>
+      {footer ? (
+        <Text color="fg.subtle" fontSize="xs" textAlign="center">
+          {footer}
+        </Text>
+      ) : null}
+    </Stack>
+  </Flex>
+);
+
+/** Inline alert used for form-level failures on the auth screens. */
+export const AuthFormAlert = ({ message, tone }: { message: string; tone: 'error' | 'warning' }) => (
+  <Alert.Root borderRadius="md" size="sm" status={tone}>
+    <Alert.Indicator />
+    <Alert.Title fontSize="xs">{message}</Alert.Title>
+  </Alert.Root>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/auth/components/LoginScreen.tsx b/invokeai/frontend/webv2/src/workbench/auth/components/LoginScreen.tsx
new file mode 100644
index 00000000000..0201cd4ab04
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/components/LoginScreen.tsx
@@ -0,0 +1,95 @@
+import { chakra, Checkbox, Input } from '@chakra-ui/react';
+import { useNavigate } from '@tanstack/react-router';
+import { loginSchema } from '@workbench/auth/schemas';
+import { loginWithCredentials, useAuthSession } from '@workbench/auth/session';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, Field } from '@workbench/components/ui';
+import { useZodForm } from '@workbench/models/useZodForm';
+import { useCallback, type ChangeEvent, type FormEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { AuthFormAlert, AuthScreen } from './AuthScreen';
+import { PasswordInput } from './PasswordInput';
+
+/** Sign-in screen, shown only when the backend runs in multi-user mode. */
+export const LoginScreen = () => {
+  const { t } = useTranslation();
+  const session = useAuthSession();
+  const navigate = useNavigate();
+  const form = useZodForm(loginSchema, { email: '', password: '', rememberMe: false });
+
+  const submit = useCallback(
+    () =>
+      form.handleSubmit(async (values) => {
+        try {
+          await loginWithCredentials(values.email, values.password, values.rememberMe);
+        } catch (error) {
+          throw new Error(getApiErrorMessage(error, t('auth.signInFailed')));
+        }
+
+        await navigate({ to: '/' });
+      }),
+    [form, navigate, t]
+  );
+
+  const handleSubmit = useCallback(
+    (event: FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      void submit();
+    },
+    [submit]
+  );
+
+  const handleEmailChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('email', event.target.value),
+    [form]
+  );
+
+  const handlePasswordChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('password', event.target.value),
+    [form]
+  );
+
+  const handleRememberMeChange = useCallback(
+    (event: Checkbox.CheckedChangeDetails) => form.setValue('rememberMe', event.checked === true),
+    [form]
+  );
+
+  return (
+    <AuthScreen subtitle={t('auth.signInSubtitle')} title={t('auth.welcomeTitle')}>
+      <chakra.form display="flex" flexDirection="column" gap="4" onSubmit={handleSubmit}>
+        {session.sessionExpired ? <AuthFormAlert message={t('auth.sessionExpired')} tone="warning" /> : null}
+        {form.formError ? <AuthFormAlert message={form.formError} tone="error" /> : null}
+        <Field error={form.errors.email} label={t('users.email')}>
+          <Input
+            aria-invalid={form.errors.email ? true : undefined}
+            autoComplete="email"
+            autoFocus
+            placeholder="you@example.com"
+            value={form.values.email}
+            onChange={handleEmailChange}
+          />
+        </Field>
+        <Field error={form.errors.password} label={t('auth.password')}>
+          <PasswordInput
+            aria-invalid={form.errors.password ? true : undefined}
+            autoComplete="current-password"
+            placeholder={t('auth.yourPassword')}
+            value={form.values.password}
+            onChange={handlePasswordChange}
+          />
+        </Field>
+        <Checkbox.Root checked={form.values.rememberMe} size="sm" onCheckedChange={handleRememberMeChange}>
+          <Checkbox.HiddenInput />
+          <Checkbox.Control />
+          <Checkbox.Label color="fg.muted" fontWeight="400">
+            {t('auth.keepSignedIn')}
+          </Checkbox.Label>
+        </Checkbox.Root>
+        <Button loading={form.isSubmitting} size="sm" type="submit" variant="solid">
+          {t('auth.signIn')}
+        </Button>
+      </chakra.form>
+    </AuthScreen>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/auth/components/PasswordInput.tsx b/invokeai/frontend/webv2/src/workbench/auth/components/PasswordInput.tsx
new file mode 100644
index 00000000000..3dafe2e8b62
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/components/PasswordInput.tsx
@@ -0,0 +1,71 @@
+import { Box, HStack, Input, InputGroup, Text } from '@chakra-ui/react';
+import { getPasswordStrength, type PasswordStrength } from '@workbench/auth/schemas';
+import { IconButton } from '@workbench/components/ui';
+import { EyeIcon, EyeOffIcon } from 'lucide-react';
+import { useCallback, useMemo, useState, type ComponentProps } from 'react';
+import { useTranslation } from 'react-i18next';
+
+type InputProps = ComponentProps<typeof Input>;
+
+/** Password input with an inline visibility toggle. */
+export const PasswordInput = (props: InputProps) => {
+  const { t } = useTranslation();
+  const [isVisible, setIsVisible] = useState(false);
+  const handleToggleVisibility = useCallback(() => setIsVisible((current) => !current), []);
+  const endElement = useMemo(
+    () => (
+      <IconButton
+        aria-label={isVisible ? t('auth.hidePassword') : t('auth.showPassword')}
+        color="fg.muted"
+        size="2xs"
+        variant="ghost"
+        onClick={handleToggleVisibility}
+      >
+        {isVisible ? <EyeOffIcon /> : <EyeIcon />}
+      </IconButton>
+    ),
+    [handleToggleVisibility, isVisible, t]
+  );
+
+  return (
+    <InputGroup endElement={endElement}>
+      <Input type={isVisible ? 'text' : 'password'} {...props} />
+    </InputGroup>
+  );
+};
+
+const STRENGTH_META: Record<PasswordStrength, { filledSegments: number; labelKey: string; tone: string }> = {
+  moderate: { filledSegments: 2, labelKey: 'auth.passwordStrength.moderate', tone: 'fg.warning' },
+  strong: { filledSegments: 3, labelKey: 'auth.passwordStrength.strong', tone: 'fg.success' },
+  weak: { filledSegments: 1, labelKey: 'auth.passwordStrength.weak', tone: 'fg.error' },
+};
+
+/** Three-segment strength readout; renders nothing until the user types. */
+export const PasswordStrengthMeter = ({ password }: { password: string }) => {
+  const { t } = useTranslation();
+
+  if (!password) {
+    return null;
+  }
+
+  const meta = STRENGTH_META[getPasswordStrength(password)];
+
+  return (
+    <HStack gap="2">
+      <HStack flex="1" gap="1">
+        {[0, 1, 2].map((segment) => (
+          <Box
+            key={segment}
+            bg={segment < meta.filledSegments ? meta.tone : 'border.subtle'}
+            flex="1"
+            h="1"
+            rounded="full"
+          />
+        ))}
+      </HStack>
+      <Text color={meta.tone} fontSize="2xs" fontWeight="600">
+        {t(meta.labelKey)}
+      </Text>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/auth/components/ProfileDialog.tsx b/invokeai/frontend/webv2/src/workbench/auth/components/ProfileDialog.tsx
new file mode 100644
index 00000000000..6072075dae3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/components/ProfileDialog.tsx
@@ -0,0 +1,208 @@
+import { Dialog, HStack, Input, Portal, Stack, Text } from '@chakra-ui/react';
+import { generatePassword, updateCurrentUser, type ProfileUpdateRequest, type UserDTO } from '@workbench/auth/api';
+import { createProfileSchema, PASSWORD_RULES_HINT, type ProfileFormValues } from '@workbench/auth/schemas';
+import { setSessionUser, useAuthSession } from '@workbench/auth/session';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, CloseButton, Field, FieldLabel } from '@workbench/components/ui';
+import { useZodForm } from '@workbench/models/useZodForm';
+import { useNotify } from '@workbench/useNotify';
+import { WandSparklesIcon } from 'lucide-react';
+import { useCallback, useMemo, useState, type ChangeEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { AuthFormAlert } from './AuthScreen';
+import { PasswordInput, PasswordStrengthMeter } from './PasswordInput';
+
+/** Account settings: display name and password change for the signed-in user. */
+export const ProfileDialog = ({ isOpen, onClose, user }: { isOpen: boolean; onClose: () => void; user: UserDTO }) => {
+  const { t } = useTranslation();
+  const handleOpenChange = useCallback(
+    (event: Dialog.OpenChangeDetails) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  return (
+    <Dialog.Root
+      lazyMount
+      open={isOpen}
+      placement="center"
+      scrollBehavior="inside"
+      size="sm"
+      unmountOnExit
+      onOpenChange={handleOpenChange}
+    >
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Header borderBottomWidth="1px" borderColor="border.subtle">
+              <Stack gap="0.5">
+                <Dialog.Title fontSize="md" fontWeight="700">
+                  {t('auth.account')}
+                </Dialog.Title>
+                <Text color="fg.subtle" fontSize="xs">
+                  {t('auth.signedInAs', { email: user.email })}
+                </Text>
+              </Stack>
+            </Dialog.Header>
+            <ProfileForm user={user} onClose={onClose} />
+            <Dialog.CloseTrigger asChild>
+              <CloseButton color="fg.muted" size="sm" />
+            </Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
+
+const ProfileForm = ({ onClose, user }: { onClose: () => void; user: UserDTO }) => {
+  const { t } = useTranslation();
+  const session = useAuthSession();
+  const notify = useNotify();
+  const [isGenerating, setIsGenerating] = useState(false);
+  const schema = useMemo(() => createProfileSchema(session.strictPasswordChecking), [session.strictPasswordChecking]);
+  const initialValues: ProfileFormValues = useMemo(
+    () => ({ confirmPassword: '', currentPassword: '', displayName: user.display_name ?? '', newPassword: '' }),
+    [user.display_name]
+  );
+  const form = useZodForm(schema, initialValues);
+
+  const fillGeneratedPassword = useCallback(async () => {
+    setIsGenerating(true);
+
+    try {
+      const password = await generatePassword();
+
+      form.setValue('newPassword', password);
+      form.setValue('confirmPassword', password);
+      notify.info(t('users.passwordGenerated'), t('auth.passwordGeneratedDescription'));
+    } catch (error) {
+      notify.error(t('users.couldNotGeneratePassword'), getApiErrorMessage(error, t('users.backendRejectedRequest')));
+    } finally {
+      setIsGenerating(false);
+    }
+  }, [form, notify, t]);
+
+  const submit = useCallback(
+    () =>
+      form.handleSubmit(async (values) => {
+        const changes: ProfileUpdateRequest = {};
+        const displayName = values.displayName.trim();
+
+        if (displayName !== (user.display_name ?? '')) {
+          changes.display_name = displayName;
+        }
+
+        if (values.newPassword !== '') {
+          changes.current_password = values.currentPassword;
+          changes.new_password = values.newPassword;
+        }
+
+        if (Object.keys(changes).length === 0) {
+          onClose();
+          return;
+        }
+
+        try {
+          const updated = await updateCurrentUser(changes);
+
+          setSessionUser(updated);
+        } catch (error) {
+          throw new Error(getApiErrorMessage(error, t('auth.couldNotUpdateAccount')));
+        }
+
+        notify.success(t('auth.accountUpdated'));
+        onClose();
+      }),
+    [form, notify, onClose, t, user.display_name]
+  );
+  const handleDisplayNameChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('displayName', event.target.value),
+    [form]
+  );
+  const handleCurrentPasswordChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('currentPassword', event.target.value),
+    [form]
+  );
+  const handleNewPasswordChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('newPassword', event.target.value),
+    [form]
+  );
+  const handleConfirmPasswordChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('confirmPassword', event.target.value),
+    [form]
+  );
+  const handleGeneratePassword = useCallback(() => void fillGeneratedPassword(), [fillGeneratedPassword]);
+  const handleSave = useCallback(() => void submit(), [submit]);
+
+  return (
+    <>
+      <Dialog.Body>
+        <Stack gap="5" py="2">
+          {form.formError ? <AuthFormAlert message={form.formError} tone="error" /> : null}
+          <Field helpText={t('auth.profileDisplayNameHelp')} label={t('users.displayName')}>
+            <Input
+              autoComplete="name"
+              placeholder={user.email}
+              value={form.values.displayName}
+              onChange={handleDisplayNameChange}
+            />
+          </Field>
+          <Stack gap="3">
+            <HStack justify="space-between">
+              <FieldLabel>{t('auth.changePassword')}</FieldLabel>
+              <Button loading={isGenerating} size="2xs" variant="outline" onClick={handleGeneratePassword}>
+                <WandSparklesIcon />
+                {t('users.generate')}
+              </Button>
+            </HStack>
+            <Field error={form.errors.currentPassword} label={t('auth.currentPassword')}>
+              <PasswordInput
+                aria-invalid={form.errors.currentPassword ? true : undefined}
+                autoComplete="current-password"
+                value={form.values.currentPassword}
+                onChange={handleCurrentPasswordChange}
+              />
+            </Field>
+            <Field
+              error={form.errors.newPassword}
+              helpText={session.strictPasswordChecking ? PASSWORD_RULES_HINT : t('auth.leaveBlankKeepPassword')}
+              label={t('users.newPassword')}
+            >
+              <Stack gap="1.5">
+                <PasswordInput
+                  aria-invalid={form.errors.newPassword ? true : undefined}
+                  autoComplete="new-password"
+                  value={form.values.newPassword}
+                  onChange={handleNewPasswordChange}
+                />
+                <PasswordStrengthMeter password={form.values.newPassword} />
+              </Stack>
+            </Field>
+            <Field error={form.errors.confirmPassword} label={t('auth.confirmNewPassword')}>
+              <PasswordInput
+                aria-invalid={form.errors.confirmPassword ? true : undefined}
+                autoComplete="new-password"
+                value={form.values.confirmPassword}
+                onChange={handleConfirmPasswordChange}
+              />
+            </Field>
+          </Stack>
+        </Stack>
+      </Dialog.Body>
+      <Dialog.Footer gap="2">
+        <Button size="xs" variant="ghost" onClick={onClose}>
+          {t('common.cancel')}
+        </Button>
+        <Button loading={form.isSubmitting} size="xs" variant="solid" onClick={handleSave}>
+          {t('users.saveChanges')}
+        </Button>
+      </Dialog.Footer>
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/auth/components/SessionExpiryGuard.tsx b/invokeai/frontend/webv2/src/workbench/auth/components/SessionExpiryGuard.tsx
new file mode 100644
index 00000000000..9f34f706ba0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/components/SessionExpiryGuard.tsx
@@ -0,0 +1,21 @@
+import { useNavigate } from '@tanstack/react-router';
+import { useAuthSession } from '@workbench/auth/session';
+import { useEffect } from 'react';
+
+/**
+ * Watches for mid-session token rejection (a 401 on any authenticated request)
+ * and routes back to the login screen, which explains the expiry. Mounted once
+ * inside the workbench route; renders nothing.
+ */
+export const SessionExpiryGuard = () => {
+  const session = useAuthSession();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    if (session.multiuserEnabled && session.sessionExpired && session.user === null) {
+      void navigate({ to: '/login' });
+    }
+  }, [navigate, session.multiuserEnabled, session.sessionExpired, session.user]);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/auth/components/SetupScreen.tsx b/invokeai/frontend/webv2/src/workbench/auth/components/SetupScreen.tsx
new file mode 100644
index 00000000000..3e5a32cbd70
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/components/SetupScreen.tsx
@@ -0,0 +1,115 @@
+import { chakra, Input, Stack } from '@chakra-ui/react';
+import { useNavigate } from '@tanstack/react-router';
+import { createSetupSchema, PASSWORD_RULES_HINT, type SetupFormValues } from '@workbench/auth/schemas';
+import { completeAdminSetup, useAuthSession } from '@workbench/auth/session';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, Field } from '@workbench/components/ui';
+import { useZodForm } from '@workbench/models/useZodForm';
+import { useCallback, useMemo, type ChangeEvent, type FormEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { AuthFormAlert, AuthScreen } from './AuthScreen';
+import { PasswordInput, PasswordStrengthMeter } from './PasswordInput';
+
+const INITIAL_VALUES: SetupFormValues = { confirmPassword: '', displayName: '', email: '', password: '' };
+
+/**
+ * First-run screen for multi-user mode: creates the administrator account and
+ * signs straight into it.
+ */
+export const SetupScreen = () => {
+  const { t } = useTranslation();
+  const session = useAuthSession();
+  const navigate = useNavigate();
+  const schema = useMemo(() => createSetupSchema(session.strictPasswordChecking), [session.strictPasswordChecking]);
+  const form = useZodForm(schema, INITIAL_VALUES);
+
+  const submit = useCallback(
+    () =>
+      form.handleSubmit(async (values) => {
+        try {
+          await completeAdminSetup(values.email, values.displayName.trim() || null, values.password);
+        } catch (error) {
+          throw new Error(getApiErrorMessage(error, t('auth.couldNotCreateAdmin')));
+        }
+
+        await navigate({ to: '/' });
+      }),
+    [form, navigate, t]
+  );
+  const handleSubmit = useCallback(
+    (event: FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      void submit();
+    },
+    [submit]
+  );
+  const handleEmailChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('email', event.target.value),
+    [form]
+  );
+  const handleDisplayNameChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('displayName', event.target.value),
+    [form]
+  );
+  const handlePasswordChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('password', event.target.value),
+    [form]
+  );
+  const handleConfirmPasswordChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => form.setValue('confirmPassword', event.target.value),
+    [form]
+  );
+
+  return (
+    <AuthScreen footer={t('auth.setupFooter')} subtitle={t('auth.setupSubtitle')} title={t('auth.setupTitle')}>
+      <chakra.form display="flex" flexDirection="column" gap="4" onSubmit={handleSubmit}>
+        {form.formError ? <AuthFormAlert message={form.formError} tone="error" /> : null}
+        <Field error={form.errors.email} label={t('users.email')}>
+          <Input
+            aria-invalid={form.errors.email ? true : undefined}
+            autoComplete="email"
+            autoFocus
+            placeholder="admin@example.com"
+            value={form.values.email}
+            onChange={handleEmailChange}
+          />
+        </Field>
+        <Field helpText={t('auth.displayNameHelp')} label={t('users.displayName')}>
+          <Input
+            autoComplete="name"
+            placeholder={t('auth.administrator')}
+            value={form.values.displayName}
+            onChange={handleDisplayNameChange}
+          />
+        </Field>
+        <Field
+          error={form.errors.password}
+          helpText={session.strictPasswordChecking ? PASSWORD_RULES_HINT : undefined}
+          label={t('auth.password')}
+        >
+          <Stack gap="1.5">
+            <PasswordInput
+              aria-invalid={form.errors.password ? true : undefined}
+              autoComplete="new-password"
+              value={form.values.password}
+              onChange={handlePasswordChange}
+            />
+            <PasswordStrengthMeter password={form.values.password} />
+          </Stack>
+        </Field>
+        <Field error={form.errors.confirmPassword} label={t('auth.confirmPassword')}>
+          <PasswordInput
+            aria-invalid={form.errors.confirmPassword ? true : undefined}
+            autoComplete="new-password"
+            value={form.values.confirmPassword}
+            onChange={handleConfirmPasswordChange}
+          />
+        </Field>
+        <Button loading={form.isSubmitting} size="sm" type="submit" variant="solid">
+          {t('auth.createAdminAccount')}
+        </Button>
+      </chakra.form>
+    </AuthScreen>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/auth/schemas.test.ts b/invokeai/frontend/webv2/src/workbench/auth/schemas.test.ts
new file mode 100644
index 00000000000..59c5a1c87c1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/schemas.test.ts
@@ -0,0 +1,145 @@
+import { ApiError, getApiErrorMessage } from '@workbench/backend/http';
+import { describe, expect, it } from 'vitest';
+
+import {
+  createProfileSchema,
+  createSetupSchema,
+  createUserFormSchema,
+  getPasswordStrength,
+  loginSchema,
+} from './schemas';
+
+describe('password strength', () => {
+  it('mirrors the backend rules', () => {
+    expect(getPasswordStrength('short')).toBe('weak');
+    expect(getPasswordStrength('alllowercase')).toBe('moderate');
+    expect(getPasswordStrength('NoDigitsHere')).toBe('moderate');
+    expect(getPasswordStrength('Str0ngEnough')).toBe('strong');
+  });
+});
+
+describe('login schema', () => {
+  it('requires a valid email and a password', () => {
+    expect(loginSchema.safeParse({ email: 'not-an-email', password: 'x', rememberMe: false }).success).toBe(false);
+    expect(loginSchema.safeParse({ email: 'a@b.com', password: '', rememberMe: false }).success).toBe(false);
+    expect(loginSchema.safeParse({ email: 'a@b.com', password: 'pw', rememberMe: true }).success).toBe(true);
+  });
+
+  it('accepts special-use domains, matching the backend', () => {
+    expect(loginSchema.safeParse({ email: 'admin@localhost', password: 'pw', rememberMe: false }).success).toBe(true);
+    expect(loginSchema.safeParse({ email: 'dev@invoke.local', password: 'pw', rememberMe: false }).success).toBe(true);
+  });
+});
+
+describe('setup schema', () => {
+  it('enforces strength only in strict mode', () => {
+    const base = { confirmPassword: 'simple', displayName: '', email: 'a@b.com', password: 'simple' };
+
+    expect(createSetupSchema(false).safeParse(base).success).toBe(true);
+    expect(createSetupSchema(true).safeParse(base).success).toBe(false);
+    expect(
+      createSetupSchema(true).safeParse({ ...base, confirmPassword: 'Str0ngEnough', password: 'Str0ngEnough' }).success
+    ).toBe(true);
+  });
+
+  it('rejects mismatched confirmation', () => {
+    const result = createSetupSchema(false).safeParse({
+      confirmPassword: 'other',
+      displayName: '',
+      email: 'a@b.com',
+      password: 'simple',
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('profile schema', () => {
+  it('treats an empty new password as no change', () => {
+    const result = createProfileSchema(true).safeParse({
+      confirmPassword: '',
+      currentPassword: '',
+      displayName: 'Me',
+      newPassword: '',
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('requires the current password and confirmation when changing', () => {
+    const schema = createProfileSchema(false);
+
+    expect(
+      schema.safeParse({ confirmPassword: 'newpw', currentPassword: '', displayName: '', newPassword: 'newpw' }).success
+    ).toBe(false);
+    expect(
+      schema.safeParse({ confirmPassword: 'nope', currentPassword: 'old', displayName: '', newPassword: 'newpw' })
+        .success
+    ).toBe(false);
+    expect(
+      schema.safeParse({ confirmPassword: 'newpw', currentPassword: 'old', displayName: '', newPassword: 'newpw' })
+        .success
+    ).toBe(true);
+  });
+});
+
+describe('user form schema', () => {
+  it('requires email and password when creating', () => {
+    const schema = createUserFormSchema(true, true);
+
+    expect(schema.safeParse({ displayName: '', email: '', isAdmin: false, password: 'Str0ngEnough' }).success).toBe(
+      false
+    );
+    expect(schema.safeParse({ displayName: '', email: 'a@b.com', isAdmin: false, password: 'weak' }).success).toBe(
+      false
+    );
+    expect(
+      schema.safeParse({ displayName: '', email: 'a@b.com', isAdmin: true, password: 'Str0ngEnough' }).success
+    ).toBe(true);
+  });
+
+  it('allows an empty password when editing', () => {
+    const schema = createUserFormSchema(true, false);
+
+    expect(schema.safeParse({ displayName: 'New Name', email: '', isAdmin: false, password: '' }).success).toBe(true);
+    expect(schema.safeParse({ displayName: '', email: '', isAdmin: false, password: 'weak' }).success).toBe(false);
+  });
+});
+
+describe('getApiErrorMessage', () => {
+  it('unwraps FastAPI detail strings', () => {
+    expect(getApiErrorMessage(new ApiError('{"detail":"Incorrect email or password"}', 401), 'fallback')).toBe(
+      'Incorrect email or password'
+    );
+  });
+
+  it('unwraps the first validation issue', () => {
+    const body = JSON.stringify({ detail: [{ loc: ['body', 'email'], msg: 'value is not a valid email address' }] });
+
+    expect(getApiErrorMessage(new ApiError(body, 422), 'fallback')).toBe('email: value is not a valid email address');
+  });
+
+  it('formats multiple-of validation issues with the field and received value', () => {
+    const body = JSON.stringify({
+      detail: [
+        {
+          ctx: { multiple_of: 16 },
+          input: 888,
+          loc: ['body', 'batch', 'graph', 'nodes', 'denoise_latents', 'flux2_denoise', 'height'],
+          msg: 'Input should be a multiple of 16',
+          type: 'multiple_of',
+        },
+      ],
+    });
+
+    expect(getApiErrorMessage(new ApiError(body, 422), 'fallback')).toBe(
+      'height must be a multiple of 16 (received 888).'
+    );
+  });
+
+  it('falls back for non-JSON bodies and unknown errors', () => {
+    expect(getApiErrorMessage(new ApiError('', 500), 'fallback')).toBe('fallback');
+    expect(getApiErrorMessage(new ApiError('plain text', 500), 'fallback')).toBe('plain text');
+    expect(getApiErrorMessage('nope', 'fallback')).toBe('fallback');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/auth/schemas.ts b/invokeai/frontend/webv2/src/workbench/auth/schemas.ts
new file mode 100644
index 00000000000..d1ee8bc4ede
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/schemas.ts
@@ -0,0 +1,107 @@
+import { z } from 'zod';
+
+/**
+ * Form schemas for the auth surfaces. Password rules mirror the backend's
+ * `validate_password_strength`: 8+ characters with an uppercase letter, a
+ * lowercase letter, and a digit. When strict checking is off the backend
+ * accepts any non-empty password, so the schemas relax to match.
+ */
+
+export type PasswordStrength = 'weak' | 'moderate' | 'strong';
+
+export const getPasswordStrength = (password: string): PasswordStrength => {
+  if (password.length < 8) {
+    return 'weak';
+  }
+
+  const hasUpper = /[A-Z]/.test(password);
+  const hasLower = /[a-z]/.test(password);
+  const hasDigit = /\d/.test(password);
+
+  return hasUpper && hasLower && hasDigit ? 'strong' : 'moderate';
+};
+
+export const PASSWORD_RULES_HINT = 'At least 8 characters, with an uppercase letter, a lowercase letter, and a digit.';
+
+/**
+ * Deliberately lenient: the backend accepts special-use domains (`@localhost`,
+ * `.local`) for development setups, so the form only catches obvious mistakes
+ * and leaves real validation to the server.
+ */
+const emailSchema = z
+  .string()
+  .trim()
+  .refine((value) => {
+    const atIndex = value.indexOf('@');
+
+    return atIndex > 0 && atIndex < value.length - 1;
+  }, 'Enter a valid email address.');
+
+const createPasswordSchema = (strict: boolean) =>
+  strict
+    ? z
+        .string()
+        .min(8, 'Password must be at least 8 characters long.')
+        .refine((value) => getPasswordStrength(value) === 'strong', PASSWORD_RULES_HINT)
+    : z.string().min(1, 'Enter a password.');
+
+/** Optional-password variant: empty string means "leave unchanged". */
+const createOptionalPasswordSchema = (strict: boolean) =>
+  z.string().refine((value) => value === '' || !strict || getPasswordStrength(value) === 'strong', PASSWORD_RULES_HINT);
+
+export const loginSchema = z.object({
+  email: emailSchema,
+  password: z.string().min(1, 'Enter your password.'),
+  rememberMe: z.boolean(),
+});
+
+export type LoginFormValues = z.infer<typeof loginSchema>;
+
+export const createSetupSchema = (strict: boolean) =>
+  z
+    .object({
+      confirmPassword: z.string(),
+      displayName: z.string(),
+      email: emailSchema,
+      password: createPasswordSchema(strict),
+    })
+    .refine((values) => values.password === values.confirmPassword, {
+      message: 'Passwords do not match.',
+      path: ['confirmPassword'],
+    });
+
+export type SetupFormValues = z.infer<ReturnType<typeof createSetupSchema>>;
+
+export const createProfileSchema = (strict: boolean) =>
+  z
+    .object({
+      confirmPassword: z.string(),
+      currentPassword: z.string(),
+      displayName: z.string(),
+      newPassword: createOptionalPasswordSchema(strict),
+    })
+    .refine((values) => values.newPassword === '' || values.currentPassword !== '', {
+      message: 'Enter your current password to set a new one.',
+      path: ['currentPassword'],
+    })
+    .refine((values) => values.newPassword === '' || values.newPassword === values.confirmPassword, {
+      message: 'Passwords do not match.',
+      path: ['confirmPassword'],
+    });
+
+export type ProfileFormValues = z.infer<ReturnType<typeof createProfileSchema>>;
+
+/**
+ * One shape serves both admin user-form modes. Creating requires email and
+ * password; editing ignores the email field and treats an empty password as
+ * "leave unchanged".
+ */
+export const createUserFormSchema = (strict: boolean, requireCredentials: boolean) =>
+  z.object({
+    displayName: z.string(),
+    email: requireCredentials ? emailSchema : z.string(),
+    isAdmin: z.boolean(),
+    password: requireCredentials ? createPasswordSchema(strict) : createOptionalPasswordSchema(strict),
+  });
+
+export type UserFormValues = z.infer<ReturnType<typeof createUserFormSchema>>;
diff --git a/invokeai/frontend/webv2/src/workbench/auth/session.ts b/invokeai/frontend/webv2/src/workbench/auth/session.ts
new file mode 100644
index 00000000000..5a6c66eb495
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/auth/session.ts
@@ -0,0 +1,171 @@
+import { ApiError, clearAuthToken, getAuthToken, setAuthToken, setUnauthorizedHandler } from '@workbench/backend/http';
+import { socketHub } from '@workbench/backend/socketHub';
+import { createExternalStore } from '@workbench/externalStore';
+
+import { getAuthStatus, getCurrentUser, login, logout, setupAdmin, type AuthStatus, type UserDTO } from './api';
+
+/**
+ * Session-lived auth state shared by the router guards and shell chrome. When
+ * multi-user is disabled on the backend the snapshot stays at its defaults
+ * (`multiuserEnabled: false`, `user: null`) and the entire auth surface — login
+ * screen, user menu, expiry handling — stays dormant.
+ */
+export interface AuthSession {
+  /** 'unknown' until the first `/auth/status` round-trip resolves. */
+  phase: 'unknown' | 'ready';
+  multiuserEnabled: boolean;
+  setupRequired: boolean;
+  strictPasswordChecking: boolean;
+  user: UserDTO | null;
+  /** Set when a stored token is rejected mid-session; shown on the login screen. */
+  sessionExpired: boolean;
+}
+
+const store = createExternalStore<AuthSession>({
+  multiuserEnabled: false,
+  phase: 'unknown',
+  sessionExpired: false,
+  setupRequired: false,
+  strictPasswordChecking: false,
+  user: null,
+});
+
+export const useAuthSession = (): AuthSession => store.useSnapshot();
+
+/**
+ * Imperative read for non-reactive callers (e.g. the widget registry). Safe
+ * inside the workbench: the route guard resolves the session before mounting,
+ * and a user change remounts the whole workbench route.
+ */
+export const getAuthSession = (): AuthSession => store.getSnapshot();
+
+/**
+ * Sticky across sign-out: a debounced autosave can still fire during the
+ * logout transition, and it must land in the bucket of the user whose data
+ * was loaded — never the shared single-user bucket.
+ */
+let activeUserScope = '';
+
+const setActiveUserScope = (user: UserDTO | null): void => {
+  if (user !== null) {
+    activeUserScope = `:user:${user.user_id}`;
+  }
+};
+
+/**
+ * Suffix for localStorage keys holding user-owned state (projects, account
+ * preferences, personal API keys — see the spec's State Ownership section).
+ * Empty in single-user mode, so existing keys keep working unchanged.
+ */
+export const getUserStorageScope = (): string => (store.getSnapshot().multiuserEnabled ? activeUserScope : '');
+
+const fetchAuthStatus = async (): Promise<AuthStatus> => {
+  try {
+    return await getAuthStatus();
+  } catch {
+    // Backend unreachable: let the shell mount in single-user shape. The
+    // connection banner reports the outage, and a 401 once the backend returns
+    // in multi-user mode routes through the session-expiry path to login.
+    return { admin_email: null, multiuser_enabled: false, setup_required: false, strict_password_checking: false };
+  }
+};
+
+const resolveSession = async (): Promise<AuthSession> => {
+  const status = await fetchAuthStatus();
+  let user: UserDTO | null = null;
+
+  if (status.multiuser_enabled && !status.setup_required && getAuthToken()) {
+    try {
+      user = await getCurrentUser();
+    } catch (error) {
+      if (error instanceof ApiError && (error.status === 401 || error.status === 403)) {
+        clearAuthToken();
+      }
+      // Any other failure leaves `user` null; the route guard lands on login.
+    }
+  }
+
+  setActiveUserScope(user);
+  store.patchSnapshot({
+    multiuserEnabled: status.multiuser_enabled,
+    phase: 'ready',
+    setupRequired: status.setup_required,
+    strictPasswordChecking: status.strict_password_checking,
+    user,
+  });
+
+  return store.getSnapshot();
+};
+
+let pendingResolve: Promise<AuthSession> | null = null;
+
+/** Resolve the session exactly once per app load; later calls reuse the snapshot. */
+export const ensureAuthSession = (): Promise<AuthSession> => {
+  const current = store.getSnapshot();
+
+  if (current.phase === 'ready') {
+    return Promise.resolve(current);
+  }
+
+  pendingResolve ??= resolveSession().finally(() => {
+    pendingResolve = null;
+  });
+
+  return pendingResolve;
+};
+
+export const loginWithCredentials = async (email: string, password: string, rememberMe: boolean): Promise<void> => {
+  // A stale token must not ride along on the login request itself.
+  clearAuthToken();
+
+  const result = await login({ email, password, remember_me: rememberMe });
+
+  setAuthToken(result.token);
+  setActiveUserScope(result.user);
+  store.patchSnapshot({ sessionExpired: false, user: result.user });
+};
+
+export const logoutSession = async (): Promise<void> => {
+  try {
+    await logout();
+  } catch {
+    // Tokens are stateless on the backend; local sign-out always wins.
+  }
+
+  clearAuthToken();
+  // Tear down the shared socket so it does not linger authenticated as the
+  // previous user; the next authenticated mount reconnects with a fresh token.
+  socketHub.disconnect();
+  store.patchSnapshot({ sessionExpired: false, user: null });
+};
+
+/** Create the initial admin account, then sign straight in with it. */
+export const completeAdminSetup = async (
+  email: string,
+  displayName: string | null,
+  password: string
+): Promise<void> => {
+  await setupAdmin({ display_name: displayName, email, password });
+  store.patchSnapshot({ setupRequired: false });
+  await loginWithCredentials(email, password, false);
+};
+
+/** Reflect a profile edit (display name, password) into the session snapshot. */
+export const setSessionUser = (user: UserDTO): void => {
+  store.patchSnapshot({ user });
+};
+
+// A 401 on any authenticated request means the stored token expired or was
+// revoked. Only react while an authenticated multi-user session is live, so
+// failed login attempts and single-user mode never trip it.
+setUnauthorizedHandler(() => {
+  const session = store.getSnapshot();
+
+  if (!session.multiuserEnabled || session.user === null) {
+    return;
+  }
+
+  clearAuthToken();
+  socketHub.disconnect();
+  store.patchSnapshot({ sessionExpired: true, user: null });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/backend/SocketHubRuntime.tsx b/invokeai/frontend/webv2/src/workbench/backend/SocketHubRuntime.tsx
new file mode 100644
index 00000000000..9c8a4b9c91a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/SocketHubRuntime.tsx
@@ -0,0 +1,20 @@
+import { useEffect } from 'react';
+
+import { socketHub } from './socketHub';
+
+/**
+ * Renders nothing. Mounted once above both the Launchpad and the editor: opens
+ * the single backend socket for the authenticated session. Feature-specific
+ * runtimes attach listeners where needed so this base runtime stays lightweight.
+ *
+ * It intentionally does NOT disconnect on unmount — that keeps it StrictMode
+ * safe and lets the socket persist across Launchpad↔editor navigation. The
+ * socket is torn down explicitly on logout/expiry (see `auth/session.ts`).
+ */
+export const SocketHubRuntime = () => {
+  useEffect(() => {
+    socketHub.connect();
+  }, []);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/backend/connectionStore.ts b/invokeai/frontend/webv2/src/workbench/backend/connectionStore.ts
new file mode 100644
index 00000000000..d2e87c5beb4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/connectionStore.ts
@@ -0,0 +1,29 @@
+import type { BackendConnectionStatus } from '@workbench/types';
+
+import { createExternalStore } from '@workbench/externalStore';
+
+/**
+ * Provider-free connection status for the shared backend socket. The socket hub
+ * is the sole writer; surfaces that mount no workbench providers (the Launchpad)
+ * read it directly, and the editor mirrors it into workbench state via a bridge
+ * in `WorkbenchRuntime`. Lives outside the reducer so the connection signal is
+ * available everywhere the socket is, not just inside the editor.
+ */
+export interface ConnectionSnapshot {
+  status: BackendConnectionStatus;
+  error?: string;
+}
+
+const store = createExternalStore<ConnectionSnapshot>({ status: 'connecting' });
+
+export const setConnectionStatus = (status: BackendConnectionStatus, error?: string): void => {
+  store.setSnapshot({ error, status });
+};
+
+export const getConnectionStatus = (): ConnectionSnapshot => store.getSnapshot();
+
+export const useConnectionStatusSelector = store.useSelector;
+
+export const useConnectionStatus = (): ConnectionSnapshot => store.useSnapshot();
+
+export const subscribeConnection = (listener: () => void): (() => void) => store.subscribe(listener);
diff --git a/invokeai/frontend/webv2/src/workbench/backend/events.ts b/invokeai/frontend/webv2/src/workbench/backend/events.ts
new file mode 100644
index 00000000000..48f709a61f6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/events.ts
@@ -0,0 +1,158 @@
+/**
+ * Typed contracts for the backend Socket.IO events webv2 consumes. Payload
+ * shapes mirror the pydantic models in
+ * `invokeai/app/services/events/events_common.py` (serialized as snake_case).
+ */
+
+/** Backend queue item lifecycle status. Note the backend spells it `canceled`. */
+export type BackendQueueItemStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'canceled';
+
+export type TerminalBackendQueueItemStatus = Extract<BackendQueueItemStatus, 'completed' | 'failed' | 'canceled'>;
+
+export interface QueueItemEventBase {
+  queue_id: string;
+  item_id: number;
+  batch_id: string;
+  origin: string | null;
+  destination: string | null;
+}
+
+export interface QueueItemStatusChangedEvent extends QueueItemEventBase {
+  status: BackendQueueItemStatus;
+  error_type: string | null;
+  error_message: string | null;
+  error_traceback: string | null;
+  created_at: string;
+  updated_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+  session_id: string;
+}
+
+export interface BatchEnqueuedEvent {
+  queue_id: string;
+  batch_id: string;
+  enqueued: number;
+  requested: number;
+  priority: number;
+  origin: string | null;
+  user_id: string;
+}
+
+export interface QueueClearedEvent {
+  queue_id: string;
+}
+
+export interface QueueItemsRetriedEvent {
+  queue_id: string;
+  retried_item_ids: number[];
+}
+
+/** Shared shape of per-invocation lifecycle events (`InvocationEventBase` on the backend). */
+export interface InvocationEventBase extends QueueItemEventBase {
+  session_id: string;
+  /** The id of the executing invocation's source node — the editor's node id. */
+  invocation_source_id: string;
+}
+
+export interface InvocationStartedEvent extends InvocationEventBase {}
+
+export interface InvocationProgressEvent extends InvocationEventBase {
+  message: string;
+  /** 0..1, or null for indeterminate progress. */
+  percentage: number | null;
+  /** Intermittent denoising preview, when the invocation produces one. */
+  image?: { width: number; height: number; dataURL: string } | null;
+}
+
+export interface InvocationCompleteEvent extends InvocationEventBase {
+  /** The invocation's output, discriminated by its `type` (e.g. `image_output`). */
+  result: { type: string } & Record<string, unknown>;
+}
+
+export interface InvocationErrorEvent extends InvocationEventBase {
+  error_type: string;
+  error_message: string;
+}
+
+export interface BackendSocketEvents {
+  queue_item_status_changed: QueueItemStatusChangedEvent;
+  batch_enqueued: BatchEnqueuedEvent;
+  queue_cleared: QueueClearedEvent;
+  queue_items_retried: QueueItemsRetriedEvent;
+  invocation_started: InvocationStartedEvent;
+  invocation_progress: InvocationProgressEvent;
+  invocation_complete: InvocationCompleteEvent;
+  invocation_error: InvocationErrorEvent;
+}
+
+export const isTerminalBackendStatus = (status: BackendQueueItemStatus): status is TerminalBackendQueueItemStatus =>
+  status === 'completed' || status === 'failed' || status === 'canceled';
+
+/**
+ * Queue items enqueued by webv2 carry the local queue item id in their origin
+ * so that submissions survive a reload: on startup the backend queue is listed
+ * and items are re-adopted by decoding their origin.
+ */
+const QUEUE_ITEM_ORIGIN_PREFIX = 'webv2:';
+const PROJECT_QUEUE_ITEM_ORIGIN_PREFIX = 'webv2:p:';
+
+/**
+ * The origin prefix for utility-queue items — small graphs (filter previews,
+ * SAM, …) enqueued OUTSIDE any project's queue and awaited directly via
+ * `socketHub.on` (see `canvas-engine/backend/utilityQueue.ts`).
+ *
+ * The whole point of a distinct prefix is result isolation (plan Risk 4): a
+ * utility item must never be mistaken for a project queue item and routed into
+ * staging or the gallery. `parseQueueItemOrigin` therefore returns `null` for it
+ * — so `queueCoordinator.reconcile` and `isQueueServerItemInProject` never map a
+ * utility backend item to a local project item, and `routeQueueItemResults`
+ * (only ever invoked for coordinator-tracked project runs, which utility items
+ * are never registered as) never sees it. The `util:` segment sits under the
+ * shared `webv2:` namespace but is checked BEFORE the generic branch below, so
+ * it is not misparsed as a bare (non-project) local queue item id.
+ */
+const UTILITY_QUEUE_ITEM_ORIGIN_PREFIX = 'webv2:util:';
+
+export const buildProjectQueueItemOriginPrefix = (projectId: string): string =>
+  `${PROJECT_QUEUE_ITEM_ORIGIN_PREFIX}${projectId}:q:`;
+
+export const buildQueueItemOrigin = (localQueueItemId: string, projectId?: string): string =>
+  projectId
+    ? `${buildProjectQueueItemOriginPrefix(projectId)}${localQueueItemId}`
+    : `${QUEUE_ITEM_ORIGIN_PREFIX}${localQueueItemId}`;
+
+/** Builds the isolated origin for a utility-queue item (`webv2:util:<id>`). */
+export const buildUtilityQueueItemOrigin = (utilityId: string): string =>
+  `${UTILITY_QUEUE_ITEM_ORIGIN_PREFIX}${utilityId}`;
+
+/** True when `origin` belongs to the utility queue (never a project/local queue item). */
+export const isUtilityQueueItemOrigin = (origin: string | null | undefined): boolean =>
+  origin?.startsWith(UTILITY_QUEUE_ITEM_ORIGIN_PREFIX) ?? false;
+
+export const parseQueueItemOrigin = (origin: string | null | undefined): string | null => {
+  // Utility items are intentionally invisible to project routing (Risk 4): they
+  // resolve to no local queue item, so nothing adopts them or routes their
+  // results. Checked first because `webv2:util:` also matches the generic
+  // `webv2:` branch below.
+  if (isUtilityQueueItemOrigin(origin)) {
+    return null;
+  }
+
+  return origin?.startsWith(PROJECT_QUEUE_ITEM_ORIGIN_PREFIX)
+    ? origin.slice(origin.lastIndexOf(':q:') + 3)
+    : origin?.startsWith(QUEUE_ITEM_ORIGIN_PREFIX)
+      ? origin.slice(QUEUE_ITEM_ORIGIN_PREFIX.length)
+      : null;
+};
+
+export const parseQueueItemOriginProjectId = (origin: string | null | undefined): string | null => {
+  if (!origin?.startsWith(PROJECT_QUEUE_ITEM_ORIGIN_PREFIX)) {
+    return null;
+  }
+
+  const rest = origin.slice(PROJECT_QUEUE_ITEM_ORIGIN_PREFIX.length);
+  const separatorIndex = rest.indexOf(':q:');
+
+  return separatorIndex === -1 ? null : rest.slice(0, separatorIndex);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/backend/http.ts b/invokeai/frontend/webv2/src/workbench/backend/http.ts
new file mode 100644
index 00000000000..399c644b561
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/http.ts
@@ -0,0 +1,196 @@
+/**
+ * Shared HTTP client for the InvokeAI backend. Every REST call goes through
+ * `apiFetch` so authentication matches the WebSocket connection: both read the
+ * same `auth_token` and send it as a bearer token. The token is read per
+ * request, so a login that lands mid-session applies without a reload.
+ */
+
+const API_BASE_URL = import.meta.env.VITE_INVOKEAI_API_BASE_URL ?? '';
+const AUTH_TOKEN_STORAGE_KEY = 'auth_token';
+
+export const getAuthToken = (): string | null => {
+  try {
+    return window.localStorage.getItem(AUTH_TOKEN_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+};
+
+export const setAuthToken = (token: string): void => {
+  try {
+    window.localStorage.setItem(AUTH_TOKEN_STORAGE_KEY, token);
+  } catch {
+    // Storage unavailable (private mode, quota): the session lasts until reload.
+  }
+};
+
+export const clearAuthToken = (): void => {
+  try {
+    window.localStorage.removeItem(AUTH_TOKEN_STORAGE_KEY);
+  } catch {
+    // Nothing to clear if storage is unavailable.
+  }
+};
+
+/**
+ * Called when an authenticated request comes back 401 — the stored token is no
+ * longer valid. The auth session store registers itself here so the HTTP layer
+ * stays unaware of session semantics.
+ */
+let unauthorizedHandler: (() => void) | null = null;
+
+export const setUnauthorizedHandler = (handler: (() => void) | null): void => {
+  unauthorizedHandler = handler;
+};
+
+export const getBackendSocketUrl = (): string => {
+  if (!API_BASE_URL.trim()) {
+    return window.location.origin;
+  }
+
+  return new URL(API_BASE_URL, window.location.origin).origin;
+};
+
+export const buildApiUrl = (path: string): string => `${API_BASE_URL}${path}`;
+
+/** Resolve a backend-relative resource URL (e.g. image URLs in DTOs) against the API host. */
+export const absolutizeApiUrl = (url: string): string => {
+  if (!API_BASE_URL || url.startsWith('http://') || url.startsWith('https://')) {
+    return url;
+  }
+
+  return new URL(url, API_BASE_URL).toString();
+};
+
+export class ApiError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}
+
+const humanizeFieldName = (value: string): string => value.replaceAll('_', ' ');
+
+const getLastString = (values: unknown[]): string | null => {
+  for (let index = values.length - 1; index >= 0; index -= 1) {
+    const value = values[index];
+
+    if (typeof value === 'string') {
+      return value;
+    }
+  }
+
+  return null;
+};
+
+const getValidationIssueMessage = (issue: unknown): string | null => {
+  if (!issue || typeof issue !== 'object') {
+    return null;
+  }
+
+  const record = issue as { ctx?: unknown; input?: unknown; loc?: unknown; msg?: unknown; type?: unknown };
+  const loc = Array.isArray(record.loc) ? record.loc : [];
+  const lastLoc = getLastString(loc);
+  const field = lastLoc ? humanizeFieldName(lastLoc) : null;
+
+  if (record.type === 'multiple_of') {
+    const ctx = record.ctx && typeof record.ctx === 'object' ? (record.ctx as { multiple_of?: unknown }) : null;
+    const multipleOf = ctx?.multiple_of;
+
+    if (field && typeof multipleOf === 'number') {
+      const received =
+        typeof record.input === 'number' || typeof record.input === 'string' ? ` (received ${record.input})` : '';
+
+      return `${field} must be a multiple of ${multipleOf}${received}.`;
+    }
+  }
+
+  if (typeof record.msg === 'string' && record.msg) {
+    return field ? `${field}: ${record.msg}` : record.msg;
+  }
+
+  return null;
+};
+
+export const assertOk = async (response: Response): Promise<Response> => {
+  if (response.ok) {
+    return response;
+  }
+
+  const text = await response.text();
+  throw new ApiError(text || `${response.status} ${response.statusText}`, response.status);
+};
+
+/** Authenticated fetch that leaves status handling to the caller. */
+export const apiFetchRaw = (path: string, init?: RequestInit): Promise<Response> => {
+  const token = getAuthToken();
+  const headers = new Headers(init?.headers);
+
+  if (token && !headers.has('Authorization')) {
+    headers.set('Authorization', `Bearer ${token}`);
+  }
+
+  return fetch(buildApiUrl(path), { ...init, headers });
+};
+
+export const apiFetch = async (path: string, init?: RequestInit): Promise<Response> => {
+  const hadToken = getAuthToken() !== null;
+  const response = await apiFetchRaw(path, init);
+
+  if (response.status === 401 && hadToken) {
+    unauthorizedHandler?.();
+  }
+
+  return assertOk(response);
+};
+
+/**
+ * Backend errors arrive as FastAPI JSON (`{"detail": "..."}`); `ApiError`
+ * carries the raw body. This unwraps `detail` into a human-readable message.
+ */
+export const getApiErrorMessage = (error: unknown, fallback: string): string => {
+  if (error instanceof ApiError) {
+    try {
+      const parsed = JSON.parse(error.message) as { detail?: unknown };
+
+      if (typeof parsed.detail === 'string' && parsed.detail) {
+        return parsed.detail;
+      }
+
+      // Validation errors come as a list of issues; surface the first one.
+      if (Array.isArray(parsed.detail)) {
+        const message = getValidationIssueMessage(parsed.detail[0]);
+
+        if (message) {
+          return message;
+        }
+      }
+    } catch {
+      // Not JSON — fall through to the raw message.
+    }
+
+    return error.message || fallback;
+  }
+
+  return error instanceof Error && error.message ? error.message : fallback;
+};
+
+export const apiFetchJson = async <T>(path: string, init?: RequestInit): Promise<T> => {
+  const headers = new Headers(init?.headers);
+
+  if (init?.body !== undefined && !(init.body instanceof FormData) && !headers.has('Content-Type')) {
+    headers.set('Content-Type', 'application/json');
+  }
+
+  const response = await apiFetch(path, { ...init, headers });
+
+  return (await response.json()) as T;
+};
+
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    window.setTimeout(resolve, ms);
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/backend/itemProgressStore.test.ts b/invokeai/frontend/webv2/src/workbench/backend/itemProgressStore.test.ts
new file mode 100644
index 00000000000..91e23d338db
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/itemProgressStore.test.ts
@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { itemProgressStore } from './itemProgressStore';
+
+describe('itemProgressStore', () => {
+  beforeEach(() => {
+    itemProgressStore.clearAll();
+  });
+
+  it('preserves the previous live preview image when a progress update has no image payload', () => {
+    itemProgressStore.set(42, {
+      image: { dataUrl: 'data:image/png;base64,step-1', height: 64, width: 64 },
+      message: 'Denoising 1/20',
+      percentage: 0.05,
+    });
+
+    itemProgressStore.set(42, {
+      message: 'Denoising 2/20',
+      percentage: 0.1,
+    });
+
+    expect(itemProgressStore.get(42)).toEqual({
+      image: { dataUrl: 'data:image/png;base64,step-1', height: 64, width: 64 },
+      message: 'Denoising 2/20',
+      percentage: 0.1,
+    });
+  });
+
+  it('clears the live preview image when a progress update explicitly sets image to null', () => {
+    itemProgressStore.set(42, {
+      image: { dataUrl: 'data:image/png;base64,step-1', height: 64, width: 64 },
+      message: 'Denoising 1/20',
+      percentage: 0.05,
+    });
+
+    itemProgressStore.set(42, {
+      image: null,
+      message: '',
+      percentage: null,
+    });
+
+    expect(itemProgressStore.get(42)).toEqual({
+      image: null,
+      message: '',
+      percentage: null,
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/backend/itemProgressStore.ts b/invokeai/frontend/webv2/src/workbench/backend/itemProgressStore.ts
new file mode 100644
index 00000000000..dee301fff10
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/itemProgressStore.ts
@@ -0,0 +1,41 @@
+import { createKeyedTransientStore } from '@workbench/externalStore';
+import { mergeDenoiseProgressImage, type DenoiseProgressImage } from '@workbench/images/streamingImageSource';
+
+/**
+ * Live progress for in-flight queue items keyed by the backend `item_id`. The
+ * sibling `progressStore` keys by the *local* submission id, which only exists
+ * for items this client enqueued; the Queue widget shows the whole server queue,
+ * so its NOW & NEXT card needs progress addressable by the backend id carried on
+ * the socket's `invocation_started`/`invocation_progress` events.
+ */
+
+export interface ItemProgress {
+  message: string;
+  /** 0..1, or null while indeterminate. */
+  percentage: number | null;
+  image?: DenoiseProgressImage | null;
+}
+
+const progressByItemId = createKeyedTransientStore<number, ItemProgress>();
+
+export const itemProgressStore = {
+  get(itemId: number): ItemProgress | null {
+    return progressByItemId.get(itemId) ?? null;
+  },
+  set(itemId: number, progress: ItemProgress): void {
+    const current = progressByItemId.get(itemId);
+    const image = mergeDenoiseProgressImage(current?.image, progress.image);
+    const next = image === undefined ? progress : { ...progress, image };
+
+    progressByItemId.set(itemId, next);
+  },
+  clear(itemId: number): void {
+    progressByItemId.delete(itemId);
+  },
+  clearAll(): void {
+    progressByItemId.clear();
+  },
+};
+
+export const useItemProgress = (itemId: number | null | undefined): ItemProgress | null =>
+  progressByItemId.useValue(itemId ?? -1) ?? null;
diff --git a/invokeai/frontend/webv2/src/workbench/backend/modelLoadStore.ts b/invokeai/frontend/webv2/src/workbench/backend/modelLoadStore.ts
new file mode 100644
index 00000000000..d4835cd3314
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/modelLoadStore.ts
@@ -0,0 +1,38 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+export interface ModelLoadInfo {
+  label: string;
+}
+
+const store = createExternalStore<{ activeLoads: ModelLoadInfo[] }>({ activeLoads: [] });
+
+const getModelLoadLabel = (payload: unknown): string => {
+  const record = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {};
+  const config = record.config && typeof record.config === 'object' ? (record.config as Record<string, unknown>) : {};
+  const name = typeof config.name === 'string' && config.name.trim() ? config.name.trim() : 'model';
+  const extras = [config.base, config.type, record.submodel_type].filter(
+    (value): value is string => typeof value === 'string' && value.trim().length > 0
+  );
+
+  return extras.length ? `${name} (${extras.join(', ')})` : name;
+};
+
+export const modelLoadStore = {
+  started(payload: unknown): void {
+    store.patchSnapshot({ activeLoads: [...store.getSnapshot().activeLoads, { label: getModelLoadLabel(payload) }] });
+  },
+  completed(payload: unknown): void {
+    const label = getModelLoadLabel(payload);
+    const { activeLoads } = store.getSnapshot();
+    const index = activeLoads.findIndex((load) => load.label === label);
+
+    store.patchSnapshot({
+      activeLoads: index >= 0 ? activeLoads.filter((_, loadIndex) => loadIndex !== index) : activeLoads.slice(1),
+    });
+  },
+  reset(): void {
+    store.patchSnapshot({ activeLoads: [] });
+  },
+};
+
+export const useModelLoads = (): ModelLoadInfo[] => store.useSelector((snapshot) => snapshot.activeLoads);
diff --git a/invokeai/frontend/webv2/src/workbench/backend/nodeExecutionStore.ts b/invokeai/frontend/webv2/src/workbench/backend/nodeExecutionStore.ts
new file mode 100644
index 00000000000..477f732f64b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/nodeExecutionStore.ts
@@ -0,0 +1,100 @@
+import { createKeyedTransientStore } from '@workbench/externalStore';
+
+import type { InvocationCompleteEvent, InvocationErrorEvent, InvocationStartedEvent } from './events';
+
+import { buildApiUrl } from './http';
+
+/**
+ * Ephemeral per-node execution state, keyed by the invocation's source node id
+ * (the workflow editor's node id). Like the queue-item progress store, this is
+ * high-frequency transient data that deliberately lives outside the workbench
+ * reducer; the editor's nodes subscribe per id and only re-render when their
+ * own node's state moves.
+ */
+
+export type NodeExecutionStatus = 'running' | 'completed' | 'failed';
+
+export interface NodeExecutionState {
+  status: NodeExecutionStatus;
+  /** 0..1, or null while indeterminate. Only meaningful while running. */
+  progress: number | null;
+  progressMessage: string | null;
+  /** Thumbnail of the node's most recent image output, when it produced one. */
+  outputImageUrl: string | null;
+  error: string | null;
+}
+
+const stateByNodeId = createKeyedTransientStore<string, NodeExecutionState>();
+
+/** Pull the produced image out of an invocation output, whatever the node type. */
+const getResultImageName = (result: InvocationCompleteEvent['result']): string | null => {
+  const image = (result as { image?: { image_name?: unknown } }).image;
+
+  return typeof image?.image_name === 'string' ? image.image_name : null;
+};
+
+export const nodeExecutionStore = {
+  clearAll(): void {
+    stateByNodeId.clear();
+  },
+  completed(event: InvocationCompleteEvent): void {
+    const imageName = getResultImageName(event.result);
+    const previous = stateByNodeId.get(event.invocation_source_id);
+
+    stateByNodeId.set(event.invocation_source_id, {
+      error: null,
+      outputImageUrl: imageName
+        ? buildApiUrl(`/api/v1/images/i/${encodeURIComponent(imageName)}/thumbnail`)
+        : (previous?.outputImageUrl ?? null),
+      progress: null,
+      progressMessage: null,
+      status: 'completed',
+    });
+  },
+  failed(event: InvocationErrorEvent): void {
+    const previous = stateByNodeId.get(event.invocation_source_id);
+
+    stateByNodeId.set(event.invocation_source_id, {
+      error: event.error_message,
+      outputImageUrl: previous?.outputImageUrl ?? null,
+      progress: null,
+      progressMessage: null,
+      status: 'failed',
+    });
+  },
+  progress(nodeId: string, percentage: number | null, message: string): void {
+    const previous = stateByNodeId.get(nodeId);
+
+    stateByNodeId.set(nodeId, {
+      error: null,
+      outputImageUrl: previous?.outputImageUrl ?? null,
+      progress: percentage,
+      progressMessage: message,
+      status: 'running',
+    });
+  },
+  /** A queue item reached a terminal state: nothing can still be running. */
+  settleRunning(): void {
+    for (const [nodeId, state] of stateByNodeId.entries()) {
+      if (state.status === 'running') {
+        stateByNodeId.set(nodeId, { ...state, progress: null, progressMessage: null, status: 'completed' });
+      }
+    }
+  },
+  started(event: InvocationStartedEvent): void {
+    const previous = stateByNodeId.get(event.invocation_source_id);
+
+    stateByNodeId.set(event.invocation_source_id, {
+      error: null,
+      outputImageUrl: previous?.outputImageUrl ?? null,
+      progress: null,
+      progressMessage: null,
+      status: 'running',
+    });
+  },
+};
+
+export type NodeExecutionSink = typeof nodeExecutionStore;
+
+export const useNodeExecutionState = (nodeId: string): NodeExecutionState | null =>
+  stateByNodeId.useValue(nodeId) ?? null;
diff --git a/invokeai/frontend/webv2/src/workbench/backend/progressImageStore.ts b/invokeai/frontend/webv2/src/workbench/backend/progressImageStore.ts
new file mode 100644
index 00000000000..fd1ce3e21e3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/progressImageStore.ts
@@ -0,0 +1,64 @@
+import type { DenoiseProgressImage } from '@workbench/images/streamingImageSource';
+
+import { createExternalStore, createKeyedTransientStore } from '@workbench/externalStore';
+
+/**
+ * The most recent denoising preview image from `invocation_progress` events,
+ * as a b64 data URL. Cleared when the run settles so consumers (the editor's
+ * Current Image node, progress surfaces) fall back to the last real output.
+ */
+
+export type ProgressImageSnapshot = DenoiseProgressImage;
+
+export interface ProgressImageTarget {
+  queueItemId: string;
+  itemIndex: number;
+}
+
+export type LatestProgressImageSnapshot = ProgressImageSnapshot & { target?: ProgressImageTarget };
+
+const latestSnapshotStore = createExternalStore<{ latestSnapshot: LatestProgressImageSnapshot | null }>({
+  latestSnapshot: null,
+});
+const snapshotsByTarget = createKeyedTransientStore<string, ProgressImageSnapshot>();
+
+const getTargetKey = ({ itemIndex, queueItemId }: ProgressImageTarget): string => `${queueItemId}:${itemIndex}`;
+
+const isLatestTarget = (target: ProgressImageTarget): boolean =>
+  latestSnapshotStore.getSnapshot().latestSnapshot?.target?.queueItemId === target.queueItemId &&
+  latestSnapshotStore.getSnapshot().latestSnapshot?.target?.itemIndex === target.itemIndex;
+
+export const progressImageStore = {
+  clear(target?: ProgressImageTarget): void {
+    if (!target) {
+      latestSnapshotStore.patchSnapshot({ latestSnapshot: null });
+      snapshotsByTarget.clear();
+
+      return;
+    }
+
+    const targetKey = getTargetKey(target);
+    const didClearLatest = isLatestTarget(target);
+
+    snapshotsByTarget.delete(targetKey);
+
+    if (didClearLatest) {
+      latestSnapshotStore.patchSnapshot({ latestSnapshot: null });
+    }
+  },
+  set(image: ProgressImageSnapshot, target?: ProgressImageTarget): void {
+    latestSnapshotStore.patchSnapshot({ latestSnapshot: target ? { ...image, target } : image });
+
+    if (target) {
+      snapshotsByTarget.set(getTargetKey(target), image);
+    }
+  },
+};
+
+export type ProgressImageSink = typeof progressImageStore;
+
+export const useProgressImage = (): LatestProgressImageSnapshot | null =>
+  latestSnapshotStore.useSelector((snapshot) => snapshot.latestSnapshot);
+
+export const useQueueItemProgressImage = (queueItemId: string, itemIndex: number): ProgressImageSnapshot | null =>
+  snapshotsByTarget.useValue(getTargetKey({ itemIndex, queueItemId })) ?? null;
diff --git a/invokeai/frontend/webv2/src/workbench/backend/progressStore.ts b/invokeai/frontend/webv2/src/workbench/backend/progressStore.ts
new file mode 100644
index 00000000000..b96ac078846
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/progressStore.ts
@@ -0,0 +1,43 @@
+import { createKeyedTransientStore } from '@workbench/externalStore';
+
+/**
+ * Ephemeral live-progress store for in-flight queue items, keyed by the local
+ * queue item id. Progress is high-frequency transient data, so it deliberately
+ * lives outside the workbench reducer: routing it through dispatch would
+ * re-render every consumer of workbench state and churn autosave on each step
+ * of every generation. Any widget can subscribe to a single item via
+ * `useQueueItemProgress` and only re-renders when that item's progress moves.
+ */
+
+export interface QueueItemProgress {
+  /** 1-based image slot currently executing inside this local batch. */
+  activeItemIndex?: number;
+  completedItemCount?: number;
+  message: string;
+  /** 0..1, or null while indeterminate. */
+  percentage: number | null;
+  totalItemCount?: number;
+}
+
+export interface QueueItemProgressSink {
+  clearAll?(): void;
+  set(queueItemId: string, progress: QueueItemProgress): void;
+  clear(queueItemId: string): void;
+}
+
+const progressByQueueItemId = createKeyedTransientStore<string, QueueItemProgress>();
+
+export const queueItemProgressStore: QueueItemProgressSink = {
+  clearAll() {
+    progressByQueueItemId.clear();
+  },
+  clear(queueItemId) {
+    progressByQueueItemId.delete(queueItemId);
+  },
+  set(queueItemId, progress) {
+    progressByQueueItemId.set(queueItemId, progress);
+  },
+};
+
+export const useQueueItemProgress = (queueItemId: string): QueueItemProgress | null =>
+  progressByQueueItemId.useValue(queueItemId) ?? null;
diff --git a/invokeai/frontend/webv2/src/workbench/backend/queueCoordinator.test.ts b/invokeai/frontend/webv2/src/workbench/backend/queueCoordinator.test.ts
new file mode 100644
index 00000000000..1fa2bec550e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/queueCoordinator.test.ts
@@ -0,0 +1,675 @@
+import type { EnqueueGenerateRequest, ImageDTO, QueueItemDTO } from '@workbench/generation/types';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { NodeExecutionSink } from './nodeExecutionStore';
+import type { QueueItemProgress, QueueItemProgressSink } from './progressStore';
+
+import { buildQueueItemOrigin, buildUtilityQueueItemOrigin, type QueueItemStatusChangedEvent } from './events';
+import { ApiError } from './http';
+import {
+  createQueueCoordinator,
+  QueueItemCancelledError,
+  type QueueCoordinator,
+  type QueueCoordinatorApi,
+  type QueueCoordinatorCallbacks,
+} from './queueCoordinator';
+import { createSocketHub, type BackendSocket } from './socketHub';
+
+class FakeSocket implements BackendSocket {
+  readonly emitted: { event: string; payload: unknown }[] = [];
+  private readonly handlers = new Map<string, ((payload: never) => void)[]>();
+
+  on(event: string, handler: (payload: never) => void): void {
+    this.handlers.set(event, [...(this.handlers.get(event) ?? []), handler]);
+  }
+
+  off(event: string, handler: (payload: never) => void): void {
+    this.handlers.set(
+      event,
+      (this.handlers.get(event) ?? []).filter((existing) => existing !== handler)
+    );
+  }
+
+  emit(event: string, payload: unknown): void {
+    this.emitted.push({ event, payload });
+  }
+
+  connect(): void {
+    this.fire('connect', undefined);
+  }
+
+  disconnect(): void {
+    this.fire('disconnect', 'io client disconnect');
+  }
+
+  fire(event: string, payload: unknown): void {
+    for (const handler of this.handlers.get(event) ?? []) {
+      (handler as (value: unknown) => void)(payload);
+    }
+  }
+}
+
+const createStatusEvent = (overrides: Partial<QueueItemStatusChangedEvent>): QueueItemStatusChangedEvent => ({
+  batch_id: 'batch-1',
+  completed_at: null,
+  created_at: '2026-06-10T00:00:00Z',
+  destination: 'gallery',
+  error_message: null,
+  error_traceback: null,
+  error_type: null,
+  item_id: 1,
+  origin: null,
+  queue_id: 'default',
+  session_id: 'session-1',
+  started_at: null,
+  status: 'completed',
+  updated_at: '2026-06-10T00:00:00Z',
+  ...overrides,
+});
+
+const createQueueItemDTO = (overrides: Partial<QueueItemDTO>): QueueItemDTO => ({
+  item_id: 1,
+  session: { results: {} },
+  status: 'in_progress',
+  ...overrides,
+});
+
+const createImage = (imageName: string, sourceQueueItemId: string): ImageDTO => ({
+  height: 64,
+  imageName,
+  imageUrl: `https://example.test/${imageName}`,
+  isIntermediate: false,
+  queuedAt: '2026-06-10T00:00:00Z',
+  sourceQueueItemId,
+  thumbnailUrl: `https://example.test/${imageName}/thumb`,
+  width: 64,
+});
+
+const generateRequest: EnqueueGenerateRequest = {
+  batchCount: 1,
+  destination: 'gallery',
+  graph: { edges: [], id: 'graph-1', nodes: {} },
+  negativePrompt: '',
+  negativePromptNodeId: 'negative_prompt',
+  positivePrompt: 'a fjord at dawn',
+  positivePromptNodeId: 'positive_prompt',
+  projectId: 'project-1',
+  seed: 1,
+  seedNodeId: 'seed',
+  shouldRandomizeSeed: false,
+  sourceQueueItemId: 'local-1',
+};
+
+interface Harness {
+  api: { [Key in keyof QueueCoordinatorApi]: ReturnType<typeof vi.fn> };
+  callbacks: { [Key in keyof QueueCoordinatorCallbacks]: ReturnType<typeof vi.fn> };
+  coordinator: QueueCoordinator;
+  hub: ReturnType<typeof createSocketHub>;
+  nodeExecution: { [Key in keyof NodeExecutionSink]: ReturnType<typeof vi.fn> };
+  progressImage: { clear: ReturnType<typeof vi.fn>; set: ReturnType<typeof vi.fn> };
+  progressEntries: Map<string, QueueItemProgress>;
+  socket: FakeSocket;
+}
+
+const createHarness = (options: { galleryRefreshCoalesceMs?: number } = {}): Harness => {
+  const socket = new FakeSocket();
+  const progressEntries = new Map<string, QueueItemProgress>();
+  const progress: QueueItemProgressSink = {
+    clear: (queueItemId) => {
+      progressEntries.delete(queueItemId);
+    },
+    set: (queueItemId, value) => {
+      progressEntries.set(queueItemId, value);
+    },
+  };
+  const api = {
+    cancelQueueItems: vi.fn(() => Promise.resolve()),
+    cancelQueueItemsByBatchIds: vi.fn(() => Promise.resolve()),
+    enqueueGenerateGraph: vi.fn(() => Promise.resolve({ batchId: 'batch-1', enqueued: 1, itemIds: [1], requested: 1 })),
+    enqueueWorkflowGraph: vi.fn(() => Promise.resolve({ batchId: 'batch-1', enqueued: 1, itemIds: [1], requested: 1 })),
+    getQueueItem: vi.fn((itemId: number) => Promise.resolve(createQueueItemDTO({ item_id: itemId }))),
+    getQueueItemResultImages: vi.fn((itemId: number, sourceQueueItemId: string) =>
+      Promise.resolve([createImage(`image-${itemId}.png`, sourceQueueItemId)])
+    ),
+    listAllQueueItems: vi.fn((): Promise<QueueItemDTO[]> => Promise.resolve([])),
+  };
+  const callbacks = {
+    onGalleryRefresh: vi.fn(),
+  };
+  const nodeExecution = {
+    clearAll: vi.fn(),
+    completed: vi.fn(),
+    failed: vi.fn(),
+    progress: vi.fn(),
+    settleRunning: vi.fn(),
+    started: vi.fn(),
+  };
+  const progressImage = { clear: vi.fn(), set: vi.fn() };
+  const hub = createSocketHub({ createSocket: () => socket });
+
+  hub.connect();
+
+  const coordinator = createQueueCoordinator(callbacks, {
+    api,
+    galleryRefreshCoalesceMs: options.galleryRefreshCoalesceMs ?? 1,
+    hub,
+    nodeExecution,
+    progress,
+    progressImage,
+  });
+
+  return { api, callbacks, coordinator, hub, nodeExecution, progressImage, progressEntries, socket };
+};
+
+describe('queueCoordinator', () => {
+  let harness: Harness;
+
+  beforeEach(() => {
+    harness = createHarness();
+  });
+
+  afterEach(() => {
+    harness.coordinator.dispose();
+    harness.hub.disconnect();
+    vi.useRealTimers();
+  });
+
+  it('settles submitted runs from terminal socket events without polling', async () => {
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 2,
+      itemIds: [1, 2],
+      requested: 2,
+    });
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 2 }));
+
+    const images = await resultsPromise;
+
+    expect(images.map((image) => image.imageName)).toEqual(['image-1.png', 'image-2.png']);
+    expect(harness.api.getQueueItem).not.toHaveBeenCalled();
+  });
+
+  it('rejects with the backend error message when a run fails', async () => {
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire(
+      'queue_item_status_changed',
+      createStatusEvent({ error_message: 'CUDA out of memory', item_id: 1, status: 'failed' })
+    );
+
+    await expect(resultsPromise).rejects.toThrow('CUDA out of memory');
+  });
+
+  it('rejects with QueueItemCancelledError when the backend cancels a run', async () => {
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1, status: 'canceled' }));
+
+    await expect(resultsPromise).rejects.toBeInstanceOf(QueueItemCancelledError);
+  });
+
+  it('returns completed batch item results when sibling backend items are canceled', async () => {
+    harness.callbacks.onBackendItemCancelled = vi.fn();
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 3,
+      itemIds: [1, 2, 3],
+      requested: 3,
+    });
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1, status: 'canceled' }));
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 2 }));
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 3, status: 'canceled' }));
+
+    const images = await resultsPromise;
+
+    expect(images.map((image) => image.imageName)).toEqual(['image-2.png']);
+    expect(harness.api.getQueueItemResultImages).toHaveBeenCalledTimes(1);
+    expect(harness.api.getQueueItemResultImages).toHaveBeenCalledWith(2, 'local-1', '2026-06-10T00:00:00Z');
+    expect(harness.callbacks.onBackendItemCancelled).toHaveBeenCalledWith('local-1', 1);
+    expect(harness.callbacks.onBackendItemCancelled).toHaveBeenCalledWith('local-1', 3);
+  });
+
+  it('forwards result image extraction options when waiting for results', async () => {
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z', {
+      resultNodeIds: ['canvas_output'],
+    });
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+
+    await resultsPromise;
+
+    expect(harness.api.getQueueItemResultImages).toHaveBeenCalledWith(1, 'local-1', '2026-06-10T00:00:00Z', {
+      resultNodeIds: ['canvas_output'],
+    });
+  });
+
+  it('rejects with QueueItemCancelledError when every backend item in a batch is canceled', async () => {
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 2,
+      itemIds: [1, 2],
+      requested: 2,
+    });
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1, status: 'canceled' }));
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 2, status: 'canceled' }));
+
+    await expect(resultsPromise).rejects.toBeInstanceOf(QueueItemCancelledError);
+    expect(harness.api.getQueueItemResultImages).not.toHaveBeenCalled();
+  });
+
+  it('settles runs whose terminal event arrived before tracking began', async () => {
+    harness.coordinator.connect();
+
+    // The event for item 1 lands while enqueue_batch is still resolving.
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+
+    const images = await harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    expect(images.map((image) => image.imageName)).toEqual(['image-1.png']);
+  });
+
+  it('rejects runs when the backend queue accepts no items', async () => {
+    harness.api.enqueueGenerateGraph.mockResolvedValue({ batchId: 'batch-1', enqueued: 0, itemIds: [], requested: 1 });
+
+    await expect(harness.coordinator.submitGenerate('local-1', generateRequest)).rejects.toThrow(
+      'The backend queue did not accept this generation.'
+    );
+  });
+
+  it('rejects runs when the backend queue accepts only part of the batch', async () => {
+    harness.api.enqueueGenerateGraph.mockResolvedValue({ batchId: 'batch-1', enqueued: 1, itemIds: [1], requested: 2 });
+
+    await expect(harness.coordinator.submitGenerate('local-1', generateRequest)).rejects.toThrow(
+      'The backend queue accepted 1 of 2 requested items.'
+    );
+  });
+
+  it('coalesces gallery refreshes across a burst of completions', async () => {
+    vi.useFakeTimers();
+    harness = createHarness({ galleryRefreshCoalesceMs: 400 });
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 10,
+      itemIds: Array.from({ length: 10 }, (_, index) => index + 1),
+      requested: 10,
+    });
+    harness.coordinator.connect();
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    await vi.advanceTimersByTimeAsync(500); // flush the on-connect refresh
+    harness.callbacks.onGalleryRefresh.mockClear();
+
+    for (let itemId = 1; itemId <= 10; itemId += 1) {
+      harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: itemId }));
+    }
+
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(harness.callbacks.onGalleryRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not refresh the gallery for failed or canceled items', async () => {
+    vi.useFakeTimers();
+    harness = createHarness({ galleryRefreshCoalesceMs: 400 });
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 2,
+      itemIds: [1, 2],
+      requested: 2,
+    });
+    harness.coordinator.connect();
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    await vi.advanceTimersByTimeAsync(500); // flush the on-connect refresh
+    harness.callbacks.onGalleryRefresh.mockClear();
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1, status: 'failed' }));
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 2, status: 'canceled' }));
+
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(harness.callbacks.onGalleryRefresh).not.toHaveBeenCalled();
+  });
+
+  it('routes progress events to the tracked item and clears them on completion', async () => {
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+
+    harness.socket.fire('invocation_progress', {
+      ...createStatusEvent({ item_id: 1 }),
+      message: 'Denoising',
+      percentage: 0.5,
+    });
+
+    expect(harness.progressEntries.get('local-1')).toEqual({
+      activeItemIndex: 1,
+      completedItemCount: 0,
+      message: 'Denoising',
+      percentage: 0.5,
+      totalItemCount: 1,
+    });
+
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+    await resultsPromise;
+
+    expect(harness.progressEntries.has('local-1')).toBe(false);
+    expect(harness.progressImage.clear).toHaveBeenCalledWith({ itemIndex: 1, queueItemId: 'local-1' });
+  });
+
+  it('keeps the completed progress image until backend item result routing finishes', async () => {
+    let finishRouting: () => void = () => undefined;
+    const routingPromise = new Promise<void>((resolve) => {
+      finishRouting = resolve;
+    });
+
+    harness.callbacks.onBackendItemComplete = vi.fn(() => routingPromise);
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire('invocation_progress', {
+      ...createStatusEvent({ item_id: 1 }),
+      image: { dataURL: 'data:image/png;base64,final-denoise', height: 32, width: 64 },
+      invocation_source_id: 'denoise',
+      message: 'Denoising',
+      percentage: 1,
+    });
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+
+    await resultsPromise;
+
+    expect(harness.callbacks.onBackendItemComplete).toHaveBeenCalledWith('local-1', 1);
+    expect(harness.progressImage.clear).not.toHaveBeenCalled();
+
+    finishRouting();
+    await routingPromise;
+    await Promise.resolve();
+
+    expect(harness.progressImage.clear).toHaveBeenCalledWith({ itemIndex: 1, queueItemId: 'local-1' });
+  });
+
+  it('notifies when one backend item in a batch completes', async () => {
+    harness.callbacks.onBackendItemComplete = vi.fn();
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 2,
+      itemIds: [1, 2],
+      requested: 2,
+    });
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+
+    expect(harness.callbacks.onBackendItemComplete).toHaveBeenCalledWith('local-1', 1);
+  });
+
+  it('routes progress images to the active image slot inside a submitted batch', async () => {
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 2,
+      itemIds: [1, 2],
+      requested: 2,
+    });
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+
+    harness.socket.fire('invocation_progress', {
+      ...createStatusEvent({ item_id: 2 }),
+      image: { dataURL: 'data:image/png;base64,abc', height: 32, width: 64 },
+      invocation_source_id: 'denoise',
+      message: 'Denoising',
+      percentage: 0.5,
+    });
+
+    expect(harness.progressImage.set).toHaveBeenCalledWith(
+      { dataUrl: 'data:image/png;base64,abc', height: 32, width: 64 },
+      { itemIndex: 2, queueItemId: 'local-1' }
+    );
+  });
+
+  it('ignores untracked queue events before mutating local execution state', () => {
+    vi.useFakeTimers();
+    harness = createHarness({ galleryRefreshCoalesceMs: 400 });
+    harness.coordinator.connect();
+    harness.callbacks.onGalleryRefresh.mockClear();
+
+    harness.socket.fire('invocation_started', {
+      ...createStatusEvent({ item_id: 99 }),
+      invocation_source_id: 'node-1',
+    });
+    harness.socket.fire('invocation_progress', {
+      ...createStatusEvent({ item_id: 99 }),
+      invocation_source_id: 'node-1',
+      message: 'other user progress',
+      percentage: 0.5,
+    });
+    harness.socket.fire('invocation_complete', {
+      ...createStatusEvent({ item_id: 99 }),
+      invocation_source_id: 'node-1',
+      result: { type: 'image_output' },
+    });
+    harness.socket.fire('invocation_error', {
+      ...createStatusEvent({ item_id: 99 }),
+      error_message: 'other user failure',
+      error_type: 'Error',
+      invocation_source_id: 'node-1',
+    });
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 99 }));
+
+    expect(harness.nodeExecution.started).not.toHaveBeenCalled();
+    expect(harness.nodeExecution.progress).not.toHaveBeenCalled();
+    expect(harness.nodeExecution.completed).not.toHaveBeenCalled();
+    expect(harness.nodeExecution.failed).not.toHaveBeenCalled();
+    expect(harness.nodeExecution.settleRunning).not.toHaveBeenCalled();
+    expect(harness.progressImage.clear).not.toHaveBeenCalled();
+    expect(harness.progressImage.set).not.toHaveBeenCalled();
+    expect(harness.callbacks.onGalleryRefresh).not.toHaveBeenCalled();
+  });
+
+  it('tracks the active image index inside a submitted batch', async () => {
+    harness.api.enqueueGenerateGraph.mockResolvedValue({
+      batchId: 'batch-1',
+      enqueued: 2,
+      itemIds: [1, 2],
+      requested: 2,
+    });
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+
+    expect(harness.progressEntries.get('local-1')).toEqual({
+      activeItemIndex: 1,
+      completedItemCount: 0,
+      message: '',
+      percentage: null,
+      totalItemCount: 2,
+    });
+
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+
+    expect(harness.progressEntries.get('local-1')).toEqual({
+      activeItemIndex: 2,
+      completedItemCount: 1,
+      message: '',
+      percentage: null,
+      totalItemCount: 2,
+    });
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 2 }));
+
+    await resultsPromise;
+  });
+
+  describe('reconcile', () => {
+    it('adopts pending items the backend already accepted, by origin', async () => {
+      harness.api.listAllQueueItems.mockResolvedValue([
+        createQueueItemDTO({ batch_id: 'batch-9', item_id: 7, origin: buildQueueItemOrigin('local-1') }),
+      ]);
+
+      const outcomes = await harness.coordinator.reconcile([{ id: 'local-1', status: 'pending' }]);
+
+      expect(outcomes.get('local-1')).toEqual({ backendBatchId: 'batch-9', backendItemIds: [7], kind: 'adopted' });
+      expect(harness.api.enqueueGenerateGraph).not.toHaveBeenCalled();
+    });
+
+    it('resumes running items and settles them from their listed terminal status', async () => {
+      harness.api.getQueueItem.mockResolvedValue(createQueueItemDTO({ item_id: 7, status: 'completed' }));
+
+      const outcomes = await harness.coordinator.reconcile([{ backendItemIds: [7], id: 'local-1', status: 'running' }]);
+
+      expect(outcomes.get('local-1')).toEqual({ kind: 'resumed' });
+      expect(harness.api.listAllQueueItems).not.toHaveBeenCalled();
+
+      const images = await harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+      expect(images.map((image) => image.imageName)).toEqual(['image-7.png']);
+    });
+
+    it('marks running items missing when their backend items vanished', async () => {
+      harness.api.getQueueItem.mockRejectedValue(new ApiError('not found', 404));
+
+      const outcomes = await harness.coordinator.reconcile([{ backendItemIds: [7], id: 'local-1', status: 'running' }]);
+
+      expect(outcomes.get('local-1')).toEqual({ kind: 'missing' });
+      expect(harness.api.listAllQueueItems).not.toHaveBeenCalled();
+    });
+
+    it('asks for a fresh enqueue when a pending item left no backend trace', async () => {
+      harness.api.listAllQueueItems.mockResolvedValue([]);
+
+      const outcomes = await harness.coordinator.reconcile([{ id: 'local-1', status: 'pending' }]);
+
+      expect(outcomes.get('local-1')).toEqual({ kind: 'enqueue' });
+    });
+
+    it('skips the backend round-trip when there is nothing to reconcile', async () => {
+      const outcomes = await harness.coordinator.reconcile([]);
+
+      expect(outcomes.size).toBe(0);
+      expect(harness.api.listAllQueueItems).not.toHaveBeenCalled();
+    });
+
+    // Review fix (Task 38, finding 3): the prior "Risk-4" coverage only asserted
+    // the parse primitive (`parseQueueItemOrigin(utilityOrigin) === null`) in
+    // isolation. This drives the REAL `reconcile` path with a completed,
+    // result-carrying `webv2:util:<uuid>`-origin backend item mixed into a live
+    // `listAllQueueItems` response, proving the coordinator itself — not just the
+    // helper it calls — never adopts it into a project queue item (which is the
+    // only way a utility item's images could ever reach `routeQueueItemResults`
+    // and land in canvas staging or the gallery).
+    it('never adopts a completed, result-carrying utility-origin item into a project queue item', async () => {
+      harness.api.listAllQueueItems.mockResolvedValue([
+        createQueueItemDTO({
+          batch_id: 'util-batch',
+          item_id: 99,
+          origin: buildUtilityQueueItemOrigin('util-run-1'),
+          session: { results: { n1: { image: { image_name: 'util-result.png' }, type: 'image_output' } } },
+          status: 'completed',
+        }),
+      ]);
+
+      const outcomes = await harness.coordinator.reconcile([{ id: 'local-1', status: 'pending' }]);
+
+      // The utility item parses to no local queue item id, so it can never be
+      // bucketed under 'local-1' by origin: the pending project item finds no
+      // backend trace of its own and is asked to enqueue fresh — never
+      // "adopted" with the utility item's id, and never routed anywhere.
+      expect(outcomes.get('local-1')).toEqual({ kind: 'enqueue' });
+      expect(harness.api.getQueueItemResultImages).not.toHaveBeenCalled();
+      expect(harness.api.getQueueItem).not.toHaveBeenCalledWith(99);
+    });
+  });
+
+  it('settles missed events through the safety sweep on reconnect', async () => {
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    // The completion event was lost to a disconnect; the reconnect sweep
+    // re-checks every outstanding item.
+    harness.api.getQueueItem.mockResolvedValue(createQueueItemDTO({ item_id: 1, status: 'completed' }));
+    harness.socket.fire('connect', undefined);
+
+    const images = await resultsPromise;
+
+    expect(images.map((image) => image.imageName)).toEqual(['image-1.png']);
+  });
+
+  it('fails runs whose backend items were pruned (404) during a sweep', async () => {
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    const resultsPromise = harness.coordinator.waitForResults('local-1', '2026-06-10T00:00:00Z');
+
+    harness.api.getQueueItem.mockRejectedValue(new ApiError('not found', 404));
+    harness.socket.fire('connect', undefined);
+
+    await expect(resultsPromise).rejects.toThrow('no longer on the backend queue');
+  });
+
+  it('prefers precise item ids for cancellation, falling back to batch id', async () => {
+    await harness.coordinator.cancelRun({ backendBatchId: 'batch-1', backendItemIds: [1, 2] });
+
+    expect(harness.api.cancelQueueItems).toHaveBeenCalledWith([1, 2]);
+    expect(harness.api.cancelQueueItemsByBatchIds).not.toHaveBeenCalled();
+
+    await harness.coordinator.cancelRun({ backendBatchId: 'batch-2' });
+
+    expect(harness.api.cancelQueueItemsByBatchIds).toHaveBeenCalledWith(['batch-2']);
+  });
+
+  it('treats stale missing backend items as already cancelled', async () => {
+    harness.api.cancelQueueItems.mockRejectedValue(
+      new ApiError('Queue item with id 42 not found in queue default', 404)
+    );
+
+    await expect(harness.coordinator.cancelRun({ backendItemIds: [42] })).resolves.toBeUndefined();
+  });
+
+  it('detaches socket listeners after dispose', async () => {
+    harness.coordinator.connect();
+
+    await harness.coordinator.submitGenerate('local-1', generateRequest);
+    harness.coordinator.dispose();
+
+    harness.socket.fire('queue_item_status_changed', createStatusEvent({ item_id: 1 }));
+
+    expect(harness.nodeExecution.settleRunning).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/backend/queueCoordinator.ts b/invokeai/frontend/webv2/src/workbench/backend/queueCoordinator.ts
new file mode 100644
index 00000000000..71795c3ca5c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/queueCoordinator.ts
@@ -0,0 +1,684 @@
+import type {
+  EnqueueGenerateRequest,
+  EnqueueGenerateResult,
+  EnqueueWorkflowRequest,
+  ImageDTO,
+  QueueItemDTO,
+} from '@workbench/generation/types';
+import type { BackendConnectionStatus } from '@workbench/types';
+
+import {
+  cancelQueueItems,
+  cancelQueueItemsByBatchIds,
+  enqueueGenerateGraph,
+  enqueueWorkflowGraph,
+  getQueueItem,
+  getQueueItemResultImages,
+  listAllQueueItems,
+  type QueueItemResultImageOptions,
+} from '@workbench/generation/api';
+
+import type { SocketHub } from './socketHub';
+
+import {
+  isTerminalBackendStatus,
+  parseQueueItemOrigin,
+  type InvocationCompleteEvent,
+  type InvocationErrorEvent,
+  type InvocationProgressEvent,
+  type InvocationStartedEvent,
+  type QueueItemStatusChangedEvent,
+  type TerminalBackendQueueItemStatus,
+} from './events';
+import { ApiError } from './http';
+import { modelLoadStore } from './modelLoadStore';
+import { nodeExecutionStore, type NodeExecutionSink } from './nodeExecutionStore';
+import { progressImageStore, type ProgressImageSink, type ProgressImageTarget } from './progressImageStore';
+import { queueItemProgressStore, type QueueItemProgressSink } from './progressStore';
+
+const GALLERY_REFRESH_COALESCE_MS = 400;
+const SAFETY_SWEEP_INTERVAL_MS = 30_000;
+const TERMINAL_EVENT_BUFFER_LIMIT = 256;
+
+export interface QueueCoordinatorApi {
+  cancelQueueItems: typeof cancelQueueItems;
+  cancelQueueItemsByBatchIds: typeof cancelQueueItemsByBatchIds;
+  enqueueGenerateGraph: typeof enqueueGenerateGraph;
+  enqueueWorkflowGraph: typeof enqueueWorkflowGraph;
+  getQueueItem: typeof getQueueItem;
+  getQueueItemResultImages: typeof getQueueItemResultImages;
+  listAllQueueItems: typeof listAllQueueItems;
+}
+
+export interface QueueCoordinatorCallbacks {
+  /** Fired when one backend item in a local batch completes, before the whole local batch necessarily settles. */
+  onBackendItemComplete?(localQueueItemId: string, backendItemId: number): void | Promise<void>;
+  /** Fired when one backend item in a local batch is canceled. */
+  onBackendItemCancelled?(localQueueItemId: string, backendItemId: number): void;
+  /** Coalesced signal that completed generations may have added gallery images. */
+  onGalleryRefresh(): void;
+}
+
+type TerminalOutcome = { status: 'completed' } | { status: 'failed'; error: string } | { status: 'canceled' };
+
+/** Thrown by `waitForResults` when the backend reports the run was canceled. */
+export class QueueItemCancelledError extends Error {
+  constructor(localQueueItemId: string) {
+    super(`Queue item ${localQueueItemId} was canceled.`);
+    this.name = 'QueueItemCancelledError';
+  }
+}
+
+export interface ReconcileInput {
+  id: string;
+  status: 'pending' | 'running';
+  backendItemIds?: number[];
+  backendBatchId?: string;
+}
+
+export type ReconcileOutcome =
+  /** A pending item the backend already accepted before the reload; do not re-enqueue. */
+  | { kind: 'adopted'; backendItemIds: number[]; backendBatchId?: string }
+  /** A running item whose backend items were found again; its results are awaitable. */
+  | { kind: 'resumed' }
+  /** A running item whose backend items no longer exist (queue cleared or pruned). */
+  | { kind: 'missing' }
+  /** A pending item the backend has never seen; submit it normally. */
+  | { kind: 'enqueue' };
+
+export interface CancelRunRequest {
+  backendBatchId?: string;
+  backendItemIds?: number[];
+}
+
+export interface QueueCoordinator {
+  connect(): void;
+  dispose(): void;
+  /**
+   * Match persisted pending/running queue items against the live backend queue
+   * so a reload neither double-submits nor orphans work. Adopted and resumed
+   * items are tracked and can be awaited with `waitForResults`.
+   */
+  reconcile(items: ReconcileInput[]): Promise<Map<string, ReconcileOutcome>>;
+  /** Enqueue a generate batch and track its backend items for event-driven settlement. */
+  submitGenerate(localQueueItemId: string, request: EnqueueGenerateRequest): Promise<EnqueueGenerateResult>;
+  /** Enqueue a compiled workflow graph and track its backend items the same way. */
+  submitWorkflow(localQueueItemId: string, request: EnqueueWorkflowRequest): Promise<EnqueueGenerateResult>;
+  /**
+   * Resolve once every backend item of the run reaches a terminal status —
+   * driven by socket events, with a slow safety sweep as the only polling.
+   * Resolves with the result images, throws on failure, and throws
+   * `QueueItemCancelledError` on backend-side cancellation.
+   */
+  waitForResults(
+    localQueueItemId: string,
+    queuedAt: string,
+    options?: QueueItemResultImageOptions
+  ): Promise<ImageDTO[]>;
+  cancelRun(request: CancelRunRequest): Promise<void>;
+}
+
+interface RunState {
+  backendItemIds: number[];
+  backendBatchId?: string;
+  outcomePromises: Promise<TerminalOutcome>[];
+}
+
+interface RunProgressState {
+  activeBackendItemId?: number;
+  backendItemIds: number[];
+  cancelledBackendItemIds: Set<number>;
+  completedBackendItemIds: Set<number>;
+  message: string;
+  percentage: number | null;
+}
+
+interface WaitState {
+  localQueueItemId: string;
+  settle: (outcome: TerminalOutcome) => void;
+}
+
+const defaultApi: QueueCoordinatorApi = {
+  cancelQueueItems,
+  cancelQueueItemsByBatchIds,
+  enqueueGenerateGraph,
+  enqueueWorkflowGraph,
+  getQueueItem,
+  getQueueItemResultImages,
+  listAllQueueItems,
+};
+
+const toTerminalOutcome = (
+  status: TerminalBackendQueueItemStatus,
+  error?: string | null,
+  errorType?: string | null
+): TerminalOutcome => {
+  if (status === 'completed') {
+    return { status: 'completed' };
+  }
+
+  if (status === 'failed') {
+    return { error: error ?? errorType ?? 'Generation failed.', status: 'failed' };
+  }
+
+  return { status: 'canceled' };
+};
+
+export const createQueueCoordinator = (
+  callbacks: QueueCoordinatorCallbacks,
+  options: {
+    hub: Pick<SocketHub, 'on' | 'emit' | 'onConnectionChange'>;
+    api?: Partial<QueueCoordinatorApi>;
+    galleryRefreshCoalesceMs?: number;
+    nodeExecution?: NodeExecutionSink;
+    progress?: QueueItemProgressSink;
+    progressImage?: ProgressImageSink;
+    sweepIntervalMs?: number;
+  }
+): QueueCoordinator => {
+  const api: QueueCoordinatorApi = { ...defaultApi, ...options.api };
+  const hub = options.hub;
+  const progress = options.progress ?? queueItemProgressStore;
+  const nodeExecution = options.nodeExecution ?? nodeExecutionStore;
+  const progressImage = options.progressImage ?? progressImageStore;
+  const galleryRefreshCoalesceMs = options.galleryRefreshCoalesceMs ?? GALLERY_REFRESH_COALESCE_MS;
+  const sweepIntervalMs = options.sweepIntervalMs ?? SAFETY_SWEEP_INTERVAL_MS;
+
+  const runs = new Map<string, RunState>();
+  const runProgress = new Map<string, RunProgressState>();
+  const waits = new Map<number, WaitState>();
+  /**
+   * Terminal events that arrived for items nobody tracks yet. Closes the race
+   * where a very fast generation finishes between `enqueue_batch` resolving
+   * and the run being registered.
+   */
+  const recentTerminalOutcomes = new Map<number, TerminalOutcome>();
+
+  const detachers: Array<() => void> = [];
+  let isAttached = false;
+  let isDisposed = false;
+  let galleryRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+  let sweepTimer: ReturnType<typeof setInterval> | null = null;
+  let isSweeping = false;
+
+  const scheduleGalleryRefresh = (): void => {
+    if (isDisposed || galleryRefreshTimer !== null) {
+      return;
+    }
+
+    galleryRefreshTimer = setTimeout(() => {
+      galleryRefreshTimer = null;
+      callbacks.onGalleryRefresh();
+    }, galleryRefreshCoalesceMs);
+  };
+
+  const bufferTerminalOutcome = (backendItemId: number, outcome: TerminalOutcome): void => {
+    recentTerminalOutcomes.delete(backendItemId);
+    recentTerminalOutcomes.set(backendItemId, outcome);
+
+    while (recentTerminalOutcomes.size > TERMINAL_EVENT_BUFFER_LIMIT) {
+      const oldestId = recentTerminalOutcomes.keys().next().value;
+
+      if (oldestId === undefined) {
+        return;
+      }
+
+      recentTerminalOutcomes.delete(oldestId);
+    }
+  };
+
+  const publishRunProgress = (localQueueItemId: string): void => {
+    const state = runProgress.get(localQueueItemId);
+
+    if (!state) {
+      return;
+    }
+
+    const terminalBackendItemIds = new Set([...state.completedBackendItemIds, ...state.cancelledBackendItemIds]);
+    const activeBackendItemId =
+      state.activeBackendItemId !== undefined && !terminalBackendItemIds.has(state.activeBackendItemId)
+        ? state.activeBackendItemId
+        : undefined;
+    const activeItemIndex = activeBackendItemId
+      ? state.backendItemIds.indexOf(activeBackendItemId) + 1
+      : Math.min(terminalBackendItemIds.size + 1, state.backendItemIds.length);
+
+    progress.set(localQueueItemId, {
+      activeItemIndex: Math.max(1, activeItemIndex),
+      completedItemCount: terminalBackendItemIds.size,
+      message: state.message,
+      percentage: state.percentage,
+      totalItemCount: state.backendItemIds.length,
+    });
+  };
+
+  const getProgressImageTarget = (localQueueItemId: string, backendItemId: number): ProgressImageTarget => {
+    const backendItemIds = runProgress.get(localQueueItemId)?.backendItemIds ?? [backendItemId];
+    const itemIndex = backendItemIds.indexOf(backendItemId);
+
+    return { itemIndex: itemIndex === -1 ? 1 : itemIndex + 1, queueItemId: localQueueItemId };
+  };
+
+  const settleWait = (backendItemId: number, outcome: TerminalOutcome): void => {
+    const wait = waits.get(backendItemId);
+
+    if (!wait) {
+      bufferTerminalOutcome(backendItemId, outcome);
+      return;
+    }
+
+    waits.delete(backendItemId);
+    const progressTarget = getProgressImageTarget(wait.localQueueItemId, backendItemId);
+    const clearProgressImage = (): void => progressImage.clear(progressTarget);
+    const state = runProgress.get(wait.localQueueItemId);
+
+    if (state) {
+      state.activeBackendItemId = undefined;
+      if (outcome.status === 'completed') {
+        state.completedBackendItemIds.add(backendItemId);
+      }
+      if (outcome.status === 'canceled') {
+        state.cancelledBackendItemIds.add(backendItemId);
+      }
+      state.message = '';
+      state.percentage = null;
+      publishRunProgress(wait.localQueueItemId);
+    }
+
+    if (outcome.status === 'completed') {
+      const routingPromise = callbacks.onBackendItemComplete?.(wait.localQueueItemId, backendItemId);
+
+      if (routingPromise) {
+        void Promise.resolve(routingPromise)
+          .finally(clearProgressImage)
+          .catch(() => undefined);
+      } else {
+        clearProgressImage();
+      }
+    }
+
+    if (outcome.status === 'canceled') {
+      clearProgressImage();
+      callbacks.onBackendItemCancelled?.(wait.localQueueItemId, backendItemId);
+    }
+
+    if (outcome.status === 'failed') {
+      clearProgressImage();
+    }
+
+    wait.settle(outcome);
+  };
+
+  const settleFromQueueItem = (queueItem: QueueItemDTO): void => {
+    if (queueItem.status !== 'pending' && queueItem.status !== 'in_progress') {
+      settleWait(queueItem.item_id, toTerminalOutcome(queueItem.status, queueItem.error_message, queueItem.error_type));
+    }
+  };
+
+  const isTrackedEvent = (event: { item_id: number }): boolean => waits.has(event.item_id);
+
+  const trackBackendItem = (localQueueItemId: string, backendItemId: number): Promise<TerminalOutcome> => {
+    const bufferedOutcome = recentTerminalOutcomes.get(backendItemId);
+
+    if (bufferedOutcome) {
+      recentTerminalOutcomes.delete(backendItemId);
+
+      return Promise.resolve(bufferedOutcome);
+    }
+
+    return new Promise<TerminalOutcome>((settle) => {
+      waits.set(backendItemId, { localQueueItemId, settle });
+    });
+  };
+
+  const beginRun = (localQueueItemId: string, backendItemIds: number[], backendBatchId?: string): void => {
+    runs.set(localQueueItemId, {
+      backendBatchId,
+      backendItemIds,
+      outcomePromises: backendItemIds.map((backendItemId) => trackBackendItem(localQueueItemId, backendItemId)),
+    });
+
+    runProgress.set(localQueueItemId, {
+      backendItemIds,
+      cancelledBackendItemIds: new Set(),
+      completedBackendItemIds: new Set(),
+      message: '',
+      percentage: null,
+    });
+    publishRunProgress(localQueueItemId);
+  };
+
+  /** Slow safety net for events lost to disconnects; runs on reconnect and on a long interval. */
+  const sweep = async (): Promise<void> => {
+    if (isSweeping || waits.size === 0) {
+      return;
+    }
+
+    isSweeping = true;
+
+    try {
+      await Promise.all(
+        [...waits.keys()].map(async (backendItemId) => {
+          try {
+            settleFromQueueItem(await api.getQueueItem(backendItemId));
+          } catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
+              settleWait(backendItemId, {
+                error: `Queue item ${backendItemId} is no longer on the backend queue.`,
+                status: 'failed',
+              });
+            }
+          }
+        })
+      );
+    } finally {
+      isSweeping = false;
+    }
+  };
+
+  const handleStatusChanged = (event: QueueItemStatusChangedEvent): void => {
+    if (!isTerminalBackendStatus(event.status)) {
+      return;
+    }
+
+    if (!isTrackedEvent(event)) {
+      bufferTerminalOutcome(event.item_id, toTerminalOutcome(event.status, event.error_message, event.error_type));
+      return;
+    }
+
+    nodeExecution.settleRunning();
+    settleWait(event.item_id, toTerminalOutcome(event.status, event.error_message, event.error_type));
+
+    if (event.status === 'completed') {
+      scheduleGalleryRefresh();
+    }
+  };
+
+  const handleProgress = (event: InvocationProgressEvent): void => {
+    const wait = waits.get(event.item_id);
+
+    if (!wait) {
+      return;
+    }
+
+    nodeExecution.progress(event.invocation_source_id, event.percentage, event.message);
+
+    if (event.image?.dataURL) {
+      progressImage.set(
+        { dataUrl: event.image.dataURL, height: event.image.height, width: event.image.width },
+        getProgressImageTarget(wait.localQueueItemId, event.item_id)
+      );
+    }
+
+    const state = runProgress.get(wait.localQueueItemId);
+
+    if (state) {
+      state.activeBackendItemId = event.item_id;
+      state.message = event.message;
+      state.percentage = event.percentage;
+      publishRunProgress(wait.localQueueItemId);
+    } else {
+      progress.set(wait.localQueueItemId, { message: event.message, percentage: event.percentage });
+    }
+  };
+
+  /**
+   * React to the shared socket's connection lifecycle. The hub owns the socket,
+   * the connection store, and `modelLoadStore.reset()`; the coordinator only
+   * clears its generation-scoped stores and, on (re)connect, schedules a gallery
+   * refresh and sweeps for events missed while disconnected.
+   */
+  const handleConnectionChange = (status: BackendConnectionStatus): void => {
+    progress.clearAll?.();
+    nodeExecution.clearAll();
+
+    if (status === 'connected') {
+      scheduleGalleryRefresh();
+      void sweep();
+    }
+  };
+
+  /** Attach generation listeners to the shared socket hub. */
+  const connect = (): void => {
+    if (isDisposed || isAttached) {
+      return;
+    }
+
+    isAttached = true;
+
+    detachers.push(
+      hub.on('queue_item_status_changed', handleStatusChanged),
+      hub.on('invocation_progress', handleProgress),
+      hub.on('invocation_started', (event: InvocationStartedEvent) => {
+        if (!isTrackedEvent(event)) {
+          return;
+        }
+
+        nodeExecution.started(event);
+      }),
+      hub.on('invocation_complete', (event: InvocationCompleteEvent) => {
+        if (!isTrackedEvent(event)) {
+          return;
+        }
+
+        nodeExecution.completed(event);
+      }),
+      hub.on('invocation_error', (event: InvocationErrorEvent) => {
+        if (!isTrackedEvent(event)) {
+          return;
+        }
+
+        nodeExecution.failed(event);
+      }),
+      hub.on('model_load_started', (payload: never) => {
+        modelLoadStore.started(payload);
+      }),
+      hub.on('model_load_complete', (payload: never) => {
+        modelLoadStore.completed(payload);
+      })
+    );
+
+    // Fires synchronously with the current status, so attaching after the hub
+    // has already connected still triggers the initial clear + sweep.
+    detachers.push(hub.onConnectionChange(handleConnectionChange));
+
+    sweepTimer = setInterval(() => {
+      void sweep();
+    }, sweepIntervalMs);
+  };
+
+  /** Detach generation listeners; the hub keeps the socket alive. */
+  const dispose = (): void => {
+    isDisposed = true;
+
+    for (const detach of detachers) {
+      detach();
+    }
+
+    detachers.length = 0;
+
+    if (galleryRefreshTimer !== null) {
+      clearTimeout(galleryRefreshTimer);
+      galleryRefreshTimer = null;
+    }
+
+    if (sweepTimer !== null) {
+      clearInterval(sweepTimer);
+      sweepTimer = null;
+    }
+  };
+
+  const reconcile = async (items: ReconcileInput[]): Promise<Map<string, ReconcileOutcome>> => {
+    const outcomes = new Map<string, ReconcileOutcome>();
+
+    if (items.length === 0) {
+      return outcomes;
+    }
+
+    const backendItems = items.every((item) => item.backendItemIds?.length)
+      ? (
+          await Promise.all(
+            items
+              .flatMap((item) => item.backendItemIds ?? [])
+              .map(async (itemId) => {
+                try {
+                  return await api.getQueueItem(itemId);
+                } catch (error) {
+                  if (error instanceof ApiError && error.status === 404) {
+                    return undefined;
+                  }
+
+                  throw error;
+                }
+              })
+          )
+        ).filter((item) => item !== undefined)
+      : await api.listAllQueueItems();
+    const backendItemsById = new Map(backendItems.map((item) => [item.item_id, item]));
+    const backendItemsByLocalId = new Map<string, QueueItemDTO[]>();
+
+    for (const backendItem of backendItems) {
+      const localQueueItemId = parseQueueItemOrigin(backendItem.origin);
+
+      if (localQueueItemId) {
+        backendItemsByLocalId.set(localQueueItemId, [
+          ...(backendItemsByLocalId.get(localQueueItemId) ?? []),
+          backendItem,
+        ]);
+      }
+    }
+
+    for (const item of items) {
+      const knownBackendItems = item.backendItemIds?.length
+        ? item.backendItemIds.map((backendItemId) => backendItemsById.get(backendItemId))
+        : (backendItemsByLocalId.get(item.id) ?? []);
+      const foundBackendItems = knownBackendItems.filter((backendItem) => backendItem !== undefined);
+
+      if (foundBackendItems.length !== knownBackendItems.length || foundBackendItems.length === 0) {
+        // A pending item with no backend trace was never accepted and is safe
+        // to submit; a running item with (partially) vanished backend items is
+        // unrecoverable.
+        outcomes.set(item.id, item.status === 'pending' ? { kind: 'enqueue' } : { kind: 'missing' });
+        continue;
+      }
+
+      const backendItemIds = foundBackendItems.map((backendItem) => backendItem.item_id);
+      const backendBatchId = item.backendBatchId ?? foundBackendItems[0]?.batch_id;
+
+      beginRun(item.id, backendItemIds, backendBatchId);
+
+      for (const backendItem of foundBackendItems) {
+        settleFromQueueItem(backendItem);
+      }
+
+      outcomes.set(
+        item.id,
+        item.status === 'running' ? { kind: 'resumed' } : { backendBatchId, backendItemIds, kind: 'adopted' }
+      );
+    }
+
+    return outcomes;
+  };
+
+  const submitGenerate = async (
+    localQueueItemId: string,
+    request: EnqueueGenerateRequest
+  ): Promise<EnqueueGenerateResult> => {
+    const result = await api.enqueueGenerateGraph(request);
+
+    if (result.enqueued === 0) {
+      throw new Error('The backend queue did not accept this generation. The queue may be full.');
+    }
+
+    if (result.requested !== result.enqueued) {
+      throw new Error(`The backend queue accepted ${result.enqueued} of ${result.requested} requested items.`);
+    }
+
+    beginRun(localQueueItemId, result.itemIds, result.batchId);
+
+    return result;
+  };
+
+  const submitWorkflow = async (
+    localQueueItemId: string,
+    request: EnqueueWorkflowRequest
+  ): Promise<EnqueueGenerateResult> => {
+    const result = await api.enqueueWorkflowGraph(request);
+
+    if (result.enqueued === 0) {
+      throw new Error('The backend queue did not accept this workflow. The queue may be full.');
+    }
+
+    if (result.requested !== result.enqueued) {
+      throw new Error(`The backend queue accepted ${result.enqueued} of ${result.requested} requested items.`);
+    }
+
+    beginRun(localQueueItemId, result.itemIds, result.batchId);
+
+    return result;
+  };
+
+  const waitForResults = async (
+    localQueueItemId: string,
+    queuedAt: string,
+    options?: QueueItemResultImageOptions
+  ): Promise<ImageDTO[]> => {
+    const run = runs.get(localQueueItemId);
+
+    if (!run) {
+      throw new Error(`Queue item ${localQueueItemId} has no tracked backend run.`);
+    }
+
+    try {
+      const outcomes = await Promise.all(run.outcomePromises);
+      const failure = outcomes.find((outcome) => outcome.status === 'failed');
+
+      if (failure) {
+        throw new Error(failure.error);
+      }
+
+      const completedBackendItemIds = run.backendItemIds.filter(
+        (_backendItemId, index) => outcomes[index]?.status === 'completed'
+      );
+
+      if (completedBackendItemIds.length === 0 && outcomes.some((outcome) => outcome.status === 'canceled')) {
+        throw new QueueItemCancelledError(localQueueItemId);
+      }
+
+      const imagesPerItem = await Promise.all(
+        completedBackendItemIds.map((backendItemId) =>
+          options
+            ? api.getQueueItemResultImages(backendItemId, localQueueItemId, queuedAt, options)
+            : api.getQueueItemResultImages(backendItemId, localQueueItemId, queuedAt)
+        )
+      );
+
+      return imagesPerItem.flat();
+    } finally {
+      runs.delete(localQueueItemId);
+      runProgress.delete(localQueueItemId);
+      progress.clear(localQueueItemId);
+    }
+  };
+
+  const cancelRun = async ({ backendBatchId, backendItemIds }: CancelRunRequest): Promise<void> => {
+    try {
+      if (backendItemIds?.length) {
+        await api.cancelQueueItems(backendItemIds);
+        return;
+      }
+
+      if (backendBatchId) {
+        await api.cancelQueueItemsByBatchIds([backendBatchId]);
+      }
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) {
+        return;
+      }
+
+      throw error;
+    }
+  };
+
+  return { cancelRun, connect, dispose, reconcile, submitGenerate, submitWorkflow, waitForResults };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/backend/socketHub.test.ts b/invokeai/frontend/webv2/src/workbench/backend/socketHub.test.ts
new file mode 100644
index 00000000000..3f2a574786b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/socketHub.test.ts
@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { BackendSocket } from './socketHub';
+
+import { getConnectionStatus } from './connectionStore';
+import { modelLoadStore } from './modelLoadStore';
+import { createSocketHub } from './socketHub';
+
+class FakeSocket implements BackendSocket {
+  readonly emitted: { event: string; payload: unknown }[] = [];
+  private readonly handlers = new Map<string, Set<(payload: never) => void>>();
+
+  on(event: string, handler: (payload: never) => void): void {
+    let handlers = this.handlers.get(event);
+
+    if (!handlers) {
+      handlers = new Set();
+      this.handlers.set(event, handlers);
+    }
+
+    handlers.add(handler);
+  }
+
+  off(event: string, handler: (payload: never) => void): void {
+    this.handlers.get(event)?.delete(handler);
+  }
+
+  emit(event: string, payload: unknown): void {
+    this.emitted.push({ event, payload });
+  }
+
+  connect(): void {
+    this.fire('connect', undefined);
+  }
+
+  disconnect(): void {
+    this.fire('disconnect', 'io client disconnect');
+  }
+
+  fire(event: string, payload: unknown): void {
+    for (const handler of this.handlers.get(event) ?? []) {
+      (handler as (value: unknown) => void)(payload);
+    }
+  }
+}
+
+describe('socketHub', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('connects, reports connected status, and subscribes to the queue', () => {
+    const socket = new FakeSocket();
+    const hub = createSocketHub({ createSocket: () => socket });
+    const onChange = vi.fn();
+
+    hub.onConnectionChange(onChange);
+    onChange.mockClear();
+    hub.connect();
+
+    expect(getConnectionStatus().status).toBe('connected');
+    expect(onChange).toHaveBeenNthCalledWith(1, 'connecting', undefined);
+    expect(onChange).toHaveBeenLastCalledWith('connected', undefined);
+    expect(socket.emitted).toContainEqual({ event: 'subscribe_queue', payload: { queue_id: 'default' } });
+  });
+
+  it('fires the current status synchronously on subscribe', () => {
+    const socket = new FakeSocket();
+    const hub = createSocketHub({ createSocket: () => socket });
+
+    hub.connect();
+
+    const late = vi.fn();
+
+    hub.onConnectionChange(late);
+
+    expect(late).toHaveBeenCalledWith('connected', undefined);
+  });
+
+  it('is idempotent — repeated connect keeps one socket', () => {
+    let created = 0;
+    const hub = createSocketHub({
+      createSocket: () => {
+        created += 1;
+
+        return new FakeSocket();
+      },
+    });
+
+    hub.connect();
+    hub.connect();
+
+    expect(created).toBe(1);
+  });
+
+  it('delivers consumer listeners and detaches them on unsubscribe', () => {
+    const socket = new FakeSocket();
+    const hub = createSocketHub({ createSocket: () => socket });
+
+    hub.connect();
+
+    const handler = vi.fn();
+    const off = hub.on('queue_item_status_changed', handler);
+
+    socket.fire('queue_item_status_changed', { item_id: 1 });
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    off();
+    socket.fire('queue_item_status_changed', { item_id: 2 });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-binds consumer listeners after a reconnect', () => {
+    const sockets: FakeSocket[] = [];
+    const hub = createSocketHub({
+      createSocket: () => {
+        const socket = new FakeSocket();
+
+        sockets.push(socket);
+
+        return socket;
+      },
+    });
+
+    hub.connect();
+
+    const handler = vi.fn();
+
+    hub.on('queue_item_status_changed', handler);
+    hub.disconnect();
+    hub.connect();
+
+    expect(sockets).toHaveLength(2);
+
+    sockets[1]!.fire('queue_item_status_changed', { item_id: 1 });
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('resets model loads and reports a disconnect', () => {
+    const resetSpy = vi.spyOn(modelLoadStore, 'reset');
+    const socket = new FakeSocket();
+    const hub = createSocketHub({ createSocket: () => socket });
+
+    hub.connect();
+    expect(resetSpy).toHaveBeenCalled();
+
+    socket.fire('disconnect', 'transport close');
+
+    expect(getConnectionStatus().status).toBe('disconnected');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/backend/socketHub.ts b/invokeai/frontend/webv2/src/workbench/backend/socketHub.ts
new file mode 100644
index 00000000000..344d236bb80
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/backend/socketHub.ts
@@ -0,0 +1,150 @@
+import type { BackendConnectionStatus } from '@workbench/types';
+
+import { io } from 'socket.io-client';
+
+import { setConnectionStatus } from './connectionStore';
+import { getAuthToken, getBackendSocketUrl } from './http';
+import { modelLoadStore } from './modelLoadStore';
+
+const SOCKET_PATH = '/ws/socket.io';
+
+/**
+ * The minimal Socket.IO surface the hub uses; tests substitute a fake.
+ */
+export interface BackendSocket {
+  on(event: string, handler: (payload: never) => void): unknown;
+  off(event: string, handler: (payload: never) => void): unknown;
+  emit(event: string, payload: unknown): unknown;
+  connect(): unknown;
+  disconnect(): unknown;
+}
+
+export type ConnectionListener = (status: BackendConnectionStatus, error?: string) => void;
+
+/**
+ * Owns the single backend socket for the whole authenticated app. It is only a
+ * transport/status hub; feature runtimes attach their own listeners so admin
+ * model code and editor queue code do not leak into the base Launchpad bundle.
+ */
+export interface SocketHub {
+  /** Idempotent: connects the single socket if one is not already live. */
+  connect(): void;
+  /** Tears down the socket (identity change / logout); a later `connect` rebuilds it. */
+  disconnect(): void;
+  /** Attach a raw socket listener; returns an unsubscribe. Survives socket recreation. */
+  on(event: string, handler: (payload: never) => void): () => void;
+  emit(event: string, payload: unknown): void;
+  /** Subscribe to connection transitions; fires synchronously with current status on subscribe. */
+  onConnectionChange(handler: ConnectionListener): () => void;
+}
+
+const createDefaultSocket = (): BackendSocket => {
+  const token = getAuthToken();
+
+  // Socket.IO's generic `off` overload does not structurally match our minimal
+  // facade; the socket satisfies the surface we actually use, so narrow it here.
+  return io(getBackendSocketUrl(), {
+    auth: token ? { token } : undefined,
+    autoConnect: false,
+    extraHeaders: token ? { Authorization: `Bearer ${token}` } : undefined,
+    path: SOCKET_PATH,
+    timeout: 60000,
+  }) as unknown as BackendSocket;
+};
+
+export const createSocketHub = (options: { createSocket?: () => BackendSocket } = {}): SocketHub => {
+  const createSocket = options.createSocket ?? createDefaultSocket;
+
+  let socket: BackendSocket | null = null;
+  let status: BackendConnectionStatus = 'connecting';
+  let lastError: string | undefined;
+
+  /** Registered consumer listeners, kept so they can be re-bound to a fresh socket. */
+  const eventHandlers = new Map<string, Set<(payload: never) => void>>();
+  const connectionListeners = new Set<ConnectionListener>();
+
+  const publishStatus = (next: BackendConnectionStatus, error?: string): void => {
+    status = next;
+    lastError = error;
+    setConnectionStatus(next, error);
+
+    for (const listener of connectionListeners) {
+      listener(next, error);
+    }
+  };
+
+  const connect = (): void => {
+    if (socket) {
+      return;
+    }
+
+    const nextSocket = createSocket();
+
+    socket = nextSocket;
+    publishStatus('connecting');
+
+    nextSocket.on('connect', () => {
+      modelLoadStore.reset();
+      publishStatus('connected');
+      nextSocket.emit('subscribe_queue', { queue_id: 'default' });
+    });
+    nextSocket.on('connect_error', (error: { message: string }) => {
+      modelLoadStore.reset();
+      publishStatus('disconnected', error.message);
+    });
+    nextSocket.on('disconnect', (reason: string) => {
+      modelLoadStore.reset();
+      publishStatus('disconnected', reason);
+    });
+
+    // Re-bind consumer listeners so they survive a socket recreation.
+    for (const [event, handlers] of eventHandlers) {
+      for (const handler of handlers) {
+        nextSocket.on(event, handler);
+      }
+    }
+
+    nextSocket.connect();
+  };
+
+  const disconnect = (): void => {
+    socket?.disconnect();
+    socket = null;
+    publishStatus('connecting');
+  };
+
+  const on = (event: string, handler: (payload: never) => void): (() => void) => {
+    let handlers = eventHandlers.get(event);
+
+    if (!handlers) {
+      handlers = new Set();
+      eventHandlers.set(event, handlers);
+    }
+
+    handlers.add(handler);
+    socket?.on(event, handler);
+
+    return () => {
+      eventHandlers.get(event)?.delete(handler);
+      socket?.off(event, handler);
+    };
+  };
+
+  const emit = (event: string, payload: unknown): void => {
+    socket?.emit(event, payload);
+  };
+
+  const onConnectionChange = (handler: ConnectionListener): (() => void) => {
+    connectionListeners.add(handler);
+    handler(status, lastError);
+
+    return () => {
+      connectionListeners.delete(handler);
+    };
+  };
+
+  return { connect, disconnect, emit, on, onConnectionChange };
+};
+
+/** The app-wide socket hub singleton, connected by `SocketHubRuntime`. */
+export const socketHub = createSocketHub();
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/ARCHITECTURE.md b/invokeai/frontend/webv2/src/workbench/canvas-engine/ARCHITECTURE.md
new file mode 100644
index 00000000000..e31fbbba4cb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/ARCHITECTURE.md
@@ -0,0 +1,148 @@
+# Canvas Engine Architecture
+
+## Ownership invariant
+
+The workbench reducer owns the serializable canvas contract. A per-project canvas engine owns pixels, decoded images, rendering, interaction, history, transient editing state, and caller-owned raster snapshots. Engine-owned objects never enter reducer actions or persisted project state.
+
+Canvas mutations are explicitly project-addressed. `CanvasProjectMutation` is the complete reducer mutation vocabulary, and the only `WorkbenchAction` that carries one is:
+
+```ts
+{
+  type: 'applyCanvasProjectMutation';
+  projectId: string;
+  mutation: CanvasProjectMutation;
+}
+```
+
+The workbench reducer handles this envelope only through `updateProjectById`. There are no canvas actions whose target is inferred from the active project.
+
+Each engine receives a `CanvasProjectMutationPort` bound to its immutable `projectId`. The port exposes only `getCanvasState()`, `subscribe()`, and `dispatch(mutation)`. It neither exposes the global workbench dispatcher nor follows active-project changes. Widgets use `useCanvasProjectMutationDispatch`, which captures the current project ID and emits the same envelope. Consequently, project switches and colliding layer IDs cannot redirect a delayed engine mutation to another project.
+
+The port's `dispatch()` returns whether the named project's canvas identity changed. Paint persistence clears a dirty result only after the intended layer accepts the bitmap reference. A rejected update retains dirty pixels for retry; deletion of the layer or project is terminal and discards obsolete persistence work. This applies equally to raster/control paint sources and paint-backed masks.
+
+## Package and capability boundaries
+
+`canvas-engine/` is the rendering and editing core. It may import engine-internal modules and shared canvas contracts, mutations, and the project mutation port. It must not import React, widgets, application canvas operations, generation graphs, socket infrastructure, or backend networking. `importBoundaries.test.ts` enforces that rule.
+
+`canvas-operations/` owns application workflows such as Filter and Select Object. Coordinators may depend on queues, uploads, model selection, and narrow engine capabilities. Their stores are React-free and compatible with `useSyncExternalStore`; React adapters remain under `widgets/`.
+
+The public engine handle is divided into capability groups such as `CanvasDocumentCapability`, `CanvasExportCapability`, `CanvasLayerCapability`, `CanvasLifecycleCapability`, and the interaction/store capabilities. Production consumers request the smallest aggregate they need. The full `CanvasEngine` type is limited by `fullEngineImports.test.ts` to the registry and composition roots; tests may construct full-engine fakes. The unused `fflate` dependency has been removed.
+
+`CanvasCoreStores` contains interaction state only. Filter and Select Object snapshots are created and owned by `canvas-operations`; application-session state cannot leak into the core store contract.
+
+Controllers communicate through constructor-injected ports or public capabilities. They do not reach into another controller's private maps, and the core engine never receives the global workbench dispatcher.
+
+## Controllers
+
+`engine.ts` is the core composition root and document-event router. New behavior belongs in a focused controller with explicit dependencies and an idempotent `dispose()` method.
+
+Current extracted ownership includes:
+
+- `RasterController`: base layer caches, decoded bitmap leases, derived and adjusted surfaces, rasterization jobs, invalidation, and the unified raster-memory controller.
+- `RasterMemoryBudgetController`: base, derived, decoded, detached, and reserved byte accounting plus generation-scoped and operation-owned reservations and pins.
+- `RenderController`: render targets, scheduler construction, previews, and render lifecycle.
+- `HistoryController`: engine-owned history and inactive byte trimming.
+- `PersistenceController`: dirty-bitmap flush barriers and disposal.
+- `EditingController`: selection state and exclusive edit-lease lifecycle.
+- `InteractionController`: public tool commands and their disposal boundary.
+- `LayerController`: guarded layer mutations and thumbnail capability ports.
+- `RasterExportController`: guarded layer rasterization, transformed copies, encoding, reservations, and pin leases.
+- `PsdExportController`: immutable PSD planning, snapshot capture, reservation, execution, and cancellation.
+- `StagedResultController`: guarded staged-candidate acceptance and its history entry.
+- `ControlPixelController`, `SelectionImageController`, and `LayerMutationController`: atomic pixel/document publication at their respective boundaries.
+- `MaskResultController`, `FilterResultController`, and `GeneratedResultController`: guarded application-result adoption through narrow host ports.
+
+Controller-local tests instantiate these boundaries with fakes. Integration tests in `engine.test.ts` cover composition, document routing, and cross-controller invariants.
+
+## Immutable document and raster snapshots
+
+`CanvasDocumentCapability.captureSnapshot()` returns a `CanvasDocumentSnapshot` or `null`. A snapshot contains a structured clone of the exact `CanvasStateContractV2` and the engine's `documentGeneration`. The engine privately associates it with the reducer canvas identity from which it was captured, so a caller cannot manufacture a current snapshot by copying fields.
+
+`CanvasExportCapability.captureRasterSnapshot(snapshot, layerIds, options)` requests exactly the required layer caches, temporarily pins them, reserves detached-surface capacity, and copies their pixels into independent surfaces. It returns a typed `ok`, `stale`, `aborted`, `not-ready`, or `over-budget` result. Freshness is checked before and after every asynchronous rasterization boundary and once after all copies are detached.
+
+An `ok` result contains a `CanvasRasterSnapshot`: the cloned canvas contract, its document generation, a map of detached layer surfaces, and an idempotent `release()`. The snapshot is caller-owned. Its surfaces do not read live caches and remain valid while the engine cools down; cooldown releases generation-scoped reservations and pins but does not invalidate detached snapshots. The caller must release the snapshot in `finally`. Engine disposal releases any snapshots still outstanding.
+
+This creates a deliberate transaction boundary:
+
+1. Before detachment completes, a document change makes the capture `stale`; no downstream submission may use a mixture of generations.
+2. After a successful invocation detachment, ordinary editing may continue. Composite, upload, graph compilation, and queue submission read only the frozen contract and detached surfaces.
+3. A wholesale canvas replacement remains a separate session, identified by `documentRevision`; completed results from an older session are dropped.
+
+Canvas invocation first crosses the paint-flush barrier, then captures the post-flush document, plans every raster/control/regional composite, and detaches exactly the contributing layers. Composite dedupe writes are staged in transaction-local maps. They are published to the persistent per-engine dedupe cache only after all frozen compositing, uploads, compilation, and queue dispatch complete; stale or failed captures leave no persistent dedupe entries.
+
+`submitCanvasInvocationSnapshot` carries the exact cloned canvas state used for compilation. `enqueueCompiledSnapshot` clones that supplied state rather than reading the live project canvas. Generated candidates are placed from `queueItem.snapshot.canvas.document.bbox`, so later bbox edits do not move the result. `documentRevision` still prevents results from a replaced canvas session from entering current staging.
+
+## Frame demand before allocation
+
+`calculateActiveFrameLayerIds` is a pure pre-allocation pass. For each enabled renderable layer it combines persisted source bounds with any larger live cache rect, applies the committed or transient transform (including rotation), respects isolation, and intersects the result with the document-space viewport.
+
+The render path computes this set before `ensureLayerCaches`. Only demanded layers are rasterized for the frame. Offscreen enabled layers are not eagerly allocated; they remain on-demand and LRU-evictable, then rasterize again when panning or a transform reveals them.
+
+Budget enforcement protects only:
+
+- layers demanded by the active frame; and
+- layers explicitly pinned by an in-flight thumbnail, export, snapshot, or other background operation.
+
+Derived surfaces are evicted first, followed by least-recently-used unprotected base caches. Export and thumbnail callers request and pin their own caches, preserving their behavior without treating all enabled layers as visible. Deterministic tests assert allocation counts and bytes for pan/reveal, rotated bounds, unflushed paint bounds, isolation, transient transforms, eviction, and re-rasterization.
+
+## Raster resource ownership and memory policy
+
+The raster soft limit is 512 MiB. `RasterMemoryBudgetController` maintains one snapshot across all material allocation classes:
+
+- `baseBytes`: layer cache surfaces;
+- `derivedBytes`: derived and adjusted display surfaces;
+- `decodedBytes`: leased `ImageBitmap` instances;
+- `detachedBytes`: caller-owned raster snapshot surfaces; and
+- `reservedBytes`: capacity promised to background work but not yet represented by another class.
+
+Active-frame base surfaces are allowed to exceed the soft limit so the visible frame can render; diagnostics report the overage. Background snapshots, thumbnails, raster exports, transformed/adjusted copies, and PSD exports must reserve sufficient available bytes before allocating and return typed `over-budget` outcomes when they cannot. Surface-cache enforcement subtracts decoded, detached, and reserved bytes before calculating the base/derived allowance.
+
+Reservations and cache pins are idempotent leases. Cancellable preparation work uses lifecycle-generation leases, which activation, cooldown, and disposal release if the normal `finally` path has not already done so. Once an asynchronous raster composite is in flight, it uses operation-owned reservations and pins instead: lifecycle changes may make its result stale, but cannot erase its accounting while a yielded allocation is still able to resume. The operation releases those leases in `finally`. Detached snapshot accounting is also caller-owned: it follows the snapshot and is released only by `CanvasRasterSnapshot.release()` or engine disposal.
+
+`DecodedBitmapPool` replaces permanent decoded-image caching. `acquire(imageName, decode, signal)` coalesces concurrent decodes for the same image and returns a short-lived `DecodedBitmapLease`. Each rasterizer releases its lease in `finally`. The bitmap closes after the final lease, a pending decode is aborted when all interested callers cancel, and disposal aborts pending work and closes every resolved bitmap. Pool byte changes feed `decodedBytes`, so decoded images participate in the same budget as surfaces.
+
+## Derived surfaces and invalidation
+
+Every display-only pixel effect uses `DerivedSurfaceCache`. A slot is identified by layer ID and effect kind, and guarded by source surface identity, monotonic source version, and a deterministic parameter key. Reuse is safe only when every guard matches. Source replacement therefore cannot publish or reuse a surface produced for an older preview.
+
+Invalidate only the affected effect when parameters change. Delete every derived slot when a layer is removed, replaced, or its base cache is evicted. Frame-demand culling happens before derived lookup or construction.
+
+## Edit leases and staged-result acceptance
+
+Application operations acquire one exclusive lease from `CanvasEditGate`. A lease carries an `AbortSignal`, has an explicit `isCurrent()` freshness check, and is idempotently released. Release, document/project invalidation, cooldown, or disposal aborts and stales the lease. Expected cancellation and stale results use status unions; exceptions represent unexpected failures.
+
+Staged-result acceptance is engine-owned. The UI enables Accept from interaction capabilities, but `StagedResultController` remains authoritative. It captures a document-edit permit, rejects an active gesture, and verifies the selected candidate's stable key immediately before dispatch.
+
+The initial `commitStagedImage` mutation atomically inserts the new raster layer, selects it, clears staging, and records the project event. The controller verifies both the reducer postcondition and the document mirror before pushing exactly one engine-history entry. It returns `busy`, `stale`, or `missing` without changing staging or history when any guard fails.
+
+Undo removes the accepted layer and restores the prior selection. Redo restores the identical layer and selection without recreating the event or staging candidate. The history entry uses failure-atomic replay, and a successful commit uses the normal history `push`, which clears any previous redo stack. Undo intentionally does not return the accepted candidate to staging.
+
+## PSD export
+
+PSD export is a planner/executor transaction over immutable snapshots. `PsdExportController` captures one `CanvasDocumentSnapshot`, plans exportable raster layers and their transformed world-space bounds, then obtains a `CanvasRasterSnapshot` including disabled layers. Execution reads only those detached surfaces; it cannot mix live layer caches from different document generations.
+
+The controller retains the 30,000-pixel side cap and also derives a pixel-area limit from currently available reserved bytes. It accounts for the flattened composite plus each transformed layer surface, budgets eight bytes per required pixel, and reserves the full execution allocation before creating PSD surfaces. A final freshness check occurs before that reservation; once execution starts it uses only frozen pixels. Capture and execution reservations are released in `finally`, and cancellation aborts before the next allocation or side effect.
+
+The capability returns `exported`, `nothing`, `too-large`, `not-ready`, `over-budget`, `stale`, or `aborted`. The layers widget awaits the promise and maps every non-success result to a user-visible notice.
+
+## Lifecycle
+
+Lifecycle states are `active`, `cooling`, `cool`, and `disposed`. Losing the final registry reference immediately detaches input/render targets, cancels background PSD work and rasterization, releases the old generation's reservations and pins, and starts a dirty-pixel flush. Successful, still-current flushes release reconstructible raster caches and trim history. Failed flushes retain dirty pixels and remain retryable; the registry retains the engine and retries after another grace period, disposing it only after a `cooled` result. Reacquisition increments the lifecycle generation so late flush or grace-period work cannot clean up or dispose a live engine. Operation-owned composite leases survive these generation transitions until their owning operation settles.
+
+Caller-owned `CanvasRasterSnapshot` objects are not reconstructible lifecycle caches. They remain usable through cooldown and continue to count against detached bytes until released. Final engine disposal force-releases them.
+
+## Browser acceptance
+
+Node and browser suites are separated by filename and config. `vitest.config.mts` excludes `*.browser.test.ts(x)`; `vitest.browser.config.mts` runs those files through `@vitest/browser-playwright` 4.1.9 in headless Chromium. `test:browser` runs the browser suite and `test:all` runs Node followed by browser tests. CI installs Chromium with `pnpm exec playwright install chromium` before the browser job.
+
+The real-Canvas2D suite verifies transformed composition, clipping, alpha and blend modes, browser text metrics, PNG blob encoding, `createImageBitmap` decoding, pixel undo/redo, and a small PSD write/read round trip. A React `StrictMode` harness verifies surface attachment, `ResizeObserver` sizing, detachment, registry cooldown/reacquisition, grace-period safety, and project switching.
+
+## Adding functionality
+
+- New tool: implement the tool interface under `tools/`, keep durable state in `CanvasProjectMutation`, and expose only required tool capability methods.
+- New derived effect: add a stable effect kind/parameter key, construct through `DerivedSurfaceCache`, and test warm hits, precise invalidation, stale source guards, culling, and byte accounting.
+- New layer operation: put pure pixel/document math in the core and orchestration in a controller; accept narrow ports, use project-bound mutations, reserve background allocations, and return status unions for expected no-op/stale cases.
+- New background raster workflow: capture a document snapshot, plan required layers, reserve and pin before allocation, detach immutable surfaces, release every lease in `finally`, and define whether edits after detachment are allowed.
+- New application coordinator: place it under `canvas-operations/`, acquire an edit lease, capture through narrow document/export capabilities, own its session store and cancellation, and publish through preview/layer capabilities.
+
+Deterministic CI assertions use operation counters and byte totals. Wall-clock timing is informational only.
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/api.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/api.ts
new file mode 100644
index 00000000000..0dd22b0ddf2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/api.ts
@@ -0,0 +1,211 @@
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type {
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasLayerContract,
+  CanvasStagingCandidateContract,
+  CanvasStateContractV2,
+} from '@workbench/types';
+
+import type { CanvasEditGate } from './editGate';
+import type { EngineStores } from './engineStores';
+import type { RasterCompositeExportRequest, RasterCompositeExportResult } from './exportRasterComposite';
+import type { RasterSurface } from './render/raster';
+import type { Rect, ToolId, Vec2 } from './types';
+import type { Viewport } from './viewport';
+
+/** Opaque snapshot identity carried through asynchronous layer operations. */
+export interface LayerExportGuard {
+  readonly projectId: string;
+  readonly layerId: string;
+  readonly layer: CanvasLayerContract;
+  readonly cacheVersion: number;
+  readonly documentGeneration: number;
+}
+
+export type CanvasCoreStores = EngineStores;
+
+export interface CanvasCoreStoreCapability {
+  readonly stores: CanvasCoreStores;
+}
+
+export interface CanvasSurfaceCapability {
+  attach(screenCanvas: HTMLCanvasElement, overlayCanvas: HTMLCanvasElement): void;
+  detach(): void;
+  resize(cssWidth: number, cssHeight: number, dpr: number): void;
+}
+
+export interface CanvasDocumentCapability {
+  captureSnapshot(): CanvasDocumentSnapshot | null;
+  getDocument(): CanvasDocumentContractV2 | null;
+}
+
+/** Immutable reducer canvas state captured at one engine document generation. */
+export interface CanvasDocumentSnapshot {
+  readonly canvas: CanvasStateContractV2;
+  readonly documentGeneration: number;
+}
+
+export interface CanvasDetachedLayerSurface {
+  readonly rect: Rect;
+  readonly surface: RasterSurface;
+}
+
+/** Caller-owned frozen pixels paired with the exact canvas contract that planned them. */
+export interface CanvasRasterSnapshot extends CanvasDocumentSnapshot {
+  /** Requested layers confirmed to have no current live or persisted pixels. */
+  readonly emptyLayerIds: ReadonlySet<string>;
+  readonly layerSurfaces: ReadonlyMap<string, CanvasDetachedLayerSurface>;
+  /** Idempotently releases all detached-pixel memory owned by this snapshot. */
+  release(): void;
+}
+
+export type CaptureRasterSnapshotResult =
+  | { status: 'ok'; snapshot: CanvasRasterSnapshot }
+  | { status: 'stale' | 'aborted' | 'not-ready' | 'over-budget' };
+
+export type PsdExportResult = 'exported' | 'nothing' | 'too-large' | 'not-ready' | 'over-budget' | 'stale' | 'aborted';
+
+export interface CanvasPsdExportCapability {
+  exportRasterLayersToPsd(fileName: string): Promise<PsdExportResult>;
+}
+
+export interface CanvasViewportCapability {
+  getViewport(): Viewport;
+  fitToView(): void;
+  setBboxGrid(size: number): void;
+}
+
+export interface CanvasToolCapability {
+  setTool(toolId: ToolId, options?: { temporary?: boolean }): void;
+  stepBrushSize(direction: 1 | -1): void;
+}
+
+export interface CanvasHistoryCapability {
+  undo(): void;
+  redo(): void;
+  clearHistory(): void;
+}
+
+export type LayerThumbnailRequestResult = 'ready' | 'stale' | 'error' | 'missing' | 'unsupported' | 'over-budget';
+
+export interface CanvasPreviewCapability {
+  drawLayerThumbnail(layerId: string, target: HTMLCanvasElement, maxSize: number): boolean;
+  requestLayerThumbnail(layerId: string): Promise<LayerThumbnailRequestResult>;
+}
+
+export interface CanvasExportCapability {
+  captureRasterSnapshot(
+    documentSnapshot: CanvasDocumentSnapshot,
+    layerIds: readonly string[],
+    options?: { signal?: AbortSignal; includeDisabled?: boolean }
+  ): Promise<CaptureRasterSnapshotResult>;
+  captureLayerExportGuard(layerId: string): LayerExportGuard | null;
+  exportBakedLayerBlob(layerId: string, options?: ExportBakedLayerPixelsOptions): Promise<ExportBakedLayerBlobResult>;
+  exportRasterComposite(request: RasterCompositeExportRequest): Promise<RasterCompositeExportResult>;
+  getCompositeExecutorDeps(): CanvasCompositeExecutorDeps;
+  hasExportableLayerContent(layerId: string): boolean;
+  isLayerExportGuardCurrent(guard: LayerExportGuard): boolean;
+}
+
+export type {
+  RasterCompositeExportRequest,
+  RasterCompositeExportResult,
+  RasterCompositeExportSnapshot,
+} from './exportRasterComposite';
+
+export interface ExportLayerPixelsOptions {
+  includeDisabled?: boolean;
+  applyAdjustments?: boolean;
+  signal?: AbortSignal;
+}
+
+export type ExportBakedLayerPixelsOptions = Omit<ExportLayerPixelsOptions, 'applyAdjustments'> & {
+  applyAdjustments?: boolean;
+};
+
+export type ExportBakedLayerBlobResult =
+  | { status: 'ok'; blob: Blob; rect: Rect; guard: LayerExportGuard }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' | 'aborted' };
+
+export interface CanvasCompositeExecutorDeps {
+  backend: {
+    createSurface(width: number, height: number): RasterSurface;
+    encodeSurface(surface: RasterSurface, type?: string): Promise<Blob>;
+  };
+  getLayerSurface(layerId: string): Promise<{ surface: RasterSurface; rect: Rect }>;
+  reserve?(
+    bytes: number
+  ):
+    | { status: 'ok'; lease: { release(): void } }
+    | { status: 'over-budget'; requestedBytes: number; availableBytes: number };
+  uploadImage(blob: Blob): Promise<{ imageName: string; width: number; height: number }>;
+}
+
+export interface CanvasSelectionCapability {
+  deselect(): void;
+  eraseSelection(): void;
+  fillSelection(): void;
+  getSelectionBounds(): Rect | null;
+  getSelectionMaskRect(): Rect | null;
+  invertSelection(): void;
+  replaceSelectionFromImage(
+    guard: LayerExportGuard,
+    image: CanvasImageRef,
+    rect: Rect,
+    signal?: AbortSignal
+  ): Promise<ReplaceSelectionFromImageResult>;
+  selectAll(): void;
+}
+
+export type ReplaceSelectionFromImageResult =
+  | { status: 'selected' }
+  | { status: 'aborted' | 'missing' | 'locked' | 'stale' | 'unsupported' | 'busy' }
+  | { status: 'failed'; message: string };
+
+export interface CanvasLayerCapability {
+  applyStructuralPreview(action: CanvasProjectMutation): boolean;
+  canCommitStructural(): boolean;
+  commitGeneratedImageResult(options: CommitGeneratedImageOptions): Promise<CommitGeneratedImageResult>;
+  commitStagedImage(options: CommitStagedImageOptions): CommitStagedImageResult;
+  commitStructural(label: string, forward: CanvasProjectMutation, inverse: CanvasProjectMutation): boolean;
+  invertMask(layerId: string): boolean;
+}
+
+export interface CommitStagedImageOptions {
+  candidate: CanvasStagingCandidateContract;
+  selectedImageIndex: number;
+}
+
+export type CommitStagedImageResult =
+  | { status: 'committed'; layerId: string }
+  | { status: 'busy' | 'stale' | 'missing' };
+
+export type GeneratedImageTarget = 'replace' | 'copy-raster' | 'copy-control';
+
+export interface CommitGeneratedImageOptions {
+  guard: LayerExportGuard;
+  image: CanvasImageRef;
+  origin: Vec2;
+  target: GeneratedImageTarget;
+  historyLabel?: string;
+  copyLayerName?: string;
+  signal?: AbortSignal;
+}
+
+export type CommitGeneratedImageResult =
+  | { status: 'committed'; layerId: string }
+  | { status: 'missing' | 'locked' | 'stale' | 'unsupported' | 'busy' | 'aborted' }
+  | { status: 'failed'; message: string };
+
+export type CanvasLifecycleState = 'active' | 'cooling' | 'cool' | 'disposed';
+
+export interface CanvasLifecycleCapability {
+  activate(): void;
+  beginCooldown(): Promise<'cooled' | 'dirty'>;
+  dispose(): void;
+  getLifecycleState(): CanvasLifecycleState;
+  flushPendingUploads(): Promise<void>;
+}
+
+export type CanvasEditCapability = CanvasEditGate;
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/applicationHost.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/applicationHost.ts
new file mode 100644
index 00000000000..b9b367e1700
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/applicationHost.ts
@@ -0,0 +1,85 @@
+import type {
+  CanvasCompositeExecutorDeps,
+  CommitGeneratedImageOptions,
+  CommitGeneratedImageResult,
+  ExportBakedLayerBlobResult,
+  ExportLayerPixelsOptions,
+  LayerExportGuard,
+  ReplaceSelectionFromImageResult,
+} from '@workbench/canvas-engine/api';
+import type {
+  CommitRasterFilterOptions,
+  CommitRasterFilterResult,
+} from '@workbench/canvas-engine/controllers/filterResultController';
+import type {
+  CommitMaskImageResult,
+  CommitMaskImageResultOptions,
+} from '@workbench/canvas-engine/controllers/maskResultController';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { SamInteractionState, SamVisualInput } from '@workbench/canvas-engine/samInteraction';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasImageRef } from '@workbench/types';
+
+export type SelectObjectStartContext =
+  | { status: 'missing' | 'disabled' | 'locked' | 'unsupported' | 'not-ready' }
+  | {
+      status: 'ready';
+      guard: LayerExportGuard;
+      layerId: string;
+      layerName: string;
+      layerType: 'raster' | 'control';
+      sourceRect: Rect;
+    };
+
+/** Narrow core primitives used only by application-level canvas coordinators. */
+export interface CanvasApplicationHost {
+  captureGuard(layerId: string): LayerExportGuard | null;
+  clearFilterPreview(layerId: string): void;
+  clearSamPreview(): void;
+  commitFilter(options: CommitRasterFilterOptions): Promise<CommitRasterFilterResult>;
+  commitGenerated(options: CommitGeneratedImageOptions): Promise<CommitGeneratedImageResult>;
+  commitMask(options: CommitMaskImageResultOptions): Promise<CommitMaskImageResult>;
+  decodeSelectObjectPreview(result: { image: CanvasImageRef; rect: Rect }, signal: AbortSignal): Promise<RasterSurface>;
+  encodeSurface(surface: RasterSurface): Promise<Blob>;
+  exportBakedLayerBlob(layerId: string): Promise<ExportBakedLayerBlobResult>;
+  exportLayerPixels(
+    layerId: string,
+    options?: ExportLayerPixelsOptions
+  ): Promise<
+    | { status: 'ok'; surface: RasterSurface; rect: Rect; guard: LayerExportGuard; release(): void }
+    | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' }
+  >;
+  getCompositeExecutorDeps(): CanvasCompositeExecutorDeps;
+  getDocument(): CanvasDocumentContractV2 | null;
+  isGuardCurrent(guard: LayerExportGuard): boolean;
+  isInteractionLocked(): boolean;
+  isSamToolActive(): boolean;
+  prepareSelectObjectStart(layerId: string): SelectObjectStartContext;
+  publishFilterPreview(
+    layerId: string,
+    imageName: string,
+    rect: Rect,
+    guard: LayerExportGuard,
+    filterType?: string
+  ): Promise<'shown' | 'missing' | 'stale'>;
+  publishSamPreview(preview: {
+    data: RasterSurface;
+    guard: LayerExportGuard;
+    isolated: boolean;
+    rect: Rect;
+  }): undefined;
+  replaceSelection(
+    guard: LayerExportGuard,
+    image: CanvasImageRef,
+    rect: Rect,
+    signal?: AbortSignal
+  ): Promise<ReplaceSelectionFromImageResult>;
+  replaceTemporaryRestoreTool(): void;
+  selectLayer(layerId: string): void;
+  setSamInputHandler(handler: ((input: SamVisualInput) => void) | null): void;
+  setEscapeHandler(handler: ((gestureWasActive: boolean) => boolean) | null): void;
+  setSamInteraction(state: SamInteractionState | null): void;
+  setSamTool(): void;
+  setViewTool(): void;
+  subscribeToolChanges(listener: (change: { from: string; to: string; temporary: boolean }) => void): () => void;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/browserRaster.browser.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/browserRaster.browser.test.ts
new file mode 100644
index 00000000000..d21ac5a5a55
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/browserRaster.browser.test.ts
@@ -0,0 +1,204 @@
+import type { Mat2d } from '@workbench/canvas-engine/types';
+import type {
+  CanvasDocumentContractV2,
+  CanvasLayerSourceContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { executePsdExport, planPsdExport } from '@workbench/canvas-engine/export/psdExport';
+import { createHistory } from '@workbench/canvas-engine/history/history';
+import { createImagePatchEntry } from '@workbench/canvas-engine/history/imagePatch';
+import { compositeDocument } from '@workbench/canvas-engine/render/compositor';
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createDomRasterBackend, type RasterSurface } from '@workbench/canvas-engine/render/raster';
+import { rasterizeTextSource } from '@workbench/canvas-engine/render/rasterizers/textRasterizer';
+import { describe, expect, it } from 'vitest';
+
+const IDENTITY: Mat2d = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+
+const readPixel = (surface: RasterSurface, x: number, y: number): number[] => [
+  ...surface.ctx.getImageData(x, y, 1, 1).data,
+];
+
+const expectPixel = (surface: RasterSurface, x: number, y: number, expected: number[], tolerance = 0): void => {
+  const actual = readPixel(surface, x, y);
+  expected.forEach((channel, index) => {
+    expect(actual[index]).toBeGreaterThanOrEqual(channel - tolerance);
+    expect(actual[index]).toBeLessThanOrEqual(channel + tolerance);
+  });
+};
+
+const rasterLayer = (
+  id: string,
+  overrides: Partial<CanvasRasterLayerContractV2> = {}
+): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: 8, imageName: id, width: 8 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+  ...overrides,
+});
+
+const documentWith = (layers: CanvasRasterLayerContractV2[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 8, width: 8, x: 0, y: 0 },
+  height: 8,
+  layers,
+  selectedLayerId: layers[0]?.id ?? null,
+  version: 2,
+  width: 8,
+});
+
+describe('real browser raster acceptance', () => {
+  it('composites transformed layers through clipping, alpha, and multiply blend mode', () => {
+    const backend = createDomRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const bottom = caches.getOrCreate('bottom', 8, 8);
+    bottom.surface.ctx.fillStyle = '#ff0000';
+    bottom.surface.ctx.fillRect(0, 0, 8, 8);
+    caches.publishPixels('bottom');
+
+    const top = caches.getOrCreate('top', 4, 8);
+    top.surface.ctx.fillStyle = '#0000ff';
+    top.surface.ctx.fillRect(0, 0, 4, 8);
+    caches.publishPixels('top');
+
+    const target = backend.createSurface(8, 8);
+    compositeDocument(
+      target,
+      documentWith([
+        rasterLayer('top', {
+          blendMode: 'multiply',
+          opacity: 0.5,
+          source: { image: { height: 8, imageName: 'top', width: 4 }, type: 'image' },
+          transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 2, y: 0 },
+        }),
+        rasterLayer('bottom'),
+      ]),
+      caches,
+      IDENTITY,
+      { clipRect: { height: 8, width: 4, x: 0, y: 0 } }
+    );
+
+    expectPixel(target, 1, 1, [255, 0, 0, 255]);
+    expectPixel(target, 3, 1, [127, 0, 0, 255], 2);
+    expectPixel(target, 5, 1, [0, 0, 0, 0]);
+  });
+
+  it('uses browser text metrics and produces real glyph pixels', async () => {
+    const backend = createDomRasterBackend();
+    const source: Extract<CanvasLayerSourceContract, { type: 'text' }> = {
+      align: 'left',
+      color: '#ff0000',
+      content: 'Invoke',
+      fontFamily: 'sans-serif',
+      fontSize: 24,
+      fontWeight: 400,
+      lineHeight: 1.2,
+      type: 'text',
+    };
+    const measureSurface = backend.createSurface(1, 1);
+    measureSurface.ctx.font = '400 24px sans-serif';
+    const browserWidth = Math.ceil(measureSurface.ctx.measureText(source.content).width);
+
+    const result = await rasterizeTextSource(source, {
+      backend,
+      documentSize: { height: 64, width: 64 },
+      resolver: () => Promise.resolve(new Blob()),
+      store: createLayerCacheStore(backend),
+    });
+    const pixels = result.surface.ctx.getImageData(0, 0, result.surface.width, result.surface.height).data;
+
+    expect(result.rect.width).toBe(browserWidth);
+    expect(result.rect.height).toBe(Math.ceil(24 * 1.2));
+    expect(pixels.some((channel, index) => index % 4 === 3 && channel > 0)).toBe(true);
+  });
+
+  it('encodes a PNG blob and decodes it through createImageBitmap', async () => {
+    const backend = createDomRasterBackend();
+    const source = backend.createSurface(3, 2);
+    source.ctx.fillStyle = '#00ff00';
+    source.ctx.fillRect(0, 0, 3, 2);
+
+    const blob = await backend.encodeSurface(source);
+    const bitmap = await backend.createImageBitmap(blob);
+    const decoded = backend.createSurface(3, 2);
+    decoded.ctx.drawImage(bitmap, 0, 0);
+
+    expect(blob.type).toBe('image/png');
+    expect(blob.size).toBeGreaterThan(0);
+    expect(bitmap.width).toBe(3);
+    expect(bitmap.height).toBe(2);
+    expectPixel(decoded, 1, 1, [0, 255, 0, 255]);
+    bitmap.close();
+  });
+
+  it('undoes and redoes a real pixel patch', () => {
+    const backend = createDomRasterBackend();
+    const surface = backend.createSurface(1, 1);
+    const before = new ImageData(new Uint8ClampedArray([255, 0, 0, 255]), 1, 1);
+    const after = new ImageData(new Uint8ClampedArray([0, 0, 255, 255]), 1, 1);
+    const history = createHistory();
+    surface.ctx.putImageData(after, 0, 0);
+    history.push(
+      createImagePatchEntry({
+        after,
+        apply: (_layerId, rect, pixels) => surface.ctx.putImageData(pixels, rect.x, rect.y),
+        before,
+        label: 'Browser pixel edit',
+        layerId: 'paint',
+        rect: { height: 1, width: 1, x: 0, y: 0 },
+      })
+    );
+
+    history.undo();
+    expectPixel(surface, 0, 0, [255, 0, 0, 255]);
+    history.redo();
+    expectPixel(surface, 0, 0, [0, 0, 255, 255]);
+  });
+
+  it('round-trips a small real PSD with layer and composite pixels', async () => {
+    const backend = createDomRasterBackend();
+    const layerSurface = backend.createSurface(2, 2);
+    layerSurface.ctx.fillStyle = '#ff0000';
+    layerSurface.ctx.fillRect(0, 0, 2, 2);
+    const plan = planPsdExport([
+      {
+        blendMode: 'normal',
+        contentRect: { height: 2, width: 2, x: 0, y: 0 },
+        id: 'red',
+        isEnabled: true,
+        name: 'Red',
+        opacity: 1,
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      },
+    ]);
+    let bytes: ArrayBuffer | null = null;
+
+    await executePsdExport(plan, 'acceptance.psd', {
+      backend,
+      download: (data) => {
+        bytes = data;
+      },
+      getLayerSurface: () =>
+        Promise.resolve({
+          rect: { height: 2, width: 2, x: 0, y: 0 },
+          surface: layerSurface,
+        }),
+    });
+
+    expect(bytes).not.toBeNull();
+    const { readPsd } = await import('ag-psd');
+    const parsed = readPsd(bytes!, { useImageData: true });
+    expect(parsed.width).toBe(2);
+    expect(parsed.height).toBe(2);
+    expect(parsed.children?.map((child) => child.name)).toEqual(['Red']);
+    expect(Array.from(parsed.imageData!.data.slice(0, 4))).toEqual([255, 0, 0, 255]);
+    expect(Array.from(parsed.children![0]!.imageData!.data.slice(0, 4))).toEqual([255, 0, 0, 255]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/color.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/color.test.ts
new file mode 100644
index 00000000000..999eb3c030f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/color.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { rgbaToHex } from './color';
+
+describe('rgbaToHex', () => {
+  it('formats channels as a lowercase #rrggbb string', () => {
+    expect(rgbaToHex(0, 0, 0)).toBe('#000000');
+    expect(rgbaToHex(255, 255, 255)).toBe('#ffffff');
+    expect(rgbaToHex(255, 0, 0)).toBe('#ff0000');
+    expect(rgbaToHex(18, 52, 86)).toBe('#123456');
+  });
+
+  it('pads single-digit hex bytes with a leading zero', () => {
+    expect(rgbaToHex(1, 2, 3)).toBe('#010203');
+  });
+
+  it('rounds fractional channels to the nearest integer', () => {
+    expect(rgbaToHex(127.6, 127.4, 0)).toBe('#807f00');
+  });
+
+  it('clamps out-of-range channels to [0, 255]', () => {
+    expect(rgbaToHex(-10, 300, 128)).toBe('#00ff80');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/color.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/color.ts
new file mode 100644
index 00000000000..8ddef1befc8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/color.ts
@@ -0,0 +1,18 @@
+/**
+ * Small pure color helpers shared by the engine. Zero React, zero import-time
+ * side effects.
+ */
+
+/** Clamps a color channel to the `[0, 255]` byte range, rounding to the nearest integer. */
+const clampChannel = (value: number): number => Math.max(0, Math.min(255, Math.round(value)));
+
+const toHexByte = (value: number): string => clampChannel(value).toString(16).padStart(2, '0');
+
+/**
+ * Formats an opaque color as a lowercase `#rrggbb` CSS hex string. Channels are
+ * `[0, 255]`; alpha is intentionally not part of the output — brush/eraser
+ * options store an opaque fill color, and the color picker's own transparency
+ * check (`sampleDocumentColor` returning `null`) already decides whether a
+ * sample is pickable at all.
+ */
+export const rgbaToHex = (r: number, g: number, b: number): string => `#${toHexByte(r)}${toHexByte(g)}${toHexByte(b)}`;
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/booleanMergeController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/booleanMergeController.ts
new file mode 100644
index 00000000000..19ce862c53f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/booleanMergeController.ts
@@ -0,0 +1,212 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { isMergeableRasterLayer } from '@workbench/canvas-engine/document/sources';
+import { isEmpty, roundOut, union } from '@workbench/canvas-engine/math/rect';
+
+export type BooleanRasterOperation = 'intersect' | 'cutout' | 'cutaway' | 'exclude';
+export type BooleanRasterResult = 'merged' | 'missing' | 'unsupported' | 'not-ready' | 'busy' | 'empty';
+
+type ExportResult =
+  | { status: 'ok'; surface: RasterSurface; rect: Rect; guard: LayerExportGuard; release(): void }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' };
+
+export interface BooleanMergeControllerOptions {
+  readonly backend: RasterBackend;
+  readonly history: History;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly capturePermit: () => object | null;
+  readonly isPermitCurrent: (permit: object) => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly endBurst: () => void;
+  readonly isCacheReady: (layer: CanvasLayerContract, document: CanvasDocumentContractV2) => boolean;
+  readonly exportBaked: (layerId: string) => Promise<ExportResult>;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly createLayerId: () => string;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    expectedReducer: () => boolean,
+    expectedMirror: () => boolean
+  ) => void;
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => unknown;
+  readonly installPrepared: (prepared: unknown) => void;
+}
+
+const modes: Record<BooleanRasterOperation, GlobalCompositeOperation> = {
+  cutaway: 'source-out',
+  cutout: 'destination-in',
+  exclude: 'xor',
+  intersect: 'source-in',
+};
+
+/** Owns guarded two-layer boolean compositing and atomic stack history. */
+export class BooleanMergeController {
+  private disposed = false;
+
+  constructor(private readonly deps: BooleanMergeControllerOptions) {}
+
+  async merge(upperLayerId: string, operation: BooleanRasterOperation): Promise<BooleanRasterResult> {
+    const permit = this.deps.capturePermit();
+    if (this.disposed || !permit || this.deps.isGestureActive()) {
+      return 'busy';
+    }
+    this.deps.endBurst();
+    const document = this.deps.getDocument();
+    if (!document) {
+      return 'missing';
+    }
+    const upperIndex = document.layers.findIndex((layer) => layer.id === upperLayerId);
+    const upper = document.layers[upperIndex];
+    const below = document.layers[upperIndex + 1];
+    if (upperIndex < 0 || !upper || !below) {
+      return 'missing';
+    }
+    if (!isMergeableRasterLayer(upper) || !isMergeableRasterLayer(below)) {
+      return 'unsupported';
+    }
+    if (!this.deps.isCacheReady(upper, document) || !this.deps.isCacheReady(below, document)) {
+      return 'not-ready';
+    }
+    const owned: Extract<ExportResult, { status: 'ok' }>[] = [];
+    const acquire = async (layerId: string): Promise<ExportResult> => {
+      const result = await this.deps.exportBaked(layerId);
+      if (result.status === 'ok') {
+        owned.push(result);
+      }
+      return result;
+    };
+    try {
+      const settled = await Promise.allSettled([acquire(upper.id), acquire(below.id)]);
+      const rejected = settled.find((result) => result.status === 'rejected');
+      if (rejected?.status === 'rejected') {
+        throw rejected.reason instanceof Error ? rejected.reason : new Error(String(rejected.reason));
+      }
+      const [upperPixels, belowPixels] = settled.map(
+        (result) => (result as PromiseFulfilledResult<ExportResult>).value
+      );
+      if (!this.deps.isPermitCurrent(permit)) {
+        return 'busy';
+      }
+      if (upperPixels.status !== 'ok' || belowPixels.status !== 'ok') {
+        if (upperPixels.status === 'not-ready' || belowPixels.status === 'not-ready') {
+          return 'not-ready';
+        }
+        if (
+          upperPixels.status === 'disabled' ||
+          upperPixels.status === 'unsupported' ||
+          belowPixels.status === 'disabled' ||
+          belowPixels.status === 'unsupported'
+        ) {
+          return 'unsupported';
+        }
+        return 'empty';
+      }
+      if (
+        !this.deps.isPermitCurrent(permit) ||
+        this.deps.isGestureActive() ||
+        upperPixels.guard.layer !== upper ||
+        belowPixels.guard.layer !== below ||
+        !this.deps.isGuardCurrent(upperPixels.guard) ||
+        !this.deps.isGuardCurrent(belowPixels.guard)
+      ) {
+        return this.deps.isPermitCurrent(permit) ? 'not-ready' : 'busy';
+      }
+      const liveDocument = this.deps.getDocument();
+      const liveIndex = liveDocument?.layers.findIndex((layer) => layer.id === upperLayerId) ?? -1;
+      if (!liveDocument || liveDocument.layers[liveIndex] !== upper || liveDocument.layers[liveIndex + 1] !== below) {
+        return 'not-ready';
+      }
+      const resultRect = roundOut(union(upperPixels.rect, belowPixels.rect));
+      if (isEmpty(resultRect)) {
+        return 'empty';
+      }
+      const pixels = this.deps.backend.createSurface(resultRect.width, resultRect.height);
+      pixels.ctx.setTransform(1, 0, 0, 1, 0, 0);
+      pixels.ctx.clearRect(0, 0, resultRect.width, resultRect.height);
+      pixels.ctx.globalAlpha = below.opacity;
+      pixels.ctx.globalCompositeOperation = 'source-over';
+      pixels.ctx.drawImage(
+        belowPixels.surface.canvas,
+        belowPixels.rect.x - resultRect.x,
+        belowPixels.rect.y - resultRect.y
+      );
+      pixels.ctx.globalAlpha = upper.opacity;
+      pixels.ctx.globalCompositeOperation = modes[operation];
+      pixels.ctx.drawImage(
+        upperPixels.surface.canvas,
+        upperPixels.rect.x - resultRect.x,
+        upperPixels.rect.y - resultRect.y
+      );
+      const resultId = this.deps.createLayerId();
+      const resultLayer: CanvasLayerContract = {
+        blendMode: 'normal',
+        id: resultId,
+        isEnabled: true,
+        isLocked: false,
+        name: `${upper.name} ${operation}`,
+        opacity: 1,
+        source: { bitmap: null, offset: { x: resultRect.x, y: resultRect.y }, type: 'paint' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        type: 'raster',
+      };
+      const original = [
+        { id: upper.id, isEnabled: upper.isEnabled },
+        { id: below.id, isEnabled: below.isEnabled },
+      ];
+      const disabled = original.map(({ id }) => ({ id, isEnabled: false }));
+      const selectedLayerId = liveDocument.selectedLayerId;
+      const hasState = (doc: CanvasDocumentContractV2 | null, updates: typeof original): boolean =>
+        updates.every((update) => doc?.layers.find((layer) => layer.id === update.id)?.isEnabled === update.isEnabled);
+      const apply = (): void => {
+        const prepared = this.deps.preparePixels(resultId, resultRect, pixels);
+        this.deps.dispatchPrepared(
+          {
+            add: { index: liveIndex, layers: [resultLayer] },
+            enabledUpdates: disabled,
+            selectedLayerId: resultId,
+            type: 'applyCanvasLayerStackMutation',
+          },
+          () =>
+            this.deps.getReducerDocument()?.selectedLayerId === resultId &&
+            hasState(this.deps.getReducerDocument(), disabled),
+          () => this.deps.getDocument()?.selectedLayerId === resultId && hasState(this.deps.getDocument(), disabled)
+        );
+        this.deps.installPrepared(prepared);
+      };
+      if (!this.deps.isPermitCurrent(permit)) {
+        return 'busy';
+      }
+      apply();
+      this.deps.history.push({
+        bytes: resultRect.width * resultRect.height * 4 + 256,
+        label: `Boolean ${operation}`,
+        redo: apply,
+        replayFailureAtomic: true,
+        undo: () =>
+          this.deps.dispatchPrepared(
+            { enabledUpdates: original, removeIds: [resultId], selectedLayerId, type: 'applyCanvasLayerStackMutation' },
+            () =>
+              this.deps.getReducerDocument()?.selectedLayerId === selectedLayerId &&
+              hasState(this.deps.getReducerDocument(), original),
+            () =>
+              this.deps.getDocument()?.selectedLayerId === selectedLayerId &&
+              hasState(this.deps.getDocument(), original)
+          ),
+      });
+      return 'merged';
+    } finally {
+      for (const result of owned) {
+        result.release();
+      }
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/controlPixelController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/controlPixelController.test.ts
new file mode 100644
index 00000000000..63ab0c6ac80
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/controlPixelController.test.ts
@@ -0,0 +1,36 @@
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ControlPixelController } from './controlPixelController';
+
+describe('ControlPixelController', () => {
+  it('can be instantiated with narrow fakes and rejects edits without a document', () => {
+    const controller = new ControlPixelController({
+      applyImagePatch: vi.fn(),
+      backend: createTestStubRasterBackend(),
+      bitmapStore: { discardLayer: vi.fn(), markLayerDirty: vi.fn(), suspendLayer: vi.fn() } as never,
+      canEdit: () => true,
+      deleteDerived: vi.fn(),
+      dispatchReplacement: vi.fn(),
+      endBurst: vi.fn(),
+      getActiveProjectId: () => 'project-1',
+      getDocument: () => null,
+      getTransformSession: () => null,
+      history: {} as never,
+      installPrepared: vi.fn(),
+      invalidate: vi.fn(),
+      isCacheReady: () => false,
+      isOperationIdle: () => true,
+      layers: {} as never,
+      notifyPainted: vi.fn(),
+      preparePixels: vi.fn(),
+      projectId: 'project-1',
+      publishStroke: vi.fn(),
+      setTransformOverride: vi.fn(),
+    });
+
+    expect(controller.begin('control-1')).toBeNull();
+    expect(controller.isOpenFor(['control-1'])).toBe(false);
+    expect(() => controller.dispose()).not.toThrow();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/controlPixelController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/controlPixelController.ts
new file mode 100644
index 00000000000..329da8ee448
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/controlPixelController.ts
@@ -0,0 +1,439 @@
+import type { BitmapStore } from '@workbench/canvas-engine/document/bitmapStore';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { ImagePatchApply } from '@workbench/canvas-engine/history/imagePatch';
+import type { LayerPixelSnapshot, LayerPixelSnapshotApply } from '@workbench/canvas-engine/history/layerSnapshot';
+import type { LayerCacheStore, PreparedLayerCacheReplacement } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend } from '@workbench/canvas-engine/render/raster';
+import type {
+  ControlPixelEditTransaction,
+  PixelEditPatch,
+  StrokeCommittedEvent,
+} from '@workbench/canvas-engine/tools/tool';
+import type { LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasControlLayerContract, CanvasDocumentContractV2 } from '@workbench/types';
+
+import { getSourceContentRect } from '@workbench/canvas-engine/document/sources';
+import {
+  bakeControlPixelEditSurface,
+  buildMaterializedControlLayer,
+  decideControlPixelEdit,
+} from '@workbench/canvas-engine/editing/controlPixelEdit';
+import { createImagePatchEntry } from '@workbench/canvas-engine/history/imagePatch';
+import { createLayerSnapshotEntry } from '@workbench/canvas-engine/history/layerSnapshot';
+import { isEmpty } from '@workbench/canvas-engine/math/rect';
+
+export interface ControlPixelControllerOptions {
+  readonly applyImagePatch: ImagePatchApply;
+  readonly backend: RasterBackend;
+  readonly bitmapStore: Pick<BitmapStore, 'discardLayer' | 'markLayerDirty' | 'suspendLayer'>;
+  readonly canEdit: () => boolean;
+  readonly deleteDerived: (layerId: string) => void;
+  readonly dispatchReplacement: (layer: CanvasControlLayerContract) => void;
+  readonly endBurst: () => void;
+  readonly getActiveProjectId: () => string | null;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getTransformSession: () => unknown;
+  readonly history: History;
+  readonly installPrepared: (prepared: PreparedLayerCacheReplacement, persist?: boolean) => void;
+  readonly invalidate: (layerId: string, overlay?: boolean) => void;
+  readonly isCacheReady: (layer: CanvasControlLayerContract, document: CanvasDocumentContractV2) => boolean;
+  readonly isOperationIdle: () => boolean;
+  readonly layers: LayerCacheStore;
+  readonly notifyPainted: (layerId: string) => void;
+  readonly preparePixels: (
+    layerId: string,
+    rect: Rect,
+    pixels: ReturnType<RasterBackend['createSurface']>
+  ) => PreparedLayerCacheReplacement;
+  readonly projectId: string;
+  readonly publishStroke: (event: StrokeCommittedEvent) => void;
+  readonly setTransformOverride: (layerId: string, transform: LayerTransform | null) => void;
+}
+
+const isImageDataEqual = (left: ImageData, right: ImageData): boolean => {
+  if (left.width !== right.width || left.height !== right.height || left.data.length !== right.data.length) {
+    return false;
+  }
+  for (let index = 0; index < left.data.length; index += 1) {
+    if (left.data[index] !== right.data[index]) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/** Owns the exclusive direct/materialized control-layer pixel transaction. */
+export class ControlPixelController {
+  private open: { cancel: () => void; layerId: string } | null = null;
+
+  constructor(private readonly options: ControlPixelControllerOptions) {}
+
+  cancel(): void {
+    this.open?.cancel();
+  }
+
+  isOpenFor(layerIds: readonly string[]): boolean {
+    return this.open !== null && layerIds.includes(this.open.layerId);
+  }
+
+  private applySnapshot: LayerPixelSnapshotApply = (snapshot) => {
+    const pixels = this.options.backend.createSurface(snapshot.rect.width, snapshot.rect.height);
+    if (snapshot.pixels) {
+      pixels.ctx.putImageData(snapshot.pixels, 0, 0);
+    }
+    const prepared = this.options.preparePixels(snapshot.layer.id, snapshot.rect, pixels);
+    this.options.dispatchReplacement(snapshot.layer);
+    try {
+      this.options.bitmapStore.discardLayer(snapshot.layer.id);
+    } catch {
+      // Persistence bookkeeping is ancillary after reducer acceptance.
+    }
+    this.options.installPrepared(prepared, snapshot.layer.source.type === 'paint');
+  };
+
+  begin(layerId: string): ControlPixelEditTransaction | null {
+    const o = this.options;
+    const document = o.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (
+      !o.canEdit() ||
+      !document ||
+      document.selectedLayerId !== layerId ||
+      !layer ||
+      layer.type !== 'control' ||
+      this.open ||
+      !o.isOperationIdle() ||
+      o.getTransformSession()
+    ) {
+      return null;
+    }
+    const contentRect = getSourceContentRect(layer, document);
+    const decision = decideControlPixelEdit({
+      hasSourceContent: !isEmpty(contentRect),
+      isCacheReady: o.isCacheReady(layer, document),
+      layer,
+    });
+    if (decision.status === 'rejected') {
+      return null;
+    }
+    if (decision.status === 'direct') {
+      return this.beginDirect(layerId, layer);
+    }
+    return this.beginMaterialized(layerId, layer, contentRect);
+  }
+
+  private beginDirect(layerId: string, layer: CanvasControlLayerContract): ControlPixelEditTransaction | null {
+    const o = this.options;
+    const originalEntry = o.layers.get(layerId);
+    let originalPixels: ImageData | null = null;
+    if (originalEntry && !isEmpty(originalEntry.rect)) {
+      try {
+        originalPixels = originalEntry.surface.ctx.getImageData(
+          0,
+          0,
+          originalEntry.rect.width,
+          originalEntry.rect.height
+        );
+      } catch {
+        return null;
+      }
+    }
+    const original = originalEntry
+      ? {
+          hasPublishedPixels: originalEntry.hasPublishedPixels,
+          lastUsed: originalEntry.lastUsed,
+          pixels: originalPixels,
+          rect: { ...originalEntry.rect },
+          stale: originalEntry.stale,
+          surface: originalEntry.surface,
+          version: originalEntry.version,
+        }
+      : null;
+    const releasePersistence = o.bitmapStore.suspendLayer(layerId);
+    let closed = false;
+    let owner: { cancel: () => void; layerId: string };
+    const close = (): boolean => {
+      if (closed || this.open !== owner) {
+        return false;
+      }
+      closed = true;
+      this.open = null;
+      return true;
+    };
+    const restore = (): void => {
+      try {
+        if (!original) {
+          o.layers.delete(layerId);
+        } else {
+          original.surface.resize(original.rect.width, original.rect.height);
+          if (original.pixels) {
+            original.surface.ctx.putImageData(original.pixels, 0, 0);
+          }
+          const current = o.layers.get(layerId) ?? o.layers.getOrCreateRect(layerId, original.rect);
+          Object.assign(current, {
+            hasPublishedPixels: original.hasPublishedPixels,
+            lastUsed: original.lastUsed,
+            rect: { ...original.rect },
+            stale: original.stale,
+            surface: original.surface,
+            version: original.version,
+          });
+        }
+      } finally {
+        o.deleteDerived(layerId);
+        o.invalidate(layerId);
+      }
+    };
+    const restoreAndRelease = (): void => {
+      try {
+        restore();
+      } finally {
+        releasePersistence();
+      }
+    };
+    const cancel = (): void => {
+      if (close()) {
+        restoreAndRelease();
+      }
+    };
+    const commitPatch = (label: string, patch: PixelEditPatch): boolean => {
+      if (closed || this.open !== owner) {
+        return false;
+      }
+      if (isImageDataEqual(patch.before, patch.after)) {
+        cancel();
+        return false;
+      }
+      const document = o.getDocument();
+      if (
+        o.getActiveProjectId() !== o.projectId ||
+        !o.canEdit() ||
+        !o.isOperationIdle() ||
+        document?.selectedLayerId !== layerId ||
+        document.layers.find((candidate) => candidate.id === layerId) !== layer
+      ) {
+        cancel();
+        return false;
+      }
+      close();
+      let entry = null;
+      try {
+        if (!o.history.isApplying()) {
+          entry = createImagePatchEntry({
+            after: patch.after,
+            apply: o.applyImagePatch,
+            before: patch.before,
+            label,
+            layerId,
+            rect: patch.rect,
+          });
+        }
+      } catch (error) {
+        restoreAndRelease();
+        throw error;
+      }
+      o.endBurst();
+      try {
+        if (entry) {
+          o.history.push(entry);
+        }
+        o.notifyPainted(layerId);
+        o.bitmapStore.markLayerDirty(layerId);
+      } finally {
+        releasePersistence();
+      }
+      return true;
+    };
+    const transaction: ControlPixelEditTransaction = {
+      cancel,
+      commitPatch: (label, patch) => void commitPatch(label, patch),
+      commitStroke: (event) => {
+        if (event.layerId !== layerId) {
+          cancel();
+          return;
+        }
+        if (
+          commitPatch(event.tool === 'eraser' ? 'Eraser stroke' : 'Brush stroke', {
+            after: event.afterImageData,
+            before: event.beforeImageData,
+            rect: event.dirtyRect,
+          })
+        ) {
+          o.publishStroke(event);
+        }
+      },
+      layerId,
+    };
+    owner = { cancel, layerId };
+    this.open = owner;
+    return transaction;
+  }
+
+  private beginMaterialized(
+    layerId: string,
+    layer: CanvasControlLayerContract,
+    contentRect: Rect
+  ): ControlPixelEditTransaction | null {
+    const o = this.options;
+    const originalEntry = o.layers.get(layerId);
+    const original = originalEntry
+      ? {
+          hasPublishedPixels: originalEntry.hasPublishedPixels,
+          lastUsed: originalEntry.lastUsed,
+          rect: { ...originalEntry.rect },
+          stale: originalEntry.stale,
+          surface: originalEntry.surface,
+          version: originalEntry.version,
+        }
+      : null;
+    const beforeRect = original?.rect ?? { ...contentRect };
+    let beforePixels: ImageData | null = null;
+    if (!isEmpty(beforeRect)) {
+      if (!originalEntry) {
+        return null;
+      }
+      try {
+        beforePixels = originalEntry.surface.ctx.getImageData(0, 0, beforeRect.width, beforeRect.height);
+      } catch {
+        return null;
+      }
+    }
+    let prepared: PreparedLayerCacheReplacement;
+    try {
+      if (originalEntry && !isEmpty(originalEntry.rect)) {
+        const baked = bakeControlPixelEditSurface({
+          backend: o.backend,
+          source: originalEntry.surface,
+          sourceRect: originalEntry.rect,
+          transform: layer.transform,
+        });
+        prepared = o.preparePixels(layerId, baked.rect, baked.surface);
+      } else {
+        prepared = o.preparePixels(layerId, { height: 0, width: 0, x: 0, y: 0 }, o.backend.createSurface(0, 0));
+      }
+    } catch {
+      return null;
+    }
+    const before: LayerPixelSnapshot = { layer: structuredClone(layer), pixels: beforePixels, rect: beforeRect };
+    const restore = (): void => {
+      try {
+        if (original) {
+          const current = o.layers.get(layerId);
+          if (current) {
+            Object.assign(current, { ...original, rect: { ...original.rect } });
+          }
+        } else {
+          o.layers.delete(layerId);
+        }
+      } finally {
+        o.deleteDerived(layerId);
+        o.setTransformOverride(layerId, null);
+        o.invalidate(layerId, true);
+      }
+    };
+    const releasePersistence = o.bitmapStore.suspendLayer(layerId);
+    const restoreAndRelease = (): void => {
+      try {
+        restore();
+      } finally {
+        releasePersistence();
+      }
+    };
+    try {
+      const preview = originalEntry ?? o.layers.getOrCreateRect(layerId, prepared.rect);
+      Object.assign(preview, {
+        surface: prepared.surface,
+        rect: { ...prepared.rect },
+        hasPublishedPixels: true,
+        stale: false,
+      });
+      preview.version += 1;
+      o.deleteDerived(layerId);
+      o.setTransformOverride(layerId, { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+      o.invalidate(layerId, true);
+    } catch {
+      restoreAndRelease();
+      return null;
+    }
+    let closed = false;
+    let owner: { cancel: () => void; layerId: string };
+    const close = (): boolean => {
+      if (closed || this.open !== owner) {
+        return false;
+      }
+      closed = true;
+      this.open = null;
+      return true;
+    };
+    const cancel = (): void => {
+      if (close()) {
+        restoreAndRelease();
+      }
+    };
+    const commit = (label: string, event?: StrokeCommittedEvent): void => {
+      if (!close()) {
+        return;
+      }
+      const document = o.getDocument();
+      const edited = o.layers.get(layerId);
+      if (
+        o.getActiveProjectId() !== o.projectId ||
+        !o.canEdit() ||
+        !o.isOperationIdle() ||
+        document?.selectedLayerId !== layerId ||
+        document.layers.find((candidate) => candidate.id === layerId) !== layer ||
+        !edited ||
+        (event && event.layerId !== layerId)
+      ) {
+        restoreAndRelease();
+        return;
+      }
+      let entry = null;
+      try {
+        const pixels = isEmpty(edited.rect)
+          ? null
+          : edited.surface.ctx.getImageData(0, 0, edited.rect.width, edited.rect.height);
+        const materialized = buildMaterializedControlLayer(layer, edited.rect);
+        const after: LayerPixelSnapshot = { layer: materialized, pixels, rect: { ...edited.rect } };
+        if (!o.history.isApplying()) {
+          entry = createLayerSnapshotEntry({ after, apply: this.applySnapshot, before, label });
+        }
+        o.dispatchReplacement(materialized);
+      } catch (error) {
+        restoreAndRelease();
+        throw error;
+      }
+      o.setTransformOverride(layerId, null);
+      o.endBurst();
+      try {
+        if (entry) {
+          o.history.push(entry);
+        }
+        o.notifyPainted(layerId);
+        o.bitmapStore.markLayerDirty(layerId);
+      } finally {
+        releasePersistence();
+      }
+      if (event) {
+        o.publishStroke(event);
+      }
+    };
+    const transaction: ControlPixelEditTransaction = {
+      cancel,
+      commitPatch: (label, patch) => (isImageDataEqual(patch.before, patch.after) ? cancel() : commit(label)),
+      commitStroke: (event) =>
+        isImageDataEqual(event.beforeImageData, event.afterImageData)
+          ? cancel()
+          : commit(event.tool === 'eraser' ? 'Eraser stroke' : 'Brush stroke', event),
+      layerId,
+    };
+    owner = { cancel, layerId };
+    this.open = owner;
+    return transaction;
+  }
+
+  dispose(): void {
+    this.cancel();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/copyLayerController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/copyLayerController.ts
new file mode 100644
index 00000000000..1601911e9ea
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/copyLayerController.ts
@@ -0,0 +1,124 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+type ExportResult =
+  | { status: 'ok'; surface: RasterSurface; rect: Rect; guard: LayerExportGuard; release(): void }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' };
+
+export interface CopyLayerControllerOptions {
+  readonly history: History;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly capturePermit: () => object | null;
+  readonly isPermitCurrent: (permit: object) => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly endBurst: () => void;
+  readonly exportBaked: (layerId: string) => Promise<ExportResult>;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly createLayerId: () => string;
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => unknown;
+  readonly installPrepared: (prepared: unknown) => void;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    expectedReducer: () => boolean,
+    expectedMirror: () => boolean
+  ) => void;
+}
+
+/** Owns guarded baked copies into new raster paint layers. */
+export class CopyLayerController {
+  private disposed = false;
+  constructor(private readonly deps: CopyLayerControllerOptions) {}
+
+  async copyToRaster(layerId: string): Promise<string | null> {
+    const permit = this.deps.capturePermit();
+    if (this.disposed || !permit || this.deps.isGestureActive()) {
+      return null;
+    }
+    this.deps.endBurst();
+    const document = this.deps.getDocument();
+    const sourceLayer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !sourceLayer) {
+      return null;
+    }
+    const baked = await this.deps.exportBaked(layerId);
+    if (baked.status !== 'ok') {
+      return null;
+    }
+    try {
+      if (!this.deps.isPermitCurrent(permit)) {
+        return null;
+      }
+      if (this.deps.isGestureActive() || !this.deps.isGuardCurrent(baked.guard) || baked.guard.layer !== sourceLayer) {
+        return null;
+      }
+      const liveDocument = this.deps.getDocument();
+      const sourceIndex = liveDocument?.layers.findIndex((layer) => layer.id === layerId) ?? -1;
+      if (!liveDocument || liveDocument.layers[sourceIndex] !== sourceLayer || sourceIndex < 0) {
+        return null;
+      }
+      const newId = this.deps.createLayerId();
+      const layer: CanvasLayerContract = {
+        blendMode: 'normal',
+        id: newId,
+        isEnabled: true,
+        isLocked: false,
+        name: `${sourceLayer.name} copy`,
+        opacity: 1,
+        source: { bitmap: null, offset: { x: baked.rect.x, y: baked.rect.y }, type: 'paint' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        type: 'raster',
+      };
+      const selectedLayerId = liveDocument.selectedLayerId;
+      const apply = (): void => {
+        const prepared = this.deps.preparePixels(newId, baked.rect, baked.surface);
+        this.deps.dispatchPrepared(
+          {
+            add: { index: sourceIndex, layers: [layer] },
+            enabledUpdates: [],
+            selectedLayerId: newId,
+            type: 'applyCanvasLayerStackMutation',
+          },
+          () =>
+            this.deps.getReducerDocument()?.selectedLayerId === newId &&
+            this.deps.getReducerDocument()?.layers.some((candidate) => candidate === layer) === true,
+          () =>
+            this.deps.getDocument()?.selectedLayerId === newId &&
+            this.deps.getDocument()?.layers.some((candidate) => candidate === layer) === true
+        );
+        this.deps.installPrepared(prepared);
+      };
+      if (!this.deps.isPermitCurrent(permit)) {
+        return null;
+      }
+      apply();
+      this.deps.history.push({
+        bytes: baked.rect.width * baked.rect.height * 4 + 256,
+        label: 'Copy layer to raster',
+        redo: apply,
+        replayFailureAtomic: true,
+        undo: () =>
+          this.deps.dispatchPrepared(
+            { enabledUpdates: [], removeIds: [newId], selectedLayerId, type: 'applyCanvasLayerStackMutation' },
+            () =>
+              this.deps.getReducerDocument()?.selectedLayerId === selectedLayerId &&
+              this.deps.getReducerDocument()?.layers.some((candidate) => candidate.id === newId) === false,
+            () =>
+              this.deps.getDocument()?.selectedLayerId === selectedLayerId &&
+              this.deps.getDocument()?.layers.some((candidate) => candidate.id === newId) === false
+          ),
+      });
+      return newId;
+    } finally {
+      baked.release();
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/cropLayerController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/cropLayerController.ts
new file mode 100644
index 00000000000..3f22fc11e5f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/cropLayerController.ts
@@ -0,0 +1,167 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasLayerSourceContract } from '@workbench/types';
+
+import { renderableSourceOf } from '@workbench/canvas-engine/document/sources';
+import { intersect, isEmpty, roundOut } from '@workbench/canvas-engine/math/rect';
+
+export type CropLayerResult =
+  | { status: 'cropped' }
+  | { status: 'missing' | 'locked' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' | 'busy' }
+  | { status: 'failed'; message: string };
+
+type ExportResult =
+  | { status: 'ok'; surface: RasterSurface; rect: Rect; guard: LayerExportGuard; release(): void }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' };
+
+interface PixelSnapshot {
+  pixels: RasterSurface;
+  rect: Rect;
+}
+
+export interface CropLayerControllerOptions {
+  readonly backend: RasterBackend;
+  readonly history: History;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly capturePermit: () => object | null;
+  readonly isPermitCurrent: (permit: object) => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly endBurst: () => void;
+  readonly isSupportedSource: (source: CanvasLayerSourceContract) => boolean;
+  readonly exportBaked: (layerId: string) => Promise<ExportResult>;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly captureCache: (
+    layer: CanvasLayerContract,
+    document: CanvasDocumentContractV2
+  ) => PixelSnapshot | null | 'not-ready';
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => unknown;
+  readonly installPrepared: (prepared: unknown) => void;
+  readonly discardPersisted: (layerId: string) => void;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    expectedReducer: () => boolean,
+    expectedMirror: () => boolean
+  ) => void;
+}
+
+/** Owns guarded crop-to-bbox conversion and replayable pixel snapshots. */
+export class CropLayerController {
+  private disposed = false;
+  constructor(private readonly deps: CropLayerControllerOptions) {}
+
+  async crop(layerId: string): Promise<CropLayerResult> {
+    const permit = this.deps.capturePermit();
+    if (this.disposed || !permit || this.deps.isGestureActive()) {
+      return { status: 'busy' };
+    }
+    this.deps.endBurst();
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer) {
+      return { status: 'missing' };
+    }
+    if (layer.isLocked) {
+      return { status: 'locked' };
+    }
+    const source = renderableSourceOf(layer);
+    if (!source || !this.deps.isSupportedSource(source)) {
+      return { status: 'unsupported' };
+    }
+    try {
+      const exported = await this.deps.exportBaked(layerId);
+      if (exported.status !== 'ok') {
+        return { status: exported.status === 'disabled' ? 'not-ready' : exported.status };
+      }
+      try {
+        if (!this.deps.isPermitCurrent(permit)) {
+          return { status: 'busy' };
+        }
+        const liveDocument = this.deps.getDocument();
+        const liveLayer = liveDocument?.layers.find((candidate) => candidate.id === layerId);
+        if (!liveDocument || !liveLayer) {
+          return { status: 'missing' };
+        }
+        if (!this.deps.isPermitCurrent(permit) || this.deps.isGestureActive()) {
+          return { status: 'busy' };
+        }
+        if (liveLayer.isLocked) {
+          return { status: 'locked' };
+        }
+        if (!this.deps.isGuardCurrent(exported.guard)) {
+          return { status: 'not-ready' };
+        }
+        const liveSource = renderableSourceOf(liveLayer);
+        if (!liveSource || !this.deps.isSupportedSource(liveSource)) {
+          return { status: 'unsupported' };
+        }
+        const overlap = intersect(exported.rect, roundOut(liveDocument.bbox));
+        if (!overlap || isEmpty(overlap)) {
+          return { status: 'empty' };
+        }
+        const cropRect = roundOut(overlap);
+        const beforePixels = this.deps.captureCache(liveLayer, liveDocument);
+        if (!beforePixels || beforePixels === 'not-ready') {
+          return { status: 'not-ready' };
+        }
+        const before = structuredClone(liveLayer);
+        const cropped = this.deps.backend.createSurface(cropRect.width, cropRect.height);
+        cropped.ctx.setTransform(1, 0, 0, 1, 0, 0);
+        cropped.ctx.clearRect(0, 0, cropRect.width, cropRect.height);
+        cropped.ctx.drawImage(exported.surface.canvas, exported.rect.x - cropRect.x, exported.rect.y - cropRect.y);
+        const identity = { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+        const paint = { bitmap: null, offset: { x: cropRect.x, y: cropRect.y }, type: 'paint' } as const;
+        let after: CanvasLayerContract;
+        if (before.type === 'raster') {
+          const { adjustments: _adjustments, ...rest } = before;
+          after = { ...rest, source: paint, transform: identity };
+        } else if (before.type === 'control') {
+          const { filter: _filter, ...rest } = before;
+          after = { ...rest, source: paint, transform: identity };
+        } else {
+          after = { ...before, mask: { ...before.mask, bitmap: null, offset: paint.offset }, transform: identity };
+        }
+        const publish = (contract: CanvasLayerContract, prepared: unknown): void => {
+          this.deps.dispatchPrepared(
+            { layer: contract, layerId, type: 'replaceCanvasLayer' },
+            () => this.deps.getReducerDocument()?.layers.find((candidate) => candidate.id === layerId) === contract,
+            () => this.deps.getDocument()?.layers.find((candidate) => candidate.id === layerId) === contract
+          );
+          try {
+            this.deps.discardPersisted(layerId);
+          } catch {
+            /* ancillary */
+          }
+          this.deps.installPrepared(prepared);
+        };
+        const apply = (contract: CanvasLayerContract, snapshot: PixelSnapshot): void =>
+          publish(contract, this.deps.preparePixels(layerId, snapshot.rect, snapshot.pixels));
+        const afterPixels = { pixels: cropped, rect: cropRect };
+        const prepared = this.deps.preparePixels(layerId, cropRect, cropped);
+        if (!this.deps.isPermitCurrent(permit)) {
+          return { status: 'busy' };
+        }
+        publish(after, prepared);
+        this.deps.history.push({
+          bytes: beforePixels.rect.width * beforePixels.rect.height * 4 + cropRect.width * cropRect.height * 4 + 256,
+          label: 'Crop layer to bbox',
+          redo: () => apply(after, afterPixels),
+          replayFailureAtomic: true,
+          undo: () => apply(before, beforePixels),
+        });
+        return { status: 'cropped' };
+      } finally {
+        exported.release();
+      }
+    } catch (error) {
+      return { message: error instanceof Error ? error.message : String(error), status: 'failed' };
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/editingController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/editingController.test.ts
new file mode 100644
index 00000000000..5d48d6db22c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/editingController.test.ts
@@ -0,0 +1,119 @@
+import type { SelectionState, SelectionStateDeps } from '@workbench/canvas-engine/selection/selectionState';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { EditingController } from './editingController';
+
+const createSelection = (): SelectionState => ({
+  antsPaths: () => [],
+  bounds: () => null,
+  clear: vi.fn(),
+  commit: vi.fn(),
+  containsPoint: () => false,
+  dispose: vi.fn(),
+  hasSelection: () => false,
+  invert: vi.fn(),
+  mask: () => null,
+  replaceMask: vi.fn(),
+  selectAll: vi.fn(),
+});
+
+const createTextOptions = () => ({
+  canEdit: () => true,
+  commitStructural: vi.fn(),
+  createLayerId: () => 'text-1',
+  getDocument: () => null,
+  invalidate: vi.fn(),
+  isGestureActive: () => false,
+  options: { get: () => ({}) as never },
+  session: { get: () => null, set: vi.fn() },
+});
+
+const createTransformOptions = () => ({
+  backend: {} as never,
+  canEdit: () => true,
+  dispatch: vi.fn(),
+  endBurst: vi.fn(),
+  getCache: () => null,
+  getDocument: () => null,
+  invalidate: vi.fn(),
+  isGestureActive: () => false,
+  pushHistory: vi.fn(),
+  replaceCache: vi.fn(),
+  restoreCache: vi.fn(),
+  session: { get: () => null, set: vi.fn() },
+  setOverride: vi.fn(),
+});
+
+const createSelectionPixelOptions = () => ({
+  applyImagePatch: vi.fn(),
+  backend: {} as never,
+  beginControlEdit: () => null,
+  canEdit: () => true,
+  deleteDerived: vi.fn(),
+  endBurst: vi.fn(),
+  getDocument: () => null,
+  getFillColor: () => '#000',
+  history: {} as never,
+  invalidateLayer: vi.fn(),
+  isGestureActive: () => false,
+  layers: {} as never,
+  markDirty: vi.fn(),
+  notifyPainted: vi.fn(),
+});
+
+const createSelectionImageOptions = () => ({
+  capturePermit: () => null,
+  decodeImage: vi.fn(),
+  getDocument: () => null,
+  isGestureActive: () => false,
+  isGuardCurrent: () => false,
+  isPermitCurrent: () => false,
+});
+
+describe('EditingController', () => {
+  it('owns selection state and invalidates exclusive leases with document lifecycle', () => {
+    const selection = createSelection();
+    const createSelectionState = vi.fn((_deps: SelectionStateDeps) => selection);
+    const controller = new EditingController({
+      getDocument: () => null,
+      selection: {} as SelectionStateDeps,
+      selectionPixels: createSelectionPixelOptions(),
+      selectionImage: createSelectionImageOptions(),
+      createSelectionState,
+      text: createTextOptions(),
+      transform: createTransformOptions(),
+    });
+
+    expect(controller.selection).toBe(selection);
+    const lease = controller.edits.tryAcquire({ kind: 'filter', layerId: 'layer-1' });
+    expect(lease?.isCurrent()).toBe(true);
+
+    controller.invalidateDocument();
+    expect(lease?.signal.aborted).toBe(true);
+    expect(lease?.isCurrent()).toBe(false);
+    expect(controller.edits.tryAcquire({ kind: 'filter' })?.isCurrent()).toBe(true);
+  });
+
+  it('disposes selection and leases idempotently and cannot reactivate afterward', () => {
+    const selection = createSelection();
+    const controller = new EditingController({
+      getDocument: () => null,
+      selection: {} as SelectionStateDeps,
+      selectionPixels: createSelectionPixelOptions(),
+      selectionImage: createSelectionImageOptions(),
+      createSelectionState: () => selection,
+      text: createTextOptions(),
+      transform: createTransformOptions(),
+    });
+    const lease = controller.edits.tryAcquire({ kind: 'select-object' });
+
+    controller.dispose();
+    controller.dispose();
+    controller.activate();
+
+    expect(selection.dispose).toHaveBeenCalledTimes(1);
+    expect(lease?.signal.aborted).toBe(true);
+    expect(controller.edits.tryAcquire({ kind: 'filter' })).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/editingController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/editingController.ts
new file mode 100644
index 00000000000..38c615a4f99
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/editingController.ts
@@ -0,0 +1,127 @@
+import type { CanvasEditGate, CanvasEditGateController } from '@workbench/canvas-engine/editGate';
+import type { SelectionState, SelectionStateDeps } from '@workbench/canvas-engine/selection/selectionState';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { getSourceBounds, isRenderableLayer } from '@workbench/canvas-engine/document/sources';
+import { createCanvasEditGate } from '@workbench/canvas-engine/editGate';
+import { roundOut, union } from '@workbench/canvas-engine/math/rect';
+import { createSelectionState } from '@workbench/canvas-engine/selection/selectionState';
+
+import { SelectionImageController, type SelectionImageControllerOptions } from './selectionImageController';
+import { SelectionPixelController, type SelectionPixelControllerOptions } from './selectionPixelController';
+import { TextEditingController, type TextEditingControllerOptions } from './textEditingController';
+import { TransformEditingController, type TransformEditingControllerOptions } from './transformEditingController';
+
+export interface EditingControllerOptions<Permit = unknown, Owner = symbol> {
+  readonly selection: SelectionStateDeps;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly createSelectionState?: (deps: SelectionStateDeps) => SelectionState;
+  readonly createEditGate?: () => CanvasEditGateController;
+  readonly text: TextEditingControllerOptions;
+  readonly transform: TransformEditingControllerOptions;
+  readonly selectionPixels: Omit<SelectionPixelControllerOptions, 'selection'>;
+  readonly selectionImage: Omit<SelectionImageControllerOptions<Permit, Owner>, 'selection'>;
+}
+
+/** Owns transient editing state whose lifetime follows one engine instance. */
+export class EditingController<Permit = unknown, Owner = symbol> {
+  readonly selection: SelectionState;
+  readonly edits: CanvasEditGate;
+  readonly text: TextEditingController;
+  readonly transform: TransformEditingController;
+  readonly selectionPixels: SelectionPixelController;
+  readonly selectionImage: SelectionImageController<Permit, Owner>;
+  private readonly editGate: CanvasEditGateController;
+  private readonly getDocument: () => CanvasDocumentContractV2 | null;
+  private disposed = false;
+
+  constructor(options: EditingControllerOptions<Permit, Owner>) {
+    this.selection = (options.createSelectionState ?? createSelectionState)(options.selection);
+    this.getDocument = options.getDocument;
+    this.editGate = (options.createEditGate ?? createCanvasEditGate)();
+    this.edits = this.editGate;
+    this.text = new TextEditingController(options.text);
+    this.transform = new TransformEditingController(options.transform);
+    this.selectionPixels = new SelectionPixelController({ ...options.selectionPixels, selection: this.selection });
+    this.selectionImage = new SelectionImageController<Permit, Owner>({
+      ...options.selectionImage,
+      selection: this.selection,
+    });
+  }
+
+  activate(): void {
+    if (!this.disposed) {
+      this.editGate.activate();
+    }
+  }
+
+  private selectionDomain(): Rect | null {
+    const document = this.getDocument();
+    if (!document) {
+      return null;
+    }
+    let bounds: Rect = { ...document.bbox };
+    for (const layer of document.layers) {
+      if (isRenderableLayer(layer)) {
+        bounds = union(bounds, getSourceBounds(layer, document));
+      }
+    }
+    return roundOut(bounds);
+  }
+
+  selectAll(): void {
+    const domain = this.selectionDomain();
+    if (domain) {
+      this.selection.selectAll(domain);
+    }
+  }
+
+  deselect(): void {
+    this.selection.clear();
+  }
+
+  invertSelection(): void {
+    const domain = this.selectionDomain();
+    if (domain) {
+      this.selection.invert(domain);
+    }
+  }
+
+  cooldown(): void {
+    if (!this.disposed) {
+      this.editGate.cooldown();
+    }
+  }
+
+  invalidateDocument(): void {
+    if (!this.disposed) {
+      this.editGate.invalidateDocument();
+    }
+  }
+
+  invalidateProject(): void {
+    if (!this.disposed) {
+      this.editGate.invalidateProject();
+    }
+  }
+
+  invalidateLayer(layerId: string): void {
+    if (!this.disposed) {
+      this.editGate.invalidateLayer(layerId);
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.editGate.dispose();
+    this.text.dispose();
+    this.transform.dispose();
+    this.selectionPixels.dispose();
+    this.selectionImage.dispose();
+    this.selection.dispose();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/extractMaskedAreaController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/extractMaskedAreaController.ts
new file mode 100644
index 00000000000..4b51cf854b4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/extractMaskedAreaController.ts
@@ -0,0 +1,242 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { CanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { DerivedSurfaceCache } from '@workbench/canvas-engine/render/derivedSurfaceCache';
+import type { LayerCacheEntry, LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { getSourceContentRect } from '@workbench/canvas-engine/document/sources';
+import { isEmpty } from '@workbench/canvas-engine/math/rect';
+import { compositeDocument } from '@workbench/canvas-engine/render/compositor';
+
+export type ExtractMaskedAreaResult =
+  | { status: 'extracted'; layerId: string }
+  | { status: 'missing' | 'unsupported' | 'not-ready' | 'busy' | 'empty' };
+
+type ExportResult =
+  | { status: 'ok'; surface: RasterSurface; rect: Rect; guard: LayerExportGuard; release(): void }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' };
+
+export interface ExtractMaskedAreaControllerOptions {
+  readonly backend: RasterBackend;
+  readonly layers: LayerCacheStore;
+  readonly derived: DerivedSurfaceCache;
+  readonly diagnostics: CanvasDiagnostics;
+  readonly history: History;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly capturePermit: () => object | null;
+  readonly isPermitCurrent: (permit: object) => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly endBurst: () => void;
+  readonly isCacheReady: (layer: CanvasLayerContract, document: CanvasDocumentContractV2) => boolean;
+  readonly hasExportableContent: (layerId: string) => boolean;
+  readonly exportBaked: (layerId: string, includeDisabled?: boolean) => Promise<ExportResult>;
+  readonly rasterize: (layerId: string) => Promise<ExportResult>;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly getAdjustedSurface: (layer: CanvasLayerContract, entry: LayerCacheEntry) => RasterSurface | null;
+  readonly getMaskPattern: (style: string, color: string) => RasterSurface | null;
+  readonly createLayerId: () => string;
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => unknown;
+  readonly installPrepared: (prepared: unknown) => void;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    expectedReducer: () => boolean,
+    expectedMirror: () => boolean
+  ) => void;
+}
+
+/** Owns guarded extraction of raster content through an inpaint mask. */
+export class ExtractMaskedAreaController {
+  private disposed = false;
+  constructor(private readonly deps: ExtractMaskedAreaControllerOptions) {}
+
+  async extract(maskLayerId: string): Promise<ExtractMaskedAreaResult> {
+    const permit = this.deps.capturePermit();
+    if (this.disposed || !permit || this.deps.isGestureActive()) {
+      return { status: 'busy' };
+    }
+    this.deps.endBurst();
+    const document = this.deps.getDocument();
+    if (!document) {
+      return { status: 'missing' };
+    }
+    const maskIndex = document.layers.findIndex((layer) => layer.id === maskLayerId);
+    const mask = document.layers[maskIndex];
+    if (maskIndex < 0 || !mask) {
+      return { status: 'missing' };
+    }
+    if (mask.type !== 'inpaint_mask' || mask.isLocked) {
+      return { status: 'unsupported' };
+    }
+    const liveMask = this.deps.layers.get(maskLayerId);
+    if (isEmpty(getSourceContentRect(mask, document)) && (!liveMask || isEmpty(liveMask.rect))) {
+      return { status: 'empty' };
+    }
+    const contributors = document.layers.filter(
+      (layer) => layer.isEnabled && layer.type === 'raster' && this.deps.hasExportableContent(layer.id)
+    );
+    if (contributors.length === 0) {
+      return { status: 'empty' };
+    }
+    if (
+      !this.deps.isCacheReady(mask, document) ||
+      contributors.some((layer) => !this.deps.isCacheReady(layer, document))
+    ) {
+      return { status: 'not-ready' };
+    }
+    const owned: Extract<ExportResult, { status: 'ok' }>[] = [];
+    const acquire = async (resultPromise: Promise<ExportResult>): Promise<ExportResult> => {
+      const result = await resultPromise;
+      if (result.status === 'ok') {
+        owned.push(result);
+      }
+      return result;
+    };
+    try {
+      const settled = await Promise.allSettled([
+        acquire(this.deps.exportBaked(maskLayerId, true)),
+        ...contributors.map((layer) => acquire(this.deps.rasterize(layer.id))),
+      ]);
+      const rejected = settled.find((result) => result.status === 'rejected');
+      if (rejected?.status === 'rejected') {
+        throw rejected.reason instanceof Error ? rejected.reason : new Error(String(rejected.reason));
+      }
+      const [maskPixels, ...contributorPixels] = settled.map(
+        (result) => (result as PromiseFulfilledResult<ExportResult>).value
+      );
+      if (!this.deps.isPermitCurrent(permit)) {
+        return { status: 'busy' };
+      }
+      if (maskPixels.status !== 'ok') {
+        return { status: maskPixels.status === 'not-ready' ? 'not-ready' : 'empty' };
+      }
+      if (contributorPixels.some((pixels) => pixels.status !== 'ok')) {
+        return { status: contributorPixels.some((pixels) => pixels.status === 'not-ready') ? 'not-ready' : 'empty' };
+      }
+      if (this.deps.isGestureActive()) {
+        return { status: 'busy' };
+      }
+      if (maskPixels.guard.layer !== mask || !this.deps.isGuardCurrent(maskPixels.guard)) {
+        return { status: 'not-ready' };
+      }
+      const liveDocument = this.deps.getDocument();
+      const liveMaskIndex = liveDocument?.layers.findIndex((layer) => layer.id === maskLayerId) ?? -1;
+      const currentMask = liveDocument?.layers[liveMaskIndex];
+      if (!liveDocument || !currentMask) {
+        return { status: 'missing' };
+      }
+      if (currentMask !== mask) {
+        return { status: currentMask.type === 'inpaint_mask' && currentMask.isLocked ? 'unsupported' : 'not-ready' };
+      }
+      const liveContributors = liveDocument.layers.filter(
+        (layer) => layer.isEnabled && layer.type === 'raster' && this.deps.hasExportableContent(layer.id)
+      );
+      if (
+        liveMaskIndex !== maskIndex ||
+        liveContributors.some((layer, index) => layer !== contributors[index]) ||
+        liveContributors.length !== contributors.length
+      ) {
+        return { status: 'not-ready' };
+      }
+      for (let index = 0; index < contributorPixels.length; index += 1) {
+        const pixels = contributorPixels[index];
+        const contributor = contributors[index];
+        if (
+          !pixels ||
+          pixels.status !== 'ok' ||
+          !contributor ||
+          pixels.guard.layer !== contributor ||
+          !this.deps.isGuardCurrent(pixels.guard)
+        ) {
+          return { status: 'not-ready' };
+        }
+      }
+      const rect = maskPixels.rect;
+      if (isEmpty(rect)) {
+        return { status: 'empty' };
+      }
+      const pixels = this.deps.backend.createSurface(rect.width, rect.height);
+      compositeDocument(
+        pixels,
+        { ...document, layers: contributors },
+        this.deps.layers,
+        { a: 1, b: 0, c: 0, d: 1, e: -rect.x, f: -rect.y },
+        {
+          adjustedSurface: this.deps.getAdjustedSurface,
+          backend: this.deps.backend,
+          derivedSurfaces: this.deps.derived,
+          diagnostics: this.deps.diagnostics,
+          maskPatternTile: this.deps.getMaskPattern,
+        }
+      );
+      pixels.ctx.setTransform(1, 0, 0, 1, 0, 0);
+      pixels.ctx.globalAlpha = 1;
+      pixels.ctx.globalCompositeOperation = 'destination-in';
+      pixels.ctx.drawImage(maskPixels.surface.canvas, 0, 0);
+      const resultId = this.deps.createLayerId();
+      const layer: CanvasLayerContract = {
+        blendMode: 'normal',
+        id: resultId,
+        isEnabled: true,
+        isLocked: false,
+        name: `${mask.name} extraction`,
+        opacity: 1,
+        source: { bitmap: null, offset: { x: rect.x, y: rect.y }, type: 'paint' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        type: 'raster',
+      };
+      const selectedLayerId = liveDocument.selectedLayerId;
+      const apply = (): void => {
+        const prepared = this.deps.preparePixels(resultId, rect, pixels);
+        this.deps.dispatchPrepared(
+          {
+            add: { index: maskIndex, layers: [layer] },
+            enabledUpdates: [],
+            selectedLayerId: resultId,
+            type: 'applyCanvasLayerStackMutation',
+          },
+          () =>
+            this.deps.getReducerDocument()?.selectedLayerId === resultId &&
+            this.deps.getReducerDocument()?.layers.some((candidate) => candidate === layer) === true,
+          () =>
+            this.deps.getDocument()?.selectedLayerId === resultId &&
+            this.deps.getDocument()?.layers.some((candidate) => candidate === layer) === true
+        );
+        this.deps.installPrepared(prepared);
+      };
+      if (!this.deps.isPermitCurrent(permit)) {
+        return { status: 'busy' };
+      }
+      apply();
+      this.deps.history.push({
+        bytes: rect.width * rect.height * 4 + 256,
+        label: 'Extract masked area',
+        redo: apply,
+        replayFailureAtomic: true,
+        undo: () =>
+          this.deps.dispatchPrepared(
+            { enabledUpdates: [], removeIds: [resultId], selectedLayerId, type: 'applyCanvasLayerStackMutation' },
+            () =>
+              this.deps.getReducerDocument()?.selectedLayerId === selectedLayerId &&
+              this.deps.getReducerDocument()?.layers.some((candidate) => candidate.id === resultId) === false,
+            () =>
+              this.deps.getDocument()?.selectedLayerId === selectedLayerId &&
+              this.deps.getDocument()?.layers.some((candidate) => candidate.id === resultId) === false
+          ),
+      });
+      return { layerId: resultId, status: 'extracted' };
+    } finally {
+      for (const result of owned) {
+        result.release();
+      }
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/filterResultController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/filterResultController.ts
new file mode 100644
index 00000000000..50fe03f33b8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/filterResultController.ts
@@ -0,0 +1,261 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { CapturedLayerCache } from '@workbench/canvas-engine/controllers/layerMutationController';
+import type { DecodeImageResult } from '@workbench/canvas-engine/controllers/rasterController';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { PreparedLayerCacheReplacement } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type {
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { createControlLayer } from '@workbench/canvas-engine/document/layerFactories';
+import { LayerFilterOutputDimensionError } from '@workbench/canvas-engine/filterError';
+
+export type CommitRasterFilterResult =
+  | { status: 'committed'; layerId: string }
+  | { status: 'missing' | 'locked' | 'stale' | 'unsupported' | 'busy' | 'aborted' }
+  | { status: 'failed'; message: string };
+export interface RasterFilterSettings {
+  type: string;
+  settings: Record<string, unknown>;
+}
+export type RasterFilterCommitTarget = 'apply' | 'raster' | 'control';
+export interface CommitRasterFilterOptions {
+  guard: LayerExportGuard;
+  image: CanvasImageRef;
+  rect: Rect;
+  mode: 'replace' | 'copy';
+  filter?: RasterFilterSettings;
+  target?: RasterFilterCommitTarget;
+  requireExactImageDimensions?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface FilterResultControllerOptions<Permit, Owner = symbol> {
+  readonly captureCache: (layer: CanvasLayerContract, document: CanvasDocumentContractV2) => CapturedLayerCache;
+  readonly capturePermit: (owner?: Owner) => Permit | null;
+  readonly createLayerId: () => string;
+  readonly decodeImage: (
+    image: CanvasImageRef,
+    options: {
+      signal?: AbortSignal;
+      isCurrent?: () => boolean;
+      scaleToImage?: boolean;
+      validateDecoded?: (width: number, height: number) => void;
+    }
+  ) => Promise<DecodeImageResult>;
+  readonly discardPersisted: (layerId: string) => void;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    reducerAccepted: () => boolean,
+    mirrorAccepted: () => boolean
+  ) => void;
+  readonly endBurst: () => void;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getMainModelBase: () => string | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly history: History;
+  readonly installPrepared: (prepared: PreparedLayerCacheReplacement, persist?: boolean) => void;
+  readonly isGestureActive: () => boolean;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly isPermitCurrent: (permit: Permit) => boolean;
+  readonly needsPixelPersistence: (layer: CanvasLayerContract) => boolean;
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => PreparedLayerCacheReplacement;
+}
+
+/** Publishes guarded filter results as replacements or independent copies. */
+export class FilterResultController<Permit, Owner = symbol> {
+  constructor(private readonly options: FilterResultControllerOptions<Permit, Owner>) {}
+
+  async commit(options: CommitRasterFilterOptions, owner?: Owner): Promise<CommitRasterFilterResult> {
+    const o = this.options;
+    const permit = o.capturePermit(owner);
+    if (!permit) {
+      return { status: 'busy' };
+    }
+    if (options.signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    try {
+      const decoded = await o.decodeImage(options.image, {
+        isCurrent: () => o.isPermitCurrent(permit),
+        scaleToImage: false,
+        signal: options.signal,
+        validateDecoded: (width, height) => {
+          if (
+            options.requireExactImageDimensions &&
+            (width !== options.image.width || height !== options.image.height)
+          ) {
+            throw new LayerFilterOutputDimensionError(
+              options.filter?.type ?? 'decoded_filter',
+              { height, width },
+              { height: options.image.height, width: options.image.width, x: options.rect.x, y: options.rect.y }
+            );
+          }
+        },
+      });
+      if (decoded.status !== 'ok') {
+        return { status: decoded.status === 'aborted' ? 'aborted' : 'busy' };
+      }
+      const pixels = decoded.surface;
+      const document = o.getDocument();
+      const liveLayer = document?.layers.find((candidate) => candidate.id === options.guard.layerId);
+      if (!document || !liveLayer) {
+        return { status: 'missing' };
+      }
+      if (liveLayer.isLocked) {
+        return { status: 'locked' };
+      }
+      if (liveLayer.type !== 'raster' && liveLayer.type !== 'control') {
+        return { status: 'unsupported' };
+      }
+      if (!o.isPermitCurrent(permit) || o.isGestureActive()) {
+        return { status: 'busy' };
+      }
+      if (!o.isGuardCurrent(options.guard)) {
+        return { status: 'stale' };
+      }
+      if (options.signal?.aborted) {
+        return { status: 'aborted' };
+      }
+      o.endBurst();
+      const image = structuredClone(options.image);
+      const rect = { ...options.rect };
+      const paintSource = { bitmap: image, offset: { x: rect.x, y: rect.y }, type: 'paint' } as const;
+      if (options.mode === 'replace') {
+        const beforePixels = o.captureCache(liveLayer, document);
+        if (!beforePixels || beforePixels === 'not-ready') {
+          return { status: 'stale' };
+        }
+        const before = structuredClone(liveLayer);
+        const after: CanvasLayerContract =
+          liveLayer.type === 'raster'
+            ? (() => {
+                const { adjustments: _adjustments, ...base } = liveLayer;
+                return structuredClone({ ...base, filter: options.filter, source: paintSource });
+              })()
+            : structuredClone({ ...liveLayer, filter: options.filter, source: paintSource });
+        const afterPixels = { pixels, rect };
+        const publish = (
+          contract: CanvasLayerContract,
+          prepared: PreparedLayerCacheReplacement,
+          publishOptions: { discardPersistence: boolean; persist: boolean }
+        ): void => {
+          o.dispatchPrepared(
+            { layer: contract, layerId: liveLayer.id, type: 'replaceCanvasLayer' },
+            () => o.getReducerDocument()?.layers.find((candidate) => candidate.id === liveLayer.id) === contract,
+            () => o.getDocument()?.layers.find((candidate) => candidate.id === liveLayer.id) === contract
+          );
+          if (publishOptions.discardPersistence) {
+            try {
+              o.discardPersisted(liveLayer.id);
+            } catch {
+              /* Ancillary after commit. */
+            }
+          }
+          o.installPrepared(prepared, publishOptions.persist);
+        };
+        const apply = (
+          contract: CanvasLayerContract,
+          snapshot: { pixels: RasterSurface; rect: Rect },
+          publishOptions: { discardPersistence: boolean; persist: boolean }
+        ): void => publish(contract, o.preparePixels(liveLayer.id, snapshot.rect, snapshot.pixels), publishOptions);
+        publish(after, o.preparePixels(liveLayer.id, rect, pixels), { discardPersistence: true, persist: false });
+        o.history.push({
+          bytes: beforePixels.rect.width * beforePixels.rect.height * 4 + rect.width * rect.height * 4 + 256,
+          label: 'Replace layer with filter result',
+          redo: () => apply(after, afterPixels, { discardPersistence: true, persist: false }),
+          replayFailureAtomic: true,
+          undo: () =>
+            apply(before, beforePixels, { discardPersistence: false, persist: o.needsPixelPersistence(before) }),
+        });
+        return { layerId: liveLayer.id, status: 'committed' };
+      }
+      const sourceIndex = document.layers.findIndex((candidate) => candidate.id === liveLayer.id);
+      if (sourceIndex < 0) {
+        return { status: 'missing' };
+      }
+      const selectedLayerId = document.selectedLayerId;
+      const layerId = o.createLayerId();
+      let copy: CanvasLayerContract;
+      if (options.target === 'control') {
+        const base =
+          liveLayer.type === 'control'
+            ? structuredClone(liveLayer)
+            : createControlLayer(`${liveLayer.name} filtered`, layerId, o.getMainModelBase());
+        copy = {
+          ...base,
+          filter: options.filter,
+          id: layerId,
+          name: `${liveLayer.name} filtered`,
+          source: paintSource,
+          transform: structuredClone(liveLayer.transform),
+        };
+      } else if (options.target === 'raster' && liveLayer.type === 'control') {
+        copy = {
+          blendMode: liveLayer.blendMode,
+          filter: options.filter,
+          id: layerId,
+          isEnabled: true,
+          isLocked: false,
+          name: `${liveLayer.name} filtered`,
+          opacity: liveLayer.opacity,
+          source: paintSource,
+          transform: structuredClone(liveLayer.transform),
+          type: 'raster',
+        };
+      } else {
+        const { adjustments: _adjustments, ...base } = structuredClone(liveLayer as CanvasRasterLayerContractV2);
+        copy = {
+          ...base,
+          filter: options.filter,
+          id: layerId,
+          name: `${liveLayer.name} filtered`,
+          source: paintSource,
+          type: 'raster',
+        };
+      }
+      const apply = (): void => {
+        const prepared = o.preparePixels(layerId, rect, pixels);
+        o.dispatchPrepared(
+          { index: sourceIndex, layer: copy, type: 'addCanvasLayer' },
+          () => o.getReducerDocument()?.layers.some((candidate) => candidate === copy) === true,
+          () => o.getDocument()?.layers.some((candidate) => candidate === copy) === true
+        );
+        o.installPrepared(prepared, false);
+      };
+      apply();
+      o.history.push({
+        bytes: rect.width * rect.height * 4 + 256,
+        label: 'Copy layer filter result',
+        redo: apply,
+        replayFailureAtomic: true,
+        undo: () => {
+          o.dispatchPrepared(
+            { id: selectedLayerId, type: 'setCanvasSelectedLayer' },
+            () => o.getReducerDocument()?.selectedLayerId === selectedLayerId,
+            () => o.getDocument()?.selectedLayerId === selectedLayerId
+          );
+          o.dispatchPrepared(
+            { ids: [layerId], type: 'removeCanvasLayers' },
+            () => o.getReducerDocument()?.layers.some((candidate) => candidate.id === layerId) === false,
+            () => o.getDocument()?.layers.some((candidate) => candidate.id === layerId) === false
+          );
+        },
+      });
+      return { layerId, status: 'committed' };
+    } catch (error) {
+      if (options.signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
+        return { status: 'aborted' };
+      }
+      return { message: error instanceof Error ? error.message : String(error), status: 'failed' };
+    }
+  }
+
+  dispose(): void {}
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/generatedResultController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/generatedResultController.ts
new file mode 100644
index 00000000000..c3b746942ad
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/generatedResultController.ts
@@ -0,0 +1,253 @@
+import type {
+  CommitGeneratedImageOptions,
+  CommitGeneratedImageResult,
+  LayerExportGuard,
+} from '@workbench/canvas-engine/api';
+import type { CapturedLayerCache } from '@workbench/canvas-engine/controllers/layerMutationController';
+import type { DecodeImageResult } from '@workbench/canvas-engine/controllers/rasterController';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { PreparedLayerCacheReplacement } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasImageRef, CanvasLayerContract } from '@workbench/types';
+
+import { createControlLayer, nextControlLayerName } from '@workbench/canvas-engine/document/layerFactories';
+
+export interface GeneratedResultControllerOptions<Permit, Owner = symbol> {
+  readonly captureCache: (layer: CanvasLayerContract, document: CanvasDocumentContractV2) => CapturedLayerCache;
+  readonly capturePermit: (owner?: Owner) => Permit | null;
+  readonly clearPreview: (layerId: string) => void;
+  readonly createLayerId: () => string;
+  readonly decodeImage: (
+    image: CanvasImageRef,
+    options: { signal?: AbortSignal; isCurrent?: () => boolean }
+  ) => Promise<DecodeImageResult>;
+  readonly discardPersisted: (layerId: string) => void;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    reducerAccepted: () => boolean,
+    mirrorAccepted: () => boolean
+  ) => void;
+  readonly endBurst: () => void;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getMainModelBase: () => string | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly history: History;
+  readonly installPrepared: (prepared: PreparedLayerCacheReplacement, persist?: boolean) => void;
+  readonly isGestureActive: () => boolean;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly isPermitCurrent: (permit: Permit) => boolean;
+  readonly needsPixelPersistence: (layer: CanvasLayerContract) => boolean;
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => PreparedLayerCacheReplacement;
+}
+
+/** Publishes guarded workflow/SAM images as replacements or copies. */
+export class GeneratedResultController<Permit, Owner = symbol> {
+  constructor(private readonly options: GeneratedResultControllerOptions<Permit, Owner>) {}
+
+  async commit(options: CommitGeneratedImageOptions, owner?: Owner): Promise<CommitGeneratedImageResult> {
+    const o = this.options;
+    const permit = o.capturePermit(owner);
+    if (!permit) {
+      return { status: 'busy' };
+    }
+    if (options.signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    const validate = ():
+      | { document: CanvasDocumentContractV2; liveLayer: Extract<CanvasLayerContract, { type: 'raster' | 'control' }> }
+      | { result: CommitGeneratedImageResult } => {
+      if (!o.isPermitCurrent(permit)) {
+        return { result: { status: 'busy' } };
+      }
+      const document = o.getDocument();
+      if (!document) {
+        return { result: { status: 'missing' } };
+      }
+      const liveLayer = document.layers.find((layer) => layer.id === options.guard.layerId);
+      if (!liveLayer) {
+        return { result: { status: 'missing' } };
+      }
+      if (liveLayer.isLocked) {
+        return { result: { status: 'locked' } };
+      }
+      if (liveLayer.type !== 'raster' && liveLayer.type !== 'control') {
+        return { result: { status: 'unsupported' } };
+      }
+      if (o.isGestureActive()) {
+        return { result: { status: 'busy' } };
+      }
+      if (!o.isGuardCurrent(options.guard)) {
+        return { result: { status: 'stale' } };
+      }
+      return { document, liveLayer };
+    };
+    try {
+      const decoded = await o.decodeImage(options.image, {
+        isCurrent: () => o.isPermitCurrent(permit),
+        signal: options.signal,
+      });
+      if (decoded.status !== 'ok') {
+        return { status: decoded.status === 'aborted' ? 'aborted' : 'busy' };
+      }
+      const checked = validate();
+      if ('result' in checked) {
+        return checked.result;
+      }
+      const { document, liveLayer } = checked;
+      const image = structuredClone(options.image);
+      const origin = { ...options.origin };
+      const rect = { height: image.height, width: image.width, ...origin };
+      const source = { bitmap: image, offset: origin, type: 'paint' } as const;
+      const identityTransform: LayerTransform = { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+      const publishSnapshot = (
+        contract: CanvasLayerContract,
+        prepared: PreparedLayerCacheReplacement,
+        publishOptions: { discardPersistence: boolean; persist: boolean }
+      ): void => {
+        o.dispatchPrepared(
+          { layer: contract, layerId: liveLayer.id, type: 'replaceCanvasLayer' },
+          () => o.getReducerDocument()?.layers.find((candidate) => candidate.id === liveLayer.id) === contract,
+          () => o.getDocument()?.layers.find((candidate) => candidate.id === liveLayer.id) === contract
+        );
+        if (publishOptions.discardPersistence) {
+          try {
+            o.discardPersisted(liveLayer.id);
+          } catch {
+            /* Ancillary after reducer acceptance. */
+          }
+        }
+        try {
+          o.clearPreview(liveLayer.id);
+        } catch {
+          /* Transient preview is ancillary. */
+        }
+        o.installPrepared(prepared, publishOptions.persist);
+      };
+      const applySnapshot = (
+        contract: CanvasLayerContract,
+        snapshot: { pixels: RasterSurface; rect: Rect },
+        publishOptions: { discardPersistence: boolean; persist: boolean }
+      ): void =>
+        publishSnapshot(contract, o.preparePixels(liveLayer.id, snapshot.rect, snapshot.pixels), publishOptions);
+      if (options.target === 'replace') {
+        const beforePixels = o.captureCache(liveLayer, document);
+        if (!beforePixels || beforePixels === 'not-ready') {
+          return { status: 'stale' };
+        }
+        if (options.signal?.aborted) {
+          return { status: 'aborted' };
+        }
+        const before = structuredClone(liveLayer);
+        let after: CanvasLayerContract;
+        if (liveLayer.type === 'raster') {
+          const { adjustments: _adjustments, ...base } = structuredClone(liveLayer);
+          after = { ...base, source, transform: identityTransform };
+        } else {
+          after = { ...structuredClone(liveLayer), source, transform: identityTransform };
+        }
+        const afterPixels = { pixels: decoded.surface, rect };
+        const prepared = o.preparePixels(liveLayer.id, rect, decoded.surface);
+        if (options.signal?.aborted) {
+          return { status: 'aborted' };
+        }
+        const finalCheck = validate();
+        if ('result' in finalCheck) {
+          return finalCheck.result;
+        }
+        o.endBurst();
+        publishSnapshot(after, prepared, { discardPersistence: true, persist: false });
+        o.history.push({
+          bytes: beforePixels.rect.width * beforePixels.rect.height * 4 + rect.width * rect.height * 4 + 256,
+          label: options.historyLabel ?? 'Replace layer with workflow result',
+          redo: () => applySnapshot(after, afterPixels, { discardPersistence: true, persist: false }),
+          replayFailureAtomic: true,
+          undo: () =>
+            applySnapshot(before, beforePixels, {
+              discardPersistence: false,
+              persist: o.needsPixelPersistence(before),
+            }),
+        });
+        return { layerId: liveLayer.id, status: 'committed' };
+      }
+      const sourceIndex = document.layers.findIndex((candidate) => candidate.id === liveLayer.id);
+      if (sourceIndex < 0) {
+        return { status: 'missing' };
+      }
+      const layerId = o.createLayerId();
+      const selectedLayerId = document.selectedLayerId;
+      const copy: CanvasLayerContract =
+        options.target === 'copy-control'
+          ? {
+              ...createControlLayer(
+                options.copyLayerName ?? nextControlLayerName(document.layers.map((layer) => layer.name)),
+                layerId,
+                o.getMainModelBase()
+              ),
+              source,
+              transform: identityTransform,
+            }
+          : {
+              blendMode: 'normal',
+              id: layerId,
+              isEnabled: true,
+              isLocked: false,
+              name: options.copyLayerName ?? `${liveLayer.name} workflow result`,
+              opacity: 1,
+              source,
+              transform: identityTransform,
+              type: 'raster',
+            };
+      const publishCopy = (prepared: PreparedLayerCacheReplacement): void => {
+        o.dispatchPrepared(
+          { index: sourceIndex, layer: copy, type: 'addCanvasLayer' },
+          () => o.getReducerDocument()?.layers.some((candidate) => candidate === copy) === true,
+          () => o.getDocument()?.layers.some((candidate) => candidate === copy) === true
+        );
+        o.installPrepared(prepared, false);
+      };
+      const applyCopy = (): void => publishCopy(o.preparePixels(layerId, rect, decoded.surface));
+      const prepared = o.preparePixels(layerId, rect, decoded.surface);
+      if (options.signal?.aborted) {
+        return { status: 'aborted' };
+      }
+      const finalCheck = validate();
+      if ('result' in finalCheck) {
+        return finalCheck.result;
+      }
+      o.endBurst();
+      publishCopy(prepared);
+      o.history.push({
+        bytes: rect.width * rect.height * 4 + 256,
+        label:
+          options.target === 'copy-control'
+            ? 'Copy workflow result to control layer'
+            : 'Copy workflow result to raster layer',
+        redo: applyCopy,
+        replayFailureAtomic: true,
+        undo: () => {
+          o.dispatchPrepared(
+            { id: selectedLayerId, type: 'setCanvasSelectedLayer' },
+            () => o.getReducerDocument()?.selectedLayerId === selectedLayerId,
+            () => o.getDocument()?.selectedLayerId === selectedLayerId
+          );
+          o.dispatchPrepared(
+            { ids: [layerId], type: 'removeCanvasLayers' },
+            () => o.getReducerDocument()?.layers.some((candidate) => candidate.id === layerId) === false,
+            () => o.getDocument()?.layers.some((candidate) => candidate.id === layerId) === false
+          );
+        },
+      });
+      return { layerId, status: 'committed' };
+    } catch (error) {
+      if (options.signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
+        return { status: 'aborted' };
+      }
+      return { message: error instanceof Error ? error.message : String(error), status: 'failed' };
+    }
+  }
+
+  dispose(): void {}
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/historyController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/historyController.test.ts
new file mode 100644
index 00000000000..1cdd825910a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/historyController.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { HistoryController } from './historyController';
+
+describe('HistoryController', () => {
+  it('owns history and trims it to the inactive byte budget', () => {
+    const controller = new HistoryController({ activeByteBudget: 1_000, inactiveByteBudget: 100 });
+    controller.history.push({ bytes: 60, label: 'old', redo: () => undefined, undo: () => undefined });
+    controller.history.push({ bytes: 70, label: 'new', redo: () => undefined, undo: () => undefined });
+
+    controller.cooldown();
+
+    expect(controller.history.byteSize()).toBe(70);
+    expect(controller.history.canUndo()).toBe(true);
+    controller.dispose();
+    controller.dispose();
+    expect(controller.history.byteSize()).toBe(0);
+  });
+
+  it('owns guarded commands and synchronizes undo/redo stores', () => {
+    let canEdit = true;
+    let gestureActive = false;
+    const canUndo = { set: vi.fn() };
+    const canRedo = { set: vi.fn() };
+    const endBurst = vi.fn();
+    const controller = new HistoryController({
+      canEdit: () => canEdit,
+      canRedoStore: canRedo,
+      canUndoStore: canUndo,
+      endBurst,
+      isGestureActive: () => gestureActive,
+    });
+    const undo = vi.fn();
+    const redo = vi.fn();
+    controller.history.push({ bytes: 1, label: 'edit', redo, undo });
+
+    controller.undo();
+    expect(undo).toHaveBeenCalledOnce();
+    expect(endBurst).toHaveBeenCalledOnce();
+    expect(canUndo.set).toHaveBeenLastCalledWith(false);
+    expect(canRedo.set).toHaveBeenLastCalledWith(true);
+
+    gestureActive = true;
+    controller.redo();
+    expect(redo).not.toHaveBeenCalled();
+    gestureActive = false;
+    canEdit = false;
+    controller.clear();
+    expect(controller.history.canRedo()).toBe(true);
+
+    canEdit = true;
+    controller.clear();
+    expect(controller.history.canRedo()).toBe(false);
+    controller.dispose();
+  });
+
+  it('isolates store subscriber failures while synchronizing both flags', () => {
+    const canUndo = {
+      set: vi.fn(() => {
+        throw new Error('observer');
+      }),
+    };
+    const canRedo = { set: vi.fn() };
+    const controller = new HistoryController({ canRedoStore: canRedo, canUndoStore: canUndo });
+
+    expect(() =>
+      controller.history.push({ bytes: 1, label: 'edit', redo: () => undefined, undo: () => undefined })
+    ).not.toThrow();
+    expect(canRedo.set).toHaveBeenCalled();
+    controller.dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/historyController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/historyController.ts
new file mode 100644
index 00000000000..3615e511cf5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/historyController.ts
@@ -0,0 +1,84 @@
+import { createHistory, HISTORY_BYTE_BUDGET, type History } from '@workbench/canvas-engine/history/history';
+
+export const INACTIVE_HISTORY_BYTE_BUDGET = 64 * 1024 * 1024;
+
+export interface HistoryControllerOptions {
+  readonly activeByteBudget?: number;
+  readonly inactiveByteBudget?: number;
+  readonly canEdit?: () => boolean;
+  readonly isGestureActive?: () => boolean;
+  readonly endBurst?: () => void;
+  readonly canUndoStore?: { set(value: boolean): void };
+  readonly canRedoStore?: { set(value: boolean): void };
+}
+
+export class HistoryController {
+  readonly history: History;
+  private readonly inactiveByteBudget: number;
+  private readonly canEdit: () => boolean;
+  private readonly isGestureActive: () => boolean;
+  private readonly endBurst: () => void;
+  private readonly unsubscribe: () => void;
+  private disposed = false;
+
+  constructor(options: HistoryControllerOptions = {}) {
+    this.inactiveByteBudget = options.inactiveByteBudget ?? INACTIVE_HISTORY_BYTE_BUDGET;
+    this.history = createHistory({ byteBudget: options.activeByteBudget ?? HISTORY_BYTE_BUDGET });
+    this.canEdit = options.canEdit ?? (() => true);
+    this.isGestureActive = options.isGestureActive ?? (() => false);
+    this.endBurst = options.endBurst ?? (() => undefined);
+    const syncStores = (): void => {
+      try {
+        options.canUndoStore?.set(this.history.canUndo());
+      } catch {
+        // Store observers are ancillary and must not break history transactions.
+      }
+      try {
+        options.canRedoStore?.set(this.history.canRedo());
+      } catch {
+        // Keep the two notifications isolated from one another.
+      }
+    };
+    this.unsubscribe = this.history.subscribe(syncStores);
+    syncStores();
+  }
+
+  undo(): void {
+    if (this.disposed || !this.canEdit() || this.isGestureActive()) {
+      return;
+    }
+    this.endBurst();
+    this.history.undo();
+  }
+
+  redo(): void {
+    if (this.disposed || !this.canEdit() || this.isGestureActive()) {
+      return;
+    }
+    this.endBurst();
+    this.history.redo();
+  }
+
+  clear(): void {
+    if (this.disposed || !this.canEdit()) {
+      return;
+    }
+    this.endBurst();
+    this.history.clear();
+  }
+
+  cooldown(): void {
+    if (!this.disposed) {
+      this.history.trimToBytes(this.inactiveByteBudget);
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.unsubscribe();
+    this.history.clear();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/interactionController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/interactionController.test.ts
new file mode 100644
index 00000000000..7aae8c4d489
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/interactionController.test.ts
@@ -0,0 +1,67 @@
+import type { Tool } from '@workbench/canvas-engine/tools/tool';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { InteractionController } from './interactionController';
+
+const createHarness = () => {
+  const brush = { onActivate: vi.fn(), onDeactivate: vi.fn() } as unknown as Tool;
+  const view = { onActivate: vi.fn(), onDeactivate: vi.fn() } as unknown as Tool;
+  const tools = { brush, view };
+  const publishActiveTool = vi.fn();
+  const updateCursor = vi.fn();
+  const invalidateOverlay = vi.fn();
+  const beforeSwitch = vi.fn();
+  const stepBrushSize = vi.fn();
+  let locked = false;
+  const controller = new InteractionController({
+    beforeSwitch,
+    getTool: (id) => tools[id as keyof typeof tools],
+    getToolContext: () => ({}) as never,
+    invalidateOverlay,
+    isLocked: () => locked,
+    publishActiveTool,
+    stepBrushSize,
+    updateCursor,
+  });
+  return {
+    beforeSwitch,
+    brush,
+    controller,
+    invalidateOverlay,
+    lock: () => (locked = true),
+    publishActiveTool,
+    stepBrushSize,
+    updateCursor,
+    view,
+  };
+};
+
+describe('InteractionController', () => {
+  it('owns active-tool transitions and publishes their effects', () => {
+    const h = createHarness();
+    h.controller.tools.setTool('brush', { temporary: true });
+
+    expect(h.beforeSwitch).toHaveBeenCalledWith('view', 'brush', { temporary: true });
+    expect(h.view.onDeactivate).toHaveBeenCalledOnce();
+    expect(h.brush.onActivate).toHaveBeenCalledOnce();
+    expect(h.controller.getActiveToolId()).toBe('brush');
+    expect(h.publishActiveTool).toHaveBeenCalledWith('brush');
+    expect(h.updateCursor).toHaveBeenCalledOnce();
+    expect(h.invalidateOverlay).toHaveBeenCalledOnce();
+  });
+
+  it('blocks non-view transitions while locked and ignores commands after disposal', () => {
+    const h = createHarness();
+    h.lock();
+    h.controller.setTool('brush');
+    expect(h.controller.getActiveToolId()).toBe('view');
+
+    h.controller.tools.stepBrushSize(1);
+    expect(h.stepBrushSize).toHaveBeenCalledWith(1);
+    h.controller.dispose();
+    h.controller.dispose();
+    h.controller.tools.stepBrushSize(-1);
+    expect(h.stepBrushSize).toHaveBeenCalledOnce();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/interactionController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/interactionController.ts
new file mode 100644
index 00000000000..e017b9ca35f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/interactionController.ts
@@ -0,0 +1,60 @@
+import type { CanvasToolCapability } from '@workbench/canvas-engine/api';
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { ToolId } from '@workbench/canvas-engine/types';
+
+export interface InteractionControllerOptions {
+  readonly initialToolId?: ToolId;
+  readonly getTool: (toolId: ToolId) => Tool | undefined;
+  readonly getToolContext: () => ToolContext;
+  readonly isLocked: () => boolean;
+  readonly beforeSwitch?: (from: ToolId, to: ToolId, options?: { temporary?: boolean }) => void;
+  readonly publishActiveTool: (toolId: ToolId) => void;
+  readonly updateCursor: () => void;
+  readonly invalidateOverlay: () => void;
+  readonly stepBrushSize: (direction: 1 | -1) => void;
+}
+
+/** Owns active-tool transitions and the public tool command boundary. */
+export class InteractionController {
+  readonly tools: CanvasToolCapability;
+  private activeToolId: ToolId;
+  private disposed = false;
+
+  constructor(private readonly options: InteractionControllerOptions) {
+    this.activeToolId = options.initialToolId ?? 'view';
+    this.tools = {
+      setTool: (toolId, switchOptions) => this.setTool(toolId, switchOptions),
+      stepBrushSize: (direction) => {
+        if (!this.disposed) {
+          options.stepBrushSize(direction);
+        }
+      },
+    };
+  }
+
+  getActiveToolId(): ToolId {
+    return this.activeToolId;
+  }
+
+  getActiveTool(): Tool | undefined {
+    return this.options.getTool(this.activeToolId);
+  }
+
+  setTool(toolId: ToolId, switchOptions?: { temporary?: boolean }): void {
+    if (this.disposed || (this.options.isLocked() && toolId !== 'view') || toolId === this.activeToolId) {
+      return;
+    }
+    const previous = this.activeToolId;
+    this.options.beforeSwitch?.(previous, toolId, switchOptions);
+    this.options.getTool(previous)?.onDeactivate?.(this.options.getToolContext(), switchOptions);
+    this.activeToolId = toolId;
+    this.options.getTool(toolId)?.onActivate?.(this.options.getToolContext(), switchOptions);
+    this.options.publishActiveTool(toolId);
+    this.options.updateCursor();
+    this.options.invalidateOverlay();
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerController.test.ts
new file mode 100644
index 00000000000..9ac7241f41e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerController.test.ts
@@ -0,0 +1,200 @@
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { LayerController } from './layerController';
+import { StructuralLayerController } from './structuralLayerController';
+
+describe('LayerController', () => {
+  const mask = {
+    applyImagePatch: vi.fn(),
+    canEdit: () => true,
+    deleteDerived: vi.fn(),
+    discardPersisted: vi.fn(),
+    dispatch: vi.fn(),
+    endBurst: vi.fn(),
+    getDocument: () => null,
+    history: {} as never,
+    isCacheReady: () => false,
+    isGestureActive: () => false,
+    layers: {} as never,
+    markDirty: vi.fn(),
+    notifyPainted: vi.fn(),
+    restoreCache: vi.fn(),
+  };
+  const thumbnail = {
+    backend: {} as never,
+    getActiveProjectId: () => null,
+    getCheckerboard: vi.fn(),
+    getDocument: () => null,
+    getEntry: () => undefined,
+    getMaskPattern: () => null,
+    isDisposed: () => false,
+    isSupportedSource: () => true,
+    projectId: 'p1',
+    rasterize: vi.fn(),
+    reportError: vi.fn(),
+    setStatus: vi.fn(),
+  };
+  const structural = new StructuralLayerController({
+    canEdit: () => true,
+    dispatch: vi.fn(),
+    getDocument: () => null,
+    history: { push: vi.fn() } as never,
+    isGestureActive: () => false,
+  });
+  const rasterize = {
+    backend: {} as never,
+    canEdit: () => true,
+    dispatch: vi.fn(),
+    endBurst: vi.fn(),
+    getDocument: () => null,
+    history: {} as never,
+    isGestureActive: () => false,
+    layers: {} as never,
+    markDirty: vi.fn(),
+    notifyPainted: vi.fn(),
+    rasterizeDeps: vi.fn(),
+  };
+  const merge = {
+    backend: {} as never,
+    canEdit: () => true,
+    capturePermit: () => null,
+    createLayerId: () => 'merged',
+    dispatch: vi.fn(),
+    dispatchPrepared: vi.fn(),
+    endBurst: vi.fn(),
+    exportBaked: vi.fn(),
+    getDocument: () => null,
+    getReducerDocument: () => null,
+    hasExportableContent: () => false,
+    history: {} as never,
+    installPrepared: vi.fn(),
+    isCacheReady: () => true,
+    isGestureActive: () => false,
+    isGuardCurrent: () => true,
+    isPermitCurrent: () => true,
+    layers: {} as never,
+    markDirty: vi.fn(),
+    notifyPainted: vi.fn(),
+    preparePixels: vi.fn(),
+  };
+  const booleanMerge = {
+    backend: {} as never,
+    capturePermit: () => null,
+    createLayerId: () => 'result',
+    dispatchPrepared: vi.fn(),
+    endBurst: vi.fn(),
+    exportBaked: vi.fn(),
+    getDocument: () => null,
+    getReducerDocument: () => null,
+    history: {} as never,
+    installPrepared: vi.fn(),
+    isCacheReady: () => true,
+    isGestureActive: () => false,
+    isGuardCurrent: () => true,
+    isPermitCurrent: () => true,
+    preparePixels: vi.fn(),
+  };
+  const extractMaskedArea = {
+    backend: {} as never,
+    capturePermit: () => null,
+    createLayerId: () => 'result',
+    derived: {} as never,
+    diagnostics: {} as never,
+    dispatchPrepared: vi.fn(),
+    endBurst: vi.fn(),
+    exportBaked: vi.fn(),
+    getAdjustedSurface: vi.fn(),
+    getDocument: () => null,
+    getMaskPattern: () => null,
+    getReducerDocument: () => null,
+    hasExportableContent: () => false,
+    history: {} as never,
+    installPrepared: vi.fn(),
+    isCacheReady: () => true,
+    isGestureActive: () => false,
+    isGuardCurrent: () => true,
+    isPermitCurrent: () => true,
+    layers: {} as never,
+    preparePixels: vi.fn(),
+    rasterize: vi.fn(),
+  };
+  const crop = {
+    backend: {} as never,
+    captureCache: vi.fn(),
+    capturePermit: () => null,
+    discardPersisted: vi.fn(),
+    dispatchPrepared: vi.fn(),
+    endBurst: vi.fn(),
+    exportBaked: vi.fn(),
+    getDocument: () => null,
+    getReducerDocument: () => null,
+    history: {} as never,
+    installPrepared: vi.fn(),
+    isGestureActive: () => false,
+    isGuardCurrent: () => true,
+    isPermitCurrent: () => true,
+    isSupportedSource: () => true,
+    preparePixels: vi.fn(),
+  };
+  const copy = {
+    capturePermit: () => null,
+    createLayerId: () => 'copy',
+    dispatchPrepared: vi.fn(),
+    endBurst: vi.fn(),
+    exportBaked: vi.fn(),
+    getDocument: () => null,
+    getReducerDocument: () => null,
+    history: {} as never,
+    installPrepared: vi.fn(),
+    isGestureActive: () => false,
+    isGuardCurrent: () => true,
+    isPermitCurrent: () => true,
+    preparePixels: vi.fn(),
+  };
+  it('exposes only declared layer and preview ports', async () => {
+    const forward: CanvasProjectMutation = { id: 'layer', type: 'setCanvasSelectedLayer' };
+    const inverse: CanvasProjectMutation = { id: null, type: 'setCanvasSelectedLayer' };
+    const deps = {
+      commitGeneratedImageResult: vi.fn(() => Promise.resolve({ layerId: 'copy', status: 'committed' as const })),
+      mask,
+      booleanMerge,
+      extractMaskedArea,
+      crop,
+      copy,
+      merge,
+      thumbnail,
+      structural,
+      rasterize,
+    };
+    const controller = new LayerController(deps);
+
+    expect(controller.layers.applyStructuralPreview(forward)).toBe(true);
+    controller.layers.commitStructural('edit', forward, inverse);
+    expect(controller.previews.drawLayerThumbnail('layer', {} as HTMLCanvasElement, 96)).toBe(false);
+    await expect(controller.previews.requestLayerThumbnail('layer')).resolves.toBe('stale');
+  });
+
+  it('disposes idempotently and rejects later mutations', () => {
+    const deps = {
+      commitGeneratedImageResult: vi.fn(() => Promise.resolve({ layerId: 'copy', status: 'committed' as const })),
+      mask,
+      booleanMerge,
+      extractMaskedArea,
+      crop,
+      copy,
+      merge,
+      thumbnail,
+      structural,
+      rasterize,
+    };
+    const controller = new LayerController(deps);
+    controller.dispose();
+    controller.dispose();
+
+    expect(controller.layers.applyStructuralPreview({} as CanvasProjectMutation)).toBe(false);
+    controller.layers.commitStructural('late', {} as CanvasProjectMutation, {} as CanvasProjectMutation);
+    expect(controller.previews.drawLayerThumbnail('layer', {} as HTMLCanvasElement, 96)).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerController.ts
new file mode 100644
index 00000000000..0318b34f9f6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerController.ts
@@ -0,0 +1,83 @@
+import type { CanvasLayerCapability, CanvasPreviewCapability } from '@workbench/canvas-engine/api';
+
+import type { MaskLayerControllerOptions } from './maskLayerController';
+import type { StructuralLayerController } from './structuralLayerController';
+
+import { BooleanMergeController, type BooleanMergeControllerOptions } from './booleanMergeController';
+import { CopyLayerController, type CopyLayerControllerOptions } from './copyLayerController';
+import { CropLayerController, type CropLayerControllerOptions } from './cropLayerController';
+import { ExtractMaskedAreaController, type ExtractMaskedAreaControllerOptions } from './extractMaskedAreaController';
+import { MaskLayerController } from './maskLayerController';
+import { MergeLayerController, type MergeLayerControllerOptions } from './mergeLayerController';
+import { RasterizeLayerController, type RasterizeLayerControllerOptions } from './rasterizeLayerController';
+import { ThumbnailController, type ThumbnailControllerOptions } from './thumbnailController';
+
+export type LayerControllerDeps = Omit<
+  CanvasLayerCapability,
+  'applyStructuralPreview' | 'canCommitStructural' | 'commitStagedImage' | 'commitStructural' | 'invertMask'
+> &
+  Omit<CanvasPreviewCapability, 'drawLayerThumbnail' | 'requestLayerThumbnail'> & {
+    mask: MaskLayerControllerOptions;
+    thumbnail: ThumbnailControllerOptions;
+    structural: StructuralLayerController;
+    rasterize: RasterizeLayerControllerOptions;
+    merge: MergeLayerControllerOptions;
+    booleanMerge: BooleanMergeControllerOptions;
+    extractMaskedArea: ExtractMaskedAreaControllerOptions;
+    crop: CropLayerControllerOptions;
+    copy: CopyLayerControllerOptions;
+  };
+
+/** Public layer-operation boundary. Implementations are injected by the composition root. */
+export class LayerController {
+  readonly layers: Omit<CanvasLayerCapability, 'commitStagedImage'>;
+  readonly previews: CanvasPreviewCapability;
+  readonly mask: MaskLayerController;
+  readonly thumbnail: ThumbnailController;
+  readonly structural: StructuralLayerController;
+  readonly rasterize: RasterizeLayerController;
+  readonly merge: MergeLayerController;
+  readonly booleanMerge: BooleanMergeController;
+  readonly extractMaskedArea: ExtractMaskedAreaController;
+  readonly crop: CropLayerController;
+  readonly copy: CopyLayerController;
+  private disposed = false;
+
+  constructor(deps: LayerControllerDeps) {
+    this.mask = new MaskLayerController(deps.mask);
+    this.thumbnail = new ThumbnailController(deps.thumbnail);
+    this.structural = deps.structural;
+    this.rasterize = new RasterizeLayerController(deps.rasterize);
+    this.merge = new MergeLayerController(deps.merge);
+    this.booleanMerge = new BooleanMergeController(deps.booleanMerge);
+    this.extractMaskedArea = new ExtractMaskedAreaController(deps.extractMaskedArea);
+    this.crop = new CropLayerController(deps.crop);
+    this.copy = new CopyLayerController(deps.copy);
+    this.layers = {
+      applyStructuralPreview: (action) => (this.disposed ? false : this.structural.preview(action)),
+      canCommitStructural: () => this.structural.canCommit(),
+      commitGeneratedImageResult: (options) =>
+        this.disposed ? Promise.resolve({ status: 'aborted' }) : deps.commitGeneratedImageResult(options),
+      commitStructural: (label, forward, inverse) => this.structural.commit(label, forward, inverse),
+      invertMask: (layerId) => (this.disposed ? false : this.mask.invert(layerId)),
+    };
+    this.previews = {
+      drawLayerThumbnail: (layerId, target, maxSize) =>
+        this.disposed ? false : this.thumbnail.draw(layerId, target, maxSize),
+      requestLayerThumbnail: (layerId) => (this.disposed ? Promise.resolve('stale') : this.thumbnail.request(layerId)),
+    };
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.mask.dispose();
+    this.thumbnail.dispose();
+    this.structural.dispose();
+    this.rasterize.dispose();
+    this.merge.dispose();
+    this.booleanMerge.dispose();
+    this.extractMaskedArea.dispose();
+    this.crop.dispose();
+    this.copy.dispose();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerMutationController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerMutationController.ts
new file mode 100644
index 00000000000..6583424137b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/layerMutationController.ts
@@ -0,0 +1,134 @@
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { PreparedLayerCacheReplacement } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+export type CapturedLayerCache = { pixels: RasterSurface; rect: Rect } | null | 'not-ready';
+
+export interface LayerMutationControllerOptions {
+  readonly canEdit: () => boolean;
+  readonly captureCache: (layer: CanvasLayerContract, document: CanvasDocumentContractV2) => CapturedLayerCache;
+  readonly discardPersisted: (layerId: string) => void;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    reducerAccepted: () => boolean,
+    mirrorAccepted: () => boolean
+  ) => void;
+  readonly endBurst: () => void;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly history: History;
+  readonly installPrepared: (prepared: PreparedLayerCacheReplacement, persist?: boolean) => void;
+  readonly isGestureActive: () => boolean;
+  readonly needsPixelPersistence: (layer: CanvasLayerContract) => boolean;
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => PreparedLayerCacheReplacement;
+  readonly sameContract: (document: CanvasDocumentContractV2 | null, layer: CanvasLayerContract) => boolean;
+}
+
+/** Owns failure-atomic copy and cross-type conversion mutations. */
+export class LayerMutationController {
+  constructor(private readonly options: LayerMutationControllerOptions) {}
+
+  copy(label: string, sourceLayerId: string, layer: CanvasLayerContract, index: number): boolean {
+    const o = this.options;
+    if (!o.canEdit() || o.isGestureActive()) {
+      return false;
+    }
+    o.endBurst();
+    const document = o.getDocument();
+    const source = document?.layers.find((candidate) => candidate.id === sourceLayerId);
+    if (!document || !source || document.layers.some((candidate) => candidate.id === layer.id)) {
+      return false;
+    }
+    const captured = o.captureCache(source, document);
+    if (captured === 'not-ready') {
+      return false;
+    }
+    const selectedLayerId = document.selectedLayerId;
+    const apply = (): void => {
+      const prepared = captured ? o.preparePixels(layer.id, captured.rect, captured.pixels) : null;
+      o.dispatchPrepared(
+        {
+          add: { index, layers: [layer] },
+          enabledUpdates: [],
+          selectedLayerId: layer.id,
+          type: 'applyCanvasLayerStackMutation',
+        },
+        () =>
+          o.getReducerDocument()?.selectedLayerId === layer.id &&
+          o.getReducerDocument()?.layers.some((candidate) => candidate === layer) === true,
+        () =>
+          o.getDocument()?.selectedLayerId === layer.id &&
+          o.getDocument()?.layers.some((candidate) => candidate === layer) === true
+      );
+      if (prepared) {
+        o.installPrepared(prepared, o.needsPixelPersistence(layer));
+      }
+    };
+    apply();
+    o.history.push({
+      bytes: captured ? captured.rect.width * captured.rect.height * 4 + 256 : 256,
+      label,
+      redo: apply,
+      replayFailureAtomic: true,
+      undo: () =>
+        o.dispatchPrepared(
+          { enabledUpdates: [], removeIds: [layer.id], selectedLayerId, type: 'applyCanvasLayerStackMutation' },
+          () =>
+            o.getReducerDocument()?.selectedLayerId === selectedLayerId &&
+            o.getReducerDocument()?.layers.some((candidate) => candidate.id === layer.id) === false,
+          () =>
+            o.getDocument()?.selectedLayerId === selectedLayerId &&
+            o.getDocument()?.layers.some((candidate) => candidate.id === layer.id) === false
+        ),
+    });
+    return true;
+  }
+
+  convert(label: string, expected: CanvasLayerContract, after: CanvasLayerContract): boolean {
+    const o = this.options;
+    if (!o.canEdit() || o.isGestureActive() || expected.id !== after.id || expected.type === after.type) {
+      return false;
+    }
+    o.endBurst();
+    const document = o.getDocument();
+    const current = document?.layers.find((candidate) => candidate.id === expected.id);
+    if (!document || !current || current !== expected || current.isLocked || current.type !== expected.type) {
+      return false;
+    }
+    const captured = o.captureCache(current, document);
+    if (captured === 'not-ready') {
+      return false;
+    }
+    const apply = (layer: CanvasLayerContract): void => {
+      const prepared = captured ? o.preparePixels(layer.id, captured.rect, captured.pixels) : null;
+      o.dispatchPrepared(
+        { id: layer.id, layer, targetType: layer.type, type: 'convertCanvasLayer' },
+        () => o.sameContract(o.getReducerDocument(), layer),
+        () => o.sameContract(o.getDocument(), layer)
+      );
+      try {
+        o.discardPersisted(layer.id);
+      } catch {
+        /* Ancillary after reducer acceptance. */
+      }
+      if (prepared) {
+        o.installPrepared(prepared, o.needsPixelPersistence(layer));
+      }
+    };
+    const before = structuredClone(current);
+    apply(after);
+    o.history.push({
+      bytes: captured ? captured.rect.width * captured.rect.height * 4 + 256 : 256,
+      label,
+      redo: () => apply(after),
+      replayFailureAtomic: true,
+      undo: () => apply(before),
+    });
+    return true;
+  }
+
+  dispose(): void {}
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/maskLayerController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/maskLayerController.ts
new file mode 100644
index 00000000000..66859a118ac
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/maskLayerController.ts
@@ -0,0 +1,140 @@
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { ImagePatchApply } from '@workbench/canvas-engine/history/imagePatch';
+import type { LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasImageRef, CanvasLayerContract } from '@workbench/types';
+
+import { getSourceContentRect, isMaskLayer } from '@workbench/canvas-engine/document/sources';
+import { createImagePatchEntry } from '@workbench/canvas-engine/history/imagePatch';
+import { invert as invertMatrix } from '@workbench/canvas-engine/math/mat2d';
+import { isEmpty, roundOut, transformBounds, union } from '@workbench/canvas-engine/math/rect';
+import { bakeMatrix } from '@workbench/canvas-engine/transform/transformMath';
+
+export interface MaskLayerControllerOptions {
+  readonly layers: LayerCacheStore;
+  readonly history: History;
+  readonly applyImagePatch: ImagePatchApply;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly canEdit: () => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly isCacheReady: (layer: CanvasLayerContract, document: CanvasDocumentContractV2) => boolean;
+  readonly endBurst: () => void;
+  readonly discardPersisted: (layerId: string) => void;
+  readonly markDirty: (layerId: string) => void;
+  readonly dispatch: (action: CanvasProjectMutation) => void;
+  readonly deleteDerived: (layerId: string) => void;
+  readonly notifyPainted: (layerId: string) => void;
+  readonly restoreCache: (layerId: string, rect: Rect, pixels: ImageData) => void;
+}
+
+/** Owns destructive mask pixel operations and their history/persistence lifecycle. */
+export class MaskLayerController {
+  private disposed = false;
+
+  constructor(private readonly deps: MaskLayerControllerOptions) {}
+
+  clear(layerId: string): boolean {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return false;
+    }
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer || !isMaskLayer(layer) || layer.isLocked) {
+      return false;
+    }
+    const originalBitmap = layer.mask.bitmap;
+    const originalOffset = layer.mask.offset ?? { x: 0, y: 0 };
+    const entry = this.deps.isCacheReady(layer, document) ? this.deps.layers.get(layerId) : undefined;
+    const rect = entry && !isEmpty(entry.rect) ? { ...entry.rect } : null;
+    const before = rect ? entry?.surface.ctx.getImageData(0, 0, rect.width, rect.height) : null;
+    if (!originalBitmap && (!before || !rect)) {
+      return false;
+    }
+    this.deps.endBurst();
+    const dispatchMask = (bitmap: CanvasImageRef | null, offset: { x: number; y: number }): void => {
+      this.deps.dispatch({
+        config: { layerType: layer.type, mask: { bitmap, offset } },
+        id: layerId,
+        type: 'updateCanvasLayerConfig',
+      });
+    };
+    const applyClear = (): void => {
+      this.deps.discardPersisted(layerId);
+      dispatchMask(null, { x: 0, y: 0 });
+      this.deps.layers.delete(layerId);
+      this.deps.deleteDerived(layerId);
+      const empty = this.deps.layers.getOrCreateRect(layerId, { height: 0, width: 0, x: 0, y: 0 });
+      empty.stale = false;
+      this.deps.notifyPainted(layerId);
+    };
+    const applyRestore = (): void => {
+      this.deps.discardPersisted(layerId);
+      dispatchMask(originalBitmap, originalOffset);
+      if (before && rect) {
+        this.deps.restoreCache(layerId, rect, before);
+      }
+    };
+    applyClear();
+    this.deps.history.push({
+      bytes: (before?.data.byteLength ?? 0) + 256,
+      label: 'Clear mask',
+      redo: applyClear,
+      undo: applyRestore,
+    });
+    return true;
+  }
+
+  invert(layerId: string): boolean {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return false;
+    }
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer || !isMaskLayer(layer) || layer.isLocked || !layer.isEnabled) {
+      return false;
+    }
+    if (!this.deps.isCacheReady(layer, document)) {
+      return false;
+    }
+    const content = getSourceContentRect(layer, document);
+    const liveRect = this.deps.layers.get(layerId)?.rect;
+    const contentUnion =
+      liveRect && !isEmpty(liveRect) ? (isEmpty(content) ? liveRect : union(content, liveRect)) : content;
+    const inverse = invertMatrix(bakeMatrix(layer.transform));
+    const bbox = inverse ? roundOut(transformBounds(inverse, document.bbox)) : document.bbox;
+    const domain = roundOut(isEmpty(contentUnion) ? bbox : union(contentUnion, bbox));
+    if (isEmpty(domain)) {
+      return false;
+    }
+    this.deps.endBurst();
+    const entry = this.deps.layers.growToRect(layerId, domain);
+    const readX = domain.x - entry.rect.x;
+    const readY = domain.y - entry.rect.y;
+    const before = entry.surface.ctx.getImageData(readX, readY, domain.width, domain.height);
+    const work = entry.surface.ctx.getImageData(readX, readY, domain.width, domain.height);
+    for (let index = 3; index < work.data.length; index += 4) {
+      work.data[index] = 255 - (work.data[index] ?? 0);
+    }
+    entry.surface.ctx.putImageData(work, readX, readY);
+    this.deps.notifyPainted(layerId);
+    this.deps.markDirty(layerId);
+    if (!this.deps.history.isApplying()) {
+      this.deps.history.push(
+        createImagePatchEntry({
+          after: work,
+          apply: this.deps.applyImagePatch,
+          before,
+          label: 'Invert mask',
+          layerId,
+          rect: domain,
+        })
+      );
+    }
+    return true;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/maskResultController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/maskResultController.ts
new file mode 100644
index 00000000000..d884b932d14
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/maskResultController.ts
@@ -0,0 +1,137 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasImageRef } from '@workbench/types';
+
+import {
+  createInpaintMaskFromImage,
+  createRegionalGuidanceFromImage,
+  DEFAULT_INPAINT_MASK_FILL,
+  nextInpaintMaskName,
+  nextRegionalGuidanceFillColor,
+  nextRegionalGuidanceName,
+} from '@workbench/canvas-engine/document/layerFactories';
+
+export type MaskImageResultTarget = 'inpaint_mask' | 'regional_guidance';
+export interface CommitMaskImageResultOptions {
+  guard: LayerExportGuard;
+  image: CanvasImageRef;
+  rect: Rect;
+  target: MaskImageResultTarget;
+  signal?: AbortSignal;
+}
+export type CommitMaskImageResult =
+  | { status: 'committed'; layerId: string }
+  | { status: 'aborted' | 'missing' | 'locked' | 'stale' | 'unsupported' | 'busy' };
+
+export interface MaskResultControllerOptions<Owner = symbol> {
+  readonly canEdit: (owner?: Owner) => boolean;
+  readonly createLayerId: () => string;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    reducerAccepted: () => boolean,
+    mirrorAccepted: () => boolean
+  ) => void;
+  readonly endBurst: () => void;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly history: History;
+  readonly isGestureActive: () => boolean;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+}
+
+/** Converts a guarded object-selection result into a structural mask layer. */
+export class MaskResultController<Owner = symbol> {
+  constructor(private readonly options: MaskResultControllerOptions<Owner>) {}
+
+  commit(options: CommitMaskImageResultOptions, owner?: Owner): Promise<CommitMaskImageResult> {
+    const o = this.options;
+    if (!o.canEdit(owner)) {
+      return Promise.resolve({ status: 'busy' });
+    }
+    if (options.signal?.aborted) {
+      return Promise.resolve({ status: 'aborted' });
+    }
+    const document = o.getDocument();
+    if (!document) {
+      return Promise.resolve({ status: 'missing' });
+    }
+    const liveLayer = document.layers.find((candidate) => candidate.id === options.guard.layerId);
+    if (!liveLayer) {
+      return Promise.resolve({ status: 'missing' });
+    }
+    if (liveLayer.isLocked) {
+      return Promise.resolve({ status: 'locked' });
+    }
+    if (liveLayer.type !== 'raster' && liveLayer.type !== 'control') {
+      return Promise.resolve({ status: 'unsupported' });
+    }
+    const sourceIndex = document.layers.findIndex((candidate) => candidate.id === liveLayer.id);
+    if (o.isGestureActive()) {
+      return Promise.resolve({ status: 'busy' });
+    }
+    if (!o.isGuardCurrent(options.guard)) {
+      return Promise.resolve({ status: 'stale' });
+    }
+    if (options.signal?.aborted) {
+      return Promise.resolve({ status: 'aborted' });
+    }
+    if (sourceIndex < 0) {
+      return Promise.resolve({ status: 'missing' });
+    }
+    const names = document.layers.map((layer) => layer.name);
+    const layerId = o.createLayerId();
+    const layer =
+      options.target === 'inpaint_mask'
+        ? createInpaintMaskFromImage({
+            fill: DEFAULT_INPAINT_MASK_FILL,
+            id: layerId,
+            image: options.image,
+            name: nextInpaintMaskName(names),
+            rect: options.rect,
+          })
+        : createRegionalGuidanceFromImage({
+            fill: {
+              color: nextRegionalGuidanceFillColor(
+                document.layers.filter((candidate) => candidate.type === 'regional_guidance').length
+              ),
+              style: 'solid',
+            },
+            id: layerId,
+            image: options.image,
+            name: nextRegionalGuidanceName(names),
+            rect: options.rect,
+          });
+    const selectedLayerId = document.selectedLayerId;
+    const apply = (): void =>
+      o.dispatchPrepared(
+        { index: sourceIndex, layer, type: 'addCanvasLayer' },
+        () => o.getReducerDocument()?.layers.some((candidate) => candidate === layer) === true,
+        () => o.getDocument()?.layers.some((candidate) => candidate === layer) === true
+      );
+    o.endBurst();
+    apply();
+    o.history.push({
+      bytes: 256,
+      label: options.target === 'inpaint_mask' ? 'Create inpaint mask from object' : 'Create region from object',
+      redo: apply,
+      replayFailureAtomic: true,
+      undo: () => {
+        o.dispatchPrepared(
+          { id: selectedLayerId, type: 'setCanvasSelectedLayer' },
+          () => o.getReducerDocument()?.selectedLayerId === selectedLayerId,
+          () => o.getDocument()?.selectedLayerId === selectedLayerId
+        );
+        o.dispatchPrepared(
+          { ids: [layerId], type: 'removeCanvasLayers' },
+          () => o.getReducerDocument()?.layers.some((candidate) => candidate.id === layerId) === false,
+          () => o.getDocument()?.layers.some((candidate) => candidate.id === layerId) === false
+        );
+      },
+    });
+    return Promise.resolve({ layerId, status: 'committed' });
+  }
+
+  dispose(): void {}
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/mergeLayerController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/mergeLayerController.ts
new file mode 100644
index 00000000000..2fcd2e08c3e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/mergeLayerController.ts
@@ -0,0 +1,285 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { mergeDownMatrix } from '@workbench/canvas-engine/document/mergeDown';
+import { getMergeVisibleRasterLayers } from '@workbench/canvas-engine/document/mergeVisible';
+import { isMergeableRasterLayer } from '@workbench/canvas-engine/document/sources';
+import { isEmpty, roundOut, transformBounds, union } from '@workbench/canvas-engine/math/rect';
+import { blendToComposite } from '@workbench/canvas-engine/render/compositor';
+
+export type MergeVisibleResult = 'merged' | 'not-ready' | 'busy' | 'nothing';
+
+type ExportResult =
+  | { status: 'ok'; surface: RasterSurface; rect: Rect; guard: LayerExportGuard; release(): void }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' };
+
+export interface MergeLayerControllerOptions {
+  readonly backend: RasterBackend;
+  readonly history: History;
+  readonly layers: LayerCacheStore;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getReducerDocument: () => CanvasDocumentContractV2 | null;
+  readonly canEdit: () => boolean;
+  readonly capturePermit: () => object | null;
+  readonly isPermitCurrent: (permit: object) => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly isCacheReady: (layer: CanvasLayerContract, document: CanvasDocumentContractV2) => boolean;
+  readonly hasExportableContent: (layerId: string) => boolean;
+  readonly exportBaked: (layerId: string) => Promise<ExportResult>;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly createLayerId: () => string;
+  readonly preparePixels: (layerId: string, rect: Rect, pixels: RasterSurface) => unknown;
+  readonly installPrepared: (prepared: unknown) => void;
+  readonly dispatchPrepared: (
+    action: CanvasProjectMutation,
+    expectedReducer: () => boolean,
+    expectedMirror: () => boolean
+  ) => void;
+  readonly endBurst: () => void;
+  readonly dispatch: (action: CanvasProjectMutation) => void;
+  readonly notifyPainted: (layerId: string) => void;
+  readonly markDirty: (layerId: string) => void;
+}
+
+/** Owns destructive merge-down and non-destructive merge-visible pixel operations. */
+export class MergeLayerController {
+  private disposed = false;
+
+  constructor(private readonly deps: MergeLayerControllerOptions) {}
+
+  mergeDown(upperLayerId: string): boolean {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return false;
+    }
+    this.deps.endBurst();
+    const document = this.deps.getDocument();
+    if (!document) {
+      return false;
+    }
+    const upperIndex = document.layers.findIndex((layer) => layer.id === upperLayerId);
+    const upper = document.layers[upperIndex];
+    const below = document.layers[upperIndex + 1];
+    if (upperIndex < 0 || !upper || !below || !isMergeableRasterLayer(upper) || !isMergeableRasterLayer(below)) {
+      return false;
+    }
+    const upperCache = this.deps.layers.get(upper.id);
+    const belowCache = this.deps.layers.get(below.id);
+    const upperHasContent = this.deps.hasExportableContent(upper.id);
+    const belowHasContent = this.deps.hasExportableContent(below.id);
+    if (
+      (upperHasContent && !upperCache) ||
+      (belowHasContent && !belowCache) ||
+      !this.deps.isCacheReady(upper, document) ||
+      !this.deps.isCacheReady(below, document)
+    ) {
+      return false;
+    }
+    const matrix = mergeDownMatrix(below.transform, upper.transform);
+    if (!matrix) {
+      return false;
+    }
+    if (!belowHasContent && !upperHasContent) {
+      this.deps.dispatch({
+        source: { bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' },
+        type: 'mergeCanvasLayersDown',
+        upperLayerId,
+      });
+      this.deps.layers.delete(below.id);
+      this.deps.notifyPainted(below.id);
+      this.deps.markDirty(below.id);
+      return true;
+    }
+    const mergedRect = roundOut(
+      belowHasContent && upperHasContent
+        ? union(belowCache!.rect, transformBounds(matrix, upperCache!.rect))
+        : belowHasContent
+          ? belowCache!.rect
+          : transformBounds(matrix, upperCache!.rect)
+    );
+    const merged = this.deps.backend.createSurface(mergedRect.width, mergedRect.height);
+    const context = merged.ctx;
+    context.setTransform(1, 0, 0, 1, 0, 0);
+    context.clearRect(0, 0, mergedRect.width, mergedRect.height);
+    if (belowHasContent) {
+      context.drawImage(
+        belowCache!.surface.canvas,
+        belowCache!.rect.x - mergedRect.x,
+        belowCache!.rect.y - mergedRect.y
+      );
+    }
+    if (upperHasContent) {
+      context.setTransform(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e - mergedRect.x, matrix.f - mergedRect.y);
+      context.globalAlpha = upper.opacity;
+      context.globalCompositeOperation = blendToComposite(upper.blendMode);
+      context.drawImage(upperCache!.surface.canvas, upperCache!.rect.x, upperCache!.rect.y);
+      context.setTransform(1, 0, 0, 1, 0, 0);
+      context.globalAlpha = 1;
+      context.globalCompositeOperation = 'source-over';
+    }
+    this.deps.dispatch({
+      source: { bitmap: null, offset: { x: mergedRect.x, y: mergedRect.y }, type: 'paint' },
+      type: 'mergeCanvasLayersDown',
+      upperLayerId,
+    });
+    this.deps.layers.delete(below.id);
+    const target = this.deps.layers.getOrCreateRect(below.id, mergedRect);
+    target.surface.ctx.drawImage(merged.canvas, 0, 0);
+    target.stale = false;
+    this.deps.notifyPainted(below.id);
+    this.deps.markDirty(below.id);
+    return true;
+  }
+
+  async mergeVisible(): Promise<MergeVisibleResult> {
+    const permit = this.deps.capturePermit();
+    if (this.disposed || !permit || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return 'busy';
+    }
+    this.deps.endBurst();
+    const document = this.deps.getDocument();
+    if (!document) {
+      return 'nothing';
+    }
+    const contributors = getMergeVisibleRasterLayers(document.layers, this.deps.hasExportableContent);
+    if (contributors.length < 2) {
+      return 'nothing';
+    }
+    const owned: Extract<ExportResult, { status: 'ok' }>[] = [];
+    const acquire = async (layerId: string): Promise<ExportResult> => {
+      const result = await this.deps.exportBaked(layerId);
+      if (result.status === 'ok') {
+        owned.push(result);
+      }
+      return result;
+    };
+    try {
+      const settled = await Promise.allSettled(contributors.map((layer) => acquire(layer.id)));
+      const rejected = settled.find((result) => result.status === 'rejected');
+      if (rejected?.status === 'rejected') {
+        throw rejected.reason instanceof Error ? rejected.reason : new Error(String(rejected.reason));
+      }
+      const exports = settled.map((result) => (result as PromiseFulfilledResult<ExportResult>).value);
+      if (!this.deps.isPermitCurrent(permit)) {
+        return 'busy';
+      }
+      if (exports.some((result) => result.status !== 'ok')) {
+        return 'not-ready';
+      }
+      if (this.deps.isGestureActive()) {
+        return 'busy';
+      }
+      for (let index = 0; index < exports.length; index += 1) {
+        const exported = exports[index];
+        const contributor = contributors[index];
+        if (
+          !exported ||
+          exported.status !== 'ok' ||
+          !contributor ||
+          exported.guard.layer !== contributor ||
+          !this.deps.isGuardCurrent(exported.guard)
+        ) {
+          return 'not-ready';
+        }
+      }
+
+      const liveDocument = this.deps.getDocument();
+      const liveContributors = liveDocument
+        ? getMergeVisibleRasterLayers(liveDocument.layers, this.deps.hasExportableContent)
+        : [];
+      if (
+        !liveDocument ||
+        liveContributors.length !== contributors.length ||
+        liveContributors.some((layer, index) => layer !== contributors[index])
+      ) {
+        return 'not-ready';
+      }
+
+      const successful = exports as Extract<ExportResult, { status: 'ok' }>[];
+      let rect = successful[0]!.rect;
+      for (let index = 1; index < successful.length; index += 1) {
+        rect = union(rect, successful[index]!.rect);
+      }
+      rect = roundOut(rect);
+      if (isEmpty(rect)) {
+        return 'nothing';
+      }
+      const pixels = this.deps.backend.createSurface(rect.width, rect.height);
+      const context = pixels.ctx;
+      context.setTransform(1, 0, 0, 1, 0, 0);
+      context.clearRect(0, 0, rect.width, rect.height);
+      for (let index = successful.length - 1; index >= 0; index -= 1) {
+        const exported = successful[index]!;
+        const contributor = contributors[index]!;
+        context.globalAlpha = contributor.opacity;
+        context.globalCompositeOperation = blendToComposite(contributor.blendMode);
+        context.drawImage(exported.surface.canvas, exported.rect.x - rect.x, exported.rect.y - rect.y);
+      }
+      context.globalAlpha = 1;
+      context.globalCompositeOperation = 'source-over';
+
+      const resultId = this.deps.createLayerId();
+      const resultLayer: CanvasLayerContract = {
+        blendMode: 'normal',
+        id: resultId,
+        isEnabled: true,
+        isLocked: false,
+        name: `${contributors[0]!.name} merged`,
+        opacity: 1,
+        source: { bitmap: null, offset: { x: rect.x, y: rect.y }, type: 'paint' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        type: 'raster',
+      };
+      const selectedLayerId = liveDocument.selectedLayerId;
+      const hasResult = (doc: CanvasDocumentContractV2 | null): boolean =>
+        doc?.selectedLayerId === resultId && doc.layers[0] === resultLayer;
+      const apply = (): void => {
+        const prepared = this.deps.preparePixels(resultId, rect, pixels);
+        this.deps.dispatchPrepared(
+          {
+            add: { index: 0, layers: [resultLayer] },
+            enabledUpdates: [],
+            selectedLayerId: resultId,
+            type: 'applyCanvasLayerStackMutation',
+          },
+          () => hasResult(this.deps.getReducerDocument()),
+          () => hasResult(this.deps.getDocument())
+        );
+        this.deps.installPrepared(prepared);
+      };
+      if (!this.deps.isPermitCurrent(permit)) {
+        return 'busy';
+      }
+      apply();
+      this.deps.history.push({
+        bytes: rect.width * rect.height * 4 + 256,
+        label: 'Merge visible',
+        redo: apply,
+        replayFailureAtomic: true,
+        undo: () =>
+          this.deps.dispatchPrepared(
+            { enabledUpdates: [], removeIds: [resultId], selectedLayerId, type: 'applyCanvasLayerStackMutation' },
+            () =>
+              this.deps.getReducerDocument()?.selectedLayerId === selectedLayerId &&
+              this.deps.getReducerDocument()?.layers.some((layer) => layer.id === resultId) === false,
+            () =>
+              this.deps.getDocument()?.selectedLayerId === selectedLayerId &&
+              this.deps.getDocument()?.layers.some((layer) => layer.id === resultId) === false
+          ),
+      });
+      return 'merged';
+    } finally {
+      for (const result of owned) {
+        result.release();
+      }
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/persistenceController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/persistenceController.test.ts
new file mode 100644
index 00000000000..aebfee5c2ab
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/persistenceController.test.ts
@@ -0,0 +1,27 @@
+import type { BitmapStore } from '@workbench/canvas-engine/document/bitmapStore';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { PersistenceController } from './persistenceController';
+
+const createStore = (): BitmapStore => ({
+  discardLayer: vi.fn(),
+  dispose: vi.fn(),
+  flushPendingUploads: vi.fn(() => Promise.resolve()),
+  isSelfEcho: vi.fn(() => false),
+  markLayerDirty: vi.fn(),
+  reset: vi.fn(),
+  suspendLayer: vi.fn(() => vi.fn()),
+});
+
+describe('PersistenceController', () => {
+  it('provides a flush barrier and idempotent disposal', async () => {
+    const store = createStore();
+    const controller = new PersistenceController(store);
+    await controller.flush();
+    expect(store.flushPendingUploads).toHaveBeenCalledOnce();
+    controller.dispose();
+    controller.dispose();
+    expect(store.dispose).toHaveBeenCalledOnce();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/persistenceController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/persistenceController.ts
new file mode 100644
index 00000000000..8193ed12db2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/persistenceController.ts
@@ -0,0 +1,22 @@
+import type { BitmapStore } from '@workbench/canvas-engine/document/bitmapStore';
+
+export class PersistenceController {
+  readonly store: BitmapStore;
+  private disposed = false;
+
+  constructor(store: BitmapStore) {
+    this.store = store;
+  }
+
+  flush(): Promise<void> {
+    return this.store.flushPendingUploads();
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.store.dispose();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/previewStateController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/previewStateController.ts
new file mode 100644
index 00000000000..25421a62d6a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/previewStateController.ts
@@ -0,0 +1,120 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+
+export interface StagedPreviewState {
+  surface: RasterSurface;
+  width: number;
+  height: number;
+  placement?: Rect & { opacity: number };
+}
+
+export interface FilterPreviewState {
+  surface: RasterSurface;
+  rect: Rect;
+  guard: LayerExportGuard;
+}
+
+export interface SamPreviewState {
+  data: RasterSurface;
+  rect: Rect;
+  guard: LayerExportGuard;
+  isolated: boolean;
+}
+
+/** Owns render-preview surfaces and monotonic async publication guards. */
+export class PreviewStateController {
+  private staged: StagedPreviewState | null = null;
+  private stagedToken = 0;
+  private readonly filters = new Map<string, FilterPreviewState>();
+  private readonly filterTokens = new Map<string, number>();
+  private readonly guardedFilterTokens = new Map<string, number>();
+  private sam: SamPreviewState | null = null;
+
+  getStaged(): StagedPreviewState | null {
+    return this.staged;
+  }
+  nextStagedToken(): number {
+    return ++this.stagedToken;
+  }
+  isStagedTokenCurrent(token: number): boolean {
+    return token === this.stagedToken;
+  }
+  publishStaged(token: number, preview: StagedPreviewState): boolean {
+    if (!this.isStagedTokenCurrent(token)) {
+      return false;
+    }
+    this.staged = preview;
+    return true;
+  }
+  clearStaged(): boolean {
+    this.stagedToken += 1;
+    const hadPreview = this.staged !== null;
+    this.staged = null;
+    return hadPreview;
+  }
+
+  hasFilter(layerId: string): boolean {
+    return this.filters.has(layerId);
+  }
+  getFilter(layerId: string): FilterPreviewState | undefined {
+    return this.filters.get(layerId);
+  }
+  filterSnapshot(): Map<string, FilterPreviewState> {
+    return new Map(this.filters);
+  }
+  filterLayerIds(): string[] {
+    return [...new Set([...this.filters.keys(), ...this.filterTokens.keys(), ...this.guardedFilterTokens.keys()])];
+  }
+  clearFilter(layerId: string): boolean {
+    this.filterTokens.set(layerId, (this.filterTokens.get(layerId) ?? 0) + 1);
+    this.guardedFilterTokens.delete(layerId);
+    return this.filters.delete(layerId);
+  }
+  beginGuardedFilter(layerId: string): number {
+    const token = (this.filterTokens.get(layerId) ?? 0) + 1;
+    this.filterTokens.set(layerId, token);
+    this.guardedFilterTokens.set(layerId, token);
+    return token;
+  }
+  finishGuardedFilter(layerId: string, token: number): void {
+    if (this.guardedFilterTokens.get(layerId) === token) {
+      this.guardedFilterTokens.delete(layerId);
+    }
+  }
+  isFilterTokenCurrent(layerId: string, token: number): boolean {
+    return this.filterTokens.get(layerId) === token;
+  }
+  publishFilter(layerId: string, token: number, preview: FilterPreviewState): boolean {
+    if (!this.isFilterTokenCurrent(layerId, token)) {
+      return false;
+    }
+    this.filters.set(layerId, preview);
+    return true;
+  }
+  clearFilters(): void {
+    for (const layerId of this.filterLayerIds()) {
+      this.clearFilter(layerId);
+    }
+  }
+
+  getSam(): SamPreviewState | null {
+    return this.sam;
+  }
+  setSam(preview: SamPreviewState): SamPreviewState | null {
+    const previous = this.sam;
+    this.sam = preview;
+    return previous;
+  }
+  clearSam(): SamPreviewState | null {
+    const previous = this.sam;
+    this.sam = null;
+    return previous;
+  }
+
+  dispose(): void {
+    this.clearStaged();
+    this.clearFilters();
+    this.sam = null;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/psdExportController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/psdExportController.test.ts
new file mode 100644
index 00000000000..577fc3f083a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/psdExportController.test.ts
@@ -0,0 +1,403 @@
+import type { CanvasDocumentSnapshot, CanvasRasterSnapshot } from '@workbench/canvas-engine/api';
+import type { ExecutePsdExportDeps, PsdExportPlan } from '@workbench/canvas-engine/export/psdExport';
+import type { CanvasDocumentContractV2, CanvasRasterLayerContractV2, CanvasStateContractV2 } from '@workbench/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { derivePsdPixelAreaLimit, PSD_ALLOCATION_BYTES_PER_PIXEL, PsdExportController } from './psdExportController';
+
+const document: CanvasDocumentContractV2 = {
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [
+    {
+      blendMode: 'normal',
+      id: 'layer',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Layer',
+      opacity: 1,
+      source: { image: { height: 100, imageName: 'layer.png', width: 100 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    },
+  ],
+  selectedLayerId: null,
+  version: 2,
+  width: 100,
+};
+
+const canvas: CanvasStateContractV2 = {
+  document,
+  documentRevision: 0,
+  snapshots: [],
+  stagingArea: {
+    areThumbnailsVisible: false,
+    autoSwitchMode: 'off',
+    isVisible: false,
+    pendingImageIds: [],
+    pendingImages: [],
+    selectedImageIndex: 0,
+  },
+  version: 2,
+};
+
+const canvasWithDocument = (nextDocument: CanvasDocumentContractV2): CanvasStateContractV2 => ({
+  ...canvas,
+  document: nextDocument,
+});
+
+describe('PsdExportController', () => {
+  it('derives the PSD allocation pixel-area limit from currently available reserved bytes', () => {
+    expect(derivePsdPixelAreaLimit(159_999)).toBe(19_999);
+    expect(derivePsdPixelAreaLimit(160_000)).toBe(20_000);
+  });
+
+  it('executes from one immutable raster snapshot instead of live layer pixels', async () => {
+    const backend = createTestStubRasterBackend();
+    const detached = backend.createSurface(100, 100);
+    const documentSnapshot: CanvasDocumentSnapshot = {
+      canvas,
+      documentGeneration: 4,
+    };
+    const release = vi.fn();
+    const rasterSnapshot: CanvasRasterSnapshot = {
+      ...documentSnapshot,
+      emptyLayerIds: new Set<string>(),
+      layerSurfaces: new Map([['layer', { rect: { height: 100, width: 100, x: 0, y: 0 }, surface: detached }]]),
+      release,
+    };
+    const captureRasterSnapshot = vi.fn(() => Promise.resolve({ snapshot: rasterSnapshot, status: 'ok' as const }));
+    const execute = vi.fn(async (_plan, _fileName, deps: ExecutePsdExportDeps) => {
+      await expect(deps.getLayerSurface('layer')).resolves.toEqual({
+        rect: { height: 100, width: 100, x: 0, y: 0 },
+        surface: detached,
+      });
+    });
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => documentSnapshot,
+      captureRasterSnapshot,
+      execute,
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent: () => true,
+      reserve: () => ({ lease: { release: vi.fn() }, status: 'ok' }),
+    });
+
+    await expect(controller.export('layers.psd')).resolves.toBe('exported');
+    expect(captureRasterSnapshot).toHaveBeenCalledWith(documentSnapshot, ['layer'], expect.any(Object));
+    expect(execute).toHaveBeenCalledOnce();
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('plans a new bitmap-less paint layer from its captured unflushed live pixels', async () => {
+    const backend = createTestStubRasterBackend();
+    const paintDocument: CanvasDocumentContractV2 = {
+      ...document,
+      layers: [
+        {
+          blendMode: 'normal',
+          id: 'paint',
+          isEnabled: true,
+          isLocked: false,
+          name: 'Paint',
+          opacity: 1,
+          source: { bitmap: null, type: 'paint' },
+          transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+          type: 'raster',
+        },
+      ],
+    };
+    const paintCanvas = canvasWithDocument(paintDocument);
+    const documentSnapshot: CanvasDocumentSnapshot = { canvas: paintCanvas, documentGeneration: 6 };
+    const rect = { height: 30, width: 20, x: -5, y: -6 };
+    const execute = vi.fn((plan) => {
+      expect(plan).toMatchObject({ height: 30, status: 'ok', width: 20 });
+      if (plan.status !== 'ok') {
+        throw new Error('Expected an executable PSD plan');
+      }
+      expect(plan.layers[0]?.contentRect).toEqual(rect);
+      return Promise.resolve();
+    });
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => documentSnapshot,
+      captureRasterSnapshot: () =>
+        Promise.resolve({
+          snapshot: {
+            ...documentSnapshot,
+            emptyLayerIds: new Set<string>(),
+            layerSurfaces: new Map([['paint', { rect, surface: backend.createSurface(20, 30) }]]),
+            release: vi.fn(),
+          },
+          status: 'ok',
+        }),
+      execute,
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent: () => true,
+      reserve: () => ({ lease: { release: vi.fn() }, status: 'ok' }),
+    });
+
+    await expect(controller.export('paint.psd')).resolves.toBe('exported');
+    expect(execute).toHaveBeenCalledOnce();
+  });
+
+  it('plans and reserves from a grown live-cache rect instead of smaller persisted source bounds', async () => {
+    const backend = createTestStubRasterBackend();
+    const smallLayer: CanvasRasterLayerContractV2 = {
+      ...(document.layers[0] as CanvasRasterLayerContractV2),
+      source: { image: { height: 10, imageName: 'small.png', width: 10 }, type: 'image' },
+    };
+    const smallDocument: CanvasDocumentContractV2 = {
+      ...document,
+      layers: [smallLayer],
+    };
+    const grownCanvas = canvasWithDocument(smallDocument);
+    const documentSnapshot: CanvasDocumentSnapshot = { canvas: grownCanvas, documentGeneration: 7 };
+    const grownRect = { height: 40, width: 30, x: -12, y: -8 };
+    const reserve = vi.fn(() => ({ lease: { release: vi.fn() }, status: 'ok' as const }));
+    const execute = vi.fn((plan) => {
+      expect(plan).toMatchObject({ height: 40, status: 'ok', width: 30 });
+      if (plan.status !== 'ok') {
+        throw new Error('Expected an executable PSD plan');
+      }
+      expect(plan.layers[0]?.contentRect).toEqual(grownRect);
+      return Promise.resolve();
+    });
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => documentSnapshot,
+      captureRasterSnapshot: () =>
+        Promise.resolve({
+          snapshot: {
+            ...documentSnapshot,
+            emptyLayerIds: new Set<string>(),
+            layerSurfaces: new Map([['layer', { rect: grownRect, surface: backend.createSurface(30, 40) }]]),
+            release: vi.fn(),
+          },
+          status: 'ok',
+        }),
+      execute,
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent: () => true,
+      reserve,
+    });
+
+    await expect(controller.export('grown.psd')).resolves.toBe('exported');
+    expect(reserve).toHaveBeenCalledWith(30 * 40 * 2 * PSD_ALLOCATION_BYTES_PER_PIXEL);
+  });
+
+  it('exports valid captured pixels while skipping a confirmed-empty paint layer', async () => {
+    const backend = createTestStubRasterBackend();
+    const validLayer = document.layers[0] as CanvasRasterLayerContractV2;
+    const blankLayer: CanvasRasterLayerContractV2 = {
+      ...validLayer,
+      id: 'blank',
+      name: 'Blank',
+      source: { bitmap: null, type: 'paint' },
+    };
+    const mixedCanvas = canvasWithDocument({ ...document, layers: [validLayer, blankLayer] });
+    const documentSnapshot: CanvasDocumentSnapshot = { canvas: mixedCanvas, documentGeneration: 8 };
+    const execute = vi.fn((plan: PsdExportPlan) => {
+      if (plan.status !== 'ok') {
+        throw new Error('Expected an executable PSD plan');
+      }
+      expect(plan.layers.map((layer) => layer.id)).toEqual(['layer']);
+      return Promise.resolve();
+    });
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => documentSnapshot,
+      captureRasterSnapshot: () =>
+        Promise.resolve({
+          snapshot: {
+            ...documentSnapshot,
+            emptyLayerIds: new Set(['blank']),
+            layerSurfaces: new Map([
+              [
+                'layer',
+                {
+                  rect: { height: 100, width: 100, x: 0, y: 0 },
+                  surface: backend.createSurface(100, 100),
+                },
+              ],
+            ]),
+            release: vi.fn(),
+          },
+          status: 'ok',
+        }),
+      execute,
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent: () => true,
+      reserve: () => ({ lease: { release: vi.fn() }, status: 'ok' }),
+    });
+
+    await expect(controller.export('mixed.psd')).resolves.toBe('exported');
+    expect(execute).toHaveBeenCalledOnce();
+  });
+
+  it('returns nothing when every requested raster layer is confirmed empty', async () => {
+    const backend = createTestStubRasterBackend();
+    const blankLayer: CanvasRasterLayerContractV2 = {
+      ...(document.layers[0] as CanvasRasterLayerContractV2),
+      id: 'blank',
+      name: 'Blank',
+      source: { bitmap: null, type: 'paint' },
+    };
+    const blankCanvas = canvasWithDocument({ ...document, layers: [blankLayer] });
+    const documentSnapshot: CanvasDocumentSnapshot = { canvas: blankCanvas, documentGeneration: 9 };
+    const release = vi.fn();
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => documentSnapshot,
+      captureRasterSnapshot: () =>
+        Promise.resolve({
+          snapshot: {
+            ...documentSnapshot,
+            emptyLayerIds: new Set(['blank']),
+            layerSurfaces: new Map(),
+            release,
+          },
+          status: 'ok',
+        }),
+      execute: vi.fn(),
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent: () => true,
+      reserve: vi.fn(),
+    });
+
+    await expect(controller.export('blank.psd')).resolves.toBe('nothing');
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('derives the execution limit after detached capture and releases the snapshot when over budget', async () => {
+    const backend = createTestStubRasterBackend();
+    const snapshotRelease = vi.fn();
+    const reserve = vi.fn();
+    const captureRasterSnapshot = vi.fn(() =>
+      Promise.resolve({
+        snapshot: {
+          canvas,
+          documentGeneration: 1,
+          emptyLayerIds: new Set<string>(),
+          layerSurfaces: new Map([
+            ['layer', { rect: { height: 100, width: 100, x: 0, y: 0 }, surface: backend.createSurface(100, 100) }],
+          ]),
+          release: snapshotRelease,
+        },
+        status: 'ok' as const,
+      })
+    );
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => ({
+        canvas,
+        documentGeneration: 1,
+      }),
+      captureRasterSnapshot,
+      getAvailableBytes: () => 0,
+      isDocumentSnapshotCurrent: () => true,
+      reserve,
+    });
+
+    await expect(controller.export('layers.psd')).resolves.toBe('over-budget');
+    expect(captureRasterSnapshot).toHaveBeenCalledOnce();
+    expect(snapshotRelease).toHaveBeenCalledOnce();
+    expect(reserve).not.toHaveBeenCalled();
+  });
+
+  it('propagates over-budget when immutable raster snapshot capture is refused', async () => {
+    const controller = new PsdExportController({
+      backend: createTestStubRasterBackend(),
+      captureDocumentSnapshot: () => ({
+        canvas,
+        documentGeneration: 1,
+      }),
+      captureRasterSnapshot: () => Promise.resolve({ status: 'over-budget' }),
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent: () => true,
+      reserve: () => ({ lease: { release: vi.fn() }, status: 'ok' }),
+    });
+
+    await expect(controller.export('layers.psd')).resolves.toBe('over-budget');
+  });
+
+  it('rejects a stale document generation after capture and releases the raster snapshot', async () => {
+    const backend = createTestStubRasterBackend();
+    const documentSnapshot: CanvasDocumentSnapshot = {
+      canvas,
+      documentGeneration: 3,
+    };
+    const release = vi.fn();
+    const isDocumentSnapshotCurrent = vi.fn().mockReturnValueOnce(true).mockReturnValueOnce(false);
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => documentSnapshot,
+      captureRasterSnapshot: () =>
+        Promise.resolve({
+          snapshot: {
+            ...documentSnapshot,
+            emptyLayerIds: new Set<string>(),
+            layerSurfaces: new Map(),
+            release,
+          },
+          status: 'ok',
+        }),
+      execute: vi.fn(),
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent,
+      reserve: vi.fn(),
+    });
+
+    await expect(controller.export('layers.psd')).resolves.toBe('stale');
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('aborts active execution on disposal and releases snapshot and reservation resources', async () => {
+    const backend = createTestStubRasterBackend();
+    const documentSnapshot: CanvasDocumentSnapshot = { canvas, documentGeneration: 5 };
+    const snapshotRelease = vi.fn();
+    const reservationRelease = vi.fn();
+    const controller = new PsdExportController({
+      backend,
+      captureDocumentSnapshot: () => documentSnapshot,
+      captureRasterSnapshot: () =>
+        Promise.resolve({
+          snapshot: {
+            ...documentSnapshot,
+            emptyLayerIds: new Set<string>(),
+            layerSurfaces: new Map([
+              [
+                'layer',
+                {
+                  rect: { height: 100, width: 100, x: 0, y: 0 },
+                  surface: backend.createSurface(100, 100),
+                },
+              ],
+            ]),
+            release: snapshotRelease,
+          },
+          status: 'ok',
+        }),
+      execute: (_plan, _fileName, deps) =>
+        new Promise((_resolve, reject) => {
+          deps.signal?.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')), {
+            once: true,
+          });
+        }),
+      getAvailableBytes: () => 1_000_000,
+      isDocumentSnapshotCurrent: () => true,
+      reserve: () => ({ lease: { release: reservationRelease }, status: 'ok' }),
+    });
+
+    const exportPromise = controller.export('layers.psd');
+    await vi.waitFor(() => expect(snapshotRelease).not.toHaveBeenCalled());
+    controller.dispose();
+
+    await expect(exportPromise).resolves.toBe('aborted');
+    expect(snapshotRelease).toHaveBeenCalledOnce();
+    expect(reservationRelease).toHaveBeenCalledOnce();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/psdExportController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/psdExportController.ts
new file mode 100644
index 00000000000..416eb3ecbc4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/psdExportController.ts
@@ -0,0 +1,188 @@
+import type {
+  CanvasDetachedLayerSurface,
+  CanvasDocumentSnapshot,
+  CaptureRasterSnapshotResult,
+  PsdExportResult,
+} from '@workbench/canvas-engine/api';
+import type { RasterBackend } from '@workbench/canvas-engine/render/raster';
+import type { CanvasLayerContract } from '@workbench/types';
+
+import {
+  executePsdExport,
+  planPsdExport,
+  type ExecutePsdExportDeps,
+  type PsdExportLayerInput,
+  type PsdExportPlan,
+} from '@workbench/canvas-engine/export/psdExport';
+
+type RasterMemoryReservationResult =
+  | { status: 'ok'; lease: { release(): void } }
+  | { status: 'over-budget'; requestedBytes: number; availableBytes: number };
+
+export interface PsdExportControllerOptions {
+  readonly backend: RasterBackend;
+  readonly captureDocumentSnapshot: () => CanvasDocumentSnapshot | null;
+  readonly captureRasterSnapshot: (
+    snapshot: CanvasDocumentSnapshot,
+    layerIds: readonly string[],
+    options: { signal: AbortSignal; includeDisabled: boolean }
+  ) => Promise<CaptureRasterSnapshotResult>;
+  readonly execute?: (plan: PsdExportPlan, fileName: string, deps: ExecutePsdExportDeps) => Promise<void>;
+  readonly getAvailableBytes: () => number;
+  readonly isDocumentSnapshotCurrent: (snapshot: CanvasDocumentSnapshot) => boolean;
+  readonly reserve: (bytes: number) => RasterMemoryReservationResult;
+}
+
+const isExportable = (layer: CanvasLayerContract): boolean => {
+  if (layer.type !== 'raster') {
+    return false;
+  }
+  switch (layer.source.type) {
+    case 'paint':
+    case 'image':
+    case 'gradient':
+    case 'text':
+      return true;
+    case 'shape':
+      return layer.source.kind !== 'polygon';
+    default:
+      return false;
+  }
+};
+
+export const PSD_ALLOCATION_BYTES_PER_PIXEL = 8;
+
+export const derivePsdPixelAreaLimit = (availableBytes: number): number =>
+  Math.max(0, Math.floor(availableBytes / PSD_ALLOCATION_BYTES_PER_PIXEL));
+
+const getRequiredAllocationPixelArea = (plan: Extract<PsdExportPlan, { status: 'ok' }>): number =>
+  plan.width * plan.height +
+  plan.layers.reduce((total, layer) => total + layer.worldRect.width * layer.worldRect.height, 0);
+
+/** Owns immutable PSD snapshot capture, budget reservation, execution, and cancellation. */
+export class PsdExportController {
+  private disposed = false;
+  private readonly active = new Set<AbortController>();
+
+  constructor(private readonly deps: PsdExportControllerOptions) {}
+
+  async export(fileName: string, options: { signal?: AbortSignal } = {}): Promise<PsdExportResult> {
+    if (this.disposed || options.signal?.aborted) {
+      return 'aborted';
+    }
+    const abortController = new AbortController();
+    const abort = (): void => abortController.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', abort, { once: true });
+    this.active.add(abortController);
+    try {
+      const documentSnapshot = this.deps.captureDocumentSnapshot();
+      if (!documentSnapshot) {
+        return 'nothing';
+      }
+      if (!this.deps.isDocumentSnapshotCurrent(documentSnapshot)) {
+        return 'stale';
+      }
+      const document = documentSnapshot.canvas.document;
+      const layers = document.layers.filter(isExportable);
+      if (layers.length === 0) {
+        return 'nothing';
+      }
+      const capture = await this.deps.captureRasterSnapshot(
+        documentSnapshot,
+        layers.map((layer) => layer.id),
+        { includeDisabled: true, signal: abortController.signal }
+      );
+      if (capture.status !== 'ok') {
+        return capture.status;
+      }
+      const rasterSnapshot = capture.snapshot;
+      try {
+        if (abortController.signal.aborted) {
+          return 'aborted';
+        }
+        if (!this.deps.isDocumentSnapshotCurrent(documentSnapshot)) {
+          return 'stale';
+        }
+        const inputs: PsdExportLayerInput[] = [];
+        for (const layer of layers) {
+          const detached = rasterSnapshot.layerSurfaces.get(layer.id);
+          if (!detached) {
+            if (rasterSnapshot.emptyLayerIds.has(layer.id)) {
+              continue;
+            }
+            return 'not-ready';
+          }
+          inputs.push({
+            adjustments: layer.type === 'raster' ? layer.adjustments : undefined,
+            blendMode: layer.blendMode,
+            contentRect: detached.rect,
+            id: layer.id,
+            isEnabled: layer.isEnabled,
+            name: layer.name,
+            opacity: layer.opacity,
+            transform: layer.transform,
+          });
+        }
+        const plan = planPsdExport(inputs);
+        if (plan.status === 'empty') {
+          return 'nothing';
+        }
+        if (plan.status === 'too-large') {
+          return 'too-large';
+        }
+        const requestedPixelArea = getRequiredAllocationPixelArea(plan);
+        const requestedBytes = requestedPixelArea * PSD_ALLOCATION_BYTES_PER_PIXEL;
+        if (requestedPixelArea > derivePsdPixelAreaLimit(this.deps.getAvailableBytes())) {
+          return 'over-budget';
+        }
+        const reservation = this.deps.reserve(requestedBytes);
+        if (reservation.status === 'over-budget') {
+          return 'over-budget';
+        }
+        try {
+          const getLayerSurface = (layerId: string): Promise<CanvasDetachedLayerSurface> => {
+            const detached = rasterSnapshot.layerSurfaces.get(layerId);
+            if (!detached) {
+              return Promise.reject(new Error(`PSD raster snapshot is missing layer ${layerId}.`));
+            }
+            return Promise.resolve(detached);
+          };
+          try {
+            await (this.deps.execute ?? executePsdExport)(
+              plan,
+              /\.psd$/i.test(fileName) ? fileName : `${fileName}.psd`,
+              { backend: this.deps.backend, getLayerSurface, signal: abortController.signal }
+            );
+          } catch (error) {
+            if (abortController.signal.aborted || (error instanceof DOMException && error.name === 'AbortError')) {
+              return 'aborted';
+            }
+            throw error;
+          }
+          return abortController.signal.aborted ? 'aborted' : 'exported';
+        } finally {
+          reservation.lease.release();
+        }
+      } finally {
+        rasterSnapshot.release();
+      }
+    } finally {
+      this.active.delete(abortController);
+      options.signal?.removeEventListener('abort', abort);
+    }
+  }
+
+  cancel(): void {
+    for (const controller of this.active) {
+      controller.abort();
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.cancel();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterController.test.ts
new file mode 100644
index 00000000000..6f43351a185
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterController.test.ts
@@ -0,0 +1,33 @@
+import type { CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { createCanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { RasterController } from './rasterController';
+
+describe('RasterController', () => {
+  it('owns base and derived surfaces and invalidates all effects for a layer', () => {
+    const backend = createTestStubRasterBackend();
+    const onVersionChange = vi.fn();
+    const controller = new RasterController({
+      backend,
+      diagnostics: createCanvasDiagnostics(true),
+      onVersionChange,
+    });
+    const entry = controller.layers.getOrCreate('a', 10, 10);
+    const layer = {
+      adjustments: { brightness: 0.5, contrast: 0, saturation: 0 },
+      id: 'a',
+      type: 'raster',
+    } as CanvasRasterLayerContractV2;
+    expect(controller.getAdjustedSurface(layer, entry)).not.toBeNull();
+    expect(controller.derived.byteSize()).toBe(400);
+
+    controller.deleteDerivedSurfaces('a');
+    expect(controller.derived.byteSize()).toBe(0);
+    controller.dispose();
+    controller.dispose();
+    expect(controller.layers.byteSize()).toBe(0);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterController.ts
new file mode 100644
index 00000000000..52bce8f99fd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterController.ts
@@ -0,0 +1,298 @@
+import type { CanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+import type { LayerCacheEntry, LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type {
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+} from '@workbench/types';
+
+export type DecodeImageResult =
+  | { status: 'ok'; surface: RasterSurface; decodedWidth: number; decodedHeight: number }
+  | { status: 'aborted' | 'stale' };
+
+export interface RasterizationJob {
+  abortedByCaller?: boolean;
+  controller: AbortController;
+  version: number;
+  documentGeneration: number;
+  source: CanvasLayerSourceContract;
+  promise: Promise<'published' | 'stale' | 'error' | 'aborted'>;
+}
+
+import {
+  createAdjustedSurfaceCache,
+  type AdjustedSurfaceCache,
+} from '@workbench/canvas-engine/render/adjustedSurfaceCache';
+import { createDecodedBitmapPool, type DecodedBitmapPool } from '@workbench/canvas-engine/render/decodedBitmapPool';
+import {
+  createDerivedSurfaceCache,
+  type DerivedSurfaceCache,
+} from '@workbench/canvas-engine/render/derivedSurfaceCache';
+import { createLayerCacheStore, DEFAULT_CACHE_BUDGET_BYTES } from '@workbench/canvas-engine/render/layerCache';
+
+import { RasterMemoryBudgetController } from './rasterMemoryBudgetController';
+
+export interface RasterControllerOptions {
+  readonly backend: RasterBackend;
+  readonly diagnostics: CanvasDiagnostics;
+  readonly onVersionChange?: (layerId: string) => void;
+  readonly getDocument?: () => CanvasDocumentContractV2 | null;
+  readonly getLayerImageName?: (layer: CanvasLayerContract) => string | null;
+  readonly imageResolver?: (imageName: string, signal?: AbortSignal) => Promise<Blob>;
+}
+
+export class RasterController {
+  readonly layers: LayerCacheStore;
+  readonly derived: DerivedSurfaceCache;
+  readonly adjustments: AdjustedSurfaceCache;
+  readonly memory: RasterMemoryBudgetController;
+  readonly bitmaps: DecodedBitmapPool;
+  private readonly jobs = new Map<string, RasterizationJob>();
+  private readonly activeJobs = new Set<RasterizationJob>();
+  private readonly trackedImages = new Map<string, string>();
+  private readonly mirroredImages = new Map<string, string>();
+  private readonly thumbnailKeys = new Map<string, string>();
+  private documentGeneration = 0;
+  private disposed = false;
+  private readonly getDocument: () => CanvasDocumentContractV2 | null;
+  private readonly getLayerImageName: (layer: CanvasLayerContract) => string | null;
+  private readonly backend: RasterBackend;
+  private readonly imageResolver: ((imageName: string, signal?: AbortSignal) => Promise<Blob>) | null;
+
+  constructor(options: RasterControllerOptions) {
+    this.backend = options.backend;
+    this.memory = new RasterMemoryBudgetController({ budgetBytes: DEFAULT_CACHE_BUDGET_BYTES });
+    this.bitmaps = createDecodedBitmapPool({ onBytesChange: (bytes) => this.memory.setDecodedBytes(bytes) });
+    this.layers = createLayerCacheStore(options.backend, { onVersionChange: options.onVersionChange });
+    this.getDocument = options.getDocument ?? (() => null);
+    this.getLayerImageName = options.getLayerImageName ?? (() => null);
+    this.imageResolver = options.imageResolver ?? null;
+    this.derived = createDerivedSurfaceCache(options.diagnostics);
+    this.adjustments = createAdjustedSurfaceCache(options.backend, this.derived);
+  }
+
+  async decodeImage(
+    image: CanvasImageRef,
+    options: {
+      signal?: AbortSignal;
+      isCurrent?: () => boolean;
+      scaleToImage?: boolean;
+      validateDecoded?: (width: number, height: number) => void;
+    } = {}
+  ): Promise<DecodeImageResult> {
+    if (!this.imageResolver) {
+      throw new Error('RasterController requires an image resolver to decode images.');
+    }
+    if (options.signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    const blob = await this.imageResolver(image.imageName, options.signal);
+    if (options.signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    if (options.isCurrent && !options.isCurrent()) {
+      return { status: 'stale' };
+    }
+    const bitmap = await this.backend.createImageBitmap(blob);
+    if (options.signal?.aborted || (options.isCurrent && !options.isCurrent())) {
+      bitmap.close();
+      return { status: options.signal?.aborted ? 'aborted' : 'stale' };
+    }
+    try {
+      options.validateDecoded?.(bitmap.width, bitmap.height);
+      const surface = this.backend.createSurface(image.width, image.height);
+      surface.ctx.setTransform(1, 0, 0, 1, 0, 0);
+      surface.ctx.clearRect(0, 0, image.width, image.height);
+      if (options.scaleToImage === false) {
+        surface.ctx.drawImage(bitmap, 0, 0);
+      } else {
+        surface.ctx.drawImage(bitmap, 0, 0, image.width, image.height);
+      }
+      return { decodedHeight: bitmap.height, decodedWidth: bitmap.width, status: 'ok', surface };
+    } finally {
+      bitmap.close();
+    }
+  }
+
+  async decodeBlob(
+    blob: Blob,
+    dimensions?: { width: number; height: number; scale?: boolean }
+  ): Promise<{ surface: RasterSurface; decodedWidth: number; decodedHeight: number }> {
+    const bitmap = await this.backend.createImageBitmap(blob);
+    try {
+      const width = dimensions?.width ?? bitmap.width;
+      const height = dimensions?.height ?? bitmap.height;
+      const surface = this.backend.createSurface(width, height);
+      surface.ctx.setTransform(1, 0, 0, 1, 0, 0);
+      surface.ctx.clearRect(0, 0, width, height);
+      if (dimensions?.scale) {
+        surface.ctx.drawImage(bitmap, 0, 0, width, height);
+      } else {
+        surface.ctx.drawImage(bitmap, 0, 0);
+      }
+      return { decodedHeight: bitmap.height, decodedWidth: bitmap.width, surface };
+    } finally {
+      bitmap.close();
+    }
+  }
+
+  getAdjustedSurface(layer: CanvasLayerContract, entry: LayerCacheEntry): RasterSurface | null {
+    return layer.type === 'raster' ? this.adjustments.get(layer.id, entry, layer.adjustments) : null;
+  }
+
+  deleteDerivedSurfaces(layerId: string): void {
+    this.adjustments.delete(layerId);
+    this.derived.deleteLayer(layerId);
+  }
+
+  getDocumentGeneration(): number {
+    return this.documentGeneration;
+  }
+
+  invalidateDocument(): void {
+    this.documentGeneration += 1;
+    this.cancelAllRasterization();
+  }
+
+  getRasterizationJob(layerId: string): RasterizationJob | undefined {
+    return this.jobs.get(layerId);
+  }
+
+  installRasterizationJob(layerId: string, job: RasterizationJob): void {
+    this.jobs.set(layerId, job);
+    this.activeJobs.add(job);
+  }
+
+  finishRasterizationJob(layerId: string, job: RasterizationJob): void {
+    if (this.jobs.get(layerId) === job) {
+      this.jobs.delete(layerId);
+    }
+    this.activeJobs.delete(job);
+  }
+
+  cancelRasterization(layerId: string): void {
+    const job = this.jobs.get(layerId);
+    if (!job) {
+      return;
+    }
+    this.jobs.delete(layerId);
+    job.controller.abort();
+  }
+
+  cancelAllRasterization(): void {
+    const jobs = [...this.jobs.values()];
+    this.jobs.clear();
+    for (const job of jobs) {
+      job.controller.abort();
+    }
+  }
+
+  hasActiveSourceImage(imageName: string): boolean {
+    for (const job of this.activeJobs) {
+      if (job.source.type === 'image' && job.source.image.imageName === imageName) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  getTrackedImage(layerId: string): string | undefined {
+    return this.trackedImages.get(layerId);
+  }
+  setTrackedImage(layerId: string, imageName: string): void {
+    this.trackedImages.set(layerId, imageName);
+  }
+  deleteTrackedImage(layerId: string): void {
+    this.trackedImages.delete(layerId);
+  }
+  trackedImageIds(): string[] {
+    return [...this.trackedImages.keys()];
+  }
+  hasTrackedImage(imageName: string): boolean {
+    return [...this.trackedImages.values()].includes(imageName);
+  }
+  clearTrackedImages(): void {
+    this.trackedImages.clear();
+  }
+
+  getMirroredImage(layerId: string): string | undefined {
+    return this.mirroredImages.get(layerId);
+  }
+  setMirroredImage(layerId: string, imageName: string): void {
+    this.mirroredImages.set(layerId, imageName);
+  }
+  deleteMirroredImage(layerId: string): void {
+    this.mirroredImages.delete(layerId);
+  }
+  mirroredImageNames(): string[] {
+    return [...this.mirroredImages.values()];
+  }
+  clearMirroredImages(): void {
+    this.mirroredImages.clear();
+  }
+
+  getThumbnailKey(layerId: string): string | undefined {
+    return this.thumbnailKeys.get(layerId);
+  }
+  setThumbnailKey(layerId: string, key: string): void {
+    this.thumbnailKeys.set(layerId, key);
+  }
+  deleteThumbnailKey(layerId: string): void {
+    this.thumbnailKeys.delete(layerId);
+  }
+  clearThumbnailKeys(): void {
+    this.thumbnailKeys.clear();
+  }
+
+  releaseBitmapIfUnreferenced(imageName: string): void {
+    // Decoded bitmaps are lease-owned and close automatically after the final
+    // rasterizer releases them. Retained for callers that also update tracking.
+    void imageName;
+  }
+
+  untrackLayerImage(layerId: string): void {
+    const imageName = this.getTrackedImage(layerId);
+    if (!imageName) {
+      return;
+    }
+    this.deleteTrackedImage(layerId);
+    this.releaseBitmapIfUnreferenced(imageName);
+  }
+
+  trackPublishedLayerImage(layer: CanvasLayerContract): void {
+    const previous = this.getTrackedImage(layer.id);
+    const current = this.getLayerImageName(layer);
+    if (current) {
+      this.setTrackedImage(layer.id, current);
+    } else {
+      this.deleteTrackedImage(layer.id);
+    }
+    if (previous && previous !== current) {
+      this.releaseBitmapIfUnreferenced(previous);
+    }
+  }
+
+  dropLayer(layerId: string): void {
+    this.cancelRasterization(layerId);
+    this.untrackLayerImage(layerId);
+    this.layers.delete(layerId);
+    this.deleteDerivedSurfaces(layerId);
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.cancelAllRasterization();
+    this.clearTrackedImages();
+    this.clearMirroredImages();
+    this.clearThumbnailKeys();
+    this.layers.dispose();
+    this.bitmaps.dispose();
+    this.adjustments.dispose();
+    this.memory.dispose();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterExportController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterExportController.test.ts
new file mode 100644
index 00000000000..4362cd4a17c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterExportController.test.ts
@@ -0,0 +1,162 @@
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { RasterExportController } from './rasterExportController';
+
+describe('RasterExportController budget', () => {
+  it('returns over-budget before allocating a baked raster export', async () => {
+    const backend = createTestStubRasterBackend();
+    const layers = createLayerCacheStore(backend);
+    const entry = layers.getOrCreate('layer', 100, 100);
+    entry.hasPublishedPixels = true;
+    entry.stale = false;
+    const layer = {
+      blendMode: 'normal' as const,
+      id: 'layer',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Layer',
+      opacity: 1,
+      source: { image: { height: 100, imageName: 'layer.png', width: 100 }, type: 'image' as const },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster' as const,
+    };
+    const document: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [layer],
+      selectedLayerId: null,
+      version: 2,
+      width: 100,
+    };
+    const reserve = vi.fn(() => ({ availableBytes: 0, requestedBytes: 40_000, status: 'over-budget' as const }));
+    const controller = new RasterExportController({
+      backend,
+      captureGuard: () => ({ cacheVersion: 1, documentGeneration: 1, layer, layerId: 'layer', projectId: 'p' }),
+      getDocument: () => document,
+      getOrStartRasterization: () => Promise.resolve('published'),
+      isGuardCurrent: () => true,
+      isRasterizing: () => false,
+      isSupportedSource: () => true,
+      layers,
+      reserve,
+    });
+
+    await expect(controller.baked('layer')).resolves.toEqual({ status: 'over-budget' });
+    expect(reserve).toHaveBeenCalledWith(40_000);
+  });
+
+  it('holds the baked-surface reservation until blob encoding settles', async () => {
+    const stub = createTestStubRasterBackend();
+    let resolveEncode!: (blob: Blob) => void;
+    const encodeSurface = vi.fn(
+      () =>
+        new Promise<Blob>((resolve) => {
+          resolveEncode = resolve;
+        })
+    );
+    const backend = { ...stub, encodeSurface };
+    const layers = createLayerCacheStore(backend);
+    const entry = layers.getOrCreate('layer', 100, 100);
+    entry.hasPublishedPixels = true;
+    entry.stale = false;
+    const layer = {
+      adjustments: { brightness: 0.1, contrast: 0, saturation: 0 },
+      blendMode: 'normal' as const,
+      id: 'layer',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Layer',
+      opacity: 1,
+      source: { image: { height: 100, imageName: 'layer.png', width: 100 }, type: 'image' as const },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster' as const,
+    };
+    const document: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [layer],
+      selectedLayerId: null,
+      version: 2,
+      width: 100,
+    };
+    const release = vi.fn();
+    const reserve = vi.fn(() => ({ lease: { release }, status: 'ok' as const }));
+    const controller = new RasterExportController({
+      backend,
+      captureGuard: () => ({ cacheVersion: 1, documentGeneration: 1, layer, layerId: 'layer', projectId: 'p' }),
+      getDocument: () => document,
+      getOrStartRasterization: () => Promise.resolve('published'),
+      isGuardCurrent: () => true,
+      isRasterizing: () => false,
+      isSupportedSource: () => true,
+      layers,
+      reserve,
+    });
+
+    const pending = controller.blob('layer');
+    await vi.waitFor(() => expect(encodeSurface).toHaveBeenCalledOnce());
+    expect(release).not.toHaveBeenCalled();
+
+    resolveEncode(new Blob(['png']));
+    await expect(pending).resolves.toMatchObject({ status: 'ok' });
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('transfers the baked-surface reservation to the caller until idempotent release', async () => {
+    const backend = createTestStubRasterBackend();
+    const layers = createLayerCacheStore(backend);
+    const entry = layers.getOrCreate('layer', 100, 100);
+    entry.hasPublishedPixels = true;
+    entry.stale = false;
+    const layer = {
+      adjustments: { brightness: 0.1, contrast: 0, saturation: 0 },
+      blendMode: 'normal' as const,
+      id: 'layer',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Layer',
+      opacity: 1,
+      source: { image: { height: 100, imageName: 'layer.png', width: 100 }, type: 'image' as const },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster' as const,
+    };
+    const document: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [layer],
+      selectedLayerId: null,
+      version: 2,
+      width: 100,
+    };
+    const release = vi.fn();
+    const reserve = vi.fn(() => ({ lease: { release }, status: 'ok' as const }));
+    const controller = new RasterExportController({
+      backend,
+      captureGuard: () => ({ cacheVersion: 1, documentGeneration: 1, layer, layerId: 'layer', projectId: 'p' }),
+      getDocument: () => document,
+      getOrStartRasterization: () => Promise.resolve('published'),
+      isGuardCurrent: () => true,
+      isRasterizing: () => false,
+      isSupportedSource: () => true,
+      layers,
+      reserve,
+    });
+
+    const result = await controller.baked('layer');
+    expect(result.status).toBe('ok');
+    expect(reserve).toHaveBeenCalledWith(80_000);
+    expect(release).not.toHaveBeenCalled();
+    if (result.status === 'ok') {
+      result.release();
+      result.release();
+    }
+    expect(release).toHaveBeenCalledOnce();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterExportController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterExportController.ts
new file mode 100644
index 00000000000..bf84ccc9a80
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterExportController.ts
@@ -0,0 +1,265 @@
+import type {
+  ExportBakedLayerBlobResult,
+  ExportBakedLayerPixelsOptions,
+  ExportLayerPixelsOptions,
+  LayerExportGuard,
+} from '@workbench/canvas-engine/api';
+import type { LayerCacheEntry, LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasLayerSourceContract } from '@workbench/types';
+
+import { getSourceContentRect, renderableSourceOf } from '@workbench/canvas-engine/document/sources';
+import { fromTRS } from '@workbench/canvas-engine/math/mat2d';
+import { isEmpty, roundOut, transformBounds } from '@workbench/canvas-engine/math/rect';
+import { applyAdjustments } from '@workbench/canvas-engine/render/adjustments';
+
+export type ExportLayerPixelsResult =
+  | {
+      status: 'ok';
+      surface: ReturnType<RasterBackend['createSurface']>;
+      rect: Rect;
+      guard: LayerExportGuard;
+      release(): void;
+    }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' | 'aborted' };
+
+export interface RasterExportControllerOptions {
+  readonly backend: RasterBackend;
+  readonly captureGuard: (layer: CanvasLayerContract, entry: LayerCacheEntry) => LayerExportGuard;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getOrStartRasterization: (
+    layer: CanvasLayerContract,
+    document: CanvasDocumentContractV2,
+    signal?: AbortSignal
+  ) => Promise<'published' | 'stale' | 'error' | 'aborted'>;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly isRasterizing: (layer: CanvasLayerContract) => boolean;
+  readonly isSupportedSource: (source: CanvasLayerSourceContract) => boolean;
+  readonly layers: LayerCacheStore;
+  readonly reserve?: (
+    bytes: number
+  ) =>
+    | { status: 'ok'; lease: { release(): void } }
+    | { status: 'over-budget'; requestedBytes: number; availableBytes: number };
+  readonly pin?: (layerId: string) => { release(): void };
+}
+
+interface ReservedExportLayerPixels {
+  readonly result: ExportLayerPixelsResult;
+  release(): void;
+}
+
+const noReservedPixels = (result: ExportLayerPixelsResult): ReservedExportLayerPixels => ({
+  release: () => undefined,
+  result,
+});
+
+/** Owns cache-backed, transformed, and encoded layer export primitives. */
+export class RasterExportController {
+  constructor(private readonly options: RasterExportControllerOptions) {}
+
+  private applyAdjustments(
+    result: Extract<ExportLayerPixelsResult, { status: 'ok' }>,
+    shouldApply: boolean
+  ): ExportLayerPixelsResult {
+    const layer = result.guard.layer;
+    if (!shouldApply || layer.type !== 'raster' || !layer.adjustments) {
+      return result;
+    }
+    const reservation = this.options.reserve?.(result.rect.width * result.rect.height * 8);
+    if (reservation?.status === 'over-budget') {
+      result.release();
+      return { status: 'over-budget' };
+    }
+    const pinLease = this.options.pin?.(result.guard.layerId);
+    let released = false;
+    const release = (): void => {
+      if (released) {
+        return;
+      }
+      released = true;
+      result.release();
+      pinLease?.release();
+      if (reservation?.status === 'ok') {
+        reservation.lease.release();
+      }
+    };
+    try {
+      const surface = this.options.backend.createSurface(result.rect.width, result.rect.height);
+      const ctx = surface.ctx;
+      ctx.setTransform(1, 0, 0, 1, 0, 0);
+      ctx.clearRect(0, 0, result.rect.width, result.rect.height);
+      ctx.drawImage(result.surface.canvas, 0, 0);
+      const imageData = ctx.getImageData(0, 0, result.rect.width, result.rect.height);
+      applyAdjustments(imageData, layer.adjustments);
+      ctx.putImageData(imageData, 0, 0);
+      return { ...result, release, surface };
+    } catch (error) {
+      release();
+      throw error;
+    }
+  }
+
+  async rasterize(layerId: string, options: ExportLayerPixelsOptions = {}): Promise<ExportLayerPixelsResult> {
+    const document = this.options.getDocument();
+    if (!document) {
+      return { status: 'missing' };
+    }
+    const layer = document.layers.find((candidate) => candidate.id === layerId);
+    const source = layer ? renderableSourceOf(layer) : null;
+    if (!layer || !source) {
+      return { status: 'missing' };
+    }
+    if (!options.includeDisabled && !layer.isEnabled) {
+      return { status: 'disabled' };
+    }
+    if (!this.options.isSupportedSource(source)) {
+      return { status: 'unsupported' };
+    }
+    const liveEntry = this.options.layers.get(layerId);
+    if (liveEntry && !liveEntry.stale && !this.options.isRasterizing(layer) && !isEmpty(liveEntry.rect)) {
+      return this.applyAdjustments(
+        {
+          guard: this.options.captureGuard(layer, liveEntry),
+          release: () => undefined,
+          rect: liveEntry.rect,
+          status: 'ok',
+          surface: liveEntry.surface,
+        },
+        options.applyAdjustments === true
+      );
+    }
+    const contentRect = getSourceContentRect(layer, document);
+    if (isEmpty(contentRect)) {
+      return { status: 'empty' };
+    }
+    const reservation = this.options.reserve?.(contentRect.width * contentRect.height * 8);
+    if (reservation?.status === 'over-budget') {
+      return { status: 'over-budget' };
+    }
+    const pinLease = this.options.pin?.(layerId);
+    try {
+      const rasterized = await this.options.getOrStartRasterization(layer, document, options.signal);
+      if (rasterized !== 'published') {
+        return { status: rasterized === 'aborted' ? 'aborted' : 'not-ready' };
+      }
+    } finally {
+      pinLease?.release();
+      if (reservation?.status === 'ok') {
+        reservation.lease.release();
+      }
+    }
+    const currentDocument = this.options.getDocument();
+    const currentLayer = currentDocument?.layers.find((candidate) => candidate.id === layerId);
+    const entry = this.options.layers.get(layerId);
+    if (!currentLayer || !entry || entry.stale) {
+      return { status: 'not-ready' };
+    }
+    const currentSource = renderableSourceOf(currentLayer);
+    if (!currentSource) {
+      return { status: 'missing' };
+    }
+    if (!options.includeDisabled && !currentLayer.isEnabled) {
+      return { status: 'disabled' };
+    }
+    if (!this.options.isSupportedSource(currentSource)) {
+      return { status: 'unsupported' };
+    }
+    if (isEmpty(entry.rect)) {
+      return { status: 'empty' };
+    }
+    return this.applyAdjustments(
+      {
+        guard: this.options.captureGuard(currentLayer, entry),
+        release: () => undefined,
+        rect: entry.rect,
+        status: 'ok',
+        surface: entry.surface,
+      },
+      options.applyAdjustments === true
+    );
+  }
+
+  private async reserveBaked(
+    layerId: string,
+    options: ExportBakedLayerPixelsOptions = {}
+  ): Promise<ReservedExportLayerPixels> {
+    const raw = await this.rasterize(layerId, { ...options, applyAdjustments: false });
+    if (raw.status !== 'ok') {
+      return noReservedPixels(raw);
+    }
+    const layer = raw.guard.layer;
+    const matrix = fromTRS(
+      { x: layer.transform.x, y: layer.transform.y },
+      layer.transform.rotation,
+      layer.transform.scaleX,
+      layer.transform.scaleY
+    );
+    const rect = roundOut(transformBounds(matrix, raw.rect));
+    if (isEmpty(rect)) {
+      raw.release();
+      return noReservedPixels({ status: 'empty' });
+    }
+    const appliesAdjustments = options.applyAdjustments !== false && layer.type === 'raster' && !!layer.adjustments;
+    const reservation = this.options.reserve?.(rect.width * rect.height * (appliesAdjustments ? 8 : 4));
+    if (reservation?.status === 'over-budget') {
+      raw.release();
+      return noReservedPixels({ status: 'over-budget' });
+    }
+    const pinLease = this.options.pin?.(layerId);
+    let released = false;
+    const release = (): void => {
+      if (released) {
+        return;
+      }
+      released = true;
+      pinLease?.release();
+      if (reservation?.status === 'ok') {
+        reservation.lease.release();
+      }
+      raw.release();
+    };
+    try {
+      const surface = this.options.backend.createSurface(rect.width, rect.height);
+      const ctx = surface.ctx;
+      ctx.setTransform(1, 0, 0, 1, 0, 0);
+      ctx.clearRect(0, 0, rect.width, rect.height);
+      ctx.setTransform(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e - rect.x, matrix.f - rect.y);
+      ctx.drawImage(raw.surface.canvas, raw.rect.x, raw.rect.y);
+      if (appliesAdjustments && layer.type === 'raster' && layer.adjustments) {
+        const imageData = ctx.getImageData(0, 0, rect.width, rect.height);
+        applyAdjustments(imageData, layer.adjustments);
+        ctx.putImageData(imageData, 0, 0);
+      }
+      return { release, result: { guard: raw.guard, rect, release, status: 'ok', surface } };
+    } catch (error) {
+      release();
+      throw error;
+    }
+  }
+
+  async baked(layerId: string, options: ExportBakedLayerPixelsOptions = {}): Promise<ExportLayerPixelsResult> {
+    const reserved = await this.reserveBaked(layerId, options);
+    return reserved.result;
+  }
+
+  async blob(layerId: string, options: ExportBakedLayerPixelsOptions = {}): Promise<ExportBakedLayerBlobResult> {
+    const reserved = await this.reserveBaked(layerId, options);
+    try {
+      const result = reserved.result;
+      if (result.status !== 'ok') {
+        return result;
+      }
+      const blob = await this.options.backend.encodeSurface(result.surface, 'image/png');
+      if (!this.options.isGuardCurrent(result.guard)) {
+        return { status: 'not-ready' };
+      }
+      return { blob, guard: result.guard, rect: result.rect, status: 'ok' };
+    } finally {
+      reserved.release();
+    }
+  }
+
+  dispose(): void {}
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterMemoryBudgetController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterMemoryBudgetController.test.ts
new file mode 100644
index 00000000000..a38d9cade23
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterMemoryBudgetController.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+
+import { RasterMemoryBudgetController } from './rasterMemoryBudgetController';
+
+describe('RasterMemoryBudgetController', () => {
+  it('reports the currently available bytes used to derive background pixel-area limits', () => {
+    const memory = new RasterMemoryBudgetController({ budgetBytes: 1_000 });
+    memory.setBaseBytes(400);
+    memory.setDecodedBytes(100);
+
+    expect(memory.getAvailableBytes()).toBe(500);
+  });
+
+  it('accounts for owned bytes and refuses background reservations beyond the soft limit', () => {
+    const memory = new RasterMemoryBudgetController({ budgetBytes: 1_000 });
+
+    memory.setBaseBytes(400);
+    memory.setDerivedBytes(200);
+    memory.setDecodedBytes(100);
+    memory.setDetachedBytes(50);
+
+    const accepted = memory.reserve(200, { generation: 1, purpose: 'thumbnail' });
+    const refused = memory.reserve(100, { generation: 1, purpose: 'raster-export' });
+
+    expect(accepted.status).toBe('ok');
+    expect(refused).toEqual({ availableBytes: 50, requestedBytes: 100, status: 'over-budget' });
+    expect(memory.snapshot()).toEqual({
+      baseBytes: 400,
+      decodedBytes: 100,
+      derivedBytes: 200,
+      detachedBytes: 50,
+      reservedBytes: 200,
+      totalBytes: 950,
+    });
+  });
+
+  it('makes generation reservation and pin release idempotent across cancellation and disposal', () => {
+    const memory = new RasterMemoryBudgetController({ budgetBytes: 1_000 });
+    const reserved = memory.reserve(400, { generation: 7, purpose: 'psd-export' });
+    expect(reserved.status).toBe('ok');
+    if (reserved.status !== 'ok') {
+      throw new Error('Expected reservation');
+    }
+    const pin = memory.pin('layer-a', 7);
+
+    memory.releaseGeneration(7);
+    reserved.lease.release();
+    pin.release();
+    memory.releaseGeneration(7);
+    memory.dispose();
+    memory.dispose();
+
+    expect(memory.snapshot().reservedBytes).toBe(0);
+    expect(memory.isPinned('layer-a')).toBe(false);
+  });
+
+  it('keeps caller-owned detached snapshots accounted across generation release', () => {
+    const memory = new RasterMemoryBudgetController({ budgetBytes: 1_000 });
+    const detached = memory.trackDetached(300, 9);
+
+    expect(memory.snapshot().detachedBytes).toBe(300);
+    memory.releaseGeneration(9);
+    expect(memory.snapshot().detachedBytes).toBe(300);
+    detached.release();
+    expect(memory.snapshot().detachedBytes).toBe(0);
+  });
+
+  it('keeps in-flight operation reservations and pins across generation release', () => {
+    const memory = new RasterMemoryBudgetController({ budgetBytes: 1_000 });
+    const reservation = memory.reserveOperation(300, { purpose: 'invocation-composite' });
+    expect(reservation.status).toBe('ok');
+    if (reservation.status !== 'ok') {
+      throw new Error('Expected operation reservation');
+    }
+    const pin = memory.pinOperation('layer-a');
+
+    memory.releaseGeneration(4);
+
+    expect(memory.snapshot().reservedBytes).toBe(300);
+    expect(memory.isPinned('layer-a')).toBe(true);
+
+    reservation.lease.release();
+    pin.release();
+    expect(memory.snapshot().reservedBytes).toBe(0);
+    expect(memory.isPinned('layer-a')).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterMemoryBudgetController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterMemoryBudgetController.ts
new file mode 100644
index 00000000000..58a090699e3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterMemoryBudgetController.ts
@@ -0,0 +1,235 @@
+import { DEFAULT_CACHE_BUDGET_BYTES } from '@workbench/canvas-engine/render/layerCache';
+
+export type RasterBackgroundPurpose =
+  | 'background-snapshot'
+  | 'invocation-composite'
+  | 'thumbnail'
+  | 'raster-export'
+  | 'psd-export';
+
+export interface RasterMemoryLease {
+  release(): void;
+}
+
+export type RasterMemoryReservationResult =
+  | { status: 'ok'; lease: RasterMemoryLease }
+  | { status: 'over-budget'; requestedBytes: number; availableBytes: number };
+
+export interface RasterMemorySnapshot {
+  baseBytes: number;
+  derivedBytes: number;
+  decodedBytes: number;
+  detachedBytes: number;
+  reservedBytes: number;
+  totalBytes: number;
+}
+
+interface GenerationLease extends RasterMemoryLease {
+  readonly generation: number;
+}
+
+const normalizedBytes = (bytes: number): number => Math.max(0, Math.ceil(bytes));
+
+/** Owns byte accounting and generation-scoped background allocation leases. */
+export class RasterMemoryBudgetController {
+  readonly budgetBytes: number;
+  private baseBytes = 0;
+  private derivedBytes = 0;
+  private decodedBytes = 0;
+  private reportedDetachedBytes = 0;
+  private leasedDetachedBytes = 0;
+  private reservedBytes = 0;
+  private readonly generationLeases = new Map<number, Set<GenerationLease>>();
+  private readonly pins = new Map<string, Set<RasterMemoryLease>>();
+  private disposed = false;
+
+  constructor(options: { budgetBytes?: number } = {}) {
+    this.budgetBytes = normalizedBytes(options.budgetBytes ?? DEFAULT_CACHE_BUDGET_BYTES);
+  }
+
+  setBaseBytes(bytes: number): void {
+    this.baseBytes = normalizedBytes(bytes);
+  }
+
+  setDerivedBytes(bytes: number): void {
+    this.derivedBytes = normalizedBytes(bytes);
+  }
+
+  setDecodedBytes(bytes: number): void {
+    this.decodedBytes = normalizedBytes(bytes);
+  }
+
+  setDetachedBytes(bytes: number): void {
+    this.reportedDetachedBytes = normalizedBytes(bytes);
+  }
+
+  trackDetached(bytes: number, _generation: number): RasterMemoryLease {
+    if (this.disposed) {
+      return { release: () => undefined };
+    }
+    const trackedBytes = normalizedBytes(bytes);
+    this.leasedDetachedBytes += trackedBytes;
+    let released = false;
+    return {
+      release: () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        this.leasedDetachedBytes = Math.max(0, this.leasedDetachedBytes - trackedBytes);
+      },
+    };
+  }
+
+  reserve(
+    requestedBytes: number,
+    options: { generation: number; purpose: RasterBackgroundPurpose }
+  ): RasterMemoryReservationResult {
+    const bytes = normalizedBytes(requestedBytes);
+    const availableBytes = this.getAvailableBytes();
+    if (this.disposed || bytes > availableBytes) {
+      return { availableBytes, requestedBytes: bytes, status: 'over-budget' };
+    }
+    this.reservedBytes += bytes;
+    const lease = this.createGenerationLease(options.generation, () => {
+      this.reservedBytes = Math.max(0, this.reservedBytes - bytes);
+    });
+    return { lease, status: 'ok' };
+  }
+
+  /** Reserves bytes for an in-flight operation independently of lifecycle generations. */
+  reserveOperation(
+    requestedBytes: number,
+    _options: { purpose: RasterBackgroundPurpose }
+  ): RasterMemoryReservationResult {
+    const bytes = normalizedBytes(requestedBytes);
+    const availableBytes = this.getAvailableBytes();
+    if (this.disposed || bytes > availableBytes) {
+      return { availableBytes, requestedBytes: bytes, status: 'over-budget' };
+    }
+    this.reservedBytes += bytes;
+    return {
+      lease: this.createOwnedLease(() => {
+        this.reservedBytes = Math.max(0, this.reservedBytes - bytes);
+      }),
+      status: 'ok',
+    };
+  }
+
+  getAvailableBytes(): number {
+    return Math.max(0, this.budgetBytes - this.snapshot().totalBytes);
+  }
+
+  pin(layerId: string, generation: number): RasterMemoryLease {
+    if (this.disposed) {
+      return { release: () => undefined };
+    }
+    const lease = this.createGenerationLease(generation, () => {
+      const layerPins = this.pins.get(layerId);
+      layerPins?.delete(lease);
+      if (layerPins?.size === 0) {
+        this.pins.delete(layerId);
+      }
+    });
+    const layerPins = this.pins.get(layerId) ?? new Set<RasterMemoryLease>();
+    layerPins.add(lease);
+    this.pins.set(layerId, layerPins);
+    return lease;
+  }
+
+  /** Pins a cache for an in-flight operation independently of lifecycle generations. */
+  pinOperation(layerId: string): RasterMemoryLease {
+    if (this.disposed) {
+      return { release: () => undefined };
+    }
+    const lease = this.createOwnedLease(() => {
+      const layerPins = this.pins.get(layerId);
+      layerPins?.delete(lease);
+      if (layerPins?.size === 0) {
+        this.pins.delete(layerId);
+      }
+    });
+    const layerPins = this.pins.get(layerId) ?? new Set<RasterMemoryLease>();
+    layerPins.add(lease);
+    this.pins.set(layerId, layerPins);
+    return lease;
+  }
+
+  isPinned(layerId: string): boolean {
+    return (this.pins.get(layerId)?.size ?? 0) > 0;
+  }
+
+  pinnedLayerIds(): string[] {
+    return [...this.pins.keys()];
+  }
+
+  releaseGeneration(generation: number): void {
+    const leases = [...(this.generationLeases.get(generation) ?? [])];
+    for (const lease of leases) {
+      lease.release();
+    }
+  }
+
+  snapshot(): RasterMemorySnapshot {
+    const detachedBytes = this.reportedDetachedBytes + this.leasedDetachedBytes;
+    return {
+      baseBytes: this.baseBytes,
+      decodedBytes: this.decodedBytes,
+      derivedBytes: this.derivedBytes,
+      detachedBytes,
+      reservedBytes: this.reservedBytes,
+      totalBytes: this.baseBytes + this.derivedBytes + this.decodedBytes + detachedBytes + this.reservedBytes,
+    };
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    while (this.generationLeases.size > 0) {
+      const generation = this.generationLeases.keys().next().value;
+      if (generation === undefined) {
+        break;
+      }
+      this.releaseGeneration(generation);
+    }
+    this.pins.clear();
+  }
+
+  private createGenerationLease(generation: number, onRelease: () => void): GenerationLease {
+    let released = false;
+    const lease: GenerationLease = {
+      generation,
+      release: () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        onRelease();
+        const generationSet = this.generationLeases.get(generation);
+        generationSet?.delete(lease);
+        if (generationSet?.size === 0) {
+          this.generationLeases.delete(generation);
+        }
+      },
+    };
+    const generationSet = this.generationLeases.get(generation) ?? new Set<GenerationLease>();
+    generationSet.add(lease);
+    this.generationLeases.set(generation, generationSet);
+    return lease;
+  }
+
+  private createOwnedLease(onRelease: () => void): RasterMemoryLease {
+    let released = false;
+    return {
+      release: () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        onRelease();
+      },
+    };
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterizeLayerController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterizeLayerController.ts
new file mode 100644
index 00000000000..2c547f71455
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/rasterizeLayerController.ts
@@ -0,0 +1,105 @@
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend } from '@workbench/canvas-engine/render/raster';
+import type { RasterizeDeps } from '@workbench/canvas-engine/render/rasterizers';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { getSourceContentRect } from '@workbench/canvas-engine/document/sources';
+import { roundOut, transformBounds } from '@workbench/canvas-engine/math/rect';
+import { rasterizeSource } from '@workbench/canvas-engine/render/rasterizers';
+import { bakeMatrix } from '@workbench/canvas-engine/transform/transformMath';
+
+export interface RasterizeLayerControllerOptions {
+  readonly backend: RasterBackend;
+  readonly layers: LayerCacheStore;
+  readonly history: History;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly rasterizeDeps: (document: CanvasDocumentContractV2) => RasterizeDeps;
+  readonly dispatch: (action: CanvasProjectMutation) => void;
+  readonly canEdit: () => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly endBurst: () => void;
+  readonly notifyPainted: (layerId: string) => void;
+  readonly markDirty: (layerId: string) => void;
+}
+
+/** Owns conversion of parametric raster layers into persisted paint pixels. */
+export class RasterizeLayerController {
+  private disposed = false;
+
+  constructor(private readonly deps: RasterizeLayerControllerOptions) {}
+
+  rasterize(layerId: string): boolean {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return false;
+    }
+    this.deps.endBurst();
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer || layer.type !== 'raster' || layer.isLocked) {
+      return false;
+    }
+    const source = layer.source;
+    if (
+      (source.type !== 'shape' && source.type !== 'gradient' && source.type !== 'text') ||
+      (source.type === 'shape' && source.kind === 'polygon')
+    ) {
+      return false;
+    }
+    const parametricLayer: CanvasLayerContract = structuredClone(layer);
+    const apply = (): void => {
+      const liveDocument = this.deps.getDocument();
+      const liveLayer = liveDocument?.layers.find((candidate) => candidate.id === layerId);
+      if (!liveDocument || !liveLayer || liveLayer.type !== 'raster') {
+        return;
+      }
+      const liveSource = liveLayer.source;
+      if (liveSource.type !== 'shape' && liveSource.type !== 'gradient' && liveSource.type !== 'text') {
+        return;
+      }
+      const contentRect = getSourceContentRect(liveLayer, liveDocument);
+      const entry = this.deps.layers.getOrCreateRect(layerId, contentRect);
+      entry.rect = contentRect;
+      entry.stale = true;
+      void rasterizeSource(liveSource, this.deps.rasterizeDeps(liveDocument), entry.surface).then((result) => {
+        entry.rect = result.rect;
+      });
+      entry.stale = false;
+      const matrix = bakeMatrix(liveLayer.transform);
+      const bakedRect = roundOut(transformBounds(matrix, contentRect));
+      const baked = this.deps.backend.createSurface(bakedRect.width, bakedRect.height);
+      baked.ctx.setTransform(1, 0, 0, 1, 0, 0);
+      baked.ctx.clearRect(0, 0, bakedRect.width, bakedRect.height);
+      baked.ctx.imageSmoothingEnabled = true;
+      baked.ctx.setTransform(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e - bakedRect.x, matrix.f - bakedRect.y);
+      baked.ctx.drawImage(entry.surface.canvas, contentRect.x, contentRect.y);
+      baked.ctx.setTransform(1, 0, 0, 1, 0, 0);
+      const paintLayer: CanvasLayerContract = {
+        ...liveLayer,
+        source: { bitmap: null, offset: { x: bakedRect.x, y: bakedRect.y }, type: 'paint' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      };
+      this.deps.dispatch({ id: layerId, layer: paintLayer, targetType: 'raster', type: 'convertCanvasLayer' });
+      this.deps.layers.delete(layerId);
+      const target = this.deps.layers.getOrCreateRect(layerId, bakedRect);
+      target.surface.ctx.drawImage(baked.canvas, 0, 0);
+      target.stale = false;
+      this.deps.notifyPainted(layerId);
+      this.deps.markDirty(layerId);
+    };
+    apply();
+    this.deps.history.push({
+      bytes: 256,
+      label: 'Rasterize layer',
+      redo: apply,
+      undo: () =>
+        this.deps.dispatch({ id: layerId, layer: parametricLayer, targetType: 'raster', type: 'convertCanvasLayer' }),
+    });
+    return true;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/renderController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/renderController.test.ts
new file mode 100644
index 00000000000..031a5a164ae
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/renderController.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { RenderController } from './renderController';
+
+describe('RenderController', () => {
+  it('owns scheduling lifecycle and disposes idempotently', () => {
+    let frame: FrameRequestCallback | null = null;
+    const render = vi.fn();
+    const controller = new RenderController({
+      applyCursor: vi.fn(),
+      cancelFrame: () => {
+        frame = null;
+      },
+      clearPreview: vi.fn(),
+      getInputHandlers: () =>
+        ({
+          onKeyDown: vi.fn(),
+          onKeyUp: vi.fn(),
+          onPointerCancel: vi.fn(),
+          onPointerDown: vi.fn(),
+          onPointerEnter: vi.fn(),
+          onPointerLeave: vi.fn(),
+          onPointerMove: vi.fn(),
+          onPointerUp: vi.fn(),
+          onWheel: vi.fn(),
+          reset: vi.fn(),
+        }) as never,
+      isEngineDisposed: () => false,
+      onPageHide: vi.fn(),
+      onVisibilityChange: vi.fn(),
+      onWindowBlur: vi.fn(),
+      render,
+      requestFrame: (callback) => {
+        frame = callback;
+        return 1;
+      },
+      setViewportReady: vi.fn(),
+      updateAnimation: vi.fn(),
+      updateCursor: vi.fn(),
+    });
+
+    controller.scheduler.invalidate({ overlay: true });
+    expect(frame).not.toBeNull();
+    const scheduled = frame as unknown as FrameRequestCallback;
+    frame = null;
+    scheduled(0);
+    expect(render).toHaveBeenCalledOnce();
+    controller.dispose();
+    controller.dispose();
+    controller.scheduler.invalidate({ all: true });
+    expect(frame).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/renderController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/renderController.ts
new file mode 100644
index 00000000000..f1c60737837
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/renderController.ts
@@ -0,0 +1,157 @@
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { RenderScheduler, RenderSchedulerDeps } from '@workbench/canvas-engine/render/scheduler';
+
+import { createRenderScheduler } from '@workbench/canvas-engine/render/scheduler';
+
+import { PreviewStateController } from './previewStateController';
+
+const wrapCanvasSurface = (canvas: HTMLCanvasElement): RasterSurface => {
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Failed to acquire a 2D context from the canvas element');
+  }
+  return {
+    canvas,
+    ctx,
+    get height() {
+      return canvas.height;
+    },
+    resize(width: number, height: number) {
+      canvas.width = width;
+      canvas.height = height;
+    },
+    get width() {
+      return canvas.width;
+    },
+  };
+};
+
+export interface RenderControllerOptions extends RenderSchedulerDeps {
+  readonly isEngineDisposed: () => boolean;
+  readonly getInputHandlers: () => {
+    onPointerDown: (event: PointerEvent) => void;
+    onPointerMove: (event: PointerEvent) => void;
+    onPointerUp: (event: PointerEvent) => void;
+    onPointerCancel: (event: PointerEvent) => void;
+    onPointerEnter: (event: PointerEvent) => void;
+    onPointerLeave: (event: PointerEvent) => void;
+    onKeyDown: (event: KeyboardEvent) => void;
+    onKeyUp: (event: KeyboardEvent) => void;
+    onWheel: (event: WheelEvent) => void;
+    reset(): void;
+  };
+  readonly onPageHide: () => void;
+  readonly onWindowBlur: () => void;
+  readonly onVisibilityChange: () => void;
+  readonly clearPreview: () => void;
+  readonly applyCursor: (value: string) => void;
+  readonly updateCursor: () => void;
+  readonly updateAnimation: () => void;
+  readonly setViewportReady: (ready: boolean) => void;
+}
+
+/** Owns render targets, scheduling, DOM input bindings, and attach/detach lifecycle. */
+export class RenderController {
+  readonly scheduler: RenderScheduler;
+  readonly previews = new PreviewStateController();
+  private screen: RasterSurface | null = null;
+  private overlay: RasterSurface | null = null;
+  private input: HTMLCanvasElement | null = null;
+  private disposed = false;
+
+  constructor(private readonly options: RenderControllerOptions) {
+    this.scheduler = createRenderScheduler(options);
+  }
+
+  getScreen(): RasterSurface | null {
+    return this.screen;
+  }
+
+  getOverlay(): RasterSurface | null {
+    return this.overlay;
+  }
+
+  getInputElement(): HTMLCanvasElement | null {
+    return this.input;
+  }
+
+  attach(screenCanvas: HTMLCanvasElement, overlayCanvas: HTMLCanvasElement): void {
+    if (this.disposed || this.options.isEngineDisposed()) {
+      return;
+    }
+    if (this.input) {
+      this.detach();
+    }
+    this.screen = wrapCanvasSurface(screenCanvas);
+    this.overlay = wrapCanvasSurface(overlayCanvas);
+    this.input = overlayCanvas;
+    const handlers = this.options.getInputHandlers();
+    this.input.addEventListener('pointerdown', handlers.onPointerDown);
+    this.input.addEventListener('pointermove', handlers.onPointerMove);
+    this.input.addEventListener('pointerup', handlers.onPointerUp);
+    this.input.addEventListener('pointercancel', handlers.onPointerCancel);
+    this.input.addEventListener('pointerenter', handlers.onPointerEnter);
+    this.input.addEventListener('pointerleave', handlers.onPointerLeave);
+    this.input.addEventListener('wheel', handlers.onWheel, { passive: false });
+    if (typeof globalThis.addEventListener === 'function') {
+      globalThis.addEventListener('keydown', handlers.onKeyDown);
+      globalThis.addEventListener('keyup', handlers.onKeyUp);
+      globalThis.addEventListener('pagehide', this.options.onPageHide);
+      globalThis.addEventListener('blur', this.options.onWindowBlur);
+    }
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', this.options.onVisibilityChange);
+    }
+    this.scheduler.resume();
+    this.options.setViewportReady(true);
+    this.options.updateCursor();
+    this.scheduler.invalidate({ all: true });
+    this.options.updateAnimation();
+  }
+
+  detach(): void {
+    const handlers = this.options.getInputHandlers();
+    if (this.input) {
+      this.input.removeEventListener('pointerdown', handlers.onPointerDown);
+      this.input.removeEventListener('pointermove', handlers.onPointerMove);
+      this.input.removeEventListener('pointerup', handlers.onPointerUp);
+      this.input.removeEventListener('pointercancel', handlers.onPointerCancel);
+      this.input.removeEventListener('pointerenter', handlers.onPointerEnter);
+      this.input.removeEventListener('pointerleave', handlers.onPointerLeave);
+      this.input.removeEventListener('wheel', handlers.onWheel);
+      this.options.applyCursor('');
+    }
+    if (typeof globalThis.removeEventListener === 'function') {
+      globalThis.removeEventListener('keydown', handlers.onKeyDown);
+      globalThis.removeEventListener('keyup', handlers.onKeyUp);
+      globalThis.removeEventListener('pagehide', this.options.onPageHide);
+      globalThis.removeEventListener('blur', this.options.onWindowBlur);
+    }
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this.options.onVisibilityChange);
+    }
+    handlers.reset();
+    this.options.clearPreview();
+    this.scheduler.pause();
+    this.options.setViewportReady(false);
+    this.screen = null;
+    this.overlay = null;
+    this.input = null;
+    this.options.updateAnimation();
+  }
+
+  resize(width: number, height: number): void {
+    this.screen?.resize(width, height);
+    this.overlay?.resize(width, height);
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.detach();
+    this.disposed = true;
+    this.scheduler.dispose();
+    this.previews.dispose();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionImageController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionImageController.ts
new file mode 100644
index 00000000000..5c4fe487960
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionImageController.ts
@@ -0,0 +1,86 @@
+import type { LayerExportGuard, ReplaceSelectionFromImageResult } from '@workbench/canvas-engine/api';
+import type { DecodeImageResult } from '@workbench/canvas-engine/controllers/rasterController';
+import type { SelectionState } from '@workbench/canvas-engine/selection/selectionState';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasImageRef } from '@workbench/types';
+
+export interface SelectionImageControllerOptions<Permit, Owner = symbol> {
+  readonly capturePermit: (owner?: Owner) => Permit | null;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly decodeImage: (
+    image: CanvasImageRef,
+    options: {
+      signal?: AbortSignal;
+      isCurrent?: () => boolean;
+      scaleToImage?: boolean;
+      validateDecoded?: (width: number, height: number) => void;
+    }
+  ) => Promise<DecodeImageResult>;
+  readonly isGestureActive: () => boolean;
+  readonly isGuardCurrent: (guard: LayerExportGuard) => boolean;
+  readonly isPermitCurrent: (permit: Permit) => boolean;
+  readonly selection: SelectionState;
+}
+
+/** Decodes guarded application results into the transient selection mask. */
+export class SelectionImageController<Permit, Owner = symbol> {
+  constructor(private readonly options: SelectionImageControllerOptions<Permit, Owner>) {}
+
+  async replace(
+    guard: LayerExportGuard,
+    image: CanvasImageRef,
+    rect: Rect,
+    signal?: AbortSignal,
+    owner?: Owner
+  ): Promise<ReplaceSelectionFromImageResult> {
+    const permit = this.options.capturePermit(owner);
+    if (!permit) {
+      return { status: 'busy' };
+    }
+    if (signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    try {
+      const decoded = await this.options.decodeImage(image, {
+        isCurrent: () => this.options.isPermitCurrent(permit),
+        signal,
+      });
+      if (decoded.status !== 'ok') {
+        return { status: decoded.status === 'aborted' ? 'aborted' : 'busy' };
+      }
+      const pixels = decoded.surface;
+      const document = this.options.getDocument();
+      if (!document) {
+        return { status: 'missing' };
+      }
+      const layer = document.layers.find((candidate) => candidate.id === guard.layerId);
+      if (!layer) {
+        return { status: 'missing' };
+      }
+      if (layer.isLocked) {
+        return { status: 'locked' };
+      }
+      if (layer.type !== 'raster' && layer.type !== 'control') {
+        return { status: 'unsupported' };
+      }
+      if (!this.options.isPermitCurrent(permit) || this.options.isGestureActive()) {
+        return { status: 'busy' };
+      }
+      if (!this.options.isGuardCurrent(guard)) {
+        return { status: 'stale' };
+      }
+      if (signal?.aborted) {
+        return { status: 'aborted' };
+      }
+      this.options.selection.replaceMask({ rect: { ...rect }, surface: pixels });
+      return { status: 'selected' };
+    } catch (error) {
+      if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
+        return { status: 'aborted' };
+      }
+      return { message: error instanceof Error ? error.message : String(error), status: 'failed' };
+    }
+  }
+
+  dispose(): void {}
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionPixelController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionPixelController.test.ts
new file mode 100644
index 00000000000..2c183133dd4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionPixelController.test.ts
@@ -0,0 +1,62 @@
+import type { SelectionState } from '@workbench/canvas-engine/selection/selectionState';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createHistory } from '@workbench/canvas-engine/history/history';
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { SelectionPixelController } from './selectionPixelController';
+
+describe('SelectionPixelController', () => {
+  it('owns raster fill persistence and history through declared ports', () => {
+    const backend = createTestStubRasterBackend();
+    const layers = createLayerCacheStore(backend);
+    layers.getOrCreateRect('paint', { height: 2, width: 2, x: 0, y: 0 });
+    const mask = backend.createSurface(2, 2);
+    mask.ctx.fillStyle = '#fff';
+    mask.ctx.fillRect(0, 0, 2, 2);
+    const selection = {
+      bounds: () => ({ height: 2, width: 2, x: 0, y: 0 }),
+      mask: () => ({ rect: { height: 2, width: 2, x: 0, y: 0 }, surface: mask }),
+    } as unknown as SelectionState;
+    const document = {
+      layers: [
+        {
+          id: 'paint',
+          isEnabled: true,
+          isLocked: false,
+          source: { type: 'paint' },
+          type: 'raster',
+        },
+      ],
+      selectedLayerId: 'paint',
+    } as CanvasDocumentContractV2;
+    const history = createHistory();
+    const markDirty = vi.fn();
+    const notifyPainted = vi.fn();
+    const controller = new SelectionPixelController({
+      applyImagePatch: vi.fn(),
+      backend,
+      beginControlEdit: () => null,
+      canEdit: () => true,
+      deleteDerived: vi.fn(),
+      endBurst: vi.fn(),
+      getDocument: () => document,
+      getFillColor: () => '#f00',
+      history,
+      invalidateLayer: vi.fn(),
+      isGestureActive: () => false,
+      layers,
+      markDirty,
+      notifyPainted,
+      selection,
+    });
+
+    controller.run('fill');
+
+    expect(markDirty).toHaveBeenCalledWith('paint');
+    expect(notifyPainted).toHaveBeenCalledWith('paint');
+    expect(history.canUndo()).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionPixelController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionPixelController.ts
new file mode 100644
index 00000000000..75b427caa57
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/selectionPixelController.ts
@@ -0,0 +1,266 @@
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { ImagePatchApply } from '@workbench/canvas-engine/history/imagePatch';
+import type { LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { SelectionState } from '@workbench/canvas-engine/selection/selectionState';
+import type { ControlPixelEditTransaction } from '@workbench/canvas-engine/tools/tool';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { getSourceBounds } from '@workbench/canvas-engine/document/sources';
+import { createImagePatchEntry } from '@workbench/canvas-engine/history/imagePatch';
+import { intersect, isEmpty, roundOut } from '@workbench/canvas-engine/math/rect';
+import { eraseMaskedRegion, fillMaskedRegion } from '@workbench/canvas-engine/selection/selectionOps';
+
+type PixelTarget =
+  | { kind: 'raster'; layerId: string; transparencyLocked: boolean }
+  | { kind: 'control'; transaction: ControlPixelEditTransaction; transparencyLocked: false };
+
+export interface SelectionPixelControllerOptions {
+  readonly selection: SelectionState;
+  readonly backend: RasterBackend;
+  readonly layers: LayerCacheStore;
+  readonly history: History;
+  readonly applyImagePatch: ImagePatchApply;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly beginControlEdit: (layerId: string) => ControlPixelEditTransaction | null;
+  readonly canEdit: () => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly getFillColor: () => string;
+  readonly endBurst: () => void;
+  readonly deleteDerived: (layerId: string) => void;
+  readonly invalidateLayer: (layerId: string) => void;
+  readonly notifyPainted: (layerId: string) => void;
+  readonly markDirty: (layerId: string) => void;
+}
+
+const imageDataEqual = (left: ImageData, right: ImageData): boolean => {
+  if (left.width !== right.width || left.height !== right.height || left.data.length !== right.data.length) {
+    return false;
+  }
+  for (let index = 0; index < left.data.length; index += 1) {
+    if (left.data[index] !== right.data[index]) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/** Owns selection-driven fill/erase pixel transactions. */
+export class SelectionPixelController {
+  private disposed = false;
+
+  constructor(private readonly deps: SelectionPixelControllerOptions) {}
+
+  private target(): PixelTarget | null {
+    const document = this.deps.getDocument();
+    if (!document?.selectedLayerId) {
+      return null;
+    }
+    const layer = document.layers.find((candidate) => candidate.id === document.selectedLayerId);
+    if (layer?.type === 'raster' && layer.source.type === 'paint' && !layer.isLocked && layer.isEnabled) {
+      return { kind: 'raster', layerId: layer.id, transparencyLocked: layer.isTransparencyLocked === true };
+    }
+    if (layer?.type === 'control') {
+      const transaction = this.deps.beginControlEdit(layer.id);
+      return transaction ? { kind: 'control', transaction, transparencyLocked: false } : null;
+    }
+    return null;
+  }
+
+  run(kind: 'fill' | 'erase'): void {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return;
+    }
+    const document = this.deps.getDocument();
+    const placedMask = this.deps.selection.mask();
+    const bounds = this.deps.selection.bounds();
+    if (!document || !placedMask || !bounds) {
+      return;
+    }
+    const selectionRect = roundOut(bounds);
+    const selectedLayer = document.layers.find((candidate) => candidate.id === document.selectedLayerId);
+    if (
+      kind === 'erase' &&
+      selectedLayer?.type === 'control' &&
+      !intersect(selectionRect, roundOut(getSourceBounds(selectedLayer, document)))
+    ) {
+      return;
+    }
+    const target = this.target();
+    if (!target) {
+      return;
+    }
+    const cancelControl = (): void => {
+      if (target.kind === 'control') {
+        target.transaction.cancel();
+      }
+    };
+    if (kind === 'erase' && target.transparencyLocked) {
+      cancelControl();
+      return;
+    }
+    const layerId = target.kind === 'control' ? target.transaction.layerId : target.layerId;
+    let before: ImageData | null = null;
+    let editOrigin: { x: number; y: number } | null = null;
+    let editRect: Rect | null = null;
+    let editSurface: RasterSurface | null = null;
+    let commitStarted = false;
+    let rollbackStarted = false;
+    let growthSnapshot:
+      | {
+          hasPublishedPixels: boolean;
+          lastUsed: number;
+          pixels: ImageData | null;
+          rect: Rect;
+          stale: boolean;
+          surface: RasterSurface;
+          version: number;
+        }
+      | null
+      | undefined;
+    const rollback = (): void => {
+      if (target.kind !== 'control' || rollbackStarted) {
+        return;
+      }
+      rollbackStarted = true;
+      try {
+        if (growthSnapshot !== undefined) {
+          if (growthSnapshot === null) {
+            this.deps.layers.delete(layerId);
+          } else {
+            const current = this.deps.layers.get(layerId);
+            if (current) {
+              growthSnapshot.surface.resize(growthSnapshot.rect.width, growthSnapshot.rect.height);
+              if (growthSnapshot.pixels) {
+                growthSnapshot.surface.ctx.putImageData(growthSnapshot.pixels, 0, 0);
+              }
+              current.hasPublishedPixels = growthSnapshot.hasPublishedPixels;
+              current.lastUsed = growthSnapshot.lastUsed;
+              current.rect = { ...growthSnapshot.rect };
+              current.stale = growthSnapshot.stale;
+              current.surface = growthSnapshot.surface;
+              current.version = growthSnapshot.version;
+            }
+          }
+          this.deps.deleteDerived(layerId);
+          this.deps.invalidateLayer(layerId);
+        } else if (before && editOrigin && editRect && editSurface) {
+          editSurface.ctx.putImageData(before, editRect.x - editOrigin.x, editRect.y - editOrigin.y);
+          this.deps.deleteDerived(layerId);
+          this.deps.invalidateLayer(layerId);
+        }
+      } finally {
+        target.transaction.cancel();
+      }
+    };
+    try {
+      if (target.kind === 'control' && kind === 'fill') {
+        const existing = this.deps.layers.get(layerId);
+        const needsGrowth =
+          !existing ||
+          isEmpty(existing.rect) ||
+          selectionRect.x < existing.rect.x ||
+          selectionRect.y < existing.rect.y ||
+          selectionRect.x + selectionRect.width > existing.rect.x + existing.rect.width ||
+          selectionRect.y + selectionRect.height > existing.rect.y + existing.rect.height;
+        if (needsGrowth) {
+          growthSnapshot = existing
+            ? {
+                hasPublishedPixels: existing.hasPublishedPixels,
+                lastUsed: existing.lastUsed,
+                pixels: isEmpty(existing.rect)
+                  ? null
+                  : existing.surface.ctx.getImageData(0, 0, existing.rect.width, existing.rect.height),
+                rect: { ...existing.rect },
+                stale: existing.stale,
+                surface: existing.surface,
+                version: existing.version,
+              }
+            : null;
+        }
+      }
+      let rect: Rect | null;
+      let entry;
+      if (kind === 'fill' && !target.transparencyLocked) {
+        rect = selectionRect;
+        entry = this.deps.layers.growToRect(layerId, selectionRect);
+      } else {
+        const existing = this.deps.layers.get(layerId);
+        if (!existing || isEmpty(existing.rect)) {
+          cancelControl();
+          return;
+        }
+        rect = intersect(selectionRect, existing.rect);
+        entry = existing;
+      }
+      if (!rect || isEmpty(rect)) {
+        cancelControl();
+        return;
+      }
+      this.deps.endBurst();
+      const surface = entry.surface;
+      const origin = { x: entry.rect.x, y: entry.rect.y };
+      before = surface.ctx.getImageData(rect.x - origin.x, rect.y - origin.y, rect.width, rect.height);
+      editOrigin = origin;
+      editRect = rect;
+      editSurface = surface;
+      if (kind === 'fill') {
+        fillMaskedRegion({
+          backend: this.deps.backend,
+          color: this.deps.getFillColor(),
+          composite: target.transparencyLocked ? 'source-atop' : 'source-over',
+          mask: placedMask.surface,
+          maskOrigin: placedMask.rect,
+          rect,
+          target: surface,
+          targetOrigin: origin,
+        });
+      } else {
+        eraseMaskedRegion({
+          backend: this.deps.backend,
+          mask: placedMask.surface,
+          maskOrigin: placedMask.rect,
+          rect,
+          target: surface,
+          targetOrigin: origin,
+        });
+      }
+      const after = surface.ctx.getImageData(rect.x - origin.x, rect.y - origin.y, rect.width, rect.height);
+      const label = kind === 'fill' ? 'Fill selection' : 'Erase selection';
+      if (target.kind === 'control') {
+        if (imageDataEqual(before, after)) {
+          rollback();
+          return;
+        }
+        commitStarted = true;
+        target.transaction.commitPatch(label, { after, before, rect });
+      } else {
+        this.deps.notifyPainted(target.layerId);
+        this.deps.markDirty(target.layerId);
+        if (!this.deps.history.isApplying()) {
+          this.deps.history.push(
+            createImagePatchEntry({
+              after,
+              apply: this.deps.applyImagePatch,
+              before,
+              label,
+              layerId: target.layerId,
+              rect,
+            })
+          );
+        }
+      }
+    } catch (error) {
+      if (target.kind !== 'control' || commitStarted) {
+        throw error;
+      }
+      rollback();
+      throw error;
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.integration.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.integration.test.ts
new file mode 100644
index 00000000000..a247b1c0be3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.integration.test.ts
@@ -0,0 +1,151 @@
+import type { CanvasProjectMutationPort } from '@workbench/canvasProjectMutationPort';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasStagingCandidateContract } from '@workbench/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { createCanvasEngine } from '@workbench/canvas-operations/createCanvasEngine';
+import { createCanvasProjectMutationPort } from '@workbench/canvasProjectMutationPort';
+import { createWorkbenchStore } from '@workbench/workbenchStore';
+import { describe, expect, it } from 'vitest';
+
+const candidate: CanvasStagingCandidateContract = {
+  height: 40,
+  imageName: 'rollback-result.png',
+  imageUrl: '/rollback-result.png',
+  placement: { height: 80, opacity: 0.5, width: 60, x: 12, y: 18 },
+  queuedAt: '2026-07-16T00:00:00.000Z',
+  sourceQueueItemId: 'queue-rollback',
+  thumbnailUrl: '/rollback-result-thumb.png',
+  width: 30,
+};
+const selection = { candidate, selectedImageIndex: 0 } as const;
+
+const createMirrorRejectingPort = (
+  store: ReturnType<typeof createWorkbenchStore>,
+  projectId: string
+): { arm: (type: CanvasProjectMutation['type']) => void; port: CanvasProjectMutationPort } => {
+  const real = createCanvasProjectMutationPort(store, projectId);
+  let faultActive = false;
+  let readsAfterCommit = 0;
+  let armedType: CanvasProjectMutation['type'] | null = null;
+  const port: CanvasProjectMutationPort = {
+    dispatch: (mutation) => {
+      if (mutation.type === armedType) {
+        faultActive = true;
+        readsAfterCommit = 0;
+        armedType = null;
+      } else {
+        faultActive = false;
+      }
+      return real.dispatch(mutation);
+    },
+    getCanvasState: () => {
+      if (faultActive) {
+        readsAfterCommit += 1;
+        if (readsAfterCommit === 1 || readsAfterCommit === 3) {
+          throw new Error('document mirror read failed');
+        }
+      }
+      return real.getCanvasState();
+    },
+    subscribe: real.subscribe,
+  };
+  return { arm: (type) => (armedType = type), port };
+};
+
+describe('staged result project-port integration', () => {
+  it('commits the actually selected slot when duplicate candidate keys have different placements', () => {
+    const store = createWorkbenchStore();
+    const projectId = store.getState().activeProjectId;
+    const first = { ...candidate, placement: { ...candidate.placement, x: 10 } };
+    const selected = { ...candidate, placement: { ...candidate.placement, x: 90 } };
+    store.dispatch({ candidate: first, projectId, type: 'appendCanvasStagingCandidate' });
+    store.dispatch({ candidate: selected, projectId, type: 'appendCanvasStagingCandidate' });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort: createCanvasProjectMutationPort(store, projectId),
+      projectId,
+      reportError: () => undefined,
+    });
+
+    const result = engine.layers.commitStagedImage({ candidate: selected, selectedImageIndex: 1 });
+
+    expect(result.status).toBe('committed');
+    expect(store.getState().projects[0]?.canvas.document.layers[0]?.transform.x).toBe(90);
+    engine.lifecycle.dispose();
+  });
+
+  it('rolls back the exact layer, event, selection, and staging when initial mirror acceptance fails', () => {
+    const store = createWorkbenchStore();
+    const projectId = store.getState().activeProjectId;
+    store.dispatch({ candidate, projectId, type: 'appendCanvasStagingCandidate' });
+    const before = structuredClone(store.getState().projects.find((project) => project.id === projectId)!);
+    const rejectingPort = createMirrorRejectingPort(store, projectId);
+    rejectingPort.arm('commitStagedImage');
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort: rejectingPort.port,
+      projectId,
+      reportError: () => undefined,
+    });
+
+    expect(engine.layers.commitStagedImage(selection)).toEqual({
+      status: 'stale',
+    });
+    expect(store.getState().projects.find((project) => project.id === projectId)).toEqual(before);
+    expect(engine.document.getDocument()).toEqual(before.canvas.document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('compensates a reducer-accepted undo when mirror acceptance fails and keeps history retryable', () => {
+    const store = createWorkbenchStore();
+    const projectId = store.getState().activeProjectId;
+    store.dispatch({ candidate, projectId, type: 'appendCanvasStagingCandidate' });
+    const rejectingPort = createMirrorRejectingPort(store, projectId);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort: rejectingPort.port,
+      projectId,
+      reportError: () => undefined,
+    });
+    expect(engine.layers.commitStagedImage(selection).status).toBe('committed');
+    const accepted = structuredClone(store.getState().projects.find((project) => project.id === projectId)!);
+    rejectingPort.arm('applyCanvasLayerStackMutation');
+
+    expect(() => engine.history.undo()).toThrow('document mirror read failed');
+    expect(store.getState().projects.find((project) => project.id === projectId)).toEqual(accepted);
+    expect(engine.document.getDocument()).toEqual(accepted.canvas.document);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('compensates a reducer-accepted redo when mirror acceptance fails and keeps history retryable', () => {
+    const store = createWorkbenchStore();
+    const projectId = store.getState().activeProjectId;
+    store.dispatch({ candidate, projectId, type: 'appendCanvasStagingCandidate' });
+    const rejectingPort = createMirrorRejectingPort(store, projectId);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort: rejectingPort.port,
+      projectId,
+      reportError: () => undefined,
+    });
+    expect(engine.layers.commitStagedImage(selection).status).toBe('committed');
+    engine.history.undo();
+    const undone = structuredClone(store.getState().projects.find((project) => project.id === projectId)!);
+    rejectingPort.arm('applyCanvasLayerStackMutation');
+
+    expect(() => engine.history.redo()).toThrow('document mirror read failed');
+    expect(store.getState().projects.find((project) => project.id === projectId)).toEqual(undone);
+    expect(engine.document.getDocument()).toEqual(undone.canvas.document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.test.ts
new file mode 100644
index 00000000000..d664eaad3d1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.test.ts
@@ -0,0 +1,296 @@
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasStagingCandidateContract, CanvasStateContractV2 } from '@workbench/types';
+
+import { createHistory } from '@workbench/canvas-engine/history/history';
+import { describe, expect, it, vi } from 'vitest';
+
+import { StagedResultController } from './stagedResultController';
+
+const candidate: CanvasStagingCandidateContract = {
+  height: 40,
+  imageName: 'result.png',
+  imageUrl: '/result.png',
+  placement: { height: 80, opacity: 0.5, width: 60, x: 12, y: 18 },
+  queuedAt: '2026-07-16T00:00:00.000Z',
+  sourceQueueItemId: 'queue-1',
+  thumbnailUrl: '/thumb.png',
+  width: 30,
+};
+const selection = { candidate, selectedImageIndex: 0 } as const;
+
+const makeCanvas = (): CanvasStateContractV2 => ({
+  document: {
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers: [],
+    selectedLayerId: null,
+    version: 2,
+    width: 100,
+  },
+  documentRevision: 0,
+  snapshots: [],
+  stagingArea: {
+    areThumbnailsVisible: false,
+    autoSwitchMode: 'off',
+    isVisible: true,
+    pendingImageIds: [candidate.imageName],
+    pendingImages: [candidate],
+    selectedImageIndex: 0,
+  },
+  version: 2,
+});
+
+describe('StagedResultController', () => {
+  it('commits the guarded candidate and records history only after reducer and mirror acceptance', () => {
+    let reducerCanvas = makeCanvas();
+    let mirrorDocument = reducerCanvas.document;
+    const history = createHistory();
+    const dispatchPrepared = vi.fn(
+      (mutation: CanvasProjectMutation, reducerAccepted: () => boolean, mirrorAccepted: () => boolean) => {
+        if (mutation.type === 'applyCanvasLayerStackMutation') {
+          reducerCanvas = {
+            ...reducerCanvas,
+            document: {
+              ...reducerCanvas.document,
+              layers: mutation.removeIds
+                ? reducerCanvas.document.layers.filter((layer) => !mutation.removeIds?.includes(layer.id))
+                : mutation.add
+                  ? [...mutation.add.layers, ...reducerCanvas.document.layers]
+                  : reducerCanvas.document.layers,
+              selectedLayerId: mutation.selectedLayerId,
+            },
+          };
+          expect(reducerAccepted()).toBe(true);
+          expect(mirrorAccepted()).toBe(false);
+          mirrorDocument = reducerCanvas.document;
+          expect(mirrorAccepted()).toBe(true);
+          return;
+        }
+        expect(mutation).toMatchObject({ selectedImageIndex: 0, type: 'commitStagedImage' });
+        if (mutation.type !== 'commitStagedImage') {
+          throw new Error('unexpected mutation');
+        }
+        const layer = mutation.layer;
+        reducerCanvas = {
+          ...reducerCanvas,
+          document: { ...reducerCanvas.document, layers: [layer], selectedLayerId: layer.id },
+          stagingArea: { ...reducerCanvas.stagingArea, isVisible: false, pendingImageIds: [], pendingImages: [] },
+        };
+        mirrorDocument = reducerCanvas.document;
+        expect(reducerAccepted()).toBe(true);
+        expect(mirrorAccepted()).toBe(true);
+      }
+    );
+    const controller = new StagedResultController({
+      capturePermit: () => ({ epoch: 1 }),
+      createEventId: () => 'event-1',
+      createLayerId: () => 'layer-1',
+      dispatchPrepared,
+      endBurst: vi.fn(),
+      getCanvasState: () => reducerCanvas,
+      getDocument: () => mirrorDocument,
+      history,
+      isGestureActive: () => false,
+      isPermitCurrent: () => true,
+      now: () => '2026-07-16T01:00:00.000Z',
+    });
+
+    expect(controller.commit(selection)).toEqual({ status: 'committed', layerId: 'layer-1' });
+    expect(reducerCanvas.document.layers[0]).toMatchObject({
+      id: 'layer-1',
+      opacity: 0.5,
+      source: { image: { imageName: 'result.png' }, type: 'image' },
+      transform: { scaleX: 2, scaleY: 2, x: 12, y: 18 },
+      type: 'raster',
+    });
+    expect(history.canUndo()).toBe(true);
+
+    history.undo();
+    expect(reducerCanvas.document.layers).toEqual([]);
+    expect(reducerCanvas.document.selectedLayerId).toBeNull();
+    expect(reducerCanvas.stagingArea.pendingImages).toEqual([]);
+
+    history.redo();
+    expect(reducerCanvas.document.layers[0]).toBe(reducerCanvas.document.layers[0]);
+    expect(reducerCanvas.document.layers[0]?.id).toBe('layer-1');
+    expect(reducerCanvas.stagingArea.pendingImages).toEqual([]);
+  });
+
+  it('returns stale without history when the selected candidate changes before reducer acceptance', () => {
+    const canvas = makeCanvas();
+    const history = createHistory();
+    const controller = new StagedResultController({
+      capturePermit: () => ({ epoch: 1 }),
+      createEventId: () => 'event-1',
+      createLayerId: () => 'layer-1',
+      dispatchPrepared: () => {
+        throw new Error('reducer rejected stale candidate');
+      },
+      endBurst: vi.fn(),
+      getCanvasState: () => canvas,
+      getDocument: () => canvas.document,
+      history,
+      isGestureActive: () => false,
+      isPermitCurrent: () => true,
+      now: () => '2026-07-16T01:00:00.000Z',
+    });
+
+    expect(controller.commit(selection)).toEqual({ status: 'stale' });
+    expect(canvas.document.layers).toEqual([]);
+    expect(canvas.stagingArea.pendingImages).toEqual([candidate]);
+    expect(history.canUndo()).toBe(false);
+  });
+
+  it.each([
+    { gestureActive: false, name: 'edit lease is unavailable', permit: null, permitCurrent: false },
+    { gestureActive: true, name: 'a gesture is active', permit: { epoch: 1 }, permitCurrent: true },
+    { gestureActive: false, name: 'the captured edit permit is stale', permit: { epoch: 1 }, permitCurrent: false },
+  ])('returns busy without mutation when $name', ({ gestureActive, permit, permitCurrent }) => {
+    const canvas = makeCanvas();
+    const dispatchPrepared = vi.fn();
+    const history = createHistory();
+    const controller = new StagedResultController({
+      capturePermit: () => permit,
+      createEventId: () => 'event-1',
+      createLayerId: () => 'layer-1',
+      dispatchPrepared,
+      endBurst: vi.fn(),
+      getCanvasState: () => canvas,
+      getDocument: () => canvas.document,
+      history,
+      isGestureActive: () => gestureActive,
+      isPermitCurrent: () => permitCurrent,
+      now: () => '2026-07-16T01:00:00.000Z',
+    });
+
+    expect(controller.commit(selection)).toEqual({ status: 'busy' });
+    expect(dispatchPrepared).not.toHaveBeenCalled();
+    expect(history.canUndo()).toBe(false);
+  });
+
+  it.each(['reducer', 'mirror'])('does not record history when %s acceptance rejects the commit', () => {
+    const canvas = makeCanvas();
+    const history = createHistory();
+    const controller = new StagedResultController({
+      capturePermit: () => ({ epoch: 1 }),
+      createEventId: () => 'event-1',
+      createLayerId: () => 'layer-1',
+      dispatchPrepared: () => {
+        throw new Error('acceptance rejected');
+      },
+      endBurst: vi.fn(),
+      getCanvasState: () => canvas,
+      getDocument: () => canvas.document,
+      history,
+      isGestureActive: () => false,
+      isPermitCurrent: () => true,
+      now: () => '2026-07-16T01:00:00.000Z',
+    });
+
+    expect(controller.commit(selection)).toEqual({ status: 'stale' });
+    expect(canvas.stagingArea.pendingImages).toEqual([candidate]);
+    expect(history.canUndo()).toBe(false);
+  });
+
+  it('clears the redo stack after a new staged image commit', () => {
+    let reducerCanvas = makeCanvas();
+    let mirrorDocument = reducerCanvas.document;
+    const history = createHistory();
+    history.push({ bytes: 1, label: 'older edit', redo: vi.fn(), undo: vi.fn() });
+    history.undo();
+    expect(history.canRedo()).toBe(true);
+    const controller = new StagedResultController({
+      capturePermit: () => ({ epoch: 1 }),
+      createEventId: () => 'event-1',
+      createLayerId: () => 'layer-1',
+      dispatchPrepared: (mutation, reducerAccepted, mirrorAccepted) => {
+        if (mutation.type !== 'commitStagedImage') {
+          throw new Error('unexpected mutation');
+        }
+        reducerCanvas = {
+          ...reducerCanvas,
+          document: {
+            ...reducerCanvas.document,
+            layers: [mutation.layer],
+            selectedLayerId: mutation.layer.id,
+          },
+          stagingArea: {
+            ...reducerCanvas.stagingArea,
+            isVisible: false,
+            pendingImageIds: [],
+            pendingImages: [],
+            selectedImageIndex: 0,
+          },
+        };
+        expect(reducerAccepted()).toBe(true);
+        mirrorDocument = reducerCanvas.document;
+        expect(mirrorAccepted()).toBe(true);
+      },
+      endBurst: vi.fn(),
+      getCanvasState: () => reducerCanvas,
+      getDocument: () => mirrorDocument,
+      history,
+      isGestureActive: () => false,
+      isPermitCurrent: () => true,
+      now: () => '2026-07-16T01:00:00.000Z',
+    });
+
+    expect(controller.commit(selection).status).toBe('committed');
+    expect(history.canRedo()).toBe(false);
+  });
+
+  it.each([
+    { canvas: null, name: 'project', options: selection },
+    {
+      canvas: makeCanvas(),
+      name: 'candidate',
+      options: { candidate: { ...candidate, imageName: 'missing.png' }, selectedImageIndex: 0 },
+    },
+  ])('returns missing without mutation when the $name is absent', ({ canvas, options }) => {
+    const dispatchPrepared = vi.fn();
+    const history = createHistory();
+    const controller = new StagedResultController({
+      capturePermit: () => ({ epoch: 1 }),
+      createEventId: () => 'event-1',
+      createLayerId: () => 'layer-1',
+      dispatchPrepared,
+      endBurst: vi.fn(),
+      getCanvasState: () => canvas,
+      getDocument: () => canvas?.document ?? null,
+      history,
+      isGestureActive: () => false,
+      isPermitCurrent: () => true,
+      now: () => '2026-07-16T01:00:00.000Z',
+    });
+
+    expect(controller.commit(options)).toEqual({ status: 'missing' });
+    expect(dispatchPrepared).not.toHaveBeenCalled();
+    expect(history.canUndo()).toBe(false);
+  });
+
+  it('rejects retained commit capabilities after disposal', () => {
+    const canvas = makeCanvas();
+    const dispatchPrepared = vi.fn();
+    const history = createHistory();
+    const controller = new StagedResultController({
+      capturePermit: () => ({ epoch: 1 }),
+      createEventId: () => 'event-1',
+      createLayerId: () => 'layer-1',
+      dispatchPrepared,
+      endBurst: vi.fn(),
+      getCanvasState: () => canvas,
+      getDocument: () => canvas.document,
+      history,
+      isGestureActive: () => false,
+      isPermitCurrent: () => true,
+      now: () => '2026-07-16T01:00:00.000Z',
+    });
+
+    controller.dispose();
+
+    expect(controller.commit(selection)).toEqual({ status: 'missing' });
+    expect(dispatchPrepared).not.toHaveBeenCalled();
+    expect(history.canUndo()).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.ts
new file mode 100644
index 00000000000..53648c52370
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/stagedResultController.ts
@@ -0,0 +1,211 @@
+import type { CommitStagedImageOptions, CommitStagedImageResult } from '@workbench/canvas-engine/api';
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type {
+  CanvasDocumentContractV2,
+  CanvasRasterLayerContractV2,
+  CanvasStagingCandidateContract,
+  CanvasStateContractV2,
+  ProjectEvent,
+} from '@workbench/types';
+
+import { getCanvasStagingCandidateFingerprint } from '@workbench/canvasStagingView';
+
+export interface StagedResultControllerOptions<Permit, Owner = symbol> {
+  readonly capturePermit: (owner?: Owner) => Permit | null;
+  readonly createEventId: () => string;
+  readonly createLayerId: () => string;
+  readonly dispatchPrepared: (
+    mutation: CanvasProjectMutation,
+    reducerAccepted: () => boolean,
+    mirrorAccepted: () => boolean
+  ) => void;
+  readonly endBurst: () => void;
+  readonly getCanvasState: () => CanvasStateContractV2 | null;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly history: History;
+  readonly isGestureActive: () => boolean;
+  readonly isPermitCurrent: (permit: Permit) => boolean;
+  readonly now: () => string;
+}
+
+const createLayer = (
+  id: string,
+  name: string,
+  candidate: CanvasStagingCandidateContract
+): CanvasRasterLayerContractV2 => {
+  const { placement } = candidate;
+  return {
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name,
+    opacity: placement.opacity,
+    source: {
+      image: { height: candidate.height, imageName: candidate.imageName, width: candidate.width },
+      type: 'image',
+    },
+    transform: {
+      rotation: 0,
+      scaleX: candidate.width === 0 ? 1 : placement.width / candidate.width,
+      scaleY: candidate.height === 0 ? 1 : placement.height / candidate.height,
+      x: placement.x,
+      y: placement.y,
+    },
+    type: 'raster',
+  };
+};
+
+/** Owns guarded, project-bound acceptance of staged canvas results. */
+export class StagedResultController<Permit, Owner = symbol> {
+  private disposed = false;
+
+  constructor(private readonly options: StagedResultControllerOptions<Permit, Owner>) {}
+
+  commit(options: CommitStagedImageOptions, owner?: Owner): CommitStagedImageResult {
+    const o = this.options;
+    if (this.disposed) {
+      return { status: 'missing' };
+    }
+    const permit = o.capturePermit(owner);
+    if (!permit || o.isGestureActive()) {
+      return { status: 'busy' };
+    }
+    const canvas = o.getCanvasState();
+    if (!canvas) {
+      return { status: 'missing' };
+    }
+    const candidateFingerprint = getCanvasStagingCandidateFingerprint(options.candidate);
+    if (
+      !canvas.stagingArea.pendingImages.some(
+        (pending) => getCanvasStagingCandidateFingerprint(pending) === candidateFingerprint
+      )
+    ) {
+      return { status: 'missing' };
+    }
+    if (!o.isPermitCurrent(permit) || o.isGestureActive()) {
+      return { status: 'busy' };
+    }
+
+    const layer = createLayer(o.createLayerId(), `Layer ${canvas.document.layers.length + 1}`, options.candidate);
+    const event: ProjectEvent = {
+      createdAt: o.now(),
+      id: o.createEventId(),
+      summary: `Accepted ${options.candidate.imageName} into a new raster layer`,
+      type: 'canvas-layer-accepted',
+    };
+    const previousSelectedLayerId = canvas.document.selectedLayerId;
+    const previousLayers = canvas.document.layers;
+    const acceptedLayers = [layer, ...previousLayers];
+    const previousStagingArea = structuredClone(canvas.stagingArea);
+    const hasPreviousLayerStack = (document: CanvasDocumentContractV2 | null): boolean =>
+      document?.selectedLayerId === previousSelectedLayerId &&
+      document.layers.length === previousLayers.length &&
+      document.layers.every((current, index) => current === previousLayers[index]);
+    const hasAcceptedLayerStack = (document: CanvasDocumentContractV2 | null): boolean =>
+      document?.selectedLayerId === layer.id &&
+      document.layers.length === acceptedLayers.length &&
+      document.layers.every((current, index) => current === acceptedLayers[index]);
+    const isCommitted = (next: CanvasStateContractV2 | null): boolean =>
+      next?.document.selectedLayerId === layer.id &&
+      next.document.layers.some((current) => current === layer) &&
+      next.stagingArea.pendingImages.length === 0 &&
+      next.stagingArea.pendingImageIds.length === 0 &&
+      next.stagingArea.selectedImageIndex === 0 &&
+      !next.stagingArea.isVisible;
+    const isMirrored = (): boolean =>
+      o.getDocument()?.selectedLayerId === layer.id &&
+      o.getDocument()?.layers.some((current) => current === layer) === true;
+
+    try {
+      o.endBurst();
+      o.dispatchPrepared(
+        {
+          candidateFingerprint,
+          event,
+          layer,
+          selectedImageIndex: options.selectedImageIndex,
+          type: 'commitStagedImage',
+        },
+        () => isCommitted(o.getCanvasState()),
+        isMirrored
+      );
+    } catch {
+      if (isCommitted(o.getCanvasState())) {
+        o.dispatchPrepared(
+          {
+            event,
+            layer,
+            selectedLayerId: previousSelectedLayerId,
+            stagingArea: previousStagingArea,
+            type: 'rollbackStagedImageCommit',
+          },
+          () =>
+            hasPreviousLayerStack(o.getCanvasState()?.document ?? null) &&
+            o.getCanvasState()?.stagingArea === previousStagingArea,
+          () => hasPreviousLayerStack(o.getDocument())
+        );
+      }
+      return { status: 'stale' };
+    }
+
+    const applyLayerStack = (
+      mutation: Extract<CanvasProjectMutation, { type: 'applyCanvasLayerStackMutation' }>,
+      reducerAccepted: () => boolean,
+      mirrorAccepted: () => boolean,
+      rollback: Extract<CanvasProjectMutation, { type: 'applyCanvasLayerStackMutation' }>,
+      reducerRolledBack: () => boolean,
+      mirrorRolledBack: () => boolean
+    ): void => {
+      try {
+        o.dispatchPrepared(mutation, reducerAccepted, mirrorAccepted);
+      } catch (error) {
+        if (reducerAccepted()) {
+          o.dispatchPrepared(rollback, reducerRolledBack, mirrorRolledBack);
+        }
+        throw error;
+      }
+    };
+    const addAcceptedLayer: Extract<CanvasProjectMutation, { type: 'applyCanvasLayerStackMutation' }> = {
+      add: { index: 0, layers: [layer] },
+      enabledUpdates: [],
+      selectedLayerId: layer.id,
+      type: 'applyCanvasLayerStackMutation',
+    };
+    const removeAcceptedLayer: Extract<CanvasProjectMutation, { type: 'applyCanvasLayerStackMutation' }> = {
+      enabledUpdates: [],
+      removeIds: [layer.id],
+      selectedLayerId: previousSelectedLayerId,
+      type: 'applyCanvasLayerStackMutation',
+    };
+    o.history.push({
+      bytes: 256,
+      label: 'Accept staged image',
+      redo: () =>
+        applyLayerStack(
+          addAcceptedLayer,
+          () => hasAcceptedLayerStack(o.getCanvasState()?.document ?? null),
+          () => hasAcceptedLayerStack(o.getDocument()),
+          removeAcceptedLayer,
+          () => hasPreviousLayerStack(o.getCanvasState()?.document ?? null),
+          () => hasPreviousLayerStack(o.getDocument())
+        ),
+      replayFailureAtomic: true,
+      undo: () =>
+        applyLayerStack(
+          removeAcceptedLayer,
+          () => hasPreviousLayerStack(o.getCanvasState()?.document ?? null),
+          () => hasPreviousLayerStack(o.getDocument()),
+          addAcceptedLayer,
+          () => hasAcceptedLayerStack(o.getCanvasState()?.document ?? null),
+          () => hasAcceptedLayerStack(o.getDocument())
+        ),
+    });
+    return { layerId: layer.id, status: 'committed' };
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/structuralLayerController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/structuralLayerController.test.ts
new file mode 100644
index 00000000000..36bb7244e20
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/structuralLayerController.test.ts
@@ -0,0 +1,112 @@
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createHistory } from '@workbench/canvas-engine/history/history';
+import { describe, expect, it, vi } from 'vitest';
+
+import { StructuralLayerController } from './structuralLayerController';
+
+describe('StructuralLayerController', () => {
+  it('reports whether a structural commit is currently allowed and committed', () => {
+    const dispatch = vi.fn();
+    const history = createHistory();
+    const controller = new StructuralLayerController({
+      canEdit: () => true,
+      dispatch,
+      getDocument: () => null,
+      history,
+      isGestureActive: () => false,
+    });
+    const forward = { id: 'layer', type: 'setCanvasSelectedLayer' } as const;
+    const inverse = { id: null, type: 'setCanvasSelectedLayer' } as const;
+
+    expect(controller.canCommit()).toBe(true);
+    expect(controller.commit('Select layer', forward, inverse)).toBe(true);
+    expect(dispatch).toHaveBeenCalledOnce();
+    expect(history.canUndo()).toBe(true);
+  });
+
+  it.each([
+    { canEdit: false, gestureActive: false, reason: 'editing is disallowed' },
+    { canEdit: true, gestureActive: true, reason: 'a gesture is active' },
+  ])('reports and refuses a structural commit when $reason', ({ canEdit, gestureActive }) => {
+    const dispatch = vi.fn();
+    const history = createHistory();
+    const controller = new StructuralLayerController({
+      canEdit: () => canEdit,
+      dispatch,
+      getDocument: () => null,
+      history,
+      isGestureActive: () => gestureActive,
+    });
+
+    expect(controller.canCommit()).toBe(false);
+    expect(
+      controller.commit(
+        'Select layer',
+        { id: 'layer', type: 'setCanvasSelectedLayer' },
+        { id: null, type: 'setCanvasSelectedLayer' }
+      )
+    ).toBe(false);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(history.canUndo()).toBe(false);
+  });
+
+  it('reports and refuses structural commits after disposal', () => {
+    const dispatch = vi.fn();
+    const history = createHistory();
+    const controller = new StructuralLayerController({
+      canEdit: () => true,
+      dispatch,
+      getDocument: () => null,
+      history,
+      isGestureActive: () => false,
+    });
+
+    controller.dispose();
+
+    expect(controller.canCommit()).toBe(false);
+    expect(
+      controller.commit(
+        'Select layer',
+        { id: 'layer', type: 'setCanvasSelectedLayer' },
+        { id: null, type: 'setCanvasSelectedLayer' }
+      )
+    ).toBe(false);
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+
+  it('owns guarded structural history and coalesces rapid nudges', () => {
+    let now = 0;
+    const dispatch = vi.fn();
+    const history = createHistory();
+    const document = {
+      layers: [
+        {
+          id: 'layer',
+          isEnabled: true,
+          isLocked: false,
+          transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        },
+      ],
+      selectedLayerId: 'layer',
+    } as CanvasDocumentContractV2;
+    const controller = new StructuralLayerController({
+      canEdit: () => true,
+      dispatch,
+      getDocument: () => document,
+      history,
+      isGestureActive: () => false,
+      now: () => now,
+    });
+
+    controller.nudge(1, 0);
+    now = 100;
+    document.layers[0]!.transform.x = 1;
+    controller.nudge(1, 0);
+
+    expect(dispatch).toHaveBeenCalledTimes(2);
+    history.undo();
+    expect(dispatch).toHaveBeenLastCalledWith(expect.objectContaining({ patch: { transform: { x: 0, y: 0 } } }));
+    expect(history.canUndo()).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/structuralLayerController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/structuralLayerController.ts
new file mode 100644
index 00000000000..c4e364b4e4f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/structuralLayerController.ts
@@ -0,0 +1,97 @@
+import type { History } from '@workbench/canvas-engine/history/history';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createDocumentPatchEntry } from '@workbench/canvas-engine/history/documentPatch';
+
+export interface StructuralLayerControllerOptions {
+  readonly history: History;
+  readonly dispatch: (action: CanvasProjectMutation) => void;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly canEdit: () => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly now?: () => number;
+}
+
+interface NudgeBurst {
+  expiresAt: number;
+  layerId: string;
+  origin: { x: number; y: number };
+}
+
+const NUDGE_COALESCE_MS = 500;
+
+/** Owns guarded structural document edits and nudge coalescing. */
+export class StructuralLayerController {
+  private burst: NudgeBurst | null = null;
+  private disposed = false;
+  private readonly now: () => number;
+
+  constructor(private readonly deps: StructuralLayerControllerOptions) {
+    this.now = deps.now ?? Date.now;
+  }
+
+  endBurst(): void {
+    this.burst = null;
+  }
+
+  canCommit(): boolean {
+    return !this.disposed && this.deps.canEdit() && !this.deps.isGestureActive();
+  }
+
+  commit(label: string, forward: CanvasProjectMutation, inverse: CanvasProjectMutation): boolean {
+    if (!this.canCommit()) {
+      return false;
+    }
+    this.endBurst();
+    this.deps.dispatch(forward);
+    this.deps.history.push(createDocumentPatchEntry({ dispatch: this.deps.dispatch, forward, inverse, label }));
+    return true;
+  }
+
+  preview(action: CanvasProjectMutation): boolean {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return false;
+    }
+    this.deps.dispatch(action);
+    return true;
+  }
+
+  nudge(dx: number, dy: number): void {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return;
+    }
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === document.selectedLayerId);
+    if (!document?.selectedLayerId || !layer || layer.isLocked || !layer.isEnabled) {
+      return;
+    }
+    const next = { x: layer.transform.x + dx, y: layer.transform.y + dy };
+    const now = this.now();
+    const coalesce = !!this.burst && this.burst.layerId === layer.id && now < this.burst.expiresAt;
+    const origin = coalesce && this.burst ? this.burst.origin : { x: layer.transform.x, y: layer.transform.y };
+    const forward: CanvasProjectMutation = {
+      id: layer.id,
+      patch: { transform: next },
+      type: 'updateCanvasLayer',
+    };
+    const inverse: CanvasProjectMutation = {
+      id: layer.id,
+      patch: { transform: origin },
+      type: 'updateCanvasLayer',
+    };
+    this.deps.dispatch(forward);
+    const entry = createDocumentPatchEntry({ dispatch: this.deps.dispatch, forward, inverse, label: 'Nudge layer' });
+    if (coalesce) {
+      this.deps.history.amendLast(entry);
+    } else {
+      this.deps.history.push(entry);
+    }
+    this.burst = { expiresAt: now + NUDGE_COALESCE_MS, layerId: layer.id, origin };
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.endBurst();
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/textEditingController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/textEditingController.test.ts
new file mode 100644
index 00000000000..0c2bd9f3679
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/textEditingController.test.ts
@@ -0,0 +1,51 @@
+import type { TextEditSession } from '@workbench/canvas-engine/engineStores';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { DEFAULT_TEXT_OPTIONS } from '@workbench/canvas-engine/engineStores';
+import { describe, expect, it, vi } from 'vitest';
+
+import { TextEditingController } from './textEditingController';
+
+const createHarness = (document: CanvasDocumentContractV2) => {
+  let session: TextEditSession | null = null;
+  const commitStructural = vi.fn();
+  const invalidate = vi.fn();
+  const controller = new TextEditingController({
+    canEdit: () => true,
+    commitStructural,
+    createLayerId: () => 'text-new',
+    getDocument: () => document,
+    invalidate,
+    isGestureActive: () => false,
+    options: { get: () => DEFAULT_TEXT_OPTIONS },
+    session: {
+      get: () => session,
+      set: (value) => (session = value),
+    },
+  });
+  return { commitStructural, controller, getSession: () => session, invalidate };
+};
+
+describe('TextEditingController', () => {
+  it('owns create session state and commits one structural layer addition', () => {
+    const h = createHarness({ bbox: { height: 1, width: 1, x: 0, y: 0 }, height: 1, layers: [], width: 1 } as never);
+    h.controller.openCreate({ x: 10.4, y: 20.6 });
+    expect(h.getSession()?.transform).toMatchObject({ x: 10, y: 21 });
+
+    h.controller.commit('hello');
+    expect(h.getSession()).toBeNull();
+    expect(h.commitStructural).toHaveBeenCalledOnce();
+    expect(h.commitStructural.mock.calls[0]?.[0]).toBe('Add text');
+  });
+
+  it('uses the registered content reader and cancels empty creates', () => {
+    const h = createHarness({ bbox: { height: 1, width: 1, x: 0, y: 0 }, height: 1, layers: [], width: 1 } as never);
+    h.controller.openCreate({ x: 0, y: 0 });
+    h.controller.setContentReader(() => '   ');
+
+    expect(h.controller.commitOpen()).toBe(true);
+    expect(h.getSession()).toBeNull();
+    expect(h.commitStructural).not.toHaveBeenCalled();
+    expect(h.invalidate).toHaveBeenCalledWith({ overlay: true });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/textEditingController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/textEditingController.ts
new file mode 100644
index 00000000000..ee93ab402da
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/textEditingController.ts
@@ -0,0 +1,186 @@
+import type { TextEditSession, TextSource, TextToolOptions } from '@workbench/canvas-engine/engineStores';
+import type { Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+export interface TextEditingControllerOptions {
+  readonly session: {
+    get(): TextEditSession | null;
+    set(value: TextEditSession | null): void;
+  };
+  readonly options: { get(): TextToolOptions };
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly canEdit: () => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly createLayerId: () => string;
+  readonly commitStructural: (label: string, forward: CanvasProjectMutation, inverse: CanvasProjectMutation) => void;
+  readonly invalidate: (payload: { layers?: string[]; overlay?: true }) => void;
+}
+
+const sourcesEqual = (left: TextSource, right: TextSource): boolean =>
+  left.content === right.content &&
+  left.fontFamily === right.fontFamily &&
+  left.fontSize === right.fontSize &&
+  left.fontWeight === right.fontWeight &&
+  left.lineHeight === right.lineHeight &&
+  left.align === right.align &&
+  left.color === right.color;
+
+/** Owns create/edit text session state and its structural commits. */
+export class TextEditingController {
+  private sessionId = 0;
+  private contentReader: (() => string) | null = null;
+  private disposed = false;
+
+  constructor(private readonly deps: TextEditingControllerOptions) {}
+
+  private sourceFromOptions(content: string): TextSource {
+    const options = this.deps.options.get();
+    return {
+      align: options.align,
+      color: options.color,
+      content,
+      fontFamily: options.fontFamily,
+      fontSize: options.fontSize,
+      fontWeight: options.fontWeight,
+      lineHeight: options.lineHeight,
+      type: 'text',
+    };
+  }
+
+  setContentReader(reader: (() => string) | null): void {
+    this.contentReader = reader;
+  }
+
+  openCreate(point: Vec2): void {
+    if (this.disposed || !this.deps.getDocument()) {
+      return;
+    }
+    this.deps.session.set({
+      id: ++this.sessionId,
+      layerId: null,
+      mode: 'create',
+      source: this.sourceFromOptions(''),
+      startSource: null,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: Math.round(point.x), y: Math.round(point.y) },
+    });
+    this.deps.invalidate({ overlay: true });
+  }
+
+  openEdit(layerId: string): void {
+    if (this.disposed) {
+      return;
+    }
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (
+      !document ||
+      !layer ||
+      layer.type !== 'raster' ||
+      layer.source.type !== 'text' ||
+      !layer.isEnabled ||
+      layer.isLocked
+    ) {
+      return;
+    }
+    this.deps.session.set({
+      id: ++this.sessionId,
+      layerId,
+      mode: 'edit',
+      source: { ...layer.source },
+      startSource: { ...layer.source },
+      transform: { ...layer.transform },
+    });
+    this.deps.invalidate({ layers: [layerId] });
+  }
+
+  updateStyle(patch: Partial<TextToolOptions>): void {
+    const session = this.deps.session.get();
+    if (this.disposed || !session) {
+      return;
+    }
+    this.deps.session.set({ ...session, source: { ...session.source, ...patch } });
+  }
+
+  cancel(): void {
+    const session = this.deps.session.get();
+    if (!session) {
+      return;
+    }
+    this.deps.session.set(null);
+    this.deps.invalidate(session.layerId ? { layers: [session.layerId] } : { overlay: true });
+  }
+
+  commit(content: string, styleChanges?: Partial<TextToolOptions>): void {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return;
+    }
+    const session = this.deps.session.get();
+    if (!session) {
+      return;
+    }
+    const finalSource: TextSource = { ...session.source, ...styleChanges, content };
+    if (session.mode === 'create') {
+      if (content.trim() === '') {
+        this.cancel();
+        return;
+      }
+      const layerId = this.deps.createLayerId();
+      const layer: CanvasLayerContract = {
+        blendMode: 'normal',
+        id: layerId,
+        isEnabled: true,
+        isLocked: false,
+        name: `Text ${(this.deps.getDocument()?.layers.length ?? 0) + 1}`,
+        opacity: 1,
+        source: finalSource,
+        transform: session.transform,
+        type: 'raster',
+      };
+      this.deps.session.set(null);
+      this.deps.commitStructural(
+        'Add text',
+        { index: 0, layer, type: 'addCanvasLayer' },
+        { ids: [layerId], type: 'removeCanvasLayers' }
+      );
+      this.deps.invalidate({ overlay: true });
+      return;
+    }
+    const { layerId, startSource } = session;
+    if (!layerId || !startSource) {
+      this.cancel();
+      return;
+    }
+    this.deps.session.set(null);
+    if (sourcesEqual(startSource, finalSource)) {
+      this.deps.invalidate({ layers: [layerId] });
+      return;
+    }
+    this.deps.commitStructural(
+      'Edit text',
+      { id: layerId, source: finalSource, type: 'updateCanvasLayerSource' },
+      { id: layerId, source: startSource, type: 'updateCanvasLayerSource' }
+    );
+  }
+
+  commitOpen(): boolean {
+    if (this.disposed || !this.deps.canEdit()) {
+      return false;
+    }
+    const session = this.deps.session.get();
+    if (!session) {
+      return false;
+    }
+    this.commit(this.contentReader ? this.contentReader() : session.source.content);
+    return true;
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.contentReader = null;
+    this.deps.session.set(null);
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/thumbnailController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/thumbnailController.test.ts
new file mode 100644
index 00000000000..6b064d5ad0c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/thumbnailController.test.ts
@@ -0,0 +1,50 @@
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ThumbnailController } from './thumbnailController';
+
+describe('ThumbnailController budget', () => {
+  it('returns over-budget before rasterizing a missing thumbnail cache', async () => {
+    const layer = {
+      blendMode: 'normal' as const,
+      id: 'layer',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Layer',
+      opacity: 1,
+      source: { image: { height: 100, imageName: 'layer.png', width: 100 }, type: 'image' as const },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster' as const,
+    };
+    const document: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [layer],
+      selectedLayerId: null,
+      version: 2,
+      width: 100,
+    };
+    const rasterize = vi.fn();
+    const controller = new ThumbnailController({
+      backend: createTestStubRasterBackend(),
+      getActiveProjectId: () => 'p',
+      getCheckerboard: vi.fn(),
+      getDocument: () => document,
+      getEntry: () => undefined,
+      getMaskPattern: () => null,
+      isDisposed: () => false,
+      isSupportedSource: () => true,
+      projectId: 'p',
+      rasterize,
+      reportError: vi.fn(),
+      reserve: () => ({ availableBytes: 0, requestedBytes: 80_000, status: 'over-budget' }),
+      setStatus: vi.fn(),
+    });
+
+    await expect(controller.request('layer')).resolves.toBe('over-budget');
+    expect(rasterize).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/thumbnailController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/thumbnailController.ts
new file mode 100644
index 00000000000..6afe026dffe
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/thumbnailController.ts
@@ -0,0 +1,152 @@
+import type { LayerThumbnailRequestResult } from '@workbench/canvas-engine/api';
+import type { LayerCacheEntry } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasLayerSourceContract } from '@workbench/types';
+
+import { getSourceContentRect, renderableSourceOf } from '@workbench/canvas-engine/document/sources';
+import { applyAdjustments, isIdentityAdjustments } from '@workbench/canvas-engine/render/adjustments';
+import { renderControlTransparency } from '@workbench/canvas-engine/render/controlTransparency';
+import { colorizeMask } from '@workbench/canvas-engine/render/maskFill';
+import { fitThumbnailSize } from '@workbench/canvas-engine/render/thumbnail';
+
+export interface ThumbnailControllerOptions {
+  readonly backend: RasterBackend;
+  readonly projectId: string;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getActiveProjectId: () => string | null;
+  readonly getEntry: (layerId: string) => LayerCacheEntry | undefined;
+  readonly getCheckerboard: () => RasterSurface;
+  readonly getMaskPattern: (style: string, color: string) => RasterSurface | null;
+  readonly isDisposed: () => boolean;
+  readonly isSupportedSource: (source: CanvasLayerSourceContract) => boolean;
+  readonly rasterize: (
+    layer: CanvasLayerContract,
+    document: CanvasDocumentContractV2
+  ) => Promise<'published' | 'stale' | 'error'>;
+  readonly setStatus: (layerId: string, status: 'loading' | 'ready' | 'error' | null) => void;
+  readonly reportError: (layerId: string, error: unknown) => void;
+  readonly reserve?: (
+    bytes: number
+  ) =>
+    | { status: 'ok'; lease: { release(): void } }
+    | { status: 'over-budget'; requestedBytes: number; availableBytes: number };
+  readonly pin?: (layerId: string) => { release(): void };
+}
+
+/** Owns bounded thumbnail rendering and lazy rasterization status. */
+export class ThumbnailController {
+  private disposed = false;
+
+  constructor(private readonly deps: ThumbnailControllerOptions) {}
+
+  draw(layerId: string, target: HTMLCanvasElement, maxSize: number): boolean {
+    if (this.disposed) {
+      return false;
+    }
+    const entry = this.deps.getEntry(layerId);
+    const layer = this.deps.getDocument()?.layers.find((candidate) => candidate.id === layerId);
+    if (!entry?.hasPublishedPixels || !layer) {
+      return false;
+    }
+    const { height, width } = fitThumbnailSize(entry.surface.width, entry.surface.height, maxSize);
+    const context = target.getContext('2d');
+    if (width === 0 || height === 0 || !context) {
+      return false;
+    }
+    const reservation = this.deps.reserve?.(width * height * 12);
+    if (reservation?.status === 'over-budget') {
+      return false;
+    }
+    const pinLease = this.deps.pin?.(layerId);
+    try {
+      target.width = width;
+      target.height = height;
+      context.clearRect(0, 0, width, height);
+      const thumbnail = this.deps.backend.createSurface(width, height);
+      thumbnail.ctx.setTransform(1, 0, 0, 1, 0, 0);
+      thumbnail.ctx.clearRect(0, 0, width, height);
+      thumbnail.ctx.globalAlpha = 1;
+      thumbnail.ctx.globalCompositeOperation = 'source-over';
+      thumbnail.ctx.drawImage(entry.surface.canvas, 0, 0, width, height);
+      const checker = context.createPattern(this.deps.getCheckerboard().canvas as CanvasImageSource, 'repeat');
+      if (checker) {
+        context.fillStyle = checker;
+        context.fillRect(0, 0, width, height);
+      }
+      let display = thumbnail;
+      if (layer.type === 'raster' && !isIdentityAdjustments(layer.adjustments)) {
+        const pixels = thumbnail.ctx.getImageData(0, 0, width, height);
+        applyAdjustments(pixels, layer.adjustments);
+        thumbnail.ctx.putImageData(pixels, 0, 0);
+      } else if (layer.type === 'control' && layer.withTransparencyEffect) {
+        display = renderControlTransparency(this.deps.backend, thumbnail, width, height);
+      } else if (layer.type === 'inpaint_mask' || layer.type === 'regional_guidance') {
+        const { fill } = layer.mask;
+        display = colorizeMask(
+          this.deps.backend,
+          thumbnail,
+          width,
+          height,
+          fill,
+          this.deps.getMaskPattern(fill.style, fill.color)
+        );
+      }
+      context.globalAlpha = layer.opacity;
+      context.drawImage(display.canvas as CanvasImageSource, 0, 0);
+      return true;
+    } finally {
+      pinLease?.release();
+      if (reservation?.status === 'ok') {
+        reservation.lease.release();
+      }
+    }
+  }
+
+  async request(layerId: string): Promise<LayerThumbnailRequestResult> {
+    if (this.disposed || this.deps.isDisposed() || this.deps.getActiveProjectId() !== this.deps.projectId) {
+      this.deps.setStatus(layerId, null);
+      return this.disposed || this.deps.isDisposed() ? 'missing' : 'stale';
+    }
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer) {
+      this.deps.setStatus(layerId, null);
+      return 'missing';
+    }
+    const source = renderableSourceOf(layer);
+    if (!source || !this.deps.isSupportedSource(source)) {
+      this.deps.setStatus(layerId, null);
+      return 'unsupported';
+    }
+    const entry = this.deps.getEntry(layerId);
+    if (entry?.hasPublishedPixels && !entry.stale) {
+      this.deps.setStatus(layerId, 'ready');
+      return 'ready';
+    }
+    const rect = getSourceContentRect(layer, document);
+    const reservation = this.deps.reserve?.(rect.width * rect.height * 8);
+    if (reservation?.status === 'over-budget') {
+      this.deps.setStatus(layerId, null);
+      return 'over-budget';
+    }
+    const pinLease = this.deps.pin?.(layerId);
+    this.deps.setStatus(layerId, 'loading');
+    try {
+      const result = await this.deps.rasterize(layer, document);
+      return result === 'published' ? 'ready' : result;
+    } catch (error) {
+      this.deps.setStatus(layerId, 'error');
+      this.deps.reportError(layerId, error);
+      return 'error';
+    } finally {
+      pinLease?.release();
+      if (reservation?.status === 'ok') {
+        reservation.lease.release();
+      }
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/transformEditingController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/transformEditingController.test.ts
new file mode 100644
index 00000000000..ee787c732a3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/transformEditingController.test.ts
@@ -0,0 +1,61 @@
+import type { TransformSession } from '@workbench/canvas-engine/engineStores';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { TransformEditingController } from './transformEditingController';
+
+const document = {
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [
+    {
+      blendMode: 'normal',
+      id: 'shape',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Shape',
+      opacity: 1,
+      source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    },
+  ],
+  width: 100,
+} as CanvasDocumentContractV2;
+
+describe('TransformEditingController', () => {
+  it('owns preview state and commits parametric transforms through declared ports', () => {
+    let session: TransformSession | null = null;
+    const dispatch = vi.fn();
+    const pushHistory = vi.fn();
+    const setOverride = vi.fn();
+    const controller = new TransformEditingController({
+      backend: createTestStubRasterBackend(),
+      canEdit: () => true,
+      dispatch,
+      endBurst: vi.fn(),
+      getCache: () => null,
+      getDocument: () => document,
+      invalidate: vi.fn(),
+      isGestureActive: () => false,
+      pushHistory,
+      replaceCache: vi.fn(),
+      restoreCache: vi.fn(),
+      session: { get: () => session, set: (value) => (session = value) },
+      setOverride,
+    });
+
+    controller.begin('shape');
+    controller.update({ rotation: 0, scaleX: 1, scaleY: 1, x: 12, y: 4 });
+    controller.apply();
+
+    expect(session).toBeNull();
+    expect(dispatch).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'shape', patch: { transform: expect.objectContaining({ x: 12, y: 4 }) } })
+    );
+    expect(pushHistory).toHaveBeenCalledOnce();
+    expect(setOverride).toHaveBeenLastCalledWith('shape', null);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/transformEditingController.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/transformEditingController.ts
new file mode 100644
index 00000000000..03dcecd906a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/controllers/transformEditingController.ts
@@ -0,0 +1,199 @@
+import type { TransformSession } from '@workbench/canvas-engine/engineStores';
+import type { HistoryEntry } from '@workbench/canvas-engine/history/history';
+import type { LayerCacheEntry } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { isRenderableLayer } from '@workbench/canvas-engine/document/sources';
+import { createDocumentPatchEntry } from '@workbench/canvas-engine/history/documentPatch';
+import { isEmpty, roundOut, transformBounds } from '@workbench/canvas-engine/math/rect';
+import { hittableLayerSize } from '@workbench/canvas-engine/tools/moveHitTest';
+import { bakeMatrix } from '@workbench/canvas-engine/transform/transformMath';
+
+export interface TransformEditingControllerOptions {
+  readonly session: { get(): TransformSession | null; set(value: TransformSession | null): void };
+  readonly backend: RasterBackend;
+  readonly getDocument: () => CanvasDocumentContractV2 | null;
+  readonly getCache: (layerId: string) => LayerCacheEntry | null;
+  readonly setOverride: (layerId: string, transform: LayerTransform | null) => void;
+  readonly replaceCache: (layerId: string, rect: Rect, surface: RasterSurface) => void;
+  readonly restoreCache: (layerId: string, rect: Rect, pixels: ImageData) => void;
+  readonly dispatch: (action: CanvasProjectMutation) => void;
+  readonly pushHistory: (entry: HistoryEntry) => void;
+  readonly canEdit: () => boolean;
+  readonly isGestureActive: () => boolean;
+  readonly endBurst: () => void;
+  readonly invalidate: (payload: { layers: string[]; overlay: true }) => void;
+}
+
+const unchanged = (left: LayerTransform, right: LayerTransform): boolean =>
+  left.x === right.x &&
+  left.y === right.y &&
+  left.scaleX === right.scaleX &&
+  left.scaleY === right.scaleY &&
+  left.rotation === right.rotation;
+
+/** Owns transform session state, previews, param commits, and paint bakes. */
+export class TransformEditingController {
+  private disposed = false;
+
+  constructor(private readonly deps: TransformEditingControllerOptions) {}
+
+  private clearOverride(): void {
+    const session = this.deps.session.get();
+    if (session) {
+      this.deps.setOverride(session.layerId, null);
+    }
+  }
+
+  begin(layerId: string): void {
+    if (this.disposed) {
+      return;
+    }
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer || !layer.isEnabled || layer.isLocked || !hittableLayerSize(layer, document)) {
+      return;
+    }
+    this.clearOverride();
+    const start = { ...layer.transform };
+    this.deps.session.set({ layerId, startTransform: start, transform: start });
+    this.deps.setOverride(layerId, start);
+    this.deps.invalidate({ layers: [layerId], overlay: true });
+  }
+
+  update(transform: LayerTransform): void {
+    const session = this.deps.session.get();
+    if (this.disposed || !session) {
+      return;
+    }
+    this.deps.session.set({ ...session, transform });
+    this.deps.setOverride(session.layerId, transform);
+    this.deps.invalidate({ layers: [session.layerId], overlay: true });
+  }
+
+  cancel(): void {
+    const session = this.deps.session.get();
+    if (!session) {
+      return;
+    }
+    this.deps.setOverride(session.layerId, null);
+    this.deps.session.set(null);
+    this.deps.invalidate({ layers: [session.layerId], overlay: true });
+  }
+
+  private bakeEntry(
+    layerId: string,
+    beforeRect: Rect,
+    before: ImageData,
+    afterRect: Rect,
+    after: ImageData,
+    oldTransform: LayerTransform,
+    newTransform: LayerTransform
+  ): HistoryEntry {
+    return {
+      bytes: before.data.byteLength + after.data.byteLength + 256,
+      label: 'Transform layer',
+      redo: () => {
+        this.deps.dispatch({ id: layerId, patch: { transform: newTransform }, type: 'updateCanvasLayer' });
+        this.deps.restoreCache(layerId, afterRect, after);
+      },
+      undo: () => {
+        this.deps.dispatch({ id: layerId, patch: { transform: oldTransform }, type: 'updateCanvasLayer' });
+        this.deps.restoreCache(layerId, beforeRect, before);
+      },
+    };
+  }
+
+  apply(): void {
+    if (this.disposed || !this.deps.canEdit() || this.deps.isGestureActive()) {
+      return;
+    }
+    const session = this.deps.session.get();
+    if (!session) {
+      return;
+    }
+    const document = this.deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === session.layerId);
+    const size = document && layer ? hittableLayerSize(layer, document) : null;
+    if (
+      !document ||
+      !layer ||
+      !size ||
+      !isRenderableLayer(layer) ||
+      layer.isLocked ||
+      unchanged(session.transform, session.startTransform)
+    ) {
+      this.cancel();
+      return;
+    }
+    const source = layer.type === 'raster' || layer.type === 'control' ? layer.source : null;
+    if (
+      source?.type === 'image' ||
+      source?.type === 'shape' ||
+      source?.type === 'gradient' ||
+      source?.type === 'text'
+    ) {
+      this.deps.endBurst();
+      this.deps.setOverride(session.layerId, null);
+      this.deps.session.set(null);
+      const forward: CanvasProjectMutation = {
+        id: session.layerId,
+        patch: { transform: session.transform },
+        type: 'updateCanvasLayer',
+      };
+      const inverse: CanvasProjectMutation = {
+        id: session.layerId,
+        patch: { transform: session.startTransform },
+        type: 'updateCanvasLayer',
+      };
+      this.deps.dispatch(forward);
+      this.deps.pushHistory(
+        createDocumentPatchEntry({ dispatch: this.deps.dispatch, forward, inverse, label: 'Transform layer' })
+      );
+      this.deps.invalidate({ layers: [session.layerId], overlay: true });
+      return;
+    }
+    if (source?.type !== 'paint') {
+      this.cancel();
+      return;
+    }
+    const cache = this.deps.getCache(layer.id);
+    if (!cache || isEmpty(cache.rect)) {
+      this.cancel();
+      return;
+    }
+    this.deps.endBurst();
+    const beforeRect = { ...cache.rect };
+    const before = cache.surface.ctx.getImageData(0, 0, beforeRect.width, beforeRect.height);
+    const matrix = bakeMatrix(session.transform);
+    const afterRect = roundOut(transformBounds(matrix, beforeRect));
+    const baked = this.deps.backend.createSurface(afterRect.width, afterRect.height);
+    const context = baked.ctx;
+    context.setTransform(1, 0, 0, 1, 0, 0);
+    context.clearRect(0, 0, afterRect.width, afterRect.height);
+    context.imageSmoothingEnabled = true;
+    context.setTransform(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e - afterRect.x, matrix.f - afterRect.y);
+    context.drawImage(cache.surface.canvas, beforeRect.x, beforeRect.y);
+    context.setTransform(1, 0, 0, 1, 0, 0);
+    const after = context.getImageData(0, 0, afterRect.width, afterRect.height);
+    const oldTransform = { ...session.startTransform };
+    const identity: LayerTransform = { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+    this.deps.setOverride(layer.id, null);
+    this.deps.session.set(null);
+    this.deps.dispatch({ id: layer.id, patch: { transform: identity }, type: 'updateCanvasLayer' });
+    this.deps.replaceCache(layer.id, afterRect, baked);
+    this.deps.pushHistory(this.bakeEntry(layer.id, beforeRect, before, afterRect, after, oldTransform, identity));
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.cancel();
+    this.disposed = true;
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/diagnostics.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/diagnostics.test.ts
new file mode 100644
index 00000000000..8315b7d553b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/diagnostics.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { createCanvasDiagnostics } from './diagnostics';
+
+describe('createCanvasDiagnostics', () => {
+  it('is a stable no-op when disabled', () => {
+    const diagnostics = createCanvasDiagnostics();
+    const before = diagnostics.snapshot();
+    diagnostics.increment('surfaceCreations');
+    diagnostics.add('allocatedBaseBytes', 400);
+    expect(diagnostics.snapshot()).toBe(before);
+    expect(before.surfaceCreations).toBe(0);
+    expect(before.allocatedBaseBytes).toBe(0);
+  });
+
+  it('records deterministic counters when enabled and resets explicitly', () => {
+    const diagnostics = createCanvasDiagnostics(true);
+    diagnostics.increment('derivedCacheHits');
+    diagnostics.increment('derivedCacheHits');
+    diagnostics.add('allocatedDerivedBytes', 256);
+    expect(diagnostics.snapshot()).toMatchObject({ allocatedDerivedBytes: 256, derivedCacheHits: 2 });
+    diagnostics.reset();
+    expect(diagnostics.snapshot()).toMatchObject({ allocatedDerivedBytes: 0, derivedCacheHits: 0 });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/diagnostics.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/diagnostics.ts
new file mode 100644
index 00000000000..ba70fe76271
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/diagnostics.ts
@@ -0,0 +1,75 @@
+export interface CanvasDiagnosticsSnapshot {
+  readonly surfaceCreations: number;
+  readonly surfaceResizes: number;
+  readonly allocatedBaseBytes: number;
+  readonly allocatedDerivedBytes: number;
+  readonly imageDataReads: number;
+  readonly imageDataWrites: number;
+  readonly derivedCacheHits: number;
+  readonly derivedCacheMisses: number;
+  readonly derivedCacheEvictions: number;
+  readonly layersConsidered: number;
+  readonly layersCulled: number;
+  readonly layersDrawn: number;
+  readonly compositeFrames: number;
+  readonly overlayFrames: number;
+  readonly overBudgetVisibleBaseBytes: number;
+}
+
+export type CanvasDiagnosticsCounter = keyof CanvasDiagnosticsSnapshot;
+type MutableCanvasDiagnosticsSnapshot = { -readonly [K in CanvasDiagnosticsCounter]: number };
+
+export interface CanvasDiagnostics {
+  readonly enabled: boolean;
+  increment(counter: CanvasDiagnosticsCounter): void;
+  add(counter: CanvasDiagnosticsCounter, amount: number): void;
+  snapshot(): Readonly<CanvasDiagnosticsSnapshot>;
+  reset(): void;
+}
+
+const zeroSnapshot = (): MutableCanvasDiagnosticsSnapshot => ({
+  allocatedBaseBytes: 0,
+  allocatedDerivedBytes: 0,
+  compositeFrames: 0,
+  derivedCacheEvictions: 0,
+  derivedCacheHits: 0,
+  derivedCacheMisses: 0,
+  imageDataReads: 0,
+  imageDataWrites: 0,
+  layersConsidered: 0,
+  layersCulled: 0,
+  layersDrawn: 0,
+  overlayFrames: 0,
+  overBudgetVisibleBaseBytes: 0,
+  surfaceCreations: 0,
+  surfaceResizes: 0,
+});
+
+const DISABLED_SNAPSHOT = Object.freeze(zeroSnapshot());
+
+export const createCanvasDiagnostics = (enabled = false): CanvasDiagnostics => {
+  if (!enabled) {
+    return {
+      add: () => undefined,
+      enabled: false,
+      increment: () => undefined,
+      reset: () => undefined,
+      snapshot: () => DISABLED_SNAPSHOT,
+    };
+  }
+
+  let counters = zeroSnapshot();
+  return {
+    add: (counter, amount) => {
+      counters[counter] += amount;
+    },
+    enabled: true,
+    increment: (counter) => {
+      counters[counter] += 1;
+    },
+    reset: () => {
+      counters = zeroSnapshot();
+    },
+    snapshot: () => Object.freeze({ ...counters }),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/bitmapStore.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/bitmapStore.test.ts
new file mode 100644
index 00000000000..786ef5f5320
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/bitmapStore.test.ts
@@ -0,0 +1,1136 @@
+import type { CanvasImageUploadResult } from '@workbench/canvas-engine/document/imageUpload';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasImageRef, CanvasLayerSourceContract } from '@workbench/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createBitmapStore } from './bitmapStore';
+
+const LAYER = 'layer-1';
+
+/** A resolvable deferred, so a test can hold an upload pending on demand. */
+const createDeferred = <T>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason: unknown) => void;
+} => {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, reject, resolve };
+};
+
+/** Drains microtasks until `predicate` is true (or `maxTicks` is exhausted). */
+const drainUntil = async (predicate: () => boolean, maxTicks = 50): Promise<void> => {
+  for (let i = 0; i < maxTicks && !predicate(); i += 1) {
+    await Promise.resolve();
+  }
+};
+
+interface HarnessOptions {
+  encodeSurface?: (surface: RasterSurface) => Promise<Blob>;
+  hashBlob?: (blob: Blob) => Promise<string>;
+  uploadImage?: (blob: Blob) => Promise<CanvasImageUploadResult>;
+  maxUploadAttempts?: number;
+  onError?: (error: unknown, layerId: string) => void;
+  /** The layer-local content-rect origin the surface sits at (default 0,0). */
+  offset?: { x: number; y: number };
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/** The default source: a plain paint layer, matching every pre-existing test's assumption. */
+const PAINT_SOURCE: CanvasLayerSourceContract = { bitmap: null, type: 'paint' };
+
+const createHarness = (options: HarnessOptions = {}) => {
+  const surface: RasterSurface = createTestStubRasterBackend().createSurface(10, 10);
+  let encoded = 'pixels-A';
+  let uploadSeq = 0;
+  let source: CanvasLayerSourceContract | null = PAINT_SOURCE;
+
+  let offset = options.offset ?? { x: 0, y: 0 };
+
+  const encodeSurface = vi.fn(
+    options.encodeSurface ?? (() => Promise.resolve(new Blob([encoded], { type: 'image/png' })))
+  );
+  const uploadImage =
+    options.uploadImage ??
+    vi.fn(
+      (_blob: Blob): Promise<CanvasImageUploadResult> =>
+        Promise.resolve({ height: 10, imageName: `img-${uploadSeq++}`, width: 10 })
+    );
+  const dispatch = vi.fn((_action: CanvasProjectMutation) => true);
+
+  const store = createBitmapStore({
+    debounceMs: 1500,
+    dispatch,
+    encodeSurface,
+    getLayerSource: () => source,
+    getLayerSurface: () => ({ offset, surface }),
+    // Deterministic content hash: the encoded blob's own text.
+    hashBlob: options.hashBlob ?? ((blob) => blob.text()),
+    maxUploadAttempts: options.maxUploadAttempts ?? 3,
+    onError: options.onError,
+    retryDelaysMs: [1],
+    // Immediate backoff so retries don't depend on timer advancement.
+    sleep: options.sleep ?? (() => Promise.resolve()),
+    uploadImage,
+  });
+
+  return {
+    dispatch,
+    encodeSurface,
+    setEncoded: (value: string) => {
+      encoded = value;
+    },
+    setOffset: (value: { x: number; y: number }) => {
+      offset = value;
+    },
+    setSource: (value: CanvasLayerSourceContract | null) => {
+      source = value;
+    },
+    store,
+    uploadImage: uploadImage as ReturnType<typeof vi.fn>,
+  };
+};
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('createBitmapStore', () => {
+  it('debounces a burst of strokes into a single flush', async () => {
+    const h = createHarness();
+
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(500);
+    h.store.markLayerDirty(LAYER); // resets the timer
+    await vi.advanceTimersByTimeAsync(500);
+    h.store.markLayerDirty(LAYER); // resets again
+    await vi.advanceTimersByTimeAsync(1000); // 1000 < 1500 since the last stroke
+
+    expect(h.uploadImage).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    expect(h.uploadImage).toHaveBeenCalledTimes(1);
+    expect(h.dispatch).toHaveBeenCalledTimes(1);
+    h.store.dispose();
+  });
+
+  it('dedupes identical pixels: the second flush reuses the image and skips the upload', async () => {
+    const h = createHarness();
+
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+    expect(h.uploadImage).toHaveBeenCalledTimes(1);
+    expect(h.dispatch).toHaveBeenCalledTimes(1);
+
+    // Same encoded pixels → same hash → dedupe hit, no second upload.
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    expect(h.uploadImage).toHaveBeenCalledTimes(1);
+    h.store.dispose();
+  });
+
+  it('dispatches a same-hash re-flush when the offset changed (pure-translation persistence)', async () => {
+    const h = createHarness({ offset: { x: 0, y: 0 } });
+
+    // First flush: paint pixels at the origin → uploads img-0, document now
+    // points at { imageName: 'img-0', offset: { x: 0, y: 0 } }.
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+    expect(h.uploadImage).toHaveBeenCalledTimes(1);
+    expect(h.dispatch).toHaveBeenCalledTimes(1);
+    h.setSource({ bitmap: { height: 10, imageName: 'img-0', width: 10 }, offset: { x: 0, y: 0 }, type: 'paint' });
+
+    // Transform-drag by +50px then Apply: the bake produces byte-identical
+    // pixels (same hash → dedupe hit, no upload) but the content sits at a new
+    // offset. The dispatch that persists the moved offset must still fire.
+    h.setOffset({ x: 50, y: 0 });
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    // No new upload (pixels deduped), but a fresh dispatch carrying the offset.
+    expect(h.uploadImage).toHaveBeenCalledTimes(1);
+    expect(h.dispatch).toHaveBeenCalledTimes(2);
+    expect(h.dispatch.mock.calls.at(-1)?.[0]).toMatchObject({
+      source: { bitmap: { imageName: 'img-0' }, offset: { x: 50, y: 0 }, type: 'paint' },
+      type: 'updateCanvasLayerSource',
+    });
+    h.store.dispose();
+  });
+
+  it('dispatches the content-rect offset alongside the bitmap ref (paint persistence round-trip)', async () => {
+    const h = createHarness({ offset: { x: 40, y: 25 } });
+
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    const dispatched = h.dispatch.mock.calls.at(-1)?.[0];
+    expect(dispatched).toMatchObject({
+      source: { bitmap: { imageName: 'img-0' }, offset: { x: 40, y: 25 }, type: 'paint' },
+      type: 'updateCanvasLayerSource',
+    });
+    // The encoded blob covers only the content-sized surface (10×10 stub), so a
+    // reload rasterizes those pixels at the persisted offset.
+    expect(h.encodeSurface).toHaveBeenCalledWith(expect.objectContaining({ height: 10, width: 10 }));
+    h.store.dispose();
+  });
+
+  it('routes the swap through dispatchBitmap when provided (mask persistence seam), not the default dispatch', async () => {
+    const surface = createTestStubRasterBackend().createSurface(10, 10);
+    const dispatch = vi.fn((_action: CanvasProjectMutation) => true);
+    const dispatchBitmap = vi.fn(
+      (_layerId: string, _bitmap: CanvasImageRef, _offset: { x: number; y: number }) => true
+    );
+    const store = createBitmapStore({
+      debounceMs: 1500,
+      dispatch,
+      dispatchBitmap,
+      encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+      getLayerSource: () => ({ bitmap: null, type: 'paint' }),
+      getLayerSurface: () => ({ offset: { x: 7, y: 8 }, surface }),
+      hashBlob: (blob) => blob.text(),
+      retryDelaysMs: [1],
+      sleep: () => Promise.resolve(),
+      uploadImage: () => Promise.resolve({ height: 10, imageName: 'mask-img', width: 10 }),
+    });
+
+    store.markLayerDirty('mask1');
+    await vi.advanceTimersByTimeAsync(1500);
+    await store.flushPendingUploads();
+
+    // The engine-provided seam receives the ref + offset; the default paint-source
+    // dispatch is NOT used (the engine picks updateCanvasLayerConfig for masks).
+    expect(dispatchBitmap).toHaveBeenCalledTimes(1);
+    expect(dispatchBitmap).toHaveBeenCalledWith('mask1', expect.objectContaining({ imageName: 'mask-img' }), {
+      x: 7,
+      y: 8,
+    });
+    expect(dispatch).not.toHaveBeenCalled();
+    store.dispose();
+  });
+
+  it('retains dirty pixels when the intended layer rejects the persisted bitmap', async () => {
+    const surface = createTestStubRasterBackend().createSurface(10, 10);
+    const dispatchBitmap = vi.fn(() => false);
+    const store = createBitmapStore({
+      debounceMs: 1500,
+      dispatch: vi.fn(),
+      dispatchBitmap,
+      encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+      getLayerSource: () => ({ bitmap: null, type: 'paint' }),
+      getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface }),
+      hashBlob: (blob) => blob.text(),
+      uploadImage: () => Promise.resolve({ height: 10, imageName: 'rejected-img', width: 10 }),
+    });
+
+    store.markLayerDirty(LAYER);
+    await expect(store.flushPendingUploads()).rejects.toThrow('Canvas pixel persistence failed');
+    await expect(store.flushPendingUploads()).rejects.toThrow('Canvas pixel persistence failed');
+
+    expect(dispatchBitmap).toHaveBeenCalledTimes(2);
+    store.dispose();
+  });
+
+  it('retains dirty pixels when a legacy dispatcher returns no acceptance signal', async () => {
+    const surface = createTestStubRasterBackend().createSurface(10, 10);
+    const dispatchBitmap = vi.fn(() => undefined) as unknown as (
+      layerId: string,
+      bitmap: CanvasImageRef,
+      offset: { x: number; y: number }
+    ) => boolean;
+    const store = createBitmapStore({
+      debounceMs: 1500,
+      dispatch: vi.fn(() => true),
+      dispatchBitmap,
+      encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+      getLayerSource: () => ({ bitmap: null, type: 'paint' }),
+      getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface }),
+      hashBlob: (blob) => blob.text(),
+      uploadImage: () => Promise.resolve({ height: 10, imageName: 'missing-acceptance-img', width: 10 }),
+    });
+
+    store.markLayerDirty(LAYER);
+    await expect(store.flushPendingUploads()).rejects.toThrow('Canvas pixel persistence failed');
+    await expect(store.flushPendingUploads()).rejects.toThrow('Canvas pixel persistence failed');
+
+    expect(dispatchBitmap).toHaveBeenCalledTimes(2);
+    store.dispose();
+  });
+
+  it.each(['dispatch', 'dispatchBitmap'] as const)(
+    'retains dirty pixels when %s throws before the intended bitmap lands',
+    async (dispatchSeam) => {
+      const surface = createTestStubRasterBackend().createSurface(10, 10);
+      let shouldThrow = true;
+      const throwingDispatch = vi.fn(() => {
+        if (shouldThrow) {
+          throw new Error('subscriber failed before commit');
+        }
+        return true;
+      });
+      const onError = vi.fn();
+      const store = createBitmapStore({
+        debounceMs: 1500,
+        dispatch: dispatchSeam === 'dispatch' ? throwingDispatch : vi.fn(() => true),
+        dispatchBitmap: dispatchSeam === 'dispatchBitmap' ? throwingDispatch : undefined,
+        encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+        getLayerSource: () => ({ bitmap: null, type: 'paint' }),
+        getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface }),
+        hashBlob: (blob) => blob.text(),
+        onError,
+        uploadImage: () => Promise.resolve({ height: 10, imageName: 'retry-after-throw.png', width: 10 }),
+      });
+
+      store.markLayerDirty(LAYER);
+      await expect(store.flushPendingUploads()).rejects.toThrow('Canvas pixel persistence failed');
+
+      expect(throwingDispatch).toHaveBeenCalledOnce();
+      expect(onError).toHaveBeenCalledOnce();
+      expect(
+        store.isSelfEcho(LAYER, {
+          bitmap: { height: 10, imageName: 'retry-after-throw.png', width: 10 },
+          type: 'paint',
+        })
+      ).toBe(false);
+
+      shouldThrow = false;
+      await store.flushPendingUploads();
+
+      expect(throwingDispatch).toHaveBeenCalledTimes(2);
+      store.dispose();
+    }
+  );
+
+  it('accepts a thrown dispatch when authoritative state proves the intended bitmap landed', async () => {
+    const surface = createTestStubRasterBackend().createSurface(10, 10);
+    let source: CanvasLayerSourceContract | null = { bitmap: null, type: 'paint' };
+    const dispatchBitmap = vi.fn((_layerId: string, bitmap: CanvasImageRef, offset: { x: number; y: number }) => {
+      source = { bitmap, offset, type: 'paint' };
+      throw new Error('subscriber failed after commit');
+    });
+    const onError = vi.fn();
+    const store = createBitmapStore({
+      debounceMs: 1500,
+      dispatch: vi.fn(() => true),
+      dispatchBitmap,
+      encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+      getLayerSource: () => source,
+      getLayerSurface: () => ({ offset: { x: 7, y: 8 }, surface }),
+      hashBlob: (blob) => blob.text(),
+      onError,
+      uploadImage: () => Promise.resolve({ height: 10, imageName: 'landed-before-throw.png', width: 10 }),
+    });
+
+    store.markLayerDirty(LAYER);
+    await expect(store.flushPendingUploads()).resolves.toBeUndefined();
+    await expect(store.flushPendingUploads()).resolves.toBeUndefined();
+
+    expect(dispatchBitmap).toHaveBeenCalledOnce();
+    expect(onError).not.toHaveBeenCalled();
+    expect(store.isSelfEcho(LAYER, source)).toBe(true);
+    store.dispose();
+  });
+
+  it('drops dirty pixels when rejection confirms that the intended layer was deleted', async () => {
+    const surface = createTestStubRasterBackend().createSurface(10, 10);
+    let source: CanvasLayerSourceContract | null = { bitmap: null, type: 'paint' };
+    const dispatchBitmap = vi.fn(() => {
+      source = null;
+      return false;
+    });
+    const store = createBitmapStore({
+      debounceMs: 1500,
+      dispatch: vi.fn(),
+      dispatchBitmap,
+      encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+      getLayerSource: () => source,
+      getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface }),
+      hashBlob: (blob) => blob.text(),
+      uploadImage: () => Promise.resolve({ height: 10, imageName: 'orphan-img', width: 10 }),
+    });
+
+    store.markLayerDirty(LAYER);
+    await store.flushPendingUploads();
+    await store.flushPendingUploads();
+
+    expect(dispatchBitmap).toHaveBeenCalledTimes(1);
+    store.dispose();
+  });
+
+  it('uploads a new image when the pixels change', async () => {
+    const h = createHarness();
+
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    h.setEncoded('pixels-B');
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    expect(h.uploadImage).toHaveBeenCalledTimes(2);
+    expect(h.dispatch).toHaveBeenCalledTimes(2);
+    h.store.dispose();
+  });
+
+  it('undo re-flush reuses the prior image and does not re-upload (history convergence)', async () => {
+    const h = createHarness();
+
+    // Paint state A → upload img-0.
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+    // Paint state B → upload img-1.
+    h.setEncoded('pixels-B');
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+    expect(h.uploadImage).toHaveBeenCalledTimes(2);
+
+    // Undo restores state A's pixels in the cache; the engine re-marks the layer
+    // dirty. The re-flush re-hashes to img-0's content and reuses it — NO upload.
+    h.setEncoded('pixels-A');
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    expect(h.uploadImage).toHaveBeenCalledTimes(2);
+    // The contract converges back to img-0 (the previously uploaded state-A image).
+    const lastDispatch = h.dispatch.mock.calls.at(-1)?.[0];
+    expect(lastDispatch).toMatchObject({
+      source: { bitmap: { imageName: 'img-0' }, type: 'paint' },
+      type: 'updateCanvasLayerSource',
+    });
+    h.store.dispose();
+  });
+
+  it('swaps on success: dispatch fires only after the upload resolves', async () => {
+    const deferred = createDeferred<CanvasImageUploadResult>();
+    const uploadImage = vi.fn(() => deferred.promise);
+    const h = createHarness({ uploadImage });
+
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+
+    // Upload is in flight; the contract keeps its old ref (no dispatch yet).
+    expect(uploadImage).toHaveBeenCalledTimes(1);
+    expect(h.dispatch).not.toHaveBeenCalled();
+
+    deferred.resolve({ height: 10, imageName: 'img-x', width: 10 });
+    await h.store.flushPendingUploads();
+
+    expect(h.dispatch).toHaveBeenCalledTimes(1);
+    expect(h.dispatch.mock.calls[0][0]).toMatchObject({
+      id: LAYER,
+      source: { bitmap: { imageName: 'img-x' }, type: 'paint' },
+      type: 'updateCanvasLayerSource',
+    });
+    h.store.dispose();
+  });
+
+  it('on upload failure: no dispatch, layer stays dirty, then recovers on a later success', async () => {
+    let shouldFail = true;
+    const uploadImage = vi.fn(() => {
+      if (shouldFail) {
+        return Promise.reject(new Error('upload failed'));
+      }
+      return Promise.resolve<CanvasImageUploadResult>({ height: 10, imageName: 'img-ok', width: 10 });
+    });
+    const onError = vi.fn();
+    const surface = createTestStubRasterBackend().createSurface(10, 10);
+    const dispatch = vi.fn((_action: CanvasProjectMutation) => true);
+    const store = createBitmapStore({
+      debounceMs: 1500,
+      dispatch,
+      encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+      getLayerSource: () => PAINT_SOURCE,
+      getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface }),
+      hashBlob: (blob) => blob.text(),
+      maxUploadAttempts: 2,
+      onError,
+      retryDelaysMs: [1],
+      sleep: () => Promise.resolve(),
+      uploadImage,
+    });
+
+    store.markLayerDirty(LAYER);
+    await expect(store.flushPendingUploads()).rejects.toThrow('Canvas pixel persistence failed');
+
+    // Retried up to the attempt cap, then gave up without dispatching.
+    expect(uploadImage).toHaveBeenCalledTimes(2);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledTimes(1);
+
+    // The layer is still dirty; a subsequent flush succeeds and dispatches.
+    shouldFail = false;
+    store.markLayerDirty(LAYER);
+    await store.flushPendingUploads();
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch.mock.calls[0][0]).toMatchObject({ source: { bitmap: { imageName: 'img-ok' } } });
+    store.dispose();
+  });
+
+  it('flushPendingUploads is a barrier: it cancels the debounce and resolves only after uploads settle', async () => {
+    const deferred = createDeferred<CanvasImageUploadResult>();
+    const uploadImage = vi.fn(() => deferred.promise);
+    const h = createHarness({ uploadImage });
+
+    h.store.markLayerDirty(LAYER);
+    // Do NOT advance to the debounce window; the barrier must flush immediately.
+    const barrier = h.store.flushPendingUploads();
+
+    let settled = false;
+    void barrier.then(() => {
+      settled = true;
+    });
+
+    // Encode/hash have run and the upload is in flight, but it hasn't resolved.
+    // Drain the encode→hash microtask chain (several awaits) without resolving.
+    for (let i = 0; i < 5; i += 1) {
+      await Promise.resolve();
+    }
+    expect(uploadImage).toHaveBeenCalledTimes(1);
+    expect(settled).toBe(false);
+
+    deferred.resolve({ height: 10, imageName: 'img-b', width: 10 });
+    await barrier;
+
+    expect(settled).toBe(true);
+    expect(h.dispatch).toHaveBeenCalledTimes(1);
+    h.store.dispose();
+  });
+
+  it('suspends debounced dirty work and resumes it only after release', async () => {
+    const h = createHarness();
+    h.store.markLayerDirty(LAYER);
+    const release = h.store.suspendLayer(LAYER);
+
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(h.uploadImage).not.toHaveBeenCalled();
+    expect(h.dispatch).not.toHaveBeenCalled();
+
+    release();
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    expect(h.uploadImage).toHaveBeenCalledOnce();
+    expect(h.dispatch).toHaveBeenCalledOnce();
+    h.store.dispose();
+  });
+
+  it('records dirty work marked during suspension without scheduling until release', async () => {
+    const h = createHarness();
+    const release = h.store.suspendLayer(LAYER);
+    h.store.markLayerDirty(LAYER);
+
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(h.encodeSurface).not.toHaveBeenCalled();
+
+    release();
+    await h.store.flushPendingUploads();
+
+    expect(h.encodeSurface).toHaveBeenCalledOnce();
+    expect(h.dispatch).toHaveBeenCalledOnce();
+    h.store.dispose();
+  });
+
+  it('invalidates an in-flight result and keeps a barrier pending until suspension releases', async () => {
+    const uploads = [createDeferred<CanvasImageUploadResult>(), createDeferred<CanvasImageUploadResult>()];
+    let uploadIndex = 0;
+    const uploadImage = vi.fn(() => uploads[uploadIndex++]!.promise);
+    const h = createHarness({ uploadImage });
+    h.store.markLayerDirty(LAYER);
+    const barrier = h.store.flushPendingUploads();
+    await drainUntil(() => uploadImage.mock.calls.length === 1);
+
+    const release = h.store.suspendLayer(LAYER);
+    let settled = false;
+    void barrier.then(() => {
+      settled = true;
+    });
+    uploads[0]!.resolve({ height: 10, imageName: 'obsolete', width: 10 });
+    await drainUntil(() => settled);
+
+    expect(settled).toBe(false);
+    expect(h.dispatch).not.toHaveBeenCalled();
+    expect(uploadImage).toHaveBeenCalledOnce();
+
+    release();
+    await drainUntil(() => uploadImage.mock.calls.length === 2);
+    uploads[1]!.resolve({ height: 10, imageName: 'fresh', width: 10 });
+    await barrier;
+
+    expect(h.dispatch).toHaveBeenCalledOnce();
+    expect(h.dispatch.mock.calls[0]![0]).toMatchObject({ source: { bitmap: { imageName: 'fresh' } } });
+    h.store.dispose();
+  });
+
+  it('supports nested suspension leases and idempotent release', async () => {
+    const h = createHarness();
+    h.store.markLayerDirty(LAYER);
+    const releaseOuter = h.store.suspendLayer(LAYER);
+    const releaseInner = h.store.suspendLayer(LAYER);
+
+    releaseOuter();
+    releaseOuter();
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(h.uploadImage).not.toHaveBeenCalled();
+
+    releaseInner();
+    await h.store.flushPendingUploads();
+    expect(h.uploadImage).toHaveBeenCalledOnce();
+    h.store.dispose();
+  });
+
+  it('ignores a stale suspension release after reset reuses the same layer id', async () => {
+    const h = createHarness();
+    const releaseOldDocument = h.store.suspendLayer(LAYER);
+
+    h.store.reset();
+
+    const releaseNewDocument = h.store.suspendLayer(LAYER);
+    h.store.markLayerDirty(LAYER);
+    const barrier = h.store.flushPendingUploads();
+    let settled = false;
+    void barrier.then(() => {
+      settled = true;
+    });
+
+    releaseOldDocument();
+    await vi.advanceTimersByTimeAsync(3000);
+    await Promise.resolve();
+
+    expect(settled).toBe(false);
+    expect(h.encodeSurface).not.toHaveBeenCalled();
+
+    releaseNewDocument();
+    await barrier;
+
+    expect(h.encodeSurface).toHaveBeenCalledOnce();
+    expect(h.dispatch).toHaveBeenCalledOnce();
+    h.store.dispose();
+  });
+
+  it.each(['reset', 'dispose'] as const)('%s settles barriers waiting on suspended dirty work', async (ending) => {
+    const h = createHarness();
+    h.store.markLayerDirty(LAYER);
+    h.store.suspendLayer(LAYER);
+    const barrier = h.store.flushPendingUploads();
+    let settled = false;
+    void barrier.then(() => {
+      settled = true;
+    });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+
+    h.store[ending]();
+    await barrier;
+
+    expect(settled).toBe(true);
+    expect(h.dispatch).not.toHaveBeenCalled();
+    if (ending === 'reset') {
+      h.store.dispose();
+    }
+  });
+
+  it('a stroke landing while the barrier awaits an in-flight upload is not dropped: the barrier waits for the follow-up flush', async () => {
+    const deferreds = [createDeferred<CanvasImageUploadResult>(), createDeferred<CanvasImageUploadResult>()];
+    let call = 0;
+    const uploadImage = vi.fn(() => deferreds[call++].promise);
+    const h = createHarness({ uploadImage });
+
+    h.store.markLayerDirty(LAYER);
+    const barrier = h.store.flushPendingUploads();
+    let settled = false;
+    void barrier.then(() => {
+      settled = true;
+    });
+
+    // Drain the encode→hash microtask chain: the first (stale) upload is in flight.
+    await drainUntil(() => uploadImage.mock.calls.length >= 1);
+    expect(uploadImage).toHaveBeenCalledTimes(1);
+    expect(settled).toBe(false);
+
+    // A fresh stroke lands mid-flight: new pixels re-dirty the layer while the
+    // stale upload is still pending.
+    h.setEncoded('pixels-B');
+    h.store.markLayerDirty(LAYER);
+
+    // The stale upload resolves. The barrier must NOT settle yet: the layer
+    // was re-dirtied by a newer stroke during the await, so it owes a follow-up
+    // flush of the newer pixels before the "latest painted pixels" guarantee holds.
+    deferreds[0].resolve({ height: 10, imageName: 'img-old', width: 10 });
+    await drainUntil(() => uploadImage.mock.calls.length >= 2);
+    expect(uploadImage).toHaveBeenCalledTimes(2);
+    expect(settled).toBe(false);
+
+    deferreds[1].resolve({ height: 10, imageName: 'img-new', width: 10 });
+    await barrier;
+
+    expect(settled).toBe(true);
+    expect(h.dispatch).toHaveBeenCalledTimes(2);
+    expect(h.dispatch.mock.calls[1][0]).toMatchObject({
+      id: LAYER,
+      source: { bitmap: { imageName: 'img-new' }, type: 'paint' },
+      type: 'updateCanvasLayerSource',
+    });
+    h.store.dispose();
+  });
+
+  it('a persistently failing layer does not spin the barrier: it rejects after one bounded attempt and stays dirty', async () => {
+    const uploadImage = vi.fn(() => Promise.reject(new Error('upload failed')));
+    const onError = vi.fn();
+    const surface = createTestStubRasterBackend().createSurface(10, 10);
+    const dispatch = vi.fn((_action: CanvasProjectMutation) => true);
+    const store = createBitmapStore({
+      debounceMs: 1500,
+      dispatch,
+      encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+      getLayerSource: () => PAINT_SOURCE,
+      getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface }),
+      hashBlob: (blob) => blob.text(),
+      maxUploadAttempts: 2,
+      onError,
+      retryDelaysMs: [1],
+      sleep: () => Promise.resolve(),
+      uploadImage,
+    });
+
+    store.markLayerDirty(LAYER);
+    await expect(store.flushPendingUploads()).rejects.toThrow('Canvas pixel persistence failed');
+
+    // The internal retry cap (maxUploadAttempts) bounds a single flush's own
+    // attempts. The barrier must not loop back and re-attempt a layer whose
+    // flush already FAILED this call, so the total stays at that cap instead
+    // of growing with extra barrier iterations (no spin).
+    expect(uploadImage).toHaveBeenCalledTimes(2);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledTimes(1);
+
+    // The layer is still dirty (deferred, not dropped): a later debounce retries it.
+    await vi.advanceTimersByTimeAsync(1500);
+    expect(uploadImage.mock.calls.length).toBeGreaterThan(2);
+
+    store.dispose();
+  });
+
+  it('isSelfEcho recognizes the exact ref it just applied and rejects a different one', async () => {
+    const h = createHarness();
+
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+
+    const applied = h.dispatch.mock.calls[0][0] as Extract<CanvasProjectMutation, { type: 'updateCanvasLayerSource' }>;
+    const appliedSource = applied.source;
+
+    // The dispatch's own round-trip is a self-echo → the engine skips re-raster.
+    expect(h.store.isSelfEcho(LAYER, appliedSource)).toBe(true);
+
+    // A different bitmap (undo/import) is NOT an echo → must re-rasterize.
+    const otherPaint: CanvasLayerSourceContract = {
+      bitmap: { height: 10, imageName: 'other', width: 10 },
+      type: 'paint',
+    };
+    expect(h.store.isSelfEcho(LAYER, otherPaint)).toBe(false);
+
+    // A different layer, and non-paint / null sources, are never echoes.
+    expect(h.store.isSelfEcho('layer-2', appliedSource)).toBe(false);
+    expect(h.store.isSelfEcho(LAYER, { image: { height: 1, imageName: 'i', width: 1 }, type: 'image' })).toBe(false);
+    expect(h.store.isSelfEcho(LAYER, null)).toBe(false);
+    h.store.dispose();
+  });
+
+  it('reset() clears the self-echo guard so a reused layer id is not suppressed', async () => {
+    const h = createHarness();
+
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+    expect(h.dispatch).toHaveBeenCalledTimes(1);
+    expect(h.uploadImage).toHaveBeenCalledTimes(1);
+
+    const applied = h.dispatch.mock.calls[0][0] as Extract<CanvasProjectMutation, { type: 'updateCanvasLayerSource' }>;
+    expect(h.store.isSelfEcho(LAYER, applied.source)).toBe(true);
+
+    // A wholesale document replacement drops the outgoing document's self-echo
+    // bookkeeping (a reused layer id must not inherit it).
+    h.store.reset();
+    expect(h.store.isSelfEcho(LAYER, applied.source)).toBe(false);
+
+    // Re-persisting identical pixels now dispatches again: the content-hash
+    // dedupe reuses the already-uploaded image (no new upload), but the stale
+    // self-echo no longer suppresses the dispatch, so the contract converges.
+    h.store.markLayerDirty(LAYER);
+    await vi.advanceTimersByTimeAsync(1500);
+    await h.store.flushPendingUploads();
+    expect(h.dispatch).toHaveBeenCalledTimes(2);
+    expect(h.uploadImage).toHaveBeenCalledTimes(1);
+
+    h.store.dispose();
+  });
+
+  it('reset() cancels a pending debounced flush for the outgoing document', async () => {
+    const h = createHarness();
+
+    h.store.markLayerDirty(LAYER);
+    h.store.reset();
+    await vi.advanceTimersByTimeAsync(3000);
+
+    expect(h.uploadImage).not.toHaveBeenCalled();
+    expect(h.dispatch).not.toHaveBeenCalled();
+
+    h.store.dispose();
+  });
+
+  it('discardLayer cancels pending and in-flight persistence for one cleared layer', async () => {
+    const deferred = createDeferred<CanvasImageUploadResult>();
+    const uploadImage = vi.fn(() => deferred.promise);
+    const h = createHarness({ uploadImage });
+
+    h.store.markLayerDirty(LAYER);
+    const barrier = h.store.flushPendingUploads();
+    await drainUntil(() => uploadImage.mock.calls.length >= 1);
+
+    h.store.discardLayer(LAYER);
+    deferred.resolve({ height: 10, imageName: 'stale-mask', width: 10 });
+    await barrier;
+    await vi.advanceTimersByTimeAsync(3000);
+
+    expect(h.dispatch).not.toHaveBeenCalled();
+    h.store.dispose();
+  });
+
+  it.each(['discard', 'reset'] as const)(
+    'does not resurrect dirty persistence when an in-flight upload rejects after %s',
+    async (cancellation) => {
+      const deferred = createDeferred<CanvasImageUploadResult>();
+      const uploadImage = vi.fn(() => deferred.promise);
+      const onError = vi.fn();
+      const h = createHarness({ maxUploadAttempts: 1, onError, uploadImage });
+      h.store.markLayerDirty(LAYER);
+      const barrier = h.store.flushPendingUploads();
+      await drainUntil(() => uploadImage.mock.calls.length >= 1);
+
+      if (cancellation === 'discard') {
+        h.store.discardLayer(LAYER);
+      } else {
+        h.store.reset();
+      }
+      deferred.reject(new Error('obsolete upload failed'));
+      await barrier;
+      await vi.advanceTimersByTimeAsync(3000);
+
+      expect(uploadImage).toHaveBeenCalledOnce();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      expect(onError).not.toHaveBeenCalled();
+      await h.store.flushPendingUploads();
+      expect(uploadImage).toHaveBeenCalledOnce();
+      h.store.dispose();
+    }
+  );
+
+  it.each(['discard', 'reset'] as const)(
+    'does not resurrect dirty persistence when in-flight encoding rejects after %s',
+    async (cancellation) => {
+      const deferred = createDeferred<Blob>();
+      const encodeSurface = vi.fn(() => deferred.promise);
+      const onError = vi.fn();
+      const h = createHarness({ encodeSurface, onError });
+      h.store.markLayerDirty(LAYER);
+      const barrier = h.store.flushPendingUploads();
+      await drainUntil(() => encodeSurface.mock.calls.length >= 1);
+
+      if (cancellation === 'discard') {
+        h.store.discardLayer(LAYER);
+      } else {
+        h.store.reset();
+      }
+      deferred.reject(new Error('obsolete encode failed'));
+      await barrier;
+      await vi.advanceTimersByTimeAsync(3000);
+
+      expect(encodeSurface).toHaveBeenCalledOnce();
+      expect(h.uploadImage).not.toHaveBeenCalled();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      expect(onError).not.toHaveBeenCalled();
+      await h.store.flushPendingUploads();
+      expect(encodeSurface).toHaveBeenCalledOnce();
+      h.store.dispose();
+    }
+  );
+
+  it.each(['discard', 'reset'] as const)(
+    'does not hash or upload when in-flight encoding fulfills after %s',
+    async (cancellation) => {
+      const deferred = createDeferred<Blob>();
+      const encodeSurface = vi.fn(() => deferred.promise);
+      const hashBlob = vi.fn((blob: Blob) => blob.text());
+      const h = createHarness({ encodeSurface, hashBlob });
+      h.store.markLayerDirty(LAYER);
+      const barrier = h.store.flushPendingUploads();
+      await drainUntil(() => encodeSurface.mock.calls.length >= 1);
+
+      if (cancellation === 'discard') {
+        h.store.discardLayer(LAYER);
+      } else {
+        h.store.reset();
+      }
+      deferred.resolve(new Blob(['obsolete pixels'], { type: 'image/png' }));
+      await barrier;
+
+      expect(hashBlob).not.toHaveBeenCalled();
+      expect(h.uploadImage).not.toHaveBeenCalled();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      h.store.dispose();
+    }
+  );
+
+  it.each(['discard', 'reset'] as const)(
+    'does not upload when in-flight hashing fulfills after %s',
+    async (cancellation) => {
+      const deferred = createDeferred<string>();
+      const hashBlob = vi.fn(() => deferred.promise);
+      const h = createHarness({ hashBlob });
+      h.store.markLayerDirty(LAYER);
+      const barrier = h.store.flushPendingUploads();
+      await drainUntil(() => hashBlob.mock.calls.length >= 1);
+
+      if (cancellation === 'discard') {
+        h.store.discardLayer(LAYER);
+      } else {
+        h.store.reset();
+      }
+      deferred.resolve('obsolete-hash');
+      await barrier;
+
+      expect(h.uploadImage).not.toHaveBeenCalled();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      h.store.dispose();
+    }
+  );
+
+  it.each(['discard', 'reset'] as const)(
+    'stops obsolete upload retries when %s lands during retry backoff',
+    async (cancellation) => {
+      const backoff = createDeferred<void>();
+      const sleep = vi.fn(() => backoff.promise);
+      const uploadImage = vi.fn(() => Promise.reject(new Error('retry me')));
+      const onError = vi.fn();
+      const h = createHarness({ maxUploadAttempts: 3, onError, sleep, uploadImage });
+      h.store.markLayerDirty(LAYER);
+      const barrier = h.store.flushPendingUploads();
+      await drainUntil(() => sleep.mock.calls.length >= 1);
+      expect(uploadImage).toHaveBeenCalledOnce();
+
+      if (cancellation === 'discard') {
+        h.store.discardLayer(LAYER);
+      } else {
+        h.store.reset();
+      }
+      backoff.resolve();
+      await barrier;
+
+      expect(uploadImage).toHaveBeenCalledOnce();
+      expect(onError).not.toHaveBeenCalled();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      h.store.dispose();
+    }
+  );
+
+  it('allows fresh same-id persistence after repeated idle discards', async () => {
+    const h = createHarness();
+    for (let i = 0; i < 1_000; i += 1) {
+      h.store.discardLayer(`removed-${i}`);
+    }
+
+    h.store.discardLayer(LAYER);
+    h.store.markLayerDirty(LAYER);
+    await h.store.flushPendingUploads();
+
+    expect(h.uploadImage).toHaveBeenCalledOnce();
+    expect(h.dispatch).toHaveBeenCalledOnce();
+    h.store.dispose();
+  });
+
+  it('preserves a fresh same-id generation while obsolete encoding settles', async () => {
+    const obsoleteEncode = createDeferred<Blob>();
+    let encodeCall = 0;
+    const encodeSurface = vi.fn(() => {
+      encodeCall += 1;
+      return encodeCall === 1
+        ? obsoleteEncode.promise
+        : Promise.resolve(new Blob(['fresh pixels'], { type: 'image/png' }));
+    });
+    const hashBlob = vi.fn((blob: Blob) => blob.text());
+    const h = createHarness({ encodeSurface, hashBlob });
+    h.store.markLayerDirty(LAYER);
+    const barrier = h.store.flushPendingUploads();
+    await drainUntil(() => encodeSurface.mock.calls.length === 1);
+
+    h.store.discardLayer(LAYER);
+    h.store.markLayerDirty(LAYER);
+    obsoleteEncode.resolve(new Blob(['obsolete pixels'], { type: 'image/png' }));
+    await barrier;
+
+    expect(encodeSurface).toHaveBeenCalledTimes(2);
+    expect(hashBlob).toHaveBeenCalledOnce();
+    expect(await hashBlob.mock.calls[0]![0].text()).toBe('fresh pixels');
+    expect(h.uploadImage).toHaveBeenCalledOnce();
+    expect(h.dispatch).toHaveBeenCalledOnce();
+    h.store.dispose();
+  });
+
+  it.each(['discard', 'reset'] as const)(
+    'lets an error observer %s failed persistence without a later dirty resurrection',
+    async (cancellation) => {
+      const uploadImage = vi.fn(() => Promise.reject(new Error('upload failed')));
+      let store: ReturnType<typeof createBitmapStore> | null = null;
+      const onError = vi.fn(() => {
+        if (cancellation === 'discard') {
+          store?.discardLayer(LAYER);
+        } else {
+          store?.reset();
+        }
+      });
+      const h = createHarness({ maxUploadAttempts: 1, onError, uploadImage });
+      store = h.store;
+
+      h.store.markLayerDirty(LAYER);
+      await h.store.flushPendingUploads();
+      await vi.advanceTimersByTimeAsync(3000);
+
+      expect(onError).toHaveBeenCalledOnce();
+      expect(uploadImage).toHaveBeenCalledOnce();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      await h.store.flushPendingUploads();
+      expect(uploadImage).toHaveBeenCalledOnce();
+      h.store.dispose();
+    }
+  );
+
+  it('does not flush after dispose', async () => {
+    const h = createHarness();
+    h.store.markLayerDirty(LAYER);
+    h.store.dispose();
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(h.uploadImage).not.toHaveBeenCalled();
+  });
+
+  describe('source-type guard (rasterize → undo convergence)', () => {
+    it('drops the dirty entry without dispatching when the debounce timer fires after the layer left `paint`', async () => {
+      const h = createHarness();
+
+      h.store.markLayerDirty(LAYER);
+      // The layer converted back to a parametric source (e.g. rasterize → undo)
+      // before the debounce window elapsed — the cache surface still resolves
+      // (a source swap doesn't clear it), so only this guard prevents a stale
+      // paint dispatch.
+      h.setSource({
+        fill: '#ff0000',
+        height: 40,
+        kind: 'rect',
+        stroke: null,
+        strokeWidth: 0,
+        type: 'shape',
+        width: 60,
+      });
+
+      await vi.advanceTimersByTimeAsync(1500);
+
+      expect(h.uploadImage).not.toHaveBeenCalled();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      h.store.dispose();
+    });
+
+    it('drops the dirty entry without dispatching when `flushPendingUploads` is awaited after the layer left `paint`', async () => {
+      const h = createHarness();
+
+      h.store.markLayerDirty(LAYER);
+      h.setSource({ angle: 0, kind: 'linear', stops: [{ color: '#000', offset: 0 }], type: 'gradient' });
+
+      // Do NOT advance timers: exercise the barrier path (e.g. pressing Invoke
+      // right after the undo), not just the debounce path.
+      await h.store.flushPendingUploads();
+
+      expect(h.uploadImage).not.toHaveBeenCalled();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      h.store.dispose();
+    });
+
+    it('drops the dirty entry without dispatching when the layer no longer exists', async () => {
+      const h = createHarness();
+
+      h.store.markLayerDirty(LAYER);
+      h.setSource(null);
+
+      await h.store.flushPendingUploads();
+
+      expect(h.uploadImage).not.toHaveBeenCalled();
+      expect(h.dispatch).not.toHaveBeenCalled();
+      h.store.dispose();
+    });
+
+    it('closes the race where the source leaves `paint` WHILE an upload is already in flight', async () => {
+      const deferred = createDeferred<CanvasImageUploadResult>();
+      const uploadImage = vi.fn(() => deferred.promise);
+      const h = createHarness({ uploadImage });
+
+      h.store.markLayerDirty(LAYER);
+      const barrier = h.store.flushPendingUploads();
+
+      // Encode/hash/upload have started (passing the entry-time guard while the
+      // source was still `paint`); the upload is now in flight.
+      await drainUntil(() => uploadImage.mock.calls.length >= 1);
+      expect(uploadImage).toHaveBeenCalledTimes(1);
+
+      // The source changes away from `paint` DURING the in-flight upload —
+      // later than the entry-time check, so only the pre-dispatch recheck
+      // catches it.
+      h.setSource({ fill: '#000', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 });
+
+      deferred.resolve({ height: 10, imageName: 'img-x', width: 10 });
+      await barrier;
+
+      expect(h.dispatch).not.toHaveBeenCalled();
+      h.store.dispose();
+    });
+
+    it('still flushes normally when the layer stays a paint layer (no regression)', async () => {
+      const h = createHarness();
+
+      h.store.markLayerDirty(LAYER);
+      await vi.advanceTimersByTimeAsync(1500);
+      await h.store.flushPendingUploads();
+
+      expect(h.uploadImage).toHaveBeenCalledTimes(1);
+      expect(h.dispatch).toHaveBeenCalledTimes(1);
+      expect(h.dispatch.mock.calls[0][0]).toMatchObject({
+        id: LAYER,
+        source: { type: 'paint' },
+        type: 'updateCanvasLayerSource',
+      });
+      h.store.dispose();
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/bitmapStore.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/bitmapStore.ts
new file mode 100644
index 00000000000..3b779d8e925
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/bitmapStore.ts
@@ -0,0 +1,687 @@
+/**
+ * The bitmap store: paint persistence via content-hashed server images.
+ *
+ * Painting bakes strokes straight into a layer's raster cache surface (see
+ * `strokeSession`/`paintTool`), but nothing persists — a reload would lose the
+ * strokes. This store closes that loop: on each committed stroke it marks the
+ * layer dirty, and after a short idle window it encodes the layer's full cache
+ * surface to a PNG, content-hashes it (SHA-256), dedupes against already
+ * uploaded bitmaps, uploads new ones, and — only once the upload succeeds —
+ * dispatches `updateCanvasLayerSource` so the reducer-owned document points its
+ * paint layer at the persisted image name. The reducer stays pixel-free: only a
+ * `CanvasImageRef` (name + dims + hash) ever crosses the boundary.
+ *
+ * Key invariants:
+ * - **Swap-on-success**: the contract keeps its previous ref until the upload
+ *   resolves. A failed upload never dispatches; the layer stays dirty and the
+ *   old ref stays valid, so a reload still shows the last persisted pixels.
+ * - **Debounce per layer** (~1.5 s idle): a new stroke resets the timer, so a
+ *   burst of strokes uploads once.
+ * - **Content-hash dedupe**: identical pixels reuse the previously uploaded
+ *   image name and skip the upload entirely. This is what makes undo cheap
+ *   (restoring old pixels re-hashes to the already-uploaded image).
+ * - **Self-echo guard**: the dispatch round-trips back through the document
+ *   mirror as a source change for the layer. {@link BitmapStore.isSelfEcho}
+ *   lets the engine skip re-rasterizing/invalidating the cache for the exact
+ *   bitmap ref this store just applied (the pixels already match).
+ * - **Source-type guard**: a layer's cache surface survives a source-type
+ *   change (e.g. rasterize's paint bake, then an undo back to shape/gradient)
+ *   — only the document's source pointer changes, not the cache. So every
+ *   flush re-checks `getLayerSource` (at entry AND again right before the
+ *   dispatch, since encode/hash/upload all await) and drops the pending work
+ *   without dispatching if the layer is no longer `paint` (or no longer
+ *   exists). Otherwise a stale debounced flush would silently convert a
+ *   parametric layer back to `paint` with wrong-extent pixels.
+ * - **Redundant-dispatch skip is ground-truth, not memory**: right before
+ *   dispatching, a flush skips if the DOCUMENT's current bitmap ref (via
+ *   `getLayerSource`) already equals the resolved image name — not if
+ *   `lastApplied` (this store's memory of what it last dispatched) does. A
+ *   round trip through a non-`paint` source and back (rasterize → undo →
+ *   redo) leaves `lastApplied` pointing at a name the document no longer
+ *   references (the redo lands on `{ bitmap: null }`); comparing against that
+ *   stale memory would suppress the re-dispatch forever. Comparing against
+ *   the document itself self-heals regardless of how it drifted.
+ *
+ * Every side-effecting dependency (encode, upload, hash, dispatch, timers) is
+ * injectable, so this runs in node tests with fakes. Zero React.
+ */
+
+import type { CanvasImageUploadResult } from '@workbench/canvas-engine/document/imageUpload';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasImageRef, CanvasLayerSourceContract } from '@workbench/types';
+
+/** Default idle window before a dirty layer is flushed. */
+export const DEFAULT_DEBOUNCE_MS = 1500;
+/** Default upload attempts per flush (initial try + retries). */
+export const DEFAULT_MAX_UPLOAD_ATTEMPTS = 3;
+/** Default backoff delays (ms) between upload retries. */
+export const DEFAULT_RETRY_DELAYS_MS = [250, 1000] as const;
+/** Default cap on the hash→image dedupe map. */
+export const DEFAULT_DEDUPE_CAP = 64;
+
+export class BitmapPersistenceError extends Error {
+  readonly layerIds: readonly string[];
+
+  constructor(layerIds: readonly string[]) {
+    super(`Canvas pixel persistence failed for ${layerIds.length} layer${layerIds.length === 1 ? '' : 's'}.`);
+    this.name = 'BitmapPersistenceError';
+    this.layerIds = [...layerIds];
+  }
+}
+
+/** Injectable timer seam (defaults to the global timers). */
+export interface BitmapStoreTimers {
+  setTimeout(handler: () => void, ms: number): number;
+  clearTimeout(handle: number): void;
+}
+
+/** Dependencies for {@link createBitmapStore}. */
+export interface BitmapStoreDeps {
+  /**
+   * Returns a layer's live cache surface (its painted pixels) plus the layer-local
+   * `offset` its top-left pixel sits at (its content rect origin), or `null` when
+   * the cache is gone/empty. The surface is CONTENT-SIZED, so the encoded PNG
+   * covers only the painted region and the dispatched paint source carries the
+   * offset (loading rasterizes at it). Read atomically here so the encoded pixels
+   * and the offset always agree.
+   */
+  getLayerSurface(layerId: string): { surface: RasterSurface; offset: { x: number; y: number } } | null;
+  /**
+   * Returns a layer's CURRENT document source, or `null` if the layer no
+   * longer exists. Used to guard a flush against a source-type change that
+   * happened AFTER the dirty mark was recorded — e.g. rasterize (paint) →
+   * undo (back to shape/gradient) — where the layer's cache surface still
+   * resolves (it isn't cleared by the source swap) but persisting it would
+   * dispatch stale paint pixels over a now-parametric layer.
+   */
+  getLayerSource(layerId: string): CanvasLayerSourceContract | null;
+  /**
+   * Reads a layer source from reducer-owned project state, bypassing subscriber-
+   * refreshed mirrors. Used only to verify whether a dispatch that threw after
+   * reducer commit nevertheless landed exactly as intended.
+   */
+  getAuthoritativeLayerSource?(layerId: string): CanvasLayerSourceContract | null;
+  /** Encodes a surface to an image `Blob` (PNG). Usually `backend.encodeSurface`. */
+  encodeSurface(surface: RasterSurface): Promise<Blob>;
+  /** Uploads a bitmap blob, resolving to its server image name and dimensions. */
+  uploadImage(blob: Blob): Promise<CanvasImageUploadResult>;
+  /** Dispatches to the reducer (the single swap-on-success `updateCanvasLayerSource`). */
+  dispatch(action: CanvasProjectMutation): boolean;
+  /**
+   * Applies the persisted bitmap ref + offset to the layer's document contract,
+   * as the single swap-on-success dispatch. Lets the engine pick the right
+   * action per layer type — `updateCanvasLayerSource` (paint source) for raster/
+   * control layers, `updateCanvasLayerConfig` (mask) for inpaint/regional masks —
+   * while the store stays type-agnostic. Absent ⇒ the default paint-source
+   * dispatch (used by the store's own tests, which only exercise paint layers).
+   */
+  dispatchBitmap?(layerId: string, bitmap: CanvasImageRef, offset: { x: number; y: number }): boolean;
+  /** Content-hashes a blob (defaults to SHA-256 hex via `crypto.subtle`). */
+  hashBlob?(blob: Blob): Promise<string>;
+  /** Idle debounce window in ms (default {@link DEFAULT_DEBOUNCE_MS}). */
+  debounceMs?: number;
+  /** Upload attempts per flush (default {@link DEFAULT_MAX_UPLOAD_ATTEMPTS}). */
+  maxUploadAttempts?: number;
+  /** Backoff delays between retries (default {@link DEFAULT_RETRY_DELAYS_MS}). */
+  retryDelaysMs?: readonly number[];
+  /** Cap on the dedupe map (default {@link DEFAULT_DEDUPE_CAP}). */
+  dedupeCap?: number;
+  /** Injectable timers (default: global). */
+  timers?: BitmapStoreTimers;
+  /** Injectable delay used for retry backoff (default: `timers.setTimeout`). */
+  sleep?(ms: number): Promise<void>;
+  /** Reports a persistent flush/upload failure. Omitted callbacks leave the failure unreported. */
+  onError?(error: unknown, layerId: string): void;
+}
+
+/** The imperative bitmap-store handle. */
+export interface BitmapStore {
+  /** Marks a layer dirty and (re)arms its debounce timer. Called on each committed stroke. */
+  markLayerDirty(layerId: string): void;
+  /**
+   * Temporarily prevents persistence from reading or dispatching `layerId` while
+   * preserving dirty work. Returns an idempotent release; leases may be nested.
+   */
+  suspendLayer(layerId: string): () => void;
+  /** Cancels pending persistence and invalidates an in-flight result for one layer. */
+  discardLayer(layerId: string): void;
+  /** Flushes every dirty layer immediately and resolves once all in-flight uploads settle. */
+  flushPendingUploads(): Promise<void>;
+  /**
+   * True when `source` is exactly the paint bitmap ref this store most recently
+   * applied to `layerId` — i.e. the engine is seeing its own dispatch round-trip
+   * and must NOT re-rasterize/invalidate the cache (the pixels already match).
+   * A different bitmap (undo/import) returns `false` and re-rasterizes as usual.
+   */
+  isSelfEcho(layerId: string, source: CanvasLayerSourceContract | null): boolean;
+  /**
+   * Drops the persistence bookkeeping that describes the OUTGOING document, for
+   * use on a wholesale document replacement. Clears the `lastApplied` self-echo
+   * map (a reused layer id in the new document could otherwise have a legit
+   * persistence dispatch suppressed forever) and any pending dirty/debounced
+   * work for the old document. The content-hash dedupe cache is intentionally
+   * kept — it is a pure content-addressed mapping (identical PNG bytes → the
+   * same immutable uploaded image) and so is never stale across documents.
+   */
+  reset(): void;
+  /** Cancels all timers; in-flight uploads are left to settle (no dispatch after dispose). */
+  dispose(): void;
+}
+
+const defaultTimers: BitmapStoreTimers = {
+  clearTimeout: (handle) => globalThis.clearTimeout(handle),
+  setTimeout: (handler, ms) => globalThis.setTimeout(handler, ms),
+};
+
+/** SHA-256 hex of a blob's bytes, via the Web Crypto API (Node ≥ 20 exposes `crypto.subtle`). */
+const defaultHashBlob = async (blob: Blob): Promise<string> => {
+  const buffer = await blob.arrayBuffer();
+  const digest = await crypto.subtle.digest('SHA-256', buffer);
+  const bytes = new Uint8Array(digest);
+  let hex = '';
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, '0');
+  }
+  return hex;
+};
+
+/** Creates a bitmap store wired to the given seams. */
+export const createBitmapStore = (deps: BitmapStoreDeps): BitmapStore => {
+  const debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const maxAttempts = Math.max(1, deps.maxUploadAttempts ?? DEFAULT_MAX_UPLOAD_ATTEMPTS);
+  const retryDelays = deps.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+  const dedupeCap = Math.max(1, deps.dedupeCap ?? DEFAULT_DEDUPE_CAP);
+  const timers = deps.timers ?? defaultTimers;
+  const hashBlob = deps.hashBlob ?? defaultHashBlob;
+  const sleep =
+    deps.sleep ??
+    ((ms: number): Promise<void> =>
+      new Promise((resolve) => {
+        timers.setTimeout(resolve, ms);
+      }));
+  const reportError = (error: unknown, layerId: string): void => deps.onError?.(error, layerId);
+
+  /** Layers awaiting a flush (either debounced or re-dirtied during a flush). */
+  const dirty = new Set<string>();
+  /**
+   * Why a layer is currently in `dirty`: `'stroke'` means a new paint stroke
+   * (re)marked it — worth retrying inside a barrier call; `'failure'` means
+   * its last flush attempt exhausted upload retries — the barrier must not
+   * retry it again within the same {@link flushPendingUploads} call (anti-spin).
+   * A stroke landing after a failure flips this back to `'stroke'`.
+   */
+  const dirtyReason = new Map<string, 'failure' | 'stroke'>();
+  /** Active debounce timers, keyed by layer id. */
+  const debounceTimers = new Map<string, number>();
+  /** The in-flight flush op per layer (at most one), used by the barrier and to serialize. */
+  const inFlight = new Map<string, Promise<void>>();
+  /** Content-hash → uploaded image, an LRU-ish dedupe cache (bounded). */
+  const hashToImage = new Map<string, CanvasImageUploadResult>();
+  /** Layer id → the image name most recently dispatched by this store (self-echo guard). */
+  const lastApplied = new Map<string, string>();
+  /**
+   * Per-layer generation used only while invalidated work is still in flight.
+   * Idle ids are removed so ordinary layer deletion cannot accumulate permanent
+   * tombstones for the lifetime of the engine.
+   */
+  const layerGenerations = new Map<string, number>();
+  /** Active nested persistence-suspension generation per layer. */
+  const suspensions = new Map<string, { count: number; token: symbol }>();
+  /** Barriers waiting for a suspended dirty layer to resume or be reset/disposed. */
+  const suspensionWaiters = new Set<() => void>();
+  let disposed = false;
+
+  const isSuspended = (layerId: string): boolean => (suspensions.get(layerId)?.count ?? 0) > 0;
+  const notifySuspensionWaiters = (): void => {
+    const waiters = [...suspensionWaiters];
+    suspensionWaiters.clear();
+    for (const resolve of waiters) {
+      resolve();
+    }
+  };
+  const waitForSuspensionChange = (): Promise<void> =>
+    new Promise((resolve) => {
+      suspensionWaiters.add(resolve);
+    });
+
+  const clearTimer = (layerId: string): void => {
+    const handle = debounceTimers.get(layerId);
+    if (handle !== undefined) {
+      timers.clearTimeout(handle);
+      debounceTimers.delete(layerId);
+    }
+  };
+
+  const scheduleFlush = (layerId: string): void => {
+    clearTimer(layerId);
+    const handle = timers.setTimeout(() => {
+      debounceTimers.delete(layerId);
+      void runFlush(layerId);
+    }, debounceMs);
+    debounceTimers.set(layerId, handle);
+  };
+
+  const rememberDedupe = (hash: string, result: CanvasImageUploadResult): void => {
+    hashToImage.delete(hash);
+    hashToImage.set(hash, result);
+    while (hashToImage.size > dedupeCap) {
+      const oldest = hashToImage.keys().next().value;
+      if (oldest === undefined) {
+        break;
+      }
+      hashToImage.delete(oldest);
+    }
+  };
+
+  const touchDedupe = (hash: string, result: CanvasImageUploadResult): void => {
+    // Move to the most-recently-used end.
+    hashToImage.delete(hash);
+    hashToImage.set(hash, result);
+  };
+
+  const uploadWithRetry = async (
+    blob: Blob,
+    isCurrentGeneration: () => boolean
+  ): Promise<CanvasImageUploadResult | null> => {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (!isCurrentGeneration()) {
+        return null;
+      }
+      if (attempt > 0) {
+        const delay = retryDelays[Math.min(attempt - 1, retryDelays.length - 1)] ?? 0;
+        if (delay > 0) {
+          await sleep(delay);
+          if (!isCurrentGeneration()) {
+            return null;
+          }
+        }
+      }
+      if (!isCurrentGeneration()) {
+        return null;
+      }
+      try {
+        const result = await deps.uploadImage(blob);
+        if (!isCurrentGeneration()) {
+          return null;
+        }
+        return result;
+      } catch (error) {
+        if (!isCurrentGeneration()) {
+          return null;
+        }
+        lastError = error;
+      }
+    }
+    throw lastError ?? new Error('Canvas image upload failed');
+  };
+
+  /** Encodes → hashes → dedupes/uploads → swaps the layer's ref, once. */
+  const flushLayer = async (layerId: string): Promise<void> => {
+    const generationAtEntry = layerGenerations.get(layerId) ?? 0;
+    const isCurrentGeneration = (): boolean => !disposed && (layerGenerations.get(layerId) ?? 0) === generationAtEntry;
+    const requeueFailure = (error: unknown): void => {
+      if (!isCurrentGeneration()) {
+        return;
+      }
+      // Requeue before notifying. An injected error observer may deliberately
+      // discard/reset this generation; its cancellation must be the final word,
+      // not followed by a stale dirty.add(). Observer exceptions are ancillary.
+      dirty.add(layerId);
+      dirtyReason.set(layerId, 'failure');
+      try {
+        reportError(error, layerId);
+      } catch {
+        // Keep the bounded retry state intact when an observer itself fails.
+      }
+    };
+    const placed = deps.getLayerSurface(layerId);
+    if (!placed) {
+      // Layer or its cache is gone (or empty); nothing to persist.
+      dirty.delete(layerId);
+      clearTimer(layerId);
+      return;
+    }
+    // Capture the surface AND its offset together at encode time so they agree:
+    // encode reads these pixels, and the dispatch below carries this offset. A
+    // growth during the async encode window re-marks the layer (its stroke marks
+    // it dirty), so a follow-up flush re-converges with the current rect + offset.
+    const { offset, surface } = placed;
+    // Source-type guard (see `getLayerSource` doc): the dirty mark may predate
+    // a conversion away from `paint` (rasterize → undo is the motivating case,
+    // but any convert-back qualifies). The cache surface still resolves above
+    // — a source swap doesn't clear it — so without this check we'd encode and
+    // dispatch a `paint` source over a layer that is no longer paint at all.
+    // Drop the pending flush entirely: nothing about this dirty mark is still
+    // valid, and a future genuine paint stroke will re-mark it if the layer
+    // ever becomes a paint layer again.
+    const sourceAtEntry = deps.getLayerSource(layerId);
+    if (!sourceAtEntry || sourceAtEntry.type !== 'paint') {
+      dirty.delete(layerId);
+      clearTimer(layerId);
+      return;
+    }
+    // Consume the dirty flag up front; a failure re-adds it below. A stroke that
+    // lands mid-flush re-marks the layer, so the finally handler re-schedules.
+    dirty.delete(layerId);
+    clearTimer(layerId);
+
+    let hash: string;
+    let blob: Blob;
+    try {
+      blob = await deps.encodeSurface(surface);
+      if (!isCurrentGeneration()) {
+        return;
+      }
+      hash = await hashBlob(blob);
+      if (!isCurrentGeneration()) {
+        return;
+      }
+    } catch (error) {
+      requeueFailure(error);
+      return;
+    }
+
+    let result = hashToImage.get(hash);
+    if (result) {
+      // Dedupe hit: identical pixels already uploaded — reuse the name, no upload.
+      touchDedupe(hash, result);
+    } else {
+      try {
+        const uploaded = await uploadWithRetry(blob, isCurrentGeneration);
+        if (!uploaded) {
+          return;
+        }
+        result = uploaded;
+      } catch (error) {
+        // Swap-on-success: never dispatch on failure. The old ref stays valid
+        // and the layer stays dirty for a later retry.
+        requeueFailure(error);
+        return;
+      }
+      rememberDedupe(hash, result);
+    }
+
+    if (!isCurrentGeneration()) {
+      return;
+    }
+    // Re-check the source right before dispatching: `encodeSurface`/`hashBlob`/
+    // `uploadImage` above all awaited, so a source-type change (rasterize →
+    // undo) landing DURING that window would slip past the entry-time
+    // `sourceAtEntry` check otherwise. This is the final gate before the
+    // side-effecting dispatch.
+    const sourceNow = deps.getLayerSource(layerId);
+    if (!sourceNow || sourceNow.type !== 'paint') {
+      return;
+    }
+    // The DOCUMENT already points at this exact image (e.g. a re-flush of
+    // identical pixels that hash-deduped to an already-applied ref): skip a
+    // redundant dispatch and its self-echo round-trip.
+    //
+    // This is checked against `sourceNow` (the document's CURRENT bitmap ref),
+    // not `lastApplied` (this store's memory of what it last dispatched) — the
+    // two can diverge. `lastApplied` is never cleared when a layer's source is
+    // converted away from `paint` and back (e.g. `rasterizeLayer` → undo →
+    // redo: the document round-trips through a parametric source and back to
+    // `paint`, landing on `{ bitmap: null }`, while `lastApplied` still holds
+    // the previously-uploaded name from before the undo). Comparing against
+    // `lastApplied` in that case would suppress the dispatch forever, leaving
+    // the document permanently pointed at `bitmap: null` even though the
+    // dedupe correctly resolved the identical baked pixels back to the prior
+    // image. Comparing against the document's actual current ref is the
+    // ground truth for "is this dispatch a no-op" and self-heals regardless
+    // of how the document's source got out of sync with this store's memory.
+    //
+    // The OFFSET must match too: a pure-translation transform (drag + Apply)
+    // bakes byte-identical pixels → same hash → dedupe resolves to the
+    // already-referenced image, but the paint offset moved. Comparing only
+    // `imageName` would skip the dispatch that persists the new offset, so the
+    // translation would be silently lost on reload (and every re-flush would
+    // re-skip it forever). Compare the captured `offset` (which travels with
+    // this dispatch) against the document's current offset — absent offsets are
+    // the legacy origin `{ x: 0, y: 0 }`.
+    const currentOffset = sourceNow.bitmap ? (sourceNow.offset ?? { x: 0, y: 0 }) : null;
+    if (
+      sourceNow.bitmap?.imageName === result.imageName &&
+      currentOffset !== null &&
+      currentOffset.x === offset.x &&
+      currentOffset.y === offset.y
+    ) {
+      return;
+    }
+
+    const bitmap: CanvasImageRef = {
+      contentHash: hash,
+      height: result.height,
+      imageName: result.imageName,
+      width: result.width,
+    };
+    // Record BEFORE dispatching: `dispatch` may notify the mirror synchronously,
+    // so `isSelfEcho` must already see the applied name when the engine reacts.
+    lastApplied.set(layerId, result.imageName);
+    let accepted: boolean;
+    try {
+      accepted = deps.dispatchBitmap
+        ? deps.dispatchBitmap(layerId, bitmap, { x: offset.x, y: offset.y })
+        : deps.dispatch({
+            id: layerId,
+            source: { bitmap, offset: { x: offset.x, y: offset.y }, type: 'paint' },
+            type: 'updateCanvasLayerSource',
+          });
+    } catch (error) {
+      const authoritativeSource = (deps.getAuthoritativeLayerSource ?? deps.getLayerSource)(layerId);
+      const authoritativeOffset =
+        authoritativeSource?.type === 'paint' && authoritativeSource.bitmap
+          ? (authoritativeSource.offset ?? { x: 0, y: 0 })
+          : null;
+      const didLand =
+        authoritativeSource?.type === 'paint' &&
+        authoritativeSource.bitmap?.imageName === bitmap.imageName &&
+        authoritativeSource.bitmap.width === bitmap.width &&
+        authoritativeSource.bitmap.height === bitmap.height &&
+        authoritativeSource.bitmap.contentHash === bitmap.contentHash &&
+        authoritativeOffset?.x === offset.x &&
+        authoritativeOffset.y === offset.y;
+      if (didLand) {
+        return;
+      }
+      lastApplied.delete(layerId);
+      if (authoritativeSource !== null) {
+        requeueFailure(error);
+      }
+      return;
+    }
+    if (accepted !== true) {
+      lastApplied.delete(layerId);
+      if (deps.getLayerSource(layerId) !== null) {
+        dirty.add(layerId);
+        dirtyReason.set(layerId, 'failure');
+      }
+    }
+  };
+
+  /** Runs (or joins) a flush for a layer, serializing to one in-flight op per layer. */
+  const runFlush = (layerId: string): Promise<void> => {
+    const existing = inFlight.get(layerId);
+    if (existing) {
+      return existing;
+    }
+    if (isSuspended(layerId)) {
+      return Promise.resolve();
+    }
+    const op = flushLayer(layerId).finally(() => {
+      inFlight.delete(layerId);
+      // Re-dirtied during the flush (new stroke) or a failure re-queued it.
+      if (dirty.has(layerId) && !disposed && !isSuspended(layerId)) {
+        scheduleFlush(layerId);
+      } else {
+        // Any invalidated operation for this id has now settled and there is no
+        // successor waiting to inherit its generation. Retire the tombstone.
+        layerGenerations.delete(layerId);
+      }
+    });
+    inFlight.set(layerId, op);
+    return op;
+  };
+
+  const markLayerDirty = (layerId: string): void => {
+    if (disposed) {
+      return;
+    }
+    dirty.add(layerId);
+    dirtyReason.set(layerId, 'stroke');
+    if (!isSuspended(layerId)) {
+      scheduleFlush(layerId);
+    }
+  };
+
+  const suspendLayer = (layerId: string): (() => void) => {
+    if (disposed) {
+      return () => undefined;
+    }
+    const currentSuspension = suspensions.get(layerId);
+    const count = currentSuspension?.count ?? 0;
+    const token = currentSuspension?.token ?? Symbol(layerId);
+    suspensions.set(layerId, { count: count + 1, token });
+    if (count === 0) {
+      const hadPendingWork = dirty.has(layerId) || debounceTimers.has(layerId) || inFlight.has(layerId);
+      clearTimer(layerId);
+      if (inFlight.has(layerId)) {
+        layerGenerations.set(layerId, (layerGenerations.get(layerId) ?? 0) + 1);
+      }
+      if (hadPendingWork) {
+        dirty.add(layerId);
+        dirtyReason.set(layerId, 'stroke');
+      }
+    }
+
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      const current = suspensions.get(layerId);
+      if (!current || current.token !== token) {
+        return;
+      }
+      if (current.count <= 1) {
+        suspensions.delete(layerId);
+        if (dirty.has(layerId) && !disposed) {
+          scheduleFlush(layerId);
+        }
+      } else {
+        suspensions.set(layerId, { count: current.count - 1, token });
+      }
+      notifySuspensionWaiters();
+    };
+  };
+
+  const discardLayer = (layerId: string): void => {
+    if (inFlight.has(layerId)) {
+      // Keep an invalidating generation only while obsolete async work can
+      // still settle. Same-id work arriving before it settles inherits this
+      // generation and is scheduled after the old operation completes.
+      layerGenerations.set(layerId, (layerGenerations.get(layerId) ?? 0) + 1);
+    } else {
+      layerGenerations.delete(layerId);
+    }
+    dirty.delete(layerId);
+    dirtyReason.delete(layerId);
+    lastApplied.delete(layerId);
+    clearTimer(layerId);
+  };
+
+  /** Safety net against a genuine infinite loop; real barrier calls settle in a handful of rounds. */
+  const MAX_BARRIER_ITERATIONS = 10_000;
+
+  const flushPendingUploads = async (): Promise<void> => {
+    // Immediately flush every currently-dirty layer (cancelling its debounce),
+    // then await the in-flight ops — looping so a layer re-dirtied by a NEW
+    // stroke that lands while its upload is in flight gets a follow-up flush
+    // before the barrier resolves (the "document points at the latest painted
+    // pixels" guarantee). A layer whose flush FAILED within this barrier call
+    // is not retried again this call — only a fresh stroke re-enters the loop
+    // for it — so a persistently failing upload still can't spin the barrier
+    // forever.
+    const failedThisBarrier = new Set<string>();
+    for (let iteration = 0; iteration < MAX_BARRIER_ITERATIONS; iteration += 1) {
+      const toFlush = Array.from(dirty).filter((layerId) => !failedThisBarrier.has(layerId) && !isSuspended(layerId));
+      for (const layerId of toFlush) {
+        clearTimer(layerId);
+        void runFlush(layerId);
+      }
+      const ops = [...inFlight.values()];
+      if (ops.length === 0) {
+        if (Array.from(dirty).some((layerId) => isSuspended(layerId))) {
+          await waitForSuspensionChange();
+          continue;
+        }
+        const failedLayerIds = Array.from(failedThisBarrier).filter(
+          (layerId) => dirty.has(layerId) && dirtyReason.get(layerId) === 'failure'
+        );
+        if (failedLayerIds.length > 0) {
+          throw new BitmapPersistenceError(failedLayerIds);
+        }
+        return;
+      }
+      await Promise.all(ops);
+      for (const layerId of toFlush) {
+        if (dirty.has(layerId) && dirtyReason.get(layerId) === 'failure') {
+          failedThisBarrier.add(layerId);
+        }
+      }
+    }
+    throw new Error('Canvas pixel persistence barrier exceeded its iteration limit.');
+  };
+
+  const isSelfEcho = (layerId: string, source: CanvasLayerSourceContract | null): boolean => {
+    if (!source || source.type !== 'paint') {
+      return false;
+    }
+    const imageName = source.bitmap?.imageName;
+    return imageName !== undefined && lastApplied.get(layerId) === imageName;
+  };
+
+  const reset = (): void => {
+    for (const layerId of inFlight.keys()) {
+      layerGenerations.set(layerId, (layerGenerations.get(layerId) ?? 0) + 1);
+    }
+    for (const layerId of layerGenerations.keys()) {
+      if (!inFlight.has(layerId)) {
+        layerGenerations.delete(layerId);
+      }
+    }
+    // Cancel pending debounced flushes and drop dirty state for the OLD document.
+    for (const handle of debounceTimers.values()) {
+      timers.clearTimeout(handle);
+    }
+    debounceTimers.clear();
+    dirty.clear();
+    dirtyReason.clear();
+    suspensions.clear();
+    notifySuspensionWaiters();
+    // The self-echo map is per-(old)document; a reused layer id in the new
+    // document must not inherit it. `hashToImage` is content-addressed and kept.
+    lastApplied.clear();
+  };
+
+  const dispose = (): void => {
+    disposed = true;
+    for (const handle of debounceTimers.values()) {
+      timers.clearTimeout(handle);
+    }
+    debounceTimers.clear();
+    dirty.clear();
+    dirtyReason.clear();
+    suspensions.clear();
+    notifySuspensionWaiters();
+    inFlight.clear();
+    hashToImage.clear();
+    lastApplied.clear();
+    layerGenerations.clear();
+  };
+
+  return { discardLayer, dispose, flushPendingUploads, isSelfEcho, markLayerDirty, reset, suspendLayer };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/documentMirror.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/documentMirror.test.ts
new file mode 100644
index 00000000000..104b5bfa456
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/documentMirror.test.ts
@@ -0,0 +1,379 @@
+import type {
+  CanvasDocumentContractV2,
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+  CanvasStagingAreaContractV2,
+  CanvasStateContractV2,
+} from '@workbench/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import type { DocumentMirrorCallbacks } from './documentMirror';
+
+import { createDocumentMirror } from './documentMirror';
+
+const rasterLayer = (id: string, overrides: Partial<CanvasRasterLayerContractV2> = {}): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: 10, imageName: id, width: 10 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+  ...overrides,
+});
+
+const makeDoc = (
+  layers: CanvasLayerContract[],
+  overrides: Partial<CanvasDocumentContractV2> = {}
+): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 100,
+  ...overrides,
+});
+
+const makeStaging = (): CanvasStagingAreaContractV2 => ({
+  areThumbnailsVisible: false,
+  autoSwitchMode: 'off',
+  isVisible: false,
+  pendingImageIds: [],
+  pendingImages: [],
+  selectedImageIndex: 0,
+});
+
+const makeCanvas = (document: CanvasDocumentContractV2, documentRevision = 0): CanvasStateContractV2 => ({
+  document,
+  documentRevision,
+  snapshots: [],
+  stagingArea: makeStaging(),
+  version: 2,
+});
+
+interface FakeProject {
+  id: string;
+  canvas: CanvasStateContractV2;
+}
+
+const createFakeStore = (projects: FakeProject[]) => {
+  let state = { projects };
+  const listeners = new Set<() => void>();
+  return {
+    getState: () => state,
+    replaceStateSilently: (next: { projects: FakeProject[] }) => {
+      state = next;
+    },
+    setState: (next: { projects: FakeProject[] }) => {
+      state = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+};
+
+const spyCallbacks = () => ({
+  onBboxChanged: vi.fn<DocumentMirrorCallbacks['onBboxChanged']>(),
+  onDocumentReplaced: vi.fn<DocumentMirrorCallbacks['onDocumentReplaced']>(),
+  onLayerOrderChanged: vi.fn<DocumentMirrorCallbacks['onLayerOrderChanged']>(),
+  onLayersChanged: vi.fn<DocumentMirrorCallbacks['onLayersChanged']>(),
+  onStagingChanged: vi.fn<DocumentMirrorCallbacks['onStagingChanged']>(),
+});
+
+describe('createDocumentMirror', () => {
+  it('synchronously refreshes from authoritative state when normal notification was interrupted', () => {
+    const a = rasterLayer('a');
+    const doc = makeDoc([a]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    const mirror = createDocumentMirror(store, 'p1', callbacks);
+    const updated: CanvasDocumentContractV2 = { ...doc, layers: [{ ...a, opacity: 0.5 }] };
+
+    store.replaceStateSilently({ projects: [{ canvas: { ...canvas, document: updated }, id: 'p1' }] });
+    expect(mirror.getDocument()).toBe(doc);
+
+    mirror.refresh();
+
+    expect(mirror.getDocument()).toBe(updated);
+    expect(callbacks.onLayersChanged).toHaveBeenCalledWith(['a'], []);
+  });
+
+  it('reports exactly the edited layer id when one layer changes by reference', () => {
+    const a = rasterLayer('a');
+    const b = rasterLayer('b');
+    const doc = makeDoc([a, b]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // Replace only layer `a` (new object), keep `b` identity. A prop-only edit
+    // (like the reducer's `updateCanvasLayer`) keeps the `source` reference, so
+    // the id is reported as changed but NOT source-changed.
+    const nextDoc: CanvasDocumentContractV2 = { ...doc, layers: [{ ...a, opacity: 0.5 }, b] };
+    store.setState({ projects: [{ canvas: { ...canvas, document: nextDoc }, id: 'p1' }] });
+
+    expect(callbacks.onLayersChanged).toHaveBeenCalledTimes(1);
+    expect(callbacks.onLayersChanged).toHaveBeenCalledWith(['a'], []);
+    expect(callbacks.onDocumentReplaced).not.toHaveBeenCalled();
+    expect(callbacks.onBboxChanged).not.toHaveBeenCalled();
+  });
+
+  it('reports a prop-only edit as changed but not source-changed, and a source swap as both', () => {
+    const a = rasterLayer('a');
+    const doc = makeDoc([a]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // Prop-only edit (opacity): spreading the prior layer preserves its `source`
+    // reference exactly as the reducer does, so the engine must NOT re-rasterize
+    // (which would clear an unflushed paint layer).
+    const opacityEdit: CanvasDocumentContractV2 = { ...doc, layers: [{ ...a, opacity: 0.5 }] };
+    store.setState({ projects: [{ canvas: { ...canvas, document: opacityEdit }, id: 'p1' }] });
+    expect(callbacks.onLayersChanged).toHaveBeenLastCalledWith(['a'], []);
+
+    // Genuine source swap (new `source` object): reported as source-changed.
+    const swapped = store.getState().projects[0]!.canvas.document.layers[0] as CanvasRasterLayerContractV2;
+    const sourceSwap: CanvasDocumentContractV2 = {
+      ...doc,
+      layers: [{ ...swapped, source: { image: { height: 10, imageName: 'a-v2', width: 10 }, type: 'image' } }],
+    };
+    store.setState({ projects: [{ canvas: { ...canvas, document: sourceSwap }, id: 'p1' }] });
+    expect(callbacks.onLayersChanged).toHaveBeenLastCalledWith(['a'], ['a']);
+  });
+
+  it('for a mask: a fill-only change is NOT source-changed, a bitmap swap IS (protects unflushed strokes)', () => {
+    const mask: CanvasInpaintMaskLayerContract = {
+      blendMode: 'normal',
+      id: 'm',
+      isEnabled: true,
+      isLocked: false,
+      mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+      name: 'm',
+      opacity: 1,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'inpaint_mask',
+    };
+    const doc = makeDoc([mask]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // A fill-only change (new `mask` object, same `bitmap` ref): reported as
+    // changed but NOT source-changed — invalidating would clear unflushed strokes.
+    const fillEdit: CanvasDocumentContractV2 = {
+      ...doc,
+      layers: [{ ...mask, mask: { bitmap: null, fill: { color: '#00ff00', style: 'grid' } } }],
+    };
+    store.setState({ projects: [{ canvas: { ...canvas, document: fillEdit }, id: 'p1' }] });
+    expect(callbacks.onLayersChanged).toHaveBeenLastCalledWith(['m'], []);
+
+    // A bitmap swap (persistence round-trip / undo): reported as source-changed.
+    const current = store.getState().projects[0]!.canvas.document.layers[0] as CanvasInpaintMaskLayerContract;
+    const bitmapSwap: CanvasDocumentContractV2 = {
+      ...doc,
+      layers: [{ ...current, mask: { ...current.mask, bitmap: { height: 20, imageName: 'mask-v1', width: 30 } } }],
+    };
+    store.setState({ projects: [{ canvas: { ...canvas, document: bitmapSwap }, id: 'p1' }] });
+    expect(callbacks.onLayersChanged).toHaveBeenLastCalledWith(['m'], ['m']);
+  });
+
+  it('reports added and removed layer ids', () => {
+    const a = rasterLayer('a');
+    const doc = makeDoc([a]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    const b = rasterLayer('b');
+    // Added layers are reported as source-changed (no prior cache to keep).
+    store.setState({ projects: [{ canvas: { ...canvas, document: { ...doc, layers: [b, a] } }, id: 'p1' }] });
+    expect(callbacks.onLayersChanged).toHaveBeenLastCalledWith(['b'], ['b']);
+
+    // A removal is a change but not a source change (the id has no incoming source).
+    store.setState({ projects: [{ canvas: { ...canvas, document: { ...doc, layers: [b] } }, id: 'p1' }] });
+    expect(callbacks.onLayersChanged).toHaveBeenLastCalledWith(['a'], []);
+  });
+
+  it('fires onLayerOrderChanged exactly once on a pure reorder, with no layer ids reported', () => {
+    const a = rasterLayer('a');
+    const b = rasterLayer('b');
+    const doc = makeDoc([a, b]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // New array reference, same element references, swapped order.
+    store.setState({ projects: [{ canvas: { ...canvas, document: { ...doc, layers: [b, a] } }, id: 'p1' }] });
+
+    expect(callbacks.onLayerOrderChanged).toHaveBeenCalledTimes(1);
+    expect(callbacks.onLayersChanged).not.toHaveBeenCalled();
+    expect(callbacks.onDocumentReplaced).not.toHaveBeenCalled();
+    expect(callbacks.onBboxChanged).not.toHaveBeenCalled();
+  });
+
+  it('does not fire onLayerOrderChanged when the layers array is replaced with an identical order', () => {
+    const a = rasterLayer('a');
+    const b = rasterLayer('b');
+    const doc = makeDoc([a, b]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // New array reference, same element references, same order: a true no-op churn.
+    store.setState({ projects: [{ canvas: { ...canvas, document: { ...doc, layers: [a, b] } }, id: 'p1' }] });
+
+    expect(callbacks.onLayerOrderChanged).not.toHaveBeenCalled();
+    expect(callbacks.onLayersChanged).not.toHaveBeenCalled();
+  });
+
+  it('fires onDocumentReplaced when dimensions change', () => {
+    const doc = makeDoc([rasterLayer('a')]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    store.setState({
+      projects: [{ canvas: { ...canvas, document: { ...doc, width: 200 } }, id: 'p1' }],
+    });
+    expect(callbacks.onDocumentReplaced).toHaveBeenCalledTimes(1);
+    expect(callbacks.onLayersChanged).not.toHaveBeenCalled();
+  });
+
+  it('fires onDocumentReplaced when documentRevision changes, even with identical dims and layer ids', () => {
+    const doc = makeDoc([rasterLayer('a')]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // A same-dims snapshot restore: structuredClone reuses layer ids and keeps
+    // width/height/background, so only the revision bump signals the swap.
+    const restored = structuredClone(doc);
+    store.setState({ projects: [{ canvas: makeCanvas(restored, 1), id: 'p1' }] });
+
+    expect(callbacks.onDocumentReplaced).toHaveBeenCalledTimes(1);
+    expect(callbacks.onLayersChanged).not.toHaveBeenCalled();
+    expect(callbacks.onLayerOrderChanged).not.toHaveBeenCalled();
+  });
+
+  it('does not fire onDocumentReplaced for an ordinary layer edit at an unchanged revision', () => {
+    const a = rasterLayer('a');
+    const doc = makeDoc([a]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    const nextDoc: CanvasDocumentContractV2 = { ...doc, layers: [{ ...a, opacity: 0.5 }] };
+    store.setState({ projects: [{ canvas: { ...canvas, document: nextDoc }, id: 'p1' }] });
+
+    expect(callbacks.onDocumentReplaced).not.toHaveBeenCalled();
+    expect(callbacks.onLayersChanged).toHaveBeenCalledWith(['a'], []);
+  });
+
+  it('fires onBboxChanged when only the bbox moves', () => {
+    const layers = [rasterLayer('a')];
+    const doc = makeDoc(layers);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // Same layers array identity, new bbox.
+    store.setState({
+      projects: [
+        { canvas: { ...canvas, document: { ...doc, bbox: { height: 100, width: 100, x: 10, y: 10 } } }, id: 'p1' },
+      ],
+    });
+    expect(callbacks.onBboxChanged).toHaveBeenCalledTimes(1);
+    expect(callbacks.onLayersChanged).not.toHaveBeenCalled();
+    expect(callbacks.onDocumentReplaced).not.toHaveBeenCalled();
+  });
+
+  it('fires onStagingChanged when the staging area reference changes', () => {
+    const doc = makeDoc([rasterLayer('a')]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    store.setState({ projects: [{ canvas: { ...canvas, stagingArea: makeStaging() }, id: 'p1' }] });
+    expect(callbacks.onStagingChanged).toHaveBeenCalledTimes(1);
+    expect(callbacks.onDocumentReplaced).not.toHaveBeenCalled();
+  });
+
+  it('is silent when an unrelated project changes (identity short-circuit)', () => {
+    const docA = makeDoc([rasterLayer('a')]);
+    const canvasA = makeCanvas(docA);
+    const docB = makeDoc([rasterLayer('z')]);
+    const canvasB = makeCanvas(docB);
+    const store = createFakeStore([
+      { canvas: canvasA, id: 'p1' },
+      { canvas: canvasB, id: 'p2' },
+    ]);
+    const callbacks = spyCallbacks();
+    createDocumentMirror(store, 'p1', callbacks);
+
+    // Mutate only p2; p1's canvas keeps its identity.
+    store.setState({
+      projects: [
+        { canvas: canvasA, id: 'p1' },
+        { canvas: makeCanvas(makeDoc([rasterLayer('z', { opacity: 0.2 })])), id: 'p2' },
+      ],
+    });
+    expect(callbacks.onLayersChanged).not.toHaveBeenCalled();
+    expect(callbacks.onDocumentReplaced).not.toHaveBeenCalled();
+    expect(callbacks.onBboxChanged).not.toHaveBeenCalled();
+    expect(callbacks.onStagingChanged).not.toHaveBeenCalled();
+  });
+
+  it('reports null and stays no-op safe when the project is deleted', () => {
+    const doc = makeDoc([rasterLayer('a')]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    const mirror = createDocumentMirror(store, 'p1', callbacks);
+
+    store.setState({ projects: [] });
+    expect(callbacks.onDocumentReplaced).toHaveBeenCalledTimes(1);
+    expect(mirror.getDocument()).toBeNull();
+
+    // Further unrelated churn: no additional callbacks.
+    store.setState({ projects: [] });
+    expect(callbacks.onDocumentReplaced).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops observing after dispose', () => {
+    const doc = makeDoc([rasterLayer('a')]);
+    const canvas = makeCanvas(doc);
+    const store = createFakeStore([{ canvas, id: 'p1' }]);
+    const callbacks = spyCallbacks();
+    const mirror = createDocumentMirror(store, 'p1', callbacks);
+
+    mirror.dispose();
+    store.setState({ projects: [{ canvas: makeCanvas(makeDoc([rasterLayer('a', { opacity: 0.1 })])), id: 'p1' }] });
+    expect(callbacks.onLayersChanged).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/documentMirror.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/documentMirror.ts
new file mode 100644
index 00000000000..238d369df34
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/documentMirror.ts
@@ -0,0 +1,240 @@
+/**
+ * The document mirror: the one-way bridge from the reducer-owned canvas
+ * document into the engine.
+ *
+ * The reducer owns the document; the engine only reads it. External changes
+ * (layer edits, undo/redo, staging accept, project switch) arrive via a plain
+ * `store.subscribe`, and the mirror translates a new state into the narrowest
+ * possible set of callbacks by diffing against the last-seen references:
+ *
+ * - document object identical → nothing happened (fast path; this is what makes
+ *   unrelated-project changes free, since the reducer preserves identity).
+ * - `documentRevision` changed → `onDocumentReplaced` (a full invalidate). This
+ *   is bumped by the reducer on wholesale document swaps (snapshot restore,
+ *   `replaceCanvasDocument`) that reuse the same dimensions and layer ids, which
+ *   a reference/dimension diff alone cannot tell apart from an ordinary edit.
+ * - dimensions / background changed, or the document appeared/disappeared →
+ *   `onDocumentReplaced` (a full invalidate).
+ * - otherwise diff the layer array element-wise by reference (id-keyed) →
+ *   `onLayersChanged(changedIds, sourceChangedIds)`. The second argument is the
+ *   subset of ids whose *rasterization source* reference changed (an image/paint
+ *   swap, or a newly added layer) — as opposed to a prop/transform-only edit
+ *   (opacity, blend, lock, visibility, rename, nudge) that replaces the layer
+ *   object but keeps its `source`/`mask` reference. The engine invalidates a
+ *   layer's raster cache ONLY for a source change: re-rasterizing on a prop edit
+ *   is wasteful for image layers and destructive for an unflushed paint layer
+ *   (a `bitmap: null` source rasterizes to a cleared surface, wiping cached
+ *   strokes that have not been persisted yet).
+ * - layers array reference changed but every id kept the same element
+ *   reference, just in a different order (a pure reorder) →
+ *   `onLayerOrderChanged` (recomposite only; nothing to re-rasterize).
+ * - bbox value changed → `onBboxChanged`.
+ * - stagingArea reference changed → `onStagingChanged`.
+ *
+ * A missing/deleted project is a no-op safe: the mirror simply reports `null`.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { CanvasDocumentContractV2, CanvasStagingAreaContractV2, CanvasStateContractV2 } from '@workbench/types';
+
+/** The minimal store shape the mirror depends on (a superset of `WorkbenchStore`). */
+export interface DocumentMirrorStore {
+  getCanvasState?(): CanvasStateContractV2 | null;
+  getState?(): { projects: readonly { id: string; canvas: CanvasStateContractV2 }[] };
+  subscribe(listener: () => void): () => void;
+}
+
+/** Callbacks fired when the mirrored document changes. */
+export interface DocumentMirrorCallbacks {
+  /**
+   * One or more layers were added, removed, or replaced (the `changed` ids).
+   * `sourceChanged` is the subset whose rasterization source (`source` for
+   * raster/control layers, `mask` for guidance/mask layers) reference changed,
+   * plus any newly added layer — i.e. the layers whose cached pixels are now
+   * stale. A prop/transform-only edit reports the id in `changed` but NOT in
+   * `sourceChanged`, so the engine keeps (rather than clears) its raster cache.
+   */
+  onLayersChanged(changed: string[], sourceChanged: string[]): void;
+  /**
+   * The layers array was reordered (a new array reference, same element
+   * references, different sequence) — recomposite the document with the new
+   * z-order, but nothing needs re-rasterizing.
+   */
+  onLayerOrderChanged(): void;
+  /** The document was replaced wholesale (dims/background change, appear/disappear) — full invalidate. */
+  onDocumentReplaced(): void;
+  /** The generation bounding box changed. */
+  onBboxChanged(): void;
+  /** The staging area changed. */
+  onStagingChanged(): void;
+}
+
+/** The imperative mirror handle. */
+export interface DocumentMirror {
+  /** The current mirrored document, or `null` if the project is gone. */
+  getDocument(): CanvasDocumentContractV2 | null;
+  /** Synchronously reconciles from store state when ordinary notification was interrupted. */
+  refresh(): void;
+  /** Removes the store subscription. */
+  dispose(): void;
+}
+
+type Bbox = CanvasDocumentContractV2['bbox'];
+
+const bboxEqual = (a: Bbox, b: Bbox): boolean =>
+  a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+
+/**
+ * The reference whose change requires re-rasterizing a layer's cache: the
+ * `source` for raster/control layers, the mask's `bitmap` for guidance/mask
+ * layers. The reducer preserves this reference across a prop/transform-only edit
+ * (it spreads `...layer`), so comparing it distinguishes a genuine source swap
+ * from an opacity/blend/lock/visibility/rename/nudge tweak.
+ *
+ * For masks the reference is the mask BITMAP, not the whole `mask` object: the
+ * cache holds only the alpha stencil, so a fill-only change (colour/style/noise/
+ * denoise-limit) must NOT invalidate it. Invalidating on a fill tweak would
+ * re-rasterize from `mask.bitmap` — clearing unflushed brush strokes that live
+ * only in the cache — while the compositor already reads the fresh fill from the
+ * mirror at draw time. A genuine bitmap swap (persistence round-trip, undo,
+ * import) still changes this reference and re-rasterizes (guarded by self-echo).
+ */
+const rasterSourceRef = (layer: CanvasDocumentContractV2['layers'][number]): unknown =>
+  layer.type === 'raster' || layer.type === 'control' ? layer.source : layer.mask.bitmap;
+
+/**
+ * Diffs two layer arrays by object identity, keyed by layer id. Returns the ids
+ * of layers that were added, removed, or replaced (`changed`), and the subset
+ * whose rasterization source reference changed or that were newly added
+ * (`sourceChanged`) — the layers whose cached pixels are now stale.
+ */
+const diffLayers = (
+  prev: readonly CanvasDocumentContractV2['layers'][number][],
+  next: readonly CanvasDocumentContractV2['layers'][number][]
+): { changed: string[]; sourceChanged: string[] } => {
+  const prevById = new Map(prev.map((layer) => [layer.id, layer]));
+  const nextById = new Map(next.map((layer) => [layer.id, layer]));
+  const changed = new Set<string>();
+  const sourceChanged = new Set<string>();
+
+  for (const layer of next) {
+    const before = prevById.get(layer.id);
+    if (!before) {
+      // Added: no prior cache, so its source is new by definition.
+      changed.add(layer.id);
+      sourceChanged.add(layer.id);
+    } else if (before !== layer) {
+      changed.add(layer.id);
+      if (rasterSourceRef(before) !== rasterSourceRef(layer)) {
+        sourceChanged.add(layer.id);
+      }
+    }
+  }
+  for (const layer of prev) {
+    if (!nextById.has(layer.id)) {
+      // Removed: reported so the engine drops its cache. Not a source change.
+      changed.add(layer.id);
+    }
+  }
+  return { changed: [...changed], sourceChanged: [...sourceChanged] };
+};
+
+/**
+ * True when two layer arrays hold the same ids in a different sequence.
+ * Only meaningful to call once `diffLayers` has already confirmed no id was
+ * added, removed, or replaced by reference.
+ */
+const layerOrderChanged = (
+  prev: readonly CanvasDocumentContractV2['layers'][number][],
+  next: readonly CanvasDocumentContractV2['layers'][number][]
+): boolean => {
+  if (prev.length !== next.length) {
+    return true;
+  }
+  for (let i = 0; i < prev.length; i++) {
+    if (prev[i]?.id !== next[i]?.id) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * Creates a document mirror bound to `projectId`. Subscribes immediately and
+ * seeds the last-seen references from the current state (so no spurious
+ * callback fires on creation).
+ */
+export const createDocumentMirror = (
+  store: DocumentMirrorStore,
+  projectIdOrCallbacks: string | DocumentMirrorCallbacks,
+  maybeCallbacks?: DocumentMirrorCallbacks
+): DocumentMirror => {
+  const projectId = typeof projectIdOrCallbacks === 'string' ? projectIdOrCallbacks : null;
+  const callbacks = typeof projectIdOrCallbacks === 'string' ? maybeCallbacks : projectIdOrCallbacks;
+  if (!callbacks) {
+    throw new Error('DocumentMirror callbacks are required.');
+  }
+  const selectCanvas = (): CanvasStateContractV2 | null =>
+    store.getCanvasState?.() ??
+    (projectId === null
+      ? null
+      : (store.getState?.().projects.find((project) => project.id === projectId)?.canvas ?? null));
+
+  let lastDoc: CanvasDocumentContractV2 | null = selectCanvas()?.document ?? null;
+  let lastRevision: number = selectCanvas()?.documentRevision ?? 0;
+  let lastStaging: CanvasStagingAreaContractV2 | null = selectCanvas()?.stagingArea ?? null;
+
+  const handleChange = (): void => {
+    const canvas = selectCanvas();
+    const doc = canvas?.document ?? null;
+    const revision = canvas?.documentRevision ?? 0;
+    const staging = canvas?.stagingArea ?? null;
+
+    if (doc !== lastDoc) {
+      const prevDoc = lastDoc;
+      const prevRevision = lastRevision;
+      lastDoc = doc;
+      lastRevision = revision;
+
+      if (!prevDoc || !doc) {
+        // Document appeared or disappeared: treat as a full replacement.
+        callbacks.onDocumentReplaced();
+      } else if (
+        revision !== prevRevision ||
+        prevDoc.width !== doc.width ||
+        prevDoc.height !== doc.height ||
+        prevDoc.background !== doc.background
+      ) {
+        // A wholesale swap (revision bump) or a dims/background change: the pixel
+        // history no longer describes the live document.
+        callbacks.onDocumentReplaced();
+      } else {
+        if (prevDoc.layers !== doc.layers) {
+          const { changed, sourceChanged } = diffLayers(prevDoc.layers, doc.layers);
+          if (changed.length > 0) {
+            callbacks.onLayersChanged(changed, sourceChanged);
+          } else if (layerOrderChanged(prevDoc.layers, doc.layers)) {
+            callbacks.onLayerOrderChanged();
+          }
+        }
+        if (!bboxEqual(prevDoc.bbox, doc.bbox)) {
+          callbacks.onBboxChanged();
+        }
+      }
+    }
+
+    if (staging !== lastStaging) {
+      lastStaging = staging;
+      callbacks.onStagingChanged();
+    }
+  };
+
+  const unsubscribe = store.subscribe(handleChange);
+
+  return {
+    dispose: unsubscribe,
+    getDocument: () => lastDoc,
+    refresh: handleChange,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/imageUpload.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/imageUpload.ts
new file mode 100644
index 00000000000..fc043be4731
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/imageUpload.ts
@@ -0,0 +1,6 @@
+/** Dependency-neutral result returned after persisting or staging canvas pixels. */
+export interface CanvasImageUploadResult {
+  imageName: string;
+  width: number;
+  height: number;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/layerFactories.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/layerFactories.ts
new file mode 100644
index 00000000000..92d9ee4a173
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/layerFactories.ts
@@ -0,0 +1,106 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+import type {
+  CanvasControlLayerContract,
+  CanvasImageRef,
+  CanvasInpaintMaskLayerContract,
+  CanvasMaskFillContract,
+  CanvasRegionalGuidanceLayerContract,
+} from '@workbench/types';
+
+import { CONTROL_ADAPTER_DEFAULTS } from '@workbench/controlAdapters';
+
+export const DEFAULT_INPAINT_MASK_FILL = { color: '#e07575', style: 'diagonal' } as const;
+export const REGIONAL_GUIDANCE_FILL_COLORS: readonly string[] = [
+  '#799ddb',
+  '#83d683',
+  '#fae150',
+  '#dc9065',
+  '#e07575',
+  '#d58bca',
+  '#a178d6',
+];
+
+const nextNumberedName = (prefix: string, existingNames: readonly string[]): string => {
+  const expression = new RegExp(`^${prefix} (\\d+)$`);
+  const used = new Set(
+    existingNames
+      .map((name) => Number(expression.exec(name.trim())?.[1]))
+      .filter((number) => Number.isInteger(number) && number > 0)
+  );
+  let number = 1;
+  while (used.has(number)) {
+    number += 1;
+  }
+  return `${prefix} ${String(number)}`;
+};
+
+export const nextInpaintMaskName = (names: readonly string[]): string => nextNumberedName('Inpaint Mask', names);
+export const nextControlLayerName = (names: readonly string[]): string => nextNumberedName('Control Layer', names);
+export const nextRegionalGuidanceName = (names: readonly string[]): string =>
+  nextNumberedName('Regional Guidance', names);
+export const nextRegionalGuidanceFillColor = (count: number): string =>
+  REGIONAL_GUIDANCE_FILL_COLORS[(count + 1) % REGIONAL_GUIDANCE_FILL_COLORS.length] ??
+  REGIONAL_GUIDANCE_FILL_COLORS[0]!;
+
+export interface CreateMaskLayerFromImageInput {
+  image: CanvasImageRef;
+  rect: Rect;
+  id: string;
+  name: string;
+  fill: CanvasMaskFillContract;
+}
+
+export const createInpaintMaskFromImage = (input: CreateMaskLayerFromImageInput): CanvasInpaintMaskLayerContract => ({
+  blendMode: 'normal',
+  id: input.id,
+  isEnabled: true,
+  isLocked: false,
+  mask: {
+    bitmap: { ...input.image },
+    fill: { ...input.fill },
+    offset: { x: input.rect.x, y: input.rect.y },
+  },
+  name: input.name,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+export const createRegionalGuidanceFromImage = (
+  input: CreateMaskLayerFromImageInput
+): CanvasRegionalGuidanceLayerContract => ({
+  autoNegative: false,
+  blendMode: 'normal',
+  id: input.id,
+  isEnabled: true,
+  isLocked: false,
+  mask: {
+    bitmap: { ...input.image },
+    fill: { ...input.fill },
+    offset: { x: input.rect.x, y: input.rect.y },
+  },
+  name: input.name,
+  negativePrompt: null,
+  opacity: 0.5,
+  positivePrompt: null,
+  referenceImages: [],
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'regional_guidance',
+});
+
+export const createControlLayer = (name: string, id: string, base?: string | null): CanvasControlLayerContract => {
+  const adapter = base === 'z-image' ? CONTROL_ADAPTER_DEFAULTS.z_image_control : CONTROL_ADAPTER_DEFAULTS.controlnet;
+  return {
+    adapter: { ...adapter, beginEndStepPct: [...adapter.beginEndStepPct] },
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name,
+    opacity: 1,
+    source: { bitmap: null, type: 'paint' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'control',
+    withTransparencyEffect: true,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeDown.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeDown.test.ts
new file mode 100644
index 00000000000..176a28ade32
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeDown.test.ts
@@ -0,0 +1,53 @@
+import type { CanvasLayerBaseContract } from '@workbench/types';
+
+import { fromTRS, multiply } from '@workbench/canvas-engine/math/mat2d';
+import { describe, expect, it } from 'vitest';
+
+import { mergeDownMatrix } from './mergeDown';
+
+type Transform = CanvasLayerBaseContract['transform'];
+
+const transform = (patch: Partial<Transform> = {}): Transform => ({
+  rotation: 0,
+  scaleX: 1,
+  scaleY: 1,
+  x: 0,
+  y: 0,
+  ...patch,
+});
+
+const toMat = (t: Transform) => fromTRS({ x: t.x, y: t.y }, t.rotation, t.scaleX, t.scaleY);
+
+const closeTo = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+
+describe('mergeDownMatrix', () => {
+  it('is the identity when both transforms are identity', () => {
+    expect(mergeDownMatrix(transform(), transform())).toEqual({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+  });
+
+  it('translates the upper cache into the below layer local space (offset below cancels)', () => {
+    // Below sits at (10, 20); the upper layer sits at the document origin. In
+    // below-local space the origin is therefore at (-10, -20).
+    const m = mergeDownMatrix(transform({ x: 10, y: 20 }), transform());
+    expect(m).not.toBeNull();
+    expect(m!.e).toBeCloseTo(-10);
+    expect(m!.f).toBeCloseTo(-20);
+  });
+
+  it('satisfies below · M = above, so merged pixels land at their original document position', () => {
+    const below = transform({ scaleX: 2, scaleY: 2, x: 5, y: 7 });
+    const above = transform({ scaleX: 3, x: 40, y: 12 });
+    const m = mergeDownMatrix(below, above);
+    expect(m).not.toBeNull();
+
+    const recomposed = multiply(toMat(below), m!);
+    const expected = toMat(above);
+    for (const key of ['a', 'b', 'c', 'd', 'e', 'f'] as const) {
+      expect(closeTo(recomposed[key], expected[key])).toBe(true);
+    }
+  });
+
+  it('returns null when the below transform is non-invertible (zero scale)', () => {
+    expect(mergeDownMatrix(transform({ scaleX: 0 }), transform())).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeDown.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeDown.ts
new file mode 100644
index 00000000000..03d5f370a46
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeDown.ts
@@ -0,0 +1,38 @@
+/**
+ * Pure transform math for merging one layer down into the layer below it.
+ *
+ * "Merge down" bakes the upper layer's pixels into the lower layer while the
+ * reducer keeps the lower layer's transform verbatim (see
+ * `mergeCanvasLayersDown` — it never touches pixels). So the engine must draw
+ * the upper layer's cache into the lower layer's *local* space: upper-local →
+ * document (via the upper transform) → lower-local (via the inverse of the
+ * lower transform). Composing those gives the matrix returned here, which the
+ * engine feeds to `ctx.setTransform` when blitting the upper cache onto the
+ * merged surface. When the merged (lower) layer is later composited with its
+ * unchanged transform, the upper content lands back at its original document
+ * position: `lowerTransform · (lowerTransform⁻¹ · upperTransform) = upperTransform`.
+ *
+ * Zero React, zero DOM, zero import-time side effects.
+ */
+
+import type { Mat2d } from '@workbench/canvas-engine/types';
+import type { CanvasLayerBaseContract } from '@workbench/types';
+
+import { fromTRS, invert, multiply } from '@workbench/canvas-engine/math/mat2d';
+
+type LayerTransform = CanvasLayerBaseContract['transform'];
+
+const transformToMat = (t: LayerTransform): Mat2d => fromTRS({ x: t.x, y: t.y }, t.rotation, t.scaleX, t.scaleY);
+
+/**
+ * The matrix that maps the upper layer's local (cache) space into the lower
+ * layer's local space: `inverse(lower) · upper`. Returns `null` when the lower
+ * transform is singular (zero scale) and cannot be inverted.
+ */
+export const mergeDownMatrix = (lowerTransform: LayerTransform, upperTransform: LayerTransform): Mat2d | null => {
+  const lowerInverse = invert(transformToMat(lowerTransform));
+  if (!lowerInverse) {
+    return null;
+  }
+  return multiply(lowerInverse, transformToMat(upperTransform));
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeVisible.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeVisible.test.ts
new file mode 100644
index 00000000000..1e8ac0ea47f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeVisible.test.ts
@@ -0,0 +1,80 @@
+import type {
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { canMergeVisibleRasters, getMergeVisibleRasterLayers } from './mergeVisible';
+
+const raster = (id: string, overrides: Partial<CanvasRasterLayerContractV2> = {}): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+  ...overrides,
+});
+
+const mask = (id: string): CanvasInpaintMaskLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+const gradientRaster = (id: string): CanvasLayerContract =>
+  raster(id, {
+    source: {
+      angle: 0,
+      height: 10,
+      kind: 'linear',
+      stops: [
+        { color: '#000', offset: 0 },
+        { color: '#fff', offset: 1 },
+      ],
+      type: 'gradient',
+      width: 10,
+    },
+  });
+
+describe('getMergeVisibleRasterLayers', () => {
+  const hasContent = (id: string): boolean => id !== 'empty';
+
+  it('returns every visible raster with content in stack order', () => {
+    const layers = [
+      raster('top'),
+      mask('mask'),
+      raster('hidden', { isEnabled: false }),
+      raster('locked', { isLocked: true }),
+      gradientRaster('gradient'),
+      raster('empty'),
+      raster('bottom'),
+    ];
+
+    expect(getMergeVisibleRasterLayers(layers, hasContent).map((layer) => layer.id)).toEqual([
+      'top',
+      'locked',
+      'gradient',
+      'bottom',
+    ]);
+    expect(canMergeVisibleRasters(layers, hasContent)).toBe(true);
+  });
+
+  it('requires at least two visible raster layers with content', () => {
+    expect(canMergeVisibleRasters([raster('one')], hasContent)).toBe(false);
+    expect(canMergeVisibleRasters([raster('one'), raster('hidden', { isEnabled: false })], hasContent)).toBe(false);
+    expect(canMergeVisibleRasters([raster('one'), raster('empty')], hasContent)).toBe(false);
+    expect(canMergeVisibleRasters([], hasContent)).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeVisible.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeVisible.ts
new file mode 100644
index 00000000000..5510635be35
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/mergeVisible.ts
@@ -0,0 +1,24 @@
+/**
+ * Pure contributor selection for the raster group's "merge visible" action.
+ *
+ * Legacy merge-visible composites every visible raster entity with content into
+ * a new raster layer. Source kind and lock state do not affect participation:
+ * locks prevent editing a source, not reading its rendered pixels.
+ */
+
+import type { CanvasLayerContract } from '@workbench/types';
+
+export type HasMergeVisibleContent = (layerId: string) => boolean;
+
+/** Returns eligible contributors in document order (top-most first). */
+export const getMergeVisibleRasterLayers = (
+  layers: readonly CanvasLayerContract[],
+  hasContent: HasMergeVisibleContent
+): CanvasLayerContract[] =>
+  layers.filter((layer) => layer.type === 'raster' && layer.isEnabled && hasContent(layer.id));
+
+/** Whether the raster group's merge-visible action has at least two contributors. */
+export const canMergeVisibleRasters = (
+  layers: readonly CanvasLayerContract[],
+  hasContent: HasMergeVisibleContent
+): boolean => getMergeVisibleRasterLayers(layers, hasContent).length >= 2;
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/sources.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/sources.test.ts
new file mode 100644
index 00000000000..466fbb62711
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/sources.test.ts
@@ -0,0 +1,129 @@
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasLayerSourceContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getSourceBounds,
+  getSourceContentRect,
+  getSourcePixelSize,
+  isMaskLayer,
+  isRenderableLayer,
+  maskAsPaintSource,
+  renderableSourceOf,
+} from './sources';
+
+const doc = { height: 200, width: 300 } as CanvasDocumentContractV2;
+
+const inpaintMask = (
+  bitmap: { imageName: string; width: number; height: number } | null,
+  offset?: { x: number; y: number }
+): CanvasLayerContract =>
+  ({
+    blendMode: 'normal',
+    id: 'm1',
+    isEnabled: true,
+    isLocked: false,
+    mask: { bitmap, fill: { color: '#e07575', style: 'diagonal' }, ...(offset ? { offset } : {}) },
+    name: 'M',
+    opacity: 1,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'inpaint_mask',
+  }) as CanvasLayerContract;
+
+describe('mask layers as paint-like sources', () => {
+  it('isMaskLayer / renderableSourceOf treat a mask as an alpha paint source', () => {
+    const layer = inpaintMask({ height: 30, imageName: 'mask', width: 40 }, { x: 5, y: 6 });
+    expect(isMaskLayer(layer)).toBe(true);
+    expect(maskAsPaintSource(layer)).toEqual({
+      bitmap: { height: 30, imageName: 'mask', width: 40 },
+      offset: { x: 5, y: 6 },
+      type: 'paint',
+    });
+    expect(renderableSourceOf(layer)).toEqual(maskAsPaintSource(layer));
+  });
+
+  it('an enabled mask is renderable; content rect is the bitmap dims at its offset', () => {
+    const layer = inpaintMask({ height: 30, imageName: 'mask', width: 40 }, { x: 5, y: 6 });
+    expect(isRenderableLayer(layer)).toBe(true);
+    expect(getSourceContentRect(layer, doc)).toEqual({ height: 30, width: 40, x: 5, y: 6 });
+  });
+
+  it('an empty (bitmap-less) mask is renderable but has an empty content rect', () => {
+    const layer = inpaintMask(null);
+    expect(isRenderableLayer(layer)).toBe(true);
+    expect(getSourceContentRect(layer, doc)).toEqual({ height: 0, width: 0, x: 0, y: 0 });
+  });
+
+  it('a disabled mask is not renderable', () => {
+    const layer = inpaintMask({ height: 30, imageName: 'mask', width: 40 });
+    (layer as { isEnabled: boolean }).isEnabled = false;
+    expect(isRenderableLayer(layer)).toBe(false);
+  });
+});
+
+const rasterLayer = (source: CanvasLayerSourceContract, transformOver = {}): CanvasLayerContract =>
+  ({
+    blendMode: 'normal',
+    id: 'l1',
+    isEnabled: true,
+    isLocked: false,
+    name: 'L',
+    opacity: 1,
+    source,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0, ...transformOver },
+    type: 'raster',
+  }) as CanvasLayerContract;
+
+const shape: CanvasLayerSourceContract = {
+  fill: '#000',
+  height: 40,
+  kind: 'rect',
+  stroke: null,
+  strokeWidth: 0,
+  type: 'shape',
+  width: 60,
+};
+
+const gradient: CanvasLayerSourceContract = {
+  angle: 0,
+  kind: 'linear',
+  stops: [{ color: '#000', offset: 0 }],
+  type: 'gradient',
+};
+
+describe('isRenderableLayer — parametric sources', () => {
+  it('renders rect/ellipse shapes and gradients', () => {
+    expect(isRenderableLayer(rasterLayer(shape))).toBe(true);
+    expect(isRenderableLayer(rasterLayer({ ...shape, kind: 'ellipse' }))).toBe(true);
+    expect(isRenderableLayer(rasterLayer(gradient))).toBe(true);
+  });
+
+  it('does not render a deferred polygon shape', () => {
+    expect(isRenderableLayer(rasterLayer({ ...shape, kind: 'polygon' }))).toBe(false);
+  });
+
+  it('does not render a disabled layer', () => {
+    expect(isRenderableLayer({ ...rasterLayer(shape), isEnabled: false })).toBe(false);
+  });
+});
+
+describe('getSourcePixelSize — parametric sources', () => {
+  it('sizes a shape to its own extent', () => {
+    expect(getSourcePixelSize(rasterLayer(shape), doc)).toEqual({ height: 40, width: 60 });
+  });
+
+  it('sizes a gradient to the document', () => {
+    expect(getSourcePixelSize(rasterLayer(gradient), doc)).toEqual({ height: 200, width: 300 });
+  });
+});
+
+describe('getSourceBounds — parametric sources', () => {
+  it('scales+offsets a shape by its transform', () => {
+    const bounds = getSourceBounds(rasterLayer(shape, { scaleX: 2, scaleY: 3, x: 10, y: 20 }), doc);
+    expect(bounds).toEqual({ height: 120, width: 120, x: 10, y: 20 });
+  });
+
+  it('returns the whole document for a gradient', () => {
+    expect(getSourceBounds(rasterLayer(gradient), doc)).toEqual({ height: 200, width: 300, x: 0, y: 0 });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/document/sources.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/sources.ts
new file mode 100644
index 00000000000..b77fdd1d966
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/document/sources.ts
@@ -0,0 +1,208 @@
+/**
+ * Small pure helpers over canvas layers and their sources, shared by the engine
+ * (cache sizing, culling, fit-to-content) and the rasterizers.
+ *
+ * `getSourceBounds` returns a layer's axis-aligned bounds in **document space**
+ * (used for culling / fit-to-content), while `getSourcePixelSize` returns the
+ * **native** (unscaled) pixel dimensions of the layer's raster cache surface —
+ * the compositor applies the layer transform when drawing, so caches hold
+ * unscaled pixels. `isRenderableLayer` reports whether a layer can be
+ * rasterized today (enabled, with an image/paint source).
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasLayerSourceContract } from '@workbench/types';
+
+import { fromTRS } from '@workbench/canvas-engine/math/mat2d';
+import { transformBounds } from '@workbench/canvas-engine/math/rect';
+import { estimateTextExtent } from '@workbench/canvas-engine/render/rasterizers/textRasterizer';
+
+/** A layer type that carries a rasterizable `source` (raster or control). */
+type SourceLayer = Extract<CanvasLayerContract, { source: CanvasLayerSourceContract }>;
+
+/** A mask-bearing layer (inpaint mask / regional guidance); its `mask` holds an alpha bitmap. */
+type MaskLayer = Extract<CanvasLayerContract, { mask: unknown }>;
+
+/** True when a layer carries a `source` field (raster / control layers). */
+const hasSource = (layer: CanvasLayerContract): layer is SourceLayer =>
+  layer.type === 'raster' || layer.type === 'control';
+
+/** True when a layer carries a `mask` (inpaint mask / regional guidance). */
+export const isMaskLayer = (layer: CanvasLayerContract): layer is MaskLayer =>
+  layer.type === 'inpaint_mask' || layer.type === 'regional_guidance';
+
+/** The number of strict composite groups (see {@link layerGroupRank}). */
+export const LAYER_GROUP_COUNT = 4;
+
+/**
+ * The strict composite-group rank of a layer, ordered bottom→top: raster (0) <
+ * control (1) < regional guidance (2) < inpaint mask (3). Mirrors legacy
+ * `arrangeEntities` / `CanvasEntityRendererModule` and the layers panel's grouped
+ * sections, so a layer's global insertion index never lets it draw — or be
+ * hit-tested — out of group order (a raster created above a control layer still
+ * composites, and is grabbed, below it). The compositor draws groups in this
+ * order; the move/context-menu hit-test iterates them top→bottom, keeping the two
+ * in lockstep so the layer the user clicks is the layer they see on top.
+ */
+export const layerGroupRank = (layer: CanvasLayerContract): number => {
+  switch (layer.type) {
+    case 'control':
+      return 1;
+    case 'regional_guidance':
+      return 2;
+    case 'inpaint_mask':
+      return 3;
+    default:
+      // raster (and any future non-grouped renderable) composites at the bottom.
+      return 0;
+  }
+};
+
+/**
+ * A mask layer's alpha bitmap viewed as a `paint` source, so the whole paint
+ * pipeline (rasterize, content-sized cache, growth, stroke, persistence) can
+ * operate on masks unchanged: the mask stores an alpha stencil exactly like a
+ * paint bitmap; only the compositor differs (it colorizes the alpha with the
+ * layer's `fill` instead of blitting the RGBA directly). Returns `null` for a
+ * non-mask layer.
+ */
+export const maskAsPaintSource = (
+  layer: CanvasLayerContract
+): Extract<CanvasLayerSourceContract, { type: 'paint' }> | null =>
+  isMaskLayer(layer) ? { bitmap: layer.mask.bitmap, offset: layer.mask.offset, type: 'paint' } : null;
+
+/**
+ * A layer's rasterizable source: its own `source` for raster/control layers, or
+ * a synthetic `paint` view of a mask layer's alpha bitmap. `null` for layers
+ * with neither (there are none today). This is the single "what pixels does this
+ * layer hold" accessor the engine's rasterize / cache / persistence paths share.
+ */
+export const renderableSourceOf = (layer: CanvasLayerContract): CanvasLayerSourceContract | null => {
+  if (hasSource(layer)) {
+    return layer.source;
+  }
+  return maskAsPaintSource(layer);
+};
+
+/**
+ * True when a layer's source is one the engine can rasterize today: image,
+ * paint, gradient, text, or a rect/ellipse shape. A `polygon` shape has no
+ * rasterizer yet (deferred), so it is not renderable.
+ */
+export const isRenderableLayer = (layer: CanvasLayerContract): boolean => {
+  if (!layer.isEnabled) {
+    return false;
+  }
+  // Mask layers are renderable whenever enabled: an empty (bitmap-less) mask
+  // rasterizes to a zero-rect surface (skipped downstream, like empty paint).
+  if (isMaskLayer(layer)) {
+    return true;
+  }
+  if (!hasSource(layer)) {
+    return false;
+  }
+  const { source } = layer;
+  switch (source.type) {
+    case 'image':
+    case 'paint':
+    case 'gradient':
+    case 'text':
+      return true;
+    case 'shape':
+      return source.kind !== 'polygon';
+    default:
+      return false;
+  }
+};
+
+/**
+ * True when a layer carries pixels the engine can rasterize AND merge: an
+ * enabled, unlocked paint/image raster layer. Narrower than
+ * {@link isRenderableLayer} — masks, control layers, shapes, text, and gradient
+ * layers are all renderable but NOT mergeable. Locked matches the paint tool's
+ * rule (`isLocked || !isEnabled` refuses a paint target): merge writes pixels
+ * into the below layer and deletes the upper one, so it must refuse a locked
+ * layer on either side just as painting refuses a locked target. The layers
+ * panel's merge-down enablement (`canMergeLayerDown`) and the engine's
+ * `mergeLayerDown` guard both defer to this single predicate so the hotkey,
+ * context menu, and engine can never disagree about what is mergeable.
+ */
+export const isMergeableRasterLayer = (layer: CanvasLayerContract): boolean =>
+  layer.isEnabled &&
+  !layer.isLocked &&
+  layer.type === 'raster' &&
+  (layer.source.type === 'paint' || layer.source.type === 'image');
+
+/**
+ * A layer's content rectangle in its LOCAL (untransformed) coordinate space —
+ * the extent its raster cache surface covers, before the layer transform is
+ * applied. Every layer type is content-sized:
+ *
+ * - `image`: `[0, 0, w, h]` at the image's native pixels.
+ * - `shape` / `text`: `[0, 0, w, h]` at the source's own / estimated extent.
+ * - `gradient`: `[0, 0, width, height]` from the explicit extent, defaulting to
+ *   the document dims for legacy gradients that predate the extent field.
+ * - `paint`: the persisted bitmap's dims at its `offset` (legacy default `0, 0`),
+ *   or an EMPTY rect when the layer has no bitmap yet (a brand-new paint layer).
+ *
+ * Throws for layers without a rasterizable source, so callers fail loudly.
+ */
+export const getSourceContentRect = (layer: CanvasLayerContract, doc: CanvasDocumentContractV2): Rect => {
+  const source = renderableSourceOf(layer);
+  if (!source) {
+    throw new Error(`getSourceContentRect: layer type '${layer.type}' has no rasterizable source`);
+  }
+  switch (source.type) {
+    case 'image':
+      return { height: source.image.height, width: source.image.width, x: 0, y: 0 };
+    case 'shape':
+      return {
+        height: Math.max(1, Math.round(source.height)),
+        width: Math.max(1, Math.round(source.width)),
+        x: 0,
+        y: 0,
+      };
+    case 'text': {
+      const extent = estimateTextExtent(source);
+      return { height: extent.height, width: extent.width, x: 0, y: 0 };
+    }
+    case 'gradient': {
+      // Explicit extent when present; legacy gradients (no extent) were
+      // document-sized by construction, so default to the document dims.
+      const width = source.width ?? doc.width;
+      const height = source.height ?? doc.height;
+      return { height, width, x: 0, y: 0 };
+    }
+    case 'paint': {
+      if (!source.bitmap) {
+        // A brand-new / cleared paint layer holds no pixels: an empty rect.
+        return { height: 0, width: 0, x: 0, y: 0 };
+      }
+      const offset = source.offset ?? { x: 0, y: 0 };
+      return { height: source.bitmap.height, width: source.bitmap.width, x: offset.x, y: offset.y };
+    }
+  }
+};
+
+/**
+ * A layer's axis-aligned bounds in DOCUMENT space: its {@link getSourceContentRect}
+ * projected through the layer transform (rotation-aware). Used for culling and
+ * fit-to-content. Throws for layers without a rasterizable source.
+ */
+export const getSourceBounds = (layer: CanvasLayerContract, doc: CanvasDocumentContractV2): Rect => {
+  const contentRect = getSourceContentRect(layer, doc);
+  const { transform } = layer;
+  const matrix = fromTRS({ x: transform.x, y: transform.y }, transform.rotation, transform.scaleX, transform.scaleY);
+  return transformBounds(matrix, contentRect);
+};
+
+/** The native (unscaled) pixel size of a layer's raster cache surface. */
+export const getSourcePixelSize = (
+  layer: CanvasLayerContract,
+  doc: CanvasDocumentContractV2
+): { width: number; height: number } => {
+  const rect = getSourceContentRect(layer, doc);
+  return { height: rect.height, width: rect.width };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/editGate.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/editGate.test.ts
new file mode 100644
index 00000000000..8b1307fcc5a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/editGate.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+import { createCanvasEditGate } from './editGate';
+
+describe('createCanvasEditGate', () => {
+  it('grants one exclusive lease and makes release idempotently stale', () => {
+    const gate = createCanvasEditGate();
+    const lease = gate.tryAcquire({ kind: 'filter', layerId: 'a' });
+    expect(lease).not.toBeNull();
+    expect(gate.tryAcquire({ kind: 'select-object', layerId: 'b' })).toBeNull();
+    expect(lease!.isCurrent()).toBe(true);
+
+    lease!.release();
+    lease!.release();
+    expect(lease!.signal.aborted).toBe(true);
+    expect(lease!.isCurrent()).toBe(false);
+    expect(gate.tryAcquire({ kind: 'select-object', layerId: 'b' })).not.toBeNull();
+  });
+
+  it('invalidates leases on document replacement, project invalidation, cooldown, and disposal', () => {
+    const gate = createCanvasEditGate();
+    for (const invalidate of [gate.invalidateDocument, gate.invalidateProject]) {
+      const lease = gate.tryAcquire({ kind: 'test' });
+      expect(lease).not.toBeNull();
+      invalidate();
+      expect(lease!.signal.aborted).toBe(true);
+      expect(lease!.isCurrent()).toBe(false);
+    }
+
+    const coolingLease = gate.tryAcquire({ kind: 'cooling' })!;
+    gate.cooldown();
+    expect(coolingLease.isCurrent()).toBe(false);
+    expect(gate.tryAcquire({ kind: 'while-cooling' })).toBeNull();
+    gate.activate();
+
+    const disposedLease = gate.tryAcquire({ kind: 'disposed' })!;
+    gate.dispose();
+    expect(disposedLease.isCurrent()).toBe(false);
+    expect(gate.tryAcquire({ kind: 'after-dispose' })).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/editGate.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/editGate.ts
new file mode 100644
index 00000000000..96ca42bee1c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/editGate.ts
@@ -0,0 +1,91 @@
+export interface CanvasEditIdentity {
+  readonly kind: string;
+  readonly layerId?: string;
+}
+
+export interface CanvasEditLease {
+  readonly signal: AbortSignal;
+  isCurrent(): boolean;
+  release(): void;
+}
+
+export interface CanvasEditGate {
+  tryAcquire(identity: CanvasEditIdentity): CanvasEditLease | null;
+}
+
+export interface CanvasEditGateController extends CanvasEditGate {
+  activate(): void;
+  cooldown(): void;
+  invalidateDocument(): void;
+  invalidateProject(): void;
+  invalidateLayer(layerId: string): void;
+  dispose(): void;
+}
+
+interface ActiveLease {
+  readonly controller: AbortController;
+  readonly generation: number;
+  readonly identity: CanvasEditIdentity;
+}
+
+export const createCanvasEditGate = (): CanvasEditGateController => {
+  let active: ActiveLease | null = null;
+  let generation = 0;
+  let lifecycle: 'active' | 'cooling' | 'disposed' = 'active';
+
+  const invalidate = (): void => {
+    generation += 1;
+    const lease = active;
+    active = null;
+    lease?.controller.abort();
+  };
+
+  const tryAcquire = (_identity: CanvasEditIdentity): CanvasEditLease | null => {
+    if (lifecycle !== 'active' || active) {
+      return null;
+    }
+    const lease: ActiveLease = { controller: new AbortController(), generation, identity: _identity };
+    active = lease;
+    const isCurrent = (): boolean =>
+      lifecycle === 'active' && active === lease && generation === lease.generation && !lease.controller.signal.aborted;
+    return {
+      isCurrent,
+      release: () => {
+        if (active === lease) {
+          invalidate();
+        }
+      },
+      signal: lease.controller.signal,
+    };
+  };
+
+  return {
+    activate: () => {
+      if (lifecycle !== 'disposed') {
+        lifecycle = 'active';
+      }
+    },
+    cooldown: () => {
+      if (lifecycle === 'disposed') {
+        return;
+      }
+      lifecycle = 'cooling';
+      invalidate();
+    },
+    dispose: () => {
+      if (lifecycle === 'disposed') {
+        return;
+      }
+      lifecycle = 'disposed';
+      invalidate();
+    },
+    invalidateDocument: invalidate,
+    invalidateLayer: (layerId) => {
+      if (active?.identity.layerId === layerId) {
+        invalidate();
+      }
+    },
+    invalidateProject: invalidate,
+    tryAcquire,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/editing/controlPixelEdit.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/editing/controlPixelEdit.test.ts
new file mode 100644
index 00000000000..b23528e7f1b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/editing/controlPixelEdit.test.ts
@@ -0,0 +1,179 @@
+import type { CanvasControlLayerContract, CanvasLayerContract } from '@workbench/types';
+
+import { createTestStubRasterBackend, type StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it } from 'vitest';
+
+import {
+  bakeControlPixelEditSurface,
+  buildMaterializedControlLayer,
+  decideControlPixelEdit,
+  isLayerPixelEditEligible,
+} from './controlPixelEdit';
+
+const control = (overrides: Partial<CanvasControlLayerContract> = {}): CanvasControlLayerContract => ({
+  adapter: { beginEndStepPct: [0.1, 0.9], controlMode: 'more_control', kind: 'controlnet', model: 'm', weight: 0.7 },
+  blendMode: 'screen',
+  filter: { settings: { low: 10 }, type: 'canny' },
+  id: 'control',
+  isEnabled: true,
+  isLocked: false,
+  name: 'Control',
+  opacity: 0.6,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: true,
+  ...overrides,
+});
+
+describe('decideControlPixelEdit', () => {
+  it.each([
+    ['locked', control({ isLocked: true }), true, true, 'locked'],
+    ['disabled', control({ isEnabled: false }), true, true, 'disabled'],
+    [
+      'unsupported polygon',
+      control({
+        source: {
+          fill: '#fff',
+          height: 10,
+          kind: 'polygon',
+          points: [],
+          stroke: null,
+          strokeWidth: 0,
+          type: 'shape',
+          width: 10,
+        },
+      }),
+      true,
+      true,
+      'unsupported',
+    ],
+    [
+      'stale image',
+      control({ source: { image: { height: 10, imageName: 'image', width: 10 }, type: 'image' } }),
+      true,
+      false,
+      'not-ready',
+    ],
+  ] as const)('rejects a %s control', (_scenario, layer, hasSourceContent, isCacheReady, reason) => {
+    expect(decideControlPixelEdit({ hasSourceContent, isCacheReady, layer })).toEqual({ reason, status: 'rejected' });
+  });
+
+  it('edits an empty identity paint control directly', () => {
+    expect(decideControlPixelEdit({ hasSourceContent: false, isCacheReady: true, layer: control() })).toEqual({
+      status: 'direct',
+    });
+  });
+
+  it.each([
+    control({ source: { image: { height: 10, imageName: 'image', width: 10 }, type: 'image' } }),
+    control({ transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 12, y: 8 } }),
+  ])('materializes a ready non-direct control', (layer) => {
+    expect(decideControlPixelEdit({ hasSourceContent: true, isCacheReady: true, layer })).toEqual({
+      status: 'materialize',
+    });
+  });
+});
+
+describe('isLayerPixelEditEligible', () => {
+  const rasterPaint: CanvasLayerContract = {
+    blendMode: 'normal',
+    id: 'raster',
+    isEnabled: true,
+    isLocked: false,
+    name: 'Raster',
+    opacity: 1,
+    source: { bitmap: null, type: 'paint' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'raster',
+  };
+
+  it.each([
+    ['raster paint', rasterPaint, true],
+    ['paint control', control(), true],
+    [
+      'image control',
+      control({ source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' } }),
+      true,
+    ],
+    [
+      'rectangle control',
+      control({
+        source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+      }),
+      true,
+    ],
+    [
+      'polygon control',
+      control({
+        source: {
+          fill: '#fff',
+          height: 10,
+          kind: 'polygon',
+          points: [],
+          stroke: null,
+          strokeWidth: 0,
+          type: 'shape',
+          width: 10,
+        },
+      }),
+      false,
+    ],
+    [
+      'raster image',
+      { ...rasterPaint, source: { image: { height: 10, imageName: 'i', width: 10 }, type: 'image' } },
+      false,
+    ],
+    ['locked control', control({ isLocked: true }), false],
+    ['disabled control', control({ isEnabled: false }), false],
+    ['missing layer', undefined, false],
+  ] as const)('returns %s eligibility for %s', (_scenario, layer, expected) => {
+    expect(isLayerPixelEditEligible(layer)).toBe(expected);
+  });
+});
+
+describe('buildMaterializedControlLayer', () => {
+  it('changes only source and transform', () => {
+    const before = control({
+      source: { image: { height: 10, imageName: 'image', width: 10 }, type: 'image' },
+      transform: { rotation: Math.PI / 2, scaleX: 2, scaleY: 1, x: 30, y: 40 },
+    });
+    const after = buildMaterializedControlLayer(before, { height: 20, width: 10, x: 20, y: 40 });
+
+    expect(after).toEqual({
+      ...before,
+      source: { bitmap: null, offset: { x: 20, y: 40 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    });
+    expect(before.source.type).toBe('image');
+  });
+});
+
+describe('bakeControlPixelEditSurface', () => {
+  it('bakes offset source pixels through the complete translated, rotated, and scaled transform', () => {
+    const backend = createTestStubRasterBackend();
+    const source = backend.createSurface(10, 5);
+    const sourceRect = { height: 5, width: 10, x: 5, y: -4 };
+    const baked = bakeControlPixelEditSurface({
+      backend,
+      source,
+      sourceRect,
+      transform: { rotation: Math.PI / 2, scaleX: 2, scaleY: 3, x: 7, y: 11 },
+    });
+
+    expect(baked.rect).toEqual({ height: 20, width: 15, x: 4, y: 21 });
+    expect(baked.surface.width).toBe(15);
+    expect(baked.surface.height).toBe(20);
+    expect((baked.surface as StubRasterSurface).callLog).toEqual([
+      { args: [1, 0, 0, 1, 0, 0], op: 'setTransform' },
+      { args: [0, 0, 15, 20], op: 'clearRect' },
+      { args: ['imageSmoothingEnabled', true], op: 'set' },
+      {
+        args: [2 * Math.cos(Math.PI / 2), 2, -3, 3 * Math.cos(Math.PI / 2), 3, -10],
+        op: 'setTransform',
+      },
+      { args: [source.canvas, sourceRect.x, sourceRect.y], op: 'drawImage' },
+      { args: [1, 0, 0, 1, 0, 0], op: 'setTransform' },
+    ]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/editing/controlPixelEdit.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/editing/controlPixelEdit.ts
new file mode 100644
index 00000000000..8221c82e645
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/editing/controlPixelEdit.ts
@@ -0,0 +1,92 @@
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasControlLayerContract, CanvasLayerContract } from '@workbench/types';
+
+import { roundOut, transformBounds } from '@workbench/canvas-engine/math/rect';
+import { bakeMatrix, IDENTITY_TRANSFORM, type LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+
+export type ControlPixelEditRejectedReason = 'disabled' | 'locked' | 'not-ready' | 'unsupported';
+export type ControlPixelEditDecision =
+  | { status: 'direct' }
+  | { status: 'materialize' }
+  | { status: 'rejected'; reason: ControlPixelEditRejectedReason };
+
+export interface DecideControlPixelEditInput {
+  layer: CanvasControlLayerContract;
+  hasSourceContent: boolean;
+  isCacheReady: boolean;
+}
+
+const isIdentity = (transform: LayerTransform): boolean =>
+  transform.x === 0 &&
+  transform.y === 0 &&
+  transform.scaleX === 1 &&
+  transform.scaleY === 1 &&
+  transform.rotation === 0;
+
+const isRasterizable = (layer: CanvasControlLayerContract): boolean =>
+  layer.source.type !== 'shape' || layer.source.kind !== 'polygon';
+
+export const isLayerPixelEditEligible = (layer: CanvasLayerContract | undefined): boolean =>
+  !!layer &&
+  !layer.isLocked &&
+  layer.isEnabled &&
+  ((layer.type === 'raster' && layer.source.type === 'paint') || (layer.type === 'control' && isRasterizable(layer)));
+
+export const decideControlPixelEdit = ({
+  hasSourceContent,
+  isCacheReady,
+  layer,
+}: DecideControlPixelEditInput): ControlPixelEditDecision => {
+  if (layer.isLocked) {
+    return { reason: 'locked', status: 'rejected' };
+  }
+  if (!layer.isEnabled) {
+    return { reason: 'disabled', status: 'rejected' };
+  }
+  if (!isRasterizable(layer)) {
+    return { reason: 'unsupported', status: 'rejected' };
+  }
+  if (hasSourceContent && !isCacheReady) {
+    return { reason: 'not-ready', status: 'rejected' };
+  }
+  if (layer.source.type === 'paint' && isIdentity(layer.transform)) {
+    return { status: 'direct' };
+  }
+  return { status: 'materialize' };
+};
+
+export const buildMaterializedControlLayer = (
+  layer: CanvasControlLayerContract,
+  rect: Rect
+): CanvasControlLayerContract => ({
+  ...structuredClone(layer),
+  source: { bitmap: null, offset: { x: rect.x, y: rect.y }, type: 'paint' },
+  transform: { ...IDENTITY_TRANSFORM },
+});
+
+export interface BakeControlPixelEditSurfaceInput {
+  backend: RasterBackend;
+  source: RasterSurface;
+  sourceRect: Rect;
+  transform: LayerTransform;
+}
+
+export const bakeControlPixelEditSurface = ({
+  backend,
+  source,
+  sourceRect,
+  transform,
+}: BakeControlPixelEditSurfaceInput): { rect: Rect; surface: RasterSurface } => {
+  const matrix = bakeMatrix(transform);
+  const rect = roundOut(transformBounds(matrix, sourceRect));
+  const surface = backend.createSurface(rect.width, rect.height);
+  const ctx = surface.ctx;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, rect.width, rect.height);
+  ctx.imageSmoothingEnabled = true;
+  ctx.setTransform(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e - rect.x, matrix.f - rect.y);
+  ctx.drawImage(source.canvas, sourceRect.x, sourceRect.y);
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  return { rect, surface };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.mask.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.mask.test.ts
new file mode 100644
index 00000000000..f7687c4aff9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.mask.test.ts
@@ -0,0 +1,595 @@
+/**
+ * Inpaint mask engine behaviour: painting into a mask's alpha cache, persisting
+ * the mask bitmap through the bitmap store, and the in-place mask invert.
+ *
+ * Isolated in its own file so it can `vi.mock` the canvas-image upload seam
+ * (the engine's INTERNAL bitmap store uses it) without touching the rest of the
+ * engine test suite.
+ */
+
+import type { StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type { CanvasProjectMutationPort } from '@workbench/canvasProjectMutationPort';
+import type { CanvasDocumentContractV2, CanvasStateContractV2, Project, WorkbenchState } from '@workbench/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import {
+  applyCanvasProjectMutation,
+  isCanvasProjectMutation,
+  type CanvasProjectMutation,
+} from '@workbench/canvasProjectMutations';
+
+type EngineTestAction = WorkbenchAction | CanvasProjectMutation;
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import {
+  createCanvasEngine as createApplicationCanvasEngine,
+  type CanvasEngineOptions,
+} from '@workbench/canvas-operations/createCanvasEngine';
+import { createInitialWorkbenchState, workbenchReducer } from '@workbench/workbenchState';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { StrokeCommittedEvent } from './tools/tool';
+
+interface EngineStore {
+  dispatch(action: EngineTestAction): void;
+  getState(): WorkbenchState;
+  subscribe(listener: () => void): () => void;
+}
+
+const createMutationPort = (store: EngineStore, projectId: string): CanvasProjectMutationPort => ({
+  dispatch: (mutation) => {
+    const before = store.getState().projects.find((project) => project.id === projectId)?.canvas ?? null;
+    if (!before) {
+      return false;
+    }
+    store.dispatch(mutation);
+    return store.getState().projects.find((project) => project.id === projectId)?.canvas !== before;
+  },
+  getCanvasState: () => store.getState().projects.find((project) => project.id === projectId)?.canvas ?? null,
+  subscribe: store.subscribe,
+});
+
+const createCanvasEngine = ({
+  projectId,
+  store,
+  ...options
+}: Omit<CanvasEngineOptions, 'mutationPort' | 'reportError'> & { store: EngineStore }) =>
+  createApplicationCanvasEngine({
+    ...options,
+    mutationPort: createMutationPort(store, projectId),
+    projectId,
+    reportError: () => undefined,
+  });
+
+vi.mock('@workbench/canvas-operations/backend/canvasImages', () => ({
+  CanvasImageUploadError: class extends Error {},
+  uploadCanvasImage: vi.fn(() => Promise.resolve({ height: 64, imageName: 'mask-img', width: 64 })),
+}));
+
+const makeCanvas = (document: CanvasDocumentContractV2, documentRevision = 0): CanvasStateContractV2 =>
+  ({
+    document,
+    documentRevision,
+    snapshots: [],
+    stagingArea: {
+      areThumbnailsVisible: false,
+      autoSwitchMode: 'off',
+      isVisible: false,
+      pendingImageIds: [],
+      pendingImages: [],
+      selectedImageIndex: 0,
+    },
+    version: 2,
+  }) as CanvasStateContractV2;
+
+const maskDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [
+    {
+      blendMode: 'normal',
+      id: 'mask1',
+      isEnabled: true,
+      isLocked: false,
+      mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+      name: 'Inpaint Mask 1',
+      opacity: 1,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'inpaint_mask',
+    },
+  ],
+  selectedLayerId: 'mask1',
+  version: 2,
+  width: 100,
+});
+
+const createReactiveStore = (document: CanvasDocumentContractV2) => {
+  let state = {
+    activeProjectId: 'p1',
+    projects: [{ canvas: makeCanvas(document), id: 'p1' }],
+  } as unknown as WorkbenchState;
+  const listeners = new Set<() => void>();
+  const dispatch = vi.fn((action: EngineTestAction) => {
+    if (isCanvasProjectMutation(action)) {
+      const project = state.projects[0] as unknown as Project;
+      state = {
+        ...state,
+        projects: [applyCanvasProjectMutation(project, action)],
+      } as WorkbenchState;
+    }
+    for (const listener of listeners) {
+      listener();
+    }
+  });
+  return {
+    dispatch,
+    setDocument: (next: CanvasDocumentContractV2, revision = 0) => {
+      state = {
+        activeProjectId: 'p1',
+        projects: [{ canvas: makeCanvas(next, revision), id: 'p1' }],
+      } as unknown as WorkbenchState;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    store: {
+      dispatch,
+      getState: () => state,
+      subscribe: (listener: () => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    } as EngineStore,
+  };
+};
+
+const createReducerBackedStore = (document: CanvasDocumentContractV2) => {
+  let state = createInitialWorkbenchState();
+  const projectId = state.activeProjectId;
+  state = workbenchReducer(state, {
+    mutation: { document, type: 'replaceCanvasDocument' },
+    projectId,
+    type: 'applyCanvasProjectMutation',
+  });
+  const listeners = new Set<() => void>();
+  const dispatch = vi.fn((action: EngineTestAction) => {
+    state = workbenchReducer(
+      state,
+      isCanvasProjectMutation(action) ? { mutation: action, projectId, type: 'applyCanvasProjectMutation' } : action
+    );
+    for (const listener of listeners) {
+      listener();
+    }
+  });
+  return {
+    projectId,
+    store: {
+      dispatch,
+      getState: () => state,
+      subscribe: (listener: () => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    } as EngineStore,
+  };
+};
+
+const createControllableRaf = () => {
+  let nextHandle = 1;
+  const callbacks = new Map<number, FrameRequestCallback>();
+  return {
+    cancelFrame: (handle: number) => callbacks.delete(handle),
+    flush: () => {
+      const queued = [...callbacks.values()];
+      callbacks.clear();
+      for (const cb of queued) {
+        cb(0);
+      }
+    },
+    requestFrame: (cb: FrameRequestCallback) => {
+      const handle = nextHandle++;
+      callbacks.set(handle, cb);
+      return handle;
+    },
+  };
+};
+
+const createInputCanvas = (width = 100, height = 100) => {
+  const surface = createTestStubRasterBackend().createSurface(width, height);
+  const listeners = new Map<string, Set<(event: Event) => void>>();
+  const element = {
+    addEventListener: (type: string, handler: (event: Event) => void) => {
+      const set = listeners.get(type) ?? new Set();
+      set.add(handler);
+      listeners.set(type, set);
+    },
+    getBoundingClientRect: () => ({ bottom: height, height, left: 0, right: width, top: 0, width, x: 0, y: 0 }),
+    getContext: () => surface.ctx,
+    height,
+    releasePointerCapture: () => {},
+    removeEventListener: (type: string, handler: (event: Event) => void) => {
+      listeners.get(type)?.delete(handler);
+    },
+    setPointerCapture: () => {},
+    width,
+  } as unknown as HTMLCanvasElement;
+  const fire = (type: string, event: Partial<PointerEvent>) => {
+    for (const handler of listeners.get(type) ?? []) {
+      handler({ preventDefault: () => {}, ...event } as unknown as Event);
+    }
+  };
+  return { element, fire };
+};
+
+const pointerAt = (x: number, y: number, buttons = 1): Partial<PointerEvent> =>
+  ({
+    altKey: false,
+    button: 0,
+    buttons,
+    clientX: x,
+    clientY: y,
+    ctrlKey: false,
+    metaKey: false,
+    pointerId: 1,
+    pointerType: 'mouse',
+    pressure: 0.5,
+    shiftKey: false,
+    timeStamp: 0,
+  }) as Partial<PointerEvent>;
+
+const setupEngine = (doc: CanvasDocumentContractV2) => {
+  const raf = createControllableRaf();
+  vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+  vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+  vi.stubGlobal('Path2D', class FakePath2D {});
+
+  const reactive = createReactiveStore(doc);
+  const engine = createCanvasEngine({
+    backend: createTestStubRasterBackend(),
+    imageResolver: () => Promise.resolve(new Blob()),
+    projectId: 'p1',
+    store: reactive.store,
+  });
+  const strokes: StrokeCommittedEvent[] = [];
+  engine.tools.onStrokeCommitted((event) => strokes.push(event));
+
+  const screen = createInputCanvas();
+  const overlay = createInputCanvas();
+  engine.surface.attach(screen.element, overlay.element);
+  raf.flush();
+
+  return { dispatch: reactive.dispatch, engine, overlay, raf, setDocument: reactive.setDocument, strokes };
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('inpaint mask painting', () => {
+  it('routes a brush stroke into the selected mask cache (no auto-created paint layer)', () => {
+    const { dispatch, engine, overlay, strokes } = setupEngine(maskDoc());
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, 0));
+
+    expect(strokes).toHaveLength(1);
+    expect(strokes[0]!.layerId).toBe('mask1');
+    expect(strokes[0]!.tool).toBe('brush');
+    // A mask target must NOT spawn a fresh paint layer (the auto-create path).
+    const added = dispatch.mock.calls.map((c) => c[0]).filter((a) => a.type === 'addCanvasLayer');
+    expect(added).toHaveLength(0);
+    engine.lifecycle.dispose();
+  });
+
+  it('erases from the mask cache with the eraser (destination-out) as a committed stroke', () => {
+    const { engine, overlay, strokes } = setupEngine(maskDoc());
+    // Paint some coverage first.
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(60, 60));
+    overlay.fire('pointerup', pointerAt(60, 60, 0));
+    // Then erase.
+    engine.tools.setTool('eraser');
+    overlay.fire('pointerdown', pointerAt(30, 30));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, 0));
+
+    expect(strokes).toHaveLength(2);
+    expect(strokes[1]!.tool).toBe('eraser');
+    expect(strokes[1]!.layerId).toBe('mask1');
+    engine.lifecycle.dispose();
+  });
+
+  it('does not paint into a locked mask', () => {
+    const doc = maskDoc();
+    doc.layers[0]!.isLocked = true;
+    const { dispatch, engine, overlay, strokes } = setupEngine(doc);
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, 0));
+
+    expect(strokes).toHaveLength(0);
+    // Also never spawns a paint layer over the locked mask.
+    expect(dispatch.mock.calls.map((c) => c[0]).some((a) => a.type === 'addCanvasLayer')).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('persists the mask via updateCanvasLayerConfig (bitmap + offset) after a stroke flush', async () => {
+    const { dispatch, engine, overlay } = setupEngine(maskDoc());
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(50, 50));
+    overlay.fire('pointerup', pointerAt(50, 50, 0));
+
+    await engine.lifecycle.flushPendingUploads();
+
+    const configDispatch = dispatch.mock.calls
+      .map((c) => c[0])
+      .find(
+        (a): a is Extract<EngineTestAction, { type: 'updateCanvasLayerConfig' }> =>
+          a.type === 'updateCanvasLayerConfig' && a.id === 'mask1'
+      );
+    expect(configDispatch).toBeDefined();
+    const config = configDispatch!.config;
+    expect(config.layerType).toBe('inpaint_mask');
+    // The mask bitmap ref + its content offset are dispatched (not an image source).
+    expect(config).toHaveProperty('mask');
+    const mask = (config as { mask: { bitmap: unknown; offset: unknown } }).mask;
+    expect(mask.bitmap).toMatchObject({ imageName: 'mask-img' });
+    expect(mask.offset).toBeDefined();
+    // The mask persistence must NEVER dispatch a paint source (that would convert
+    // the mask into a raster paint layer).
+    expect(dispatch.mock.calls.map((c) => c[0]).some((a) => a.type === 'updateCanvasLayerSource')).toBe(false);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('mask invert', () => {
+  it('inverts a mask as an undoable op and returns true', () => {
+    const { engine } = setupEngine(maskDoc());
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.layers.invertMask('mask1')).toBe(true);
+    // One undoable image patch was recorded.
+    expect(engine.stores.canUndo.get()).toBe(true);
+    // Round trips: undo then redo restore without throwing.
+    engine.history.undo();
+    expect(engine.stores.canRedo.get()).toBe(true);
+    engine.history.redo();
+    expect(engine.stores.canUndo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns false for a missing layer, a non-mask layer, or a locked mask', () => {
+    const lockedDoc = maskDoc();
+    lockedDoc.layers[0]!.isLocked = true;
+    const { engine } = setupEngine(lockedDoc);
+    expect(engine.layers.invertMask('nope')).toBe(false);
+    expect(engine.layers.invertMask('mask1')).toBe(false); // locked
+    engine.lifecycle.dispose();
+  });
+
+  // Regression: the invert domain used to come ONLY from `getSourceContentRect`,
+  // which reads the persisted `mask.bitmap` — stale/null until the debounced
+  // bitmap-store flush runs. A stroke painted moments earlier (already reflected
+  // in the live `layerCache`, not yet flushed to the contract) that extends past
+  // the document bbox was silently excluded from the invert, so its pixels never
+  // got flipped. The domain must union in the live cache rect too.
+  it('unions the live (unflushed) cache rect into the invert domain, covering an out-of-bbox stroke', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const reactive = createReactiveStore(maskDoc());
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store: reactive.store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    engine.tools.setTool('brush');
+    // Paint well outside the document bbox (0,0,100,100 per `maskDoc`). The live
+    // cache grows to cover the stroke immediately; deliberately never call
+    // `flushPendingUploads()`, so the contract's `mask.bitmap` stays null and
+    // `getSourceContentRect` alone would report an empty content rect.
+    overlay.fire('pointerdown', pointerAt(150, 150));
+    overlay.fire('pointermove', pointerAt(180, 180));
+    overlay.fire('pointerup', pointerAt(180, 180, 0));
+
+    expect(engine.layers.invertMask('mask1')).toBe(true);
+
+    // Growing the cache (both while painting and inside `invertMask` itself)
+    // reallocates a fresh backing surface each time its extent changes, so
+    // `surfaces` holds one entry per intermediate size, not one per layer. The
+    // invert's own read/write always lands on the LAST surface that gets a
+    // `putImageData` — the final, invert-sized surface — so pick that one
+    // rather than the first surface that happens to have a `getImageData`
+    // (which would be a stale, already-abandoned paint-time surface).
+    const putSurfaces = surfaces.filter((surface) => surface.callLog.some((entry) => entry.op === 'putImageData'));
+    const maskCache = putSurfaces[putSurfaces.length - 1];
+    expect(maskCache).toBeDefined();
+    const getCalls = maskCache!.callLog.filter((entry) => entry.op === 'getImageData');
+    expect(getCalls.length).toBeGreaterThan(0);
+    const [sx, sy, sw, sh] = getCalls[getCalls.length - 1]!.args as [number, number, number, number];
+    // A domain of just the document bbox (0,0,100,100) — what `getSourceContentRect`
+    // alone would report, since `mask.bitmap` is still null pre-flush — would read
+    // a region that ends at x/y 100. Unioning in the live cache rect must grow the
+    // domain to also cover the stroke out at document (150,150)-(180,180), well
+    // past that 100 bound on both axes.
+    expect(sx + sw).toBeGreaterThan(110);
+    expect(sy + sh).toBeGreaterThan(110);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('extracts through a live unflushed mask whose contract bitmap is still null', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const doc = maskDoc();
+    doc.layers.push({
+      blendMode: 'normal',
+      id: 'raster1',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Raster 1',
+      opacity: 1,
+      source: { image: { height: 100, imageName: 'raster-image', width: 100 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    const reducer = createReducerBackedStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+    raf.flush();
+
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(50, 50));
+    overlay.fire('pointerup', pointerAt(50, 50, 0));
+
+    expect(await engine.exports.extractMaskedArea('mask1')).toMatchObject({ status: 'extracted' });
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('mask clear', () => {
+  it('clears a live unflushed inpaint mask and restores it through undo', () => {
+    const { engine, overlay } = setupEngine(maskDoc());
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(50, 50));
+    overlay.fire('pointerup', pointerAt(50, 50, 0));
+
+    expect(engine.layers.clearMask('mask1')).toBe(true);
+    expect(engine.layers.clearMask('mask1')).toBe(false);
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    engine.history.undo();
+    expect(engine.stores.canRedo.get()).toBe(true);
+    engine.history.redo();
+    expect(engine.layers.clearMask('mask1')).toBe(false);
+    engine.history.undo();
+    expect(engine.layers.clearMask('mask1')).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('clears a regional-guidance mask', () => {
+    const doc = maskDoc();
+    doc.layers[0] = {
+      autoNegative: false,
+      blendMode: 'normal',
+      id: 'mask1',
+      isEnabled: true,
+      isLocked: false,
+      mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+      name: 'Region 1',
+      negativePrompt: null,
+      opacity: 1,
+      positivePrompt: null,
+      referenceImages: [],
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'regional_guidance',
+    };
+    const { engine, overlay } = setupEngine(doc);
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(50, 50));
+    overlay.fire('pointerup', pointerAt(50, 50, 0));
+
+    expect(engine.layers.clearMask('mask1')).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('clears a cold hidden persisted mask and restores its bitmap reference on undo', () => {
+    const doc = maskDoc();
+    const mask = doc.layers[0]!;
+    if (mask.type !== 'inpaint_mask') {
+      throw new Error('Expected inpaint mask fixture');
+    }
+    mask.isEnabled = false;
+    mask.mask = {
+      ...mask.mask,
+      bitmap: { height: 40, imageName: 'persisted-mask', width: 50 },
+      offset: { x: 7, y: 9 },
+    };
+    const { dispatch, engine } = setupEngine(doc);
+
+    expect(engine.layers.clearMask('mask1')).toBe(true);
+    expect(dispatch.mock.calls.at(-1)?.[0]).toMatchObject({
+      config: { mask: { bitmap: null } },
+      id: 'mask1',
+      type: 'updateCanvasLayerConfig',
+    });
+
+    engine.history.undo();
+    expect(dispatch.mock.calls.at(-1)?.[0]).toMatchObject({
+      config: {
+        mask: { bitmap: { imageName: 'persisted-mask' }, offset: { x: 7, y: 9 } },
+      },
+      id: 'mask1',
+      type: 'updateCanvasLayerConfig',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('refuses missing, non-mask, locked, and empty layers', () => {
+    const locked = maskDoc();
+    locked.layers[0]!.isLocked = true;
+    const { engine } = setupEngine(locked);
+
+    expect(engine.layers.clearMask('missing')).toBe(false);
+    expect(engine.layers.clearMask('mask1')).toBe(false);
+    engine.lifecycle.dispose();
+
+    const raster = maskDoc();
+    raster.layers[0] = {
+      blendMode: 'normal',
+      id: 'mask1',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Raster 1',
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    };
+    const { engine: rasterEngine } = setupEngine(raster);
+    expect(rasterEngine.layers.clearMask('mask1')).toBe(false);
+    rasterEngine.lifecycle.dispose();
+
+    const { engine: emptyEngine } = setupEngine(maskDoc());
+    expect(emptyEngine.layers.clearMask('mask1')).toBe(false);
+    emptyEngine.lifecycle.dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.test.ts
new file mode 100644
index 00000000000..090b2d4f4f9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.test.ts
@@ -0,0 +1,16714 @@
+import type * as ImagePatchModule from '@workbench/canvas-engine/history/imagePatch';
+import type * as LayerSnapshotModule from '@workbench/canvas-engine/history/layerSnapshot';
+import type * as AdjustedSurfaceCacheModule from '@workbench/canvas-engine/render/adjustedSurfaceCache';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type {
+  RasterCallLogEntry,
+  StubRasterBackend,
+  StubRasterSurface,
+} from '@workbench/canvas-engine/render/raster.testStub';
+import type { ToolId } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutationPort } from '@workbench/canvasProjectMutationPort';
+import type {
+  CanvasControlLayerContract,
+  CanvasDocumentContractV2,
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+  CanvasRasterLayerContractV2,
+  CanvasStagingCandidateContract,
+  CanvasStateContractV2,
+  Project,
+  WorkbenchState,
+} from '@workbench/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import {
+  applyCanvasProjectMutation,
+  isCanvasProjectMutation,
+  type CanvasProjectMutation,
+} from '@workbench/canvasProjectMutations';
+
+type EngineTestAction = WorkbenchAction | CanvasProjectMutation;
+
+import { DEFAULT_CHECKER_COLORS } from '@workbench/canvas-engine/render/compositor';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { canvasApplicationPort } from '@workbench/canvas-operations/applicationPort';
+import {
+  createCanvasEngine as createApplicationCanvasEngine,
+  getCanvasOperations,
+  type CanvasEngine,
+  type CanvasEngineOptions,
+} from '@workbench/canvas-operations/createCanvasEngine';
+import { FILTER_AUTO_PROCESS_DEBOUNCE_MS } from '@workbench/canvas-operations/filterOperationSession';
+import { createInitialWorkbenchState, workbenchReducer } from '@workbench/workbenchState';
+import { afterEach, describe, expect, it, type Mock, vi } from 'vitest';
+
+import type { BitmapStore } from './document/bitmapStore';
+import type { StrokeCommittedEvent } from './tools/tool';
+
+import { createBitmapStore } from './document/bitmapStore';
+import { mergeDownMatrix } from './document/mergeDown';
+
+interface EngineStore {
+  dispatch(action: EngineTestAction): void;
+  getState(): WorkbenchState;
+  reducesCanvasMutations?: true;
+  subscribe(listener: () => void): () => void;
+}
+
+const createTestMutationPort = (store: EngineStore, projectId: string): CanvasProjectMutationPort => {
+  const readStoreCanvas = () => store.getState().projects.find((project) => project.id === projectId)?.canvas ?? null;
+  let canvas = readStoreCanvas();
+  let observedStoreCanvas = canvas;
+  const listeners = new Set<() => void>();
+  const unsubscribeStore = store.subscribe(() => {
+    const next = readStoreCanvas();
+    if (next !== observedStoreCanvas) {
+      observedStoreCanvas = next;
+      canvas = next;
+    }
+    for (const listener of listeners) {
+      listener();
+    }
+  });
+  return {
+    dispatch: (mutation) => {
+      const before = canvas;
+      if (!before) {
+        return false;
+      }
+      store.dispatch(mutation);
+      if (store.reducesCanvasMutations) {
+        const reduced = readStoreCanvas();
+        observedStoreCanvas = reduced;
+        canvas = reduced;
+      } else {
+        const project = store.getState().projects.find((candidate) => candidate.id === projectId);
+        canvas = applyCanvasProjectMutation({ ...(project as Project), canvas: before }, mutation).canvas;
+        for (const listener of listeners) {
+          listener();
+        }
+      }
+      return canvas !== before;
+    },
+    getCanvasState: () => {
+      const current = readStoreCanvas();
+      if (current !== observedStoreCanvas) {
+        observedStoreCanvas = current;
+        canvas = current;
+      }
+      return canvas;
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          unsubscribeStore();
+        }
+      };
+    },
+  };
+};
+
+type TestCanvasEngineOptions = Omit<CanvasEngineOptions, 'getMainModelBase' | 'mutationPort' | 'reportError'> & {
+  getMainModelBase?: () => string | null;
+  mutationPort?: CanvasProjectMutationPort;
+  reportError?: CanvasEngineOptions['reportError'];
+  store: EngineStore;
+};
+
+const createCanvasEngine = ({
+  getMainModelBase,
+  mutationPort,
+  projectId,
+  reportError,
+  store,
+  ...options
+}: TestCanvasEngineOptions): CanvasEngine =>
+  createApplicationCanvasEngine({
+    ...options,
+    getMainModelBase:
+      getMainModelBase ?? (() => canvasApplicationPort.getSelectedModelBase(store.getState(), projectId)),
+    mutationPort: mutationPort ?? createTestMutationPort(store, projectId),
+    projectId,
+    reportError: reportError ?? (() => undefined),
+  });
+
+// Records adjusted-surface cache access without exposing it on the engine. The
+// factory wraps the real implementation, preserving all behaviour.
+const adjustedSurfaceCacheDeletes = vi.hoisted(() => [] as string[]);
+const adjustedSurfaceCacheGets = vi.hoisted(() => [] as string[]);
+const adjustedSurfaceCacheDeleteFaults = vi.hoisted(() => new Set<string>());
+const historyPreparationFaults = vi.hoisted(() => ({
+  imagePatch: false,
+  imagePatchBefore: null as ImageData | null,
+  layerSnapshot: false,
+}));
+
+vi.mock('@workbench/canvas-engine/render/adjustedSurfaceCache', async (importOriginal) => {
+  const actual = await importOriginal<typeof AdjustedSurfaceCacheModule>();
+  return {
+    ...actual,
+    createAdjustedSurfaceCache: (backend: Parameters<typeof actual.createAdjustedSurfaceCache>[0]) => {
+      const cache = actual.createAdjustedSurfaceCache(backend);
+      return {
+        ...cache,
+        delete: (layerId: string) => {
+          adjustedSurfaceCacheDeletes.push(layerId);
+          if (adjustedSurfaceCacheDeleteFaults.has(layerId)) {
+            adjustedSurfaceCacheDeleteFaults.delete(layerId);
+            throw new Error('adjusted surface cache delete failed');
+          }
+          cache.delete(layerId);
+        },
+        get: (...args: Parameters<typeof cache.get>) => {
+          adjustedSurfaceCacheGets.push(args[0]);
+          return cache.get(...args);
+        },
+      };
+    },
+  };
+});
+
+vi.mock('./history/imagePatch', async (importOriginal) => {
+  const actual = await importOriginal<typeof ImagePatchModule>();
+  return {
+    ...actual,
+    createImagePatchEntry: (...args: Parameters<typeof actual.createImagePatchEntry>) => {
+      historyPreparationFaults.imagePatchBefore = args[0].before;
+      if (historyPreparationFaults.imagePatch) {
+        throw new Error('image patch preparation failed');
+      }
+      return actual.createImagePatchEntry(...args);
+    },
+  };
+});
+
+vi.mock('./history/layerSnapshot', async (importOriginal) => {
+  const actual = await importOriginal<typeof LayerSnapshotModule>();
+  return {
+    ...actual,
+    createLayerSnapshotEntry: (...args: Parameters<typeof actual.createLayerSnapshotEntry>) => {
+      if (historyPreparationFaults.layerSnapshot) {
+        throw new Error('layer snapshot preparation failed');
+      }
+      return actual.createLayerSnapshotEntry(...args);
+    },
+  };
+});
+
+const rasterLayer = (id: string, opts: { imageName?: string; opacity?: number } = {}): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: opts.opacity ?? 1,
+  source: { image: { height: 10, imageName: opts.imageName ?? id, width: 10 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const makeDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [rasterLayer('a')],
+  selectedLayerId: null,
+  version: 2,
+  width: 100,
+});
+
+const makeCanvas = (document: CanvasDocumentContractV2, documentRevision = 0): CanvasStateContractV2 => ({
+  document,
+  documentRevision,
+  snapshots: [],
+  stagingArea: {
+    areThumbnailsVisible: false,
+    autoSwitchMode: 'off',
+    isVisible: false,
+    pendingImageIds: [],
+    pendingImages: [],
+    selectedImageIndex: 0,
+  },
+  version: 2,
+});
+
+const createFakeStore = (
+  document: CanvasDocumentContractV2
+): { store: EngineStore; unsubscribe: ReturnType<typeof vi.fn> } => {
+  const state = {
+    activeProjectId: 'p1',
+    projects: [{ canvas: makeCanvas(document), id: 'p1' }],
+  } as unknown as WorkbenchState;
+  const unsubscribe = vi.fn();
+  return {
+    store: {
+      dispatch: vi.fn(),
+      getState: () => state,
+      subscribe: () => unsubscribe,
+    },
+    unsubscribe,
+  };
+};
+
+const createEngine = () => {
+  const doc = makeDoc();
+  const { store, unsubscribe } = createFakeStore(doc);
+  const engine = createCanvasEngine({
+    backend: createTestStubRasterBackend(),
+    imageResolver: () => Promise.resolve(new Blob()),
+    projectId: 'p1',
+    store,
+  });
+  return { doc, engine, unsubscribe };
+};
+
+// ---- Reactive store + render-loop harness -----------------------------
+//
+// The tests above never `attach()`, so the render loop (and thus
+// `ensureLayerCaches`) never runs. The tests below exercise the document
+// mirror wired into a live engine, so they need: a store that actually
+// notifies subscribers on change, a controllable `requestAnimationFrame`
+// pair to drive the (otherwise real) scheduler deterministically, and fake
+// canvases whose `getContext('2d')` returns a recording stub context.
+
+/** A reactive fake store: `setDocument` notifies subscribers, unlike `createFakeStore` above. */
+const createReactiveStore = (
+  document: CanvasDocumentContractV2
+): {
+  listenerCount: () => number;
+  setActiveProjectId: (projectId: string) => void;
+  setDocument: (next: CanvasDocumentContractV2, documentRevision?: number) => void;
+  store: EngineStore;
+} => {
+  let revision = 0;
+  let activeProjectId = 'p1';
+  let state = {
+    activeProjectId,
+    projects: [{ canvas: makeCanvas(document), id: 'p1' }],
+  } as unknown as WorkbenchState;
+  const listeners = new Set<() => void>();
+  const notify = (): void => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  return {
+    listenerCount: () => listeners.size,
+    setActiveProjectId: (projectId) => {
+      activeProjectId = projectId;
+      state = { ...state, activeProjectId };
+      notify();
+    },
+    setDocument: (next, documentRevision = revision) => {
+      revision = documentRevision;
+      state = {
+        activeProjectId,
+        projects: [{ canvas: makeCanvas(next, documentRevision), id: 'p1' }],
+      } as unknown as WorkbenchState;
+      notify();
+    },
+    store: {
+      dispatch: vi.fn(),
+      getState: () => state,
+      subscribe: (listener) => {
+        listeners.add(listener);
+        return () => {
+          listeners.delete(listener);
+        };
+      },
+    },
+  };
+};
+
+/** A controllable `requestAnimationFrame`/`cancelAnimationFrame` pair for driving the scheduler. */
+const createControllableRaf = () => {
+  let nextHandle = 1;
+  const callbacks = new Map<number, FrameRequestCallback>();
+  return {
+    cancelFrame: (handle: number): void => {
+      callbacks.delete(handle);
+    },
+    /** Runs every currently-queued frame callback, like the browser firing a frame. */
+    flush: (): void => {
+      const queued = [...callbacks.entries()];
+      callbacks.clear();
+      for (const [, cb] of queued) {
+        cb(0);
+      }
+    },
+    pendingCount: (): number => callbacks.size,
+    requestFrame: (cb: FrameRequestCallback): number => {
+      const handle = nextHandle++;
+      callbacks.set(handle, cb);
+      return handle;
+    },
+  };
+};
+
+/** A minimal fake `HTMLCanvasElement`: a recording 2D context, no-op listeners. */
+const createFakeCanvas = (width = 100, height = 100): { element: HTMLCanvasElement; surface: StubRasterSurface } => {
+  const surface = createTestStubRasterBackend().createSurface(width, height);
+  const listeners = new Map<string, Set<(event: Event) => void>>();
+  const element = {
+    addEventListener: (type: string, handler: (event: Event) => void) => {
+      let set = listeners.get(type);
+      if (!set) {
+        set = new Set();
+        listeners.set(type, set);
+      }
+      set.add(handler);
+    },
+    getBoundingClientRect: () => ({
+      bottom: height,
+      height,
+      left: 0,
+      right: width,
+      toJSON: () => ({}),
+      top: 0,
+      width,
+      x: 0,
+      y: 0,
+    }),
+    getContext: () => surface.ctx,
+    height,
+    releasePointerCapture: () => {},
+    removeEventListener: (type: string, handler: (event: Event) => void) => {
+      listeners.get(type)?.delete(handler);
+    },
+    setPointerCapture: () => {},
+    width,
+  } as unknown as HTMLCanvasElement;
+  return { element, surface };
+};
+
+/** A deferred promise, so a test can resolve a rasterize step on demand. */
+const createDeferred = <T>(): { promise: Promise<T>; resolve: (value: T) => void } => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+const createAbortableImageResolver = () => {
+  const requests = new Map<
+    string,
+    { deferred: ReturnType<typeof createDeferred<Blob>>; signal: AbortSignal | undefined }
+  >();
+  const resolver = vi.fn((imageName: string, signal?: AbortSignal) => {
+    const deferred = createDeferred<Blob>();
+    requests.set(imageName, { deferred, signal });
+    if (signal?.aborted) {
+      return Promise.reject(signal.reason);
+    }
+    return new Promise<Blob>((resolve, reject) => {
+      deferred.promise.then(resolve, reject);
+      signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+  });
+  return { requests, resolver };
+};
+
+type RecordingRasterBackend = StubRasterBackend & {
+  drawSourcesFor(surface: StubRasterSurface): string[];
+  surfaceById(id: string): StubRasterSurface | undefined;
+  surfaceId(surface: StubRasterSurface): string;
+};
+
+/**
+ * Stateful raster backend for publication-race tests. Every scratch/cache
+ * surface gets a stable id, as do the fake bitmaps supplied by each test. This
+ * lets a test distinguish a decode drawn into an isolated scratch surface from
+ * a scratch surface published into the live cache without exposing cache
+ * internals from the production engine.
+ */
+const createRecordingRasterBackend = (): RecordingRasterBackend => {
+  const base = createTestStubRasterBackend();
+  let nextSurfaceId = 1;
+  const surfaces = new Map<string, StubRasterSurface>();
+  return {
+    ...base,
+    createSurface: (width, height) => {
+      const surface = base.createSurface(width, height);
+      const id = `surface-${nextSurfaceId++}`;
+      Object.assign(surface.canvas, { __recordingId: id });
+      surfaces.set(id, surface);
+      return surface;
+    },
+    drawSourcesFor: (surface) =>
+      surface.callLog
+        .filter((entry) => entry.op === 'drawImage')
+        .map((entry) => (entry.args[0] as { __recordingId?: string }).__recordingId ?? 'unknown'),
+    surfaceById: (id) => surfaces.get(id),
+    surfaceId: (surface) => (surface.canvas as unknown as { __recordingId: string }).__recordingId,
+  };
+};
+
+const recordingBitmap = (id: string, width = 10, height = 10): ImageBitmap =>
+  ({ __recordingId: `bitmap-${id}`, close: vi.fn(), height, width }) as unknown as ImageBitmap;
+
+/** One-shot allocation/draw faults, armed after a deterministic number of successful calls. */
+const createStructuralFaultBackend = () => {
+  const base = createTestStubRasterBackend();
+  let allocationCountdown: number | null = null;
+  let drawCountdown: number | null = null;
+  const backend: StubRasterBackend = {
+    ...base,
+    createSurface: (width, height) => {
+      if (allocationCountdown !== null) {
+        if (allocationCountdown === 0) {
+          allocationCountdown = null;
+          throw new Error('structural cache allocation failed');
+        }
+        allocationCountdown -= 1;
+      }
+      const surface = base.createSurface(width, height);
+      const ctx = new Proxy(surface.ctx, {
+        get: (target, property, receiver) => {
+          const value = Reflect.get(target, property, receiver);
+          if (property !== 'drawImage' || typeof value !== 'function') {
+            return value;
+          }
+          return (...args: unknown[]) => {
+            if (drawCountdown !== null) {
+              if (drawCountdown === 0) {
+                drawCountdown = null;
+                throw new Error('structural cache draw failed');
+              }
+              drawCountdown -= 1;
+            }
+            return Reflect.apply(value, target, args);
+          };
+        },
+      });
+      Object.defineProperty(surface, 'ctx', { value: ctx });
+      return surface;
+    },
+  };
+
+  return {
+    armAllocation: (successfulCreates: number) => {
+      allocationCountdown = successfulCreates;
+    },
+    armDraw: (successfulDraws: number) => {
+      drawCountdown = successfulDraws;
+    },
+    backend,
+  };
+};
+
+const createInvalidateDuringBitmapDrawBackend = (bitmap: ImageBitmap, onDraw: () => void): StubRasterBackend => {
+  const backend = createTestStubRasterBackend();
+  let invalidated = false;
+  return {
+    ...backend,
+    createImageBitmap: vi.fn(() => Promise.resolve(bitmap)),
+    createSurface: (width, height) => {
+      const surface = backend.createSurface(width, height);
+      const ctx = new Proxy(surface.ctx, {
+        get: (target, property, receiver) => {
+          const value = Reflect.get(target, property, receiver);
+          if (property !== 'drawImage' || typeof value !== 'function') {
+            return value;
+          }
+          return (...args: unknown[]) => {
+            const result = Reflect.apply(value, target, args);
+            if (!invalidated && args[0] === bitmap) {
+              invalidated = true;
+              onDraw();
+            }
+            return result;
+          };
+        },
+      });
+      Object.defineProperty(surface, 'ctx', { value: ctx });
+      return surface;
+    },
+  };
+};
+
+interface LayerCacheTestSnapshot {
+  calls: RasterCallLogEntry[];
+  rect: { height: number; width: number; x: number; y: number };
+  surface: RasterSurface;
+  version: number;
+}
+
+const snapshotLayerCache = async (engine: ReturnType<typeof createCanvasEngine>, layerId: string) => {
+  const exported = await engine.exports.exportLayerPixels(layerId, { includeDisabled: true });
+  if (exported.status !== 'ok') {
+    throw new Error(`Expected a ready cache for ${layerId}, got ${exported.status}`);
+  }
+  return {
+    calls: structuredClone((exported.surface as StubRasterSurface).callLog),
+    rect: { ...exported.rect },
+    surface: exported.surface,
+    version: exported.guard.cacheVersion,
+  } satisfies LayerCacheTestSnapshot;
+};
+
+const expectLayerCacheExact = async (
+  engine: ReturnType<typeof createCanvasEngine>,
+  layerId: string,
+  expectedSnapshot: LayerCacheTestSnapshot
+): Promise<void> => {
+  const actual = await engine.exports.exportLayerPixels(layerId, { includeDisabled: true });
+  expect(actual.status).toBe('ok');
+  if (actual.status !== 'ok') {
+    return;
+  }
+  expect(actual.surface).toBe(expectedSnapshot.surface);
+  expect(actual.rect).toEqual(expectedSnapshot.rect);
+  expect(actual.guard.cacheVersion).toBe(expectedSnapshot.version);
+  expect((actual.surface as StubRasterSurface).callLog).toEqual(expectedSnapshot.calls);
+};
+
+/** Recursively follows recording-surface draw edges to a bitmap/surface id. */
+const drawGraphContains = (
+  surface: StubRasterSurface,
+  backend: RecordingRasterBackend,
+  targetId: string,
+  visited = new Set<string>()
+): boolean => {
+  for (const sourceId of backend.drawSourcesFor(surface)) {
+    if (sourceId === targetId) {
+      return true;
+    }
+    if (visited.has(sourceId)) {
+      continue;
+    }
+    visited.add(sourceId);
+    const source = backend.surfaceById(sourceId);
+    if (source && drawGraphContains(source, backend, targetId, visited)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/** Flushes pending microtasks (promise chains) without depending on fake timers. */
+const flushMicrotasks = (): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+
+const drainMicrotasksUntil = async (predicate: () => boolean, maxTicks = 100): Promise<void> => {
+  for (let tick = 0; tick < maxTicks && !predicate(); tick += 1) {
+    await Promise.resolve();
+  }
+};
+
+afterEach(() => {
+  adjustedSurfaceCacheDeleteFaults.clear();
+  historyPreparationFaults.imagePatch = false;
+  historyPreparationFaults.imagePatchBefore = null;
+  historyPreparationFaults.layerSnapshot = false;
+  vi.unstubAllGlobals();
+});
+
+describe('createCanvasEngine', () => {
+  it('captures a detached clone of the exact reducer canvas contract', () => {
+    const { doc, engine } = createEngine();
+
+    const snapshot = engine.document.captureSnapshot();
+
+    expect(snapshot?.canvas.document).toEqual(doc);
+    expect(snapshot?.canvas.document).not.toBe(doc);
+    expect(snapshot?.canvas.documentRevision).toBe(0);
+    doc.bbox.x = 99;
+    expect(snapshot?.canvas.document.bbox.x).toBe(0);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns stale and releases a partial raster snapshot when the document changes during detachment', async () => {
+    const pending = createDeferred<Blob>();
+    const document = makeDoc();
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => pending.promise,
+      projectId: 'p1',
+      store,
+    });
+    const documentSnapshot = engine.document.captureSnapshot();
+    expect(documentSnapshot).not.toBeNull();
+
+    const capture = engine.exports.captureRasterSnapshot(documentSnapshot!, ['a']);
+    setDocument({
+      ...document,
+      layers: [{ ...document.layers[0]!, opacity: 0.5 }],
+    });
+    pending.resolve(new Blob(['pixels']));
+
+    await expect(capture).resolves.toEqual({ status: 'stale' });
+    engine.lifecycle.dispose();
+  });
+
+  it('returns stale when direct paint changes cache pixels after the document snapshot', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const layer = {
+      ...rasterLayer('a'),
+      source: { bitmap: { height: 20, imageName: 'paint-pixels', width: 20 }, type: 'paint' as const },
+    };
+    const document = { ...makeDoc(), layers: [layer], selectedLayerId: layer.id };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    const initial = await engine.exports.exportLayerPixels(layer.id);
+    expect(initial.status).toBe('ok');
+    if (initial.status !== 'ok') {
+      throw new Error('Expected initial pixels');
+    }
+    const initialGuard = initial.guard;
+    initial.release();
+    const documentSnapshot = engine.document.captureSnapshot();
+    const capture = engine.exports.captureRasterSnapshot(documentSnapshot!, [layer.id]);
+
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(5, 5));
+    overlay.fire('pointermove', pointerAt(10, 10));
+    overlay.fire('pointerup', pointerAt(10, 10, { buttons: 0 }));
+
+    expect(engine.exports.isLayerExportGuardCurrent(initialGuard)).toBe(false);
+    await expect(capture).resolves.toEqual({ status: 'stale' });
+    engine.lifecycle.dispose();
+  });
+
+  it('returns stale when cooldown changes lifecycle generation during raster detachment', async () => {
+    const pending = createDeferred<Blob>();
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => pending.promise,
+      projectId: 'p1',
+      store,
+    });
+    const documentSnapshot = engine.document.captureSnapshot();
+    const capture = engine.exports.captureRasterSnapshot(documentSnapshot!, ['a']);
+
+    const cooldown = engine.lifecycle.beginCooldown();
+    pending.resolve(new Blob(['pixels']));
+
+    await expect(capture).resolves.toEqual({ status: 'stale' });
+    await cooldown;
+    engine.lifecycle.dispose();
+  });
+
+  it('promptly aborts raster snapshot cache preparation without waiting for a stalled decode', async () => {
+    const { requests, resolver } = createAbortableImageResolver();
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    const controller = new AbortController();
+    const documentSnapshot = engine.document.captureSnapshot();
+    const capture = engine.exports.captureRasterSnapshot(documentSnapshot!, ['a'], { signal: controller.signal });
+    const settled = vi.fn();
+    void capture.then(settled);
+    await drainMicrotasksUntil(() => requests.has('a'));
+
+    controller.abort(new DOMException('invoke cancelled', 'AbortError'));
+    await drainMicrotasksUntil(() => settled.mock.calls.length > 0);
+
+    expect(requests.get('a')?.signal?.aborted).toBe(true);
+    expect(settled).toHaveBeenCalledWith({ status: 'aborted' });
+    engine.lifecycle.dispose();
+  });
+
+  it('releases snapshot reservations and pins promptly after abort so a large retry can proceed', async () => {
+    const imageSize = 5_300;
+    const largeLayer: CanvasRasterLayerContractV2 = {
+      blendMode: 'normal',
+      id: 'large',
+      isEnabled: true,
+      isLocked: false,
+      name: 'large',
+      opacity: 1,
+      source: {
+        image: { height: imageSize, imageName: 'large', width: imageSize },
+        type: 'image',
+      },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    };
+    const document: CanvasDocumentContractV2 = {
+      ...makeDoc(),
+      height: imageSize,
+      layers: [largeLayer],
+      width: imageSize,
+    };
+    const { requests, resolver } = createAbortableImageResolver();
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    const controller = new AbortController();
+    const firstSnapshot = engine.document.captureSnapshot();
+    const firstCapture = engine.exports.captureRasterSnapshot(firstSnapshot!, ['large'], {
+      signal: controller.signal,
+    });
+    await drainMicrotasksUntil(() => requests.has('large'));
+
+    controller.abort(new DOMException('invoke cancelled', 'AbortError'));
+    await expect(firstCapture).resolves.toEqual({ status: 'aborted' });
+
+    requests.delete('large');
+    const retrySnapshot = engine.document.captureSnapshot();
+    const retryCapture = engine.exports.captureRasterSnapshot(retrySnapshot!, ['large']);
+    await drainMicrotasksUntil(() => requests.has('large'));
+    requests.get('large')?.deferred.resolve(new Blob(['retry pixels']));
+
+    const retry = await retryCapture;
+    expect(retry.status).toBe('ok');
+    if (retry.status === 'ok') {
+      retry.snapshot.release();
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('returns typed not-ready when asynchronous raster cache preparation fails', async () => {
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.reject(new Error('decode unavailable')),
+      projectId: 'p1',
+      reportError: vi.fn(),
+      store,
+    });
+    const documentSnapshot = engine.document.captureSnapshot();
+
+    await expect(engine.exports.captureRasterSnapshot(documentSnapshot!, ['a'])).resolves.toEqual({
+      status: 'not-ready',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('returns caller-owned detached layer surfaces with an idempotent release', async () => {
+    const { engine } = createEngine();
+    const documentSnapshot = engine.document.captureSnapshot();
+
+    const result = await engine.exports.captureRasterSnapshot(documentSnapshot!, ['a', 'a']);
+
+    expect(result.status).toBe('ok');
+    if (result.status !== 'ok') {
+      throw new Error('raster snapshot was not captured');
+    }
+    expect([...result.snapshot.layerSurfaces.keys()]).toEqual(['a']);
+    expect(result.snapshot.layerSurfaces.get('a')?.surface).toBeDefined();
+    result.snapshot.release();
+    result.snapshot.release();
+    expect(result.snapshot.layerSurfaces.size).toBe(0);
+    engine.lifecycle.dispose();
+  });
+
+  it('captures valid pixels while identifying a genuinely empty paint layer for callers to skip', async () => {
+    const blank = { ...rasterLayer('blank'), source: { bitmap: null, type: 'paint' } as const };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [rasterLayer('valid'), blank] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob(['valid'])),
+      projectId: 'p1',
+      store,
+    });
+    const documentSnapshot = engine.document.captureSnapshot();
+
+    const result = await engine.exports.captureRasterSnapshot(documentSnapshot!, ['valid', 'blank']);
+
+    expect(result.status).toBe('ok');
+    if (result.status !== 'ok') {
+      throw new Error('Expected mixed raster snapshot');
+    }
+    expect([...result.snapshot.layerSurfaces.keys()]).toEqual(['valid']);
+    expect([...result.snapshot.emptyLayerIds]).toEqual(['blank']);
+    result.snapshot.release();
+    engine.lifecycle.dispose();
+  });
+
+  it('returns a successful empty raster snapshot for a blank-only document', async () => {
+    const blank = { ...rasterLayer('blank'), source: { bitmap: null, type: 'paint' } as const };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [blank] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const documentSnapshot = engine.document.captureSnapshot();
+
+    const result = await engine.exports.captureRasterSnapshot(documentSnapshot!, ['blank']);
+
+    expect(result.status).toBe('ok');
+    if (result.status !== 'ok') {
+      throw new Error('Expected empty raster snapshot');
+    }
+    expect(result.snapshot.layerSurfaces.size).toBe(0);
+    expect([...result.snapshot.emptyLayerIds]).toEqual(['blank']);
+    result.snapshot.release();
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps caller-owned raster snapshot surfaces alive across cooldown', async () => {
+    const { engine } = createEngine();
+    const documentSnapshot = engine.document.captureSnapshot();
+    const result = await engine.exports.captureRasterSnapshot(documentSnapshot!, ['a']);
+    expect(result.status).toBe('ok');
+    if (result.status !== 'ok') {
+      throw new Error('raster snapshot was not captured');
+    }
+
+    await engine.lifecycle.beginCooldown();
+
+    expect(result.snapshot.layerSurfaces.size).toBe(1);
+    result.snapshot.release();
+    expect(result.snapshot.layerSurfaces.size).toBe(0);
+    engine.lifecycle.dispose();
+  });
+
+  it('refuses a raster snapshot using the actual live surface bytes before cloning', async () => {
+    const { engine } = createEngine();
+    const live = await engine.exports.exportLayerPixels('a');
+    expect(live.status).toBe('ok');
+    if (live.status !== 'ok') {
+      throw new Error('layer cache was not rasterized');
+    }
+    // Model a live paint cache that has grown beyond its persisted source bounds.
+    // The stub resize records dimensions without allocating a real 276 MiB buffer.
+    // One live surface fits the 512 MiB limit; cloning a second one does not.
+    live.surface.resize(8_500, 8_500);
+    const documentSnapshot = engine.document.captureSnapshot();
+
+    await expect(engine.exports.captureRasterSnapshot(documentSnapshot!, ['a'])).resolves.toEqual({
+      status: 'over-budget',
+    });
+
+    engine.lifecycle.dispose();
+  });
+
+  it('releases detached raster snapshot surfaces when the engine is disposed', async () => {
+    const { engine } = createEngine();
+    const documentSnapshot = engine.document.captureSnapshot();
+    const result = await engine.exports.captureRasterSnapshot(documentSnapshot!, ['a']);
+    expect(result.status).toBe('ok');
+    if (result.status !== 'ok') {
+      throw new Error('raster snapshot was not captured');
+    }
+
+    engine.lifecycle.dispose();
+
+    expect(result.snapshot.layerSurfaces.size).toBe(0);
+  });
+  it('mirrors the reducer-owned document on creation', () => {
+    const { doc, engine } = createEngine();
+    expect(engine.document.getDocument()).toBe(doc);
+    engine.lifecycle.dispose();
+  });
+
+  it('exposes an initial viewport and stores', () => {
+    const { engine } = createEngine();
+    expect(engine.viewport.getViewport().getZoom()).toBe(1);
+    expect(engine.stores.activeTool.get()).toBe('view');
+    expect(engine.stores.viewportReady.get()).toBe(false);
+    expect(engine.surface.attach).toBe(engine.surface.attach);
+    expect(engine.viewport.getViewport).toBe(engine.viewport.getViewport);
+    expect(engine.tools.setTool).toBeTypeOf('function');
+    expect(engine.history.undo).toBe(engine.history.undo);
+    expect(engine.lifecycle.beginCooldown).toBe(engine.lifecycle.beginCooldown);
+    expect(engine.edits.tryAcquire).toBeTypeOf('function');
+    engine.lifecycle.dispose();
+  });
+
+  it('exposes grouped capabilities without the deprecated flat facade', () => {
+    const { engine } = createEngine();
+    const deprecatedFlatMethods = [
+      'attach',
+      'beginCooldown',
+      'commitStructural',
+      'dispose',
+      'exportLayerPixels',
+      'fitToView',
+      'getDocument',
+      'processFilterOperation',
+      'setTool',
+      'startSelectObject',
+      'undo',
+    ] as const;
+
+    for (const method of deprecatedFlatMethods) {
+      expect(method in engine).toBe(false);
+    }
+    expect(engine.surface.attach).toBeTypeOf('function');
+    expect(engine.layers.commitStructural).toBeTypeOf('function');
+    expect(getCanvasOperations(engine).startSelectObject).toBeTypeOf('function');
+    expect(engine.exports.exportLayerPixels).toBeTypeOf('function');
+    engine.lifecycle.dispose();
+  });
+
+  it('invalidates edit leases across cooldown, reactivation, and disposal', async () => {
+    const { engine } = createEngine();
+    const first = engine.edits.tryAcquire({ kind: 'filter', layerId: 'a' });
+    expect(first?.isCurrent()).toBe(true);
+
+    await engine.lifecycle.beginCooldown();
+    expect(first?.signal.aborted).toBe(true);
+    expect(first?.isCurrent()).toBe(false);
+    expect(engine.edits.tryAcquire({ kind: 'filter', layerId: 'a' })).toBeNull();
+
+    engine.lifecycle.activate();
+    const second = engine.edits.tryAcquire({ kind: 'select-object', layerId: 'a' });
+    expect(second?.isCurrent()).toBe(true);
+    engine.lifecycle.dispose();
+    expect(second?.signal.aborted).toBe(true);
+    expect(second?.isCurrent()).toBe(false);
+  });
+
+  it('retains base pixels when cooldown persistence fails', async () => {
+    const doc = makeDoc();
+    const { store } = createFakeStore(doc);
+    const bitmapStore = createSpyBitmapStore();
+    vi.mocked(bitmapStore.flushPendingUploads).mockRejectedValueOnce(new Error('offline'));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const before = await engine.exports.exportLayerPixels('a');
+    expect(before.status).toBe('ok');
+
+    await expect(engine.lifecycle.beginCooldown()).resolves.toBe('dirty');
+    const retained = await engine.exports.exportLayerPixels('a');
+    expect(retained.status).toBe('ok');
+    if (before.status === 'ok' && retained.status === 'ok') {
+      expect(retained.surface).toBe(before.surface);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('retries persistence after a dirty cooldown result', async () => {
+    const doc = makeDoc();
+    const { store } = createFakeStore(doc);
+    const bitmapStore = createSpyBitmapStore();
+    vi.mocked(bitmapStore.flushPendingUploads)
+      .mockRejectedValueOnce(new Error('offline'))
+      .mockResolvedValueOnce(undefined);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    await expect(engine.lifecycle.beginCooldown()).resolves.toBe('dirty');
+    await expect(engine.lifecycle.beginCooldown()).resolves.toBe('cooled');
+
+    expect(bitmapStore.flushPendingUploads).toHaveBeenCalledTimes(2);
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps an in-flight invocation reservation accounted through cooldown', async () => {
+    const { engine } = createEngine();
+    const deps = engine.exports.getCompositeExecutorDeps();
+    const reservation = deps.reserve?.(300 * 1024 * 1024);
+    expect(reservation?.status).toBe('ok');
+
+    await engine.lifecycle.beginCooldown();
+
+    const competing = deps.reserve?.(300 * 1024 * 1024);
+    expect(competing?.status).toBe('over-budget');
+
+    if (reservation?.status === 'ok') {
+      reservation.lease.release();
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('does not release reconstructed pixels when reactivated during a cooldown flush', async () => {
+    const doc = makeDoc();
+    const { store } = createFakeStore(doc);
+    const bitmapStore = createSpyBitmapStore();
+    const flush = createDeferred<void>();
+    vi.mocked(bitmapStore.flushPendingUploads).mockReturnValueOnce(flush.promise);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const before = await engine.exports.exportLayerPixels('a');
+    const cooling = engine.lifecycle.beginCooldown();
+    engine.lifecycle.activate();
+    flush.resolve();
+    await cooling;
+
+    expect(engine.lifecycle.getLifecycleState()).toBe('active');
+    const retained = await engine.exports.exportLayerPixels('a');
+    if (before.status === 'ok' && retained.status === 'ok') {
+      expect(retained.surface).toBe(before.surface);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('exportLayerPixels rasterizes a visible layer and returns its cache surface plus content rect', async () => {
+    const { engine } = createEngine();
+
+    const result = await engine.exports.exportLayerPixels('a');
+
+    expect(result.status).toBe('ok');
+    if (result.status === 'ok') {
+      expect(result.rect).toEqual({ height: 10, width: 10, x: 0, y: 0 });
+      expect(result.surface.width).toBe(10);
+      expect(result.surface.height).toBe(10);
+      expect((result.surface as StubRasterSurface).callLog.some((entry) => entry.op === 'drawImage')).toBe(true);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('exportLayerPixels refuses hidden layers unless includeDisabled is set', async () => {
+    const hidden = { ...rasterLayer('hidden'), isEnabled: false };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [hidden] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.exports.exportLayerPixels('hidden')).toEqual({ status: 'disabled' });
+    expect((await engine.exports.exportLayerPixels('hidden', { includeDisabled: true })).status).toBe('ok');
+    engine.lifecycle.dispose();
+  });
+
+  it('exportLayerPixels can bake raster adjustments in layer-local space without baking presentation props', async () => {
+    const layer: CanvasRasterLayerContractV2 = {
+      ...(rasterLayer('a') as CanvasRasterLayerContractV2),
+      adjustments: { brightness: 0.25, contrast: 0, saturation: 0 },
+      blendMode: 'multiply',
+      opacity: 0.4,
+      source: {
+        bitmap: { height: 10, imageName: 'local-paint', width: 10 },
+        offset: { x: -4, y: 7 },
+        type: 'paint',
+      },
+      transform: { rotation: 0, scaleX: 2, scaleY: 3, x: 5, y: 6 },
+    };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [layer] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    const raw = await engine.exports.exportLayerPixels('a');
+    const adjusted = await engine.exports.exportLayerPixels('a', { applyAdjustments: true });
+
+    expect(raw.status).toBe('ok');
+    expect(adjusted.status).toBe('ok');
+    if (raw.status === 'ok' && adjusted.status === 'ok') {
+      expect(adjusted.rect).toEqual({ height: 10, width: 10, x: -4, y: 7 });
+      expect(adjusted.surface).not.toBe(raw.surface);
+      expect(adjusted.surface).toMatchObject({ height: 10, width: 10 });
+      expect(engine.exports.isLayerExportGuardCurrent(adjusted.guard)).toBe(true);
+      expect((raw.surface as StubRasterSurface).callLog.some((entry) => entry.op === 'putImageData')).toBe(false);
+      expect((adjusted.surface as StubRasterSurface).callLog).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ op: 'drawImage' }),
+          { args: [0, 0, 10, 10], op: 'getImageData' },
+          expect.objectContaining({ op: 'putImageData' }),
+        ])
+      );
+      expect(
+        (adjusted.surface as StubRasterSurface).callLog.some(
+          (entry) =>
+            entry.op === 'set' && (entry.args[0] === 'globalAlpha' || entry.args[0] === 'globalCompositeOperation')
+        )
+      ).toBe(false);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('exportLayerPixels shares the scheduled rasterization already running for the same source', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const pendingResolve = createDeferred<Blob>();
+    const imageResolver = vi.fn(() => pendingResolve.promise);
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver,
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    const exported = engine.exports.exportLayerPixels('a');
+    expect(imageResolver).toHaveBeenCalledTimes(1);
+
+    pendingResolve.resolve(new Blob());
+    expect((await exported).status).toBe('ok');
+    engine.lifecycle.dispose();
+  });
+
+  it('does not publish an older rasterization after a newer source wins', async () => {
+    const first = createDeferred<Blob>();
+    const second = createDeferred<Blob>();
+    const blobA = new Blob(['A']);
+    const blobB = new Blob(['B']);
+    const bitmapA = recordingBitmap('A');
+    const bitmapB = recordingBitmap('B');
+    const backend = createRecordingRasterBackend();
+    backend.createImageBitmap = vi.fn((blob) => Promise.resolve(blob === blobA ? bitmapA : bitmapB));
+    const imageResolver = vi.fn((imageName: string) => (imageName === 'A' ? first.promise : second.promise));
+    const document = { ...makeDoc(), layers: [rasterLayer('L', { imageName: 'A' })] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({ backend, imageResolver, projectId: 'p1', store });
+
+    const exportA = engine.exports.exportLayerPixels('L');
+    setDocument({ ...document, layers: [rasterLayer('L', { imageName: 'B' })] });
+    const exportB = engine.exports.exportLayerPixels('L');
+
+    second.resolve(blobB);
+    const resultB = await exportB;
+    expect(resultB.status).toBe('ok');
+    if (resultB.status !== 'ok') {
+      throw new Error('newer rasterization did not publish');
+    }
+    const publicationAfterB = backend.drawSourcesFor(resultB.surface as StubRasterSurface);
+
+    first.resolve(blobA);
+    expect(await exportA).toEqual({ status: 'not-ready' });
+    expect(backend.drawSourcesFor(resultB.surface as StubRasterSurface)).toEqual(publicationAfterB);
+    engine.lifecycle.dispose();
+  });
+
+  it('does not publish a rasterization from a replaced document that reuses the layer id', async () => {
+    const first = createDeferred<Blob>();
+    const second = createDeferred<Blob>();
+    const blobA = new Blob(['document-A']);
+    const blobB = new Blob(['document-B']);
+    const backend = createRecordingRasterBackend();
+    backend.createImageBitmap = vi.fn((blob) =>
+      Promise.resolve(blob === blobA ? recordingBitmap('document-A') : recordingBitmap('document-B'))
+    );
+    const imageResolver = vi.fn((imageName: string) => (imageName === 'A' ? first.promise : second.promise));
+    const document = { ...makeDoc(), layers: [rasterLayer('L', { imageName: 'A' })] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({ backend, imageResolver, projectId: 'p1', store });
+
+    const oldExport = engine.exports.exportLayerPixels('L');
+    setDocument({ ...document, layers: [rasterLayer('L', { imageName: 'B' })] }, 1);
+    const newExport = engine.exports.exportLayerPixels('L');
+
+    second.resolve(blobB);
+    const newResult = await newExport;
+    expect(newResult.status).toBe('ok');
+    if (newResult.status !== 'ok') {
+      throw new Error('replacement rasterization did not publish');
+    }
+    const publicationAfterReplacement = backend.drawSourcesFor(newResult.surface as StubRasterSurface);
+
+    first.resolve(blobA);
+    expect(await oldExport).toEqual({ status: 'not-ready' });
+    expect(backend.drawSourcesFor(newResult.surface as StubRasterSurface)).toEqual(publicationAfterReplacement);
+    engine.lifecycle.dispose();
+  });
+
+  it('shares one rasterization between concurrent exports of the same version', async () => {
+    const blob = new Blob(['shared']);
+    const imageResolver = vi.fn(() => Promise.resolve(blob));
+    const { store } = createFakeStore({ ...makeDoc(), layers: [rasterLayer('L')] });
+    const engine = createCanvasEngine({
+      backend: createRecordingRasterBackend(),
+      imageResolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const [a, b] = await Promise.all([engine.exports.exportLayerPixels('L'), engine.exports.exportLayerPixels('L')]);
+
+    expect(imageResolver).toHaveBeenCalledTimes(1);
+    expect(a.status).toBe('ok');
+    expect(b.status).toBe('ok');
+    engine.lifecycle.dispose();
+  });
+
+  it('does not return a default export when the layer becomes disabled during rasterization', async () => {
+    const pending = createDeferred<Blob>();
+    const layer = rasterLayer('L');
+    const document = { ...makeDoc(), layers: [layer] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => pending.promise,
+      projectId: 'p1',
+      store,
+    });
+
+    const exported = engine.exports.exportLayerPixels('L');
+    setDocument({ ...document, layers: [{ ...layer, isEnabled: false }] });
+    pending.resolve(new Blob());
+
+    expect(await exported).toEqual({ status: 'disabled' });
+    engine.lifecycle.dispose();
+  });
+
+  it('publishes an empty paint cache without drawing a zero-sized scratch canvas', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const empty = { ...rasterLayer('empty'), source: { bitmap: null, type: 'paint' } as const };
+    const { store } = createReactiveStore({ ...makeDoc(), layers: [empty] });
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const engine = createCanvasEngine({
+      backend: {
+        ...base,
+        createSurface: (width, height) => {
+          const surface = base.createSurface(width, height);
+          surfaces.push(surface);
+          return surface;
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+
+    const zeroSizedDraws = surfaces.flatMap((surface) =>
+      surface.callLog.filter((entry) => {
+        if (entry.op !== 'drawImage') {
+          return false;
+        }
+        const source = entry.args[0] as { height?: number; width?: number };
+        return source.width === 0 || source.height === 0;
+      })
+    );
+    expect(zeroSizedDraws).toEqual([]);
+    expect(await engine.exports.exportLayerPixels('empty')).toEqual({ status: 'empty' });
+    engine.lifecycle.dispose();
+  });
+
+  it('retries a same-version rasterization after a one-time synchronous rasterizer failure', async () => {
+    const shape: CanvasLayerSourceContract = {
+      fill: '#fff',
+      height: 10,
+      kind: 'rect',
+      stroke: null,
+      strokeWidth: 0,
+      type: 'shape',
+      width: 10,
+    };
+    const layer = { ...rasterLayer('shape'), source: shape };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [layer] });
+    const base = createTestStubRasterBackend();
+    let shouldThrow = true;
+    const engine = createCanvasEngine({
+      backend: {
+        ...base,
+        createSurface: (width, height) => {
+          const surface = base.createSurface(width, height);
+          const ctx = new Proxy(surface.ctx, {
+            get(target, property, receiver) {
+              if (property === 'fill') {
+                return (...args: unknown[]) => {
+                  if (shouldThrow) {
+                    shouldThrow = false;
+                    throw new Error('one-time fill failure');
+                  }
+                  return Reflect.apply(target.fill, target, args);
+                };
+              }
+              return Reflect.get(target, property, receiver);
+            },
+          });
+          Object.defineProperty(surface, 'ctx', { value: ctx });
+          return surface;
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.exports.exportLayerPixels('shape')).toEqual({ status: 'not-ready' });
+    expect((await engine.exports.exportLayerPixels('shape')).status).toBe('ok');
+    engine.lifecycle.dispose();
+  });
+
+  it('exportBakedLayerPixels draws the cache through the layer transform into a document-space surface', async () => {
+    const layer = {
+      ...rasterLayer('a'),
+      transform: { rotation: 0, scaleX: 2, scaleY: 3, x: 5, y: 6 },
+    };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [layer] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    const result = await engine.exports.exportBakedLayerPixels('a');
+
+    expect(result.status).toBe('ok');
+    if (result.status === 'ok') {
+      expect(result.rect).toEqual({ height: 30, width: 20, x: 5, y: 6 });
+      expect(result.surface.width).toBe(20);
+      expect(result.surface.height).toBe(30);
+      expect((result.surface as StubRasterSurface).callLog).toEqual(
+        expect.arrayContaining([
+          { args: [1, 0, 0, 1, 0, 0], op: 'setTransform' },
+          { args: [2, 0, 0, 3, 0, 0], op: 'setTransform' },
+          expect.objectContaining({ op: 'drawImage' }),
+        ])
+      );
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('exportBakedLayerPixels bakes raster adjustments into the exported surface only', async () => {
+    const layer = {
+      ...rasterLayer('a'),
+      adjustments: { brightness: 0.25, contrast: 0, saturation: 0 },
+    };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [layer] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    const raw = await engine.exports.exportLayerPixels('a');
+    const baked = await engine.exports.exportBakedLayerPixels('a');
+
+    expect(raw.status).toBe('ok');
+    expect(baked.status).toBe('ok');
+    if (raw.status === 'ok' && baked.status === 'ok') {
+      expect(baked.surface).not.toBe(raw.surface);
+      expect((raw.surface as StubRasterSurface).callLog.some((entry) => entry.op === 'putImageData')).toBe(false);
+      expect((baked.surface as StubRasterSurface).callLog).toEqual(
+        expect.arrayContaining([
+          { args: [0, 0, 10, 10], op: 'getImageData' },
+          expect.objectContaining({ op: 'putImageData' }),
+        ])
+      );
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('exportBakedLayerPixels applies adjustments exactly once when explicitly requested', async () => {
+    const layer = {
+      ...rasterLayer('a'),
+      adjustments: { brightness: 0.25, contrast: 0, saturation: 0 },
+    };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [layer] });
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const engine = createCanvasEngine({
+      backend: {
+        ...base,
+        createSurface: (width, height) => {
+          const surface = base.createSurface(width, height);
+          surfaces.push(surface);
+          return surface;
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect((await engine.exports.exportBakedLayerPixels('a', { applyAdjustments: true })).status).toBe('ok');
+
+    expect(surfaces.flatMap((surface) => surface.callLog).filter((entry) => entry.op === 'getImageData')).toHaveLength(
+      1
+    );
+    engine.lifecycle.dispose();
+  });
+
+  it('exportBakedLayerBlob encodes the baked layer surface as PNG', async () => {
+    const { engine } = createEngine();
+
+    const result = await engine.exports.exportBakedLayerBlob('a');
+
+    expect(result.status).toBe('ok');
+    if (result.status === 'ok') {
+      expect(result.rect).toEqual({ height: 10, width: 10, x: 0, y: 0 });
+      expect(result.blob.type).toBe('image/png');
+      expect(await result.blob.text()).toBe('stub-surface-10x10');
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('returns a current LayerExportGuard from local, baked-pixel, and baked-blob exports', async () => {
+    const { doc, engine } = createEngine();
+
+    const local = await engine.exports.exportLayerPixels('a');
+    const baked = await engine.exports.exportBakedLayerPixels('a');
+    const blob = await engine.exports.exportBakedLayerBlob('a');
+
+    expect(local.status).toBe('ok');
+    expect(baked.status).toBe('ok');
+    expect(blob.status).toBe('ok');
+    if (local.status !== 'ok' || baked.status !== 'ok' || blob.status !== 'ok') {
+      throw new Error('expected successful exports');
+    }
+    for (const result of [local, baked, blob]) {
+      expect(result.guard).toMatchObject({ layer: doc.layers[0], layerId: 'a', projectId: 'p1' });
+      expect(engine.exports.isLayerExportGuardCurrent(result.guard)).toBe(true);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('captures the current layer export guard synchronously after its cache is ready', async () => {
+    const { engine } = createEngine();
+    await engine.exports.exportLayerPixels('a');
+
+    const guard = engine.exports.captureLayerExportGuard('a');
+
+    expect(guard).not.toBeNull();
+    expect(guard).toMatchObject({ layerId: 'a', projectId: 'p1' });
+    expect(engine.exports.isLayerExportGuardCurrent(guard!)).toBe(true);
+    expect(engine.exports.captureLayerExportGuard('missing')).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('invalidates a LayerExportGuard when the immutable layer contract changes', async () => {
+    const document = makeDoc();
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('a');
+    expect(exported.status).toBe('ok');
+    if (exported.status !== 'ok') {
+      throw new Error('expected successful export');
+    }
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(engine).controller.start({
+      cleanupPreview,
+      guard: exported.guard,
+      identity: { kind: 'filter', layerId: 'a', projectId: 'p1' },
+    });
+
+    setDocument({ ...document, layers: [{ ...document.layers[0]!, opacity: 0.5 }] });
+
+    expect(engine.exports.isLayerExportGuardCurrent(exported.guard)).toBe(false);
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    engine.lifecycle.dispose();
+  });
+
+  it('invalidates a canvas operation when its layer source changes or its layer is removed', async () => {
+    for (const nextLayers of [
+      [
+        {
+          ...makeDoc().layers[0]!,
+          source: { image: { height: 10, imageName: 'replacement', width: 10 }, type: 'image' as const },
+        },
+      ],
+      [],
+    ]) {
+      const document = makeDoc();
+      const { setDocument, store } = createReactiveStore(document);
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels('a');
+      if (exported.status !== 'ok') {
+        throw new Error('expected successful export');
+      }
+      const cleanupPreview = vi.fn();
+      getCanvasOperations(engine).controller.start({
+        cleanupPreview,
+        guard: exported.guard,
+        identity: { kind: 'filter', layerId: 'a', projectId: 'p1' },
+      });
+
+      setDocument({ ...document, layers: nextLayers });
+
+      expect(cleanupPreview).toHaveBeenCalledOnce();
+      expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+      engine.lifecycle.dispose();
+    }
+  });
+
+  it('invalidates a LayerExportGuard when the document is replaced with the same layer object', async () => {
+    const document = makeDoc();
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('a');
+    expect(exported.status).toBe('ok');
+    if (exported.status !== 'ok') {
+      throw new Error('expected successful export');
+    }
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(engine).controller.start({
+      cleanupPreview,
+      guard: exported.guard,
+      identity: { kind: 'filter', layerId: 'a', projectId: 'p1' },
+    });
+
+    setDocument({ ...document, layers: document.layers }, 1);
+
+    expect(engine.exports.isLayerExportGuardCurrent(exported.guard)).toBe(false);
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps a project-bound LayerExportGuard current when another project becomes active', async () => {
+    const document = makeDoc();
+    const { setActiveProjectId, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('a');
+    expect(exported.status).toBe('ok');
+    if (exported.status !== 'ok') {
+      throw new Error('expected successful export');
+    }
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(engine).controller.start({
+      cleanupPreview,
+      guard: exported.guard,
+      identity: { kind: 'filter', layerId: 'a', projectId: 'p1' },
+    });
+
+    setActiveProjectId('p2');
+
+    expect(engine.exports.isLayerExportGuardCurrent(exported.guard)).toBe(true);
+    expect(cleanupPreview).not.toHaveBeenCalled();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({ status: 'active' });
+    engine.lifecycle.dispose();
+  });
+
+  it('disposes the active canvas operation with the engine', async () => {
+    const { engine } = createEngine();
+    const exported = await engine.exports.exportLayerPixels('a');
+    if (exported.status !== 'ok') {
+      throw new Error('expected successful export');
+    }
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(engine).controller.start({
+      cleanupPreview,
+      guard: exported.guard,
+      identity: { kind: 'filter', layerId: 'a', projectId: 'p1' },
+    });
+
+    engine.lifecycle.dispose();
+
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(
+      getCanvasOperations(engine).controller.start({
+        cleanupPreview,
+        guard: exported.guard,
+        identity: { kind: 'filter', layerId: 'a', projectId: 'p1' },
+      })
+    ).toBeNull();
+  });
+
+  it('does not return an encoded layer blob after its export guard becomes stale', async () => {
+    const encoded = createDeferred<Blob>();
+    const base = createTestStubRasterBackend();
+    const encodeSurface = vi.fn(() => encoded.promise);
+    const document = makeDoc();
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: { ...base, encodeSurface },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    const pending = engine.exports.exportBakedLayerBlob('a');
+    await vi.waitFor(() => expect(encodeSurface).toHaveBeenCalledOnce());
+    setDocument({ ...document, layers: [{ ...document.layers[0]!, opacity: 0.5 }] });
+    encoded.resolve(new Blob(['stale'], { type: 'image/png' }));
+
+    expect(await pending).toEqual({ status: 'not-ready' });
+    engine.lifecycle.dispose();
+  });
+
+  it('invalidates a LayerExportGuard when live cache pixels are edited', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const document = paintDoc();
+    const layer = document.layers[0];
+    if (!layer || layer.type !== 'raster') {
+      throw new Error('expected paint layer');
+    }
+    const persisted: CanvasDocumentContractV2 = {
+      ...document,
+      layers: [
+        {
+          ...layer,
+          source: { bitmap: { height: 20, imageName: 'paint-pixels', width: 20 }, type: 'paint' },
+        },
+      ],
+    };
+    const { projectId, store } = createReducerBackedStore(persisted);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    const exported = await engine.exports.exportLayerPixels(layer.id);
+    expect(exported.status).toBe('ok');
+    if (exported.status !== 'ok') {
+      throw new Error('expected successful export');
+    }
+
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(5, 5));
+    overlay.fire('pointermove', pointerAt(10, 10));
+    overlay.fire('pointerup', pointerAt(10, 10, { buttons: 0 }));
+
+    expect(engine.exports.isLayerExportGuardCurrent(exported.guard)).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox crops only the bbox overlap and restores exact contracts/cache snapshots on undo/redo', async () => {
+    const layer = {
+      ...rasterLayer('a'),
+      adjustments: { brightness: 0.2, contrast: -0.1, saturation: 0.3 },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 5, y: 5 },
+    };
+    const document = { ...makeDoc(), bbox: { height: 8, width: 10, x: 8, y: 2 }, layers: [layer] };
+    const { projectId, store } = createReducerBackedStore(document);
+    const backend = createRecordingRasterBackend();
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const beforeContract = structuredClone(engine.document.getDocument()!.layers[0]!);
+    const beforeExport = await engine.exports.exportLayerPixels('a');
+    expect(beforeExport.status).toBe('ok');
+    if (beforeExport.status !== 'ok') {
+      throw new Error('expected original cache pixels');
+    }
+    const thumbnailListener = vi.fn();
+    engine.stores.thumbnailVersion.subscribeKey('a', thumbnailListener);
+    bitmapStore.markLayerDirty.mockClear();
+
+    expect(await engine.layers.cropLayerToBbox('a')).toEqual({ status: 'cropped' });
+
+    const afterContract = engine.document.getDocument()!.layers[0]!;
+    expect(afterContract).toEqual({
+      blendMode: 'normal',
+      id: 'a',
+      isEnabled: true,
+      isLocked: false,
+      name: 'a',
+      opacity: 1,
+      source: { bitmap: null, offset: { x: 8, y: 5 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    expect('adjustments' in afterContract).toBe(false);
+    expect(bitmapStore.markLayerDirty).toHaveBeenCalledTimes(1);
+    expect(thumbnailListener).toHaveBeenCalledTimes(1);
+    const forwardExport = await engine.exports.exportLayerPixels('a');
+    expect(forwardExport.status).toBe('ok');
+    if (forwardExport.status !== 'ok') {
+      throw new Error('expected cropped cache pixels');
+    }
+    expect(forwardExport.rect).toEqual({ height: 5, width: 7, x: 8, y: 5 });
+    const forwardSources = backend.drawSourcesFor(forwardExport.surface as StubRasterSurface);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(beforeContract);
+    expect(bitmapStore.markLayerDirty).toHaveBeenCalledTimes(2);
+    expect(thumbnailListener).toHaveBeenCalledTimes(2);
+    const undoExport = await engine.exports.exportLayerPixels('a');
+    expect(undoExport.status).toBe('ok');
+    if (undoExport.status !== 'ok') {
+      throw new Error('expected restored cache pixels');
+    }
+    const undoSources = backend.drawSourcesFor(undoExport.surface as StubRasterSurface);
+    const beforeSnapshot = backend.surfaceById(undoSources.at(-1)!);
+    expect(beforeSnapshot).toBeDefined();
+    expect(backend.drawSourcesFor(beforeSnapshot!)).toContain(
+      backend.surfaceId(beforeExport.surface as StubRasterSurface)
+    );
+
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(afterContract);
+    expect(bitmapStore.markLayerDirty).toHaveBeenCalledTimes(3);
+    expect(thumbnailListener).toHaveBeenCalledTimes(3);
+    const redoExport = await engine.exports.exportLayerPixels('a');
+    expect(redoExport.status).toBe('ok');
+    if (redoExport.status !== 'ok') {
+      throw new Error('expected redone cache pixels');
+    }
+    expect(backend.drawSourcesFor(redoExport.surface as StubRasterSurface)).toEqual(forwardSources);
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox preserves control adapter settings while removing the baked filter', async () => {
+    const control: CanvasLayerContract = {
+      adapter: {
+        beginEndStepPct: [0.1, 0.9],
+        controlMode: 'more_control',
+        kind: 'controlnet',
+        model: 'm',
+        weight: 0.7,
+      },
+      blendMode: 'screen',
+      filter: { settings: { low: 10 }, type: 'canny' },
+      id: 'control',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Control',
+      opacity: 0.6,
+      source: { image: { height: 10, imageName: 'control', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'control',
+      withTransparencyEffect: true,
+    };
+    const document = { ...makeDoc(), bbox: { height: 7, width: 6, x: 2, y: 3 }, layers: [control] };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    expect(await engine.layers.cropLayerToBbox('control')).toEqual({ status: 'cropped' });
+    const cropped = engine.document.getDocument()!.layers[0];
+    expect(cropped).toMatchObject({
+      adapter: control.adapter,
+      source: { bitmap: null, offset: { x: 2, y: 3 }, type: 'paint' },
+      type: 'control',
+      withTransparencyEffect: true,
+    });
+    expect(cropped && 'filter' in cropped).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox preserves mask fill/noise/denoise configuration while replacing pixels and offset', async () => {
+    const layer: CanvasInpaintMaskLayerContract = {
+      ...maskLayer('mask'),
+      denoiseLimit: 0.45,
+      mask: {
+        bitmap: { height: 10, imageName: 'mask-img', width: 10 },
+        fill: { color: '#123456', style: 'crosshatch' },
+        offset: { x: 0, y: 0 },
+      },
+      noiseLevel: 0.25,
+    };
+    const document = { ...makeDoc(), bbox: { height: 7, width: 6, x: 2, y: 3 }, layers: [layer] };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    expect(await engine.layers.cropLayerToBbox('mask')).toEqual({ status: 'cropped' });
+    expect(engine.document.getDocument()!.layers[0]).toMatchObject({
+      denoiseLimit: 0.45,
+      mask: { bitmap: null, fill: layer.mask.fill, offset: { x: 2, y: 3 } },
+      noiseLevel: 0.25,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'inpaint_mask',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox preserves regional prompts and reference images while replacing mask pixels', async () => {
+    const layer: CanvasLayerContract = {
+      autoNegative: false,
+      blendMode: 'normal',
+      id: 'region',
+      isEnabled: true,
+      isLocked: false,
+      mask: {
+        bitmap: { height: 10, imageName: 'region-mask', width: 10 },
+        fill: { color: '#abcdef', style: 'vertical' },
+      },
+      name: 'Region',
+      negativePrompt: 'negative',
+      opacity: 0.8,
+      positivePrompt: 'positive',
+      referenceImages: [{ config: { image: null, type: 'flux2_reference_image' }, id: 'reference', isEnabled: true }],
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'regional_guidance',
+    };
+    const document = { ...makeDoc(), bbox: { height: 7, width: 6, x: 2, y: 3 }, layers: [layer] };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    expect(await engine.layers.cropLayerToBbox('region')).toEqual({ status: 'cropped' });
+    expect(engine.document.getDocument()!.layers[0]).toMatchObject({
+      autoNegative: false,
+      mask: { bitmap: null, fill: layer.mask.fill, offset: { x: 2, y: 3 } },
+      negativePrompt: 'negative',
+      positivePrompt: 'positive',
+      referenceImages: layer.referenceImages,
+      type: 'regional_guidance',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox returns empty without mutation when the layer and bbox do not overlap', async () => {
+    const document = { ...makeDoc(), bbox: { height: 5, width: 5, x: 50, y: 50 } };
+    const { projectId, store } = createReducerBackedStore(document);
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const before = engine.document.getDocument();
+
+    expect(await engine.layers.cropLayerToBbox('a')).toEqual({ status: 'empty' });
+    expect(engine.document.getDocument()).toBe(before);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox reports missing, locked, unsupported, and not-ready layers explicitly', async () => {
+    const polygon: CanvasLayerSourceContract = {
+      fill: '#000',
+      height: 10,
+      kind: 'polygon',
+      points: [
+        { x: 0, y: 0 },
+        { x: 10, y: 0 },
+        { x: 5, y: 10 },
+      ],
+      stroke: null,
+      strokeWidth: 0,
+      type: 'shape',
+      width: 10,
+    };
+    const layers = [
+      { ...rasterLayer('locked'), isLocked: true },
+      { ...rasterLayer('polygon'), source: polygon },
+      rasterLayer('pending'),
+    ];
+    const document = { ...makeDoc(), layers };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.reject(new Error('decode failed')),
+      projectId,
+      store,
+    });
+
+    expect(await engine.layers.cropLayerToBbox('missing')).toEqual({ status: 'missing' });
+    expect(await engine.layers.cropLayerToBbox('locked')).toEqual({ status: 'locked' });
+    expect(await engine.layers.cropLayerToBbox('polygon')).toEqual({ status: 'unsupported' });
+    expect(await engine.layers.cropLayerToBbox('pending')).toEqual({ status: 'not-ready' });
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox returns not-ready without mutation when the source changes during rasterization', async () => {
+    const pending = createDeferred<Blob>();
+    const document = { ...makeDoc(), layers: [rasterLayer('a', { imageName: 'A' })] };
+    const { setDocument, store } = createReactiveStore(document);
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => pending.promise,
+      projectId: 'p1',
+      store,
+    });
+
+    const crop = engine.layers.cropLayerToBbox('a');
+    setDocument({ ...document, layers: [rasterLayer('a', { imageName: 'B' })] });
+    pending.resolve(new Blob());
+
+    expect(await crop).toEqual({ status: 'not-ready' });
+    expect(store.dispatch).not.toHaveBeenCalled();
+    expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox aborts when an operation starts during its deferred export', async () => {
+    const pending = createDeferred<Blob>();
+    const document = { ...makeDoc(), layers: [rasterLayer('operation'), rasterLayer('a')] };
+    const { projectId, store } = createReducerBackedStore(document);
+    const bitmapStore = createSpyBitmapStore();
+    const resolver = vi.fn((imageName: string) => (imageName === 'a' ? pending.promise : Promise.resolve(new Blob())));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: resolver,
+      projectId,
+      store,
+    });
+    const operationExport = await engine.exports.exportLayerPixels('operation');
+    if (operationExport.status !== 'ok') {
+      throw new Error('expected an operation guard');
+    }
+    (store.dispatch as Mock).mockClear();
+    bitmapStore.markLayerDirty.mockClear();
+
+    const crop = engine.layers.cropLayerToBbox('a');
+    await vi.waitFor(() => expect(resolver).toHaveBeenCalledWith('a', expect.any(AbortSignal)));
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(engine).controller.start({
+      cleanupPreview,
+      guard: operationExport.guard,
+      identity: { kind: 'filter', layerId: 'operation', projectId },
+    });
+    pending.resolve(new Blob());
+
+    await expect(crop).resolves.toEqual({ status: 'busy' });
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(store.dispatch).not.toHaveBeenCalled();
+    expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(cleanupPreview).not.toHaveBeenCalled();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'filter', layerId: 'operation' },
+      status: 'active',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox reports busy during an open gesture', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const paint = {
+      ...rasterLayer('paint'),
+      source: { bitmap: { height: 10, imageName: 'paint', width: 10 }, type: 'paint' as const },
+    };
+    const busyHarness = createReducerBackedStore({ ...makeDoc(), layers: [paint], selectedLayerId: 'paint' });
+    const busyEngine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: busyHarness.projectId,
+      store: busyHarness.store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    busyEngine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    busyEngine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(2, 2));
+    expect(await busyEngine.layers.cropLayerToBbox('paint')).toEqual({ status: 'busy' });
+    overlay.fire('pointerup', pointerAt(2, 2, { buttons: 0 }));
+    busyEngine.lifecycle.dispose();
+  });
+
+  it('cropLayerToBbox reports failed for unexpected raster errors', async () => {
+    const base = createTestStubRasterBackend();
+    const failedHarness = createReducerBackedStore({
+      ...makeDoc(),
+      bbox: { height: 7, width: 6, x: 2, y: 3 },
+    });
+    const failedEngine = createCanvasEngine({
+      backend: {
+        ...base,
+        createSurface: (width, height) => {
+          if (width === 6 && height === 7) {
+            throw new Error('crop allocation failed');
+          }
+          return base.createSurface(width, height);
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: failedHarness.projectId,
+      store: failedHarness.store,
+    });
+    expect(await failedEngine.layers.cropLayerToBbox('a')).toEqual({
+      message: 'crop allocation failed',
+      status: 'failed',
+    });
+    failedEngine.lifecycle.dispose();
+  });
+
+  it('copyLayerToRaster finishes in its bound project after another project becomes active', async () => {
+    const pending = createDeferred<Blob>();
+    const document = makeDoc();
+    const { setActiveProjectId, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => pending.promise,
+      projectId: 'p1',
+      store,
+    });
+
+    const copy = engine.layers.copyLayerToRaster('a');
+    setActiveProjectId('p2');
+    pending.resolve(new Blob());
+
+    expect(await copy).not.toBeNull();
+    expect(store.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: 'applyCanvasLayerStackMutation' }));
+    engine.lifecycle.dispose();
+  });
+
+  it('copyLayerToRaster adds a baked paint copy directly above the source layer', async () => {
+    const doc = { ...makeDoc(), layers: [rasterLayer('top'), rasterLayer('a')] };
+    const { projectId, store } = createReducerBackedStore(doc);
+    const dispatch = store.dispatch as Mock;
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const engine = createCanvasEngine({
+      backend: {
+        ...base,
+        createSurface: (width, height) => {
+          const surface = base.createSurface(width, height);
+          surfaces.push(surface);
+          return surface;
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    const newId = await engine.layers.copyLayerToRaster('a');
+
+    expect(newId).toMatch(/^layer-/);
+    const mutation = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .find((action) => action.type === 'applyCanvasLayerStackMutation');
+    expect(mutation).toBeDefined();
+    const added = mutation?.type === 'applyCanvasLayerStackMutation' ? mutation.add : undefined;
+    const addedLayer = added?.layers[0];
+    if (added && addedLayer?.type === 'raster') {
+      expect(added.index).toBe(1);
+      expect(addedLayer.id).toBe(newId);
+      expect(addedLayer.name).toBe('a copy');
+      expect(addedLayer.source).toEqual({ bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' });
+      expect(addedLayer.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+    } else {
+      throw new Error('expected atomic layer-stack mutation with raster copy');
+    }
+    expect(
+      surfaces.some(
+        (surface) =>
+          surface.width === 10 && surface.height === 10 && surface.callLog.some((entry) => entry.op === 'drawImage')
+      )
+    ).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('copyLayerToRaster returns null for empty layers', async () => {
+    const empty = { ...rasterLayer('empty'), source: { bitmap: null, type: 'paint' } as const };
+    const { store } = createFakeStore({ ...makeDoc(), layers: [empty] });
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.layers.copyLayerToRaster('empty')).toBeNull();
+    expect(dispatch).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+
+  it('copyLayerToRaster records mask copies in engine history', async () => {
+    const mask: CanvasInpaintMaskLayerContract = {
+      ...maskLayer('mask'),
+      mask: {
+        bitmap: { height: 10, imageName: 'mask-image', width: 10 },
+        fill: { color: '#e07575', style: 'diagonal' },
+      },
+    };
+    const { projectId, store } = createReducerBackedStore({ ...makeDoc(), layers: [mask] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    const newId = await engine.layers.copyLayerToRaster('mask');
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === newId)).toBe(true);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === newId)).toBe(false);
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === newId)).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('copyLayerToRaster redo cache failure leaves the copy absent and retryable', async () => {
+    const { projectId, store } = createReducerBackedStore(makeDoc());
+    const base = createTestStubRasterBackend();
+    let failNextAllocation = false;
+    const engine = createCanvasEngine({
+      backend: {
+        ...base,
+        createSurface: (width, height) => {
+          if (failNextAllocation) {
+            failNextAllocation = false;
+            throw new Error('copy replay allocation failed');
+          }
+          return base.createSurface(width, height);
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    const newId = await engine.layers.copyLayerToRaster('a');
+    expect(newId).not.toBeNull();
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.filter((layer) => layer.id === newId)).toHaveLength(0);
+
+    failNextAllocation = true;
+    expect(() => engine.history.redo()).toThrow('copy replay allocation failed');
+
+    expect(engine.document.getDocument()!.layers.filter((layer) => layer.id === newId)).toHaveLength(0);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers.filter((layer) => layer.id === newId)).toHaveLength(1);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.filter((layer) => layer.id === newId)).toHaveLength(0);
+    engine.lifecycle.dispose();
+  });
+
+  it('setTool switches the active tool and updates the store', () => {
+    const { engine } = createEngine();
+    const listener = vi.fn();
+    engine.stores.activeTool.subscribe(listener);
+
+    engine.tools.setTool('brush');
+    expect(engine.stores.activeTool.get()).toBe('brush');
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    // Setting the same tool again is a no-op.
+    engine.tools.setTool('brush');
+    expect(listener).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('interaction lock forces view and refuses non-view tools until unlocked', () => {
+    const { engine } = createEngine();
+
+    engine.tools.setTool('brush');
+    expect(engine.stores.activeTool.get()).toBe('brush');
+
+    engine.tools.setInteractionLocked(true);
+    expect(engine.stores.activeTool.get()).toBe('view');
+
+    engine.tools.setTool('bbox');
+    expect(engine.stores.activeTool.get()).toBe('view');
+
+    engine.tools.setTool('colorPicker');
+    expect(engine.stores.activeTool.get()).toBe('view');
+
+    engine.tools.setInteractionLocked(false);
+    engine.tools.setTool('bbox');
+    expect(engine.stores.activeTool.get()).toBe('bbox');
+
+    engine.lifecycle.dispose();
+  });
+
+  it('registers the brush and eraser tools', () => {
+    const { engine } = createEngine();
+    engine.tools.setTool('brush');
+    expect(engine.stores.activeTool.get()).toBe('brush');
+    engine.tools.setTool('eraser');
+    expect(engine.stores.activeTool.get()).toBe('eraser');
+    engine.lifecycle.dispose();
+  });
+
+  it('onStrokeCommitted returns an unsubscribe and never fires without a stroke', () => {
+    const { engine } = createEngine();
+    const listener = vi.fn();
+    const unsubscribe = engine.tools.onStrokeCommitted(listener);
+    expect(typeof unsubscribe).toBe('function');
+    unsubscribe();
+    expect(listener).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+
+  it('resize records the viewport size and clamps the device-pixel ratio', () => {
+    const { engine } = createEngine();
+    engine.surface.resize(800, 600, 4);
+    expect(engine.viewport.getViewport().getViewportSize()).toEqual({ height: 600, width: 800 });
+    expect(engine.viewport.getViewport().getDpr()).toBe(2);
+    engine.lifecycle.dispose();
+  });
+
+  it('dispose removes both store subscriptions', () => {
+    const { engine, unsubscribe } = createEngine();
+    expect(unsubscribe).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+    expect(unsubscribe).toHaveBeenCalledOnce();
+  });
+
+  it('dispose is idempotent', () => {
+    const { engine, unsubscribe } = createEngine();
+    engine.lifecycle.dispose();
+    engine.lifecycle.dispose();
+    expect(unsubscribe).toHaveBeenCalledOnce();
+  });
+});
+
+describe('document mirror wiring: layer reorder', () => {
+  it('recomposites in the new z-order without re-rasterizing any layer', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const a = rasterLayer('a', { opacity: 0.25 });
+    const b = rasterLayer('b', { opacity: 0.75 });
+    const doc: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [a, b],
+      selectedLayerId: null,
+      version: 2,
+      width: 100,
+    };
+    const { setDocument, store } = createReactiveStore(doc);
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+
+    // Initial frame: dispatches (and, after a microtask flush, completes) the
+    // rasterize for both layers.
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush(); // the follow-up frame each rasterize's resolve scheduled
+    expect(resolver).toHaveBeenCalledTimes(2);
+
+    // Isolate the reorder-triggered frame's draw log.
+    screen.surface.callLog.length = 0;
+
+    // Pure reorder: new array reference, same layer object references, swapped order.
+    setDocument({ ...doc, layers: [b, a] });
+    raf.flush();
+
+    // No layer content changed, so nothing should be re-rasterized.
+    expect(resolver).toHaveBeenCalledTimes(2);
+
+    // The compositor draws bottom-to-top; `a` (alpha 0.25) is now the bottom
+    // layer and `b` (alpha 0.75) the top, so alpha is applied in that order.
+    const alphaOrder = screen.surface.callLog
+      .filter((entry) => entry.op === 'set' && entry.args[0] === 'globalAlpha')
+      .map((entry) => entry.args[1]);
+    expect(alphaOrder).toEqual([0.25, 0.75]);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('layer removal: adjusted-surface cache cleanup', () => {
+  it("drops the removed layer's adjusted surface (no cache leak)", async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    adjustedSurfaceCacheDeletes.length = 0;
+
+    const doc: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [rasterLayer('a'), rasterLayer('b')],
+      selectedLayerId: null,
+      version: 2,
+      width: 100,
+    };
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    engine.surface.attach(createFakeCanvas().element, createFakeCanvas().element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    // Still present: nothing removed yet.
+    expect(adjustedSurfaceCacheDeletes).not.toContain('a');
+
+    // Remove layer 'a' via an ordinary layer-array edit (onLayersChanged → dropLayer).
+    setDocument({ ...doc, layers: [rasterLayer('b')] });
+    raf.flush();
+
+    // The removed layer's adjusted-surface slot is dropped alongside its layer cache.
+    expect(adjustedSurfaceCacheDeletes).toContain('a');
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('resize: synchronous composite (no flash/strobe on panel drag)', () => {
+  it('composites in the SAME task as the backing-store resize, scheduling no deferred frame', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const doc = makeDoc();
+    const { store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+
+    // Run the initial attach frame so the surface holds a composited frame, then
+    // isolate what the resize alone draws.
+    raf.flush();
+    screen.surface.callLog.length = 0;
+
+    // A single resize event (as a ResizeObserver fires mid panel-drag). Sizing a
+    // `<canvas>` backing store CLEARS it; the fix recomposites synchronously so the
+    // cleared surface is repainted before the browser paints (no blank frame).
+    // No `raf.flush()` follows — so any draw seen here happened IN-TASK.
+    engine.surface.resize(800, 600, 1);
+
+    // Backing store was resized in the same call...
+    expect(screen.element.width).toBe(800);
+    expect(screen.element.height).toBe(600);
+    // ...and the composite ran SYNCHRONOUSLY (drew into the surface without a rAF
+    // flush). `compositeDocument` always clears the target, so a `clearRect` here
+    // proves the recomposite happened in-task rather than being deferred to rAF.
+    const composited = screen.surface.callLog.some((entry) => entry.op === 'clearRect');
+    expect(composited).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('schedules NO deferred frame after the synchronous composite (exactly one composite per resize)', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const doc = makeDoc();
+    const { store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    screen.surface.callLog.length = 0;
+
+    engine.surface.resize(800, 600, 1);
+
+    // The synchronous composite ran...
+    expect(screen.surface.callLog.some((entry) => entry.op === 'clearRect')).toBe(true);
+    // ...and setViewportSize's viewport-subscription `{ view: true }` invalidate was
+    // suppressed, so NO rAF frame is queued to recomposite the identical content.
+    expect(raf.pendingCount()).toBe(0);
+
+    // Draining any frame anyway must not produce a second composite.
+    screen.surface.callLog.length = 0;
+    raf.flush();
+    expect(screen.surface.callLog.some((entry) => entry.op === 'clearRect')).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('marks the composite dirty flag so the synchronous path is not gated out (T22)', () => {
+    // A resize must force a full recomposite even though no layer pixels changed:
+    // if it only marked `overlay`, the T22 `needsComposite` gate would skip the
+    // composite and the just-cleared screen surface would stay blank.
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const doc = makeDoc();
+    const { store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    screen.surface.callLog.length = 0;
+
+    engine.surface.resize(320, 240, 2);
+
+    // The screen (document composite) surface — not just the overlay — was redrawn.
+    expect(screen.surface.callLog.some((entry) => entry.op === 'clearRect')).toBe(true);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('ensureLayerCaches: edit-during-rasterize race', () => {
+  it('re-rasterizes with the newest source when an edit lands while a rasterize is in flight', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const doc = makeDoc(); // single layer 'a', imageName 'a'
+    const { setDocument, store } = createReactiveStore(doc);
+
+    const deferreds = new Map<string, ReturnType<typeof createDeferred<Blob>>>();
+    const resolver = vi.fn((imageName: string) => {
+      const deferred = createDeferred<Blob>();
+      deferreds.set(imageName, deferred);
+      return deferred.promise;
+    });
+
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+
+    // Subscribe to thumbnail-version notifications for layer 'a' *before* either
+    // rasterize settles. A bare `.get()` check at the end can't distinguish
+    // "notified once, at the wrong time, with stale pixels on the surface" from
+    // "notified once, at the right time, with fresh pixels on the surface" --
+    // both leave the same final version number. Tracking call count/timing does.
+    const thumbnailListener = vi.fn();
+    const unsubscribe = engine.stores.thumbnailVersion.subscribeKey('a', thumbnailListener);
+
+    // Frame 1: dispatches the first rasterize for imageName 'a'; it stays in flight
+    // (the deferred is never auto-resolved).
+    raf.flush();
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(resolver).toHaveBeenNthCalledWith(1, 'a', expect.any(AbortSignal));
+
+    // An edit lands mid-flight: same layer id, new object reference, new source.
+    setDocument({ ...doc, layers: [rasterLayer('a', { imageName: 'a-v2' })] });
+
+    // A frame runs while the first rasterize is still in flight. The source no
+    // longer matches that job, so a fresh isolated job starts immediately.
+    raf.flush();
+    expect(resolver).toHaveBeenCalledTimes(2);
+    expect(resolver).toHaveBeenNthCalledWith(2, 'a-v2', expect.any(AbortSignal));
+
+    // The newer rasterize wins and publishes while the old decode is pending.
+    deferreds.get('a-v2')!.resolve(new Blob());
+    await flushMicrotasks();
+    raf.flush();
+    expect(thumbnailListener).toHaveBeenCalledTimes(1);
+    expect(engine.stores.thumbnailVersion.get('a')).toBe(2);
+
+    // The older decode resolves afterwards. It may finish its isolated scratch
+    // draw, but it must neither publish nor notify subscribers.
+    deferreds.get('a')!.resolve(new Blob());
+    await flushMicrotasks();
+    raf.flush();
+    expect(thumbnailListener).toHaveBeenCalledTimes(1);
+    expect(resolver).toHaveBeenCalledTimes(2);
+
+    unsubscribe();
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- Engine-owned history (P2.3) --------------------------------------
+//
+// Drives a real brush stroke end-to-end through the engine (attach → dispatch
+// pointer events → commit) and asserts the history wiring: strokeCommitted pushes
+// an image patch, undo/redo write the before/after pixels back into the layer's
+// cache surface AND re-mark the layer dirty for persistence, and the canUndo /
+// canRedo stores track the stacks.
+
+const paintDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [
+    {
+      blendMode: 'normal',
+      id: 'paint1',
+      isEnabled: true,
+      isLocked: false,
+      name: 'paint1',
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    },
+  ],
+  selectedLayerId: 'paint1',
+  version: 2,
+  width: 100,
+});
+
+type ControlPaintHarnessOverrides = Partial<Omit<CanvasControlLayerContract, 'source' | 'type'>> & {
+  source: CanvasControlLayerContract['source'];
+};
+
+interface ControlPaintHarnessOptions {
+  bitmapStoreFactory?: (deps: {
+    backend: StubRasterBackend;
+    projectId: string;
+    store: EngineStore;
+  }) => ReturnType<typeof createSpyBitmapStore>;
+  pixelWrites?: { enabled: boolean };
+}
+
+const createControlPaintHarness = (
+  overrides: ControlPaintHarnessOverrides,
+  options: ControlPaintHarnessOptions = {}
+) => {
+  const raf = createControllableRaf();
+  vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+  vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+  vi.stubGlobal('Path2D', class FakePath2D {});
+
+  const { source, ...layerOverrides } = overrides;
+  const layer: CanvasControlLayerContract = {
+    adapter: {
+      beginEndStepPct: [0.1, 0.9],
+      controlMode: 'more_control',
+      kind: 'controlnet',
+      model: 'control-model',
+      weight: 0.7,
+    },
+    blendMode: 'screen',
+    filter: { settings: { low: 10 }, type: 'canny' },
+    id: 'control',
+    isEnabled: true,
+    isLocked: false,
+    name: 'Control',
+    opacity: 0.6,
+    source,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'control',
+    withTransparencyEffect: true,
+    ...layerOverrides,
+  };
+  const document: CanvasDocumentContractV2 = {
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers: [layer],
+    selectedLayerId: layer.id,
+    version: 2,
+    width: 100,
+  };
+  const { projectId, store } = createReducerBackedStore(document);
+  const baseBackend = createTestStubRasterBackend();
+  const pixelWrites = options.pixelWrites ?? { enabled: true };
+  const backend: StubRasterBackend = {
+    ...baseBackend,
+    createSurface: (width, height) => {
+      const surface = baseBackend.createSurface(width, height);
+      const originalCtx = surface.ctx;
+      const ctx = new Proxy(originalCtx, {
+        get(target, property, receiver) {
+          const value = Reflect.get(target, property, receiver);
+          if (property !== 'getImageData' || typeof value !== 'function') {
+            return value;
+          }
+          return (...args: unknown[]) => {
+            const imageData = Reflect.apply(value, target, args) as ImageData;
+            if (pixelWrites.enabled && imageData.data.length > 0) {
+              const drawCount = surface.callLog.filter((entry) => entry.op === 'drawImage').length;
+              imageData.data[0] = drawCount % 256;
+            }
+            return imageData;
+          };
+        },
+      });
+      Object.defineProperty(surface, 'ctx', { configurable: true, value: ctx });
+      return surface;
+    },
+  };
+  const bitmapStore = options.bitmapStoreFactory?.({ backend, projectId, store }) ?? createSpyBitmapStore();
+  const engine = createCanvasEngine({
+    backend,
+    bitmapStore,
+    imageResolver: () => Promise.resolve(new Blob()),
+    projectId,
+    store,
+  });
+  const strokes: StrokeCommittedEvent[] = [];
+  engine.tools.onStrokeCommitted((event) => strokes.push(event));
+  const overlay = createInputCanvas();
+  const screen = createInputCanvas();
+  engine.surface.attach(screen.element, overlay.element);
+
+  return {
+    backend,
+    bitmapStore,
+    document,
+    engine,
+    layer,
+    overlay,
+    publishInitialCache: async () => {
+      raf.flush();
+      await flushMicrotasks();
+      raf.flush();
+      await flushMicrotasks();
+    },
+    raf,
+    screen,
+    store,
+    strokes,
+  };
+};
+
+const createControlSelectionHarness = (overrides: ControlPaintHarnessOverrides) => {
+  const selectionPixelWrites = { enabled: true };
+  return {
+    ...createControlPaintHarness(overrides, { pixelWrites: selectionPixelWrites }),
+    setSelectionPixelWrites: (enabled: boolean) => {
+      selectionPixelWrites.enabled = enabled;
+    },
+  };
+};
+
+/** A minimal in-memory bitmap store: records dirty-marks, never touches the network. */
+const createSpyBitmapStore = (): BitmapStore & {
+  markLayerDirty: Mock<(layerId: string) => void>;
+  releaseSuspendedLayer: Mock<() => void>;
+  reset: Mock<() => void>;
+  suspendLayer: Mock<(layerId: string) => () => void>;
+} => {
+  const releaseSuspendedLayer = vi.fn();
+  return {
+    discardLayer: vi.fn(),
+    dispose: vi.fn(),
+    flushPendingUploads: vi.fn(() => Promise.resolve()),
+    isSelfEcho: () => false,
+    markLayerDirty: vi.fn<(layerId: string) => void>(),
+    releaseSuspendedLayer,
+    reset: vi.fn<() => void>(),
+    suspendLayer: vi.fn(() => releaseSuspendedLayer),
+  };
+};
+
+const createRealControlPersistenceHarness = async (
+  uploadImage: (blob: Blob) => Promise<{ height: number; imageName: string; width: number }>
+) => {
+  let placed: { offset: { x: number; y: number }; surface: RasterSurface } | null = null;
+  const encodeSurface = vi.fn(() => Promise.resolve(new Blob(['control-pixels'], { type: 'image/png' })));
+  const h = createControlPaintHarness(
+    { source: { bitmap: { height: 10, imageName: 'control-paint', width: 10 }, type: 'paint' } },
+    {
+      bitmapStoreFactory: ({ projectId, store }) => {
+        const real = createBitmapStore({
+          debounceMs: 1500,
+          dispatch: createTestMutationPort(store, projectId).dispatch,
+          encodeSurface,
+          getLayerSource: (layerId) => {
+            const layer = store
+              .getState()
+              .projects.find((project) => project.id === projectId)
+              ?.canvas.document.layers.find((candidate) => candidate.id === layerId);
+            return layer?.type === 'control' ? layer.source : null;
+          },
+          getLayerSurface: () => placed,
+          hashBlob: (blob) => blob.text(),
+          maxUploadAttempts: 1,
+          retryDelaysMs: [],
+          sleep: () => Promise.resolve(),
+          uploadImage,
+        });
+        const releaseSuspendedLayer = vi.fn();
+        return {
+          ...real,
+          markLayerDirty: vi.fn(real.markLayerDirty),
+          releaseSuspendedLayer,
+          reset: vi.fn(real.reset),
+          suspendLayer: vi.fn((layerId: string) => {
+            const release = real.suspendLayer(layerId);
+            return () => {
+              releaseSuspendedLayer();
+              release();
+            };
+          }),
+        };
+      },
+    }
+  );
+  await h.publishInitialCache();
+  const exported = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+  if (exported.status !== 'ok') {
+    throw new Error(`expected ready direct control cache, got ${exported.status}`);
+  }
+  placed = { offset: { x: exported.rect.x, y: exported.rect.y }, surface: exported.surface };
+  return { ...h, encodeSurface };
+};
+
+/** A fake canvas that also lets a test fire pointer events at the engine's listeners. */
+const createInputCanvas = (
+  width = 100,
+  height = 100
+): {
+  element: HTMLCanvasElement;
+  fire: (type: string, event: Partial<PointerEvent>) => void;
+  surface: StubRasterSurface;
+} => {
+  const surface = createTestStubRasterBackend().createSurface(width, height);
+  const listeners = new Map<string, Set<(event: Event) => void>>();
+  const element = {
+    addEventListener: (type: string, handler: (event: Event) => void) => {
+      const set = listeners.get(type) ?? new Set();
+      set.add(handler);
+      listeners.set(type, set);
+    },
+    getBoundingClientRect: () => ({ bottom: height, height, left: 0, right: width, top: 0, width, x: 0, y: 0 }),
+    getContext: () => surface.ctx,
+    height,
+    releasePointerCapture: () => {},
+    removeEventListener: (type: string, handler: (event: Event) => void) => {
+      listeners.get(type)?.delete(handler);
+    },
+    setPointerCapture: () => {},
+    width,
+  } as unknown as HTMLCanvasElement;
+  const fire = (type: string, event: Partial<PointerEvent>): void => {
+    for (const handler of listeners.get(type) ?? []) {
+      handler({ preventDefault: () => {}, ...event } as unknown as Event);
+    }
+  };
+  return { element, fire, surface };
+};
+
+const pointerAt = (x: number, y: number, opts: { button?: number; buttons?: number } = {}): Partial<PointerEvent> => ({
+  altKey: false,
+  button: opts.button ?? 0,
+  buttons: opts.buttons ?? 1,
+  clientX: x,
+  clientY: y,
+  ctrlKey: false,
+  metaKey: false,
+  pointerId: 1,
+  pointerType: 'mouse',
+  pressure: 0.5,
+  shiftKey: false,
+  timeStamp: 0,
+});
+
+/** Every `putImageData` recorded across all surfaces the backend created. */
+const putImageDataCalls = (surfaces: StubRasterSurface[]): { image: unknown; x: unknown; y: unknown }[] =>
+  surfaces.flatMap((surface) =>
+    surface.callLog
+      .filter((entry) => entry.op === 'putImageData')
+      .map((entry) => ({ image: entry.args[0], x: entry.args[1], y: entry.args[2] }))
+  );
+
+describe('engine-owned control pixel editing', () => {
+  it('brushes an empty control in place and never creates a raster layer', () => {
+    const h = createControlPaintHarness({ source: { bitmap: null, type: 'paint' } });
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    h.overlay.fire('pointermove', pointerAt(40, 40));
+    h.overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+
+    expect(h.engine.document.getDocument()!.layers).toHaveLength(1);
+    expect(h.engine.document.getDocument()!.layers[0]).toMatchObject({ id: 'control', type: 'control' });
+    expect(h.strokes).toHaveLength(1);
+    expect(h.strokes[0]!.layerId).toBe('control');
+    expect(h.bitmapStore.markLayerDirty).toHaveBeenCalledWith('control');
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledWith('control');
+    expect(h.bitmapStore.markLayerDirty.mock.invocationCallOrder[0]).toBeLessThan(
+      h.bitmapStore.releaseSuspendedLayer.mock.invocationCallOrder[0]!
+    );
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('restores the exact direct cache after a cancelled stroke grows it and permits a subsequent edit', async () => {
+    const h = createControlPaintHarness({
+      source: { bitmap: { height: 10, imageName: 'control-paint', width: 10 }, type: 'paint' },
+    });
+    await h.publishInitialCache();
+    const before = await snapshotLayerCache(h.engine, 'control');
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(80, 80));
+    h.overlay.fire('pointermove', pointerAt(90, 90));
+    h.overlay.fire('pointercancel', pointerAt(90, 90, { buttons: 0 }));
+
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe('ok');
+    if (restored.status === 'ok') {
+      expect(restored.surface).toBe(before.surface);
+      expect(restored.rect).toEqual(before.rect);
+      expect(restored.guard.cacheVersion).toBe(before.version);
+      const finalWrite = (restored.surface as StubRasterSurface).callLog
+        .filter((entry) => entry.op === 'putImageData')
+        .at(-1);
+      expect(finalWrite?.args[0]).toMatchObject({ height: before.rect.height, width: before.rect.width });
+    }
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.strokes).toHaveLength(0);
+
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledTimes(2);
+    h.overlay.fire('pointercancel', pointerAt(20, 20, { buttons: 0 }));
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledTimes(2);
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each(['brush', 'eraser'] as const)(
+    'treats a byte-identical direct %s stroke as an exact rollback',
+    async (tool) => {
+      const h = createControlPaintHarness(
+        { source: { bitmap: { height: 10, imageName: 'control-paint', width: 10 }, type: 'paint' } },
+        { pixelWrites: { enabled: false } }
+      );
+      await h.publishInitialCache();
+      const before = await snapshotLayerCache(h.engine, 'control');
+      h.engine.tools.setTool(tool);
+      h.overlay.fire('pointerdown', pointerAt(5, 5));
+      h.overlay.fire('pointermove', pointerAt(8, 8));
+      h.overlay.fire('pointerup', pointerAt(8, 8, { buttons: 0 }));
+
+      const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+      expect(restored.status).toBe('ok');
+      if (restored.status === 'ok') {
+        expect(restored.surface).toBe(before.surface);
+        expect(restored.rect).toEqual(before.rect);
+        expect(restored.guard.cacheVersion).toBe(before.version);
+      }
+      expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+      expect(h.engine.stores.canUndo.get()).toBe(false);
+      expect(h.strokes).toHaveLength(0);
+      h.engine.lifecycle.dispose();
+    }
+  );
+
+  it('keeps a pending direct-control upload suspended through cancel, then resumes the preserved dirty work', async () => {
+    const uploadImage = vi.fn(() => Promise.resolve({ height: 10, imageName: 'resumed-control', width: 10 }));
+    const h = await createRealControlPersistenceHarness(uploadImage);
+    vi.useFakeTimers();
+    try {
+      h.bitmapStore.markLayerDirty('control');
+      h.engine.tools.setTool('brush');
+      h.overlay.fire('pointerdown', pointerAt(20, 20));
+      h.overlay.fire('pointermove', pointerAt(30, 30));
+      const barrier = h.bitmapStore.flushPendingUploads();
+      let settled = false;
+      void barrier.then(() => {
+        settled = true;
+      });
+
+      await vi.advanceTimersByTimeAsync(3000);
+      expect(settled).toBe(false);
+      expect(h.encodeSurface).not.toHaveBeenCalled();
+      expect(uploadImage).not.toHaveBeenCalled();
+
+      h.overlay.fire('pointercancel', pointerAt(30, 30, { buttons: 0 }));
+      await drainMicrotasksUntil(() => settled);
+
+      expect(settled).toBe(true);
+      expect(h.encodeSurface).toHaveBeenCalledOnce();
+      expect(uploadImage).toHaveBeenCalledOnce();
+      expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+      expect(h.engine.stores.canUndo.get()).toBe(false);
+      expect(h.strokes).toHaveLength(0);
+      h.engine.lifecycle.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('invalidates an in-flight direct-control upload on begin and releases the barrier after cancel', async () => {
+    const uploads = [
+      createDeferred<{ height: number; imageName: string; width: number }>(),
+      createDeferred<{ height: number; imageName: string; width: number }>(),
+    ];
+    let uploadIndex = 0;
+    const uploadImage = vi.fn(() => uploads[uploadIndex++]!.promise);
+    const h = await createRealControlPersistenceHarness(uploadImage);
+    h.bitmapStore.markLayerDirty('control');
+    const barrier = h.bitmapStore.flushPendingUploads();
+    for (let tick = 0; tick < 50 && uploadImage.mock.calls.length < 1; tick += 1) {
+      await Promise.resolve();
+    }
+    expect(uploadImage).toHaveBeenCalledOnce();
+
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    h.overlay.fire('pointermove', pointerAt(30, 30));
+    let settled = false;
+    void barrier.then(() => {
+      settled = true;
+    });
+    uploads[0]!.resolve({ height: 10, imageName: 'obsolete-control', width: 10 });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(settled).toBe(false);
+    expect(uploadImage).toHaveBeenCalledOnce();
+
+    h.overlay.fire('pointercancel', pointerAt(30, 30, { buttons: 0 }));
+    for (let tick = 0; tick < 50 && uploadImage.mock.calls.length < 2; tick += 1) {
+      await Promise.resolve();
+    }
+    expect(uploadImage).toHaveBeenCalledTimes(2);
+    uploads[1]!.resolve({ height: 10, imageName: 'resumed-control', width: 10 });
+    await drainMicrotasksUntil(() => settled);
+
+    expect(settled).toBe(true);
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.strokes).toHaveLength(0);
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each([
+    ['image control', { source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' } }],
+    [
+      'transformed empty control',
+      {
+        source: { bitmap: null, type: 'paint' },
+        transform: { rotation: 0, scaleX: 2, scaleY: 3, x: 7, y: 11 },
+      },
+    ],
+  ] as const)('treats byte-identical brush and eraser strokes on a %s as rollback', async (_scenario, overrides) => {
+    for (const tool of ['brush', 'eraser'] as const) {
+      const h = createControlPaintHarness(overrides, { pixelWrites: { enabled: false } });
+      if (overrides.source.type === 'image') {
+        await h.publishInitialCache();
+      }
+      const beforeDocument = structuredClone(h.engine.document.getDocument());
+      const beforeCache = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+      h.engine.tools.setTool(tool);
+      h.overlay.fire('pointerdown', pointerAt(5, 5));
+      h.overlay.fire('pointermove', pointerAt(8, 8));
+      h.overlay.fire('pointerup', pointerAt(8, 8, { buttons: 0 }));
+
+      expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+      const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+      expect(restored.status).toBe(beforeCache.status);
+      if (restored.status === 'ok' && beforeCache.status === 'ok') {
+        expect(restored.surface).toBe(beforeCache.surface);
+        expect(restored.rect).toEqual(beforeCache.rect);
+        expect(restored.guard.cacheVersion).toBe(beforeCache.guard.cacheVersion);
+      }
+      expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+      expect(h.engine.stores.canUndo.get()).toBe(false);
+      expect(h.strokes).toHaveLength(0);
+      h.engine.lifecycle.dispose();
+    }
+  });
+
+  it('restores a direct control stroke when image-patch history preparation fails', async () => {
+    const h = createControlPaintHarness({ source: { bitmap: null, type: 'paint' } });
+    const before = structuredClone(h.engine.document.getDocument());
+    const beforeExport = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    h.overlay.fire('pointermove', pointerAt(40, 40));
+    historyPreparationFaults.imagePatch = true;
+
+    expect(() => h.overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }))).toThrow(
+      'image patch preparation failed'
+    );
+
+    expect(h.engine.document.getDocument()).toEqual(before);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.strokes).toHaveLength(0);
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe(beforeExport.status);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('materializes an image control plus brush stroke as one reversible edit', async () => {
+    const h = createControlPaintHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 20 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 3, x: 7, y: 11 },
+    });
+    await h.publishInitialCache();
+    const before = structuredClone(h.engine.document.getDocument()!.layers[0]);
+
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    h.overlay.fire('pointermove', pointerAt(25, 25));
+    h.overlay.fire('pointerup', pointerAt(25, 25, { buttons: 0 }));
+
+    const after = structuredClone(h.engine.document.getDocument()!.layers[0]);
+    expect(after).toMatchObject({
+      adapter: before && 'adapter' in before ? before.adapter : undefined,
+      filter: before && 'filter' in before ? before.filter : undefined,
+      id: 'control',
+      source: { type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'control',
+      withTransparencyEffect: true,
+    });
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledWith('control');
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.markLayerDirty.mock.invocationCallOrder[0]).toBeLessThan(
+      h.bitmapStore.releaseSuspendedLayer.mock.invocationCallOrder[0]!
+    );
+
+    h.engine.history.undo();
+    expect(h.engine.document.getDocument()!.layers[0]).toEqual(before);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.engine.stores.canRedo.get()).toBe(true);
+
+    h.engine.history.redo();
+    expect(h.engine.document.getDocument()!.layers[0]).toEqual(after);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('restores a materialized control when layer-snapshot history preparation fails', async () => {
+    const h = createControlPaintHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 20 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 3, x: 7, y: 11 },
+    });
+    await h.publishInitialCache();
+    const before = structuredClone(h.engine.document.getDocument());
+    const beforeCache = await snapshotLayerCache(h.engine, 'control');
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    h.overlay.fire('pointermove', pointerAt(25, 25));
+    historyPreparationFaults.layerSnapshot = true;
+
+    expect(() => h.overlay.fire('pointerup', pointerAt(25, 25, { buttons: 0 }))).toThrow(
+      'layer snapshot preparation failed'
+    );
+
+    expect(h.engine.document.getDocument()).toEqual(before);
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe('ok');
+    if (restored.status === 'ok') {
+      expect(restored.surface).toBe(beforeCache.surface);
+      expect(restored.rect).toEqual(beforeCache.rect);
+      expect(restored.guard.cacheVersion).toBe(beforeCache.version);
+    }
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.strokes).toHaveLength(0);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('releases materialized persistence and edit ownership when rollback cleanup throws', async () => {
+    const h = createControlPaintHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 20 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 3, x: 7, y: 11 },
+    });
+    await h.publishInitialCache();
+    const before = structuredClone(h.engine.document.getDocument());
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    h.overlay.fire('pointermove', pointerAt(25, 25));
+    historyPreparationFaults.layerSnapshot = true;
+    adjustedSurfaceCacheDeleteFaults.add('control');
+
+    expect(() => h.overlay.fire('pointerup', pointerAt(25, 25, { buttons: 0 }))).toThrow(
+      'adjusted surface cache delete failed'
+    );
+
+    expect(h.engine.document.getDocument()).toEqual(before);
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.strokes).toHaveLength(0);
+
+    historyPreparationFaults.layerSnapshot = false;
+    adjustedSurfaceCacheDeleteFaults.clear();
+    h.overlay.fire('pointerdown', pointerAt(30, 30));
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledTimes(2);
+    h.overlay.fire('pointercancel', pointerAt(30, 30, { buttons: 0 }));
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledTimes(2);
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each(['eraser', 'brush'] as const)(
+    'rolls back a prepared image control when a %s gesture is cancelled',
+    async (tool) => {
+      const h = createControlPaintHarness({
+        source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      });
+      await h.publishInitialCache();
+      const before = structuredClone(h.engine.document.getDocument());
+      h.engine.tools.setTool(tool);
+      h.overlay.fire('pointerdown', pointerAt(5, 5));
+      h.overlay.fire('pointercancel', pointerAt(5, 5, { buttons: 0 }));
+      expect(h.engine.document.getDocument()).toEqual(before);
+      expect(h.engine.stores.canUndo.get()).toBe(false);
+      expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(h.bitmapStore.suspendLayer).toHaveBeenCalledWith('control');
+      expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+      h.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each([
+    ['locked', { isLocked: true }],
+    ['disabled', { isEnabled: false }],
+  ] as const)('does not mutate or auto-create over a %s control', (_scenario, patch) => {
+    const h = createControlPaintHarness({ source: { bitmap: null, type: 'paint' }, ...patch });
+    const before = structuredClone(h.engine.document.getDocument());
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(20, 20));
+    h.overlay.fire('pointerup', pointerAt(20, 20, { buttons: 0 }));
+    expect(h.engine.document.getDocument()).toEqual(before);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('normalizes a transformed empty control before its first brush stroke', () => {
+    const h = createControlPaintHarness({
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 30, y: 40 },
+    });
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(35, 45));
+    h.overlay.fire('pointerup', pointerAt(35, 45, { buttons: 0 }));
+    expect(h.engine.document.getDocument()!.layers[0]).toMatchObject({
+      id: 'control',
+      source: { type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'control',
+    });
+    h.engine.history.undo();
+    expect(h.engine.document.getDocument()!.layers[0]).toMatchObject({
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 30, y: 40 },
+    });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not edit or auto-create when an image control cache is not ready', () => {
+    const h = createControlPaintHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+    });
+    h.raf.flush();
+    const before = structuredClone(h.engine.document.getDocument());
+
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(5, 5));
+    h.overlay.fire('pointerup', pointerAt(5, 5, { buttons: 0 }));
+
+    expect(h.engine.document.getDocument()).toEqual(before);
+    expect(h.engine.document.getDocument()!.layers).toHaveLength(1);
+    expect(h.strokes).toHaveLength(0);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.discardLayer).not.toHaveBeenCalled();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.engine.stores.canRedo.get()).toBe(false);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('finishes document-replacement cleanup after materialized gesture rollback throws', async () => {
+    const h = createControlPaintHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 },
+    });
+    await h.publishInitialCache();
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(8, 8));
+    h.overlay.fire('pointermove', pointerAt(12, 12));
+    adjustedSurfaceCacheDeleteFaults.add('control');
+    const replacement = { ...h.document, width: h.document.width + 1 };
+
+    expect(() => h.store.dispatch({ document: replacement, type: 'replaceCanvasDocument' })).toThrow(
+      'adjusted surface cache delete failed'
+    );
+
+    expect(h.engine.document.getDocument()).toEqual(replacement);
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.reset).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.strokes).toHaveLength(0);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('finishes affected-layer removal cleanup after direct gesture rollback throws', async () => {
+    const h = createControlPaintHarness({
+      source: { bitmap: { height: 10, imageName: 'control-paint', width: 10 }, type: 'paint' },
+    });
+    await h.publishInitialCache();
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(8, 8));
+    h.overlay.fire('pointermove', pointerAt(12, 12));
+    adjustedSurfaceCacheDeleteFaults.add('control');
+
+    expect(() => h.store.dispatch({ ids: ['control'], type: 'removeCanvasLayers' })).toThrow(
+      'adjusted surface cache delete failed'
+    );
+
+    expect(h.engine.document.getDocument()!.layers).toHaveLength(0);
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.discardLayer).toHaveBeenCalledWith('control');
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.strokes).toHaveLength(0);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not clean up a materialized gesture merely because another project becomes active', async () => {
+    const h = createControlPaintHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+    });
+    await h.publishInitialCache();
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(8, 8));
+    h.overlay.fire('pointermove', pointerAt(12, 12));
+    adjustedSurfaceCacheDeleteFaults.add('control');
+
+    expect(() => h.store.dispatch({ type: 'createProject' })).not.toThrow();
+
+    expect(h.store.getState().activeProjectId).not.toBe(h.store.getState().projects[0]!.id);
+    expect(h.bitmapStore.releaseSuspendedLayer).not.toHaveBeenCalled();
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.strokes).toHaveLength(0);
+
+    adjustedSurfaceCacheDeleteFaults.delete('control');
+    h.store.dispatch({ projectId: h.store.getState().projects[0]!.id, type: 'switchProject' });
+    h.overlay.fire('pointercancel', pointerAt(8, 8, { buttons: 0 }));
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('finishes disposal after direct gesture rollback throws and remains idempotent', async () => {
+    const h = createControlPaintHarness({
+      source: { bitmap: { height: 10, imageName: 'control-paint', width: 10 }, type: 'paint' },
+    });
+    await h.publishInitialCache();
+    h.engine.tools.setTool('brush');
+    h.overlay.fire('pointerdown', pointerAt(8, 8));
+    h.overlay.fire('pointermove', pointerAt(12, 12));
+    adjustedSurfaceCacheDeleteFaults.add('control');
+
+    expect(() => h.engine.lifecycle.dispose()).toThrow('adjusted surface cache delete failed');
+
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.dispose).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.strokes).toHaveLength(0);
+    expect(() => h.engine.lifecycle.dispose()).not.toThrow();
+    expect(h.bitmapStore.dispose).toHaveBeenCalledOnce();
+  });
+});
+
+describe('engine-owned history: stroke → undo → redo', () => {
+  const drawStroke = () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    // The engine builds real `Path2D`s for stroke outlines; node lacks it.
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const bitmapStore = createSpyBitmapStore();
+
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const strokes: StrokeCommittedEvent[] = [];
+    engine.tools.onStrokeCommitted((event) => strokes.push(event));
+
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+
+    // A brush gesture entirely inside the 100x100 document (identity viewport).
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+
+    return { bitmapStore, engine, strokes, surfaces };
+  };
+
+  it('records a stroke and restores before/after pixels on undo/redo', () => {
+    const { bitmapStore, engine, strokes, surfaces } = drawStroke();
+
+    // One stroke committed and one history entry recorded.
+    expect(strokes).toHaveLength(1);
+    const event = strokes[0]!;
+    expect(event.layerId).toBe('paint1');
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    // The commit marked the layer dirty for persistence.
+    const dirtyAfterStroke = bitmapStore.markLayerDirty.mock.calls.length;
+    expect(dirtyAfterStroke).toBeGreaterThanOrEqual(1);
+
+    // Undo: the layer's cache surface receives putImageData(before), and the layer
+    // is re-marked dirty (convergence path). Content-sized: the paint layer started
+    // empty and grew to exactly the stroke's dirty rect, so the cache-local origin
+    // equals the dirty-rect origin and the patch lands at surface (0, 0).
+    engine.history.undo();
+    const undoPut = putImageDataCalls(surfaces).find((call) => call.image === event.beforeImageData);
+    expect(undoPut).toBeDefined();
+    expect(undoPut!.x).toBe(0);
+    expect(undoPut!.y).toBe(0);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+    expect(bitmapStore.markLayerDirty.mock.calls.length).toBeGreaterThan(dirtyAfterStroke);
+
+    // Redo: putImageData(after) restores the post-stroke pixels.
+    engine.history.redo();
+    const redoPut = putImageDataCalls(surfaces).find((call) => call.image === event.afterImageData);
+    expect(redoPut).toBeDefined();
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('round-trips pixels exactly across a cache-growing stroke → undo → redo', () => {
+    // Integrated case: a multi-move stroke that GROWS the (initially empty) paint
+    // cache across several pointer batches, then undo/redo restore the exact
+    // before/after ImageData over the FULL grown extent. The piecewise pieces
+    // (growth, patch application) are covered elsewhere; this pins them together.
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const strokes: StrokeCommittedEvent[] = [];
+    engine.tools.onStrokeCommitted((event) => strokes.push(event));
+
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+
+    // Drag rightward across the document in several batches so the content-sized
+    // cache grows (and reallocates) as the stroke extends.
+    overlay.fire('pointerdown', pointerAt(10, 50));
+    overlay.fire('pointermove', pointerAt(30, 50));
+    overlay.fire('pointermove', pointerAt(50, 50));
+    overlay.fire('pointermove', pointerAt(70, 50));
+    overlay.fire('pointermove', pointerAt(90, 50));
+    overlay.fire('pointerup', pointerAt(90, 50, { buttons: 0 }));
+
+    expect(strokes).toHaveLength(1);
+    const event = strokes[0]!;
+    // The stroke grew the cache well beyond a single dab: the dirty rect spans most
+    // of the drag width, and the captured before/after cover that full extent.
+    expect(event.dirtyRect.width).toBeGreaterThan(60);
+    expect(event.beforeImageData.width).toBe(event.dirtyRect.width);
+    expect(event.beforeImageData.height).toBe(event.dirtyRect.height);
+    expect(event.afterImageData.width).toBe(event.dirtyRect.width);
+    expect(event.afterImageData.height).toBe(event.dirtyRect.height);
+
+    // Undo writes the EXACT pre-stroke ImageData back into the cache. The cache
+    // grew to exactly the (chunk-padded) dirty rect, so its local origin equals the
+    // dirty-rect origin and the patch lands at surface (0, 0).
+    engine.history.undo();
+    const undoPut = putImageDataCalls(surfaces).find((call) => call.image === event.beforeImageData);
+    expect(undoPut).toBeDefined();
+    expect(undoPut!.x).toBe(0);
+    expect(undoPut!.y).toBe(0);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    // Redo writes the EXACT post-stroke ImageData back — a lossless round-trip.
+    engine.history.redo();
+    const redoPut = putImageDataCalls(surfaces).find((call) => call.image === event.afterImageData);
+    expect(redoPut).toBeDefined();
+    expect(redoPut!.x).toBe(0);
+    expect(redoPut!.y).toBe(0);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('clears history when the document is replaced', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { setDocument, store } = createReactiveStore(paintDoc());
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    // A dims change triggers onDocumentReplaced → history.clear().
+    const replaced = { ...paintDoc(), height: 200, width: 200 };
+    setDocument(replaced);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('clears history on a same-dimension snapshot restore (documentRevision bump)', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { setDocument, store } = createReactiveStore(paintDoc());
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    // A snapshot restore reuses the same dims AND layer ids (structuredClone), so
+    // only the bumped documentRevision distinguishes it from an ordinary edit. It
+    // must still clear history: a subsequent undo would otherwise put pre-restore
+    // pixels over the restored content.
+    setDocument(paintDoc(), 1);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('re-rasterizes and resets persistence bookkeeping on a revision-bump swap that reuses a layer id with a different source', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const docV1: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [rasterLayer('a', { imageName: 'src-v1' })],
+      selectedLayerId: 'a',
+      version: 2,
+      width: 100,
+    };
+    const { setDocument, store } = createReactiveStore(docV1);
+    const resolver = vi.fn((_imageName: string) => Promise.resolve(new Blob()));
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+
+    // Initial rasterize of the v1 source.
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(resolver).toHaveBeenNthCalledWith(1, 'src-v1', expect.any(AbortSignal));
+
+    // A revision bump that REUSES layer id 'a' with a DIFFERENT source: the
+    // mirror routes this through onDocumentReplaced (a full swap), which a
+    // reference diff alone could not tell from an ordinary edit. The engine must
+    // invalidate the surviving cache entry so it re-rasterizes the new source
+    // (a stale cache entry would keep rendering the v1 pixels).
+    setDocument({ ...docV1, layers: [rasterLayer('a', { imageName: 'src-v2' })] }, 1);
+
+    // Persistence bookkeeping for the outgoing document was dropped so a reused
+    // layer id can't have its next legit persistence dispatch suppressed.
+    expect(bitmapStore.reset).toHaveBeenCalledTimes(1);
+
+    // The invalidated cache re-rasterizes, this time from the v2 source.
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    expect(resolver).toHaveBeenCalledTimes(2);
+    expect(resolver).toHaveBeenNthCalledWith(2, 'src-v2', expect.any(AbortSignal));
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('engine-owned history: undo/redo guarded during an active gesture', () => {
+  it('no-ops undo/redo mid-stroke, then works after the gesture ends', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const strokes: StrokeCommittedEvent[] = [];
+    engine.tools.onStrokeCommitted((event) => strokes.push(event));
+
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+
+    // First, record one committed stroke so there is something to undo.
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    // Start a SECOND stroke and leave it open (pointer down + move, no up).
+    // (The live session itself may draw, so snapshot the put count after it opens.)
+    overlay.fire('pointerdown', pointerAt(50, 50));
+    overlay.fire('pointermove', pointerAt(60, 60));
+    const putsMidGesture = putImageDataCalls(surfaces).length;
+
+    // Mid-gesture undo/redo must be no-ops: no history pop and no putImageData.
+    engine.history.undo();
+    engine.history.redo();
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(putImageDataCalls(surfaces).length).toBe(putsMidGesture);
+    // In particular, the first stroke's before pixels were never injected.
+    expect(putImageDataCalls(surfaces).some((call) => call.image === strokes[0]!.beforeImageData)).toBe(false);
+
+    // End the gesture; now undo works and writes the newest stroke's before pixels.
+    overlay.fire('pointerup', pointerAt(60, 60, { buttons: 0 }));
+    expect(strokes).toHaveLength(2);
+    engine.history.undo();
+    expect(putImageDataCalls(surfaces).some((call) => call.image === strokes[1]!.beforeImageData)).toBe(true);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- commitStructural: UI-initiated structural edits on the canvas history ----
+
+describe('commitStructural', () => {
+  const forward: EngineTestAction = { id: 'a', type: 'setCanvasSelectedLayer' };
+  const inverse: EngineTestAction = { id: null, type: 'setCanvasSelectedLayer' };
+
+  it('dispatches forward immediately and records a reversible history entry', () => {
+    const { store } = createFakeStore(makeDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(engine.layers.canCommitStructural()).toBe(true);
+    expect(engine.layers.commitStructural('Select layer', forward, inverse)).toBe(true);
+    // Forward dispatched once; the edit is now undoable but not redoable.
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch).toHaveBeenNthCalledWith(1, forward);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    // Undo dispatches the inverse and flips the stacks.
+    engine.history.undo();
+    expect(dispatch).toHaveBeenNthCalledWith(2, inverse);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    // Redo re-dispatches the forward.
+    engine.history.redo();
+    expect(dispatch).toHaveBeenNthCalledWith(3, forward);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+    expect(engine.layers.canCommitStructural()).toBe(false);
+    expect(engine.layers.commitStructural('Select layer', forward, inverse)).toBe(false);
+  });
+});
+
+// ---- drawLayerThumbnail: cache-backed layer previews --------------------
+
+const controlLayerForThumbnail = (id: string): CanvasLayerContract =>
+  ({
+    adapter: {
+      beginEndStepPct: [0, 1],
+      controlMode: null,
+      kind: 'controlnet',
+      model: null,
+      weight: 1,
+    },
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name: id,
+    opacity: 1,
+    source: { image: { height: 10, imageName: id, width: 10 }, type: 'image' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'control',
+    withTransparencyEffect: true,
+  }) as CanvasLayerContract;
+
+const thumbnailMaskLayer = (id: string, type: 'inpaint_mask' | 'regional_guidance'): CanvasLayerContract =>
+  ({
+    autoNegative: true,
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    mask: {
+      bitmap: { height: 10, imageName: id, width: 10 },
+      fill: { color: '#e07575', style: 'diagonal' },
+    },
+    name: id,
+    negativePrompt: null,
+    opacity: 1,
+    positivePrompt: null,
+    referenceImages: [],
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type,
+  }) as CanvasLayerContract;
+
+const largeThumbnailLayer = (
+  kind: 'raster' | 'control' | 'inpaint_mask' | 'regional_guidance'
+): CanvasLayerContract => {
+  const image = { height: 2048, imageName: `large-${kind}`, width: 4096 };
+  if (kind === 'raster') {
+    return {
+      ...rasterLayer('a'),
+      adjustments: { brightness: 0.25, contrast: -0.1, saturation: 0.3 },
+      source: { bitmap: image, offset: { x: -300, y: 250 }, type: 'paint' },
+    } as CanvasRasterLayerContractV2;
+  }
+  if (kind === 'control') {
+    return { ...controlLayerForThumbnail('a'), source: { image, type: 'image' } } as CanvasLayerContract;
+  }
+  const mask = thumbnailMaskLayer('a', kind);
+  return {
+    ...mask,
+    mask: { ...('mask' in mask ? mask.mask : {}), bitmap: image, offset: { x: -300, y: 250 } },
+  } as CanvasLayerContract;
+};
+
+const createSeededThumbnailBackend = (rgba: [number, number, number, number]): StubRasterBackend => {
+  const backend = createTestStubRasterBackend();
+  const createSurface = backend.createSurface.bind(backend);
+  backend.createSurface = (width, height) => {
+    const surface = createSurface(width, height);
+    const originalCtx = surface.ctx;
+    const ctx = new Proxy(originalCtx, {
+      get(target, property, receiver) {
+        if (property === 'getImageData') {
+          return (x: number, y: number, imageWidth: number, imageHeight: number): ImageData => {
+            target.getImageData(x, y, imageWidth, imageHeight);
+            const data = new Uint8ClampedArray(imageWidth * imageHeight * 4);
+            for (let index = 0; index < data.length; index += 4) {
+              data.set(rgba, index);
+            }
+            return { colorSpace: 'srgb', data, height: imageHeight, width: imageWidth } as ImageData;
+          };
+        }
+        return Reflect.get(target, property, receiver);
+      },
+    });
+    Object.defineProperty(surface, 'ctx', { value: ctx });
+    return surface;
+  };
+  return backend;
+};
+
+const createThumbnailTarget = (): {
+  calls: { args: unknown[]; op: string }[];
+  target: HTMLCanvasElement;
+} => {
+  const calls: { args: unknown[]; op: string }[] = [];
+  const ctx = {
+    clearRect: (...args: unknown[]) => calls.push({ args, op: 'clearRect' }),
+    createPattern: (...args: unknown[]) => {
+      calls.push({ args, op: 'createPattern' });
+      return 'checker-pattern';
+    },
+    drawImage: (...args: unknown[]) => calls.push({ args, op: 'drawImage' }),
+    fillRect: (...args: unknown[]) => calls.push({ args, op: 'fillRect' }),
+    set globalAlpha(value: unknown) {
+      calls.push({ args: [value], op: 'globalAlpha' });
+    },
+    set fillStyle(value: unknown) {
+      calls.push({ args: [value], op: 'fillStyle' });
+    },
+  };
+  const target = { getContext: () => ctx, height: 0, width: 0 } as unknown as HTMLCanvasElement;
+  return { calls, target };
+};
+
+describe('drawLayerThumbnail', () => {
+  it('returns false and draws nothing when the layer has no cache', () => {
+    const { engine } = createEngine();
+    const { calls, target } = createThumbnailTarget();
+    expect(engine.previews.drawLayerThumbnail('missing', target, 96)).toBe(false);
+    expect(calls).toHaveLength(0);
+    engine.lifecycle.dispose();
+  });
+
+  it('scales the layer cache into the target and reports success', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { store } = createReactiveStore(makeDoc()); // one 10x10 image layer 'a'
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    // One frame creates the layer cache entry (10x10).
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    const { calls, target } = createThumbnailTarget();
+    expect(engine.previews.drawLayerThumbnail('a', target, 96)).toBe(true);
+    // 10x10 never upscales, so the target keeps the source dimensions.
+    expect(target.width).toBe(10);
+    expect(target.height).toBe(10);
+    expect(calls.map((call) => call.op)).toEqual([
+      'clearRect',
+      'createPattern',
+      'fillStyle',
+      'fillRect',
+      'globalAlpha',
+      'drawImage',
+    ]);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('draws adjusted raster pixels over the checkerboard', async () => {
+    const layer = {
+      ...rasterLayer('a'),
+      adjustments: { brightness: 0.2, contrast: -0.1, saturation: 0.3 },
+      opacity: 0.4,
+    } as CanvasRasterLayerContractV2;
+    const backend = createSeededThumbnailBackend([10, 20, 30, 255]);
+    const createSurface = vi.spyOn(backend, 'createSurface');
+    const { store } = createReactiveStore({ ...makeDoc(), layers: [layer] });
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    await engine.previews.requestLayerThumbnail('a');
+    const surfaceCountBeforeDraw = createSurface.mock.calls.length;
+    const adjustedGetCountBeforeDraw = adjustedSurfaceCacheGets.length;
+
+    const { calls, target } = createThumbnailTarget();
+    expect(engine.previews.drawLayerThumbnail('a', target, 96)).toBe(true);
+    expect(adjustedSurfaceCacheGets).toHaveLength(adjustedGetCountBeforeDraw);
+    expect(createSurface.mock.calls.length).toBeGreaterThan(surfaceCountBeforeDraw);
+    const createdSurfaces = createSurface.mock.results
+      .slice(surfaceCountBeforeDraw)
+      .map((result) => result.value as StubRasterSurface);
+    expect(createdSurfaces.some((surface) => surface.callLog.some((call) => call.op === 'getImageData'))).toBe(true);
+    const adjustedPixels = createdSurfaces
+      .flatMap((surface) => surface.callLog)
+      .find((call) => call.op === 'putImageData')?.args[0] as ImageData;
+    expect(Array.from(adjustedPixels.data.slice(0, 4))).toEqual([66, 77, 89, 255]);
+    const operations = calls.map((call) => call.op);
+    expect(operations.indexOf('fillRect')).toBeLessThan(operations.lastIndexOf('drawImage'));
+    expect(calls).toContainEqual({ args: [0.4], op: 'globalAlpha' });
+    engine.lifecycle.dispose();
+  });
+
+  it.each([
+    ['control transparency', { ...controlLayerForThumbnail('a'), withTransparencyEffect: true }, 'getImageData'],
+    ['inpaint mask fill', thumbnailMaskLayer('a', 'inpaint_mask'), 'source-in'],
+    ['regional mask fill', thumbnailMaskLayer('a', 'regional_guidance'), 'source-in'],
+  ])('renders %s pixels over the checkerboard', async (_name, layer, expectedEffect) => {
+    const backend =
+      expectedEffect === 'getImageData'
+        ? createSeededThumbnailBackend([100, 50, 200, 255])
+        : createTestStubRasterBackend();
+    const createSurface = vi.spyOn(backend, 'createSurface');
+    const { store } = createReactiveStore({ ...makeDoc(), layers: [layer as CanvasLayerContract] });
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    await engine.previews.requestLayerThumbnail('a');
+    const surfaceCountBeforeDraw = createSurface.mock.calls.length;
+
+    const { calls, target } = createThumbnailTarget();
+    expect(engine.previews.drawLayerThumbnail('a', target, 96)).toBe(true);
+    expect(createSurface.mock.calls.length).toBeGreaterThan(surfaceCountBeforeDraw);
+    const createdSurfaces = createSurface.mock.results
+      .slice(surfaceCountBeforeDraw)
+      .map((result) => result.value as StubRasterSurface);
+    expect(
+      createdSurfaces.some((surface) =>
+        surface.callLog.some(
+          (call) => call.op === expectedEffect || (call.op === 'set' && call.args[1] === expectedEffect)
+        )
+      )
+    ).toBe(true);
+    if (expectedEffect === 'getImageData') {
+      const effectedPixels = createdSurfaces
+        .flatMap((surface) => surface.callLog)
+        .find((call) => call.op === 'putImageData')?.args[0] as ImageData;
+      expect(Array.from(effectedPixels.data.slice(0, 4))).toEqual([100, 50, 200, 125]);
+    } else {
+      expect(
+        createdSurfaces.some((surface) =>
+          surface.callLog.some(
+            (call) =>
+              call.op === 'set' &&
+              (call.args[0] === 'fillStyle' || call.args[0] === 'strokeStyle') &&
+              call.args[1] === '#e07575'
+          )
+        )
+      ).toBe(true);
+    }
+    expect(calls.map((call) => call.op)).toContain('fillRect');
+    expect(calls.at(-1)?.op).toBe('drawImage');
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['raster', 'control', 'inpaint_mask', 'regional_guidance'] as const)(
+    'bounds every %s thumbnail effect allocation before processing a large source',
+    async (kind) => {
+      const layer = largeThumbnailLayer(kind);
+      const backend = createTestStubRasterBackend();
+      const createSurface = vi.spyOn(backend, 'createSurface');
+      const { store } = createReactiveStore({ ...makeDoc(), layers: [layer] });
+      const engine = createCanvasEngine({
+        backend,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      await engine.previews.requestLayerThumbnail('a');
+      createSurface.mockClear();
+
+      const { target } = createThumbnailTarget();
+      expect(engine.previews.drawLayerThumbnail('a', target, 96)).toBe(true);
+
+      expect(target.width).toBe(96);
+      expect(target.height).toBe(48);
+      expect(createSurface.mock.calls.length).toBeGreaterThan(0);
+      expect(createSurface.mock.calls.every(([width, height]) => width <= 96 && height <= 96)).toBe(true);
+      const scratch = createSurface.mock.results
+        .map((result) => result.value as StubRasterSurface)
+        .find((surface) =>
+          surface.callLog.some(
+            (call) =>
+              call.op === 'drawImage' &&
+              call.args[1] === 0 &&
+              call.args[2] === 0 &&
+              call.args[3] === 96 &&
+              call.args[4] === 48
+          )
+        );
+      expect(scratch).toBeDefined();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each([
+    [
+      'raster adjustments',
+      rasterLayer('a'),
+      (layer: CanvasLayerContract) => ({
+        ...layer,
+        adjustments: { brightness: 0.25, contrast: 0, saturation: 0 },
+      }),
+    ],
+    [
+      'control transparency',
+      controlLayerForThumbnail('a'),
+      (layer: CanvasLayerContract) => ({ ...layer, withTransparencyEffect: false }),
+    ],
+    [
+      'inpaint mask fill',
+      thumbnailMaskLayer('a', 'inpaint_mask'),
+      (layer: CanvasLayerContract) => ({
+        ...layer,
+        mask: { ...('mask' in layer ? layer.mask : {}), fill: { color: '#00ff00', style: 'solid' } },
+      }),
+    ],
+    [
+      'regional mask fill',
+      thumbnailMaskLayer('a', 'regional_guidance'),
+      (layer: CanvasLayerContract) => ({
+        ...layer,
+        mask: { ...('mask' in layer ? layer.mask : {}), fill: { color: '#00ff00', style: 'solid' } },
+      }),
+    ],
+    ['opacity', rasterLayer('a'), (layer: CanvasLayerContract) => ({ ...layer, opacity: 0.5 })],
+  ])(
+    'invalidates the keyed thumbnail version when %s changes without changing the source',
+    async (_name, layer, edit) => {
+      const doc = { ...makeDoc(), layers: [layer as CanvasLayerContract] };
+      const { setDocument, store } = createReactiveStore(doc);
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      await engine.previews.requestLayerThumbnail('a');
+      const listener = vi.fn();
+      const unsubscribe = engine.stores.thumbnailVersion.subscribeKey('a', listener);
+
+      setDocument({ ...doc, layers: [edit(layer as CanvasLayerContract) as CanvasLayerContract] });
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      unsubscribe();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('does not let display invalidation suppress the next cache-version publication', async () => {
+    const layer = rasterLayer('a');
+    const doc = { ...makeDoc(), layers: [layer] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    await engine.previews.requestLayerThumbnail('a');
+    const listener = vi.fn();
+    const unsubscribe = engine.stores.thumbnailVersion.subscribeKey('a', listener);
+
+    const adjusted = {
+      ...layer,
+      adjustments: { brightness: 0.25, contrast: 0, saturation: 0 },
+    } as CanvasLayerContract;
+    setDocument({ ...doc, layers: [adjusted] });
+    setDocument({ ...doc, layers: [rasterLayer('a', { imageName: 'a-v2' })] });
+    await engine.previews.requestLayerThumbnail('a');
+
+    expect(listener).toHaveBeenCalledTimes(2);
+    unsubscribe();
+    engine.lifecycle.dispose();
+  });
+
+  it('refuses a newly allocated cache until pixels have been published', () => {
+    const pending = createDeferred<Blob>();
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => pending.promise,
+      projectId: 'p1',
+      store,
+    });
+    const { calls, target } = createThumbnailTarget();
+
+    void engine.previews.requestLayerThumbnail('a');
+
+    expect(engine.previews.drawLayerThumbnail('a', target, 96)).toBe(false);
+    expect(calls).toHaveLength(0);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('requestLayerThumbnail', () => {
+  it('starts a request for its bound project while another project is active', async () => {
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+    const { setActiveProjectId, store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    setActiveProjectId('p2');
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('ready');
+    expect(resolver).toHaveBeenCalledOnce();
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('ready');
+    engine.lifecycle.dispose();
+  });
+
+  it('rasterizes while detached and publishes thumbnail readiness', async () => {
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    expect(engine.stores.thumbnailStatus.get('a')).toBeUndefined();
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('ready');
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('ready');
+    expect(engine.previews.drawLayerThumbnail('a', createThumbnailTarget().target, 96)).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('rasterizes disabled layers on explicit request', async () => {
+    const layer = { ...makeDoc().layers[0]!, isEnabled: false };
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+    const { store } = createReactiveStore({ ...makeDoc(), layers: [layer] });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('ready');
+    expect(resolver).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases a detached thumbnail bitmap when its layer source is replaced', async () => {
+    const bitmap = recordingBitmap('detached-replaced');
+    const backend = createTestStubRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(bitmap));
+    const doc = { ...makeDoc(), layers: [rasterLayer('a', { imageName: 'old' })] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('ready');
+    setDocument({ ...doc, layers: [rasterLayer('a', { imageName: 'new' })] });
+
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases a detached thumbnail bitmap when its layer is deleted', async () => {
+    const bitmap = recordingBitmap('detached-deleted');
+    const backend = createTestStubRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(bitmap));
+    const doc = { ...makeDoc(), layers: [rasterLayer('a', { imageName: 'old' })] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('ready');
+    setDocument({ ...doc, layers: [] });
+
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases each sequential shared-source decode after its thumbnail consumer settles', async () => {
+    const bitmap = recordingBitmap('shared-deleted');
+    const backend = createTestStubRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(bitmap));
+    const first = rasterLayer('a', { imageName: 'shared' });
+    const second = rasterLayer('b', { imageName: 'shared' });
+    const doc = { ...makeDoc(), layers: [first, second] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('ready');
+    expect(await engine.previews.requestLayerThumbnail('b')).toBe('ready');
+    expect(bitmap.close).toHaveBeenCalledTimes(2);
+
+    setDocument({ ...doc, layers: [second] });
+    setDocument({ ...doc, layers: [] });
+
+    expect(bitmap.close).toHaveBeenCalledTimes(2);
+    engine.lifecycle.dispose();
+  });
+
+  it('does not retain settled shared-source decodes until layers change source', async () => {
+    const bitmap = recordingBitmap('shared-replaced');
+    const backend = createTestStubRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(bitmap));
+    const first = rasterLayer('a', { imageName: 'shared' });
+    const second = rasterLayer('b', { imageName: 'shared' });
+    const doc = { ...makeDoc(), layers: [first, second] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('ready');
+    expect(await engine.previews.requestLayerThumbnail('b')).toBe('ready');
+    expect(bitmap.close).toHaveBeenCalledTimes(2);
+
+    const firstChanged = rasterLayer('a', { imageName: 'first-new' });
+    setDocument({ ...doc, layers: [firstChanged, second] });
+    setDocument({ ...doc, layers: [firstChanged, rasterLayer('b', { imageName: 'second-new' })] });
+
+    expect(bitmap.close).toHaveBeenCalledTimes(2);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases a decoded bitmap when invalidation lands after cache insertion but before publication', async () => {
+    const bitmap = recordingBitmap('stale-before-publication');
+    const original = rasterLayer('a', { imageName: 'old' });
+    const doc = { ...makeDoc(), layers: [original] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const backend = createInvalidateDuringBitmapDrawBackend(bitmap, () => {
+      setDocument({ ...doc, layers: [rasterLayer('a', { imageName: 'new' })] });
+    });
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('stale');
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases a stale decode immediately even when another layer references its source', async () => {
+    const bitmap = recordingBitmap('stale-shared-before-publication');
+    const first = rasterLayer('a', { imageName: 'shared' });
+    const second = rasterLayer('b', { imageName: 'shared' });
+    const doc = { ...makeDoc(), layers: [first, second] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const backend = createInvalidateDuringBitmapDrawBackend(bitmap, () => {
+      setDocument({ ...doc, layers: [rasterLayer('a', { imageName: 'new' }), second] });
+    });
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('stale');
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    setDocument({ ...doc, layers: [rasterLayer('a', { imageName: 'new' })] });
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases a stale decode without waiting for a matching paint source to change', async () => {
+    const bitmap = recordingBitmap('stale-shared-paint');
+    const first = rasterLayer('a', { imageName: 'shared' });
+    const second: CanvasRasterLayerContractV2 = {
+      ...(rasterLayer('b') as CanvasRasterLayerContractV2),
+      source: { bitmap: { height: 10, imageName: 'shared', width: 10 }, type: 'paint' },
+    };
+    const doc = { ...makeDoc(), layers: [first, second] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const backend = createInvalidateDuringBitmapDrawBackend(bitmap, () => {
+      setDocument({ ...doc, layers: [second] });
+    });
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('stale');
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    setDocument({
+      ...doc,
+      layers: [{ ...second, source: { bitmap: { height: 10, imageName: 'new', width: 10 }, type: 'paint' } }],
+    });
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases a stale decode without waiting for a matching mask bitmap to change', async () => {
+    const bitmap = recordingBitmap('stale-shared-mask');
+    const first = rasterLayer('a', { imageName: 'shared' });
+    const second: CanvasInpaintMaskLayerContract = {
+      ...maskLayer('b'),
+      mask: {
+        ...maskLayer('b').mask,
+        bitmap: { height: 10, imageName: 'shared', width: 10 },
+      },
+    };
+    const doc = { ...makeDoc(), layers: [first, second] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const backend = createInvalidateDuringBitmapDrawBackend(bitmap, () => {
+      setDocument({ ...doc, layers: [second] });
+    });
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('stale');
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    setDocument({
+      ...doc,
+      layers: [
+        {
+          ...second,
+          mask: { ...second.mask, bitmap: { height: 10, imageName: 'new', width: 10 } },
+        },
+      ],
+    });
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('releases a finished unpublished decode while another request is still in flight', async () => {
+    const bitmap = recordingBitmap('stale-shared-in-flight');
+    const secondResolve = createDeferred<Blob>();
+    let resolveCount = 0;
+    const resolver = vi.fn(() => {
+      resolveCount += 1;
+      return resolveCount === 1 ? Promise.resolve(new Blob()) : secondResolve.promise;
+    });
+    const first = rasterLayer('a', { imageName: 'shared' });
+    const second = rasterLayer('b', { imageName: 'shared' });
+    const doc = { ...makeDoc(), layers: [first, second] };
+    const { setDocument, store } = createReactiveStore(doc);
+    const backend = createInvalidateDuringBitmapDrawBackend(bitmap, () => {
+      setDocument({
+        ...doc,
+        layers: [rasterLayer('a', { imageName: 'first-new' }), rasterLayer('b', { imageName: 'second-new' })],
+      });
+    });
+    const engine = createCanvasEngine({ backend, imageResolver: resolver, projectId: 'p1', store });
+
+    const firstRequest = engine.previews.requestLayerThumbnail('a');
+    const secondRequest = engine.previews.requestLayerThumbnail('b');
+    expect(await firstRequest).toBe('stale');
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+
+    secondResolve.resolve(new Blob());
+    expect(await secondRequest).toBe('stale');
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('deduplicates concurrent requests for the same source version', async () => {
+    const pending = createDeferred<Blob>();
+    const resolver = vi.fn(() => pending.promise);
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const first = engine.previews.requestLayerThumbnail('a');
+    const second = engine.previews.requestLayerThumbnail('a');
+    expect(resolver).toHaveBeenCalledTimes(1);
+
+    pending.resolve(new Blob());
+    expect(await Promise.all([first, second])).toEqual(['ready', 'ready']);
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps loading until the latest source wins', async () => {
+    const { requests, resolver } = createAbortableImageResolver();
+    const doc = makeDoc();
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const oldRequest = engine.previews.requestLayerThumbnail('a');
+    setDocument({ ...doc, layers: [rasterLayer('a', { imageName: 'a-v2' })] });
+    expect(requests.get('a')?.signal?.aborted).toBe(true);
+    const newRequest = engine.previews.requestLayerThumbnail('a');
+
+    expect(await oldRequest).toBe('stale');
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('loading');
+
+    requests.get('a-v2')?.deferred.resolve(new Blob());
+    expect(await newRequest).toBe('ready');
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('ready');
+    engine.lifecycle.dispose();
+  });
+
+  it('reports failures through status and diagnostics, then retries', async () => {
+    const resolver = vi.fn().mockRejectedValueOnce(new Error('decode failed')).mockResolvedValueOnce(new Blob());
+    const { store } = createReactiveStore(makeDoc());
+    const reportError = vi.fn();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      reportError,
+      store,
+    });
+
+    expect(await engine.previews.requestLayerThumbnail('a')).toBe('error');
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('error');
+    expect(reportError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        area: 'canvas-engine',
+        context: expect.objectContaining({ error: 'decode failed', layerId: 'a' }),
+        message: 'Layer thumbnail rasterization failed',
+        namespace: 'canvas',
+        projectId: 'p1',
+      })
+    );
+
+    const retry = engine.previews.requestLayerThumbnail('a');
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('loading');
+    expect(await retry).toBe('ready');
+    expect(resolver).toHaveBeenCalledTimes(2);
+    engine.lifecycle.dispose();
+  });
+
+  it('clears state and rejects stale completion after deletion', async () => {
+    const { requests, resolver } = createAbortableImageResolver();
+    const doc = makeDoc();
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const request = engine.previews.requestLayerThumbnail('a');
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('loading');
+    setDocument({ ...doc, layers: [] });
+    expect(requests.get('a')?.signal?.aborted).toBe(true);
+    expect(engine.stores.thumbnailStatus.get('a')).toBeUndefined();
+
+    expect(await request).toBe('stale');
+    expect(engine.stores.thumbnailStatus.get('a')).toBeUndefined();
+    expect(engine.previews.drawLayerThumbnail('a', createThumbnailTarget().target, 96)).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('clears state when the document is replaced', async () => {
+    const { requests, resolver } = createAbortableImageResolver();
+    const doc = makeDoc();
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const request = engine.previews.requestLayerThumbnail('a');
+    setDocument({ ...doc, width: doc.width + 1 }, 1);
+
+    expect(requests.get('a')?.signal?.aborted).toBe(true);
+    expect(await request).toBe('stale');
+    expect(engine.stores.thumbnailStatus.get('a')).toBeUndefined();
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps an in-flight thumbnail request after another project becomes active', async () => {
+    const pending = createDeferred<Blob>();
+    let signal: AbortSignal | undefined;
+    const resolver = vi.fn((_imageName: string, nextSignal?: AbortSignal) => {
+      signal = nextSignal;
+      return pending.promise;
+    });
+    const { setActiveProjectId, store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const request = engine.previews.requestLayerThumbnail('a');
+    setActiveProjectId('p2');
+    expect(signal?.aborted).toBe(false);
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('loading');
+
+    pending.resolve(new Blob());
+    expect(await request).toBe('ready');
+    expect(engine.stores.thumbnailStatus.get('a')).toBe('ready');
+    expect(engine.previews.drawLayerThumbnail('a', createThumbnailTarget().target, 96)).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('clears state and rejects stale completion after disposal', async () => {
+    const { requests, resolver } = createAbortableImageResolver();
+    const { store } = createReactiveStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+
+    const request = engine.previews.requestLayerThumbnail('a');
+    engine.lifecycle.dispose();
+    expect(requests.get('a')?.signal?.aborted).toBe(true);
+    expect(engine.stores.thumbnailStatus.get('a')).toBeUndefined();
+
+    expect(await request).toBe('stale');
+    expect(engine.stores.thumbnailStatus.get('a')).toBeUndefined();
+  });
+});
+
+// ---- mergeLayerDown: composites the upper cache into the below local space ----
+
+const twoPaintDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [
+    {
+      blendMode: 'multiply',
+      id: 'upper',
+      isEnabled: true,
+      isLocked: false,
+      name: 'upper',
+      opacity: 0.5,
+      // Content-sized: a persisted bitmap gives the cache a non-empty content rect.
+      // The upper (40×40) sits fully within the below (60×60) in below-local space,
+      // so the merge union stays 60×60 and the warped upper transform is non-trivial.
+      source: { bitmap: { height: 40, imageName: 'upper-bmp', width: 40 }, offset: { x: 0, y: 0 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 30, y: 40 },
+      type: 'raster',
+    },
+    {
+      blendMode: 'normal',
+      id: 'below',
+      isEnabled: true,
+      isLocked: false,
+      name: 'below',
+      opacity: 1,
+      // Offset so the merge matrix is non-trivial (below-local origin shifts).
+      source: { bitmap: { height: 60, imageName: 'below-bmp', width: 60 }, offset: { x: 0, y: 0 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 },
+      type: 'raster',
+    },
+  ],
+  selectedLayerId: 'upper',
+  version: 2,
+  width: 100,
+});
+
+/** An empty inpaint mask layer, for the merge-down mask-rejection tests below. */
+const maskLayer = (id: string): CanvasInpaintMaskLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+describe('mergeLayerDown', () => {
+  it('composites below then the transformed upper cache, and dispatches mergeCanvasLayersDown', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { store } = createReactiveStore(twoPaintDoc());
+    const dispatch = store.dispatch as Mock;
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    // One frame builds both layer caches; await the async bitmap decode so both
+    // caches are READY (merge refuses stale/in-flight caches — finding 20).
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    const surfacesBeforeMerge = surfaces.length;
+    expect(engine.layers.mergeLayerDown('upper')).toBe(true);
+
+    // The reducer is asked to collapse the two layers into a paint layer.
+    const mergeCall = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .find((action) => action.type === 'mergeCanvasLayersDown');
+    expect(mergeCall).toEqual({
+      source: { bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' },
+      type: 'mergeCanvasLayersDown',
+      upperLayerId: 'upper',
+    });
+
+    // A fresh union-sized surface was allocated for the merged pixels. Content-
+    // sized: below's rect {0,0,60,60} unioned with upper's rect warped into
+    // below-local space {20,20,40,40} is {0,0,60,60}, so the merged surface stays
+    // 60×60 with origin (0,0).
+    const merged = surfaces[surfacesBeforeMerge];
+    expect(merged).toBeDefined();
+    expect(merged!.width).toBe(60);
+    expect(merged!.height).toBe(60);
+    const log = merged!.callLog;
+
+    const expectedMatrix = mergeDownMatrix(
+      { rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 },
+      { rotation: 0, scaleX: 1, scaleY: 1, x: 30, y: 40 }
+    )!;
+    // upper{30,40} → below-local via inverse(below{10,20}) = translate(20,20).
+    expect(expectedMatrix.e).toBe(20);
+    expect(expectedMatrix.f).toBe(20);
+    const mergedOrigin = { x: 0, y: 0 };
+    const matrixIndex = log.findIndex(
+      (entry) =>
+        entry.op === 'setTransform' &&
+        entry.args[0] === expectedMatrix.a &&
+        entry.args[4] === expectedMatrix.e - mergedOrigin.x &&
+        entry.args[5] === expectedMatrix.f - mergedOrigin.y
+    );
+    expect(matrixIndex).toBeGreaterThan(-1);
+
+    // Below is blitted before the upper transform; the upper after it.
+    const drawIndices = log.reduce<number[]>((acc, entry, index) => {
+      if (entry.op === 'drawImage') {
+        acc.push(index);
+      }
+      return acc;
+    }, []);
+    expect(drawIndices).toHaveLength(2);
+    expect(drawIndices[0]).toBeLessThan(matrixIndex);
+    expect(drawIndices[1]).toBeGreaterThan(matrixIndex);
+
+    // The upper layer's opacity and blend mode are baked into the merge.
+    const alphaSet = log.find(
+      (entry) => entry.op === 'set' && entry.args[0] === 'globalAlpha' && entry.args[1] === 0.5
+    );
+    const blendSet = log.find(
+      (entry) => entry.op === 'set' && entry.args[0] === 'globalCompositeOperation' && entry.args[1] === 'multiply'
+    );
+    expect(alphaSet).toBeDefined();
+    expect(blendSet).toBeDefined();
+
+    engine.lifecycle.dispose();
+  });
+
+  it('is a no-op for the bottom-most layer (nothing below)', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { store } = createReactiveStore(twoPaintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    expect(engine.layers.mergeLayerDown('below')).toBe(false);
+    expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+      false
+    );
+
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['upper', 'below'] as const)(
+    "is a no-op when the %s layer is locked (merge is not undoable; must mirror the paint tool's locked-target refusal)",
+    (lockedId) => {
+      const raf = createControllableRaf();
+      vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+      vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+      const doc = twoPaintDoc();
+      const locked = {
+        ...doc,
+        layers: doc.layers.map((layer) => (layer.id === lockedId ? { ...layer, isLocked: true } : layer)),
+      };
+      const { store } = createReactiveStore(locked);
+      const dispatch = store.dispatch as Mock;
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      const screen = createFakeCanvas();
+      const overlay = createFakeCanvas();
+      engine.surface.attach(screen.element, overlay.element);
+      raf.flush();
+
+      expect(engine.layers.mergeLayerDown('upper')).toBe(false);
+      expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+        false
+      );
+
+      engine.lifecycle.dispose();
+    }
+  );
+
+  // A two-paint doc where exactly ONE layer is content-empty (bitmap: null → a 0×0
+  // cache surface). Merging must NOT `drawImage` the zero-dimension operand (which
+  // throws in browsers) but must still dispatch the collapse and composite the
+  // non-empty operand.
+  const oneEmptyPaintDoc = (emptyId: 'upper' | 'below'): CanvasDocumentContractV2 => {
+    const doc = twoPaintDoc();
+    return {
+      ...doc,
+      layers: doc.layers.map((layer) =>
+        layer.id === emptyId ? { ...layer, source: { bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' } } : layer
+      ),
+    };
+  };
+
+  it.each([
+    { emptyId: 'upper', keptId: 'below' },
+    { emptyId: 'below', keptId: 'upper' },
+  ] as const)(
+    'merges when only the $emptyId layer is empty: dispatches, and never draws a 0×0 surface',
+    async ({ emptyId }) => {
+      const raf = createControllableRaf();
+      vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+      vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+      const { store } = createReactiveStore(oneEmptyPaintDoc(emptyId));
+      const dispatch = store.dispatch as Mock;
+      const base = createTestStubRasterBackend();
+      const surfaces: StubRasterSurface[] = [];
+      const backend = {
+        ...base,
+        createSurface: (w: number, h: number): StubRasterSurface => {
+          const surface = base.createSurface(w, h);
+          surfaces.push(surface);
+          return surface;
+        },
+      };
+      const engine = createCanvasEngine({
+        backend,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      const screen = createFakeCanvas();
+      const overlay = createFakeCanvas();
+      engine.surface.attach(screen.element, overlay.element);
+      // Await the kept layer's bitmap decode so its cache is READY before merge
+      // (the empty operand needs no decode; merge refuses stale/in-flight caches).
+      raf.flush();
+      await flushMicrotasks();
+      raf.flush();
+
+      const surfacesBeforeMerge = surfaces.length;
+      expect(engine.layers.mergeLayerDown('upper')).toBe(true);
+
+      // Single-dispatch collapse still happens (undo semantics unchanged).
+      expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+        true
+      );
+
+      // The merged surface only composites the NON-empty operand: exactly one
+      // drawImage, and it never draws a zero-dimension source canvas.
+      const merged = surfaces[surfacesBeforeMerge];
+      expect(merged).toBeDefined();
+      const draws = merged!.callLog.filter((entry) => entry.op === 'drawImage');
+      expect(draws).toHaveLength(1);
+      for (const draw of draws) {
+        const src = draw.args[0] as { width: number; height: number };
+        expect(src.width).toBeGreaterThan(0);
+        expect(src.height).toBeGreaterThan(0);
+      }
+
+      engine.lifecycle.dispose();
+    }
+  );
+
+  // A both-empty pair must fold trivially (delete the upper, below stays empty)
+  // rather than silently no-op — otherwise merge-visible stalls on such a run (F4).
+  it('folds a both-empty pair trivially: dispatches the collapse and allocates no merged surface (F4)', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const base = twoPaintDoc();
+    const doc: CanvasDocumentContractV2 = {
+      ...base,
+      layers: base.layers.map((layer) => ({
+        ...layer,
+        source: { bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' as const },
+      })),
+    };
+    const { store } = createReactiveStore(doc);
+    const dispatch = store.dispatch as Mock;
+    const backendBase = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...backendBase,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = backendBase.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    const surfacesBeforeMerge = surfaces.length;
+    expect(engine.layers.mergeLayerDown('upper')).toBe(true);
+
+    // The collapse still dispatches (the upper layer is removed).
+    expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+      true
+    );
+    // No merged surface was allocated: a 0×0 union surface would throw, and there
+    // are no pixels to composite.
+    expect(surfaces.length).toBe(surfacesBeforeMerge);
+
+    engine.lifecycle.dispose();
+  });
+
+  // Regression: `mergeLayerDown` used to gate on `isRenderableLayer`, which masks
+  // satisfy (a mask rasterizes to a stencil whenever enabled). That let a mask
+  // reach the merge path, whose reducer unconditionally produces a `type: 'raster'`
+  // result — merging a mask blitted its stencil into the layer below and/or
+  // clobbered a mask below into a raster layer, destroying its config, with no
+  // undo. The guard must reject a mask on EITHER side, mirroring the layers
+  // panel's `isMergeableRasterLayer`/`canMergeLayerDown` enablement exactly.
+  it.each([
+    { label: 'mask above a raster layer', maskId: 'upper' as const },
+    { label: 'a raster layer above a mask', maskId: 'below' as const },
+  ])('is a no-op for $label (document unchanged, no dispatch)', ({ maskId }) => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const base = twoPaintDoc();
+    const doc: CanvasDocumentContractV2 = {
+      ...base,
+      layers: base.layers.map((layer) => (layer.id === maskId ? maskLayer(maskId) : layer)),
+    };
+    const { store } = createReactiveStore(doc);
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    expect(engine.layers.mergeLayerDown('upper')).toBe(false);
+    expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+      false
+    );
+    // Document unchanged: still two layers, each with its original type — no
+    // mask was blitted into, and no mask was clobbered into a raster layer.
+    expect(engine.document.getDocument()!.layers.map((l) => l.type)).toEqual(doc.layers.map((l) => l.type));
+
+    engine.lifecycle.dispose();
+  });
+
+  it('is a no-op for mask-above-mask (document unchanged, no dispatch)', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const base = twoPaintDoc();
+    const doc: CanvasDocumentContractV2 = {
+      ...base,
+      layers: [maskLayer('upper'), maskLayer('below')],
+    };
+    const { store } = createReactiveStore(doc);
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    expect(engine.layers.mergeLayerDown('upper')).toBe(false);
+    expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+      false
+    );
+    expect(engine.document.getDocument()!.layers.map((l) => l.type)).toEqual(['inpaint_mask', 'inpaint_mask']);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('boolean raster operations', () => {
+  const setup = () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const { projectId, store } = createReducerBackedStore(twoPaintDoc());
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (width: number, height: number): StubRasterSurface => {
+        const surface = base.createSurface(width, height);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    return { engine, raf, surfaces };
+  };
+
+  it.each([
+    ['intersect', 'source-in'],
+    ['cutout', 'destination-in'],
+    ['cutaway', 'source-out'],
+    ['exclude', 'xor'],
+  ] as const)('applies %s with %s, preserves its sources, and supports undo/redo', async (operation, composite) => {
+    const { engine, raf, surfaces } = setup();
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    expect(await engine.layers.booleanMergeRasterLayers('upper', operation)).toBe('merged');
+
+    const resultSurface = surfaces.find((surface) =>
+      surface.callLog.some(
+        (entry) => entry.op === 'set' && entry.args[0] === 'globalCompositeOperation' && entry.args[1] === composite
+      )
+    );
+    expect(resultSurface).toBeDefined();
+    expect(resultSurface!.callLog.filter((entry) => entry.op === 'drawImage')).toHaveLength(2);
+
+    const merged = engine.document.getDocument()!;
+    const result = merged.layers.find((layer) => layer.id !== 'upper' && layer.id !== 'below');
+    expect(result).toMatchObject({
+      isEnabled: true,
+      source: { bitmap: null, offset: { x: 10, y: 20 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    expect(merged.layers.find((layer) => layer.id === 'upper')?.isEnabled).toBe(false);
+    expect(merged.layers.find((layer) => layer.id === 'below')?.isEnabled).toBe(false);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.map((layer) => [layer.id, layer.isEnabled])).toEqual([
+      ['upper', true],
+      ['below', true],
+    ]);
+
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers.map((layer) => [layer.id, layer.isEnabled])).toEqual([
+      [result!.id, true],
+      ['upper', false],
+      ['below', false],
+    ]);
+    engine.lifecycle.dispose();
+  });
+
+  it('publishes a boolean merge into its bound project after another project becomes active', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const { setActiveProjectId, store } = createReactiveStore(twoPaintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    (store.dispatch as Mock).mockClear();
+
+    const merge = engine.layers.booleanMergeRasterLayers('upper', 'intersect');
+    setActiveProjectId('p2');
+
+    expect(await merge).toBe('merged');
+    expect(store.dispatch).toHaveBeenCalledWith(expect.objectContaining({ type: 'applyCanvasLayerStackMutation' }));
+    engine.lifecycle.dispose();
+  });
+
+  it('refuses the operation until both raster caches are ready', async () => {
+    const { engine, raf } = setup();
+    raf.flush();
+
+    expect(await engine.layers.booleanMergeRasterLayers('upper', 'intersect')).toBe('not-ready');
+    expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual(['upper', 'below']);
+    engine.lifecycle.dispose();
+  });
+
+  it('rejects unsupported and missing layer pairs without modifying the document', async () => {
+    const doc = twoPaintDoc();
+    doc.layers[1] = maskLayer('below');
+    const { projectId, store } = createReducerBackedStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    expect(await engine.layers.booleanMergeRasterLayers('upper', 'exclude')).toBe('unsupported');
+    expect(await engine.layers.booleanMergeRasterLayers('missing', 'exclude')).toBe('missing');
+    expect(engine.document.getDocument()!.layers).toEqual(doc.layers);
+    engine.lifecycle.dispose();
+  });
+
+  it('merges two live unflushed paint caches whose contract bitmaps are still null', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const emptyPaint = (id: string): CanvasRasterLayerContractV2 => ({
+      blendMode: 'normal',
+      id,
+      isEnabled: true,
+      isLocked: false,
+      name: id,
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    const upper = emptyPaint('upper');
+    const below = emptyPaint('below');
+    const doc = { ...makeDoc(), layers: [upper, below], selectedLayerId: 'upper' };
+    const { projectId, store } = createReducerBackedStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    overlay.fire('pointerdown', pointerAt(10, 10));
+    overlay.fire('pointermove', pointerAt(30, 30));
+    overlay.fire('pointerup', pointerAt(30, 30, { buttons: 0 }));
+    store.dispatch({ id: 'below', type: 'setCanvasSelectedLayer' });
+    overlay.fire('pointerdown', pointerAt(15, 15));
+    overlay.fire('pointermove', pointerAt(35, 35));
+    overlay.fire('pointerup', pointerAt(35, 35, { buttons: 0 }));
+
+    expect(await engine.layers.booleanMergeRasterLayers('upper', 'intersect')).toBe('merged');
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('extract masked canvas area', () => {
+  const maskedDoc = (): CanvasDocumentContractV2 => {
+    const doc = twoPaintDoc();
+    return {
+      ...doc,
+      layers: [
+        {
+          ...maskLayer('mask'),
+          mask: {
+            bitmap: { height: 20, imageName: 'mask-bitmap', width: 20 },
+            fill: { color: '#e07575', style: 'diagonal' },
+            offset: { x: 15, y: 25 },
+          },
+        },
+        ...doc.layers,
+      ],
+      selectedLayerId: 'mask',
+    };
+  };
+
+  const setup = () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const { projectId, store } = createReducerBackedStore(maskedDoc());
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (width: number, height: number): StubRasterSurface => {
+        const surface = base.createSurface(width, height);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    return { engine, raf, surfaces };
+  };
+
+  it('composites visible raster content through mask alpha and inserts one undoable raster layer', async () => {
+    const { engine, raf, surfaces } = setup();
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    const result = await engine.exports.extractMaskedArea('mask');
+    expect(result.status).toBe('extracted');
+    if (result.status !== 'extracted') {
+      throw new Error('expected an extracted layer');
+    }
+
+    const extractedPixels = surfaces.find((surface) =>
+      surface.callLog.some(
+        (entry) =>
+          entry.op === 'set' && entry.args[0] === 'globalCompositeOperation' && entry.args[1] === 'destination-in'
+      )
+    );
+    expect(extractedPixels).toMatchObject({ height: 20, width: 20 });
+    expect(extractedPixels!.callLog.filter((entry) => entry.op === 'drawImage').length).toBeGreaterThanOrEqual(3);
+
+    const extracted = engine.document.getDocument()!.layers.find((layer) => layer.id === result.layerId);
+    expect(extracted).toMatchObject({
+      isEnabled: true,
+      source: { bitmap: null, offset: { x: 15, y: 25 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    expect(engine.document.getDocument()!.layers.find((layer) => layer.id === 'mask')).toEqual(maskedDoc().layers[0]);
+    expect(engine.document.getDocument()!.layers.find((layer) => layer.id === 'upper')?.isEnabled).toBe(true);
+    expect(engine.document.getDocument()!.layers.find((layer) => layer.id === 'below')?.isEnabled).toBe(true);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === result.layerId)).toBe(false);
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === result.layerId)).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('extracts enabled raster layers but never control layers', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const raster = rasterLayer('raster');
+    const control: CanvasLayerContract = {
+      adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      blendMode: 'normal',
+      id: 'control',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Control',
+      opacity: 1,
+      source: { image: { height: 10, imageName: 'control', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'control',
+      withTransparencyEffect: false,
+    };
+    const mask: CanvasInpaintMaskLayerContract = {
+      ...maskLayer('mask'),
+      mask: {
+        ...maskLayer('mask').mask,
+        bitmap: { height: 10, imageName: 'mask', width: 10 },
+      },
+    };
+    const document = { ...makeDoc(), layers: [mask, raster, control], selectedLayerId: 'mask' };
+    const { projectId, store } = createReducerBackedStore(document);
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const engine = createCanvasEngine({
+      backend: {
+        ...base,
+        createSurface: (width, height) => {
+          const surface = base.createSurface(width, height);
+          surfaces.push(surface);
+          return surface;
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    const rasterExport = await engine.exports.exportLayerPixels(raster.id);
+    const controlExport = await engine.exports.exportLayerPixels(control.id);
+    expect(rasterExport.status).toBe('ok');
+    expect(controlExport.status).toBe('ok');
+    if (rasterExport.status !== 'ok' || controlExport.status !== 'ok') {
+      throw new Error('fixture layers did not rasterize');
+    }
+
+    expect((await engine.exports.extractMaskedArea(mask.id)).status).toBe('extracted');
+
+    const extractedPixels = surfaces.find((surface) =>
+      surface.callLog.some(
+        (entry) =>
+          entry.op === 'set' && entry.args[0] === 'globalCompositeOperation' && entry.args[1] === 'destination-in'
+      )
+    );
+    const compositeSources = extractedPixels?.callLog
+      .filter((entry) => entry.op === 'drawImage')
+      .map((entry) => entry.args[0]);
+    expect(compositeSources).toContain(rasterExport.surface.canvas);
+    expect(compositeSources).not.toContain(controlExport.surface.canvas);
+    engine.lifecycle.dispose();
+  });
+
+  it('skips enabled raster layers that have no persisted or live pixels', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const document = maskedDoc();
+    const blank: CanvasRasterLayerContractV2 = {
+      blendMode: 'normal',
+      id: 'blank',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Blank',
+      opacity: 1,
+      source: { bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    };
+    document.layers.splice(2, 0, blank);
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    expect((await engine.exports.extractMaskedArea('mask')).status).toBe('extracted');
+    engine.lifecycle.dispose();
+  });
+
+  it('does not extract stale contributor pixels after a source change during await', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const document = maskedDoc();
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    (store.dispatch as Mock).mockClear();
+
+    const extraction = engine.exports.extractMaskedArea('mask');
+    setDocument({
+      ...document,
+      layers: document.layers.map((layer) =>
+        layer.id === 'upper' && layer.type === 'raster'
+          ? {
+              ...layer,
+              source: {
+                bitmap: { height: 40, imageName: 'upper-v2', width: 40 },
+                offset: { x: 0, y: 0 },
+                type: 'paint',
+              },
+            }
+          : layer
+      ),
+    });
+
+    expect(await extraction).toEqual({ status: 'not-ready' });
+    expect(store.dispatch).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+
+  it('refuses extraction from a locked mask', async () => {
+    const document = maskedDoc();
+    document.layers[0] = { ...document.layers[0]!, isLocked: true };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    expect(await engine.exports.extractMaskedArea('mask')).toEqual({ status: 'unsupported' });
+    engine.lifecycle.dispose();
+  });
+
+  it('refuses extraction until the mask and contributor caches are ready', async () => {
+    const { engine, raf } = setup();
+    raf.flush();
+
+    expect(await engine.exports.extractMaskedArea('mask')).toEqual({ status: 'not-ready' });
+    expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual(['mask', 'upper', 'below']);
+    engine.lifecycle.dispose();
+  });
+
+  it('rejects missing, unsupported, and empty masks without changing the document', async () => {
+    const doc = maskedDoc();
+    const { projectId, store } = createReducerBackedStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+
+    expect(await engine.exports.extractMaskedArea('missing')).toEqual({ status: 'missing' });
+    expect(await engine.exports.extractMaskedArea('upper')).toEqual({ status: 'unsupported' });
+    expect(await engine.exports.extractMaskedArea('mask')).toEqual({ status: 'not-ready' });
+    expect(engine.document.getDocument()!.layers).toEqual(doc.layers);
+    engine.lifecycle.dispose();
+
+    const emptyDoc = maskedDoc();
+    emptyDoc.layers[0] = maskLayer('mask');
+    const emptyHarness = createReducerBackedStore(emptyDoc);
+    const emptyEngine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: emptyHarness.projectId,
+      store: emptyHarness.store,
+    });
+    expect(await emptyEngine.exports.extractMaskedArea('mask')).toEqual({ status: 'empty' });
+    emptyEngine.lifecycle.dispose();
+  });
+});
+
+// ---- mergeVisibleRasterLayers: guarded non-destructive composite ----
+
+/**
+ * An EngineStore backed by the REAL workbench reducer, so the operation's
+ * prepared stack mutation advances the document and mirror atomically — the
+ * no-op mock store cannot exercise that transaction.
+ */
+const createReducerBackedStore = (
+  document: CanvasDocumentContractV2,
+  mainBase?: string
+): { dispatch: Mock<(action: EngineTestAction) => void>; projectId: string; store: EngineStore } => {
+  let state = createInitialWorkbenchState();
+  const projectId = state.projects[0]!.id;
+  state = workbenchReducer(state, {
+    mutation: { document, type: 'replaceCanvasDocument' },
+    projectId,
+    type: 'applyCanvasProjectMutation',
+  });
+  if (mainBase) {
+    state = workbenchReducer(state, {
+      type: 'patchWidgetValues',
+      values: { model: { base: mainBase, key: `${mainBase}-main`, name: `${mainBase} main`, type: 'main' } },
+      widgetId: 'generate',
+    });
+  }
+  const listeners = new Set<() => void>();
+  const dispatch = vi.fn((action: EngineTestAction) => {
+    state = workbenchReducer(
+      state,
+      isCanvasProjectMutation(action) ? { mutation: action, projectId, type: 'applyCanvasProjectMutation' } : action
+    );
+    for (const listener of listeners) {
+      listener();
+    }
+  });
+  return {
+    dispatch,
+    projectId,
+    store: {
+      dispatch,
+      getState: () => state,
+      reducesCanvasMutations: true,
+      subscribe: (listener) => {
+        listeners.add(listener);
+        return () => {
+          listeners.delete(listener);
+        };
+      },
+    },
+  };
+};
+
+describe('staged result acceptance', () => {
+  const stagedCandidate = (): CanvasStagingCandidateContract => ({
+    height: 20,
+    imageName: 'staged-result.png',
+    imageUrl: '/staged-result.png',
+    placement: { height: 40, opacity: 0.75, width: 30, x: 7, y: 9 },
+    queuedAt: '2026-07-16T00:00:00.000Z',
+    sourceQueueItemId: 'queue-staged',
+    thumbnailUrl: '/staged-result-thumb.png',
+    width: 15,
+  });
+  const stagedSelection = (candidate: CanvasStagingCandidateContract, selectedImageIndex = 0) => ({
+    candidate,
+    selectedImageIndex,
+  });
+
+  it('commits through the project-bound engine and preserves layer identity and staging semantics across undo/redo', () => {
+    const reducer = createReducerBackedStore({ ...makeDoc(), selectedLayerId: 'a' });
+    const candidate = stagedCandidate();
+    reducer.store.dispatch({
+      candidate,
+      projectId: reducer.projectId,
+      type: 'appendCanvasStagingCandidate',
+    });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+
+    const result = engine.layers.commitStagedImage(stagedSelection(candidate));
+
+    expect(result.status).toBe('committed');
+    if (result.status !== 'committed') {
+      throw new Error('expected commit');
+    }
+    const projectAfterCommit = reducer.store.getState().projects[0]!;
+    const acceptedLayer = projectAfterCommit.canvas.document.layers[0]!;
+    const acceptedEvent = projectAfterCommit.events[0]!;
+    expect(acceptedLayer).toMatchObject({
+      id: result.layerId,
+      opacity: 0.75,
+      source: { image: { imageName: 'staged-result.png' }, type: 'image' },
+      transform: { scaleX: 2, scaleY: 2, x: 7, y: 9 },
+    });
+    expect(projectAfterCommit.canvas.stagingArea.pendingImages).toEqual([]);
+    expect(acceptedEvent.type).toBe('canvas-layer-accepted');
+
+    engine.history.undo();
+    const projectAfterUndo = reducer.store.getState().projects[0]!;
+    expect(projectAfterUndo.canvas.document.layers).not.toContainEqual(expect.objectContaining({ id: result.layerId }));
+    expect(projectAfterUndo.canvas.document.selectedLayerId).toBe('a');
+    expect(projectAfterUndo.canvas.stagingArea.pendingImages).toEqual([]);
+
+    engine.history.redo();
+    const projectAfterRedo = reducer.store.getState().projects[0]!;
+    expect(projectAfterRedo.canvas.document.layers[0]).toBe(acceptedLayer);
+    expect(projectAfterRedo.canvas.stagingArea.pendingImages).toEqual([]);
+    expect(projectAfterRedo.events).toContain(acceptedEvent);
+    expect(projectAfterRedo.events.filter((event) => event.id === acceptedEvent.id)).toHaveLength(1);
+
+    engine.history.undo();
+    expect(engine.stores.canRedo.get()).toBe(true);
+    reducer.store.dispatch({
+      candidate: { ...candidate, imageName: 'new-staged-result.png' },
+      projectId: reducer.projectId,
+      type: 'appendCanvasStagingCandidate',
+    });
+    expect(
+      engine.layers.commitStagedImage(stagedSelection({ ...candidate, imageName: 'new-staged-result.png' })).status
+    ).toBe('committed');
+    expect(engine.stores.canRedo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns stale without changing staging or history when the selected candidate key changes', () => {
+    const reducer = createReducerBackedStore(makeDoc());
+    const first = stagedCandidate();
+    const second = { ...stagedCandidate(), imageName: 'new-selection.png' };
+    reducer.store.dispatch({ candidate: first, projectId: reducer.projectId, type: 'appendCanvasStagingCandidate' });
+    reducer.store.dispatch({ candidate: second, projectId: reducer.projectId, type: 'appendCanvasStagingCandidate' });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    const before = reducer.store.getState().projects[0]!.canvas;
+
+    expect(engine.layers.commitStagedImage(stagedSelection(first, 1))).toEqual({ status: 'stale' });
+    expect(reducer.store.getState().projects[0]!.canvas).toBe(before);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns busy without changing staging or history while an edit lease is active', async () => {
+    const reducer = createReducerBackedStore(makeDoc());
+    reducer.store.dispatch({
+      candidate: stagedCandidate(),
+      projectId: reducer.projectId,
+      type: 'appendCanvasStagingCandidate',
+    });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    const exported = await engine.exports.exportLayerPixels('a');
+    if (exported.status !== 'ok') {
+      throw new Error('expected current layer guard');
+    }
+    const operations = getCanvasOperations(engine);
+    expect(
+      operations.controller.start({
+        cleanupPreview: vi.fn(),
+        guard: exported.guard,
+        identity: { kind: 'filter', layerId: 'a', projectId: reducer.projectId },
+      })
+    ).not.toBeNull();
+    const before = reducer.store.getState().projects[0]!.canvas;
+
+    expect(engine.layers.commitStagedImage(stagedSelection(stagedCandidate()))).toEqual({ status: 'busy' });
+    expect(reducer.store.getState().projects[0]!.canvas).toBe(before);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    operations.controller.cancel();
+    engine.lifecycle.dispose();
+  });
+
+  it('returns busy without changing staging or history while a pointer gesture is active', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const reducer = createReducerBackedStore(makeDoc());
+    reducer.store.dispatch({
+      candidate: stagedCandidate(),
+      projectId: reducer.projectId,
+      type: 'appendCanvasStagingCandidate',
+    });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    const screen = createInputCanvas();
+    const overlay = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('view');
+    overlay.fire('pointerdown', pointerAt(10, 10));
+    const before = reducer.store.getState().projects[0]!.canvas;
+
+    expect(engine.layers.commitStagedImage(stagedSelection(stagedCandidate()))).toEqual({ status: 'busy' });
+    expect(reducer.store.getState().projects[0]!.canvas).toBe(before);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    overlay.fire('pointerup', pointerAt(10, 10, { buttons: 0 }));
+    engine.lifecycle.dispose();
+  });
+
+  it('returns stale without changing staging or history when the reducer rejects acceptance', () => {
+    const document = makeDoc();
+    const canvas = makeCanvas(document);
+    canvas.stagingArea = {
+      ...canvas.stagingArea,
+      isVisible: true,
+      pendingImageIds: ['staged-result.png'],
+      pendingImages: [stagedCandidate()],
+    };
+    const mutationPort: CanvasProjectMutationPort = {
+      dispatch: () => false,
+      getCanvasState: () => canvas,
+      subscribe: () => () => undefined,
+    };
+    const { store } = createFakeStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort,
+      projectId: 'p1',
+      store,
+    });
+
+    expect(engine.layers.commitStagedImage(stagedSelection(stagedCandidate()))).toEqual({ status: 'stale' });
+    expect(canvas.stagingArea.pendingImages).toEqual([stagedCandidate()]);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns stale without history when reducer state cannot converge into the document mirror', () => {
+    const document = makeDoc();
+    const canvas = makeCanvas(document);
+    canvas.stagingArea = {
+      ...canvas.stagingArea,
+      isVisible: true,
+      pendingImageIds: ['staged-result.png'],
+      pendingImages: [stagedCandidate()],
+    };
+    let reducerCanvas = canvas;
+    let committed = false;
+    let postCommitReads = 0;
+    const mutationPort: CanvasProjectMutationPort = {
+      dispatch: (mutation) => {
+        if (mutation.type !== 'commitStagedImage') {
+          return false;
+        }
+        reducerCanvas = {
+          ...canvas,
+          document: { ...document, layers: [mutation.layer, ...document.layers], selectedLayerId: mutation.layer.id },
+          stagingArea: { ...canvas.stagingArea, pendingImageIds: [], pendingImages: [] },
+        };
+        committed = true;
+        return true;
+      },
+      getCanvasState: () => {
+        if (!committed) {
+          return canvas;
+        }
+        postCommitReads += 1;
+        return postCommitReads === 1 ? reducerCanvas : canvas;
+      },
+      subscribe: () => () => undefined,
+    };
+    const { store } = createFakeStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort,
+      projectId: 'p1',
+      store,
+    });
+
+    expect(engine.layers.commitStagedImage(stagedSelection(stagedCandidate()))).toEqual({ status: 'stale' });
+    expect(engine.document.getDocument()).toBe(document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns missing without history for an absent staged candidate or project', () => {
+    const reducer = createReducerBackedStore(makeDoc());
+    const candidateMissingEngine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    expect(
+      candidateMissingEngine.layers.commitStagedImage(
+        stagedSelection({ ...stagedCandidate(), imageName: 'missing.png' })
+      )
+    ).toEqual({
+      status: 'missing',
+    });
+    expect(candidateMissingEngine.stores.canUndo.get()).toBe(false);
+    candidateMissingEngine.lifecycle.dispose();
+
+    const document = makeDoc();
+    const { store } = createFakeStore(document);
+    const projectMissingEngine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort: {
+        dispatch: () => false,
+        getCanvasState: () => null,
+        subscribe: () => () => undefined,
+      },
+      projectId: 'missing-project',
+      store,
+    });
+    expect(projectMissingEngine.layers.commitStagedImage(stagedSelection(stagedCandidate()))).toEqual({
+      status: 'missing',
+    });
+    expect(projectMissingEngine.stores.canUndo.get()).toBe(false);
+    projectMissingEngine.lifecycle.dispose();
+  });
+});
+
+describe('structural raster publication failure atomicity', () => {
+  const sentinelLayer = (): CanvasLayerContract => ({
+    ...rasterLayer('selection-sentinel'),
+    isEnabled: false,
+  });
+
+  const createFaultHarness = (document: CanvasDocumentContractV2) => {
+    const faults = createStructuralFaultBackend();
+    const bitmapStore = createSpyBitmapStore();
+    const reducer = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: faults.backend,
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    return { ...reducer, bitmapStore, engine, faults };
+  };
+
+  type StructuralFault = 'allocation' | 'draw';
+  const structuralFaults = ['allocation', 'draw'] as const satisfies readonly StructuralFault[];
+  const armStructuralFault = (
+    faults: ReturnType<typeof createStructuralFaultBackend>,
+    failure: StructuralFault,
+    countdowns: Record<StructuralFault, number>
+  ): void => {
+    if (failure === 'allocation') {
+      faults.armAllocation(countdowns.allocation);
+    } else {
+      faults.armDraw(countdowns.draw);
+    }
+  };
+  const structuralFaultMessage = (failure: StructuralFault): string => `structural cache ${failure} failed`;
+
+  const expectInitialFailureExact = (
+    harness: ReturnType<typeof createFaultHarness>,
+    expectedDocument: CanvasDocumentContractV2
+  ): void => {
+    expect(harness.engine.document.getDocument()).toBe(expectedDocument);
+    expect(harness.engine.document.getDocument()).toEqual(expectedDocument);
+    expect(harness.engine.document.getDocument()!.selectedLayerId).toBe('selection-sentinel');
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(harness.bitmapStore.discardLayer).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(harness.engine.stores.canRedo.get()).toBe(false);
+  };
+
+  it.each(structuralFaults)(
+    'crop keeps document, cache, selection, and history exact when final cache %s fails',
+    async (failure) => {
+      const source = rasterLayer('crop-source');
+      const document: CanvasDocumentContractV2 = {
+        ...makeDoc(),
+        bbox: { height: 7, width: 6, x: 2, y: 3 },
+        layers: [source, sentinelLayer()],
+        selectedLayerId: 'selection-sentinel',
+      };
+      const harness = createFaultHarness(document);
+      const sourceCache = await snapshotLayerCache(harness.engine, source.id);
+      const expectedDocument = harness.engine.document.getDocument()!;
+      (harness.store.dispatch as Mock).mockClear();
+      harness.bitmapStore.markLayerDirty.mockClear();
+      armStructuralFault(harness.faults, failure, { allocation: 3, draw: 3 });
+
+      await expect(harness.engine.layers.cropLayerToBbox(source.id)).resolves.toEqual({
+        message: structuralFaultMessage(failure),
+        status: 'failed',
+      });
+
+      expectInitialFailureExact(harness, expectedDocument);
+      await expectLayerCacheExact(harness.engine, source.id, sourceCache);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(structuralFaults)(
+    'commitLayerCopy keeps document, cache, selection, and history exact when final cache %s fails',
+    async (failure) => {
+      const source = rasterLayer('copy-source');
+      const document = { ...makeDoc(), layers: [source, sentinelLayer()], selectedLayerId: 'selection-sentinel' };
+      const harness = createFaultHarness(document);
+      const sourceCache = await snapshotLayerCache(harness.engine, source.id);
+      const expectedDocument = harness.engine.document.getDocument()!;
+      const copy = { ...structuredClone(source), id: 'copy-result', name: 'Copy result' };
+      (harness.store.dispatch as Mock).mockClear();
+      harness.bitmapStore.markLayerDirty.mockClear();
+      armStructuralFault(harness.faults, failure, { allocation: 1, draw: 1 });
+
+      expect(() => harness.engine.layers.commitLayerCopy('Copy layer', source.id, copy, 0)).toThrow(
+        structuralFaultMessage(failure)
+      );
+
+      expectInitialFailureExact(harness, expectedDocument);
+      expect(harness.engine.document.getDocument()!.layers.some((layer) => layer.id === copy.id)).toBe(false);
+      await expectLayerCacheExact(harness.engine, source.id, sourceCache);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(structuralFaults)(
+    'commitLayerConversion keeps document, cache, selection, and history exact when final cache %s fails',
+    async (failure) => {
+      const source = rasterLayer('conversion-source');
+      const document = { ...makeDoc(), layers: [source, sentinelLayer()], selectedLayerId: 'selection-sentinel' };
+      const harness = createFaultHarness(document);
+      const sourceCache = await snapshotLayerCache(harness.engine, source.id);
+      const expectedDocument = harness.engine.document.getDocument()!;
+      const live = harness.engine.document.getDocument()!.layers.find((layer) => layer.id === source.id)!;
+      if (live.type !== 'raster') {
+        throw new Error('expected a raster conversion source');
+      }
+      const converted: CanvasLayerContract = {
+        ...structuredClone(live),
+        adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+        type: 'control',
+        withTransparencyEffect: false,
+      };
+      (harness.store.dispatch as Mock).mockClear();
+      harness.bitmapStore.markLayerDirty.mockClear();
+      armStructuralFault(harness.faults, failure, { allocation: 1, draw: 1 });
+
+      expect(() => harness.engine.layers.commitLayerConversion('Convert layer', live, converted)).toThrow(
+        structuralFaultMessage(failure)
+      );
+
+      expectInitialFailureExact(harness, expectedDocument);
+      await expectLayerCacheExact(harness.engine, source.id, sourceCache);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(structuralFaults)(
+    'copyLayerToRaster keeps document, cache, selection, and history exact when final cache %s fails',
+    async (failure) => {
+      const source = rasterLayer('raster-copy-source');
+      const document = { ...makeDoc(), layers: [source, sentinelLayer()], selectedLayerId: 'selection-sentinel' };
+      const harness = createFaultHarness(document);
+      const sourceCache = await snapshotLayerCache(harness.engine, source.id);
+      const expectedDocument = harness.engine.document.getDocument()!;
+      (harness.store.dispatch as Mock).mockClear();
+      harness.bitmapStore.markLayerDirty.mockClear();
+      armStructuralFault(harness.faults, failure, { allocation: 1, draw: 1 });
+
+      await expect(harness.engine.layers.copyLayerToRaster(source.id)).rejects.toThrow(structuralFaultMessage(failure));
+
+      expectInitialFailureExact(harness, expectedDocument);
+      await expectLayerCacheExact(harness.engine, source.id, sourceCache);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(structuralFaults)(
+    'boolean merge keeps document, source caches, selection, and history exact when final cache %s fails',
+    async (failure) => {
+      const pair = twoPaintDoc();
+      const document = {
+        ...pair,
+        layers: [...pair.layers, sentinelLayer()],
+        selectedLayerId: 'selection-sentinel',
+      };
+      const harness = createFaultHarness(document);
+      const upperCache = await snapshotLayerCache(harness.engine, 'upper');
+      const belowCache = await snapshotLayerCache(harness.engine, 'below');
+      const expectedDocument = harness.engine.document.getDocument()!;
+      (harness.store.dispatch as Mock).mockClear();
+      harness.bitmapStore.markLayerDirty.mockClear();
+      armStructuralFault(harness.faults, failure, { allocation: 3, draw: 4 });
+
+      await expect(harness.engine.layers.booleanMergeRasterLayers('upper', 'intersect')).rejects.toThrow(
+        structuralFaultMessage(failure)
+      );
+
+      expectInitialFailureExact(harness, expectedDocument);
+      await expectLayerCacheExact(harness.engine, 'upper', upperCache);
+      await expectLayerCacheExact(harness.engine, 'below', belowCache);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(structuralFaults)(
+    'masked extraction keeps document, source caches, selection, and history exact when final cache %s fails',
+    async (failure) => {
+      const pair = twoPaintDoc();
+      const mask: CanvasInpaintMaskLayerContract = {
+        ...maskLayer('atomic-mask'),
+        mask: {
+          bitmap: { height: 20, imageName: 'atomic-mask-bitmap', width: 20 },
+          fill: { color: '#e07575', style: 'diagonal' },
+          offset: { x: 15, y: 25 },
+        },
+      };
+      const document = {
+        ...pair,
+        layers: [mask, ...pair.layers, sentinelLayer()],
+        selectedLayerId: 'selection-sentinel',
+      };
+      const harness = createFaultHarness(document);
+      const maskCache = await snapshotLayerCache(harness.engine, mask.id);
+      const upperCache = await snapshotLayerCache(harness.engine, 'upper');
+      const belowCache = await snapshotLayerCache(harness.engine, 'below');
+      const expectedDocument = harness.engine.document.getDocument()!;
+      (harness.store.dispatch as Mock).mockClear();
+      harness.bitmapStore.markLayerDirty.mockClear();
+      armStructuralFault(harness.faults, failure, { allocation: 2, draw: 4 });
+
+      await expect(harness.engine.exports.extractMaskedArea(mask.id)).rejects.toThrow(structuralFaultMessage(failure));
+
+      expectInitialFailureExact(harness, expectedDocument);
+      await expectLayerCacheExact(harness.engine, mask.id, maskCache);
+      await expectLayerCacheExact(harness.engine, 'upper', upperCache);
+      await expectLayerCacheExact(harness.engine, 'below', belowCache);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  const createCropReplayHarness = async () => {
+    const source = rasterLayer('crop-replay-source');
+    const document: CanvasDocumentContractV2 = {
+      ...makeDoc(),
+      bbox: { height: 7, width: 6, x: 2, y: 3 },
+      layers: [source, sentinelLayer()],
+      selectedLayerId: 'selection-sentinel',
+    };
+    const harness = createFaultHarness(document);
+    await snapshotLayerCache(harness.engine, source.id);
+    await expect(harness.engine.layers.cropLayerToBbox(source.id)).resolves.toEqual({ status: 'cropped' });
+    return { ...harness, originalDocument: document, source };
+  };
+
+  it.each(structuralFaults)(
+    'crop undo cache-%s failure leaves the committed state exact and retryable',
+    async (failure) => {
+      const harness = await createCropReplayHarness();
+      const committedDocument = harness.engine.document.getDocument()!;
+      const committedCache = await snapshotLayerCache(harness.engine, harness.source.id);
+      armStructuralFault(harness.faults, failure, { allocation: 0, draw: 0 });
+
+      expect(() => harness.engine.history.undo()).toThrow(structuralFaultMessage(failure));
+
+      expect(harness.engine.document.getDocument()).toBe(committedDocument);
+      expect(harness.engine.document.getDocument()).toEqual(committedDocument);
+      expect(harness.engine.stores.canUndo.get()).toBe(true);
+      expect(harness.engine.stores.canRedo.get()).toBe(false);
+      await expectLayerCacheExact(harness.engine, harness.source.id, committedCache);
+      harness.engine.history.undo();
+      expect(harness.engine.document.getDocument()).toEqual(harness.originalDocument);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(structuralFaults)(
+    'crop redo cache-%s failure leaves the restored state exact and retryable',
+    async (failure) => {
+      const harness = await createCropReplayHarness();
+      const committedDocument = structuredClone(harness.engine.document.getDocument()!);
+      harness.engine.history.undo();
+      const restoredDocument = harness.engine.document.getDocument()!;
+      const restoredCache = await snapshotLayerCache(harness.engine, harness.source.id);
+      armStructuralFault(harness.faults, failure, { allocation: 0, draw: 0 });
+
+      expect(() => harness.engine.history.redo()).toThrow(structuralFaultMessage(failure));
+
+      expect(harness.engine.document.getDocument()).toBe(restoredDocument);
+      expect(harness.engine.document.getDocument()).toEqual(harness.originalDocument);
+      expect(harness.engine.stores.canUndo.get()).toBe(false);
+      expect(harness.engine.stores.canRedo.get()).toBe(true);
+      await expectLayerCacheExact(harness.engine, harness.source.id, restoredCache);
+      harness.engine.history.redo();
+      expect(harness.engine.document.getDocument()).toEqual(committedDocument);
+      harness.engine.lifecycle.dispose();
+    }
+  );
+
+  it('commitLayerCopy redo cache-draw failure leaves the restored state exact and retryable', async () => {
+    const source = rasterLayer('copy-replay-source');
+    const copy = { ...structuredClone(source), id: 'copy-replay-result', name: 'Copy replay result' };
+    const document = { ...makeDoc(), layers: [source, sentinelLayer()], selectedLayerId: 'selection-sentinel' };
+    const harness = createFaultHarness(document);
+    const originalCache = await snapshotLayerCache(harness.engine, source.id);
+    const originalDocument = harness.engine.document.getDocument()!;
+    expect(harness.engine.layers.commitLayerCopy('Copy layer', source.id, copy, 0)).toBe(true);
+    const committedDocument = structuredClone(harness.engine.document.getDocument()!);
+    harness.engine.history.undo();
+    const restoredDocument = harness.engine.document.getDocument()!;
+    harness.faults.armDraw(0);
+
+    expect(() => harness.engine.history.redo()).toThrow('structural cache draw failed');
+
+    expect(harness.engine.document.getDocument()).toBe(restoredDocument);
+    expect(harness.engine.document.getDocument()).toEqual(originalDocument);
+    expect(harness.engine.document.getDocument()!.layers.some((layer) => layer.id === copy.id)).toBe(false);
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(harness.engine.stores.canRedo.get()).toBe(true);
+    await expectLayerCacheExact(harness.engine, source.id, originalCache);
+    harness.engine.history.redo();
+    expect(harness.engine.document.getDocument()).toEqual(committedDocument);
+    expect(harness.engine.document.getDocument()!.layers.filter((layer) => layer.id === copy.id)).toHaveLength(1);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('commitLayerConversion keeps failed undo and redo cache preparation exact and retryable', async () => {
+    const source = rasterLayer('conversion-replay-source');
+    const document = { ...makeDoc(), layers: [source, sentinelLayer()], selectedLayerId: 'selection-sentinel' };
+    const harness = createFaultHarness(document);
+    await snapshotLayerCache(harness.engine, source.id);
+    const originalDocument = harness.engine.document.getDocument()!;
+    const live = originalDocument.layers.find((layer) => layer.id === source.id)!;
+    if (live.type !== 'raster') {
+      throw new Error('expected a raster conversion source');
+    }
+    const converted: CanvasLayerContract = {
+      ...structuredClone(live),
+      adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      type: 'control',
+      withTransparencyEffect: false,
+    };
+    expect(harness.engine.layers.commitLayerConversion('Convert layer', live, converted)).toBe(true);
+    const committedDocument = harness.engine.document.getDocument()!;
+    const committedCache = await snapshotLayerCache(harness.engine, source.id);
+    harness.faults.armDraw(0);
+
+    expect(() => harness.engine.history.undo()).toThrow('structural cache draw failed');
+
+    expect(harness.engine.document.getDocument()).toBe(committedDocument);
+    expect(harness.engine.stores.canUndo.get()).toBe(true);
+    expect(harness.engine.stores.canRedo.get()).toBe(false);
+    await expectLayerCacheExact(harness.engine, source.id, committedCache);
+    harness.engine.history.undo();
+    expect(harness.engine.document.getDocument()).toEqual(originalDocument);
+    const restoredDocument = harness.engine.document.getDocument()!;
+    const restoredCache = await snapshotLayerCache(harness.engine, source.id);
+    harness.faults.armAllocation(0);
+
+    expect(() => harness.engine.history.redo()).toThrow('structural cache allocation failed');
+
+    expect(harness.engine.document.getDocument()).toBe(restoredDocument);
+    expect(harness.engine.document.getDocument()).toEqual(originalDocument);
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(harness.engine.stores.canRedo.get()).toBe(true);
+    await expectLayerCacheExact(harness.engine, source.id, restoredCache);
+    harness.engine.history.redo();
+    expect(harness.engine.document.getDocument()).toEqual(committedDocument);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('boolean redo cache-draw failure leaves sources, selection, and history exact and retryable', async () => {
+    const pair = twoPaintDoc();
+    const document = {
+      ...pair,
+      layers: [...pair.layers, sentinelLayer()],
+      selectedLayerId: 'selection-sentinel',
+    };
+    const harness = createFaultHarness(document);
+    const upperCache = await snapshotLayerCache(harness.engine, 'upper');
+    const belowCache = await snapshotLayerCache(harness.engine, 'below');
+    const originalDocument = harness.engine.document.getDocument()!;
+    await expect(harness.engine.layers.booleanMergeRasterLayers('upper', 'exclude')).resolves.toBe('merged');
+    const committedDocument = structuredClone(harness.engine.document.getDocument()!);
+    const resultId = harness.engine.document.getDocument()!.selectedLayerId!;
+    harness.engine.history.undo();
+    const restoredDocument = harness.engine.document.getDocument()!;
+    harness.faults.armDraw(0);
+
+    expect(() => harness.engine.history.redo()).toThrow('structural cache draw failed');
+
+    expect(harness.engine.document.getDocument()).toBe(restoredDocument);
+    expect(harness.engine.document.getDocument()).toEqual(originalDocument);
+    expect(harness.engine.document.getDocument()!.layers.some((layer) => layer.id === resultId)).toBe(false);
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(harness.engine.stores.canRedo.get()).toBe(true);
+    await expectLayerCacheExact(harness.engine, 'upper', upperCache);
+    await expectLayerCacheExact(harness.engine, 'below', belowCache);
+    harness.engine.history.redo();
+    expect(harness.engine.document.getDocument()).toEqual(committedDocument);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('masked extraction redo cache-draw failure leaves sources, selection, and history exact and retryable', async () => {
+    const pair = twoPaintDoc();
+    const mask: CanvasInpaintMaskLayerContract = {
+      ...maskLayer('extract-replay-mask'),
+      mask: {
+        bitmap: { height: 20, imageName: 'extract-replay-mask-bitmap', width: 20 },
+        fill: { color: '#e07575', style: 'diagonal' },
+        offset: { x: 15, y: 25 },
+      },
+    };
+    const document = {
+      ...pair,
+      layers: [mask, ...pair.layers, sentinelLayer()],
+      selectedLayerId: 'selection-sentinel',
+    };
+    const harness = createFaultHarness(document);
+    const maskCache = await snapshotLayerCache(harness.engine, mask.id);
+    const upperCache = await snapshotLayerCache(harness.engine, 'upper');
+    const belowCache = await snapshotLayerCache(harness.engine, 'below');
+    const originalDocument = harness.engine.document.getDocument()!;
+    const extracted = await harness.engine.exports.extractMaskedArea(mask.id);
+    expect(extracted.status).toBe('extracted');
+    if (extracted.status !== 'extracted') {
+      throw new Error('expected masked extraction');
+    }
+    const committedDocument = structuredClone(harness.engine.document.getDocument()!);
+    harness.engine.history.undo();
+    const restoredDocument = harness.engine.document.getDocument()!;
+    harness.faults.armDraw(0);
+
+    expect(() => harness.engine.history.redo()).toThrow('structural cache draw failed');
+
+    expect(harness.engine.document.getDocument()).toBe(restoredDocument);
+    expect(harness.engine.document.getDocument()).toEqual(originalDocument);
+    expect(harness.engine.document.getDocument()!.layers.some((layer) => layer.id === extracted.layerId)).toBe(false);
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(harness.engine.stores.canRedo.get()).toBe(true);
+    await expectLayerCacheExact(harness.engine, mask.id, maskCache);
+    await expectLayerCacheExact(harness.engine, 'upper', upperCache);
+    await expectLayerCacheExact(harness.engine, 'below', belowCache);
+    harness.engine.history.redo();
+    expect(harness.engine.document.getDocument()).toEqual(committedDocument);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('copyLayerToRaster undo restores the exact prior selection', async () => {
+    const source = rasterLayer('selection-copy-source');
+    const document = { ...makeDoc(), layers: [source, sentinelLayer()], selectedLayerId: 'selection-sentinel' };
+    const harness = createFaultHarness(document);
+    const originalDocument = harness.engine.document.getDocument()!;
+    const copiedId = await harness.engine.layers.copyLayerToRaster(source.id);
+    expect(copiedId).not.toBeNull();
+
+    harness.engine.history.undo();
+
+    expect(harness.engine.document.getDocument()).toEqual(originalDocument);
+    expect(harness.engine.document.getDocument()!.selectedLayerId).toBe('selection-sentinel');
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(harness.engine.stores.canRedo.get()).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('keeps a reducer-rejected copy undo retryable until its prior selection exists again', async () => {
+    const source = rasterLayer('rejected-undo-source');
+    const sentinel = sentinelLayer();
+    const document = { ...makeDoc(), layers: [source, sentinel], selectedLayerId: sentinel.id };
+    const harness = createFaultHarness(document);
+    const copiedId = await harness.engine.layers.copyLayerToRaster(source.id);
+    expect(copiedId).not.toBeNull();
+
+    harness.store.dispatch({ ids: [sentinel.id], type: 'removeCanvasLayers' });
+    expect(harness.engine.document.getDocument()!.layers.some((layer) => layer.id === copiedId)).toBe(true);
+
+    expect(() => harness.engine.history.undo()).toThrow('Canvas document mutation was rejected');
+    expect(harness.engine.document.getDocument()!.layers.some((layer) => layer.id === copiedId)).toBe(true);
+    expect(harness.engine.stores.canUndo.get()).toBe(true);
+    expect(harness.engine.stores.canRedo.get()).toBe(false);
+
+    harness.store.dispatch({ layer: sentinel, type: 'addCanvasLayer' });
+    expect(() => harness.engine.history.undo()).not.toThrow();
+    expect(harness.engine.document.getDocument()!.layers.some((layer) => layer.id === copiedId)).toBe(false);
+    expect(harness.engine.document.getDocument()!.selectedLayerId).toBe(sentinel.id);
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(harness.engine.stores.canRedo.get()).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('publishes a prepared structural mutation to its bound project while another project is active', () => {
+    const source = rasterLayer('inactive-source');
+    const document = { ...makeDoc(), layers: [source], selectedLayerId: source.id };
+    const harness = createFaultHarness(document);
+    const liveSource = harness.engine.document.getDocument()!.layers[0]!;
+    const copy = { ...structuredClone(source), id: 'inactive-copy' };
+    harness.store.dispatch({ type: 'createProject' });
+    const otherProjectId = harness.store.getState().activeProjectId;
+    const otherBefore = structuredClone(
+      harness.store.getState().projects.find((project) => project.id === otherProjectId)!.canvas.document
+    );
+    (harness.store.dispatch as Mock).mockClear();
+
+    expect(harness.engine.layers.commitLayerCopy('Copy layer', liveSource.id, copy, 0)).toBe(true);
+
+    expect(harness.store.dispatch).toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'applyCanvasLayerStackMutation' })
+    );
+    expect(harness.store.getState().projects.find((project) => project.id === otherProjectId)!.canvas.document).toEqual(
+      otherBefore
+    );
+    expect(harness.engine.document.getDocument()?.layers[0]?.id).toBe(copy.id);
+    expect(harness.engine.stores.canUndo.get()).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('crop generation-cancels a deferred pre-crop upload before publishing the new paint incarnation', async () => {
+    const source: CanvasRasterLayerContractV2 = {
+      ...(rasterLayer('crop-persistence-source') as CanvasRasterLayerContractV2),
+      source: {
+        bitmap: { height: 10, imageName: 'before-crop-paint', width: 10 },
+        offset: { x: 0, y: 0 },
+        type: 'paint',
+      },
+    };
+    const document: CanvasDocumentContractV2 = {
+      ...makeDoc(),
+      bbox: { height: 7, width: 6, x: 2, y: 3 },
+      layers: [source, sentinelLayer()],
+      selectedLayerId: 'selection-sentinel',
+    };
+    const reducer = createReducerBackedStore(document);
+    const staleUpload = createDeferred<{ height: number; imageName: string; width: number }>();
+    let uploadCount = 0;
+    const uploadImage = vi.fn(() => {
+      uploadCount += 1;
+      return uploadCount === 1
+        ? staleUpload.promise
+        : Promise.resolve({ height: 7, imageName: 'cropped-paint', width: 6 });
+    });
+    let placed: { offset: { x: number; y: number }; surface: RasterSurface } | null = null;
+    const bitmapStore = createBitmapStore({
+      debounceMs: 1500,
+      dispatch: createTestMutationPort(reducer.store, reducer.projectId).dispatch,
+      encodeSurface: (surface) =>
+        Promise.resolve(new Blob([`${surface.width}x${surface.height}`], { type: 'image/png' })),
+      getLayerSource: (layerId) => {
+        const layer = reducer.store
+          .getState()
+          .projects.find((project) => project.id === reducer.projectId)
+          ?.canvas.document.layers.find((candidate) => candidate.id === layerId);
+        return layer?.type === 'raster' || layer?.type === 'control' ? layer.source : null;
+      },
+      getLayerSurface: () => placed,
+      hashBlob: (blob) => blob.text(),
+      maxUploadAttempts: 1,
+      retryDelaysMs: [],
+      sleep: () => Promise.resolve(),
+      uploadImage,
+    });
+    const discardLayer = vi.spyOn(bitmapStore, 'discardLayer');
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    const before = await snapshotLayerCache(engine, source.id);
+    placed = { offset: { x: before.rect.x, y: before.rect.y }, surface: before.surface };
+    bitmapStore.markLayerDirty(source.id);
+    const barrier = bitmapStore.flushPendingUploads();
+    for (let tick = 0; tick < 50 && uploadImage.mock.calls.length === 0; tick += 1) {
+      await Promise.resolve();
+    }
+    expect(uploadImage).toHaveBeenCalledOnce();
+
+    await expect(engine.layers.cropLayerToBbox(source.id)).resolves.toEqual({ status: 'cropped' });
+    const croppedCache = await snapshotLayerCache(engine, source.id);
+    placed = {
+      offset: { x: croppedCache.rect.x, y: croppedCache.rect.y },
+      surface: croppedCache.surface,
+    };
+    staleUpload.resolve({ height: 10, imageName: 'stale-pre-crop-paint', width: 10 });
+    await barrier;
+
+    const bitmapUpdates = (reducer.store.dispatch as Mock).mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .filter((action) => action.type === 'updateCanvasLayerSource' && action.id === source.id);
+    expect(discardLayer).toHaveBeenCalledWith(source.id);
+    expect(bitmapUpdates).toHaveLength(1);
+    expect(bitmapUpdates).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ source: { bitmap: expect.objectContaining({ imageName: 'stale-pre-crop-paint' }) } }),
+      ])
+    );
+    expect(bitmapUpdates[0]).toMatchObject({
+      source: {
+        bitmap: { height: 7, imageName: 'cropped-paint', width: 6 },
+        offset: { x: 2, y: 3 },
+        type: 'paint',
+      },
+    });
+    expect(engine.document.getDocument()!.selectedLayerId).toBe('selection-sentinel');
+    expect(engine.document.getDocument()!.layers.find((layer) => layer.id === source.id)).toMatchObject({
+      source: {
+        bitmap: { height: 7, imageName: 'cropped-paint', width: 6 },
+        offset: { x: 2, y: 3 },
+        type: 'paint',
+      },
+    });
+    expect(engine.stores.canUndo.get()).toBe(true);
+    await expectLayerCacheExact(engine, source.id, croppedCache);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('mergeVisibleRasterLayers', () => {
+  /** [upper raster, mask, lower raster] — the interleaved case round 1 no-oped. */
+  const interleavedDoc = (): CanvasDocumentContractV2 => {
+    const base = twoPaintDoc();
+    const [upper, below] = base.layers as [CanvasLayerContract, CanvasLayerContract];
+    return { ...base, layers: [upper, maskLayer('mid-mask'), below] };
+  };
+
+  const setup = (doc: CanvasDocumentContractV2) => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const { projectId, store } = createReducerBackedStore(doc);
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (width, height) => {
+        const surface = base.createSurface(width, height);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    return { engine, raf, store, surfaces };
+  };
+
+  it('waits for contributor rasterization before applying one atomic insertion', async () => {
+    const { engine, raf } = setup(interleavedDoc());
+    const pending = engine.layers.mergeVisibleRasterLayers();
+    expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual(['upper', 'mid-mask', 'below']);
+
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    expect(await pending).toBe('merged');
+    expect(
+      engine.document
+        .getDocument()!
+        .layers.slice(1)
+        .map((layer) => layer.id)
+    ).toEqual(['upper', 'mid-mask', 'below']);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('creates a selected raster at index zero and preserves every source layer', async () => {
+    const { engine, raf } = setup(interleavedDoc());
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('merged');
+
+    const layers = engine.document.getDocument()!.layers;
+    expect(layers).toHaveLength(4);
+    expect(layers[0]).toMatchObject({
+      blendMode: 'normal',
+      isEnabled: true,
+      isLocked: false,
+      name: 'upper merged',
+      opacity: 1,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    expect(layers.slice(1).map((layer) => layer.id)).toEqual(['upper', 'mid-mask', 'below']);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(layers[0]!.id);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('includes locked parametric rasters, excludes hidden rasters, and composites bottom-to-top', async () => {
+    const doc = twoPaintDoc();
+    const upper: CanvasRasterLayerContractV2 = {
+      ...(doc.layers[0] as CanvasRasterLayerContractV2),
+      isLocked: true,
+    };
+    const below: CanvasRasterLayerContractV2 = {
+      ...(doc.layers[1] as CanvasRasterLayerContractV2),
+      source: {
+        angle: 0,
+        height: 60,
+        kind: 'linear',
+        stops: [
+          { color: '#000000', offset: 0 },
+          { color: '#ffffff', offset: 1 },
+        ],
+        type: 'gradient',
+        width: 60,
+      },
+    };
+    const hidden: CanvasRasterLayerContractV2 = {
+      ...(doc.layers[1] as CanvasRasterLayerContractV2),
+      id: 'hidden',
+      isEnabled: false,
+      name: 'hidden',
+      source: { bitmap: { height: 500, imageName: 'hidden-bmp', width: 500 }, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: -1000, y: -1000 },
+    };
+    const sourceLayers = [upper, maskLayer('mid-mask'), hidden, below];
+    const { engine, raf, surfaces } = setup({ ...doc, layers: sourceLayers });
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('merged');
+    const merged = engine.document.getDocument()!.layers[0]!;
+    expect(merged).toMatchObject({ source: { offset: { x: 10, y: 20 }, type: 'paint' }, type: 'raster' });
+    expect(engine.document.getDocument()!.layers.slice(1)).toEqual(sourceLayers);
+
+    const composite = surfaces.find(
+      (surface) =>
+        surface.width === 60 &&
+        surface.height === 60 &&
+        surface.callLog.some(
+          (entry) => entry.op === 'set' && entry.args[0] === 'globalCompositeOperation' && entry.args[1] === 'multiply'
+        )
+    );
+    expect(composite).toBeDefined();
+    expect(
+      composite?.callLog
+        .filter((entry) => entry.op === 'drawImage')
+        .map((entry) => (entry.args[0] as { width: number }).width)
+    ).toEqual([60, 40]);
+    expect(
+      composite?.callLog
+        .filter((entry) => entry.op === 'set' && entry.args[0] === 'globalAlpha')
+        .map((entry) => entry.args[1])
+    ).toEqual([1, 0.5, 1]);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('creates another composite layer when invoked repeatedly', async () => {
+    const { engine, raf } = setup(interleavedDoc());
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('merged');
+    const firstId = engine.document.getDocument()!.layers[0]!.id;
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('merged');
+    const layers = engine.document.getDocument()!.layers;
+    expect(layers).toHaveLength(5);
+    expect(layers[0]!.id).not.toBe(firstId);
+    expect(layers[1]!.id).toBe(firstId);
+    expect(layers.slice(2).map((layer) => layer.id)).toEqual(['upper', 'mid-mask', 'below']);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('undoes and redoes only the generated layer', async () => {
+    const { engine, raf } = setup(interleavedDoc());
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    const before = engine.document.getDocument()!;
+
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('merged');
+    const merged = engine.document.getDocument()!.layers[0]!;
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers).toEqual(before.layers);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(before.selectedLayerId);
+
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(merged);
+    expect(engine.document.getDocument()!.layers.slice(1)).toEqual(before.layers);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(merged.id);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('blocks the group merge without closing an operation and restores it after cancel', async () => {
+    const { engine, raf } = setup(interleavedDoc());
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    const exported = await engine.exports.exportLayerPixels('upper');
+    if (exported.status !== 'ok') {
+      throw new Error('expected an operation guard');
+    }
+    const session = getCanvasOperations(engine).controller.start({
+      cleanupPreview: vi.fn(),
+      guard: exported.guard,
+      identity: { kind: 'filter', layerId: 'upper', projectId: engine.projectId },
+    });
+
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('busy');
+    expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual(['upper', 'mid-mask', 'below']);
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'filter' },
+      status: 'active',
+    });
+
+    session?.cancel();
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('merged');
+    engine.lifecycle.dispose();
+  });
+
+  it('returns nothing for empty raster layers and preserves them', async () => {
+    const base = twoPaintDoc();
+    const doc: CanvasDocumentContractV2 = {
+      ...base,
+      layers: base.layers.map((layer) => ({
+        ...layer,
+        source: { bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' as const },
+      })),
+    };
+    const { engine, raf } = setup(doc);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual(['upper', 'below']);
+    expect(await engine.layers.mergeVisibleRasterLayers()).toBe('nothing');
+    expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual(['upper', 'below']);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- rasterizeLayer: parametric → paint, undoable via param re-convert ----
+
+const shapeLayerDoc = (over: { isLocked?: boolean } = {}): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [
+    {
+      blendMode: 'normal',
+      id: 'shape1',
+      isEnabled: true,
+      isLocked: over.isLocked ?? false,
+      name: 'Shape',
+      opacity: 1,
+      source: { fill: '#ff0000', height: 40, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 60 },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 },
+      type: 'raster',
+    },
+  ],
+  selectedLayerId: 'shape1',
+  version: 2,
+  width: 100,
+});
+
+describe('rasterizeLayer (parametric → paint)', () => {
+  const setup = (doc: CanvasDocumentContractV2) => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const { setDocument, store } = createReactiveStore(doc);
+    const dispatch = store.dispatch as Mock;
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    return { backend, dispatch, engine, raf, setDocument, surfaces };
+  };
+
+  const convertCalls = (dispatch: Mock): EngineTestAction[] =>
+    dispatch.mock.calls.map((call) => call[0] as EngineTestAction).filter((a) => a.type === 'convertCanvasLayer');
+
+  it('bakes to a CONTENT-sized paint layer at identity and dispatches convertCanvasLayer with the offset', () => {
+    const { dispatch, engine, surfaces } = setup(shapeLayerDoc());
+    const before = surfaces.length;
+
+    expect(engine.layers.rasterizeLayer('shape1')).toBe(true);
+
+    const converts = convertCalls(dispatch);
+    expect(converts).toHaveLength(1);
+    const convert = converts[0];
+    expect(convert).toMatchObject({ id: 'shape1', targetType: 'raster', type: 'convertCanvasLayer' });
+    if (convert?.type === 'convertCanvasLayer') {
+      expect(convert.layer.type).toBe('raster');
+      if (convert.layer.type === 'raster') {
+        // Content-sized: the shape (60×40) at transform (10,20) bakes to a paint
+        // layer whose bitmap sits at offset (10,20); the transform resets to identity.
+        expect(convert.layer.source).toEqual({ bitmap: null, offset: { x: 10, y: 20 }, type: 'paint' });
+        expect(convert.layer.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+      }
+    }
+
+    // A fresh CONTENT-sized surface (the transformed shape bounds, 60×40) was
+    // allocated and the parametric cache baked into it.
+    const baked = surfaces[before];
+    expect(baked).toBeDefined();
+    expect(baked?.width).toBe(60);
+    expect(baked?.height).toBe(40);
+    expect(baked?.callLog.some((e) => e.op === 'drawImage')).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('undo re-converts to the ORIGINAL parametric source (no pixel snapshot)', () => {
+    const { dispatch, engine } = setup(shapeLayerDoc());
+    engine.layers.rasterizeLayer('shape1');
+
+    engine.history.undo();
+    const converts = convertCalls(dispatch);
+    // forward convert + undo convert.
+    expect(converts).toHaveLength(2);
+    const undoConvert = converts[1];
+    if (undoConvert?.type === 'convertCanvasLayer' && undoConvert.layer.type === 'raster') {
+      expect(undoConvert.layer.source).toEqual({
+        fill: '#ff0000',
+        height: 40,
+        kind: 'rect',
+        stroke: null,
+        strokeWidth: 0,
+        type: 'shape',
+        width: 60,
+      });
+      expect(undoConvert.layer.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 });
+    } else {
+      throw new Error('expected undo to re-convert to the shape source');
+    }
+
+    // Redo re-applies the paint conversion (bitmap:null at the baked offset).
+    engine.history.redo();
+    const afterRedo = convertCalls(dispatch);
+    expect(afterRedo).toHaveLength(3);
+    if (afterRedo[2]?.type === 'convertCanvasLayer' && afterRedo[2].layer.type === 'raster') {
+      expect(afterRedo[2].layer.source).toEqual({ bitmap: null, offset: { x: 10, y: 20 }, type: 'paint' });
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('redo re-bakes from params rather than pinning the doc-sized surface (byte-budget honesty)', () => {
+    // Regression: the history entry declared bytes:256 but captured the doc-sized
+    // `baked` surface in its redo closure, so repeated rasterizes could retain
+    // gigabytes invisible to HISTORY_BYTE_BUDGET. Redo must re-bake instead.
+    const { engine, surfaces } = setup(shapeLayerDoc());
+
+    expect(engine.layers.rasterizeLayer('shape1')).toBe(true);
+    const afterApply = surfaces.length;
+
+    engine.history.undo();
+    // Undo only re-converts (a dispatch) — it bakes nothing.
+    expect(surfaces.length).toBe(afterApply);
+
+    engine.history.redo();
+    // Redo allocates FRESH surfaces: it re-baked from params (content-sized to the
+    // transformed shape bounds, 60×40) rather than reusing a surface pinned by the
+    // entry.
+    expect(surfaces.length).toBeGreaterThan(afterApply);
+    const rebaked = surfaces.at(-1);
+    expect(rebaked?.width).toBe(60);
+    expect(rebaked?.height).toBe(40);
+    expect(rebaked?.callLog.some((e) => e.op === 'drawImage')).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('rasterizes a gradient layer', () => {
+    const doc = shapeLayerDoc();
+    doc.layers[0] = {
+      ...doc.layers[0],
+      source: { angle: 45, kind: 'linear', stops: [{ color: '#000', offset: 0 }], type: 'gradient' },
+    } as CanvasLayerContract;
+    const { dispatch, engine } = setup(doc);
+    expect(engine.layers.rasterizeLayer('shape1')).toBe(true);
+    expect(convertCalls(dispatch)).toHaveLength(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('is a no-op for a locked layer, a missing layer, and a non-parametric (paint) layer', () => {
+    const { dispatch, engine } = setup(shapeLayerDoc({ isLocked: true }));
+    expect(engine.layers.rasterizeLayer('shape1')).toBe(false);
+    expect(engine.layers.rasterizeLayer('nope')).toBe(false);
+    expect(convertCalls(dispatch)).toHaveLength(0);
+    engine.lifecycle.dispose();
+
+    const paintDoc = shapeLayerDoc();
+    paintDoc.layers[0] = { ...paintDoc.layers[0], source: { bitmap: null, type: 'paint' } } as CanvasLayerContract;
+    const paint = setup(paintDoc);
+    expect(paint.engine.layers.rasterizeLayer('shape1')).toBe(false);
+    paint.engine.lifecycle.dispose();
+  });
+
+  // ---- rasterize → undo → bitmap-store flush: source-type guard --------
+  //
+  // Reviewer-flagged bug: rasterize bakes the shape to a paint layer and marks
+  // it dirty in the bitmap store; undo re-converts it back to the parametric
+  // shape. Nothing previously cleared the pending dirty mark, so the eventual
+  // debounced (or barrier) flush would encode the paint-cache surface — still
+  // populated, since a source swap doesn't clear it — and dispatch
+  // `updateCanvasLayerSource({ type: 'paint', ... })`, silently flipping the
+  // parametric layer back to paint with stale, wrong-extent pixels.
+  //
+  // These tests wire a REAL `createBitmapStore` (exercising the actual guard
+  // in `flushLayer`) through `opts.bitmapStore`, with test-controlled
+  // encode/upload stubs (no real network) and a `getLayerSurface` that always
+  // resolves — mirroring the bug precondition that a source swap does NOT
+  // clear the cache. `getLayerSource` reads the engine's own mirrored
+  // document, so it reflects the exact reducer round trip the test drives via
+  // `setDocument`.
+  describe('rasterize → undo → bitmap-store flush (source-type guard)', () => {
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    const setupWithRealBitmapStore = (doc: CanvasDocumentContractV2) => {
+      const raf = createControllableRaf();
+      vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+      vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+      const { setDocument, store } = createReactiveStore(doc);
+      const dispatch = store.dispatch as Mock;
+
+      const encodeSurface = vi.fn(() => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })));
+      const uploadImage = vi.fn(() => Promise.resolve({ height: 100, imageName: 'img-x', width: 100 }));
+      // Always resolves, regardless of the layer's current source: mirrors the
+      // real cache, whose surface a source swap does NOT clear (only marks stale).
+      const fakeSurface = createTestStubRasterBackend().createSurface(10, 10);
+
+      // Forward-declared: `getLayerSource` closes over it, but is only ever
+      // CALLED once `engine` is assigned below (bitmap-store flushes never
+      // happen synchronously during construction).
+      let engine: ReturnType<typeof createCanvasEngine>;
+      const bitmapStore = createBitmapStore({
+        dispatch: createTestMutationPort(store, 'p1').dispatch,
+        encodeSurface,
+        getLayerSource: (layerId) => {
+          const layer = engine.document.getDocument()?.layers.find((candidate) => candidate.id === layerId);
+          return layer && (layer.type === 'raster' || layer.type === 'control') ? layer.source : null;
+        },
+        getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface: fakeSurface }),
+        hashBlob: (blob) => blob.text(),
+        retryDelaysMs: [1],
+        sleep: () => Promise.resolve(),
+        uploadImage,
+      });
+
+      engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      const screen = createFakeCanvas();
+      const overlay = createFakeCanvas();
+      engine.surface.attach(screen.element, overlay.element);
+      raf.flush();
+
+      return { dispatch, encodeSurface, engine, raf, setDocument, uploadImage };
+    };
+
+    /**
+     * Applies the most recently dispatched `convertCanvasLayer` action onto
+     * `doc`, simulating what the real reducer would do — `createReactiveStore`'s
+     * `dispatch` is a bare spy and does not mutate state on its own.
+     */
+    const applyLastConvert = (doc: CanvasDocumentContractV2, dispatch: Mock): CanvasDocumentContractV2 => {
+      const converts = convertCalls(dispatch);
+      const last = converts.at(-1);
+      if (last?.type !== 'convertCanvasLayer') {
+        throw new Error('expected a convertCanvasLayer dispatch');
+      }
+      return { ...doc, layers: doc.layers.map((layer) => (layer.id === last.id ? last.layer : layer)) };
+    };
+
+    /**
+     * Rasterizes `shape1` (paint bake, dirty-marks the bitmap store), applies
+     * that conversion to the mirrored document, then undoes it and applies
+     * THAT conversion too — the full reducer round trip a live document would
+     * go through. Leaves the document back at its original parametric shape
+     * source, with the paint-bake dirty mark for `shape1` still pending.
+     */
+    const rasterizeThenUndo = () => {
+      vi.useFakeTimers();
+      let doc = shapeLayerDoc();
+      const harness = setupWithRealBitmapStore(doc);
+      const { dispatch, engine, raf, setDocument } = harness;
+
+      expect(engine.layers.rasterizeLayer('shape1')).toBe(true);
+      doc = applyLastConvert(doc, dispatch);
+      setDocument(doc);
+      raf.flush();
+
+      engine.history.undo();
+      doc = applyLastConvert(doc, dispatch);
+      setDocument(doc);
+      raf.flush();
+
+      return harness;
+    };
+
+    /** Every dispatched `updateCanvasLayerSource` whose source is `paint`. */
+    const paintSourceDispatches = (dispatch: Mock): Extract<EngineTestAction, { type: 'updateCanvasLayerSource' }>[] =>
+      dispatch.mock.calls
+        .map((call) => call[0] as EngineTestAction)
+        .filter(
+          (action): action is Extract<EngineTestAction, { type: 'updateCanvasLayerSource' }> =>
+            action.type === 'updateCanvasLayerSource' && action.source.type === 'paint'
+        );
+
+    it('await flushPendingUploads(): the layer stays the parametric shape and no paint dispatch fires', async () => {
+      const { dispatch, engine, uploadImage } = rasterizeThenUndo();
+
+      await engine.lifecycle.flushPendingUploads();
+
+      // The guard drops the flush before it ever encodes/uploads.
+      expect(uploadImage).not.toHaveBeenCalled();
+      expect(paintSourceDispatches(dispatch)).toHaveLength(0);
+      const layer = engine.document.getDocument()!.layers[0] as CanvasRasterLayerContractV2;
+      expect(layer.source.type).toBe('shape');
+
+      engine.lifecycle.dispose();
+    });
+
+    it('advancing the debounce timer: the layer stays the parametric shape and no paint dispatch fires', async () => {
+      const { dispatch, engine, uploadImage } = rasterizeThenUndo();
+
+      await vi.advanceTimersByTimeAsync(1500);
+
+      expect(uploadImage).not.toHaveBeenCalled();
+      expect(paintSourceDispatches(dispatch)).toHaveLength(0);
+      const layer = engine.document.getDocument()!.layers[0] as CanvasRasterLayerContractV2;
+      expect(layer.source.type).toBe('shape');
+
+      engine.lifecycle.dispose();
+    });
+
+    it('redo after rasterize → flush → undo re-dispatches the paint image ref (fix round 2: no permanent bitmap:null)', async () => {
+      // Reviewer round 2, data-loss finding: rasterize → flush (contract lands
+      // on img-x, and the store's `lastApplied` remembers img-x) → undo (back
+      // to shape) → redo (convertCanvasLayer resets to `paint {bitmap: null}`)
+      // → a further flush re-bakes IDENTICAL pixels, so the content-hash dedupe
+      // resolves back to img-x — but the old `lastApplied`-based redundant-
+      // dispatch skip treated that as "already applied" and swallowed the
+      // dispatch, permanently stranding the document on `bitmap: null`. This
+      // drives the FULL sequence (including the first flush landing for real)
+      // and asserts the second flush actually re-dispatches the ref.
+      vi.useFakeTimers();
+      let doc = shapeLayerDoc();
+      const { dispatch, engine, raf, setDocument, uploadImage } = setupWithRealBitmapStore(doc);
+
+      // Rasterize → bake to paint → flush lands img-x.
+      expect(engine.layers.rasterizeLayer('shape1')).toBe(true);
+      doc = applyLastConvert(doc, dispatch);
+      setDocument(doc);
+      raf.flush();
+
+      await vi.advanceTimersByTimeAsync(1500);
+      await engine.lifecycle.flushPendingUploads();
+      expect(uploadImage).toHaveBeenCalledTimes(1);
+
+      const firstPersist = paintSourceDispatches(dispatch).at(-1);
+      expect(firstPersist).toBeDefined();
+      expect(firstPersist?.source).toMatchObject({ bitmap: { imageName: 'img-x' }, type: 'paint' });
+      // Apply the persisted ref onto the mirrored document, as the real reducer
+      // would — the document now genuinely points at img-x, not `bitmap: null`.
+      doc = {
+        ...doc,
+        layers: doc.layers.map((layer) =>
+          layer.id === firstPersist?.id ? { ...layer, source: firstPersist.source } : layer
+        ),
+      };
+      setDocument(doc);
+      raf.flush();
+
+      // Undo → back to the parametric shape source.
+      engine.history.undo();
+      doc = applyLastConvert(doc, dispatch);
+      setDocument(doc);
+      raf.flush();
+
+      // Redo → paint bake again; the fresh conversion lands on `bitmap: null`
+      // (only the debounced flush fills in the persisted ref).
+      engine.history.redo();
+      doc = applyLastConvert(doc, dispatch);
+      setDocument(doc);
+      raf.flush();
+      const layerAfterRedo = engine.document.getDocument()!.layers[0] as CanvasRasterLayerContractV2;
+      expect(layerAfterRedo.source).toEqual({ bitmap: null, offset: { x: 10, y: 20 }, type: 'paint' });
+
+      // Flush again: the re-baked pixels are identical, so the content hash
+      // dedupes back to img-x with NO new upload — but the ref must still be
+      // re-dispatched into the contract, since the document currently reads
+      // `bitmap: null`, not img-x.
+      await vi.advanceTimersByTimeAsync(1500);
+      await engine.lifecycle.flushPendingUploads();
+
+      expect(uploadImage).toHaveBeenCalledTimes(1); // dedupe hit: no re-upload
+      const dispatchesAfterRedo = paintSourceDispatches(dispatch);
+      const secondPersist = dispatchesAfterRedo.at(-1);
+      expect(secondPersist).toBeDefined();
+      expect(secondPersist).not.toBe(firstPersist);
+      expect(secondPersist?.source).toMatchObject({ bitmap: { imageName: 'img-x' }, type: 'paint' });
+
+      // Applying it restores the document's bitmap ref — no longer null.
+      doc = {
+        ...doc,
+        layers: doc.layers.map((layer) =>
+          layer.id === secondPersist?.id ? { ...layer, source: secondPersist.source } : layer
+        ),
+      };
+      setDocument(doc);
+      const layerFinal = engine.document.getDocument()!.layers[0] as CanvasRasterLayerContractV2;
+      expect(layerFinal.source.type).toBe('paint');
+      if (layerFinal.source.type === 'paint') {
+        expect(layerFinal.source.bitmap).not.toBeNull();
+        expect(layerFinal.source.bitmap?.imageName).toBe('img-x');
+      }
+
+      engine.lifecycle.dispose();
+    });
+
+    it('sanity check: a normal (non-reverted) rasterize DOES flush to paint (the guard only blocks the reverted case)', async () => {
+      vi.useFakeTimers();
+      let doc = shapeLayerDoc();
+      const { dispatch, engine, raf, setDocument, uploadImage } = setupWithRealBitmapStore(doc);
+
+      expect(engine.layers.rasterizeLayer('shape1')).toBe(true);
+      doc = applyLastConvert(doc, dispatch);
+      setDocument(doc);
+      raf.flush();
+
+      await vi.advanceTimersByTimeAsync(1500);
+      await engine.lifecycle.flushPendingUploads();
+
+      expect(uploadImage).toHaveBeenCalledTimes(1);
+      expect(paintSourceDispatches(dispatch)).toHaveLength(1);
+
+      engine.lifecycle.dispose();
+    });
+  });
+});
+
+// ---- nudgeSelectedLayer: bounds/lock logic + coalescing ----------------
+
+const selectedImageDoc = (
+  overrides: { isLocked?: boolean; isEnabled?: boolean } = {},
+  selectedLayerId: string | null = 'a'
+): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [{ ...rasterLayer('a'), ...overrides }],
+  selectedLayerId,
+  version: 2,
+  width: 100,
+});
+
+describe('nudgeSelectedLayer', () => {
+  const setup = (doc: CanvasDocumentContractV2) => {
+    const { store } = createFakeStore(doc);
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    return { dispatch, engine };
+  };
+
+  it('no-ops with no selection', () => {
+    const { dispatch, engine } = setup(selectedImageDoc({}, null));
+    engine.layers.nudgeSelectedLayer(1, 0);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('no-ops on a locked selected layer', () => {
+    const { dispatch, engine } = setup(selectedImageDoc({ isLocked: true }));
+    engine.layers.nudgeSelectedLayer(0, 1);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('no-ops on a hidden selected layer', () => {
+    const { dispatch, engine } = setup(selectedImageDoc({ isEnabled: false }));
+    engine.layers.nudgeSelectedLayer(0, 1);
+    expect(dispatch).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+
+  it('dispatches a transform update and records an undoable entry', () => {
+    const { dispatch, engine } = setup(selectedImageDoc());
+    engine.layers.nudgeSelectedLayer(3, -2);
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch).toHaveBeenNthCalledWith(1, {
+      id: 'a',
+      patch: { transform: { x: 3, y: -2 } },
+      type: 'updateCanvasLayer',
+    });
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    // Undo dispatches the inverse (back to the original position).
+    engine.history.undo();
+    expect(dispatch).toHaveBeenNthCalledWith(2, {
+      id: 'a',
+      patch: { transform: { x: 0, y: 0 } },
+      type: 'updateCanvasLayer',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('coalesces a rapid same-layer burst into one history entry', () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1_000);
+    const { engine } = setup(selectedImageDoc());
+    engine.layers.nudgeSelectedLayer(1, 0);
+    engine.layers.nudgeSelectedLayer(1, 0);
+    engine.layers.nudgeSelectedLayer(1, 0);
+    // A single undo empties the stack: the burst collapsed to one entry.
+    expect(engine.stores.canUndo.get()).toBe(true);
+    engine.history.undo();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+    vi.restoreAllMocks();
+  });
+
+  it('starts a fresh entry once the coalescing window elapses', () => {
+    const now = vi.spyOn(Date, 'now');
+    now.mockReturnValue(1_000);
+    const { engine } = setup(selectedImageDoc());
+    engine.layers.nudgeSelectedLayer(1, 0);
+    now.mockReturnValue(2_000); // > 500ms later
+    engine.layers.nudgeSelectedLayer(1, 0);
+    // Two distinct entries: one undo still leaves something to undo.
+    engine.history.undo();
+    expect(engine.stores.canUndo.get()).toBe(true);
+    engine.history.undo();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+    vi.restoreAllMocks();
+  });
+});
+
+// ---- move tool: drag gesture through the pointer pipeline ---------------
+
+describe('move tool: drag through the pipeline', () => {
+  it('commits one structural transform update and records an undoable entry', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    // A document-sized paint layer is hit-testable everywhere and pre-selected.
+    const { store } = createReactiveStore(paintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('move');
+
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(50, 30));
+    overlay.fire('pointerup', pointerAt(50, 30, { buttons: 0 }));
+
+    const transformUpdates = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .filter((action) => action.type === 'updateCanvasLayer');
+    expect(transformUpdates).toHaveLength(1);
+    expect(transformUpdates[0]).toMatchObject({ id: 'paint1', type: 'updateCanvasLayer' });
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('a click (no drag) dispatches a selection change and no transform update', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { store } = createReactiveStore(paintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('move');
+
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointerup', pointerAt(20, 20, { buttons: 0 }));
+
+    const actions = dispatch.mock.calls.map((call) => call[0] as EngineTestAction);
+    expect(actions.some((action) => action.type === 'updateCanvasLayer')).toBe(false);
+    expect(actions.some((action) => action.type === 'setCanvasSelectedLayer')).toBe(true);
+    expect(engine.stores.canUndo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- ride-along: composed auto-create + stroke history entry ------------
+
+const imageSelectedDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  // Selected layer is an image (not paintable) → a brush stroke auto-creates a
+  // fresh paint layer for the gesture.
+  layers: [rasterLayer('img')],
+  selectedLayerId: 'img',
+  version: 2,
+  width: 100,
+});
+
+describe('engine-owned history: composed auto-create + stroke entry', () => {
+  it('undo removes the auto-created layer (no pixel restore); redo re-adds it and re-applies the stroke', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(imageSelectedDoc());
+    const dispatch = store.dispatch as Mock;
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const strokes: StrokeCommittedEvent[] = [];
+    engine.tools.onStrokeCommitted((event) => strokes.push(event));
+
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+
+    // The gesture auto-created a paint layer and reported it on the commit event.
+    expect(strokes).toHaveLength(1);
+    const created = strokes[0]!.createdLayer;
+    expect(created).toBeDefined();
+    const newLayerId = created!.layer.id;
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    // The auto-create dispatched addCanvasLayer for the new id.
+    const addCalls = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .filter((action) => action.type === 'addCanvasLayer');
+    expect(addCalls).toHaveLength(1);
+
+    const putBefore = () => putImageDataCalls(surfaces).some((call) => call.image === strokes[0]!.beforeImageData);
+    const beforeUndoPutBefore = putBefore();
+
+    // Undo: removes the auto-created layer, and does NOT restore pre-stroke pixels
+    // (the layer's cache is gone).
+    engine.history.undo();
+    const removeAfterUndo = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .filter((action) => action.type === 'removeCanvasLayers');
+    expect(removeAfterUndo).toHaveLength(1);
+    expect(removeAfterUndo[0]).toEqual({ ids: [newLayerId], type: 'removeCanvasLayers' });
+    // No new before-pixel putImageData was introduced by the undo.
+    expect(putBefore()).toBe(beforeUndoPutBefore);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    // Redo: re-adds the layer and re-applies the stroke's after pixels.
+    engine.history.redo();
+    const addAfterRedo = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .filter((action) => action.type === 'addCanvasLayer');
+    expect(addAfterRedo).toHaveLength(2); // original auto-create + redo re-add
+    expect(putImageDataCalls(surfaces).some((call) => call.image === strokes[0]!.afterImageData)).toBe(true);
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('setStagedPreview', () => {
+  const emptyDoc = (bbox = { height: 100, width: 100, x: 0, y: 0 }): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox,
+    height: 100,
+    layers: [],
+    selectedLayerId: null,
+    version: 2,
+    width: 100,
+  });
+
+  /** A stub backend whose `createImageBitmap` is deferred, so decodes resolve on demand. */
+  const createDeferredBitmapBackend = () => {
+    const base = createTestStubRasterBackend();
+    const deferreds: ReturnType<typeof createDeferred<ImageBitmap>>[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createImageBitmap: () => {
+        const deferred = createDeferred<ImageBitmap>();
+        deferreds.push(deferred);
+        return deferred.promise;
+      },
+    };
+    return {
+      backend,
+      deferreds,
+      resolveBitmap: (index: number, width = 0, height = 0): void =>
+        deferreds[index]!.resolve({ close: () => {}, height, width } as unknown as ImageBitmap),
+    };
+  };
+
+  /** Screen-surface staged-preview draws are the 5-arg `drawImage(canvas, x, y, w, h)` calls. */
+  const stagedDraws = (surface: StubRasterSurface): unknown[][] =>
+    surface.callLog.filter((entry) => entry.op === 'drawImage' && entry.args.length === 5).map((entry) => entry.args);
+
+  const dataUrl = (tag: string) => `data:image/png;base64,${tag}`;
+
+  it('draws the newest decode and discards a stale one that resolves later (version race)', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const bitmaps = createDeferredBitmapBackend();
+    const { store } = createReactiveStore(emptyDoc());
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush(); // initial (no layers, no preview)
+    screen.surface.callLog.length = 0;
+
+    // Two rapid selections; the second supersedes the first.
+    engine.previews.setStagedPreview({ dataUrl: dataUrl('AAAA'), height: 10, width: 10 }); // decode #0
+    engine.previews.setStagedPreview({ dataUrl: dataUrl('BBBB'), height: 20, width: 20 }); // decode #1
+
+    // The newer decode resolves first and is drawn; a frame must have been scheduled.
+    bitmaps.resolveBitmap(1);
+    await flushMicrotasks();
+    expect(raf.pendingCount()).toBeGreaterThan(0);
+    raf.flush();
+
+    // The stale (older) decode resolves afterwards and must be dropped.
+    bitmaps.resolveBitmap(0);
+    await flushMicrotasks();
+    raf.flush();
+
+    const draws = stagedDraws(screen.surface);
+    expect(draws.length).toBeGreaterThan(0);
+    // Every staged draw is the 20x20 candidate at the bbox origin; the 10x10
+    // stale decode never reaches the screen.
+    for (const args of draws) {
+      expect(args.slice(1)).toEqual([0, 0, 20, 20]);
+    }
+
+    engine.lifecycle.dispose();
+  });
+
+  it('clears the preview on null', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const bitmaps = createDeferredBitmapBackend();
+    const { store } = createReactiveStore(emptyDoc());
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    engine.surface.attach(screen.element, createFakeCanvas().element);
+
+    engine.previews.setStagedPreview({ dataUrl: dataUrl('AAAA'), height: 10, width: 10 });
+    bitmaps.resolveBitmap(0);
+    await flushMicrotasks();
+    raf.flush();
+    expect(stagedDraws(screen.surface).length).toBeGreaterThan(0);
+
+    screen.surface.callLog.length = 0;
+    engine.previews.setStagedPreview(null);
+    raf.flush();
+    expect(stagedDraws(screen.surface)).toHaveLength(0);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('follows the current bbox origin, not the bbox at set time', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const bitmaps = createDeferredBitmapBackend();
+    const { setDocument, store } = createReactiveStore(emptyDoc({ height: 100, width: 100, x: 0, y: 0 }));
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    engine.surface.attach(screen.element, createFakeCanvas().element);
+
+    engine.previews.setStagedPreview({ dataUrl: dataUrl('AAAA'), height: 10, width: 10 });
+    bitmaps.resolveBitmap(0);
+    await flushMicrotasks();
+    raf.flush();
+    expect(stagedDraws(screen.surface).at(-1)!.slice(1)).toEqual([0, 0, 10, 10]);
+
+    // Move the bbox (an ordinary edit, same document revision — not a replacement).
+    screen.surface.callLog.length = 0;
+    setDocument(emptyDoc({ height: 10, width: 10, x: 30, y: 40 }));
+    raf.flush();
+    expect(stagedDraws(screen.surface).at(-1)!.slice(1)).toEqual([30, 40, 10, 10]);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('decodes an imageName candidate through the resolver and draws it at the bbox', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { store } = createReactiveStore(emptyDoc({ height: 100, width: 100, x: 5, y: 7 }));
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    engine.surface.attach(screen.element, createFakeCanvas().element);
+
+    engine.previews.setStagedPreview({ imageName: 'staged-candidate' });
+    await flushMicrotasks();
+    raf.flush();
+
+    expect(resolver).toHaveBeenCalledWith('staged-candidate');
+    // The decoded (stub, 0-sized) surface is drawn at the current bbox origin.
+    expect(stagedDraws(screen.surface).at(-1)!.slice(1, 3)).toEqual([5, 7]);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('stores an image candidate placement and renders it independently of the current bbox', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const base = createTestStubRasterBackend();
+    const backend: StubRasterBackend = {
+      ...base,
+      createImageBitmap: () => Promise.resolve({ close: vi.fn(), height: 17, width: 23 } as unknown as ImageBitmap),
+    };
+    const { setDocument, store } = createReactiveStore(emptyDoc({ height: 100, width: 100, x: 50, y: 60 }));
+    const engine = createCanvasEngine({
+      backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    engine.surface.attach(screen.element, createFakeCanvas().element);
+
+    engine.previews.setStagedPreview({
+      imageName: 'placed-candidate',
+      placement: { height: 34, opacity: 0.4, width: 46, x: -8, y: 13 },
+    });
+    await flushMicrotasks();
+    raf.flush();
+
+    expect(stagedDraws(screen.surface).at(-1)!.slice(1)).toEqual([-8, 13, 46, 34]);
+    const alphaSets = screen.surface.callLog
+      .filter((entry) => entry.op === 'set' && entry.args[0] === 'globalAlpha')
+      .map((entry) => entry.args[1]);
+    expect(alphaSets).toContain(0.4);
+
+    // A placed candidate no longer follows the bbox, so moving the bbox only
+    // invalidates overlay chrome and must not recomposite every canvas layer.
+    screen.surface.callLog.length = 0;
+    setDocument(emptyDoc({ height: 50, width: 50, x: 2, y: 3 }));
+    raf.flush();
+    expect(stagedDraws(screen.surface)).toHaveLength(0);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('commitRasterFilterResult', () => {
+  const durableImage = { height: 10, imageName: 'filtered-result', width: 10 };
+
+  const createReplayFaultBackend = () => {
+    const base = createTestStubRasterBackend();
+    let fault: 'allocation' | 'draw' | null = null;
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (width, height) => {
+        if (fault === 'allocation') {
+          fault = null;
+          throw new Error('replay cache allocation failed');
+        }
+        const surface = base.createSurface(width, height);
+        const ctx = new Proxy(surface.ctx, {
+          get: (target, property, receiver) => {
+            const value = Reflect.get(target, property, receiver);
+            if (property !== 'drawImage' || typeof value !== 'function') {
+              return value;
+            }
+            return (...args: unknown[]) => {
+              if (fault === 'draw') {
+                fault = null;
+                throw new Error('replay cache draw failed');
+              }
+              return Reflect.apply(value, target, args);
+            };
+          },
+        });
+        Object.defineProperty(surface, 'ctx', { value: ctx });
+        return surface;
+      },
+    };
+    return {
+      arm: (next: 'allocation' | 'draw') => {
+        fault = next;
+      },
+      backend,
+    };
+  };
+
+  const filterLayer = (id = 'L'): CanvasRasterLayerContractV2 => ({
+    adjustments: { brightness: 0.2, contrast: -0.1, saturation: 0.3 },
+    blendMode: 'multiply',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name: id,
+    opacity: 0.6,
+    source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+    transform: { rotation: 15, scaleX: 2, scaleY: 3, x: 5, y: 6 },
+    type: 'raster',
+  });
+
+  const filterDoc = (layers: CanvasLayerContract[] = [filterLayer()]): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers,
+    selectedLayerId: layers[0]?.id ?? null,
+    version: 2,
+    width: 100,
+  });
+
+  it('replaces with local paint pixels, clears adjustments, and restores exact state with one history entry', async () => {
+    const layer = filterLayer();
+    const { projectId, store } = createReducerBackedStore(filterDoc([layer]));
+    const backend = createRecordingRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(recordingBitmap('filtered')));
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const before = structuredClone(engine.document.getDocument()!.layers[0]!);
+    const exported = await engine.exports.exportLayerPixels(layer.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+    const result = await engine.layers.commitRasterFilterResult({
+      guard: exported.guard,
+      image: durableImage,
+      mode: 'replace',
+      rect: { height: 10, width: 10, x: -4, y: 7 },
+    });
+
+    expect(result).toEqual({ layerId: layer.id, status: 'committed' });
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    const after = engine.document.getDocument()!.layers[0]!;
+    const { adjustments: _adjustments, ...beforeWithoutAdjustments } = before as CanvasRasterLayerContractV2;
+    expect(after).toEqual({
+      ...beforeWithoutAdjustments,
+      source: { bitmap: durableImage, offset: { x: -4, y: 7 }, type: 'paint' },
+    });
+    expect(after.transform).toEqual(layer.transform);
+    expect('adjustments' in after).toBe(false);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    const forwardExport = await engine.exports.exportLayerPixels(layer.id);
+    expect(forwardExport.status).toBe('ok');
+    if (forwardExport.status !== 'ok') {
+      throw new Error('expected committed pixels');
+    }
+    const forwardSources = backend.drawSourcesFor(forwardExport.surface as StubRasterSurface);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(before);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    const undoExport = await engine.exports.exportLayerPixels(layer.id);
+    expect(undoExport.status).toBe('ok');
+    if (undoExport.status === 'ok') {
+      const undoSources = backend.drawSourcesFor(undoExport.surface as StubRasterSurface);
+      const beforeSnapshot = backend.surfaceById(undoSources.at(-1)!);
+      expect(beforeSnapshot).toBeDefined();
+      expect(backend.drawSourcesFor(beforeSnapshot!)).toContain(
+        backend.surfaceId(exported.surface as StubRasterSurface)
+      );
+    }
+
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(after);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    const redoExport = await engine.exports.exportLayerPixels(layer.id);
+    expect(redoExport.status).toBe('ok');
+    if (redoExport.status === 'ok') {
+      expect(backend.drawSourcesFor(redoExport.surface as StubRasterSurface)).toEqual(forwardSources);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('copies filtered local pixels directly above the source and replays one structural history entry', async () => {
+    const source = filterLayer('source');
+    const below = filterLayer('below');
+    const { projectId, store } = createReducerBackedStore({
+      ...filterDoc([source, below]),
+      selectedLayerId: below.id,
+    });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const sourceBefore = structuredClone(source);
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+
+    const result = await engine.layers.commitRasterFilterResult({
+      guard: exported.guard,
+      image: durableImage,
+      mode: 'copy',
+      rect: { height: 10, width: 10, x: 3, y: 4 },
+    });
+
+    expect(result.status).toBe('committed');
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed copy');
+    }
+    expect(engine.document.getDocument()!.layers.map((candidate) => candidate.id)).toEqual([
+      result.layerId,
+      'source',
+      'below',
+    ]);
+    expect(engine.document.getDocument()!.layers.find((candidate) => candidate.id === 'source')).toEqual(sourceBefore);
+    const copy = engine.document.getDocument()!.layers[0]!;
+    expect(copy).toMatchObject({
+      blendMode: source.blendMode,
+      isEnabled: source.isEnabled,
+      isLocked: false,
+      opacity: source.opacity,
+      source: { bitmap: durableImage, offset: { x: 3, y: 4 }, type: 'paint' },
+      transform: source.transform,
+      type: 'raster',
+    });
+    expect('adjustments' in copy).toBe(false);
+    expect((await engine.exports.exportLayerPixels(result.layerId)).status).toBe('ok');
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.map((candidate) => candidate.id)).toEqual(['source', 'below']);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(below.id);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers.map((candidate) => candidate.id)).toEqual([
+      result.layerId,
+      'source',
+      'below',
+    ]);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+    expect(engine.document.getDocument()!.layers[0]).toEqual(copy);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('atomically applies a filter and nonzero local origin to a control layer with exact undo/redo', async () => {
+    const source: CanvasLayerContract = {
+      adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      blendMode: 'normal',
+      filter: { settings: { radius: 1 }, type: 'old_filter' },
+      id: 'control',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Control',
+      opacity: 1,
+      source: { image: { height: 10, imageName: 'control-source', width: 10 }, type: 'image' },
+      transform: { rotation: 12, scaleX: 2, scaleY: 3, x: 40, y: 50 },
+      type: 'control',
+      withTransparencyEffect: true,
+    };
+    const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const before = structuredClone(source);
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable control export');
+    }
+
+    const result = await engine.layers.commitRasterFilterResult({
+      filter: { settings: { radius: 8 }, type: 'content_shuffle' },
+      guard: exported.guard,
+      image: durableImage,
+      mode: 'replace',
+      rect: { height: 10, width: 10, x: 7, y: -3 },
+      target: 'apply',
+    });
+
+    expect(result).toEqual({ layerId: source.id, status: 'committed' });
+    const after = engine.document.getDocument()!.layers[0]!;
+    expect(after).toMatchObject({
+      filter: { settings: { radius: 8 }, type: 'content_shuffle' },
+      source: { bitmap: durableImage, offset: { x: 7, y: -3 }, type: 'paint' },
+      transform: source.transform,
+      type: 'control',
+    });
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(before);
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(after);
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['raster', 'control'] as const)(
+    'saves a filtered result as a %s layer above a control source',
+    async (target) => {
+      const source: CanvasLayerContract = {
+        adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+        blendMode: 'normal',
+        id: 'control',
+        isEnabled: true,
+        isLocked: false,
+        name: 'Control',
+        opacity: 1,
+        source: { image: { height: 10, imageName: 'control-source', width: 10 }, type: 'image' },
+        transform: { rotation: 12, scaleX: 2, scaleY: 3, x: 40, y: 50 },
+        type: 'control',
+        withTransparencyEffect: true,
+      };
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable control export');
+      }
+
+      const result = await engine.layers.commitRasterFilterResult({
+        filter: { settings: {}, type: 'canny_edge_detection' },
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'copy',
+        rect: { height: 10, width: 10, x: 7, y: -3 },
+        target,
+      });
+
+      expect(result.status).toBe('committed');
+      expect(engine.document.getDocument()!.layers.map((layer) => layer.type)).toEqual([target, 'control']);
+      expect(engine.document.getDocument()!.layers[0]).toMatchObject({
+        filter: { settings: {}, type: 'canny_edge_detection' },
+        source: { offset: { x: 7, y: -3 }, type: 'paint' },
+        transform: source.transform,
+      });
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('preserves raster source placement when saving the filtered result as control', async () => {
+    const source = filterLayer('source');
+    const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable raster export');
+    }
+
+    const result = await engine.layers.commitRasterFilterResult({
+      filter: { settings: {}, type: 'canny_edge_detection' },
+      guard: exported.guard,
+      image: durableImage,
+      mode: 'copy',
+      rect: { height: 10, width: 10, x: -4, y: 7 },
+      target: 'control',
+    });
+
+    expect(result.status).toBe('committed');
+    expect(engine.document.getDocument()!.layers[0]).toMatchObject({
+      source: { offset: { x: -4, y: 7 }, type: 'paint' },
+      transform: source.transform,
+      type: 'control',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it.each([
+    { base: 'z-image', expectedKind: 'z_image_control' },
+    { base: 'sd-1', expectedKind: 'controlnet' },
+    { base: 'flux', expectedKind: 'controlnet' },
+  ] as const)(
+    'uses $expectedKind defaults when Save Filter As Control runs under $base',
+    async ({ base, expectedKind }) => {
+      const source = filterLayer('source');
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]), base);
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable raster export');
+      }
+
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'copy',
+        rect: exported.rect,
+        target: 'control',
+      });
+
+      expect(result.status).toBe('committed');
+      const created = engine.document.getDocument()!.layers[0];
+      expect(created?.type === 'control' ? created.adapter.kind : null).toBe(expectedKind);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['allocation', 'draw'] as const)(
+    'keeps replace undo retryable and exact when detached cache %s fails',
+    async (failure) => {
+      const source = filterLayer('source');
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+      const faults = createReplayFaultBackend();
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend: faults.backend,
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'replace',
+        rect: exported.rect,
+      });
+      expect(result.status).toBe('committed');
+      const expectedDocument = structuredClone(engine.document.getDocument()!);
+      const expectedCache = await engine.exports.exportLayerPixels(source.id);
+      if (expectedCache.status !== 'ok') {
+        throw new Error('expected committed cache pixels');
+      }
+      const expectedCalls = structuredClone((expectedCache.surface as StubRasterSurface).callLog);
+      const adjustedDeletesBefore = adjustedSurfaceCacheDeletes.length;
+      const thumbnailListener = vi.fn();
+      const unsubscribeThumbnail = engine.stores.thumbnailVersion.subscribe(thumbnailListener);
+      bitmapStore.markLayerDirty.mockClear();
+      (store.dispatch as Mock).mockClear();
+      faults.arm(failure);
+
+      expect(() => engine.history.undo()).toThrow(`replay cache ${failure} failed`);
+
+      expect(engine.document.getDocument()).toEqual(expectedDocument);
+      expect(engine.stores.canUndo.get()).toBe(true);
+      expect(engine.stores.canRedo.get()).toBe(false);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(thumbnailListener).not.toHaveBeenCalled();
+      expect(adjustedSurfaceCacheDeletes).toHaveLength(adjustedDeletesBefore);
+      const afterFailure = await engine.exports.exportLayerPixels(source.id);
+      expect(afterFailure.status).toBe('ok');
+      if (afterFailure.status === 'ok') {
+        expect(afterFailure.surface).toBe(expectedCache.surface);
+        expect(afterFailure.rect).toEqual(expectedCache.rect);
+        expect(afterFailure.guard.cacheVersion).toBe(expectedCache.guard.cacheVersion);
+        expect((afterFailure.surface as StubRasterSurface).callLog).toEqual(expectedCalls);
+      }
+
+      engine.history.undo();
+      expect(engine.document.getDocument()!.layers[0]).toEqual(source);
+      expect(engine.stores.canUndo.get()).toBe(false);
+      expect(engine.stores.canRedo.get()).toBe(true);
+      unsubscribeThumbnail();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['allocation', 'draw'] as const)(
+    'keeps replace redo retryable and exact when detached cache %s fails',
+    async (failure) => {
+      const source = filterLayer('source');
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+      const faults = createReplayFaultBackend();
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend: faults.backend,
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'replace',
+        rect: exported.rect,
+      });
+      expect(result.status).toBe('committed');
+      const filteredDocument = structuredClone(engine.document.getDocument()!);
+      engine.history.undo();
+      const expectedDocument = structuredClone(engine.document.getDocument()!);
+      const expectedCache = await engine.exports.exportLayerPixels(source.id);
+      if (expectedCache.status !== 'ok') {
+        throw new Error('expected restored source pixels');
+      }
+      const expectedCalls = structuredClone((expectedCache.surface as StubRasterSurface).callLog);
+      const adjustedDeletesBefore = adjustedSurfaceCacheDeletes.length;
+      const thumbnailListener = vi.fn();
+      const unsubscribeThumbnail = engine.stores.thumbnailVersion.subscribe(thumbnailListener);
+      bitmapStore.markLayerDirty.mockClear();
+      (store.dispatch as Mock).mockClear();
+      faults.arm(failure);
+
+      expect(() => engine.history.redo()).toThrow(`replay cache ${failure} failed`);
+
+      expect(engine.document.getDocument()).toEqual(expectedDocument);
+      expect(engine.stores.canUndo.get()).toBe(false);
+      expect(engine.stores.canRedo.get()).toBe(true);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(thumbnailListener).not.toHaveBeenCalled();
+      expect(adjustedSurfaceCacheDeletes).toHaveLength(adjustedDeletesBefore);
+      const afterFailure = await engine.exports.exportLayerPixels(source.id);
+      expect(afterFailure.status).toBe('ok');
+      if (afterFailure.status === 'ok') {
+        expect(afterFailure.surface).toBe(expectedCache.surface);
+        expect(afterFailure.rect).toEqual(expectedCache.rect);
+        expect(afterFailure.guard.cacheVersion).toBe(expectedCache.guard.cacheVersion);
+        expect((afterFailure.surface as StubRasterSurface).callLog).toEqual(expectedCalls);
+      }
+
+      engine.history.redo();
+      expect(engine.document.getDocument()).toEqual(filteredDocument);
+      expect(engine.stores.canUndo.get()).toBe(true);
+      expect(engine.stores.canRedo.get()).toBe(false);
+      unsubscribeThumbnail();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('discards obsolete persistence and keeps the exact durable image ref on replace redo', async () => {
+    const source = filterLayer('source');
+    const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+
+    await expect(
+      engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'replace',
+        rect: exported.rect,
+      })
+    ).resolves.toEqual({ layerId: source.id, status: 'committed' });
+    expect(bitmapStore.discardLayer).toHaveBeenCalledTimes(1);
+
+    engine.history.undo();
+    bitmapStore.markLayerDirty.mockClear();
+    engine.history.redo();
+
+    expect(bitmapStore.discardLayer).toHaveBeenCalledTimes(2);
+    expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    const redone = engine.document.getDocument()!.layers[0];
+    expect(redone).toMatchObject({ source: { bitmap: durableImage, type: 'paint' } });
+    if (redone?.type === 'raster' && redone.source.type === 'paint') {
+      expect(redone.source.bitmap).toEqual(durableImage);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  describe('paint persistence cancellation', () => {
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    const drainUntil = async (predicate: () => boolean, maxTicks = 50): Promise<void> => {
+      for (let i = 0; i < maxTicks && !predicate(); i += 1) {
+        await Promise.resolve();
+      }
+    };
+
+    const createRealBitmapStoreHarness = async (
+      uploadImage: (blob: Blob) => Promise<{ height: number; imageName: string; width: number }>
+    ) => {
+      vi.stubGlobal('Path2D', class FakePath2D {});
+      const source: CanvasRasterLayerContractV2 = {
+        ...filterLayer('source'),
+        source: {
+          bitmap: { height: 10, imageName: 'before-paint', width: 10 },
+          offset: { x: 0, y: 0 },
+          type: 'paint',
+        },
+      };
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+      const backend = {
+        ...createRecordingRasterBackend(),
+        encodeSurface: vi.fn(() => Promise.resolve(new Blob(['paint-pixels'], { type: 'image/png' }))),
+      };
+      let bitmapCall = 0;
+      backend.createImageBitmap = vi.fn(() =>
+        Promise.resolve(recordingBitmap(bitmapCall++ === 0 ? 'before-paint' : 'filtered-result'))
+      );
+      let placed: { offset: { x: number; y: number }; surface: RasterSurface } | null = null;
+      const bitmapStore = createBitmapStore({
+        debounceMs: 1500,
+        dispatch: createTestMutationPort(store, projectId).dispatch,
+        encodeSurface: () => Promise.resolve(new Blob(['unpersisted-paint'], { type: 'image/png' })),
+        getLayerSource: (layerId) => {
+          const layer = store
+            .getState()
+            .projects.find((project) => project.id === projectId)
+            ?.canvas.document.layers.find((candidate) => candidate.id === layerId);
+          return layer?.type === 'raster' || layer?.type === 'control' ? layer.source : null;
+        },
+        getLayerSurface: () => placed,
+        hashBlob: (blob) => blob.text(),
+        maxUploadAttempts: 1,
+        retryDelaysMs: [],
+        sleep: () => Promise.resolve(),
+        uploadImage,
+      });
+      const discardLayer = vi.spyOn(bitmapStore, 'discardLayer');
+      const engine = createCanvasEngine({
+        backend,
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const initial = await engine.exports.exportLayerPixels(source.id);
+      if (initial.status !== 'ok') {
+        throw new Error('expected persisted paint pixels');
+      }
+      engine.selection.selectAll();
+      engine.selection.fillSelection();
+      const refreshPlacement = async (layerId = source.id) => {
+        const exported = await engine.exports.exportLayerPixels(layerId);
+        if (exported.status !== 'ok') {
+          throw new Error('expected live paint pixels');
+        }
+        placed = {
+          offset: { x: exported.rect.x, y: exported.rect.y },
+          surface: exported.surface,
+        };
+        return exported;
+      };
+      const exported = await refreshPlacement();
+      return { backend, bitmapStore, discardLayer, engine, exported, projectId, refreshPlacement, source, store };
+    };
+
+    const bitmapUpdateActions = (store: ReturnType<typeof createReducerBackedStore>['store']) =>
+      (store.dispatch as Mock).mock.calls
+        .map((call) => call[0] as EngineTestAction)
+        .filter((action) => action.type === 'updateCanvasLayerSource' && action.id === 'source');
+
+    it('cancels pending debounced live-paint persistence before durable replace publication', async () => {
+      vi.useFakeTimers();
+      const uploadImage = vi.fn(() => Promise.resolve({ height: 10, imageName: 'stale-pending-paint', width: 10 }));
+      const harness = await createRealBitmapStoreHarness(uploadImage);
+
+      await expect(
+        harness.engine.layers.commitRasterFilterResult({
+          guard: harness.exported.guard,
+          image: durableImage,
+          mode: 'replace',
+          rect: harness.exported.rect,
+        })
+      ).resolves.toEqual({ layerId: harness.source.id, status: 'committed' });
+      const committed = structuredClone(harness.engine.document.getDocument()!);
+
+      await vi.advanceTimersByTimeAsync(1500);
+      await harness.bitmapStore.flushPendingUploads();
+
+      expect(harness.discardLayer).toHaveBeenCalledWith(harness.source.id);
+      expect(uploadImage).not.toHaveBeenCalled();
+      expect(bitmapUpdateActions(harness.store)).toHaveLength(0);
+      expect(harness.engine.document.getDocument()).toEqual(committed);
+      expect(harness.engine.document.getDocument()!.layers[0]).toMatchObject({
+        source: { bitmap: durableImage, type: 'paint' },
+      });
+      const cache = await harness.engine.exports.exportLayerPixels(harness.source.id);
+      expect(cache.status).toBe('ok');
+      if (cache.status === 'ok') {
+        expect(drawGraphContains(cache.surface as StubRasterSurface, harness.backend, 'bitmap-filtered-result')).toBe(
+          true
+        );
+      }
+
+      const reloadDocument = structuredClone(harness.engine.document.getDocument()!);
+      harness.engine.lifecycle.dispose();
+      const reloadStore = createReducerBackedStore(reloadDocument);
+      const reloadResolver = vi.fn(() => Promise.resolve(new Blob()));
+      const reloadEngine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: reloadResolver,
+        projectId: reloadStore.projectId,
+        store: reloadStore.store,
+      });
+      expect((await reloadEngine.exports.exportLayerPixels(harness.source.id)).status).toBe('ok');
+      expect(reloadResolver).toHaveBeenCalledWith(durableImage.imageName, expect.any(AbortSignal));
+      reloadEngine.lifecycle.dispose();
+    });
+
+    it('invalidates a deferred pre-filter upload before it can overwrite the durable replace', async () => {
+      vi.useFakeTimers();
+      const uploaded = createDeferred<{ height: number; imageName: string; width: number }>();
+      const uploadImage = vi.fn(() => uploaded.promise);
+      const harness = await createRealBitmapStoreHarness(uploadImage);
+      const barrier = harness.bitmapStore.flushPendingUploads();
+      await drainUntil(() => uploadImage.mock.calls.length === 1);
+      expect(uploadImage).toHaveBeenCalledOnce();
+
+      await expect(
+        harness.engine.layers.commitRasterFilterResult({
+          guard: harness.exported.guard,
+          image: durableImage,
+          mode: 'replace',
+          rect: harness.exported.rect,
+        })
+      ).resolves.toEqual({ layerId: harness.source.id, status: 'committed' });
+      const committed = structuredClone(harness.engine.document.getDocument()!);
+      uploaded.resolve({ height: 10, imageName: 'stale-in-flight-paint', width: 10 });
+      await barrier;
+      await vi.advanceTimersByTimeAsync(3000);
+
+      expect(bitmapUpdateActions(harness.store)).toHaveLength(0);
+      expect(harness.engine.document.getDocument()).toEqual(committed);
+      const cache = await harness.engine.exports.exportLayerPixels(harness.source.id);
+      expect(cache.status).toBe('ok');
+      if (cache.status === 'ok') {
+        expect(drawGraphContains(cache.surface as StubRasterSurface, harness.backend, 'bitmap-filtered-result')).toBe(
+          true
+        );
+      }
+      harness.engine.lifecycle.dispose();
+    });
+
+    it('redo discards a deferred upload from the restored unpersisted paint snapshot', async () => {
+      vi.useFakeTimers();
+      const uploaded = createDeferred<{ height: number; imageName: string; width: number }>();
+      const uploadImage = vi.fn(() => uploaded.promise);
+      const harness = await createRealBitmapStoreHarness(uploadImage);
+      await expect(
+        harness.engine.layers.commitRasterFilterResult({
+          guard: harness.exported.guard,
+          image: durableImage,
+          mode: 'replace',
+          rect: harness.exported.rect,
+        })
+      ).resolves.toEqual({ layerId: harness.source.id, status: 'committed' });
+      const committed = structuredClone(harness.engine.document.getDocument()!);
+
+      harness.engine.history.undo();
+      await harness.refreshPlacement();
+      const barrier = harness.bitmapStore.flushPendingUploads();
+      await drainUntil(() => uploadImage.mock.calls.length === 1);
+      expect(uploadImage).toHaveBeenCalledOnce();
+
+      harness.engine.history.redo();
+      await harness.refreshPlacement();
+      expect(harness.engine.document.getDocument()).toEqual(committed);
+      uploaded.resolve({ height: 10, imageName: 'stale-undo-paint', width: 10 });
+      await barrier;
+      await vi.advanceTimersByTimeAsync(3000);
+
+      expect(harness.discardLayer).toHaveBeenCalledTimes(2);
+      expect(bitmapUpdateActions(harness.store)).toHaveLength(0);
+      expect(harness.engine.document.getDocument()).toEqual(committed);
+      expect(harness.engine.stores.canUndo.get()).toBe(true);
+      expect(harness.engine.stores.canRedo.get()).toBe(false);
+      const redone = harness.engine.document.getDocument()!.layers[0];
+      expect(redone).toMatchObject({ source: { bitmap: durableImage, type: 'paint' } });
+      harness.engine.lifecycle.dispose();
+    });
+
+    it('copy undo generation-cancels a deferred upload before redo reuses the layer id', async () => {
+      vi.useFakeTimers();
+      const uploaded = createDeferred<{ height: number; imageName: string; width: number }>();
+      const uploadImage = vi.fn(() => uploaded.promise);
+      const harness = await createRealBitmapStoreHarness(uploadImage);
+      // The harness creates live source paint to establish a guarded export;
+      // this test targets only persistence owned by the subsequently-created copy.
+      harness.bitmapStore.discardLayer(harness.source.id);
+      const copied = await harness.engine.layers.commitRasterFilterResult({
+        guard: harness.exported.guard,
+        image: durableImage,
+        mode: 'copy',
+        rect: harness.exported.rect,
+      });
+      if (copied.status !== 'committed') {
+        throw new Error('expected a committed filtered copy');
+      }
+      const durableCopy = structuredClone(
+        harness.engine.document.getDocument()!.layers.find((layer) => layer.id === copied.layerId)!
+      );
+
+      harness.engine.selection.selectAll();
+      harness.engine.selection.fillSelection();
+      await harness.refreshPlacement(copied.layerId);
+      const barrier = harness.bitmapStore.flushPendingUploads();
+      await drainUntil(() => uploadImage.mock.calls.length === 1);
+      expect(uploadImage).toHaveBeenCalledOnce();
+
+      // Undo the paint edit, then undo the copy itself. Redo reuses the exact
+      // layer id while the pre-undo upload is still unresolved.
+      harness.engine.history.undo();
+      await harness.refreshPlacement(copied.layerId);
+      harness.engine.history.undo();
+      expect((await harness.engine.exports.exportLayerPixels(copied.layerId)).status).toBe('missing');
+      harness.engine.history.redo();
+      expect(harness.engine.document.getDocument()!.layers.find((layer) => layer.id === copied.layerId)).toEqual(
+        durableCopy
+      );
+
+      uploaded.resolve({ height: 10, imageName: 'stale-copy-paint', width: 10 });
+      await barrier;
+      await vi.advanceTimersByTimeAsync(3000);
+
+      const staleUpdates = (harness.store.dispatch as Mock).mock.calls
+        .map((call) => call[0] as EngineTestAction)
+        .filter((action) => action.type === 'updateCanvasLayerSource' && action.id === copied.layerId);
+      expect(staleUpdates).toHaveLength(0);
+      expect(harness.discardLayer).toHaveBeenCalledWith(copied.layerId);
+      expect(harness.engine.document.getDocument()!.layers.find((layer) => layer.id === copied.layerId)).toEqual(
+        durableCopy
+      );
+      expect(harness.engine.stores.canUndo.get()).toBe(true);
+      const cache = await harness.engine.exports.exportLayerPixels(copied.layerId);
+      expect(cache.status).toBe('ok');
+      if (cache.status === 'ok') {
+        expect(drawGraphContains(cache.surface as StubRasterSurface, harness.backend, 'bitmap-filtered-result')).toBe(
+          true
+        );
+      }
+      harness.engine.lifecycle.dispose();
+    });
+  });
+
+  it.each(['allocation', 'draw'] as const)(
+    'keeps copy redo retryable and exact when detached cache %s fails',
+    async (failure) => {
+      const source = filterLayer('source');
+      const selected = filterLayer('selected');
+      const beforeDocument = { ...filterDoc([source, selected]), selectedLayerId: selected.id };
+      const { projectId, store } = createReducerBackedStore(beforeDocument);
+      const faults = createReplayFaultBackend();
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend: faults.backend,
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'copy',
+        rect: exported.rect,
+      });
+      if (result.status !== 'committed') {
+        throw new Error('expected a committed copy');
+      }
+      const copy = structuredClone(engine.document.getDocument()!.layers[0]!);
+      engine.history.undo();
+      expect(engine.document.getDocument()).toEqual(beforeDocument);
+      const adjustedDeletesBefore = adjustedSurfaceCacheDeletes.length;
+      const thumbnailListener = vi.fn();
+      const unsubscribeThumbnail = engine.stores.thumbnailVersion.subscribe(thumbnailListener);
+      bitmapStore.markLayerDirty.mockClear();
+      (store.dispatch as Mock).mockClear();
+      faults.arm(failure);
+
+      expect(() => engine.history.redo()).toThrow(`replay cache ${failure} failed`);
+
+      expect(engine.document.getDocument()).toEqual(beforeDocument);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+      expect((await engine.exports.exportLayerPixels(result.layerId)).status).toBe('missing');
+      expect(engine.stores.canUndo.get()).toBe(false);
+      expect(engine.stores.canRedo.get()).toBe(true);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(thumbnailListener).not.toHaveBeenCalled();
+      expect(adjustedSurfaceCacheDeletes).toHaveLength(adjustedDeletesBefore);
+
+      engine.history.redo();
+      expect(engine.document.getDocument()!.layers[0]).toEqual(copy);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+      expect((await engine.exports.exportLayerPixels(result.layerId)).status).toBe('ok');
+      expect(engine.stores.canUndo.get()).toBe(true);
+      expect(engine.stores.canRedo.get()).toBe(false);
+      unsubscribeThumbnail();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  const createGuardHarness = async (
+    imageResolver: (imageName: string, signal?: AbortSignal) => Promise<Blob> = () => Promise.resolve(new Blob())
+  ) => {
+    const layer = filterLayer();
+    const document = filterDoc([layer]);
+    const reactive = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver,
+      projectId: 'p1',
+      store: reactive.store,
+    });
+    const exported = await engine.exports.exportLayerPixels(layer.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+    (reactive.store.dispatch as Mock).mockClear();
+    const commit = (signal?: AbortSignal) =>
+      engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'replace',
+        rect: exported.rect,
+        signal,
+      });
+    return { ...reactive, commit, document, engine, guard: exported.guard, layer };
+  };
+
+  const createPendingGuardHarness = async () => {
+    const decoded = createDeferred<Blob>();
+    const harness = await createGuardHarness(() => decoded.promise);
+    return { ...harness, decoded, pending: harness.commit() };
+  };
+
+  it('returns failed without mutation when the durable image cannot be decoded', async () => {
+    const harness = await createGuardHarness(() => Promise.reject(new Error('decode failed')));
+
+    await expect(harness.commit()).resolves.toEqual({ message: 'decode failed', status: 'failed' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns aborted without starting durable-image decode when already cancelled', async () => {
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+    const harness = await createGuardHarness(resolver);
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(harness.commit(controller.signal)).resolves.toEqual({ status: 'aborted' });
+    expect(resolver).not.toHaveBeenCalled();
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('passes the exact cancellation signal into durable-image resolution', async () => {
+    const resolver = vi.fn((_imageName: string, _signal?: AbortSignal) => Promise.resolve(new Blob()));
+    const layer = filterLayer();
+    const reducer = createReducerBackedStore(filterDoc([layer]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: resolver,
+      projectId: reducer.projectId,
+      store: reducer.store,
+    });
+    const exported = await engine.exports.exportLayerPixels(layer.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+    const controller = new AbortController();
+
+    await expect(
+      engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode: 'replace',
+        rect: exported.rect,
+        signal: controller.signal,
+      })
+    ).resolves.toMatchObject({ status: 'committed' });
+    expect(resolver).toHaveBeenCalledWith(durableImage.imageName, controller.signal);
+    engine.lifecycle.dispose();
+  });
+
+  it('maps an abort rejection from durable-image resolution to aborted without mutation', async () => {
+    const resolver = vi.fn(() => Promise.reject(new DOMException('cancelled', 'AbortError')));
+    const harness = await createGuardHarness(resolver);
+    const controller = new AbortController();
+
+    await expect(harness.commit(controller.signal)).resolves.toEqual({ status: 'aborted' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns aborted without mutation when cancellation occurs during durable-image decode', async () => {
+    const decoded = createDeferred<Blob>();
+    const harness = await createGuardHarness(() => decoded.promise);
+    const controller = new AbortController();
+
+    const pending = harness.commit(controller.signal);
+    controller.abort();
+    decoded.resolve(new Blob());
+
+    await expect(pending).resolves.toEqual({ status: 'aborted' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('does not publish when an operation starts during durable-image decode', async () => {
+    const harness = await createPendingGuardHarness();
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(harness.engine).controller.start({
+      cleanupPreview,
+      guard: harness.guard,
+      identity: { kind: 'filter', layerId: harness.layer.id, projectId: 'p1' },
+    });
+
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'busy' });
+    expect(harness.engine.document.getDocument()).toEqual(harness.document);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(cleanupPreview).not.toHaveBeenCalled();
+    expect(getCanvasOperations(harness.engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'filter' },
+      status: 'active',
+    });
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns missing without mutation when the source is deleted', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, layers: [] });
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'missing' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns stale without mutation when the source contract changes', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, layers: [{ ...harness.layer, opacity: 0.2 }] });
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'stale' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns locked without mutation when the source becomes locked', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, layers: [{ ...harness.layer, isLocked: true }] });
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'locked' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns stale without mutation when the guarded source changes layer type', async () => {
+    const harness = await createPendingGuardHarness();
+    const { adjustments: _adjustments, ...base } = harness.layer;
+    const control: CanvasLayerContract = {
+      ...base,
+      adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      type: 'control',
+      withTransparencyEffect: false,
+    };
+    harness.setDocument({ ...harness.document, layers: [control] });
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'stale' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns stale without mutation after the source cache version changes', async () => {
+    const harness = await createPendingGuardHarness();
+    await harness.engine.diagnostics.clearCaches();
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'stale' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns stale without mutation after document replacement reuses the source layer', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, height: 200, width: 200 }, 1);
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'stale' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('commits to the bound project after the active project changes', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setActiveProjectId('p2');
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ layerId: 'L', status: 'committed' });
+    expect(harness.store.dispatch).toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns busy without mutation while a pointer gesture is open', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const harness = await createPendingGuardHarness();
+    const screen = createInputCanvas();
+    const overlay = createInputCanvas();
+    harness.engine.surface.attach(screen.element, overlay.element);
+    overlay.fire('pointerdown', pointerAt(5, 5));
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'busy' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it.each(['replace', 'copy'] as const)(
+    'leaves document, cache, selection, history, and side effects exact when %s cache preparation fails',
+    async (mode) => {
+      const baseBackend = createTestStubRasterBackend();
+      let successfulCreatesBeforeFailure: number | null = null;
+      const backend: StubRasterBackend = {
+        ...baseBackend,
+        createSurface: (width, height) => {
+          if (successfulCreatesBeforeFailure !== null) {
+            if (successfulCreatesBeforeFailure === 0) {
+              throw new Error('filter cache allocation failed');
+            }
+            successfulCreatesBeforeFailure -= 1;
+          }
+          return baseBackend.createSurface(width, height);
+        },
+      };
+      const source = filterLayer('source');
+      const selected = filterLayer('selected');
+      const beforeDocument = { ...filterDoc([source, selected]), selectedLayerId: selected.id };
+      const { projectId, store } = createReducerBackedStore(beforeDocument);
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend,
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      const cacheSurface = exported.surface;
+      const cacheCalls = structuredClone((cacheSurface as StubRasterSurface).callLog);
+      const thumbnailVersion = engine.stores.thumbnailVersion.get(source.id);
+      const thumbnailListener = vi.fn();
+      const unsubscribeThumbnail = engine.stores.thumbnailVersion.subscribe(thumbnailListener);
+      const adjustedDeletesBefore = adjustedSurfaceCacheDeletes.length;
+      bitmapStore.markLayerDirty.mockClear();
+      (store.dispatch as Mock).mockClear();
+
+      // Commit allocates the decoded candidate first. Replace also captures its
+      // before-pixels snapshot. The following allocation is cache preparation.
+      successfulCreatesBeforeFailure = mode === 'replace' ? 2 : 1;
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode,
+        rect: exported.rect,
+      });
+      successfulCreatesBeforeFailure = null;
+
+      expect(result).toEqual({ message: 'filter cache allocation failed', status: 'failed' });
+      expect(engine.document.getDocument()).toEqual(beforeDocument);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(false);
+      expect(engine.stores.canRedo.get()).toBe(false);
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(thumbnailListener).not.toHaveBeenCalled();
+      expect(engine.stores.thumbnailVersion.get(source.id)).toBe(thumbnailVersion);
+      expect(adjustedSurfaceCacheDeletes).toHaveLength(adjustedDeletesBefore);
+
+      const afterExport = await engine.exports.exportLayerPixels(source.id);
+      expect(afterExport.status).toBe('ok');
+      if (afterExport.status === 'ok') {
+        expect(afterExport.surface).toBe(cacheSurface);
+        expect(afterExport.rect).toEqual(exported.rect);
+        expect(afterExport.guard.cacheVersion).toBe(exported.guard.cacheVersion);
+        expect((afterExport.surface as StubRasterSurface).callLog).toEqual(cacheCalls);
+      }
+
+      unsubscribeThumbnail();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['replace', 'copy'] as const)(
+    'leaves document, cache, selection, history, and side effects exact when %s cache preparation draw fails',
+    async (mode) => {
+      const baseBackend = createTestStubRasterBackend();
+      let successfulDrawsBeforeFailure: number | null = null;
+      const backend: StubRasterBackend = {
+        ...baseBackend,
+        createSurface: (width, height) => {
+          const surface = baseBackend.createSurface(width, height);
+          const ctx = new Proxy(surface.ctx, {
+            get: (target, property, receiver) => {
+              const value = Reflect.get(target, property, receiver);
+              if (property !== 'drawImage' || typeof value !== 'function') {
+                return value;
+              }
+              return (...args: unknown[]) => {
+                if (successfulDrawsBeforeFailure !== null) {
+                  if (successfulDrawsBeforeFailure === 0) {
+                    throw new Error('filter cache draw failed');
+                  }
+                  successfulDrawsBeforeFailure -= 1;
+                }
+                return Reflect.apply(value, target, args);
+              };
+            },
+          });
+          Object.defineProperty(surface, 'ctx', { value: ctx });
+          return surface;
+        },
+      };
+      const source = filterLayer('source');
+      const selected = filterLayer('selected');
+      const beforeDocument = { ...filterDoc([source, selected]), selectedLayerId: selected.id };
+      const { projectId, store } = createReducerBackedStore(beforeDocument);
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend,
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      const cacheSurface = exported.surface;
+      const cacheCalls = structuredClone((cacheSurface as StubRasterSurface).callLog);
+      const thumbnailVersion = engine.stores.thumbnailVersion.get(source.id);
+      const thumbnailListener = vi.fn();
+      const unsubscribeThumbnail = engine.stores.thumbnailVersion.subscribe(thumbnailListener);
+      const adjustedDeletesBefore = adjustedSurfaceCacheDeletes.length;
+      bitmapStore.markLayerDirty.mockClear();
+      (store.dispatch as Mock).mockClear();
+
+      // Commit draws the decoded candidate first. Replace also captures its
+      // before-pixels snapshot. The following draw prepares the detached cache.
+      successfulDrawsBeforeFailure = mode === 'replace' ? 2 : 1;
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode,
+        rect: exported.rect,
+      });
+      successfulDrawsBeforeFailure = null;
+
+      expect(result).toEqual({ message: 'filter cache draw failed', status: 'failed' });
+      expect(engine.document.getDocument()).toEqual(beforeDocument);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(false);
+      expect(engine.stores.canRedo.get()).toBe(false);
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(thumbnailListener).not.toHaveBeenCalled();
+      expect(engine.stores.thumbnailVersion.get(source.id)).toBe(thumbnailVersion);
+      expect(adjustedSurfaceCacheDeletes).toHaveLength(adjustedDeletesBefore);
+
+      const afterExport = await engine.exports.exportLayerPixels(source.id);
+      expect(afterExport.status).toBe('ok');
+      if (afterExport.status === 'ok') {
+        expect(afterExport.surface).toBe(cacheSurface);
+        expect(afterExport.rect).toEqual(exported.rect);
+        expect(afterExport.guard.cacheVersion).toBe(exported.guard.cacheVersion);
+        expect((afterExport.surface as StubRasterSurface).callLog).toEqual(cacheCalls);
+      }
+
+      unsubscribeThumbnail();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['replace', 'copy'] as const)(
+    'commits %s after dispatch even when render scheduling throws, without redundant persistence',
+    async (mode) => {
+      const raf = createControllableRaf();
+      vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+      vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+      const source = filterLayer('source');
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      engine.surface.attach(createFakeCanvas().element, createFakeCanvas().element);
+      raf.flush();
+      bitmapStore.markLayerDirty.mockImplementation(() => {
+        throw new Error('unexpected filter result persistence');
+      });
+      vi.stubGlobal('requestAnimationFrame', () => {
+        throw new Error('render scheduling failed');
+      });
+
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode,
+        rect: exported.rect,
+      });
+
+      if (result.status !== 'committed') {
+        throw new Error(`expected a committed result, received ${JSON.stringify(result)}`);
+      }
+      expect(result).toMatchObject({ status: 'committed' });
+      expect(store.dispatch).toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(true);
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['replace', 'copy'] as const)(
+    'commits %s when a thumbnail observer throws, without redundant persistence',
+    async (mode) => {
+      const source = filterLayer('source');
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      const unsubscribeThumbnail = engine.stores.thumbnailVersion.subscribe(() => {
+        throw new Error('thumbnail observer failed');
+      });
+      bitmapStore.markLayerDirty.mockImplementation(() => {
+        throw new Error('unexpected filter result persistence');
+      });
+
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode,
+        rect: exported.rect,
+      });
+
+      expect(result).toMatchObject({ status: 'committed' });
+      expect(store.dispatch).toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(true);
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      unsubscribeThumbnail();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['replace', 'copy'] as const)(
+    'commits %s when a document observer throws after the reducer applies the mutation',
+    async (mode) => {
+      const source = filterLayer('source');
+      const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+      const bitmapStore = createSpyBitmapStore();
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore,
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected a filterable export');
+      }
+      const unsubscribeFault = store.subscribe(() => {
+        throw new Error('document observer failed');
+      });
+
+      const result = await engine.layers.commitRasterFilterResult({
+        guard: exported.guard,
+        image: durableImage,
+        mode,
+        rect: exported.rect,
+      });
+
+      expect(result).toMatchObject({ status: 'committed' });
+      expect(engine.stores.canUndo.get()).toBe(true);
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      if (result.status === 'committed') {
+        expect((await engine.exports.exportLayerPixels(result.layerId)).status).toBe('ok');
+      }
+      unsubscribeFault();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('refreshes the mirror and renders the filtered result when an earlier document observer interrupts dispatch', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const source = filterLayer('source');
+    const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+    const unsubscribeFault = store.subscribe(() => {
+      throw new Error('earlier document observer failed');
+    });
+    const backend = createRecordingRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(recordingBitmap('filtered-result')));
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+
+    const result = await engine.layers.commitRasterFilterResult({
+      guard: exported.guard,
+      image: durableImage,
+      mode: 'replace',
+      rect: exported.rect,
+    });
+    unsubscribeFault();
+
+    expect(result).toEqual({ layerId: source.id, status: 'committed' });
+    const reducerDocument = store.getState().projects.find((project) => project.id === projectId)!.canvas.document;
+    expect(reducerDocument.layers[0]).toMatchObject({
+      source: { bitmap: durableImage, type: 'paint' },
+    });
+    expect(engine.document.getDocument()).toBe(reducerDocument);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    const committedExport = await engine.exports.exportLayerPixels(source.id);
+    expect(committedExport.status).toBe('ok');
+    if (committedExport.status === 'ok') {
+      expect(drawGraphContains(committedExport.surface as StubRasterSurface, backend, 'bitmap-filtered-result')).toBe(
+        true
+      );
+    }
+
+    const screen = createFakeCanvas();
+    engine.surface.attach(screen.element, createFakeCanvas().element);
+    raf.flush();
+    expect(drawGraphContains(screen.surface, backend, 'bitmap-filtered-result')).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('finishes copy undo and restores the exact prior selection after an applied observer fault', async () => {
+    const source = filterLayer('source');
+    const selected = filterLayer('selected');
+    const beforeDocument = { ...filterDoc([source, selected]), selectedLayerId: selected.id };
+    const { projectId, store } = createReducerBackedStore(beforeDocument);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+    const result = await engine.layers.commitRasterFilterResult({
+      guard: exported.guard,
+      image: durableImage,
+      mode: 'copy',
+      rect: exported.rect,
+    });
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed copy');
+    }
+    const copy = structuredClone(engine.document.getDocument()!.layers[0]!);
+    const unsubscribeFault = store.subscribe(() => {
+      throw new Error('copy undo observer failed');
+    });
+
+    expect(() => engine.history.undo()).not.toThrow();
+
+    expect(engine.document.getDocument()).toEqual(beforeDocument);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+    expect((await engine.exports.exportLayerPixels(result.layerId)).status).toBe('missing');
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+    unsubscribeFault();
+
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(copy);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps copy undo retryable when removal fails after restoring the prior selection', async () => {
+    const source = filterLayer('source');
+    const selected = filterLayer('selected');
+    const beforeDocument = { ...filterDoc([source, selected]), selectedLayerId: selected.id };
+    const { dispatch, projectId, store } = createReducerBackedStore(beforeDocument);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+    const result = await engine.layers.commitRasterFilterResult({
+      guard: exported.guard,
+      image: durableImage,
+      mode: 'copy',
+      rect: exported.rect,
+    });
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed copy');
+    }
+    const reducerDispatch = dispatch.getMockImplementation();
+    if (!reducerDispatch) {
+      throw new Error('expected reducer-backed dispatch');
+    }
+    let failRemoval = true;
+    dispatch.mockImplementation((action: EngineTestAction) => {
+      if (failRemoval && action.type === 'removeCanvasLayers') {
+        failRemoval = false;
+        throw new Error('copy removal failed');
+      }
+      reducerDispatch(action);
+    });
+
+    expect(() => engine.history.undo()).toThrow('copy removal failed');
+
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === result.layerId)).toBe(true);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()).toEqual(beforeDocument);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['replace', 'copy'] as const)('commits %s when a history-state observer throws', async (mode) => {
+    const source = filterLayer('source');
+    const { projectId, store } = createReducerBackedStore(filterDoc([source]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a filterable export');
+    }
+    const unsubscribeFault = engine.stores.canUndo.subscribe(() => {
+      throw new Error('history observer failed');
+    });
+
+    const result = await engine.layers.commitRasterFilterResult({
+      guard: exported.guard,
+      image: durableImage,
+      mode,
+      rect: exported.rect,
+    });
+
+    expect(result).toMatchObject({ status: 'committed' });
+    expect(engine.stores.canUndo.get()).toBe(true);
+    if (result.status === 'committed') {
+      expect((await engine.exports.exportLayerPixels(result.layerId)).status).toBe('ok');
+    }
+    unsubscribeFault();
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('commitGeneratedImageResult', () => {
+  const generatedImage = { height: 18, imageName: 'workflow-result.png', width: 24 };
+  const generatedOrigin = { x: -9, y: 14 };
+
+  const workflowRaster = (id = 'source'): CanvasRasterLayerContractV2 => ({
+    adjustments: { brightness: 0.2, contrast: -0.1, saturation: 0.3 },
+    blendMode: 'multiply',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name: id,
+    opacity: 0.65,
+    source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+    transform: { rotation: 0.4, scaleX: 2, scaleY: 3, x: 5, y: 6 },
+    type: 'raster',
+  });
+
+  const workflowControl = (id = 'source'): CanvasLayerContract => ({
+    adapter: {
+      beginEndStepPct: [0.15, 0.85],
+      controlMode: 'more_control',
+      kind: 'controlnet',
+      model: 'control-model',
+      weight: 0.7,
+    },
+    blendMode: 'screen',
+    filter: { settings: { low: 12, high: 90 }, type: 'canny' },
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name: id,
+    opacity: 0.55,
+    source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+    transform: { rotation: -0.3, scaleX: 1.5, scaleY: 0.75, x: 11, y: -4 },
+    type: 'control',
+    withTransparencyEffect: true,
+  });
+
+  const workflowDocument = (layers: CanvasLayerContract[] = [workflowRaster()]): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers,
+    selectedLayerId: layers.at(-1)?.id ?? null,
+    version: 2,
+    width: 100,
+  });
+
+  const createGeneratedFaultBackend = () => {
+    const base = createTestStubRasterBackend();
+    let allocationCountdown: number | null = null;
+    let drawCountdown: number | null = null;
+    let createHook: { countdown: number; run: () => void } | null = null;
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (width, height) => {
+        if (allocationCountdown !== null) {
+          if (allocationCountdown === 0) {
+            allocationCountdown = null;
+            throw new Error('generated cache allocation failed');
+          }
+          allocationCountdown -= 1;
+        }
+        if (createHook) {
+          if (createHook.countdown === 0) {
+            const hook = createHook;
+            createHook = null;
+            hook.run();
+          } else {
+            createHook.countdown -= 1;
+          }
+        }
+        const surface = base.createSurface(width, height);
+        const ctx = new Proxy(surface.ctx, {
+          get: (target, property, receiver) => {
+            const value = Reflect.get(target, property, receiver);
+            if (property !== 'drawImage' || typeof value !== 'function') {
+              return value;
+            }
+            return (...args: unknown[]) => {
+              if (drawCountdown !== null) {
+                if (drawCountdown === 0) {
+                  drawCountdown = null;
+                  throw new Error('generated cache draw failed');
+                }
+                drawCountdown -= 1;
+              }
+              return Reflect.apply(value, target, args);
+            };
+          },
+        });
+        Object.defineProperty(surface, 'ctx', { value: ctx });
+        return surface;
+      },
+    };
+    return {
+      armAllocation: (successfulCreates: number) => {
+        allocationCountdown = successfulCreates;
+      },
+      armCreateHook: (successfulCreates: number, run: () => void) => {
+        createHook = { countdown: successfulCreates, run };
+      },
+      armDraw: (successfulDraws: number) => {
+        drawCountdown = successfulDraws;
+      },
+      backend,
+    };
+  };
+
+  it.each([
+    { base: 'z-image', expectedKind: 'z_image_control' },
+    { base: 'sd-1', expectedKind: 'controlnet' },
+    { base: 'flux', expectedKind: 'controlnet' },
+  ] as const)(
+    'uses $expectedKind defaults when workflow Copy To Control runs under $base',
+    async ({ base, expectedKind }) => {
+      const source = workflowRaster();
+      const { projectId, store } = createReducerBackedStore(workflowDocument([source]), base);
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected an exportable workflow source');
+      }
+
+      const result = await engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target: 'copy-control',
+      });
+
+      expect(result.status).toBe('committed');
+      if (result.status !== 'committed') {
+        throw new Error('expected a committed control copy');
+      }
+      const created = engine.document.getDocument()!.layers.find((layer) => layer.id === result.layerId);
+      expect(created?.type === 'control' ? created.adapter.kind : null).toBe(expectedKind);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('replaces a raster at the generated origin and native size, clears baked adjustments, and replays exactly', async () => {
+    const source = workflowRaster();
+    const before = structuredClone(source);
+    const backend = createRecordingRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(recordingBitmap('workflow-result')));
+    const bitmapStore = createSpyBitmapStore();
+    const { projectId, store } = createReducerBackedStore(workflowDocument([source]));
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+
+    const result = await engine.layers.commitGeneratedImageResult({
+      guard: exported.guard,
+      image: generatedImage,
+      origin: generatedOrigin,
+      target: 'replace',
+    });
+
+    expect(result).toEqual({ layerId: source.id, status: 'committed' });
+    const after = engine.document.getDocument()!.layers[0]!;
+    expect(after).toEqual({
+      blendMode: source.blendMode,
+      id: source.id,
+      isEnabled: source.isEnabled,
+      isLocked: source.isLocked,
+      name: source.name,
+      opacity: source.opacity,
+      source: { bitmap: generatedImage, offset: generatedOrigin, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    expect('adjustments' in after).toBe(false);
+    const committedPixels = await engine.exports.exportLayerPixels(source.id);
+    expect(committedPixels.status).toBe('ok');
+    if (committedPixels.status === 'ok') {
+      expect(committedPixels.rect).toEqual({ ...generatedOrigin, height: 18, width: 24 });
+      expect(drawGraphContains(committedPixels.surface as StubRasterSurface, backend, 'bitmap-workflow-result')).toBe(
+        true
+      );
+    }
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(before);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(after);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    expect(bitmapStore.discardLayer).toHaveBeenCalledTimes(2);
+    engine.lifecycle.dispose();
+  });
+
+  it('replaces a control while preserving adapter, filter, transparency effect, and layer presentation', async () => {
+    const source = workflowControl();
+    const { projectId, store } = createReducerBackedStore(workflowDocument([source]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+
+    await expect(
+      engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target: 'replace',
+      })
+    ).resolves.toEqual({ layerId: source.id, status: 'committed' });
+
+    expect(engine.document.getDocument()!.layers[0]).toEqual({
+      ...source,
+      source: { bitmap: generatedImage, offset: generatedOrigin, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    });
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers[0]).toEqual(source);
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[0]).toMatchObject({
+      adapter: source.type === 'control' ? source.adapter : undefined,
+      filter: source.type === 'control' ? source.filter : undefined,
+      withTransparencyEffect: true,
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('copies a generated result to an unlocked raster immediately above its source and restores selection on undo', async () => {
+    const above = workflowRaster('above');
+    const source = workflowControl('source');
+    const selected = workflowRaster('selected');
+    const document = { ...workflowDocument([above, source, selected]), selectedLayerId: selected.id };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+
+    const result = await engine.layers.commitGeneratedImageResult({
+      guard: exported.guard,
+      image: generatedImage,
+      origin: generatedOrigin,
+      target: 'copy-raster',
+    });
+    if (result.status !== 'committed') {
+      throw new Error(`expected a committed copy, received ${JSON.stringify(result)}`);
+    }
+
+    expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual([
+      above.id,
+      result.layerId,
+      source.id,
+      selected.id,
+    ]);
+    expect(engine.document.getDocument()!.layers[2]).toEqual(source);
+    expect(engine.document.getDocument()!.layers[1]).toMatchObject({
+      id: result.layerId,
+      isEnabled: true,
+      isLocked: false,
+      opacity: 1,
+      source: { bitmap: generatedImage, offset: generatedOrigin, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.history.redo();
+    expect(engine.document.getDocument()!.layers[1]?.id).toBe(result.layerId);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  const createPendingGuardHarness = async () => {
+    const source = workflowRaster();
+    const document = workflowDocument([source]);
+    const decoded = createDeferred<Blob>();
+    const reactive = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: (imageName) =>
+        imageName === generatedImage.imageName ? decoded.promise : Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store: reactive.store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    (reactive.store.dispatch as Mock).mockClear();
+    const pending = engine.layers.commitGeneratedImageResult({
+      guard: exported.guard,
+      image: generatedImage,
+      origin: generatedOrigin,
+      target: 'replace',
+    });
+    return { ...reactive, decoded, document, engine, exported, pending, source };
+  };
+
+  it('returns failed without mutation when the durable generated image cannot be resolved', async () => {
+    const source = workflowRaster();
+    const document = workflowDocument([source]);
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: (imageName) =>
+        imageName === generatedImage.imageName
+          ? Promise.reject(new Error('generated decode failed'))
+          : Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    (store.dispatch as Mock).mockClear();
+
+    await expect(
+      engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target: 'replace',
+      })
+    ).resolves.toEqual({ message: 'generated decode failed', status: 'failed' });
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(store.dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns missing after decode when the source was deleted', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, layers: [] });
+    harness.decoded.resolve(new Blob());
+    await expect(harness.pending).resolves.toEqual({ status: 'missing' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns locked after decode when the source became locked', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, layers: [{ ...harness.source, isLocked: true }] });
+    harness.decoded.resolve(new Blob());
+    await expect(harness.pending).resolves.toEqual({ status: 'locked' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns unsupported after decode when the source became a mask', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, layers: [maskLayer(harness.source.id)] });
+    harness.decoded.resolve(new Blob());
+    await expect(harness.pending).resolves.toEqual({ status: 'unsupported' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns stale after decode when the immutable source contract changed', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, layers: [{ ...harness.source, opacity: 0.1 }] });
+    harness.decoded.resolve(new Blob());
+    await expect(harness.pending).resolves.toEqual({ status: 'stale' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns stale after decode when the document was replaced with the same source object', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setDocument({ ...harness.document, width: 200 }, 1);
+    harness.decoded.resolve(new Blob());
+    await expect(harness.pending).resolves.toEqual({ status: 'stale' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('commits after decode when another project became active', async () => {
+    const harness = await createPendingGuardHarness();
+    harness.setActiveProjectId('p2');
+    harness.decoded.resolve(new Blob());
+    await expect(harness.pending).resolves.toEqual({ layerId: 'source', status: 'committed' });
+    expect(harness.store.dispatch).toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns busy after decode while a pointer gesture is open', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const harness = await createPendingGuardHarness();
+    const overlay = createInputCanvas();
+    harness.engine.surface.attach(createInputCanvas().element, overlay.element);
+    overlay.fire('pointerdown', pointerAt(5, 5));
+    harness.decoded.resolve(new Blob());
+    await expect(harness.pending).resolves.toEqual({ status: 'busy' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('does not publish when an operation starts during generated-image decode', async () => {
+    const harness = await createPendingGuardHarness();
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(harness.engine).controller.start({
+      cleanupPreview,
+      guard: harness.exported.guard,
+      identity: { kind: 'filter', layerId: harness.source.id, projectId: 'p1' },
+    });
+
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'busy' });
+    expect(harness.engine.document.getDocument()).toEqual(harness.document);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(cleanupPreview).not.toHaveBeenCalled();
+    expect(getCanvasOperations(harness.engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'filter' },
+      status: 'active',
+    });
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('does not publish when an operation starts and ends during generated-image decode', async () => {
+    const harness = await createPendingGuardHarness();
+    const operation = getCanvasOperations(harness.engine).controller.start({
+      cleanupPreview: vi.fn(),
+      guard: harness.exported.guard,
+      identity: { kind: 'filter', layerId: harness.source.id, projectId: 'p1' },
+    });
+    operation?.cancel();
+
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'busy' });
+    expect(harness.engine.document.getDocument()).toEqual(harness.document);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    expect(getCanvasOperations(harness.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns aborted without resolving the generated image when already cancelled', async () => {
+    const source = workflowRaster();
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+    const { projectId, store } = createReducerBackedStore(workflowDocument([source]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: resolver,
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    resolver.mockClear();
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        signal: controller.signal,
+        target: 'replace',
+      })
+    ).resolves.toEqual({ status: 'aborted' });
+    expect(resolver).not.toHaveBeenCalled();
+    expect(engine.document.getDocument()).toEqual(workflowDocument([source]));
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns aborted during bitmap decode, releases the late bitmap, and never mutates', async () => {
+    const source = workflowRaster();
+    const bitmapDeferred = createDeferred<ImageBitmap>();
+    const bitmap = recordingBitmap('late-generated');
+    const base = createTestStubRasterBackend();
+    const createImageBitmap = vi.fn(() => bitmapDeferred.promise);
+    const { projectId, store } = createReducerBackedStore(workflowDocument([source]));
+    const engine = createCanvasEngine({
+      backend: { ...base, createImageBitmap },
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    const controller = new AbortController();
+    const pending = engine.layers.commitGeneratedImageResult({
+      guard: exported.guard,
+      image: generatedImage,
+      origin: generatedOrigin,
+      signal: controller.signal,
+      target: 'replace',
+    });
+    await vi.waitFor(() => expect(createImageBitmap).toHaveBeenCalledOnce());
+
+    controller.abort();
+    bitmapDeferred.resolve(bitmap);
+
+    await expect(pending).resolves.toEqual({ status: 'aborted' });
+    expect(bitmap.close).toHaveBeenCalledOnce();
+    expect(engine.document.getDocument()).toEqual(workflowDocument([source]));
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns stale when unpersisted paint pixels change while the generated image resolves', async () => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const source: CanvasRasterLayerContractV2 = {
+      ...workflowRaster(),
+      source: {
+        bitmap: { height: 10, imageName: 'workflow-paint-source.png', width: 10 },
+        type: 'paint',
+      },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    };
+    const generatedBlob = createDeferred<Blob>();
+    const { projectId, store } = createReducerBackedStore(workflowDocument([source]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: (imageName) =>
+        imageName === generatedImage.imageName ? generatedBlob.promise : Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    const pending = engine.layers.commitGeneratedImageResult({
+      guard: exported.guard,
+      image: generatedImage,
+      origin: generatedOrigin,
+      target: 'replace',
+    });
+
+    engine.selection.selectAll();
+    engine.selection.fillSelection();
+    const afterPaintEdit = structuredClone(engine.document.getDocument()!);
+    generatedBlob.resolve(new Blob());
+
+    await expect(pending).resolves.toEqual({ status: 'stale' });
+    expect(engine.document.getDocument()).toEqual(afterPaintEdit);
+    expect(engine.document.getDocument()!.layers[0]).not.toMatchObject({ source: { bitmap: generatedImage } });
+    expect(engine.stores.canUndo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it.each([
+    { successfulCreates: 0, target: 'replace' as const },
+    { successfulCreates: 2, target: 'replace' as const },
+    { successfulCreates: 1, target: 'copy-raster' as const },
+  ])(
+    'leaves document, cache, selection, and history exact when $target allocation fails after $successfulCreates successful creates',
+    async ({ successfulCreates, target }) => {
+      const source = workflowRaster();
+      const selected = workflowRaster('selected');
+      const document = { ...workflowDocument([source, selected]), selectedLayerId: selected.id };
+      const faults = createGeneratedFaultBackend();
+      const bitmap = recordingBitmap('allocation-failure');
+      faults.backend.createImageBitmap = vi.fn(() => Promise.resolve(bitmap));
+      const { projectId, store } = createReducerBackedStore(document);
+      const engine = createCanvasEngine({
+        backend: faults.backend,
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected an exportable workflow source');
+      }
+      const cache = exported.surface;
+      const cacheCalls = structuredClone((cache as StubRasterSurface).callLog);
+      (store.dispatch as Mock).mockClear();
+      faults.armAllocation(successfulCreates);
+
+      const result = await engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target,
+      });
+
+      expect(result).toEqual({ message: 'generated cache allocation failed', status: 'failed' });
+      expect(bitmap.close).toHaveBeenCalledOnce();
+      expect(engine.document.getDocument()).toEqual(document);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(false);
+      const after = await engine.exports.exportLayerPixels(source.id);
+      expect(after.status).toBe('ok');
+      if (after.status === 'ok') {
+        expect(after.surface).toBe(cache);
+        expect(after.guard.cacheVersion).toBe(exported.guard.cacheVersion);
+        expect((after.surface as StubRasterSurface).callLog).toEqual(cacheCalls);
+      }
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each([
+    { successfulDraws: 0, target: 'replace' as const },
+    { successfulDraws: 2, target: 'replace' as const },
+    { successfulDraws: 1, target: 'copy-raster' as const },
+  ])(
+    'leaves document, cache, selection, and history exact when $target draw fails after $successfulDraws successful draws',
+    async ({ successfulDraws, target }) => {
+      const source = workflowRaster();
+      const selected = workflowRaster('selected');
+      const document = { ...workflowDocument([source, selected]), selectedLayerId: selected.id };
+      const faults = createGeneratedFaultBackend();
+      const bitmap = recordingBitmap('draw-failure');
+      faults.backend.createImageBitmap = vi.fn(() => Promise.resolve(bitmap));
+      const { projectId, store } = createReducerBackedStore(document);
+      const engine = createCanvasEngine({
+        backend: faults.backend,
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected an exportable workflow source');
+      }
+      const cache = exported.surface;
+      const cacheCalls = structuredClone((cache as StubRasterSurface).callLog);
+      (store.dispatch as Mock).mockClear();
+      faults.armDraw(successfulDraws);
+
+      const result = await engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target,
+      });
+
+      expect(result).toEqual({ message: 'generated cache draw failed', status: 'failed' });
+      expect(bitmap.close).toHaveBeenCalledOnce();
+      expect(engine.document.getDocument()).toEqual(document);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(false);
+      const after = await engine.exports.exportLayerPixels(source.id);
+      expect(after.status).toBe('ok');
+      if (after.status === 'ok') {
+        expect(after.surface).toBe(cache);
+        expect(after.guard.cacheVersion).toBe(exported.guard.cacheVersion);
+        expect((after.surface as StubRasterSurface).callLog).toEqual(cacheCalls);
+      }
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each([
+    { successfulCreates: 2, target: 'replace' as const },
+    { successfulCreates: 1, target: 'copy-raster' as const },
+  ])(
+    'returns aborted without mutation when $target is cancelled during cache preparation',
+    async ({ successfulCreates, target }) => {
+      const source = workflowRaster();
+      const document = workflowDocument([source]);
+      const faults = createGeneratedFaultBackend();
+      const controller = new AbortController();
+      const { projectId, store } = createReducerBackedStore(document);
+      const engine = createCanvasEngine({
+        backend: faults.backend,
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels(source.id);
+      if (exported.status !== 'ok') {
+        throw new Error('expected an exportable workflow source');
+      }
+      (store.dispatch as Mock).mockClear();
+      faults.armCreateHook(successfulCreates, () => controller.abort());
+
+      await expect(
+        engine.layers.commitGeneratedImageResult({
+          guard: exported.guard,
+          image: generatedImage,
+          origin: generatedOrigin,
+          signal: controller.signal,
+          target,
+        })
+      ).resolves.toEqual({ status: 'aborted' });
+      expect(engine.document.getDocument()).toEqual(document);
+      expect(store.dispatch).not.toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(false);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each([
+    { successfulCreates: 2, target: 'replace' as const },
+    { successfulCreates: 1, target: 'copy-raster' as const },
+  ])('revalidates the exact guard immediately before $target publication', async ({ successfulCreates, target }) => {
+    const source = workflowRaster();
+    const document = workflowDocument([source]);
+    const reactive = createReactiveStore(document);
+    const faults = createGeneratedFaultBackend();
+    const engine = createCanvasEngine({
+      backend: faults.backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store: reactive.store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    (reactive.store.dispatch as Mock).mockClear();
+    faults.armCreateHook(successfulCreates, () => {
+      reactive.setDocument({ ...document, layers: [{ ...source, opacity: 0.2 }] });
+    });
+
+    await expect(
+      engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target,
+      })
+    ).resolves.toEqual({ status: 'stale' });
+    expect(reactive.store.dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps replace undo and redo retryable when detached cache preparation fails', async () => {
+    const source = workflowRaster();
+    const document = workflowDocument([source]);
+    const faults = createGeneratedFaultBackend();
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: faults.backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    await expect(
+      engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target: 'replace',
+      })
+    ).resolves.toEqual({ layerId: source.id, status: 'committed' });
+    const committed = structuredClone(engine.document.getDocument()!);
+
+    faults.armAllocation(0);
+    expect(() => engine.history.undo()).toThrow('generated cache allocation failed');
+    expect(engine.document.getDocument()).toEqual(committed);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    faults.armDraw(0);
+    expect(() => engine.history.redo()).toThrow('generated cache draw failed');
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    engine.history.redo();
+    expect(engine.document.getDocument()).toEqual(committed);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps copy redo retryable, absent, and selection-exact when detached cache preparation fails', async () => {
+    const source = workflowRaster();
+    const selected = workflowRaster('selected');
+    const document = { ...workflowDocument([source, selected]), selectedLayerId: selected.id };
+    const faults = createGeneratedFaultBackend();
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: faults.backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    const result = await engine.layers.commitGeneratedImageResult({
+      guard: exported.guard,
+      image: generatedImage,
+      origin: generatedOrigin,
+      target: 'copy-raster',
+    });
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed workflow copy');
+    }
+    const committed = structuredClone(engine.document.getDocument()!);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()).toEqual(document);
+    faults.armAllocation(0);
+    expect(() => engine.history.redo()).toThrow('generated cache allocation failed');
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(selected.id);
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === result.layerId)).toBe(false);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    engine.history.redo();
+    expect(engine.document.getDocument()).toEqual(committed);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('reloads a replaced generated image from its durable bitmap contract', async () => {
+    const source = workflowRaster();
+    const { projectId, store } = createReducerBackedStore(workflowDocument([source]));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels(source.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an exportable workflow source');
+    }
+    await expect(
+      engine.layers.commitGeneratedImageResult({
+        guard: exported.guard,
+        image: generatedImage,
+        origin: generatedOrigin,
+        target: 'replace',
+      })
+    ).resolves.toEqual({ layerId: source.id, status: 'committed' });
+    const reloadedDocument = structuredClone(engine.document.getDocument()!);
+    engine.lifecycle.dispose();
+
+    const reloadedStore = createReducerBackedStore(reloadedDocument);
+    const resolver = vi.fn(() => Promise.resolve(new Blob()));
+    const reloadedEngine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: resolver,
+      projectId: reloadedStore.projectId,
+      store: reloadedStore.store,
+    });
+    expect((await reloadedEngine.exports.exportLayerPixels(source.id)).status).toBe('ok');
+    expect(resolver).toHaveBeenCalledWith(generatedImage.imageName, expect.any(AbortSignal));
+    reloadedEngine.lifecycle.dispose();
+  });
+});
+
+describe('replaceSelectionFromImage', () => {
+  const resultImage = { height: 10, imageName: 'sam-result.png', width: 10 };
+  const resultRect = { height: 10, width: 10, x: -7, y: 13 };
+
+  const sourceLayer = (): CanvasRasterLayerContractV2 => ({
+    blendMode: 'normal',
+    id: 'sam-source',
+    isEnabled: true,
+    isLocked: false,
+    name: 'SAM source',
+    opacity: 1,
+    source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: -7, y: 13 },
+    type: 'raster',
+  });
+
+  const sourceDocument = (layer: CanvasLayerContract = sourceLayer()): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers: [layer],
+    selectedLayerId: layer.id,
+    version: 2,
+    width: 100,
+  });
+
+  const alphaBackend = (alpha: number): StubRasterBackend => {
+    const base = createTestStubRasterBackend();
+    return {
+      ...base,
+      createSurface: (width, height) => {
+        const surface = base.createSurface(width, height);
+        Object.defineProperty(surface.ctx, 'getImageData', {
+          value: (_x: number, _y: number, readWidth: number, readHeight: number) => {
+            const data = new Uint8ClampedArray(readWidth * readHeight * 4);
+            for (let index = 3; index < data.length; index += 4) {
+              data[index] = alpha;
+            }
+            return { colorSpace: 'srgb', data, height: readHeight, width: readWidth } as ImageData;
+          },
+        });
+        return surface;
+      },
+    };
+  };
+
+  const createHarness = async ({
+    alpha = 0,
+    backend = alphaBackend(alpha),
+    imageResolver = () => Promise.resolve(new Blob()),
+    seedSelection = true,
+  }: {
+    alpha?: number;
+    backend?: StubRasterBackend;
+    imageResolver?: (imageName: string, signal?: AbortSignal) => Promise<Blob>;
+    seedSelection?: boolean;
+  } = {}) => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const layer = sourceLayer();
+    const document = sourceDocument(layer);
+    const reactive = createReactiveStore(document);
+    const engine = createCanvasEngine({ backend, imageResolver, projectId: 'p1', store: reactive.store });
+    const exported = await engine.exports.exportLayerPixels(layer.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an export guard');
+    }
+    if (seedSelection) {
+      engine.selection.selectAll();
+    }
+    (reactive.store.dispatch as Mock).mockClear();
+    return { ...reactive, document, engine, guard: exported.guard, layer };
+  };
+
+  const createPendingHarness = async () => {
+    const decoded = createDeferred<Blob>();
+    const harness = await createHarness({ imageResolver: () => decoded.promise });
+    const pending = harness.engine.selection.replaceSelectionFromImage(harness.guard, resultImage, resultRect);
+    return { ...harness, decoded, pending };
+  };
+
+  it('decodes and places a non-empty alpha result into the transient selection', async () => {
+    const imageResolver = vi.fn((_imageName: string, _signal?: AbortSignal) => Promise.resolve(new Blob()));
+    const harness = await createHarness({ alpha: 255, imageResolver, seedSelection: false });
+
+    await expect(
+      harness.engine.selection.replaceSelectionFromImage(harness.guard, resultImage, resultRect)
+    ).resolves.toEqual({
+      status: 'selected',
+    });
+    expect(imageResolver).toHaveBeenCalledWith(resultImage.imageName, undefined);
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('reports selected when a has-selection observer throws after the replacement is applied', async () => {
+    const harness = await createHarness({ alpha: 255, seedSelection: false });
+    const unsubscribeFault = harness.engine.stores.hasSelection.subscribe(() => {
+      throw new Error('selection state observer failed');
+    });
+
+    await expect(
+      harness.engine.selection.replaceSelectionFromImage(harness.guard, resultImage, resultRect)
+    ).resolves.toEqual({
+      status: 'selected',
+    });
+
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    unsubscribeFault();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('reports selected and clears derived selection state for an empty mask without clearing the prior surface', async () => {
+    const base = alphaBackend(0);
+    const surfaces: StubRasterSurface[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (width, height) => {
+        const surface = base.createSurface(width, height);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const harness = await createHarness({ backend });
+    const priorMask = surfaces.at(-1);
+    if (!priorMask) {
+      throw new Error('expected a seeded selection surface');
+    }
+    const priorMaskClear = vi.fn(() => {
+      throw new Error('prior selection surface must not be cleared');
+    });
+    Object.defineProperty(priorMask.ctx, 'clearRect', { value: priorMaskClear });
+
+    await expect(
+      harness.engine.selection.replaceSelectionFromImage(harness.guard, resultImage, resultRect)
+    ).resolves.toEqual({
+      status: 'selected',
+    });
+
+    expect(priorMaskClear).not.toHaveBeenCalled();
+    expect(harness.engine.stores.hasSelection.get()).toBe(false);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('closes the decoded bitmap and preserves selection when replacement-surface allocation fails', async () => {
+    const base = alphaBackend(255);
+    const close = vi.fn();
+    let failAllocation = false;
+    const backend: StubRasterBackend = {
+      ...base,
+      createImageBitmap: vi.fn(() =>
+        Promise.resolve({ close, height: resultImage.height, width: resultImage.width } as unknown as ImageBitmap)
+      ),
+      createSurface: (width, height) => {
+        if (failAllocation) {
+          throw new Error('selection surface allocation failed');
+        }
+        return base.createSurface(width, height);
+      },
+    };
+    const harness = await createHarness({ backend });
+    failAllocation = true;
+
+    await expect(
+      harness.engine.selection.replaceSelectionFromImage(harness.guard, resultImage, resultRect)
+    ).resolves.toEqual({
+      message: 'selection surface allocation failed',
+      status: 'failed',
+    });
+
+    expect(close).toHaveBeenCalledOnce();
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns aborted before decode without touching the existing selection', async () => {
+    const imageResolver = vi.fn(() => Promise.resolve(new Blob()));
+    const harness = await createHarness({ imageResolver });
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      harness.engine.selection.replaceSelectionFromImage(harness.guard, resultImage, resultRect, controller.signal)
+    ).resolves.toEqual({ status: 'aborted' });
+    expect(imageResolver).not.toHaveBeenCalled();
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns aborted when cancellation lands during image resolution', async () => {
+    const decoded = createDeferred<Blob>();
+    const harness = await createHarness({ imageResolver: () => decoded.promise });
+    const controller = new AbortController();
+
+    const pending = harness.engine.selection.replaceSelectionFromImage(
+      harness.guard,
+      resultImage,
+      resultRect,
+      controller.signal
+    );
+    controller.abort();
+    decoded.resolve(new Blob());
+
+    await expect(pending).resolves.toEqual({ status: 'aborted' });
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns aborted and closes the bitmap when cancellation lands during bitmap decode', async () => {
+    const bitmap = createDeferred<ImageBitmap>();
+    const close = vi.fn();
+    const backend = { ...alphaBackend(0), createImageBitmap: vi.fn(() => bitmap.promise) };
+    const harness = await createHarness({ backend });
+    const controller = new AbortController();
+
+    const pending = harness.engine.selection.replaceSelectionFromImage(
+      harness.guard,
+      resultImage,
+      resultRect,
+      controller.signal
+    );
+    await vi.waitFor(() => expect(backend.createImageBitmap).toHaveBeenCalledOnce());
+    controller.abort();
+    bitmap.resolve({ close, height: 10, width: 10 } as unknown as ImageBitmap);
+
+    await expect(pending).resolves.toEqual({ status: 'aborted' });
+    expect(close).toHaveBeenCalledOnce();
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns failed on decode failure without touching the existing selection', async () => {
+    const harness = await createHarness({ imageResolver: () => Promise.reject(new Error('SAM decode failed')) });
+
+    await expect(
+      harness.engine.selection.replaceSelectionFromImage(harness.guard, resultImage, resultRect)
+    ).resolves.toEqual({
+      message: 'SAM decode failed',
+      status: 'failed',
+    });
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it.each([
+    {
+      expected: 'missing',
+      label: 'source deletion',
+      mutate: (harness: Awaited<ReturnType<typeof createHarness>>) =>
+        harness.setDocument({ ...harness.document, layers: [] }),
+    },
+    {
+      expected: 'stale',
+      label: 'source contract edit',
+      mutate: (harness: Awaited<ReturnType<typeof createHarness>>) =>
+        harness.setDocument({ ...harness.document, layers: [{ ...harness.layer, opacity: 0.5 }] }),
+    },
+    {
+      expected: 'locked',
+      label: 'source lock',
+      mutate: (harness: Awaited<ReturnType<typeof createHarness>>) =>
+        harness.setDocument({ ...harness.document, layers: [{ ...harness.layer, isLocked: true }] }),
+    },
+    {
+      expected: 'unsupported',
+      label: 'source type change',
+      mutate: (harness: Awaited<ReturnType<typeof createHarness>>) => {
+        const { source: _source, ...base } = harness.layer;
+        const mask: CanvasInpaintMaskLayerContract = {
+          ...base,
+          mask: { bitmap: null, fill: { color: '#fff', style: 'solid' } },
+          type: 'inpaint_mask',
+        };
+        harness.setDocument({ ...harness.document, layers: [mask] });
+      },
+    },
+    {
+      expected: 'stale',
+      label: 'document replacement reusing the layer',
+      mutate: (harness: Awaited<ReturnType<typeof createHarness>>) => harness.setDocument({ ...harness.document }, 1),
+    },
+  ] as const)('refuses $label without mutating the selection', async ({ expected, mutate }) => {
+    const harness = await createPendingHarness();
+    mutate(harness);
+    const selectionAfterExternalChange = harness.engine.stores.hasSelection.get();
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: expected });
+    expect(harness.engine.stores.hasSelection.get()).toBe(selectionAfterExternalChange);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns busy for an open pointer gesture without mutating the selection', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const harness = await createPendingHarness();
+    const screen = createInputCanvas();
+    const overlay = createInputCanvas();
+    harness.engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    overlay.fire('pointerdown', pointerAt(5, 5));
+    harness.decoded.resolve(new Blob());
+
+    await expect(harness.pending).resolves.toEqual({ status: 'busy' });
+    expect(harness.engine.stores.hasSelection.get()).toBe(true);
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns stale after an unpersisted paint-cache edit without mutating the selection', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const decoded = createDeferred<Blob>();
+    const document = paintDoc();
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: alphaBackend(0),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => decoded.promise,
+      projectId,
+      store,
+    });
+    const screen = createInputCanvas();
+    const overlay = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(5, 5));
+    overlay.fire('pointermove', pointerAt(8, 8));
+    overlay.fire('pointerup', pointerAt(8, 8, { buttons: 0 }));
+    const exported = await engine.exports.exportLayerPixels('paint1');
+    if (exported.status !== 'ok') {
+      throw new Error('expected live paint pixels');
+    }
+    engine.selection.selectAll();
+    const pending = engine.selection.replaceSelectionFromImage(exported.guard, resultImage, resultRect);
+
+    overlay.fire('pointerdown', pointerAt(15, 15));
+    overlay.fire('pointermove', pointerAt(18, 18));
+    overlay.fire('pointerup', pointerAt(18, 18, { buttons: 0 }));
+    decoded.resolve(new Blob());
+
+    await expect(pending).resolves.toEqual({ status: 'stale' });
+    expect(engine.stores.hasSelection.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('commitMaskImageResult', () => {
+  const resultImage = { height: 12, imageName: 'durable-sam-result.png', width: 16 };
+  const resultRect = { height: 12, width: 16, x: -5, y: 7 };
+
+  const source = (): CanvasRasterLayerContractV2 => ({
+    blendMode: 'normal',
+    id: 'source',
+    isEnabled: true,
+    isLocked: false,
+    name: 'Source',
+    opacity: 1,
+    source: { fill: '#fff', height: 12, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 16 },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: -5, y: 7 },
+    type: 'raster',
+  });
+
+  const existingInpaint = (): CanvasInpaintMaskLayerContract => ({
+    blendMode: 'normal',
+    id: 'existing-mask',
+    isEnabled: true,
+    isLocked: false,
+    mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+    name: 'Inpaint Mask 1',
+    opacity: 1,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'inpaint_mask',
+  });
+
+  const existingRegional = (): CanvasLayerContract => ({
+    autoNegative: false,
+    blendMode: 'normal',
+    id: 'existing-region',
+    isEnabled: true,
+    isLocked: false,
+    mask: { bitmap: null, fill: { color: '#83d683', style: 'solid' } },
+    name: 'Regional Guidance 1',
+    negativePrompt: null,
+    opacity: 0.5,
+    positivePrompt: null,
+    referenceImages: [],
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'regional_guidance',
+  });
+
+  const docFor = (target: 'inpaint_mask' | 'regional_guidance'): CanvasDocumentContractV2 => {
+    const layer = source();
+    const below = { ...source(), id: 'below', name: 'Below' };
+    return {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [target === 'inpaint_mask' ? existingInpaint() : existingRegional(), layer, below],
+      selectedLayerId: below.id,
+      version: 2,
+      width: 100,
+    };
+  };
+
+  it.each([
+    {
+      expected: {
+        blendMode: 'normal',
+        isEnabled: true,
+        isLocked: false,
+        mask: {
+          bitmap: resultImage,
+          fill: { color: '#e07575', style: 'diagonal' },
+          offset: { x: -5, y: 7 },
+        },
+        name: 'Inpaint Mask 2',
+        opacity: 1,
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        type: 'inpaint_mask',
+      },
+      target: 'inpaint_mask',
+    },
+    {
+      expected: {
+        autoNegative: false,
+        blendMode: 'normal',
+        isEnabled: true,
+        isLocked: false,
+        mask: {
+          bitmap: resultImage,
+          fill: { color: '#fae150', style: 'solid' },
+          offset: { x: -5, y: 7 },
+        },
+        name: 'Regional Guidance 2',
+        negativePrompt: null,
+        opacity: 0.5,
+        positivePrompt: null,
+        referenceImages: [],
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        type: 'regional_guidance',
+      },
+      target: 'regional_guidance',
+    },
+  ] as const)(
+    'adds a complete $target directly above the source with one exact history entry',
+    async ({ expected, target }) => {
+      const document = docFor(target);
+      const { projectId, store } = createReducerBackedStore(document);
+      const bitmapStore = createSpyBitmapStore();
+      const imageResolver = vi.fn(() => Promise.resolve(new Blob()));
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore,
+        imageResolver,
+        projectId,
+        store,
+      });
+      const exported = await engine.exports.exportLayerPixels('source');
+      if (exported.status !== 'ok') {
+        throw new Error('expected an export guard');
+      }
+
+      const result = await engine.layers.commitMaskImageResult({
+        guard: exported.guard,
+        image: resultImage,
+        rect: resultRect,
+        target,
+      });
+
+      expect(result.status).toBe('committed');
+      if (result.status !== 'committed') {
+        throw new Error('expected a committed mask');
+      }
+      const created = engine.document.getDocument()!.layers.find((layer) => layer.id === result.layerId)!;
+      expect(created).toEqual({ ...expected, id: result.layerId });
+      expect(engine.document.getDocument()!.layers.map((layer) => layer.id)).toEqual([
+        document.layers[0]!.id,
+        result.layerId,
+        'source',
+        'below',
+      ]);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+      expect(imageResolver).not.toHaveBeenCalled();
+      expect(bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+      expect(engine.stores.canUndo.get()).toBe(true);
+
+      engine.history.undo();
+      expect(engine.document.getDocument()).toEqual(document);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe('below');
+      expect(engine.stores.canUndo.get()).toBe(false);
+      expect(engine.stores.canRedo.get()).toBe(true);
+
+      engine.history.redo();
+      expect(engine.document.getDocument()!.layers.find((layer) => layer.id === result.layerId)).toEqual(created);
+      expect(engine.document.getDocument()!.selectedLayerId).toBe(result.layerId);
+      expect(engine.stores.canUndo.get()).toBe(true);
+      expect(engine.stores.canRedo.get()).toBe(false);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('commits and refreshes the document mirror when an earlier observer throws after the reducer adds the mask', async () => {
+    const document = docFor('inpaint_mask');
+    const { projectId, store } = createReducerBackedStore(document);
+    const unsubscribeFault = store.subscribe(() => {
+      throw new Error('earlier mask observer failed');
+    });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('source');
+    if (exported.status !== 'ok') {
+      throw new Error('expected an export guard');
+    }
+
+    const result = await engine.layers.commitMaskImageResult({
+      guard: exported.guard,
+      image: resultImage,
+      rect: resultRect,
+      target: 'inpaint_mask',
+    });
+    unsubscribeFault();
+
+    expect(result.status).toBe('committed');
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed mask');
+    }
+    expect(engine.document.getDocument()).toBe(
+      store.getState().projects.find((project) => project.id === projectId)!.canvas.document
+    );
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === result.layerId)).toBe(true);
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()).toEqual(document);
+    engine.lifecycle.dispose();
+  });
+
+  it('finishes mask undo exactly when document observers throw after both reducer mutations', async () => {
+    const document = docFor('regional_guidance');
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('source');
+    if (exported.status !== 'ok') {
+      throw new Error('expected an export guard');
+    }
+    const result = await engine.layers.commitMaskImageResult({
+      guard: exported.guard,
+      image: resultImage,
+      rect: resultRect,
+      target: 'regional_guidance',
+    });
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed mask');
+    }
+    const unsubscribeFault = store.subscribe(() => {
+      throw new Error('mask undo observer failed');
+    });
+
+    expect(() => engine.history.undo()).not.toThrow();
+
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe('below');
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+    unsubscribeFault();
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps mask undo failure-atomic when restoring the prior selection fails before reducer application', async () => {
+    const document = docFor('inpaint_mask');
+    const { dispatch, projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('source');
+    if (exported.status !== 'ok') {
+      throw new Error('expected an export guard');
+    }
+    const result = await engine.layers.commitMaskImageResult({
+      guard: exported.guard,
+      image: resultImage,
+      rect: resultRect,
+      target: 'inpaint_mask',
+    });
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed mask');
+    }
+    const committedDocument = structuredClone(engine.document.getDocument()!);
+    const reducerDispatch = dispatch.getMockImplementation();
+    if (!reducerDispatch) {
+      throw new Error('expected reducer-backed dispatch');
+    }
+    let failSelection = true;
+    dispatch.mockImplementation((action: EngineTestAction) => {
+      if (failSelection && action.type === 'setCanvasSelectedLayer') {
+        failSelection = false;
+        throw new Error('mask selection restore failed');
+      }
+      reducerDispatch(action);
+    });
+
+    expect(() => engine.history.undo()).toThrow('mask selection restore failed');
+
+    expect(engine.document.getDocument()).toEqual(committedDocument);
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps mask undo retryable when removal fails after restoring the prior selection', async () => {
+    const document = docFor('regional_guidance');
+    const { dispatch, projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('source');
+    if (exported.status !== 'ok') {
+      throw new Error('expected an export guard');
+    }
+    const result = await engine.layers.commitMaskImageResult({
+      guard: exported.guard,
+      image: resultImage,
+      rect: resultRect,
+      target: 'regional_guidance',
+    });
+    if (result.status !== 'committed') {
+      throw new Error('expected a committed mask');
+    }
+    const reducerDispatch = dispatch.getMockImplementation();
+    if (!reducerDispatch) {
+      throw new Error('expected reducer-backed dispatch');
+    }
+    let failRemoval = true;
+    dispatch.mockImplementation((action: EngineTestAction) => {
+      if (failRemoval && action.type === 'removeCanvasLayers') {
+        failRemoval = false;
+        throw new Error('mask removal failed');
+      }
+      reducerDispatch(action);
+    });
+
+    expect(() => engine.history.undo()).toThrow('mask removal failed');
+
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === result.layerId)).toBe(true);
+    expect(engine.document.getDocument()!.selectedLayerId).toBe('below');
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(engine.stores.canRedo.get()).toBe(false);
+
+    engine.history.undo();
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(engine.stores.canUndo.get()).toBe(false);
+    expect(engine.stores.canRedo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  const guardHarness = async () => {
+    const layer = source();
+    const document: CanvasDocumentContractV2 = { ...docFor('inpaint_mask'), layers: [layer] };
+    const reactive = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store: reactive.store,
+    });
+    const exported = await engine.exports.exportLayerPixels(layer.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected an export guard');
+    }
+    (reactive.store.dispatch as Mock).mockClear();
+    return { ...reactive, document, engine, guard: exported.guard, layer };
+  };
+
+  it('returns aborted before any mask mutation', async () => {
+    const harness = await guardHarness();
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      harness.engine.layers.commitMaskImageResult({
+        guard: harness.guard,
+        image: resultImage,
+        rect: resultRect,
+        signal: controller.signal,
+        target: 'inpaint_mask',
+      })
+    ).resolves.toEqual({ status: 'aborted' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it.each([
+    {
+      expected: 'missing',
+      label: 'source deletion',
+      mutate: (harness: Awaited<ReturnType<typeof guardHarness>>) =>
+        harness.setDocument({ ...harness.document, layers: [] }),
+    },
+    {
+      expected: 'stale',
+      label: 'source contract edit',
+      mutate: (harness: Awaited<ReturnType<typeof guardHarness>>) =>
+        harness.setDocument({ ...harness.document, layers: [{ ...harness.layer, opacity: 0.4 }] }),
+    },
+    {
+      expected: 'locked',
+      label: 'source lock',
+      mutate: (harness: Awaited<ReturnType<typeof guardHarness>>) =>
+        harness.setDocument({ ...harness.document, layers: [{ ...harness.layer, isLocked: true }] }),
+    },
+    {
+      expected: 'unsupported',
+      label: 'source type change',
+      mutate: (harness: Awaited<ReturnType<typeof guardHarness>>) => {
+        const { source: _source, ...base } = harness.layer;
+        const mask: CanvasInpaintMaskLayerContract = {
+          ...base,
+          mask: { bitmap: null, fill: { color: '#fff', style: 'solid' } },
+          type: 'inpaint_mask',
+        };
+        harness.setDocument({ ...harness.document, layers: [mask] });
+      },
+    },
+    {
+      expected: 'stale',
+      label: 'document replacement',
+      mutate: (harness: Awaited<ReturnType<typeof guardHarness>>) => harness.setDocument({ ...harness.document }, 1),
+    },
+    {
+      expected: 'stale',
+      label: 'cache invalidation',
+      mutate: (harness: Awaited<ReturnType<typeof guardHarness>>) => harness.engine.diagnostics.clearCaches(),
+    },
+  ] as const)('refuses $label without adding a mask or history', async ({ expected, mutate }) => {
+    const harness = await guardHarness();
+    await mutate(harness);
+
+    await expect(
+      harness.engine.layers.commitMaskImageResult({
+        guard: harness.guard,
+        image: resultImage,
+        rect: resultRect,
+        target: 'regional_guidance',
+      })
+    ).resolves.toEqual({ status: expected });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('returns busy during an open pointer gesture without adding a mask', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const harness = await guardHarness();
+    const screen = createInputCanvas();
+    const overlay = createInputCanvas();
+    harness.engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    overlay.fire('pointerdown', pointerAt(5, 5));
+
+    await expect(
+      harness.engine.layers.commitMaskImageResult({
+        guard: harness.guard,
+        image: resultImage,
+        rect: resultRect,
+        target: 'inpaint_mask',
+      })
+    ).resolves.toEqual({ status: 'busy' });
+    expect(harness.store.dispatch).not.toHaveBeenCalled();
+    expect(harness.engine.stores.canUndo.get()).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+});
+
+describe('guarded filter previews', () => {
+  const spandrelModel = {
+    base: 'any',
+    hash: 'hash',
+    key: 'upscaler',
+    name: 'Upscaler',
+    type: 'spandrel_image_to_image',
+  };
+  const emptyDoc = (): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers: [],
+    selectedLayerId: null,
+    version: 2,
+    width: 100,
+  });
+
+  /**
+   * A layer that can be added/removed from the document to drive the mirror's
+   * `onLayersChanged`/`onDocumentReplaced` callbacks, without itself consuming a
+   * `createImageBitmap` call — a `bitmap: null` paint source rasterizes
+   * synchronously (a clear), unlike an image source, so it can't shift the call
+   * ordering the pruning tests rely on to target a SPECIFIC filter-preview decode.
+   */
+  const previewableLayer = (id: string): CanvasLayerContract => ({
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name: id,
+    opacity: 1,
+    source: { bitmap: null, type: 'paint' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'raster',
+  });
+
+  const guardableLayer = (id: string): CanvasRasterLayerContractV2 => ({
+    ...(previewableLayer(id) as CanvasRasterLayerContractV2),
+    source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+  });
+
+  const filterBitmapBackend = (width = 10, height = 10): StubRasterBackend => ({
+    ...createTestStubRasterBackend(),
+    createImageBitmap: () => Promise.resolve({ close: () => undefined, height, width } as unknown as ImageBitmap),
+  });
+
+  it('auto-processes a debounced preview after a filter draft update', async () => {
+    const layer = guardableLayer('auto-filter');
+    const { store } = createReactiveStore({ ...emptyDoc(), layers: [layer] });
+    const runGraph = vi.fn(() =>
+      Promise.resolve({ height: 10, imageName: 'auto.png', origin: 'test', output: {}, width: 10 })
+    );
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      filterDeps: { runGraph, uploadIntermediate: () => Promise.resolve({ imageName: 'input.png' }) },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(layer.id)).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation(layer.id)).toBe('started');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      autoProcess: true,
+      status: 'ready',
+    });
+
+    getCanvasOperations(engine).updateFilterOperation({
+      settings: { high_threshold: 210, low_threshold: 90 },
+      type: 'canny_edge_detection',
+    });
+    expect(runGraph).not.toHaveBeenCalled();
+    await vi.waitFor(
+      () =>
+        expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+          preview: { imageName: 'auto.png' },
+          status: 'ready',
+        }),
+      { timeout: 3000 }
+    );
+    expect(runGraph).toHaveBeenCalledOnce();
+    engine.lifecycle.dispose();
+  });
+
+  it('setFilterOperationAutoProcess toggles the session and stops auto-runs', async () => {
+    const layer = guardableLayer('auto-filter-toggle');
+    const { store } = createReactiveStore({ ...emptyDoc(), layers: [layer] });
+    const runGraph = vi.fn(() =>
+      Promise.resolve({ height: 10, imageName: 'auto.png', origin: 'test', output: {}, width: 10 })
+    );
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      filterDeps: { runGraph, uploadIntermediate: () => Promise.resolve({ imageName: 'input.png' }) },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(layer.id)).status).toBe('ok');
+
+    expect(getCanvasOperations(engine).setFilterOperationAutoProcess(false)).toBe('stale');
+
+    expect(getCanvasOperations(engine).startFilterOperation(layer.id)).toBe('started');
+    expect(getCanvasOperations(engine).setFilterOperationAutoProcess(false)).toBe('updated');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({ autoProcess: false });
+
+    getCanvasOperations(engine).updateFilterOperation({
+      settings: { high_threshold: 210, low_threshold: 90 },
+      type: 'canny_edge_detection',
+    });
+    await new Promise((resolve) => {
+      setTimeout(resolve, FILTER_AUTO_PROCESS_DEBOUNCE_MS + 200);
+    });
+    expect(runGraph).not.toHaveBeenCalled();
+
+    engine.tools.setInteractionLocked(true);
+    expect(getCanvasOperations(engine).setFilterOperationAutoProcess(true)).toBe('blocked');
+    engine.lifecycle.dispose();
+  });
+
+  it('clears the session and ends the operation after a committed filter commit', async () => {
+    const source = guardableLayer('commit-clear');
+    const document = { ...emptyDoc(), layers: [source], selectedLayerId: source.id };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      filterDeps: {
+        runGraph: () => Promise.resolve({ height: 10, imageName: 'out.png', origin: 'test', output: {}, width: 10 }),
+        uploadIntermediate: () => Promise.resolve({ imageName: 'input.png' }),
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(source.id)).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation(source.id)).toBe('started');
+    await expect(getCanvasOperations(engine).processFilterOperation()).resolves.toBe('completed');
+
+    await expect(getCanvasOperations(engine).commitFilterOperation('apply', () => Promise.resolve())).resolves.toBe(
+      'committed'
+    );
+
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(getCanvasOperations(engine).startFilterOperation(source.id)).toBe('started');
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['apply', 'raster'] as const)(
+    'rejects a decoded dimension mismatch for canny %s without scaling, then retries successfully',
+    async (target) => {
+      const source = guardableLayer('dimension-source');
+      const document = { ...emptyDoc(), layers: [source], selectedLayerId: source.id };
+      const { projectId, store } = createReducerBackedStore(document);
+      const base = createTestStubRasterBackend();
+      const decodedDimensions = [
+        { height: 10, width: 9 },
+        { height: 10, width: 10 },
+        { height: 9, width: 10 },
+        { height: 10, width: 10 },
+      ];
+      const decodedBitmaps: ImageBitmap[] = [];
+      const surfaces: StubRasterSurface[] = [];
+      const backend: StubRasterBackend = {
+        ...base,
+        createImageBitmap: () => {
+          const dimensions = decodedDimensions.shift();
+          if (!dimensions) {
+            throw new Error('unexpected filter decode');
+          }
+          const bitmap = { ...dimensions, close: vi.fn(), decodedFilter: true } as unknown as ImageBitmap;
+          decodedBitmaps.push(bitmap);
+          return Promise.resolve(bitmap);
+        },
+        createSurface: (width, height) => {
+          const surface = base.createSurface(width, height);
+          surfaces.push(surface);
+          return surface;
+        },
+      };
+      const engine = createCanvasEngine({
+        backend,
+        bitmapStore: createSpyBitmapStore(),
+        filterDeps: {
+          runGraph: () =>
+            Promise.resolve({ height: 10, imageName: 'canny.png', origin: 'test', output: {}, width: 10 }),
+          uploadIntermediate: () => Promise.resolve({ imageName: 'input.png' }),
+        },
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      expect((await engine.exports.exportLayerPixels(source.id)).status).toBe('ok');
+      expect(getCanvasOperations(engine).startFilterOperation(source.id)).toBe('started');
+
+      await expect(getCanvasOperations(engine).processFilterOperation()).resolves.toBe('stale');
+      expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+        error: 'Canny Edge Detection output dimensions 9x10 do not match source dimensions 10x10.',
+        preview: null,
+        status: 'error',
+      });
+      expect(engine.document.getDocument()).toEqual(document);
+
+      await expect(getCanvasOperations(engine).processFilterOperation()).resolves.toBe('completed');
+      await expect(getCanvasOperations(engine).commitFilterOperation(target, () => Promise.resolve())).resolves.toBe(
+        'stale'
+      );
+      expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+        error: 'Canny Edge Detection output dimensions 10x9 do not match source dimensions 10x10.',
+        preview: { imageName: 'canny.png' },
+        status: 'error',
+      });
+      expect(engine.document.getDocument()).toEqual(document);
+
+      await expect(getCanvasOperations(engine).commitFilterOperation(target, () => Promise.resolve())).resolves.toBe(
+        'committed'
+      );
+
+      const bitmapDraws = surfaces.flatMap((surface) =>
+        surface.callLog.filter(
+          (entry) => entry.op === 'drawImage' && decodedBitmaps.includes(entry.args[0] as ImageBitmap)
+        )
+      );
+      expect(bitmapDraws.length).toBeGreaterThan(0);
+      expect(bitmapDraws.every((entry) => entry.args.length === 3)).toBe(true);
+      expect(engine.document.getDocument()?.layers).toHaveLength(target === 'apply' ? 1 : 2);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('interaction lock blocks Filter and Select Object launches without creating sessions', async () => {
+    const layer = guardableLayer('locked-launch');
+    const { store } = createReactiveStore({ ...emptyDoc(), layers: [layer] });
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(layer.id)).status).toBe('ok');
+
+    engine.tools.setInteractionLocked(true);
+
+    expect(getCanvasOperations(engine).startFilterOperation(layer.id)).toBe('locked');
+    expect(getCanvasOperations(engine).startSelectObject(layer.id)).toBe('locked');
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    expect(getCanvasOperations(engine).stores.samSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('keeps an active Select Object operation available to cancel while interaction is locked', async () => {
+    const layer = guardableLayer('active-before-lock');
+    const { store } = createReactiveStore({ ...emptyDoc(), layers: [layer] });
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(layer.id)).status).toBe('ok');
+    expect(getCanvasOperations(engine).startSelectObject(layer.id)).toBe('started');
+
+    engine.tools.setInteractionLocked(true);
+
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'select-object' },
+      status: 'active',
+    });
+    expect(getCanvasOperations(engine).stores.samSession.get()).not.toBeNull();
+    expect(engine.stores.activeTool.get()).toBe('view');
+
+    getCanvasOperations(engine).cancelSelectObjectSession();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(getCanvasOperations(engine).stores.samSession.get()).toBeNull();
+
+    engine.tools.setInteractionLocked(false);
+    expect(engine.stores.activeTool.get()).toBe('view');
+    engine.lifecycle.dispose();
+  });
+
+  /** A stub backend whose `createImageBitmap` is deferred, so decodes resolve on demand. */
+  const createDeferredBitmapBackend = () => {
+    const base = createTestStubRasterBackend();
+    const deferreds: ReturnType<typeof createDeferred<ImageBitmap>>[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createImageBitmap: () => {
+        const deferred = createDeferred<ImageBitmap>();
+        deferreds.push(deferred);
+        return deferred.promise;
+      },
+    };
+    return {
+      backend,
+      resolveBitmap: (index: number): void =>
+        deferreds[index]!.resolve({ close: () => {}, height: 0, width: 0 } as unknown as ImageBitmap),
+    };
+  };
+
+  it('publishes a guarded filter preview while the exported layer snapshot remains current', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+
+    const pending = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'filtered', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+    bitmaps.resolveBitmap(0);
+
+    await expect(pending).resolves.toBe('shown');
+    engine.lifecycle.dispose();
+  });
+
+  it('owns a guarded filter session independently of the launching view', async () => {
+    const layer = { ...guardableLayer('L'), filter: { settings: { radius: 2 }, type: 'content_shuffle' } };
+    const document = { ...emptyDoc(), layers: [layer] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      filterDeps: {
+        runGraph: vi.fn(() =>
+          Promise.resolve({ height: 10, imageName: 'filtered', origin: 'canvas', output: {}, width: 10 })
+        ),
+        uploadIntermediate: vi.fn(() => Promise.resolve({ imageName: 'input' })),
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('L')).status).toBe('ok');
+
+    expect(getCanvasOperations(engine).startFilterOperation('L')).toBe('started');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      draft: layer.filter,
+      initialFilter: layer.filter,
+      layerId: 'L',
+      layerName: layer.name,
+      layerType: 'raster',
+      status: 'ready',
+    });
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'filter', layerId: 'L', projectId: 'p1' },
+      status: 'active',
+    });
+    await getCanvasOperations(engine).processFilterOperation();
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      preview: { imageName: 'filtered' },
+      status: 'ready',
+    });
+
+    engine.lifecycle.dispose();
+  });
+
+  it('starts an unfiltered layer with a recommendation but preserves an existing manual filter and Cancel', async () => {
+    const unfiltered = guardableLayer('recommended');
+    const manual = {
+      ...guardableLayer('manual'),
+      filter: { settings: { coarse: true }, type: 'lineart_edge_detection' },
+    };
+    const document = { ...emptyDoc(), layers: [unfiltered, manual] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('recommended')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation('recommended', 'normal_map')).toBe('started');
+    expect(getCanvasOperations(engine).stores.filterSession.get()?.draft).toEqual({ settings: {}, type: 'normal_map' });
+    getCanvasOperations(engine).cancelFilterOperation();
+    expect(engine.document.getDocument()).toEqual({ ...document, selectedLayerId: 'recommended' });
+
+    expect((await engine.exports.exportLayerPixels('manual')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation('manual', 'normal_map')).toBe('not-ready');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    expect(getCanvasOperations(engine).startFilterOperation('manual')).toBe('started');
+    expect(getCanvasOperations(engine).stores.filterSession.get()?.draft).toEqual(manual.filter);
+    getCanvasOperations(engine).cancelFilterOperation();
+    expect(engine.document.getDocument()).toEqual({ ...document, selectedLayerId: 'manual' });
+    engine.lifecycle.dispose();
+  });
+
+  it('does not replace another layer filter session with a recommendation', async () => {
+    const first = guardableLayer('first');
+    const second = guardableLayer('second');
+    const document = { ...emptyDoc(), layers: [first, second] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('first')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation('first')).toBe('started');
+    getCanvasOperations(engine).updateFilterOperation({ settings: { coarse: true }, type: 'lineart_edge_detection' });
+    const active = getCanvasOperations(engine).stores.filterSession.get();
+
+    expect((await engine.exports.exportLayerPixels('second')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation('second', 'normal_map')).toBe('not-ready');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toEqual(active);
+    engine.lifecycle.dispose();
+  });
+
+  it('does not overwrite a same-layer draft or preview on rapid recommendations', async () => {
+    const layer = guardableLayer('recommended');
+    const document = { ...emptyDoc(), layers: [layer] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      filterDeps: {
+        runGraph: vi.fn(() =>
+          Promise.resolve({ height: 10, imageName: 'filtered', origin: 'canvas', output: {}, width: 10 })
+        ),
+        uploadIntermediate: vi.fn(() => Promise.resolve({ imageName: 'input' })),
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(layer.id)).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation(layer.id, 'normal_map')).toBe('started');
+    getCanvasOperations(engine).updateFilterOperation({ settings: { coarse: true }, type: 'lineart_edge_detection' });
+    await getCanvasOperations(engine).processFilterOperation();
+    const active = getCanvasOperations(engine).stores.filterSession.get();
+
+    expect(getCanvasOperations(engine).startFilterOperation(layer.id, 'canny_edge_detection')).toBe('not-ready');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toEqual(active);
+    engine.lifecycle.dispose();
+  });
+
+  it('does not replace a different active canvas operation with a recommendation', async () => {
+    const first = guardableLayer('first');
+    const second = guardableLayer('second');
+    const document = { ...emptyDoc(), layers: [first, second] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('first')).status).toBe('ok');
+    expect((await engine.exports.exportLayerPixels('second')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startSelectObject('first')).toBe('started');
+    const operation = getCanvasOperations(engine).controller.getSnapshot();
+
+    expect(getCanvasOperations(engine).startFilterOperation('second', 'normal_map')).toBe('not-ready');
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual(operation);
+    expect(getCanvasOperations(engine).stores.samSession.get()?.sourceRect).toEqual({
+      height: 10,
+      width: 10,
+      x: 0,
+      y: 0,
+    });
+    engine.lifecycle.dispose();
+  });
+
+  const filterFlowLayer = (
+    type: 'raster' | 'control'
+  ): Extract<CanvasLayerContract, { type: 'raster' | 'control' }> => {
+    const base = {
+      blendMode: 'multiply' as const,
+      filter: { settings: { radius: 2 }, type: 'content_shuffle' },
+      id: 'filter-source',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Filter source',
+      opacity: 0.6,
+      source: {
+        bitmap: { height: 10, imageName: 'filter-source.png', width: 10 },
+        offset: { x: 7, y: -3 },
+        type: 'paint' as const,
+      },
+      transform: { rotation: 12, scaleX: 2, scaleY: 3, x: 40, y: 50 },
+    };
+    return type === 'raster'
+      ? { ...base, type: 'raster' }
+      : {
+          ...base,
+          adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+          type: 'control',
+          withTransparencyEffect: true,
+        };
+  };
+
+  const createFilterFlowHarness = async (sourceType: 'raster' | 'control') => {
+    const source = filterFlowLayer(sourceType);
+    const document = { ...emptyDoc(), layers: [source], selectedLayerId: source.id };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      filterDeps: {
+        runGraph: vi.fn(() =>
+          Promise.resolve({ height: 10, imageName: 'filtered.png', origin: 'canvas', output: {}, width: 10 })
+        ),
+        uploadIntermediate: vi.fn(() => Promise.resolve({ imageName: 'filter-input.png' })),
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(source.id)).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation(source.id)).toBe('started');
+    await getCanvasOperations(engine).processFilterOperation();
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      preview: { imageName: 'filtered.png' },
+      status: 'ready',
+    });
+    return { document, engine, source };
+  };
+
+  it('blocks Filter actions called directly after an external lock and still allows Cancel', async () => {
+    const { document, engine } = await createFilterFlowHarness('raster');
+    const makeDurable = vi.fn(() => Promise.resolve());
+    const before = getCanvasOperations(engine).stores.filterSession.get();
+
+    engine.tools.setInteractionLocked(true);
+
+    expect(getCanvasOperations(engine).updateFilterOperation({ settings: { radius: 99 }, type: 'img_blur' })).toBe(
+      'blocked'
+    );
+    expect(getCanvasOperations(engine).resetFilterOperation({ radius: 0 })).toBe('blocked');
+    await expect(getCanvasOperations(engine).processFilterOperation()).resolves.toBe('blocked');
+    await expect(getCanvasOperations(engine).commitFilterOperation('apply', makeDurable)).resolves.toBe('blocked');
+    expect(makeDurable).not.toHaveBeenCalled();
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toEqual(before);
+
+    getCanvasOperations(engine).cancelFilterOperation();
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    engine.tools.setInteractionLocked(false);
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    expect(getCanvasOperations(engine).updateFilterOperation({ settings: {}, type: 'img_blur' })).toBe('stale');
+    expect(getCanvasOperations(engine).resetFilterOperation({})).toBe('stale');
+    engine.lifecycle.dispose();
+  });
+
+  it('blocks Filter mutation when an external lock begins during durability', async () => {
+    const { document, engine } = await createFilterFlowHarness('raster');
+    const durable = createDeferred<void>();
+    const pending = getCanvasOperations(engine).commitFilterOperation('apply', () => durable.promise);
+    await vi.waitFor(() => expect(getCanvasOperations(engine).stores.filterSession.get()?.status).toBe('committing'));
+
+    engine.tools.setInteractionLocked(true);
+    durable.resolve();
+
+    await expect(pending).resolves.toBe('blocked');
+    expect(engine.document.getDocument()).toEqual(document);
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      preview: { imageName: 'filtered.png' },
+      status: 'ready',
+    });
+    getCanvasOperations(engine).cancelFilterOperation();
+    engine.lifecycle.dispose();
+  });
+
+  it('interrupts Filter processing on an external lock without losing the draft or operation', async () => {
+    const source = filterFlowLayer('raster');
+    const { projectId, store } = createReducerBackedStore({
+      ...emptyDoc(),
+      layers: [source],
+      selectedLayerId: source.id,
+    });
+    const graph = createDeferred<{ height: number; imageName: string; origin: string; output: {}; width: number }>();
+    const runGraph = vi.fn(() => graph.promise);
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      filterDeps: {
+        runGraph,
+        uploadIntermediate: vi.fn(() => Promise.resolve({ imageName: 'filter-input.png' })),
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(source.id)).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation(source.id)).toBe('started');
+    expect(getCanvasOperations(engine).updateFilterOperation({ settings: { radius: 7 }, type: 'img_blur' })).toBe(
+      'updated'
+    );
+    const pending = getCanvasOperations(engine).processFilterOperation();
+    await vi.waitFor(() => expect(runGraph).toHaveBeenCalledOnce());
+
+    engine.tools.setInteractionLocked(true);
+    graph.resolve({ height: 10, imageName: 'late.png', origin: 'test', output: {}, width: 10 });
+
+    await expect(pending).resolves.toBe('stale');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      draft: { settings: { radius: 7 }, type: 'img_blur' },
+      preview: null,
+      status: 'ready',
+    });
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({ phase: 'ready', status: 'active' });
+    getCanvasOperations(engine).cancelFilterOperation();
+    engine.lifecycle.dispose();
+  });
+
+  it.each([
+    {
+      expectedRect: { height: 22, width: 22, x: 1, y: -9 },
+      output: { height: 22, width: 22 },
+      settings: { blur_type: 'gaussian', radius: 2 },
+      target: 'apply',
+      type: 'img_blur',
+    },
+    {
+      expectedRect: { height: 14, width: 14, x: 5, y: -5 },
+      output: { height: 14, width: 14 },
+      settings: { blur_type: 'box', radius: 2 },
+      target: 'raster',
+      type: 'img_blur',
+    },
+    {
+      expectedRect: { height: 30, width: 40, x: 7, y: -3 },
+      output: { height: 30, width: 40 },
+      settings: { autoScale: true, model: spandrelModel, scale: 4 },
+      target: 'control',
+      type: 'spandrel_filter',
+    },
+  ] as const)(
+    'preserves $type/$target output geometry through preview, commit, and one-entry undo/redo',
+    async ({ expectedRect, output, settings, target, type }) => {
+      const source = filterFlowLayer('raster');
+      const document = { ...emptyDoc(), layers: [source], selectedLayerId: source.id };
+      const { projectId, store } = createReducerBackedStore(document);
+      const engine = createCanvasEngine({
+        backend: filterBitmapBackend(output.width, output.height),
+        bitmapStore: createSpyBitmapStore(),
+        filterDeps: {
+          runGraph: vi.fn(() =>
+            Promise.resolve({ ...output, imageName: 'filtered.png', origin: 'canvas', output: {} })
+          ),
+          uploadIntermediate: vi.fn(() => Promise.resolve({ imageName: 'filter-input.png' })),
+        },
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      expect((await engine.exports.exportLayerPixels(source.id)).status).toBe('ok');
+      expect(getCanvasOperations(engine).startFilterOperation(source.id)).toBe('started');
+      getCanvasOperations(engine).updateFilterOperation({ settings: structuredClone(settings), type });
+
+      await getCanvasOperations(engine).processFilterOperation();
+      expect(getCanvasOperations(engine).stores.filterSession.get()?.preview?.rect).toEqual(expectedRect);
+      await getCanvasOperations(engine).commitFilterOperation(target, () => Promise.resolve());
+
+      const committedId = target === 'apply' ? source.id : engine.document.getDocument()!.layers[0]!.id;
+      const committed = engine.document.getDocument()!.layers.find((layer) => layer.id === committedId)!;
+      expect(committed.transform).toEqual(source.transform);
+      if (!('source' in committed)) {
+        throw new Error('expected a raster or control filter result');
+      }
+      expect(committed.source).toMatchObject({
+        bitmap: { height: output.height, width: output.width },
+        offset: { x: expectedRect.x, y: expectedRect.y },
+        type: 'paint',
+      });
+      const committedExport = await engine.exports.exportLayerPixels(committedId);
+      expect(committedExport.status === 'ok' ? committedExport.rect : null).toEqual(expectedRect);
+      expect(engine.stores.canUndo.get()).toBe(true);
+
+      engine.history.undo();
+      expect(engine.document.getDocument()).toEqual(document);
+      expect(engine.stores.canUndo.get()).toBe(false);
+      engine.history.redo();
+      const redone = engine.document.getDocument()!.layers.find((layer) => layer.id === committedId)!;
+      expect(redone).toEqual(committed);
+      expect(engine.stores.canRedo.get()).toBe(false);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['raster', 'control'] as const)(
+    'processes, retries durability, and applies %s with one origin-preserving history entry',
+    async (sourceType) => {
+      const { document, engine, source } = await createFilterFlowHarness(sourceType);
+      const makeDurable = vi
+        .fn<(imageName: string) => Promise<void>>()
+        .mockRejectedValueOnce(new Error('promotion failed'))
+        .mockResolvedValueOnce();
+
+      await getCanvasOperations(engine).commitFilterOperation('apply', makeDurable);
+      expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+        error: 'promotion failed',
+        preview: { imageName: 'filtered.png' },
+        status: 'error',
+      });
+      expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+        identity: { kind: 'filter' },
+        status: 'active',
+      });
+
+      await getCanvasOperations(engine).commitFilterOperation('apply', makeDurable);
+      expect(makeDurable).toHaveBeenCalledTimes(2);
+      expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+      expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+      expect(engine.document.getDocument()!.layers[0]).toMatchObject({
+        filter: source.filter,
+        opacity: source.opacity,
+        blendMode: source.blendMode,
+        source: { offset: { x: 7, y: -3 }, type: 'paint' },
+        transform: source.transform,
+        type: sourceType,
+      });
+      expect(engine.stores.canUndo.get()).toBe(true);
+      engine.history.undo();
+      expect(engine.document.getDocument()).toEqual(document);
+      expect(engine.stores.canUndo.get()).toBe(false);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it.each(['raster', 'control'] as const)(
+    'processes and saves as %s above the source with one history entry',
+    async (target) => {
+      const { engine, source } = await createFilterFlowHarness('control');
+
+      await getCanvasOperations(engine).commitFilterOperation(target, () => Promise.resolve());
+
+      expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+      expect(engine.document.getDocument()!.layers.map((layer) => layer.type)).toEqual([target, 'control']);
+      expect(engine.document.getDocument()!.layers[0]).toMatchObject({
+        blendMode: source.blendMode,
+        opacity: source.opacity,
+        source: { offset: { x: 7, y: -3 }, type: 'paint' },
+        transform: source.transform,
+      });
+      expect(engine.stores.canUndo.get()).toBe(true);
+      engine.history.undo();
+      expect(engine.document.getDocument()!.layers).toEqual([source]);
+      expect(engine.stores.canUndo.get()).toBe(false);
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('cancels an in-flight promotion when a replacement operation starts', async () => {
+    const { engine, source } = await createFilterFlowHarness('raster');
+    let resolvePromotion!: () => void;
+    const promotion = new Promise<void>((resolve) => {
+      resolvePromotion = resolve;
+    });
+    const pending = getCanvasOperations(engine).commitFilterOperation('apply', () => promotion);
+    await vi.waitFor(() => expect(getCanvasOperations(engine).stores.filterSession.get()?.status).toBe('committing'));
+
+    expect(getCanvasOperations(engine).startSelectObject(source.id)).toBe('started');
+    resolvePromotion();
+    await pending;
+
+    expect(engine.document.getDocument()!.layers[0]).toEqual(source);
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'select-object' },
+      status: 'active',
+    });
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('aborts an in-flight upload when a newer Process request wins', async () => {
+    const source = filterFlowLayer('raster');
+    const document = { ...emptyDoc(), layers: [source], selectedLayerId: source.id };
+    const { projectId, store } = createReducerBackedStore(document);
+    const uploadSignals: AbortSignal[] = [];
+    let uploadCount = 0;
+    const engine = createCanvasEngine({
+      backend: filterBitmapBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      filterDeps: {
+        runGraph: () =>
+          Promise.resolve({ height: 10, imageName: 'newest-filter.png', origin: 'canvas', output: {}, width: 10 }),
+        uploadIntermediate: (_blob, signal) => {
+          if (!signal) {
+            throw new Error('expected upload cancellation signal');
+          }
+          uploadSignals.push(signal);
+          uploadCount += 1;
+          if (uploadCount === 2) {
+            return Promise.resolve({ imageName: 'newest-input.png' });
+          }
+          return new Promise((_resolve, reject) => {
+            signal.addEventListener('abort', () => reject(new DOMException('superseded', 'AbortError')), {
+              once: true,
+            });
+          });
+        },
+      },
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(source.id)).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation(source.id)).toBe('started');
+
+    const older = getCanvasOperations(engine).processFilterOperation();
+    await vi.waitFor(() => expect(uploadSignals).toHaveLength(1));
+    const newer = getCanvasOperations(engine).processFilterOperation();
+    await Promise.all([older, newer]);
+
+    expect(uploadSignals[0]?.aborted).toBe(true);
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      error: null,
+      preview: { imageName: 'newest-filter.png' },
+      status: 'ready',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('makes filter and Select Object operations mutually exclusive', async () => {
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('L')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation('L')).toBe('started');
+
+    expect(getCanvasOperations(engine).startSelectObject('L')).toBe('started');
+
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    expect(getCanvasOperations(engine).stores.samSession.get()).not.toBeNull();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'select-object' },
+      status: 'active',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('refuses ordinary structural editing while a filter operation is active', async () => {
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('L')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation('L')).toBe('started');
+    vi.mocked(store.dispatch).mockClear();
+
+    engine.layers.commitStructural(
+      'Rename',
+      { id: 'L', patch: { name: 'Changed' }, type: 'updateCanvasLayer' },
+      { id: 'L', patch: { name: 'L' }, type: 'updateCanvasLayer' }
+    );
+
+    expect(store.dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.tools.handleEscapePriority({ gestureWasActive: false });
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['filter', 'select-object'] as const)(
+    'centrally blocks edits and undo during %s, then restores them after cancel',
+    async (kind) => {
+      const layer = guardableLayer('L');
+      const document = { ...emptyDoc(), layers: [layer], selectedLayerId: layer.id };
+      const { projectId, store } = createReducerBackedStore(document);
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId,
+        store,
+      });
+      expect((await engine.exports.exportLayerPixels('L')).status).toBe('ok');
+      engine.layers.commitStructural(
+        'Rename',
+        { id: 'L', patch: { name: 'Renamed' }, type: 'updateCanvasLayer' },
+        { id: 'L', patch: { name: 'L' }, type: 'updateCanvasLayer' }
+      );
+      const guard = engine.exports.captureLayerExportGuard('L');
+      if (!guard) {
+        throw new Error('expected a current operation guard');
+      }
+      const operation =
+        kind === 'filter'
+          ? getCanvasOperations(engine).controller.start({
+              cleanupPreview: vi.fn(),
+              guard,
+              identity: { kind, layerId: 'L', projectId },
+            })
+          : null;
+      if (kind === 'select-object') {
+        expect(getCanvasOperations(engine).startSelectObject('L')).toBe('started');
+      }
+
+      expect(engine.stores.documentEditingLocked.get()).toBe(true);
+      engine.history.undo();
+      expect(
+        engine.layers.applyStructuralPreview({ id: 'L', patch: { opacity: 0.2 }, type: 'updateCanvasLayer' })
+      ).toBe(false);
+      engine.layers.commitStructural(
+        'Blocked rename',
+        { id: 'L', patch: { name: 'Blocked' }, type: 'updateCanvasLayer' },
+        { id: 'L', patch: { name: 'Renamed' }, type: 'updateCanvasLayer' }
+      );
+      engine.layers.nudgeSelectedLayer(5, 0);
+      await expect(
+        engine.layers.commitRasterFilterResult({
+          guard,
+          image: { height: 10, imageName: 'unauthorized.png', width: 10 },
+          mode: 'replace',
+          rect: { height: 10, width: 10, x: 0, y: 0 },
+        })
+      ).resolves.toEqual({ status: 'busy' });
+
+      expect(engine.document.getDocument()!.layers[0]).toMatchObject({ name: 'Renamed', transform: { x: 0 } });
+      expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+        identity: { kind },
+        status: 'active',
+      });
+
+      if (kind === 'select-object') {
+        getCanvasOperations(engine).cancelSelectObjectSession();
+      } else {
+        operation?.cancel();
+      }
+      expect(engine.stores.documentEditingLocked.get()).toBe(false);
+      engine.history.undo();
+      expect(engine.document.getDocument()!.layers[0]?.name).toBe('L');
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('does not clear history while document editing is locked', async () => {
+    const layer = guardableLayer('L');
+    const document = { ...emptyDoc(), layers: [layer] };
+    const { projectId, store } = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels(layer.id)).status).toBe('ok');
+    engine.layers.commitStructural(
+      'Rename',
+      { id: layer.id, patch: { name: 'Renamed' }, type: 'updateCanvasLayer' },
+      { id: layer.id, patch: { name: layer.name }, type: 'updateCanvasLayer' }
+    );
+    const guard = engine.exports.captureLayerExportGuard(layer.id);
+    if (!guard) {
+      throw new Error('expected an operation guard');
+    }
+    const operation = getCanvasOperations(engine).controller.start({
+      cleanupPreview: vi.fn(),
+      guard,
+      identity: { kind: 'filter', layerId: layer.id, projectId },
+    });
+
+    engine.history.clearHistory();
+
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'filter' },
+      status: 'active',
+    });
+    operation?.cancel();
+    engine.history.clearHistory();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('invalidates the owned filter session when its guarded source changes', async () => {
+    const layer = guardableLayer('L');
+    const document = { ...emptyDoc(), layers: [layer] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('L')).status).toBe('ok');
+    expect(getCanvasOperations(engine).startFilterOperation('L')).toBe('started');
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toMatchObject({
+      draft: { type: 'canny_edge_detection' },
+      initialFilter: null,
+    });
+
+    setDocument({ ...document, layers: [{ ...layer, opacity: 0.5 }] });
+
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(getCanvasOperations(engine).stores.filterSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('rejects a guarded filter preview when its source changes during decode', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const layer = guardableLayer('L');
+    const document = { ...emptyDoc(), layers: [layer] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+
+    const pending = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'filtered', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+    setDocument({
+      ...document,
+      layers: [{ ...layer, source: { ...layer.source, fill: '#000' } } as CanvasLayerContract],
+    });
+    bitmaps.resolveBitmap(0);
+
+    await expect(pending).resolves.toBe('stale');
+    engine.lifecycle.dispose();
+  });
+
+  it('rejects a guarded filter preview when raster adjustments change during decode', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const layer = guardableLayer('L');
+    const document = { ...emptyDoc(), layers: [layer] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+
+    const pending = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'filtered', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+    setDocument({
+      ...document,
+      layers: [{ ...layer, adjustments: { brightness: 0.2, contrast: 0, saturation: 0 } }],
+    });
+    bitmaps.resolveBitmap(0);
+
+    await expect(pending).resolves.toBe('stale');
+    engine.lifecycle.dispose();
+  });
+
+  it('rejects a guarded filter preview when the paint cache version changes during decode', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+
+    const pending = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'filtered', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+    await engine.diagnostics.clearCaches();
+    bitmaps.resolveBitmap(0);
+
+    await expect(pending).resolves.toBe('stale');
+    engine.lifecycle.dispose();
+  });
+
+  it('returns missing when the guarded preview layer is deleted during decode', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+
+    const pending = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'filtered', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+    setDocument({ ...document, layers: [] });
+    bitmaps.resolveBitmap(0);
+
+    await expect(pending).resolves.toBe('missing');
+    engine.lifecycle.dispose();
+  });
+
+  it('rejects a guarded filter preview after document replacement reuses the layer id', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const { setDocument, store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+
+    const pending = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'filtered', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+    setDocument({ ...document, height: 200, width: 200 }, 1);
+    bitmaps.resolveBitmap(0);
+
+    await expect(pending).resolves.toBe('stale');
+    engine.lifecycle.dispose();
+  });
+
+  it('lets only the newest guarded filter preview publish', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const { store } = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+
+    const older = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'older', rect: exported.rect },
+      exported.guard
+    );
+    const newer = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'newer', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+    bitmaps.resolveBitmap(1);
+    await expect(newer).resolves.toBe('shown');
+    bitmaps.resolveBitmap(0);
+
+    await expect(older).resolves.toBe('stale');
+    engine.lifecycle.dispose();
+  });
+
+  const screenDrawsBitmap = (screen: StubRasterSurface, backend: RecordingRasterBackend, bitmapId: string): boolean =>
+    screen.callLog
+      .filter((entry) => entry.op === 'drawImage')
+      .some((entry) => {
+        const surfaceId = (entry.args[0] as { __recordingId?: string }).__recordingId;
+        const surface = surfaceId ? backend.surfaceById(surfaceId) : undefined;
+        return !!surface && backend.drawSourcesFor(surface).includes(`bitmap-${bitmapId}`);
+      });
+
+  const createPublishedGuardedPreview = async (layer: CanvasRasterLayerContractV2 = guardableLayer('L')) => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    const backend = createRecordingRasterBackend();
+    const sourceNeedsBitmap =
+      layer.type === 'raster' &&
+      (layer.source.type === 'image' || (layer.source.type === 'paint' && layer.source.bitmap !== null));
+    let bitmapCall = 0;
+    backend.createImageBitmap = vi.fn(() =>
+      Promise.resolve(recordingBitmap(sourceNeedsBitmap && bitmapCall++ === 0 ? 'layer-source' : 'guarded-preview'))
+    );
+    const document = { ...emptyDoc(), layers: [layer], selectedLayerId: layer.id };
+    const reactive = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store: reactive.store,
+    });
+    const screen = createFakeCanvas();
+    engine.surface.attach(screen.element, createFakeCanvas().element);
+    raf.flush();
+    const exported = await engine.exports.exportLayerPixels(layer.id);
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+    await expect(
+      engine.previews.setGuardedFilterPreview(
+        layer.id,
+        { imageName: 'guarded-preview', rect: exported.rect },
+        exported.guard
+      )
+    ).resolves.toBe('shown');
+    raf.flush();
+    expect(screenDrawsBitmap(screen.surface, backend, 'guarded-preview')).toBe(true);
+    screen.surface.callLog.length = 0;
+    return { backend, document, engine, layer, raf, screen: screen.surface, ...reactive };
+  };
+
+  it('keeps a published guarded preview across an active-project away/back transition', async () => {
+    const harness = await createPublishedGuardedPreview();
+
+    harness.setActiveProjectId('p2');
+    harness.setActiveProjectId('p1');
+    harness.screen.callLog.length = 0;
+    harness.engine.stores.checkerboard.set(!harness.engine.stores.checkerboard.get());
+    harness.raf.flush();
+
+    expect(screenDrawsBitmap(harness.screen, harness.backend, 'guarded-preview')).toBe(true);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('publishes an in-flight guarded preview across an active-project away/back transition', async () => {
+    const bitmaps = createDeferredBitmapBackend();
+    const document = { ...emptyDoc(), layers: [guardableLayer('L')] };
+    const reactive = createReactiveStore(document);
+    const engine = createCanvasEngine({
+      backend: bitmaps.backend,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store: reactive.store,
+    });
+    const exported = await engine.exports.exportLayerPixels('L');
+    if (exported.status !== 'ok') {
+      throw new Error('expected a guardable export');
+    }
+    const pending = engine.previews.setGuardedFilterPreview(
+      'L',
+      { imageName: 'filtered', rect: exported.rect },
+      exported.guard
+    );
+    await flushMicrotasks();
+
+    reactive.setActiveProjectId('p2');
+    reactive.setActiveProjectId('p1');
+    bitmaps.resolveBitmap(0);
+
+    await expect(pending).resolves.toBe('shown');
+    engine.lifecycle.dispose();
+  });
+
+  it('unsubscribes project-preview lifecycle handling on dispose', () => {
+    const reactive = createReactiveStore(emptyDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store: reactive.store,
+    });
+
+    expect(reactive.listenerCount()).toBe(1);
+    engine.lifecycle.dispose();
+    expect(reactive.listenerCount()).toBe(0);
+  });
+
+  it('clears an already-published guarded preview when the source contract changes', async () => {
+    const harness = await createPublishedGuardedPreview();
+    harness.setDocument({
+      ...harness.document,
+      layers: [{ ...harness.layer, source: { ...harness.layer.source, fill: '#000' } } as CanvasLayerContract],
+    });
+    harness.raf.flush();
+
+    expect(screenDrawsBitmap(harness.screen, harness.backend, 'guarded-preview')).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('clears an already-published guarded preview when raster adjustments change', async () => {
+    const harness = await createPublishedGuardedPreview();
+    harness.setDocument({
+      ...harness.document,
+      layers: [{ ...harness.layer, adjustments: { brightness: 0.3, contrast: 0, saturation: 0 } }],
+    });
+    harness.raf.flush();
+
+    expect(screenDrawsBitmap(harness.screen, harness.backend, 'guarded-preview')).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('clears an already-published guarded preview when live paint advances the cache version', async () => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const paint: CanvasRasterLayerContractV2 = {
+      ...guardableLayer('L'),
+      source: { bitmap: { height: 10, imageName: 'paint-source', width: 10 }, type: 'paint' },
+      type: 'raster',
+    };
+    const harness = await createPublishedGuardedPreview(paint);
+
+    harness.engine.selection.selectAll();
+    harness.engine.selection.fillSelection();
+    harness.raf.flush();
+
+    expect(screenDrawsBitmap(harness.screen, harness.backend, 'guarded-preview')).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+
+  it('clears an already-published guarded preview when its cache is invalidated', async () => {
+    const harness = await createPublishedGuardedPreview();
+
+    await harness.engine.diagnostics.clearCaches();
+    harness.raf.flush();
+
+    expect(screenDrawsBitmap(harness.screen, harness.backend, 'guarded-preview')).toBe(false);
+    harness.engine.lifecycle.dispose();
+  });
+});
+
+// ---- C1: prop/transform edits must not wipe an unflushed paint layer -----
+//
+// A `bitmap: null` paint layer's strokes live ONLY in its raster cache until a
+// debounced upload persists them. The paint rasterizer clears the surface for a
+// null bitmap, so re-rasterizing such a layer WIPES the strokes. The engine must
+// therefore invalidate a layer's cache only when its SOURCE reference changed —
+// never for a prop/transform-only edit (opacity/blend/lock/rename/nudge), which
+// the compositor already applies at draw time.
+
+/** Full-surface clears (`clearRect(0,0,w,h)`) recorded on a stub surface — the wipe signature. */
+const fullClearCount = (surface: StubRasterSurface): number =>
+  surface.callLog.filter((entry) => entry.op === 'clearRect' && entry.args[0] === 0 && entry.args[1] === 0).length;
+
+describe('document mirror wiring: prop vs source change (paint-pixel survival)', () => {
+  /**
+   * Rasterizes the pre-existing `paint1` layer to completion (as real frames
+   * would before the user paints — the existing-layer paint path does NOT mark
+   * the cache non-stale itself), then draws one stroke into that non-stale cache.
+   * This reproduces the C1 state: real strokes living only in a cache that a
+   * spurious re-rasterize (of the `bitmap: null` source) would clear to blank.
+   */
+  const paintOneStroke = async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { setDocument, store } = createReactiveStore(paintDoc());
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const bitmapStore = createSpyBitmapStore();
+    const resolver = vi.fn((_imageName: string) => Promise.resolve(new Blob()));
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore,
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+
+    // Initial rasterize of the (bitmap: null) paint layer → one full clear, then
+    // the cache settles non-stale (the `.then` fires on a microtask).
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+
+    // The painted layer cache is the only engine-backend surface that ever gets
+    // `getImageData` (the before/after stroke capture); the scratch stroke
+    // surface never does.
+    const paintCache = surfaces.find((surface) => surface.callLog.some((entry) => entry.op === 'getImageData'));
+    return { bitmapStore, engine, paintCache: paintCache!, raf, resolver, setDocument };
+  };
+
+  const paintOneStrokeWithReducer = async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const { projectId, store } = createReducerBackedStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+    return engine;
+  };
+
+  it('accepts a persisted bitmap from reducer state when an earlier subscriber throws before the mirror refreshes', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const reducer = createReducerBackedStore(paintDoc());
+    let throwAfterBitmapCommit = false;
+    const unsubscribeThrower = reducer.store.subscribe(() => {
+      if (throwAfterBitmapCommit) {
+        throw new Error('earlier subscriber failed after reducer commit');
+      }
+    });
+    const reportError = vi.fn();
+    const uploadImage = vi
+      .spyOn(canvasApplicationPort, 'uploadImage')
+      .mockResolvedValue({ height: 40, imageName: 'persisted-before-mirror-refresh.png', width: 60 });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      reportError,
+      store: reducer.store,
+    });
+    const overlay = createInputCanvas();
+    engine.surface.attach(createInputCanvas().element, overlay.element);
+    engine.tools.setTool('brush');
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    const strokes: StrokeCommittedEvent[] = [];
+    const unsubscribeStroke = engine.tools.onStrokeCommitted((stroke) => strokes.push(stroke));
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+    expect(strokes).toHaveLength(1);
+    expect(strokes[0]?.layerId).toBe('paint1');
+    throwAfterBitmapCommit = true;
+
+    await expect(engine.lifecycle.flushPendingUploads()).resolves.toBeUndefined();
+    await expect(engine.lifecycle.flushPendingUploads()).resolves.toBeUndefined();
+
+    const authoritativeLayer = reducer.store
+      .getState()
+      .projects.find((project) => project.id === reducer.projectId)
+      ?.canvas.document.layers.find((layer) => layer.id === 'paint1');
+    expect(uploadImage).toHaveBeenCalledOnce();
+    const bitmapUpdates = reducer.dispatch.mock.calls
+      .map(([action]) => action)
+      .filter((action) => action.type === 'updateCanvasLayerSource' && action.id === 'paint1');
+    expect(bitmapUpdates).toHaveLength(1);
+    expect(authoritativeLayer).toMatchObject({
+      source: { bitmap: { imageName: 'persisted-before-mirror-refresh.png' }, type: 'paint' },
+    });
+    expect(reportError).not.toHaveBeenCalled();
+
+    unsubscribeStroke();
+    unsubscribeThrower();
+    engine.lifecycle.dispose();
+    uploadImage.mockRestore();
+  });
+
+  it('keeps an unflushed paint layer’s pixels on a transform/opacity-only change (no re-rasterize)', async () => {
+    const { engine, paintCache, raf, resolver, setDocument } = await paintOneStroke();
+
+    // Baseline: the stroke composited into the cache (a drawImage). Exactly one
+    // full clear so far — the initial rasterize; the stroke never clears.
+    expect(paintCache.callLog.some((entry) => entry.op === 'drawImage')).toBe(true);
+    const clearsBefore = fullClearCount(paintCache);
+
+    // A prop-only edit that PRESERVES the source reference (exactly as the reducer
+    // does — it spreads `...layer`): opacity + a transform nudge.
+    const doc = engine.document.getDocument()!;
+    const layer = doc.layers[0]!;
+    setDocument({
+      ...doc,
+      layers: [{ ...layer, opacity: 0.5, transform: { ...layer.transform, x: 12, y: -4 } }],
+    });
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    // The cache was NOT re-rasterized: no new full clear, so the painted pixels
+    // survive. (A `bitmap: null` re-rasterize would clear the surface to blank.)
+    expect(fullClearCount(paintCache)).toBe(clearsBefore);
+    // No resolve/rasterize was even attempted for the paint layer.
+    expect(resolver).not.toHaveBeenCalled();
+    expect(engine.document.getDocument()!.layers[0]!.opacity).toBe(0.5);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('exports an unflushed paint layer from its ready live cache when the contract bitmap is still null', async () => {
+    const { engine, paintCache } = await paintOneStroke();
+
+    const result = await engine.exports.exportLayerPixels('paint1');
+
+    expect(result.status).toBe('ok');
+    if (result.status === 'ok') {
+      expect(result.surface).toBe(paintCache);
+      expect(result.rect.width).toBeGreaterThan(0);
+      expect(result.rect.height).toBeGreaterThan(0);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('preserves live pixels through contract copy and conversion history', async () => {
+    const engine = await paintOneStrokeWithReducer();
+    const raster = engine.document.getDocument()!.layers[0]!;
+    if (raster.type !== 'raster') {
+      throw new Error('expected raster source');
+    }
+    const control: CanvasLayerContract = {
+      ...raster,
+      adapter: {
+        beginEndStepPct: [0, 0.75],
+        controlMode: 'balanced',
+        kind: 'controlnet',
+        model: null,
+        weight: 1,
+      },
+      type: 'control',
+      withTransparencyEffect: true,
+    };
+    const copy = { ...control, id: 'control-copy', name: 'Control copy' };
+
+    expect(engine.layers.commitLayerCopy('Copy layer', raster.id, copy, 0)).toBe(true);
+    expect((await engine.exports.exportLayerPixels(copy.id)).status).toBe('ok');
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.some((layer) => layer.id === copy.id)).toBe(false);
+    engine.history.redo();
+    expect((await engine.exports.exportLayerPixels(copy.id)).status).toBe('ok');
+
+    expect(engine.layers.commitLayerConversion('Convert layer', raster, control)).toBe(true);
+    expect(engine.document.getDocument()!.layers.find((layer) => layer.id === raster.id)?.type).toBe('control');
+    expect((await engine.exports.exportLayerPixels(raster.id)).status).toBe('ok');
+    engine.history.undo();
+    expect(engine.document.getDocument()!.layers.find((layer) => layer.id === raster.id)?.type).toBe('raster');
+    expect((await engine.exports.exportLayerPixels(raster.id)).status).toBe('ok');
+    engine.lifecycle.dispose();
+  });
+
+  it('commitLayerConversion requires the caller to hold the immutable live layer object', async () => {
+    const { dispatch, projectId, store } = createReducerBackedStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('a')).status).toBe('ok');
+    const live = engine.document.getDocument()!.layers[0]!;
+    if (live.type !== 'raster') {
+      throw new Error('expected raster layer');
+    }
+    const converted: CanvasLayerContract = {
+      ...live,
+      adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      type: 'control',
+      withTransparencyEffect: false,
+    };
+    dispatch.mockClear();
+
+    expect(engine.layers.commitLayerConversion('Convert', structuredClone(live), converted)).toBe(false);
+    expect(dispatch).not.toHaveBeenCalledWith(expect.objectContaining({ type: 'convertCanvasLayer' }));
+    expect(engine.document.getDocument()!.layers[0]!.type).toBe('raster');
+    engine.lifecycle.dispose();
+  });
+
+  it('commitLayerConversion refuses conversion when the live layer is locked', async () => {
+    const { dispatch, projectId, store } = createReducerBackedStore(makeDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId,
+      store,
+    });
+    expect((await engine.exports.exportLayerPixels('a')).status).toBe('ok');
+    const expectedUnlocked = engine.document.getDocument()!.layers[0]!;
+    if (expectedUnlocked.type !== 'raster') {
+      throw new Error('expected raster layer');
+    }
+    const converted: CanvasLayerContract = {
+      ...expectedUnlocked,
+      adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      type: 'control',
+      withTransparencyEffect: false,
+    };
+    dispatch({ id: expectedUnlocked.id, patch: { isLocked: true }, type: 'updateCanvasLayer' });
+    dispatch.mockClear();
+
+    expect(engine.layers.commitLayerConversion('Convert', expectedUnlocked, converted)).toBe(false);
+    expect(dispatch).not.toHaveBeenCalledWith(expect.objectContaining({ type: 'convertCanvasLayer' }));
+    expect(engine.document.getDocument()!.layers[0]).toMatchObject({ isLocked: true, type: 'raster' });
+    engine.lifecycle.dispose();
+  });
+
+  it('flushing after a prop-only change persists the painted (non-blank) surface', async () => {
+    const { bitmapStore, engine, paintCache, raf, setDocument } = await paintOneStroke();
+    const clearsBefore = fullClearCount(paintCache);
+
+    const doc = engine.document.getDocument()!;
+    const layer = doc.layers[0]!;
+    setDocument({ ...doc, layers: [{ ...layer, opacity: 0.25 }] });
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    await engine.lifecycle.flushPendingUploads();
+
+    // The flush barrier ran, and it operated on a cache that was never wiped: the
+    // surface still carries the stroke (drawImage) with no re-rasterize clear, so
+    // the bitmap store (which encodes this exact surface) persists real pixels.
+    expect(bitmapStore.flushPendingUploads).toHaveBeenCalled();
+    expect(fullClearCount(paintCache)).toBe(clearsBefore);
+    expect(paintCache.callLog.some((entry) => entry.op === 'drawImage')).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('re-rasterizes when the paint layer’s source genuinely changes (swap to a persisted bitmap)', async () => {
+    const { engine, raf, resolver, setDocument } = await paintOneStroke();
+    expect(resolver).not.toHaveBeenCalled();
+
+    // A genuine source swap (undo/import → a NEW paint source object with a
+    // persisted bitmap). isSelfEcho is false in the spy store, so this must
+    // invalidate and re-rasterize — which decodes the persisted image.
+    const doc = engine.document.getDocument()!;
+    const layer = doc.layers[0] as CanvasRasterLayerContractV2;
+    setDocument({
+      ...doc,
+      layers: [
+        {
+          ...layer,
+          source: { bitmap: { contentHash: 'h', height: 100, imageName: 'persisted', width: 100 }, type: 'paint' },
+        },
+      ],
+    });
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    // The cache was invalidated and re-rasterized from the new persisted source.
+    expect(resolver).toHaveBeenCalledWith('persisted', expect.any(AbortSignal));
+
+    engine.lifecycle.dispose();
+  });
+
+  it('leaves image layers alone on a prop change but re-rasterizes on a source swap', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { setDocument, store } = createReactiveStore(makeDoc()); // one image layer 'a'
+    const resolver = vi.fn((_imageName: string) => Promise.resolve(new Blob()));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: resolver,
+      projectId: 'p1',
+      store,
+    });
+    engine.surface.attach(createFakeCanvas().element, createFakeCanvas().element);
+
+    // Initial rasterize of image 'a'.
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(resolver).toHaveBeenNthCalledWith(1, 'a', expect.any(AbortSignal));
+
+    // Prop-only edit (opacity), source reference preserved: no re-rasterize.
+    const doc = engine.document.getDocument()!;
+    setDocument({ ...doc, layers: [{ ...doc.layers[0]!, opacity: 0.3 }] });
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    expect(resolver).toHaveBeenCalledTimes(1);
+
+    // Source swap (new image name → new source object): re-rasterizes the new source.
+    const doc2 = engine.document.getDocument()!;
+    const imgLayer = doc2.layers[0] as CanvasRasterLayerContractV2;
+    setDocument({
+      ...doc2,
+      layers: [{ ...imgLayer, source: { image: { height: 10, imageName: 'a-v2', width: 10 }, type: 'image' } }],
+    });
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    expect(resolver).toHaveBeenCalledTimes(2);
+    expect(resolver).toHaveBeenNthCalledWith(2, 'a-v2', expect.any(AbortSignal));
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('hasExportableLayerContent', () => {
+  const sourceLayer = (id: string, source: CanvasLayerSourceContract, isEnabled = true): CanvasLayerContract => ({
+    blendMode: 'normal',
+    id,
+    isEnabled,
+    isLocked: false,
+    name: id,
+    opacity: 1,
+    source,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'raster',
+  });
+
+  const createContentEngine = (layers: CanvasLayerContract[]) => {
+    const { store } = createFakeStore({ ...makeDoc(), layers });
+    return createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+  };
+
+  const createLiveUnpersistedLayer = async (layer: CanvasLayerContract) => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { setDocument, store } = createReactiveStore({
+      ...makeDoc(),
+      layers: [layer],
+      selectedLayerId: layer.id,
+    });
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    engine.surface.attach(createInputCanvas().element, overlay.element);
+
+    // Settle the initial empty paint/mask rasterization before drawing. A stroke
+    // then grows that current cache without updating the persisted contract.
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    engine.tools.setTool('brush');
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(40, 40, { buttons: 0 }));
+
+    return { engine, setDocument };
+  };
+
+  it('returns true for image, persisted paint, and every supported parametric source', () => {
+    const sources: { id: string; source: CanvasLayerSourceContract }[] = [
+      {
+        id: 'image',
+        source: { image: { height: 12, imageName: 'image', width: 14 }, type: 'image' },
+      },
+      {
+        id: 'persisted-paint',
+        source: {
+          bitmap: { height: 15, imageName: 'paint', width: 16 },
+          offset: { x: -3, y: 4 },
+          type: 'paint',
+        },
+      },
+      {
+        id: 'rect',
+        source: { fill: '#000', height: 18, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 20 },
+      },
+      {
+        id: 'ellipse',
+        source: {
+          fill: '#000',
+          height: 18,
+          kind: 'ellipse',
+          stroke: null,
+          strokeWidth: 0,
+          type: 'shape',
+          width: 20,
+        },
+      },
+      {
+        id: 'gradient',
+        source: {
+          angle: 45,
+          height: 22,
+          kind: 'linear',
+          stops: [{ color: '#000', offset: 0 }],
+          type: 'gradient',
+          width: 24,
+        },
+      },
+      {
+        id: 'text',
+        source: {
+          align: 'left',
+          color: '#000',
+          content: 'Export me',
+          fontFamily: 'Inter',
+          fontSize: 20,
+          fontWeight: 400,
+          lineHeight: 1.2,
+          type: 'text',
+        },
+      },
+    ];
+    // Disabled layers remain exportable because Save/Clipboard may explicitly
+    // export hidden content.
+    const engine = createContentEngine(sources.map(({ id, source }) => sourceLayer(id, source, false)));
+
+    for (const { id } of sources) {
+      expect(engine.exports.hasExportableLayerContent(id), id).toBe(true);
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('returns false for empty paint, unsupported polygon, and missing ids', () => {
+    const polygon: CanvasLayerSourceContract = {
+      fill: '#000',
+      height: 20,
+      kind: 'polygon',
+      points: [
+        { x: 0, y: 0 },
+        { x: 20, y: 0 },
+        { x: 10, y: 20 },
+      ],
+      stroke: null,
+      strokeWidth: 0,
+      type: 'shape',
+      width: 20,
+    };
+    const engine = createContentEngine([
+      sourceLayer('empty-paint', { bitmap: null, type: 'paint' }),
+      sourceLayer('polygon', polygon),
+    ]);
+
+    expect(engine.exports.hasExportableLayerContent('empty-paint')).toBe(false);
+    expect(engine.exports.hasExportableLayerContent('polygon')).toBe(false);
+    expect(engine.exports.hasExportableLayerContent('missing')).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns true for a persisted disabled mask and false for an empty mask', () => {
+    const persistedMask: CanvasInpaintMaskLayerContract = {
+      ...maskLayer('persisted-mask'),
+      isEnabled: false,
+      mask: {
+        ...maskLayer('persisted-mask').mask,
+        bitmap: { height: 17, imageName: 'persisted-mask', width: 19 },
+        offset: { x: 2, y: 3 },
+      },
+    };
+    const engine = createContentEngine([persistedMask, maskLayer('empty-mask')]);
+
+    expect(engine.exports.hasExportableLayerContent('persisted-mask')).toBe(true);
+    expect(engine.exports.hasExportableLayerContent('empty-mask')).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns true for current live unpersisted paint pixels', async () => {
+    const { engine } = await createLiveUnpersistedLayer(sourceLayer('live-paint', { bitmap: null, type: 'paint' }));
+
+    expect(engine.exports.hasExportableLayerContent('live-paint')).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('captures current unflushed pixels and bounds for a new bitmap-less paint layer', async () => {
+    const { engine } = await createLiveUnpersistedLayer(
+      sourceLayer('live-snapshot-paint', { bitmap: null, type: 'paint' })
+    );
+    const documentSnapshot = engine.document.captureSnapshot();
+
+    const result = await engine.exports.captureRasterSnapshot(documentSnapshot!, ['live-snapshot-paint']);
+
+    expect(result.status).toBe('ok');
+    if (result.status !== 'ok') {
+      throw new Error('Expected live paint snapshot');
+    }
+    const detached = result.snapshot.layerSurfaces.get('live-snapshot-paint');
+    expect(detached?.rect.width).toBeGreaterThan(0);
+    expect(detached?.rect.height).toBeGreaterThan(0);
+    result.snapshot.release();
+    engine.lifecycle.dispose();
+  });
+
+  it('returns false for a stale non-empty live cache with no persisted pixels', async () => {
+    const { engine, setDocument } = await createLiveUnpersistedLayer(
+      sourceLayer('stale-paint', { bitmap: null, type: 'paint' })
+    );
+    expect(engine.exports.hasExportableLayerContent('stale-paint')).toBe(true);
+
+    const doc = engine.document.getDocument()!;
+    const layer = doc.layers[0];
+    if (!layer || layer.type !== 'raster') {
+      throw new Error('expected raster paint layer');
+    }
+    // A genuine source-reference change invalidates the still-non-empty live
+    // cache synchronously. Do not run the scheduled frame that would rebuild it.
+    setDocument({
+      ...doc,
+      layers: [{ ...layer, source: { bitmap: null, type: 'paint' } }],
+    });
+    const { target } = createThumbnailTarget();
+    expect(engine.previews.drawLayerThumbnail('stale-paint', target, 96)).toBe(true);
+    expect(engine.exports.hasExportableLayerContent('stale-paint')).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('returns true for current live unpersisted mask pixels', async () => {
+    const { engine } = await createLiveUnpersistedLayer(maskLayer('live-mask'));
+
+    expect(engine.exports.hasExportableLayerContent('live-mask')).toBe(true);
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- I4: structural edits are no-ops during an active pointer gesture -----
+
+describe('gesture guard: nudge / commitStructural mid-stroke', () => {
+  const startOpenStroke = () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+    // Open a stroke (pointer down + move, NO up) so the gesture stays active.
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(30, 30));
+    return { dispatch, engine, overlay };
+  };
+
+  it('no-ops nudgeSelectedLayer while a stroke gesture is open', () => {
+    const { dispatch, engine, overlay } = startOpenStroke();
+    const before = dispatch.mock.calls.length;
+
+    engine.layers.nudgeSelectedLayer(1, 0);
+    // No structural transform dispatch, no history entry.
+    expect(dispatch.mock.calls.filter((call) => call[0].type === 'updateCanvasLayer')).toHaveLength(0);
+    expect(engine.stores.canUndo.get()).toBe(false);
+
+    // After the gesture ends, the nudge lands.
+    overlay.fire('pointerup', pointerAt(30, 30, { buttons: 0 }));
+    engine.layers.nudgeSelectedLayer(1, 0);
+    expect(dispatch.mock.calls.length).toBeGreaterThan(before);
+    expect(dispatch.mock.calls.some((call) => call[0].type === 'updateCanvasLayer')).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('no-ops commitStructural while a stroke gesture is open, then commits after it ends', () => {
+    const { dispatch, engine, overlay } = startOpenStroke();
+    const forward: EngineTestAction = { id: 'x', type: 'setCanvasSelectedLayer' };
+    const inverse: EngineTestAction = { id: null, type: 'setCanvasSelectedLayer' };
+
+    expect(engine.layers.canCommitStructural()).toBe(false);
+    expect(engine.layers.commitStructural('Select', forward, inverse)).toBe(false);
+    // Nothing dispatched, nothing recorded on history mid-gesture.
+    expect(dispatch.mock.calls.some((call) => call[0] === forward)).toBe(false);
+    expect(engine.stores.canUndo.get()).toBe(false);
+
+    overlay.fire('pointerup', pointerAt(30, 30, { buttons: 0 }));
+    expect(engine.layers.canCommitStructural()).toBe(true);
+    expect(engine.layers.commitStructural('Select', forward, inverse)).toBe(true);
+    expect(dispatch.mock.calls.some((call) => call[0] === forward)).toBe(true);
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('no-ops mergeLayerDown while a stroke gesture is open, then merges after it ends', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(twoPaintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    // Build both layer caches so a merge could otherwise succeed; await the async
+    // decode so both are READY (merge refuses stale/in-flight caches — finding 20).
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    engine.tools.setTool('brush');
+
+    // Open a stroke into the selected 'upper' paint layer (no pointer-up).
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(30, 30));
+
+    // Mid-gesture merge is refused (matches commitStructural/nudge): not undoable.
+    expect(engine.layers.mergeLayerDown('upper')).toBe(false);
+    expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+      false
+    );
+
+    // After the gesture ends, the merge lands.
+    overlay.fire('pointerup', pointerAt(30, 30, { buttons: 0 }));
+    expect(engine.layers.mergeLayerDown('upper')).toBe(true);
+    expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'mergeCanvasLayersDown')).toBe(
+      true
+    );
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- brush cursor ring: resizes on a size change with no pointer event ----
+
+describe('brush cursor ring: live size updates', () => {
+  it('invalidates the overlay when the brush size changes without a pointer move', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+
+    // A bare hover move (no button) sets the cursor ring at a known position.
+    overlay.fire('pointermove', pointerAt(30, 30, { buttons: 0 }));
+    raf.flush();
+    expect(raf.pendingCount()).toBe(0);
+
+    // The `[`/`]` path: a size step with NO pointer event must schedule a frame
+    // (the ring redraws at its last position with the new radius).
+    engine.tools.stepBrushSize(1);
+    expect(raf.pendingCount()).toBeGreaterThan(0);
+    raf.flush();
+
+    // The options-bar slider path (a direct store write) likewise invalidates.
+    engine.stores.brushOptions.set({ ...engine.stores.brushOptions.get(), size: 123 });
+    expect(raf.pendingCount()).toBeGreaterThan(0);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('does not invalidate for a size change while no ring is shown (pointer off-canvas)', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+    raf.flush();
+    expect(raf.pendingCount()).toBe(0);
+
+    // No hover move happened, so there is no ring to resize: no frame scheduled.
+    engine.tools.stepBrushSize(1);
+    expect(raf.pendingCount()).toBe(0);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- doc-replace mid-gesture: cancels the active tool gesture (I-follow-up) ----
+
+describe('doc-replace mid-gesture: cancels the active tool gesture', () => {
+  it('cancels a bbox drag on a document swap, clears the preview, and commits nothing on pointer-up', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { setDocument, store } = createReactiveStore(paintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('bbox');
+
+    // Start a bbox move-drag (press inside the 100x100 frame, then drag).
+    overlay.fire('pointerdown', pointerAt(40, 40));
+    overlay.fire('pointermove', pointerAt(60, 60));
+    expect(engine.stores.bboxPreview.get()).not.toBeNull();
+
+    // A wholesale document swap mid-drag (dims change → onDocumentReplaced).
+    setDocument({ ...paintDoc(), height: 200, width: 200 });
+
+    // The gesture was cancelled: the transient preview is cleared.
+    expect(engine.stores.bboxPreview.get()).toBeNull();
+
+    // The eventual pointer-up must NOT commit a bbox against the replaced document.
+    overlay.fire('pointerup', pointerAt(60, 60, { buttons: 0 }));
+    expect(dispatch.mock.calls.some((call) => (call[0] as EngineTestAction).type === 'setCanvasBbox')).toBe(false);
+    expect(engine.stores.canUndo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('cancels a move-tool drag on a document swap, clearing the transform override', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { setDocument, store } = createReactiveStore(paintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const overlay = createInputCanvas();
+    const screen = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('move');
+
+    // Drag the doc-sized paint layer.
+    overlay.fire('pointerdown', pointerAt(20, 20));
+    overlay.fire('pointermove', pointerAt(50, 40));
+
+    const updatesBefore = dispatch.mock.calls.filter(
+      (call) => (call[0] as EngineTestAction).type === 'updateCanvasLayer'
+    ).length;
+
+    setDocument({ ...paintDoc(), height: 200, width: 200 });
+
+    // Pointer-up after the swap commits no transform update (the gesture was cancelled).
+    overlay.fire('pointerup', pointerAt(50, 40, { buttons: 0 }));
+    const updatesAfter = dispatch.mock.calls.filter(
+      (call) => (call[0] as EngineTestAction).type === 'updateCanvasLayer'
+    ).length;
+    expect(updatesAfter).toBe(updatesBefore);
+    expect(engine.stores.canUndo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- Zoom-cost regressions: what must NOT scale with zoom ----------------
+//
+// The reported lag ("laggier the closer you zoom in") traced to the render loop
+// recompositing the whole document on EVERY invalidation — including overlay-only
+// hover frames, whose cost is otherwise constant. A full composite up-scales each
+// doc-sized layer surface to fill the screen, so its fill-rate grows with zoom.
+// These lock the two fixes: overlay-only frames skip the composite, and composites
+// disable image smoothing when zoomed in (crisp + no bilinear up-scale per frame).
+
+describe('zoom-cost: overlay-only frames skip the document composite', () => {
+  /** A fake canvas that can BOTH fire pointer events and expose its recording surface. */
+  const createFireableSurfaceCanvas = (
+    width = 100,
+    height = 100
+  ): {
+    element: HTMLCanvasElement;
+    fire: (type: string, event: Partial<PointerEvent>) => void;
+    surface: StubRasterSurface;
+  } => {
+    const surface = createTestStubRasterBackend().createSurface(width, height);
+    const listeners = new Map<string, Set<(event: Event) => void>>();
+    const element = {
+      addEventListener: (type: string, handler: (event: Event) => void) => {
+        const set = listeners.get(type) ?? new Set();
+        set.add(handler);
+        listeners.set(type, set);
+      },
+      getBoundingClientRect: () => ({ bottom: height, height, left: 0, right: width, top: 0, width, x: 0, y: 0 }),
+      getContext: () => surface.ctx,
+      height,
+      releasePointerCapture: () => {},
+      removeEventListener: (type: string, handler: (event: Event) => void) => {
+        listeners.get(type)?.delete(handler);
+      },
+      setPointerCapture: () => {},
+      width,
+    } as unknown as HTMLCanvasElement;
+    const fire = (type: string, event: Partial<PointerEvent>): void => {
+      for (const handler of listeners.get(type) ?? []) {
+        handler({ preventDefault: () => {}, ...event } as unknown as Event);
+      }
+    };
+    return { element, fire, surface };
+  };
+
+  /** Composite draws land on the screen surface as clear/fill/blit ops. */
+  const compositeOps = (surface: StubRasterSurface): RasterCallLogEntry[] =>
+    surface.callLog.filter((e) => e.op === 'drawImage' || e.op === 'clearRect' || e.op === 'fillRect');
+
+  it('a hover pointermove redraws only the overlay, never the screen composite', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFireableSurfaceCanvas();
+    const overlay = createFireableSurfaceCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('brush');
+
+    // Drain the attach `{ all }` frame and the paint layer's async rasterize
+    // follow-up so no composite-triggering work is left pending.
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    // Isolate the hover frame.
+    screen.surface.callLog.length = 0;
+    overlay.surface.callLog.length = 0;
+
+    // A hover move (no button pressed) resizes the cursor ring → `{ overlay: true }`.
+    overlay.fire('pointermove', pointerAt(40, 40, { buttons: 0 }));
+    raf.flush();
+
+    // The screen composite did NOT run: zero clears/fills/blits landed on it. This
+    // is the win — hover cost is now independent of zoom and document size.
+    expect(compositeOps(screen.surface)).toHaveLength(0);
+    // The overlay WAS redrawn: cleared, and the cursor ring arc drawn.
+    expect(overlay.surface.callLog.some((e) => e.op === 'clearRect')).toBe(true);
+    expect(overlay.surface.callLog.some((e) => e.op === 'arc')).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('composites with smoothing OFF when zoomed in and ON when zoomed out', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const findSet = (surface: StubRasterSurface, prop: string): unknown[] =>
+      surface.callLog.filter((e) => e.op === 'set' && e.args[0] === prop).map((e) => e.args[1]);
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    // Zoom in to 20× → a view invalidation → recomposite with smoothing off.
+    screen.surface.callLog.length = 0;
+    engine.viewport.getViewport().zoomAtPoint(20, { x: 0, y: 0 });
+    raf.flush();
+    expect(findSet(screen.surface, 'imageSmoothingEnabled')).toContain(false);
+
+    // Zoom out below 1× → recomposite with smoothing on (clean down-scale).
+    screen.surface.callLog.length = 0;
+    engine.viewport.getViewport().zoomAtPoint(0.5, { x: 0, y: 0 });
+    raf.flush();
+    expect(findSet(screen.surface, 'imageSmoothingEnabled')).toContain(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('builds the checkerboard pattern tile once across many composited frames', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    // Count surfaces allocated at the checkerboard tile size (CHECKERBOARD_SQUARE_PX * 2 = 16).
+    const base = createTestStubRasterBackend();
+    const tileSurfaceSizes: string[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        if (w === 16 && h === 16) {
+          tileSurfaceSizes.push(`${w}x${h}`);
+        }
+        return base.createSurface(w, h);
+      },
+    };
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    // Checkerboard is on by default; the transparent paintDoc fills with it.
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+
+    // Force several composited frames (each recomposites and re-`createPattern`s).
+    for (let i = 0; i < 5; i++) {
+      engine.viewport.getViewport().zoomAtPoint(1 + i, { x: 0, y: 0 });
+      raf.flush();
+      await flushMicrotasks();
+    }
+
+    // The tile surface was built exactly once and reused (no per-frame rebuild).
+    expect(tileSurfaceSizes).toEqual(['16x16']);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- checker colors: theme-token feed → tile rebuild + recomposite ---------
+
+const fillStyleSets = (surface: StubRasterSurface): unknown[] =>
+  surface.callLog.filter((e) => e.op === 'set' && e.args[0] === 'fillStyle').map((e) => e.args[1]);
+
+describe('checker colors: fed-token tile rebuild', () => {
+  it('builds the fallback-colored tile when never fed, then rebuilds with fed colors and recomposites', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    // Capture every 16x16 checker tile surface (CHECKERBOARD_SQUARE_PX * 2).
+    const base = createTestStubRasterBackend();
+    const tiles: StubRasterSurface[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        if (w === 16 && h === 16) {
+          tiles.push(surface);
+        }
+        return surface;
+      },
+    };
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+
+    // First composite built the tile once, using the React-free fallback colors.
+    expect(tiles).toHaveLength(1);
+    expect(fillStyleSets(tiles[0]!)).toEqual([DEFAULT_CHECKER_COLORS.a, DEFAULT_CHECKER_COLORS.b]);
+
+    // Feed new (resolved-token) checker colors: the cached tile is dropped and
+    // rebuilt with the new colors on the next composite, which is forced to run.
+    engine.stores.checkerColors.set({ a: '#010101', b: '#020202' });
+    raf.flush();
+    await flushMicrotasks();
+
+    expect(tiles).toHaveLength(2);
+    expect(fillStyleSets(tiles[1]!)).toEqual(['#010101', '#020202']);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('does not rebuild the tile when fed colors are unchanged (equality-gated store)', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const base = createTestStubRasterBackend();
+    const tiles: StubRasterSurface[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        if (w === 16 && h === 16) {
+          tiles.push(surface);
+        }
+        return surface;
+      },
+    };
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    expect(tiles).toHaveLength(1);
+
+    // Re-feeding the SAME colors is a no-op (the store's equality check drops it),
+    // so no invalidation and no tile rebuild.
+    engine.stores.checkerColors.set({ ...DEFAULT_CHECKER_COLORS });
+    raf.flush();
+    await flushMicrotasks();
+    expect(tiles).toHaveLength(1);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- fitToView: content ∪ bbox (document rect retired as world bounds) ------
+
+const noLayerDoc = (overrides: Partial<CanvasDocumentContractV2> = {}): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 1000,
+  layers: [],
+  selectedLayerId: null,
+  version: 2,
+  width: 1000,
+  ...overrides,
+});
+
+describe('fitToView: content ∪ bbox', () => {
+  it('fits the bbox (not the larger doc rect) on an empty canvas', () => {
+    const { store } = createReactiveStore(noLayerDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    engine.surface.resize(400, 400, 1);
+
+    engine.viewport.fitToView();
+
+    // avail = 400 - 48*2 = 304; fitting the 100px bbox → 3.04. Fitting the 1000px
+    // doc rect would have been ~0.304 — the doc rect is no longer the fit target.
+    expect(engine.viewport.getViewport().getZoom()).toBeCloseTo(3.04, 2);
+    engine.lifecycle.dispose();
+  });
+
+  it('unions a renderable layer that lies beyond the bbox into the fit', () => {
+    // A raster layer 100x100 translated to (900,900): content extends to 1000, far
+    // past the 100px bbox. Fitting content ∪ bbox spans 0..1000 → zoom ~0.304.
+    const layer: CanvasLayerContract = {
+      blendMode: 'normal',
+      id: 'a',
+      isEnabled: true,
+      isLocked: false,
+      name: 'a',
+      opacity: 1,
+      source: { image: { height: 100, imageName: 'a', width: 100 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 900, y: 900 },
+      type: 'raster',
+    };
+    const { store } = createReactiveStore(noLayerDoc({ layers: [layer] }));
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    engine.surface.resize(400, 400, 1);
+
+    engine.viewport.fitToView();
+
+    // Union spans (0,0)..(1000,1000) = 1000px; avail 304 → 0.304.
+    expect(engine.viewport.getViewport().getZoom()).toBeCloseTo(0.304, 2);
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- transform session: param commit (image) + pixel bake (paint) ----------
+
+describe('transform session', () => {
+  it('image layer Apply commits one structural transform with the exact inverse', () => {
+    const { store } = createReactiveStore(selectedImageDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    engine.tools.setTool('transform');
+    engine.layers.updateTransformSession({ rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 });
+    dispatch.mockClear();
+    engine.layers.applyTransform();
+
+    const layerDispatches = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .filter((action) => action.type === 'updateCanvasLayer');
+    // Exactly one structural dispatch (the forward transform); no pixel work.
+    expect(layerDispatches).toHaveLength(1);
+    expect(layerDispatches[0]).toEqual({
+      id: 'a',
+      patch: { transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 } },
+      type: 'updateCanvasLayer',
+    });
+    expect(engine.stores.transformSession.get()).toBeNull();
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    // Undo dispatches the exact inverse (the captured start transform).
+    dispatch.mockClear();
+    engine.history.undo();
+    const undoDispatch = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .find((action) => action.type === 'updateCanvasLayer');
+    expect(undoDispatch).toEqual({
+      id: 'a',
+      patch: { transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 } },
+      type: 'updateCanvasLayer',
+    });
+
+    engine.lifecycle.dispose();
+  });
+
+  it('parametric (text) layer Apply commits ONE param transform, stays type text, no bake; undo restores', () => {
+    // Regression: parametric layers (shape/gradient/text) could not be transformed
+    // — `applyTransform` only handled image sources. Phase 5 "param for parametric":
+    // the transform commits as a param edit and the source stays editable-forever.
+    const textLayerDoc: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 100,
+      layers: [
+        {
+          blendMode: 'normal',
+          id: 't',
+          isEnabled: true,
+          isLocked: false,
+          name: 'Text',
+          opacity: 1,
+          source: {
+            align: 'left',
+            color: '#000000',
+            content: 'hi',
+            fontFamily: 'sans',
+            fontSize: 20,
+            fontWeight: 400,
+            lineHeight: 1.2,
+            type: 'text',
+          },
+          transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+          type: 'raster',
+        },
+      ],
+      selectedLayerId: 't',
+      version: 2,
+      width: 100,
+    };
+    const { store } = createReactiveStore(textLayerDoc);
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    engine.tools.setTool('transform');
+    // A session opened on the (now hit-testable) text layer.
+    expect(engine.stores.transformSession.get()).not.toBeNull();
+    engine.layers.updateTransformSession({ rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 });
+    dispatch.mockClear();
+    engine.layers.applyTransform();
+
+    const actions = dispatch.mock.calls.map((call) => call[0] as EngineTestAction);
+    const updates = actions.filter((a) => a.type === 'updateCanvasLayer');
+    // ONE param transform; source untouched (stays text) — no convert, no bake.
+    expect(updates).toHaveLength(1);
+    expect(updates[0]).toEqual({
+      id: 't',
+      patch: { transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 } },
+      type: 'updateCanvasLayer',
+    });
+    expect(actions.some((a) => a.type === 'convertCanvasLayer' || a.type === 'updateCanvasLayerSource')).toBe(false);
+    expect(engine.stores.transformSession.get()).toBeNull();
+
+    dispatch.mockClear();
+    engine.history.undo();
+    const undo = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .find((a) => a.type === 'updateCanvasLayer');
+    expect(undo).toEqual({
+      id: 't',
+      patch: { transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 } },
+      type: 'updateCanvasLayer',
+    });
+
+    engine.lifecycle.dispose();
+  });
+
+  it('handleEscapePriority cancels an open transform session (chain: transform → deselect)', () => {
+    const { store } = createReactiveStore(selectedImageDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    engine.tools.setTool('transform');
+    engine.layers.updateTransformSession({ rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 });
+    expect(engine.stores.transformSession.get()).not.toBeNull();
+
+    engine.tools.handleEscapePriority({ gestureWasActive: false });
+    expect(engine.stores.transformSession.get()).toBeNull();
+
+    engine.lifecycle.dispose();
+  });
+
+  it('an unchanged transform Apply cancels with no dispatch', () => {
+    const { store } = createReactiveStore(selectedImageDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    engine.tools.setTool('transform');
+    dispatch.mockClear();
+    engine.layers.applyTransform();
+
+    expect(dispatch.mock.calls.filter((c) => (c[0] as EngineTestAction).type === 'updateCanvasLayer')).toHaveLength(0);
+    expect(engine.stores.transformSession.get()).toBeNull();
+    expect(engine.stores.canUndo.get()).toBe(false);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('Cancel drops the session with no dispatch', () => {
+    const { store } = createReactiveStore(selectedImageDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+
+    engine.tools.setTool('transform');
+    engine.layers.updateTransformSession({ rotation: 0, scaleX: 3, scaleY: 3, x: 0, y: 0 });
+    dispatch.mockClear();
+    engine.layers.cancelTransform();
+
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.transformSession.get()).toBeNull();
+
+    engine.lifecycle.dispose();
+  });
+
+  it('paint layer Apply bakes pixels through the matrix, resets the transform, and composes one undo entry', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    // A paint layer that already carries a non-identity transform, so undo restores
+    // a transform distinct from the post-bake identity. Content-sized: it needs a
+    // persisted bitmap so its cache is non-empty (an empty paint layer is not
+    // transformable).
+    const movedPaint = paintDoc();
+    const movedLayer = movedPaint.layers[0] as CanvasRasterLayerContractV2;
+    movedLayer.source = {
+      bitmap: { height: 50, imageName: 'paint1-bmp', width: 50 },
+      offset: { x: 0, y: 0 },
+      type: 'paint',
+    };
+    movedLayer.transform = { rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 };
+    const { store } = createReactiveStore(movedPaint);
+    const dispatch = store.dispatch as Mock;
+    const bitmapStore = createSpyBitmapStore();
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const engine = createCanvasEngine({
+      backend,
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush(); // build the paint layer cache
+
+    const surfacesBeforeApply = surfaces.length;
+    const dirtyBefore = bitmapStore.markLayerDirty.mock.calls.length;
+
+    engine.tools.setTool('transform');
+    engine.layers.updateTransformSession({ rotation: 0, scaleX: 2, scaleY: 2, x: 10, y: 20 });
+    dispatch.mockClear();
+    engine.layers.applyTransform();
+
+    // A fresh CONTENT-sized surface (the transformed content bounds, 100×100 here)
+    // was allocated and drawn through the bake matrix. The 50×50 cache at scale 2 +
+    // offset (10,20) bakes to bounds {10,20,100,100}, so the surface is 100×100 and
+    // the bake transform's translation is shifted by the baked origin to (0,0).
+    const baked = surfaces[surfacesBeforeApply];
+    expect(baked).toBeDefined();
+    expect(baked!.width).toBe(100);
+    expect(baked!.height).toBe(100);
+    const setTransforms = baked!.callLog.filter((entry) => entry.op === 'setTransform');
+    // The non-identity setTransform carries the bake matrix scale (a=2, d=2), with
+    // its translation shifted into baked-local space (e=0, f=0).
+    expect(
+      setTransforms.some(
+        (entry) => entry.args[0] === 2 && entry.args[3] === 2 && entry.args[4] === 0 && entry.args[5] === 0
+      )
+    ).toBe(true);
+    expect(baked!.callLog.some((entry) => entry.op === 'drawImage')).toBe(true);
+    // Determinism: the bake always smooths (a doc-space resample, unlike the
+    // live composite which varies smoothing with zoom) rather than leaving it
+    // at whatever the fresh surface's context happens to default to.
+    expect(
+      baked!.callLog.some(
+        (entry) => entry.op === 'set' && entry.args[0] === 'imageSmoothingEnabled' && entry.args[1] === true
+      )
+    ).toBe(true);
+
+    // The reducer transform was reset to identity (pixel-free structural change).
+    const resetDispatch = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .find((action) => action.type === 'updateCanvasLayer');
+    expect(resetDispatch).toEqual({
+      id: 'paint1',
+      patch: { transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 } },
+      type: 'updateCanvasLayer',
+    });
+
+    // Baked pixels persist through the normal dirty path; session cleared; undoable.
+    expect(bitmapStore.markLayerDirty.mock.calls.length).toBeGreaterThan(dirtyBefore);
+    expect(engine.stores.transformSession.get()).toBeNull();
+    expect(engine.stores.canUndo.get()).toBe(true);
+
+    // Undo restores BOTH the old transform and the old pixels in one step.
+    dispatch.mockClear();
+    engine.history.undo();
+    const undoDispatch = dispatch.mock.calls
+      .map((call) => call[0] as EngineTestAction)
+      .find((action) => action.type === 'updateCanvasLayer');
+    expect(undoDispatch).toEqual({
+      id: 'paint1',
+      patch: { transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 } },
+      type: 'updateCanvasLayer',
+    });
+    expect(engine.stores.canRedo.get()).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('tears down the transform session on a document replace', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const { setDocument, store } = createReactiveStore(selectedImageDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    engine.tools.setTool('transform');
+    expect(engine.stores.transformSession.get()).not.toBeNull();
+
+    // A dims change is a wholesale document replacement.
+    setDocument({ ...selectedImageDoc(), height: 200, width: 200 }, 1);
+
+    expect(engine.stores.transformSession.get()).toBeNull();
+
+    engine.lifecycle.dispose();
+  });
+
+  it('cancels the session (and its preview override) when its layer is deleted mid-session', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+    const doc = selectedImageDoc();
+    const { setDocument, store } = createReactiveStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    engine.tools.setTool('transform');
+    engine.layers.updateTransformSession({ rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 5 });
+    expect(engine.stores.transformSession.get()).not.toBeNull();
+
+    // Delete the session's layer via an ordinary layer-array edit (same dims,
+    // same revision) — NOT a wholesale replace, so this exercises the
+    // `onLayersChanged` teardown rather than `onDocumentReplaced`'s.
+    setDocument({ ...doc, layers: [] });
+
+    expect(engine.stores.transformSession.get()).toBeNull();
+
+    engine.lifecycle.dispose();
+  });
+
+  // ---- temp-tool switch (space/alt hold) must not discard the session ----
+  //
+  // The pointer pipeline flags a modifier-hold switch (and its matching
+  // restore) with `{ temporary: true }` on `setTool` (see
+  // `pointerPipeline.test.ts`, "temporary modifier tools"). These tests drive
+  // that same seam directly against the engine: the public `CanvasEngine`
+  // type narrows `setTool` to one argument, but the runtime function accepts
+  // the pipeline's second (`opts`) argument, so the cast below exercises the
+  // exact call the pipeline makes on a real space/alt hold and release.
+  describe('temp-tool switch (space/alt hold)', () => {
+    it('preserves the session and its numeric edits, resuming after the hold ends', () => {
+      const raf = createControllableRaf();
+      vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+      vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+      const { store } = createReactiveStore(selectedImageDoc());
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      const screen = createFakeCanvas();
+      const overlay = createFakeCanvas();
+      engine.surface.attach(screen.element, overlay.element);
+      raf.flush();
+
+      engine.tools.setTool('transform');
+      // A numeric edit, as the options bar would drive.
+      engine.layers.updateTransformSession({ rotation: 0, scaleX: 2, scaleY: 1, x: 5, y: 0 });
+      const edited = { rotation: 0, scaleX: 2, scaleY: 1, x: 5, y: 0 };
+      expect(engine.stores.transformSession.get()?.transform).toEqual(edited);
+
+      const setTool = engine.tools.setTool as (id: ToolId, opts?: { temporary?: boolean }) => void;
+
+      setTool('view', { temporary: true }); // space down
+      expect(engine.stores.activeTool.get()).toBe('view');
+      // The session — and the numeric edit — survive the hold.
+      expect(engine.stores.transformSession.get()?.transform).toEqual(edited);
+
+      setTool('transform', { temporary: true }); // space up: resume
+      expect(engine.stores.activeTool.get()).toBe('transform');
+      // Resuming does not reopen the session from the layer's committed
+      // transform, discarding the edit.
+      expect(engine.stores.transformSession.get()?.transform).toEqual(edited);
+
+      engine.lifecycle.dispose();
+    });
+
+    it('a REAL tool switch (not temporary) still cancels the session', () => {
+      const raf = createControllableRaf();
+      vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+      vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+      const { store } = createReactiveStore(selectedImageDoc());
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      const screen = createFakeCanvas();
+      const overlay = createFakeCanvas();
+      engine.surface.attach(screen.element, overlay.element);
+      raf.flush();
+
+      engine.tools.setTool('transform');
+      expect(engine.stores.transformSession.get()).not.toBeNull();
+
+      engine.tools.setTool('view'); // a real switch — no `{ temporary: true }`
+
+      expect(engine.stores.transformSession.get()).toBeNull();
+
+      engine.lifecycle.dispose();
+    });
+
+    it('cancels cleanly when the session layer is deleted mid-hold, instead of resurrecting it on resume', () => {
+      const raf = createControllableRaf();
+      vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+      vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+
+      const doc = selectedImageDoc();
+      const { setDocument, store } = createReactiveStore(doc);
+      const engine = createCanvasEngine({
+        backend: createTestStubRasterBackend(),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: 'p1',
+        store,
+      });
+      const screen = createFakeCanvas();
+      const overlay = createFakeCanvas();
+      engine.surface.attach(screen.element, overlay.element);
+      raf.flush();
+
+      engine.tools.setTool('transform');
+      expect(engine.stores.transformSession.get()).not.toBeNull();
+
+      const setTool = engine.tools.setTool as (id: ToolId, opts?: { temporary?: boolean }) => void;
+      setTool('view', { temporary: true }); // space down
+
+      // The session's layer is deleted while temp-switched away (e.g. via the
+      // layers panel) — the layer-change teardown cancels the session
+      // immediately, regardless of which tool is active.
+      setDocument({ ...doc, layers: [] });
+      expect(engine.stores.transformSession.get()).toBeNull();
+
+      setTool('transform', { temporary: true }); // space up: resume
+      // Resuming must not resurrect a session against the now layer-less
+      // document.
+      expect(engine.stores.transformSession.get()).toBeNull();
+
+      engine.lifecycle.dispose();
+    });
+  });
+});
+
+// ---- Selection subsystem ------------------------------------------------
+
+const lockedPaintDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [
+    {
+      blendMode: 'normal',
+      id: 'paint1',
+      isEnabled: true,
+      isLocked: true,
+      name: 'paint1',
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    },
+  ],
+  selectedLayerId: 'paint1',
+  version: 2,
+  width: 100,
+});
+
+describe('engine selection: select all / deselect / invert + hasSelection store', () => {
+  it('selectAll sets hasSelection; deselect clears it', () => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const { store } = createFakeStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    expect(engine.stores.hasSelection.get()).toBe(false);
+    engine.selection.selectAll();
+    expect(engine.stores.hasSelection.get()).toBe(true);
+    engine.selection.deselect();
+    expect(engine.stores.hasSelection.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('invertSelection of an empty selection selects everything', () => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const { store } = createFakeStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    engine.selection.invertSelection();
+    expect(engine.stores.hasSelection.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('engine selection: fill / erase', () => {
+  const makeEngine = (doc: CanvasDocumentContractV2) => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const { store } = createFakeStore(doc);
+    const bitmapStore = createSpyBitmapStore();
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    return { bitmapStore, engine };
+  };
+
+  it('fills an empty selected paint control without adding a raster layer', () => {
+    const h = createControlSelectionHarness({ source: { bitmap: null, type: 'paint' } });
+    h.engine.selection.selectAll();
+    h.engine.selection.fillSelection();
+    expect(h.engine.document.getDocument()!.layers).toHaveLength(1);
+    expect(h.engine.document.getDocument()!.layers[0]).toMatchObject({ id: 'control', type: 'control' });
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('erases an existing selected paint control without adding a raster layer', async () => {
+    const h = createControlSelectionHarness({
+      source: { bitmap: { height: 10, imageName: 'paint-bitmap', width: 10 }, type: 'paint' },
+    });
+    await h.publishInitialCache();
+    h.engine.selection.selectAll();
+    h.engine.selection.eraseSelection();
+    expect(h.engine.document.getDocument()!.layers).toHaveLength(1);
+    expect(h.engine.document.getDocument()!.layers[0]).toMatchObject({ id: 'control', type: 'control' });
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each(['fill', 'erase'] as const)('materializes an image control and %ss it as one undo step', async (kind) => {
+    const h = createControlSelectionHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 },
+    });
+    await h.publishInitialCache();
+    const before = structuredClone(h.engine.document.getDocument()!.layers[0]);
+    h.engine.selection.selectAll();
+    if (kind === 'fill') {
+      h.engine.selection.fillSelection();
+    } else {
+      h.engine.selection.eraseSelection();
+    }
+    const after = structuredClone(h.engine.document.getDocument()!.layers[0]);
+    expect(after).toMatchObject({ id: 'control', source: { type: 'paint' }, type: 'control' });
+    h.engine.history.undo();
+    expect(h.engine.document.getDocument()!.layers[0]).toEqual(before);
+    h.engine.history.redo();
+    expect(h.engine.document.getDocument()!.layers[0]).toEqual(after);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not materialize an image control when Erase has no overlapping pixels', async () => {
+    const h = createControlSelectionHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 50, y: 50 },
+    });
+    await h.publishInitialCache();
+    const before = structuredClone(h.engine.document.getDocument());
+    h.engine.tools.setTool('lasso');
+    h.overlay.fire('pointerdown', pointerAt(0, 0));
+    h.overlay.fire('pointermove', pointerAt(10, 0));
+    h.overlay.fire('pointermove', pointerAt(10, 10));
+    h.overlay.fire('pointermove', pointerAt(0, 10));
+    h.overlay.fire('pointerup', pointerAt(0, 0, { buttons: 0 }));
+    h.engine.selection.eraseSelection();
+    expect(h.engine.document.getDocument()).toEqual(before);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.suspendLayer).not.toHaveBeenCalled();
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each([
+    ['locked', { isLocked: true }],
+    ['disabled', { isEnabled: false }],
+  ] as const)('selection editing leaves a %s control unchanged', (_scenario, patch) => {
+    const h = createControlSelectionHarness({ source: { bitmap: null, type: 'paint' }, ...patch });
+    const before = structuredClone(h.engine.document.getDocument());
+    h.engine.selection.selectAll();
+    h.engine.selection.fillSelection();
+    expect(h.engine.document.getDocument()).toEqual(before);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('selection editing leaves a not-ready image control unchanged', () => {
+    const h = createControlSelectionHarness({
+      source: { image: { height: 10, imageName: 'pending-image', width: 10 }, type: 'image' },
+    });
+    const before = structuredClone(h.engine.document.getDocument());
+    h.engine.selection.selectAll();
+    h.engine.selection.fillSelection();
+    expect(h.engine.document.getDocument()).toEqual(before);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each(['fill', 'erase'] as const)('does not publish a byte-identical direct control %s', async (kind) => {
+    const h = createControlSelectionHarness({
+      source: { bitmap: { height: 10, imageName: 'paint-bitmap', width: 10 }, type: 'paint' },
+    });
+    await h.publishInitialCache();
+    h.engine.tools.setTool('lasso');
+    h.overlay.fire('pointerdown', pointerAt(0, 0));
+    h.overlay.fire('pointermove', pointerAt(5, 0));
+    h.overlay.fire('pointermove', pointerAt(5, 5));
+    h.overlay.fire('pointermove', pointerAt(0, 5));
+    h.overlay.fire('pointerup', pointerAt(0, 0, { buttons: 0 }));
+    const beforeDocument = structuredClone(h.engine.document.getDocument());
+    const beforeCache = await snapshotLayerCache(h.engine, 'control');
+    const beforeThumbnailVersion = h.engine.stores.thumbnailVersion.get('control');
+    h.setSelectionPixelWrites(false);
+
+    if (kind === 'fill') {
+      h.engine.selection.fillSelection();
+    } else {
+      h.engine.selection.eraseSelection();
+    }
+
+    expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.engine.stores.thumbnailVersion.get('control')).toBe(beforeThumbnailVersion);
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe('ok');
+    if (restored.status === 'ok') {
+      expect(restored.surface).toBe(beforeCache.surface);
+      expect(restored.rect).toEqual(beforeCache.rect);
+      expect(restored.guard.cacheVersion).toBe(beforeCache.version);
+    }
+
+    h.setSelectionPixelWrites(true);
+    if (kind === 'fill') {
+      h.engine.selection.fillSelection();
+    } else {
+      h.engine.selection.eraseSelection();
+    }
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('restores direct control cache growth after a byte-identical fill', async () => {
+    const h = createControlSelectionHarness({ source: { bitmap: null, type: 'paint' } });
+    const beforeDocument = structuredClone(h.engine.document.getDocument());
+    const beforeExport = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    const beforeThumbnailVersion = h.engine.stores.thumbnailVersion.get('control');
+    h.engine.selection.selectAll();
+    h.setSelectionPixelWrites(false);
+
+    h.engine.selection.fillSelection();
+
+    expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.engine.stores.thumbnailVersion.get('control')).toBe(beforeThumbnailVersion);
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe(beforeExport.status);
+
+    h.setSelectionPixelWrites(true);
+    h.engine.selection.fillSelection();
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('rolls back a byte-identical materialized control selection edit', async () => {
+    const h = createControlSelectionHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 },
+    });
+    await h.publishInitialCache();
+    const beforeDocument = structuredClone(h.engine.document.getDocument());
+    const beforeCache = await snapshotLayerCache(h.engine, 'control');
+    const beforeThumbnailVersion = h.engine.stores.thumbnailVersion.get('control');
+    h.engine.selection.selectAll();
+    h.setSelectionPixelWrites(false);
+
+    h.engine.selection.fillSelection();
+
+    expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.engine.stores.thumbnailVersion.get('control')).toBe(beforeThumbnailVersion);
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe('ok');
+    if (restored.status === 'ok') {
+      expect(restored.surface).toBe(beforeCache.surface);
+      expect(restored.rect).toEqual(beforeCache.rect);
+      expect(restored.guard.cacheVersion).toBe(beforeCache.version);
+    }
+
+    h.setSelectionPixelWrites(true);
+    h.engine.selection.fillSelection();
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledTimes(2);
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledTimes(2);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('keeps materialized no-effect rollback authoritative when growth restoration throws once', async () => {
+    const h = createControlSelectionHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 },
+    });
+    await h.publishInitialCache();
+    const beforeDocument = structuredClone(h.engine.document.getDocument());
+    const beforeCache = await snapshotLayerCache(h.engine, 'control');
+    const beforeThumbnailVersion = h.engine.stores.thumbnailVersion.get('control');
+    const createSurface = h.backend.createSurface.bind(h.backend);
+    let didThrow = false;
+    vi.spyOn(h.backend, 'createSurface').mockImplementation((width, height) => {
+      const surface = createSurface(width, height);
+      const resize = surface.resize.bind(surface);
+      surface.resize = (nextWidth, nextHeight) => {
+        if (!didThrow && surface.width === 100 && nextWidth === 20 && nextHeight === 20) {
+          didThrow = true;
+          throw new Error('selection rollback restoration failed');
+        }
+        resize(nextWidth, nextHeight);
+      };
+      return surface;
+    });
+    h.engine.selection.selectAll();
+    h.setSelectionPixelWrites(false);
+
+    expect(() => h.engine.selection.fillSelection()).toThrow('selection rollback restoration failed');
+
+    expect(didThrow).toBe(true);
+    expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledOnce();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    expect(h.engine.stores.thumbnailVersion.get('control')).toBe(beforeThumbnailVersion);
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe('ok');
+    if (restored.status === 'ok') {
+      expect(restored.surface).toBe(beforeCache.surface);
+      expect(restored.rect).toEqual(beforeCache.rect);
+      expect(restored.guard.cacheVersion).toBe(beforeCache.version);
+    }
+
+    vi.mocked(h.backend.createSurface).mockRestore();
+    h.setSelectionPixelWrites(true);
+    h.engine.selection.fillSelection();
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    expect(h.bitmapStore.suspendLayer).toHaveBeenCalledTimes(2);
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledTimes(2);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('rolls back a direct control selection edit when masked compositing fails', async () => {
+    const h = createControlSelectionHarness({
+      source: { bitmap: { height: 10, imageName: 'paint-bitmap', width: 10 }, type: 'paint' },
+    });
+    await h.publishInitialCache();
+    const beforeDocument = structuredClone(h.engine.document.getDocument());
+    const beforeCache = await snapshotLayerCache(h.engine, 'control');
+    const originalCtx = beforeCache.surface.ctx;
+    const capturedReads: ImageData[] = [];
+    const failingCtx = new Proxy(originalCtx, {
+      get(target, property, receiver) {
+        const value = Reflect.get(target, property, receiver);
+        if (property === 'getImageData' && typeof value === 'function') {
+          return (...args: unknown[]) => {
+            const result = Reflect.apply(value, target, args) as ImageData;
+            capturedReads.push(result);
+            return result;
+          };
+        }
+        if (property === 'drawImage' && typeof value === 'function') {
+          return (...args: unknown[]) => {
+            Reflect.apply(value, target, args);
+            throw new Error('selection compositing failed');
+          };
+        }
+        return value;
+      },
+    });
+    Object.defineProperty(beforeCache.surface, 'ctx', { configurable: true, value: failingCtx });
+    h.engine.tools.setTool('lasso');
+    h.overlay.fire('pointerdown', pointerAt(0, 0));
+    h.overlay.fire('pointermove', pointerAt(5, 0));
+    h.overlay.fire('pointermove', pointerAt(5, 5));
+    h.overlay.fire('pointermove', pointerAt(0, 5));
+    h.overlay.fire('pointerup', pointerAt(0, 0, { buttons: 0 }));
+
+    expect(() => h.engine.selection.fillSelection()).toThrow('selection compositing failed');
+
+    expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(capturedReads[0]).toMatchObject({ height: 10, width: 10 });
+    expect(capturedReads.at(-1)).toMatchObject({ height: 5, width: 5 });
+    expect(
+      (beforeCache.surface as StubRasterSurface).callLog.filter((entry) => entry.op === 'putImageData').at(-1)?.args[0]
+    ).toBe(capturedReads[0]);
+
+    Object.defineProperty(beforeCache.surface, 'ctx', { configurable: true, value: originalCtx });
+    h.engine.selection.fillSelection();
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('rolls back a materialized control selection edit when masked compositing fails', async () => {
+    const h = createControlSelectionHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 },
+    });
+    await h.publishInitialCache();
+    const beforeDocument = structuredClone(h.engine.document.getDocument());
+    const beforeCache = await snapshotLayerCache(h.engine, 'control');
+    const createSurface = h.backend.createSurface.bind(h.backend);
+    vi.spyOn(h.backend, 'createSurface').mockImplementation((width, height) => {
+      const surface = createSurface(width, height);
+      const originalCtx = surface.ctx;
+      const failingCtx = new Proxy(originalCtx, {
+        get(target, property, receiver) {
+          const value = Reflect.get(target, property, receiver);
+          if (property !== 'drawImage' || typeof value !== 'function') {
+            return value;
+          }
+          return (...args: unknown[]) => {
+            const result = Reflect.apply(value, target, args);
+            if (target.globalCompositeOperation === 'destination-out') {
+              throw new Error('selection compositing failed');
+            }
+            return result;
+          };
+        },
+      });
+      Object.defineProperty(surface, 'ctx', { configurable: true, value: failingCtx });
+      return surface;
+    });
+    h.engine.selection.selectAll();
+
+    expect(() => h.engine.selection.eraseSelection()).toThrow('selection compositing failed');
+
+    expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe('ok');
+    if (restored.status === 'ok') {
+      expect(restored.surface).toBe(beforeCache.surface);
+      expect(restored.rect).toEqual(beforeCache.rect);
+      expect(restored.guard.cacheVersion).toBe(beforeCache.version);
+    }
+
+    vi.mocked(h.backend.createSurface).mockRestore();
+    h.engine.selection.eraseSelection();
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('preserves transaction-owned rollback when a materialized control selection commit fails', async () => {
+    const h = createControlSelectionHarness({
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 2, scaleY: 2, x: 5, y: 6 },
+    });
+    await h.publishInitialCache();
+    const beforeDocument = structuredClone(h.engine.document.getDocument());
+    const beforeCache = await snapshotLayerCache(h.engine, 'control');
+    h.engine.selection.selectAll();
+    historyPreparationFaults.layerSnapshot = true;
+
+    expect(() => h.engine.selection.fillSelection()).toThrow('layer snapshot preparation failed');
+
+    expect(h.engine.document.getDocument()).toEqual(beforeDocument);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    expect(h.bitmapStore.markLayerDirty).not.toHaveBeenCalled();
+    expect(h.bitmapStore.releaseSuspendedLayer).toHaveBeenCalledOnce();
+    const restored = await h.engine.exports.exportLayerPixels('control', { includeDisabled: true });
+    expect(restored.status).toBe('ok');
+    if (restored.status === 'ok') {
+      expect(restored.surface).toBe(beforeCache.surface);
+      expect(restored.rect).toEqual(beforeCache.rect);
+      expect(restored.guard.cacheVersion).toBe(beforeCache.version);
+    }
+    h.engine.lifecycle.dispose();
+  });
+
+  it('fillSelection on the selected paint layer records one undoable edit + persists', () => {
+    const { bitmapStore, engine } = makeEngine(paintDoc());
+    engine.selection.selectAll();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.selection.fillSelection();
+    expect(engine.stores.canUndo.get()).toBe(true);
+    expect(bitmapStore.markLayerDirty).toHaveBeenCalledWith('paint1');
+    // Undo restores (canRedo becomes available).
+    engine.history.undo();
+    expect(engine.stores.canRedo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('blocks paint without closing a guarded operation', async () => {
+    const { engine } = makeEngine(paintDoc());
+    engine.selection.selectAll();
+    engine.selection.fillSelection();
+    const exported = await engine.exports.exportLayerPixels('paint1');
+    if (exported.status !== 'ok') {
+      throw new Error('expected published paint pixels');
+    }
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(engine).controller.start({
+      cleanupPreview,
+      guard: exported.guard,
+      identity: { kind: 'filter', layerId: 'paint1', projectId: 'p1' },
+    });
+
+    engine.selection.fillSelection();
+
+    expect(cleanupPreview).not.toHaveBeenCalled();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'filter' },
+      status: 'active',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it('cache clear cancels a guarded operation and cleans its preview', async () => {
+    const { engine } = makeEngine(paintDoc());
+    engine.selection.selectAll();
+    engine.selection.fillSelection();
+    const exported = await engine.exports.exportLayerPixels('paint1');
+    if (exported.status !== 'ok') {
+      throw new Error('expected published paint pixels');
+    }
+    const cleanupPreview = vi.fn();
+    getCanvasOperations(engine).controller.start({
+      cleanupPreview,
+      guard: exported.guard,
+      identity: { kind: 'filter', layerId: 'paint1', projectId: 'p1' },
+    });
+
+    await engine.diagnostics.clearCaches();
+
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    engine.lifecycle.dispose();
+  });
+
+  it('eraseSelection records one undoable edit (on existing content)', () => {
+    const { engine } = makeEngine(paintDoc());
+    engine.selection.selectAll();
+    // Content-sized: erase only affects EXISTING pixels, so give the layer content
+    // first (a fill grows the empty paint cache to the selection). Then erase records
+    // its own edit within that extent.
+    engine.selection.fillSelection();
+    engine.selection.eraseSelection();
+    expect(engine.stores.canUndo.get()).toBe(true);
+    engine.lifecycle.dispose();
+  });
+
+  it('eraseSelection is a no-op on an EMPTY paint layer (no pixels to erase)', () => {
+    const { engine } = makeEngine(paintDoc());
+    engine.selection.selectAll();
+    engine.selection.eraseSelection();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('fillSelection is a no-op with no selection', () => {
+    const { engine } = makeEngine(paintDoc());
+    engine.selection.fillSelection();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('fillSelection is a no-op on an image-source layer (deferred to rasterize task)', () => {
+    const { engine } = makeEngine(imageSelectedDoc());
+    engine.selection.selectAll();
+    engine.selection.fillSelection();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('fillSelection is a no-op on a transparency-locked EMPTY layer (source-atop clamps to existing pixels)', () => {
+    const doc = paintDoc();
+    const target = doc.layers[0];
+    if (target?.type === 'raster') {
+      target.isTransparencyLocked = true;
+    }
+    const { engine } = makeEngine(doc);
+    engine.selection.selectAll();
+    engine.selection.fillSelection();
+    // The layer has no existing pixels, so a transparency-locked (source-atop) fill
+    // lands nothing — no undoable edit.
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('fillSelection is a no-op on a locked paint layer', () => {
+    const { engine } = makeEngine(lockedPaintDoc());
+    engine.selection.selectAll();
+    engine.selection.fillSelection();
+    expect(engine.stores.canUndo.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+
+  it('clearCaches flushes pending bitmap uploads before invalidating (unflushed strokes survive)', async () => {
+    const { bitmapStore, engine } = makeEngine(paintDoc());
+    // The debug "Clear caches" action must persist any in-flight (debounced) paint
+    // upload before it drops the layer caches — otherwise an unflushed stroke is lost.
+    await engine.diagnostics.clearCaches();
+    expect(bitmapStore.flushPendingUploads).toHaveBeenCalledTimes(1);
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('engine selection: marching ants animation + overlay-only', () => {
+  it('a selection redraws the overlay with ants and never composites the document', async () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+
+    screen.surface.callLog.length = 0;
+    overlay.surface.callLog.length = 0;
+
+    engine.selection.selectAll();
+    raf.flush();
+
+    // Overlay redrawn (ants stroked); the screen composite never ran.
+    const compositeOps = screen.surface.callLog.filter(
+      (e) => e.op === 'drawImage' || e.op === 'clearRect' || e.op === 'fillRect'
+    );
+    expect(compositeOps).toHaveLength(0);
+    expect(overlay.surface.callLog.some((e) => e.op === 'stroke')).toBe(true);
+
+    engine.lifecycle.dispose();
+  });
+
+  it('stops the ants loop (no pending frames) on deselect and on detach', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createFakeCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+
+    // With a selection the loop keeps rescheduling itself frame after frame.
+    engine.selection.selectAll();
+    raf.flush();
+    raf.flush();
+    expect(raf.pendingCount()).toBeGreaterThan(0);
+
+    // Deselect stops it: after draining, nothing reschedules.
+    engine.selection.deselect();
+    raf.flush();
+    expect(raf.pendingCount()).toBe(0);
+
+    // Re-select, then detach: the loop must not leak a pending frame.
+    engine.selection.selectAll();
+    raf.flush();
+    expect(raf.pendingCount()).toBeGreaterThan(0);
+    engine.surface.detach();
+    expect(raf.pendingCount()).toBe(0);
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('engine selection: lasso commit through the pipeline', () => {
+  it('a lasso drag commits a selection (hasSelection true) without dispatching', () => {
+    const raf = createControllableRaf();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('Path2D', class FakePath2D {});
+
+    const { store } = createReactiveStore(paintDoc());
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const screen = createFakeCanvas();
+    const overlay = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    engine.tools.setTool('lasso');
+    raf.flush();
+    dispatch.mockClear();
+
+    overlay.fire('pointerdown', pointerAt(10, 10));
+    overlay.fire('pointermove', pointerAt(40, 10));
+    overlay.fire('pointermove', pointerAt(40, 40));
+    overlay.fire('pointerup', pointerAt(10, 40, { buttons: 0 }));
+
+    expect(engine.stores.hasSelection.get()).toBe(true);
+    // Selection is transient: no reducer traffic from the lasso gesture.
+    expect(dispatch).not.toHaveBeenCalled();
+
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('engine selection: document replace clears the selection', () => {
+  it('a wholesale document swap deselects', () => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const { setDocument, store } = createReactiveStore(paintDoc());
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    engine.selection.selectAll();
+    expect(engine.stores.hasSelection.get()).toBe(true);
+    // A new document revision replaces the mirror.
+    setDocument(paintDoc(), 1);
+    expect(engine.stores.hasSelection.get()).toBe(false);
+    engine.lifecycle.dispose();
+  });
+});
+
+// ---- text edit session: create/edit commit, cancel, teardown ---------------
+
+describe('text edit session', () => {
+  const textSource = (over: Partial<Extract<CanvasLayerSourceContract, { type: 'text' }>> = {}) => ({
+    align: 'left' as const,
+    color: '#112233',
+    content: 'hello',
+    fontFamily: 'Inter',
+    fontSize: 20,
+    fontWeight: 400,
+    lineHeight: 1.2,
+    type: 'text' as const,
+    ...over,
+  });
+
+  const textDoc = (over: Partial<CanvasDocumentContractV2> = {}): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers: [
+      {
+        blendMode: 'normal',
+        id: 'txt1',
+        isEnabled: true,
+        isLocked: false,
+        name: 'Text 1',
+        opacity: 1,
+        source: textSource(),
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 5, y: 6 },
+        type: 'raster',
+      },
+    ],
+    selectedLayerId: 'txt1',
+    version: 2,
+    width: 100,
+    ...over,
+  });
+
+  const makeEngine = (doc: CanvasDocumentContractV2) => {
+    const { setDocument, store } = createReactiveStore(doc);
+    const dispatch = store.dispatch as Mock;
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    const layerActions = () => dispatch.mock.calls.map((call) => call[0] as EngineTestAction);
+    return { dispatch, engine, layerActions, setDocument };
+  };
+
+  it('create-mode commit dispatches ONE addCanvasLayer with the typed content; undo removes it', () => {
+    const { dispatch, engine, layerActions } = makeEngine(paintDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextCreate({ x: 10, y: 20 });
+    expect(engine.stores.textEditSession.get()?.mode).toBe('create');
+
+    dispatch.mockClear();
+    engine.layers.commitTextEdit('Typed here');
+
+    const adds = layerActions().filter((a) => a.type === 'addCanvasLayer');
+    expect(adds).toHaveLength(1);
+    const forward = adds[0];
+    if (forward?.type === 'addCanvasLayer' && forward.layer.type === 'raster' && forward.layer.source.type === 'text') {
+      expect(forward.layer.source.content).toBe('Typed here');
+      expect(forward.layer.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 });
+    } else {
+      throw new Error('expected an addCanvasLayer with a text source');
+    }
+    expect(engine.stores.textEditSession.get()).toBeNull();
+
+    dispatch.mockClear();
+    engine.history.undo();
+    const removes = layerActions().filter((a) => a.type === 'removeCanvasLayers');
+    expect(removes).toHaveLength(1);
+    engine.lifecycle.dispose();
+  });
+
+  it('an empty create-mode commit dispatches nothing (cancel semantics)', () => {
+    const { dispatch, engine } = makeEngine(paintDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextCreate({ x: 0, y: 0 });
+    dispatch.mockClear();
+    engine.layers.commitTextEdit('   ');
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('edit-mode commit dispatches ONE updateCanvasLayerSource with the exact inverse', () => {
+    const { dispatch, engine, layerActions } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    expect(engine.stores.textEditSession.get()?.mode).toBe('edit');
+
+    dispatch.mockClear();
+    engine.layers.commitTextEdit('changed');
+
+    const edits = layerActions().filter((a) => a.type === 'updateCanvasLayerSource');
+    expect(edits).toHaveLength(1);
+    const forward = edits[0];
+    if (forward?.type === 'updateCanvasLayerSource' && forward.source.type === 'text') {
+      expect(forward.id).toBe('txt1');
+      expect(forward.source.content).toBe('changed');
+    } else {
+      throw new Error('expected an updateCanvasLayerSource text edit');
+    }
+
+    dispatch.mockClear();
+    engine.history.undo();
+    const inverse = layerActions().find((a) => a.type === 'updateCanvasLayerSource');
+    if (inverse?.type === 'updateCanvasLayerSource' && inverse.source.type === 'text') {
+      expect(inverse.source.content).toBe('hello');
+    } else {
+      throw new Error('expected the inverse to restore the original content');
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('folds a live style change into the single edit commit', () => {
+    const { dispatch, engine, layerActions } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    engine.layers.updateTextEditStyle({ color: '#ff0000', fontSize: 40 });
+
+    dispatch.mockClear();
+    engine.layers.commitTextEdit('hello');
+
+    const edits = layerActions().filter((a) => a.type === 'updateCanvasLayerSource');
+    expect(edits).toHaveLength(1);
+    const forward = edits[0];
+    if (forward?.type === 'updateCanvasLayerSource' && forward.source.type === 'text') {
+      expect(forward.source.color).toBe('#ff0000');
+      expect(forward.source.fontSize).toBe(40);
+      expect(forward.source.content).toBe('hello');
+    } else {
+      throw new Error('expected the folded style change');
+    }
+    engine.lifecycle.dispose();
+  });
+
+  it('an unchanged edit-mode commit dispatches nothing', () => {
+    const { dispatch, engine } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    dispatch.mockClear();
+    engine.layers.commitTextEdit('hello');
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('cancel drops the session with no dispatch', () => {
+    const { dispatch, engine } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    dispatch.mockClear();
+    engine.layers.cancelTextEdit();
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('does not open an edit session on a locked text layer', () => {
+    const { engine } = makeEngine(
+      textDoc({
+        layers: [
+          {
+            blendMode: 'normal',
+            id: 'txt1',
+            isEnabled: true,
+            isLocked: true,
+            name: 'Text 1',
+            opacity: 1,
+            source: textSource(),
+            transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+            type: 'raster',
+          },
+        ],
+      })
+    );
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('a temporary tool switch (space-hold) preserves the open session', () => {
+    const { engine } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    expect(engine.stores.textEditSession.get()).not.toBeNull();
+
+    // Space-hold switches to the view tool temporarily; the session must survive.
+    (engine.tools.setTool as (id: ToolId, opts?: { temporary?: boolean }) => void)('view', { temporary: true });
+    expect(engine.stores.textEditSession.get()).not.toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('a real tool switch away from the text tool tears the session down', () => {
+    const { engine } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    expect(engine.stores.textEditSession.get()).not.toBeNull();
+
+    engine.tools.setTool('brush');
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('drops the session on a wholesale document replace', () => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const { engine, setDocument } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    expect(engine.stores.textEditSession.get()).not.toBeNull();
+    setDocument(paintDoc(), 1);
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('drops the session on dispose', () => {
+    const { engine } = makeEngine(paintDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextCreate({ x: 0, y: 0 });
+    expect(engine.stores.textEditSession.get()).not.toBeNull();
+    engine.lifecycle.dispose();
+    expect(engine.stores.textEditSession.get()).toBeNull();
+  });
+
+  // ---- click-elsewhere-to-commit (pointerdown / Escape) ----
+  //
+  // Regression: `commitTextEdit` only fired on the portal's blur, but the pointer
+  // pipeline `preventDefault`s a canvas pointerdown (suppressing that blur), and
+  // the mid-gesture guard swallowed any blur that did land. The commit now runs
+  // engine-side on pointerdown (before a gesture starts), reading the live portal
+  // content via a registered reader; Escape cancels a defocused session via the
+  // engine's escape ladder. These drive that engine-side logic directly.
+
+  it('commitOpenTextSession reads the registered content reader and commits the create', () => {
+    const { engine, layerActions } = makeEngine(paintDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextCreate({ x: 10, y: 20 });
+    engine.layers.setTextEditContentReader(() => 'live typed text');
+
+    expect(engine.layers.commitOpenTextSession()).toBe(true);
+
+    const adds = layerActions().filter((a) => a.type === 'addCanvasLayer');
+    expect(adds).toHaveLength(1);
+    const add = adds[0];
+    if (add?.type === 'addCanvasLayer' && add.layer.type === 'raster' && add.layer.source.type === 'text') {
+      expect(add.layer.source.content).toBe('live typed text');
+    } else {
+      throw new Error('expected an addCanvasLayer with the live reader content');
+    }
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('commitOpenTextSession returns false when no session is open', () => {
+    const { dispatch, engine } = makeEngine(paintDoc());
+    expect(engine.layers.commitOpenTextSession()).toBe(false);
+    expect(dispatch).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+
+  it('commitOpenTextSession falls back to the session content when no reader is registered', () => {
+    const { dispatch, engine } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1'); // session content = 'hello'
+    dispatch.mockClear();
+
+    expect(engine.layers.commitOpenTextSession()).toBe(true);
+    // No reader → uses the session's own content ('hello') → unchanged edit → no dispatch.
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('a second commit after the session closed is a no-op (one commit per close)', () => {
+    const { dispatch, engine, layerActions } = makeEngine(paintDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextCreate({ x: 0, y: 0 });
+    engine.layers.setTextEditContentReader(() => 'once');
+    expect(engine.layers.commitOpenTextSession()).toBe(true);
+    dispatch.mockClear();
+    // The portal's onBlur would re-fire commitTextEdit after the pointerdown commit;
+    // the session is already null, so it dispatches nothing.
+    engine.layers.commitTextEdit('once');
+    expect(engine.layers.commitOpenTextSession()).toBe(false);
+    expect(layerActions().filter((a) => a.type === 'addCanvasLayer')).toHaveLength(0);
+    engine.lifecycle.dispose();
+  });
+
+  it('handleEscapePriority cancels a defocused-but-open text session (no dispatch)', () => {
+    const { dispatch, engine } = makeEngine(textDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextEdit('txt1');
+    dispatch.mockClear();
+
+    engine.tools.handleEscapePriority({ gestureWasActive: false });
+    expect(engine.stores.textEditSession.get()).toBeNull();
+    expect(dispatch).not.toHaveBeenCalled();
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('contextMenuLayerIdAt (canvas right-click target)', () => {
+  const controlLayer = (id: string): CanvasLayerContract => ({
+    adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name: id,
+    opacity: 1,
+    source: { image: { height: 10, imageName: id, width: 10 }, type: 'image' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'control',
+    withTransparencyEffect: false,
+  });
+
+  // A raster at index 0 with a control layer above it, both covering [0,10]². At
+  // the default viewport (zoom 1, no pan) a screen point maps 1:1 to document space.
+  const stackedDoc = (): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers: [rasterLayer('raster'), controlLayer('control')],
+    selectedLayerId: null,
+    version: 2,
+    width: 100,
+  });
+
+  const makeEngine = (doc: CanvasDocumentContractV2) => {
+    const { store } = createFakeStore(doc);
+    const engine = createCanvasEngine({
+      backend: createTestStubRasterBackend(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      store,
+    });
+    return engine;
+  };
+
+  it('returns the composite-top layer at the point (control over raster, batch finding N1)', () => {
+    const engine = makeEngine(stackedDoc());
+    // The raster is earlier in the array but the control composites above it.
+    expect(engine.tools.contextMenuLayerIdAt({ x: 5, y: 5 })).toBe('control');
+    engine.lifecycle.dispose();
+  });
+
+  it('returns null on empty space', () => {
+    const engine = makeEngine(stackedDoc());
+    expect(engine.tools.contextMenuLayerIdAt({ x: 60, y: 60 })).toBeNull();
+    engine.lifecycle.dispose();
+  });
+
+  it('returns null while a text-edit session is open (never opens over an in-progress edit)', () => {
+    const engine = makeEngine(stackedDoc());
+    engine.tools.setTool('text');
+    engine.layers.openTextCreate({ x: 5, y: 5 });
+    expect(engine.stores.textEditSession.get()).not.toBeNull();
+    expect(engine.tools.contextMenuLayerIdAt({ x: 5, y: 5 })).toBeNull();
+    engine.lifecycle.dispose();
+  });
+});
+
+describe('Select Object canvas engine integration', () => {
+  const samLayer = (id: string, x = 0): CanvasRasterLayerContractV2 => ({
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name: id,
+    opacity: 1,
+    source: { fill: '#fff', height: 100, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 100 },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x, y: 0 },
+    type: 'raster',
+  });
+
+  /** A raster layer whose baked world rect exactly covers `rect`. */
+  const samRectLayer = (id: string, rect: CanvasDocumentContractV2['bbox']): CanvasRasterLayerContractV2 => ({
+    ...samLayer(id),
+    source: {
+      fill: '#fff',
+      height: rect.height,
+      kind: 'rect',
+      stroke: null,
+      strokeWidth: 0,
+      type: 'shape',
+      width: rect.width,
+    },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: rect.x, y: rect.y },
+  });
+
+  const samDocument = (layers: CanvasLayerContract[] = [samLayer('source')]): CanvasDocumentContractV2 => ({
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers,
+    selectedLayerId: layers[0]?.id ?? null,
+    version: 2,
+    width: 100,
+  });
+
+  const createOpaqueSamBackend = () => {
+    vi.stubGlobal('Path2D', class FakePath2D {});
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createSurface: (width, height) => {
+        const surface = base.createSurface(width, height);
+        surfaces.push(surface);
+        Object.defineProperty(surface.ctx, 'getImageData', {
+          value: (_x: number, _y: number, readWidth: number, readHeight: number) => {
+            const data = new Uint8ClampedArray(readWidth * readHeight * 4);
+            for (let index = 0; index < data.length; index += 4) {
+              data[index] = 17;
+              data[index + 1] = 34;
+              data[index + 2] = 51;
+              data[index + 3] = 255;
+            }
+            return { colorSpace: 'srgb', data, height: readHeight, width: readWidth } as ImageData;
+          },
+        });
+        return surface;
+      },
+    };
+    return { backend, surfaces };
+  };
+
+  const withSamPreviewBitmapDimensions = (
+    backend: StubRasterBackend,
+    width = 100,
+    height = 100
+  ): StubRasterBackend => ({
+    ...backend,
+    createImageBitmap: async (source) => {
+      const bitmap = await backend.createImageBitmap(source);
+      return Object.assign(bitmap, { height, width });
+    },
+  });
+
+  const createSamHarness = async (
+    options: {
+      backend?: StubRasterBackend;
+      bbox?: CanvasDocumentContractV2['bbox'];
+      imageResolver?: (imageName: string, signal?: AbortSignal) => Promise<Blob>;
+      layers?: CanvasLayerContract[];
+      runGraph?: NonNullable<CanvasEngineOptions['selectObjectDeps']>['runGraph'];
+      uploadIntermediate?: NonNullable<CanvasEngineOptions['selectObjectDeps']>['uploadIntermediate'];
+    } = {}
+  ) => {
+    const raf = createControllableRaf();
+    const windowListeners = new Map<string, Set<(event: Event) => void>>();
+    vi.stubGlobal('requestAnimationFrame', raf.requestFrame);
+    vi.stubGlobal('cancelAnimationFrame', raf.cancelFrame);
+    vi.stubGlobal('addEventListener', (type: string, listener: (event: Event) => void) => {
+      const listeners = windowListeners.get(type) ?? new Set();
+      listeners.add(listener);
+      windowListeners.set(type, listeners);
+    });
+    vi.stubGlobal('removeEventListener', (type: string, listener: (event: Event) => void) => {
+      windowListeners.get(type)?.delete(listener);
+    });
+    const bbox = options.bbox ?? { height: 100, width: 100, x: 0, y: 0 };
+    const reactive = createReactiveStore({ ...samDocument(options.layers), bbox });
+    const engine = createCanvasEngine({
+      backend: options.backend ?? {
+        ...createTestStubRasterBackend(),
+        createImageBitmap: () =>
+          Promise.resolve({ close: () => undefined, height: bbox.height, width: bbox.width } as unknown as ImageBitmap),
+      },
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: options.imageResolver ?? (() => Promise.resolve(new Blob())),
+      projectId: 'p1',
+      selectObjectDeps: {
+        runGraph:
+          options.runGraph ??
+          (() =>
+            Promise.resolve({ height: bbox.height, imageName: 'sam-mask.png', origin: 'test', width: bbox.width })),
+        uploadIntermediate:
+          options.uploadIntermediate ??
+          (() => Promise.resolve({ height: bbox.height, imageName: 'sam-source.png', width: bbox.width })),
+      },
+      store: reactive.store,
+    });
+    const screen = createInputCanvas();
+    const overlay = createInputCanvas();
+    engine.surface.attach(screen.element, overlay.element);
+    raf.flush();
+    await flushMicrotasks();
+    raf.flush();
+    const fireKey = (type: 'keydown' | 'keyup', code: string, key: string): void => {
+      for (const listener of windowListeners.get(type) ?? []) {
+        listener({ code, key, preventDefault: vi.fn(), repeat: false, target: null } as unknown as Event);
+      }
+    };
+    return { ...reactive, engine, fireKey, overlay, raf, screen };
+  };
+
+  it('keeps Select Object visible and inputs intact when the first Process fails to upload, then retries', async () => {
+    const bbox = { height: 100, width: 100, x: 0, y: 0 };
+    const reactive = createReactiveStore(samDocument());
+    const runGraph = vi.fn(() =>
+      Promise.resolve({ height: bbox.height, imageName: 'sam-mask.png', origin: 'test', width: bbox.width })
+    );
+    const uploadIntermediate = vi
+      .fn<NonNullable<CanvasEngineOptions['selectObjectDeps']>['uploadIntermediate']>()
+      .mockRejectedValueOnce(new Error('upload failed'))
+      .mockResolvedValueOnce({ height: bbox.height, imageName: 'sam-source.png', width: bbox.width });
+    const engine = createCanvasEngine({
+      backend: {
+        ...createTestStubRasterBackend(),
+        createImageBitmap: () =>
+          Promise.resolve({ close: () => undefined, height: bbox.height, width: bbox.width } as unknown as ImageBitmap),
+      },
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      selectObjectDeps: {
+        runGraph,
+        uploadIntermediate,
+      },
+      store: reactive.store,
+    });
+    await engine.exports.exportLayerPixels('source');
+    const input = { prompt: 'keep this', type: 'prompt' as const };
+    expect(getCanvasOperations(engine).startSelectObject('source')).toBe('started');
+    getCanvasOperations(engine).updateSelectObjectSession({ input, invert: true });
+
+    await expect(getCanvasOperations(engine).processSelectObjectSession()).resolves.toBe('error');
+
+    expect(runGraph).not.toHaveBeenCalled();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({ phase: 'error', status: 'active' });
+    expect(getCanvasOperations(engine).stores.samSession.get()).toMatchObject({
+      hasPreview: false,
+      input,
+      invert: true,
+    });
+
+    await expect(getCanvasOperations(engine).processSelectObjectSession()).resolves.toBe('published');
+    expect(runGraph).toHaveBeenCalledOnce();
+    expect(getCanvasOperations(engine).stores.samSession.get()).toMatchObject({
+      hasPreview: true,
+      input,
+      invert: true,
+      status: 'ready',
+    });
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['document', 'project'] as const)(
+    'fully clears Select Object session, store, operation, and tool on %s invalidation',
+    async (kind) => {
+      const h = await createSamHarness();
+      expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+      const document = h.engine.document.getDocument()!;
+
+      if (kind === 'document') {
+        h.setDocument({ ...document }, 1);
+      } else {
+        h.setActiveProjectId('p2');
+      }
+
+      if (kind === 'project') {
+        expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+        expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({ status: 'active' });
+        expect(h.engine.stores.activeTool.get()).toBe('sam');
+      } else {
+        expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+        expect(getCanvasOperations(h.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+        expect(h.engine.stores.activeTool.get()).toBe('view');
+      }
+      h.engine.lifecycle.dispose();
+    }
+  );
+
+  const createCommittingSamHarness = async (
+    imageResolver: (imageName: string, signal?: AbortSignal) => Promise<Blob> = () => Promise.resolve(new Blob()),
+    backend: StubRasterBackend = createTestStubRasterBackend(),
+    bbox: CanvasDocumentContractV2['bbox'] = { height: 100, width: 100, x: 0, y: 0 }
+  ) => {
+    const document = { ...samDocument([samRectLayer('source', bbox)]), bbox };
+    const reactive = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: {
+        ...backend,
+        createImageBitmap: () =>
+          Promise.resolve({ close: () => undefined, height: bbox.height, width: bbox.width } as unknown as ImageBitmap),
+      },
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver,
+      projectId: reactive.projectId,
+      selectObjectDeps: {
+        runGraph: () =>
+          Promise.resolve({ height: bbox.height, imageName: 'sam-mask.png', origin: 'test', width: bbox.width }),
+        uploadIntermediate: () =>
+          Promise.resolve({ height: bbox.height, imageName: 'sam-source.png', width: bbox.width }),
+      },
+      store: reactive.store,
+    });
+    await engine.exports.exportLayerPixels('source');
+    getCanvasOperations(engine).startSelectObject('source');
+    getCanvasOperations(engine).updateSelectObjectSession({
+      input: {
+        bbox: null,
+        excludePoints: [],
+        includePoints: [{ x: bbox.x + 5, y: bbox.y + 5 }],
+        type: 'visual',
+      },
+    });
+    await getCanvasOperations(engine).processSelectObjectSession();
+    return { ...reactive, document, engine };
+  };
+
+  const invalidateSelectObjectCommit = async (
+    engine: CanvasEngine,
+    kind: 'input' | 'reset' | 'process'
+  ): Promise<void> => {
+    if (kind === 'input') {
+      getCanvasOperations(engine).updateSelectObjectSession({ input: { prompt: 'new input', type: 'prompt' } });
+    } else if (kind === 'reset') {
+      getCanvasOperations(engine).resetSelectObjectSession();
+    } else {
+      await getCanvasOperations(engine).processSelectObjectSession();
+    }
+  };
+
+  it('starts on the selected supported source, activates the real sam tool, and edits overlay-only', async () => {
+    const h = await createSamHarness();
+
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+    expect(h.engine.stores.activeTool.get()).toBe('sam');
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'select-object', layerId: 'source', projectId: 'p1' },
+      status: 'active',
+    });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' },
+      layerName: 'source',
+      layerType: 'raster',
+      sourceRect: { height: 100, width: 100, x: 0, y: 0 },
+    });
+    h.raf.flush();
+    h.screen.surface.callLog.length = 0;
+    h.overlay.surface.callLog.length = 0;
+
+    h.overlay.fire('pointerdown', pointerAt(5, 5));
+    h.overlay.fire('pointerup', pointerAt(5, 5, { buttons: 0 }));
+    h.raf.flush();
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.input.includePoints).toEqual([{ x: 5, y: 5 }]);
+    expect(h.overlay.surface.callLog.some((entry) => entry.op === 'arc')).toBe(true);
+    expect(h.screen.surface.callLog.some((entry) => entry.op === 'clearRect' || entry.op === 'drawImage')).toBe(false);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('resets edited inputs and point mode immediately after launch without requiring a preview guard', async () => {
+    const h = await createSamHarness();
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: {
+        bbox: { height: 10, width: 10, x: 1, y: 2 },
+        excludePoints: [{ x: 4, y: 5 }],
+        includePoints: [{ x: 2, y: 3 }],
+        type: 'visual',
+      },
+      invert: true,
+      pointLabel: 'exclude',
+    });
+
+    expect(getCanvasOperations(h.engine).resetSelectObjectSession()).toBe('updated');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      error: null,
+      hasPreview: false,
+      input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' },
+      invert: false,
+      pointLabel: 'include',
+      status: 'ready',
+    });
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({ status: 'active' });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('resets after a first failed Process while preserving lifecycle ownership', async () => {
+    const bbox = { height: 100, width: 100, x: 0, y: 0 };
+    const reactive = createReactiveStore(samDocument());
+    const engine = createCanvasEngine({
+      backend: withSamPreviewBitmapDimensions(createTestStubRasterBackend()),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: 'p1',
+      selectObjectDeps: {
+        runGraph: () => Promise.reject(new Error('queue failed')),
+        uploadIntermediate: () => Promise.resolve({ height: 100, imageName: 'source.png', width: 100 }),
+      },
+      store: reactive.store,
+    });
+    await engine.exports.exportLayerPixels('source');
+    expect(getCanvasOperations(engine).startSelectObject('source')).toBe('started');
+    getCanvasOperations(engine).updateSelectObjectSession({ input: { prompt: 'cat', type: 'prompt' }, invert: true });
+    await expect(getCanvasOperations(engine).processSelectObjectSession()).resolves.toBe('error');
+    expect(getCanvasOperations(engine).stores.samSession.get()).toMatchObject({
+      error: { code: 'queue' },
+      status: 'error',
+    });
+
+    expect(getCanvasOperations(engine).resetSelectObjectSession()).toBe('updated');
+
+    expect(getCanvasOperations(engine).stores.samSession.get()).toMatchObject({
+      error: null,
+      hasPreview: false,
+      input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' },
+      invert: false,
+      pointLabel: 'include',
+      status: 'ready',
+    });
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toMatchObject({ status: 'active' });
+    expect(engine.document.getDocument()?.bbox).toEqual(bbox);
+    engine.lifecycle.dispose();
+  });
+
+  it('reuses one uploaded source image across fresh engine guards for point, invert, and refinement changes', async () => {
+    const uploadIntermediate = vi.fn(() => Promise.resolve({ height: 100, imageName: 'source.png', width: 100 }));
+    const runGraph = vi.fn(() => Promise.resolve({ height: 100, imageName: 'mask.png', origin: 'test', width: 100 }));
+    const h = await createSamHarness({ runGraph, uploadIntermediate });
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 2, y: 2 }], type: 'visual' },
+    });
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 3, y: 3 }], type: 'visual' },
+    });
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+    getCanvasOperations(h.engine).updateSelectObjectSession({ invert: true });
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+    getCanvasOperations(h.engine).updateSelectObjectSession({ applyPolygonRefinement: true });
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+
+    expect(uploadIntermediate).toHaveBeenCalledOnce();
+    expect(runGraph).toHaveBeenCalledTimes(4);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('keeps the selection when starting on the selected layer and selects a non-selected source', async () => {
+    const h = await createSamHarness({ layers: [samLayer('first'), samLayer('second', 30)] });
+
+    expect(getCanvasOperations(h.engine).startSelectObject('first')).toBe('started');
+    expect(h.store.dispatch).not.toHaveBeenCalledWith(expect.objectContaining({ type: 'setCanvasSelectedLayer' }));
+
+    expect(getCanvasOperations(h.engine).startSelectObject('second')).toBe('started');
+    expect(h.store.dispatch).toHaveBeenCalledWith({ id: 'second', type: 'setCanvasSelectedLayer' });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('runs a transformed layer rect through upload, local visual graph, metadata, and decoded rect', async () => {
+    const base = createTestStubRasterBackend();
+    const surfaces: StubRasterSurface[] = [];
+    const backend: StubRasterBackend = {
+      ...base,
+      createImageBitmap: () =>
+        Promise.resolve({ close: () => undefined, height: 20, width: 30 } as unknown as ImageBitmap),
+      createSurface: (width, height) => {
+        const surface = base.createSurface(width, height);
+        surfaces.push(surface);
+        return surface;
+      },
+    };
+    const uploadIntermediate = vi.fn(async (source: Blob) => {
+      expect(await source.text()).toBe('stub-surface-30x20');
+      return { height: 20, imageName: 'layer-source.png', width: 30 };
+    });
+    const runGraph = vi.fn<NonNullable<CanvasEngineOptions['selectObjectDeps']>['runGraph']>((options) => {
+      expect(options.graph.nodes['sam-segment']).toMatchObject({
+        bounding_boxes: [{ x_max: 20, x_min: 0, y_max: 18, y_min: 3 }],
+        point_lists: [{ points: [{ label: 1, x: 5, y: 8 }] }],
+      });
+      return Promise.resolve({ height: 20, imageName: 'mask.png', origin: 'test', width: 30 });
+    });
+    const imageResolver = vi.fn(() => Promise.resolve(new Blob(['mask'])));
+    // A 20x20 shape scaled 1.5x horizontally and translated: baked world rect {-6, 9, 30, 20}.
+    const scaled: CanvasRasterLayerContractV2 = {
+      ...samLayer('scaled'),
+      source: { fill: '#fff', height: 20, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 20 },
+      transform: { rotation: 0, scaleX: 1.5, scaleY: 1, x: -6, y: 9 },
+    };
+    const h = await createSamHarness({
+      backend,
+      imageResolver,
+      layers: [scaled, samLayer('other', 40)],
+      runGraph,
+      uploadIntermediate,
+    });
+    expect(getCanvasOperations(h.engine).startSelectObject('scaled')).toBe('started');
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.sourceRect).toEqual({
+      height: 20,
+      width: 30,
+      x: -6,
+      y: 9,
+    });
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: {
+        bbox: { height: 15, width: 20, x: -6, y: 12 },
+        excludePoints: [],
+        includePoints: [{ x: -1, y: 17 }],
+        type: 'visual',
+      },
+    });
+
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+    h.raf.flush();
+
+    expect(uploadIntermediate).toHaveBeenCalledOnce();
+    expect(runGraph).toHaveBeenCalledOnce();
+    expect(imageResolver).toHaveBeenCalledWith('mask.png', expect.any(AbortSignal));
+    expect(surfaces.some((surface) => surface.width === 30 && surface.height === 20)).toBe(true);
+    expect(h.overlay.surface.callLog).toContainEqual({
+      args: [expect.anything(), -6, 9, 30, 20],
+      op: 'drawImage',
+    });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('builds the prompt path and reports a decoded preview', async () => {
+    const runGraph = vi.fn<NonNullable<CanvasEngineOptions['selectObjectDeps']>['runGraph']>((options) => {
+      expect(options.graph.nodes['sam-detect']).toMatchObject({ prompt: 'red car', type: 'grounding_dino' });
+      return Promise.resolve({ height: 100, imageName: 'prompt-mask.png', origin: 'test', width: 100 });
+    });
+    const h = await createSamHarness({ runGraph });
+    getCanvasOperations(h.engine).startSelectObject('source');
+    getCanvasOperations(h.engine).updateSelectObjectSession({ input: { prompt: '  red car  ', type: 'prompt' } });
+
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({ hasPreview: true, status: 'ready' });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('rejects SAM metadata dimensions that do not match the decoded preview rect', async () => {
+    const h = await createSamHarness({
+      runGraph: () => Promise.resolve({ height: 99, imageName: 'bad-mask.png', origin: 'test', width: 100 }),
+    });
+    getCanvasOperations(h.engine).startSelectObject('source');
+    getCanvasOperations(h.engine).updateSelectObjectSession({ input: { prompt: 'cat', type: 'prompt' } });
+
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('error');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      error: { code: 'output-dimension', detail: 'SAM output dimensions 100x99 do not match 100x100.' },
+      hasPreview: false,
+      status: 'error',
+    });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('reports preview decode failures without publishing a stale surface', async () => {
+    const h = await createSamHarness({ imageResolver: () => Promise.reject(new Error('preview decode failed')) });
+    getCanvasOperations(h.engine).startSelectObject('source');
+    getCanvasOperations(h.engine).updateSelectObjectSession({ input: { prompt: 'cat', type: 'prompt' } });
+
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('error');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      error: { code: 'decode', detail: 'preview decode failed' },
+      hasPreview: false,
+      status: 'error',
+    });
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each([
+    { decoded: { height: 100, width: 99 }, label: 'smaller' },
+    { decoded: { height: 100, width: 101 }, label: 'larger' },
+    { decoded: { height: 100, width: Number.NaN }, label: 'non-finite' },
+    { decoded: { height: 100, width: 99.5 }, label: 'non-integer' },
+  ])('rejects a $label decoded bitmap before surface allocation and closes it', async ({ decoded }) => {
+    const close = vi.fn();
+    const base = createTestStubRasterBackend();
+    let didDecode = false;
+    const previewSurfaceAllocations = vi.fn();
+    const backend = {
+      ...base,
+      createImageBitmap: () => {
+        didDecode = true;
+        return Promise.resolve({ ...decoded, close } as unknown as ImageBitmap);
+      },
+      createSurface: (width: number, height: number) => {
+        if (didDecode) {
+          previewSurfaceAllocations(width, height);
+        }
+        return base.createSurface(width, height);
+      },
+    };
+    const h = await createSamHarness({ backend });
+    getCanvasOperations(h.engine).startSelectObject('source');
+    getCanvasOperations(h.engine).updateSelectObjectSession({ input: { prompt: 'cat', type: 'prompt' } });
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('error');
+
+    expect(close).toHaveBeenCalledOnce();
+    expect(previewSurfaceAllocations).not.toHaveBeenCalled();
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      error: {
+        code: 'output-dimension',
+        detail: `Decoded Select Object preview dimensions ${String(decoded.width)}x${decoded.height} do not match SAM output 100x100 and preview rect 100x100.`,
+      },
+      hasPreview: false,
+      status: 'error',
+    });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('saves the guarded preview to the selection mask and exits only after success', async () => {
+    const { backend, surfaces } = createOpaqueSamBackend();
+    const h = await createCommittingSamHarness(() => Promise.resolve(new Blob()), backend);
+    const makeDurable = vi.fn(() => Promise.resolve());
+
+    const previewCalls = surfaces.find((surface) =>
+      surface.callLog.some(
+        (entry) => entry.op === 'set' && entry.args[0] === 'fillStyle' && entry.args[1] === '#38bdf8'
+      )
+    )?.callLog;
+    expect(previewCalls).toEqual(
+      expect.arrayContaining([
+        { args: ['globalCompositeOperation', 'source-in'], op: 'set' },
+        { args: ['fillStyle', '#38bdf8'], op: 'set' },
+      ])
+    );
+
+    await expect(getCanvasOperations(h.engine).saveSelectObjectSession('selection', makeDurable)).resolves.toEqual({
+      status: 'selected',
+    });
+
+    expect(makeDurable).not.toHaveBeenCalled();
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(h.engine.stores.hasSelection.get()).toBe(true);
+    expect(h.engine.selection.getSelectionBounds()).toEqual(h.document.bbox);
+    expect(h.engine.selection.getSelectionMaskRect()).toEqual(h.document.bbox);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('Apply replaces the source layer content in place with one undoable history entry', async () => {
+    const h = await createCommittingSamHarness();
+    const makeDurable = vi.fn(() => Promise.resolve());
+
+    await expect(getCanvasOperations(h.engine).applySelectObjectSession(makeDurable)).resolves.toEqual({
+      layerId: 'source',
+      status: 'committed',
+    });
+
+    expect(makeDurable).toHaveBeenCalledOnce();
+    expect(makeDurable).toHaveBeenCalledWith('sam-mask.png');
+    const replaced = h.engine.document.getDocument()!.layers.find((layer) => layer.id === 'source')!;
+    expect(replaced).toMatchObject({
+      source: {
+        bitmap: { height: 100, imageName: 'sam-mask.png', width: 100 },
+        offset: { x: 0, y: 0 },
+        type: 'paint',
+      },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    });
+    expect(h.engine.document.getDocument()!.layers).toHaveLength(1);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+
+    expect(h.engine.stores.canUndo.get()).toBe(true);
+    h.engine.history.undo();
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    h.engine.history.redo();
+    expect(h.engine.document.getDocument()!.layers.find((layer) => layer.id === 'source')).toEqual(replaced);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('blocks Select Object actions called directly after an external lock and still allows Cancel', async () => {
+    const h = await createCommittingSamHarness();
+    const makeDurable = vi.fn(() => Promise.resolve());
+    const before = getCanvasOperations(h.engine).stores.samSession.get();
+
+    h.engine.tools.setInteractionLocked(true);
+
+    expect(
+      getCanvasOperations(h.engine).updateSelectObjectSession({ input: { prompt: 'changed', type: 'prompt' } })
+    ).toBe('blocked');
+    expect(getCanvasOperations(h.engine).resetSelectObjectSession()).toBe('blocked');
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('blocked');
+    await expect(getCanvasOperations(h.engine).applySelectObjectSession(makeDurable)).resolves.toEqual({
+      status: 'locked',
+    });
+    await expect(getCanvasOperations(h.engine).saveSelectObjectSession('raster', makeDurable)).resolves.toEqual({
+      status: 'locked',
+    });
+    expect(makeDurable).not.toHaveBeenCalled();
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toEqual(before);
+
+    getCanvasOperations(h.engine).cancelSelectObjectSession();
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    h.engine.tools.setInteractionLocked(false);
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+    expect(getCanvasOperations(h.engine).updateSelectObjectSession({ invert: false })).toBe('stale');
+    expect(getCanvasOperations(h.engine).resetSelectObjectSession()).toBe('stale');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('blocks Select Object save mutation when an external lock begins during durability', async () => {
+    const h = await createCommittingSamHarness();
+    const durable = createDeferred<void>();
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession('raster', () => durable.promise);
+    await vi.waitFor(() => expect(getCanvasOperations(h.engine).stores.samSession.get()?.status).toBe('committing'));
+
+    h.engine.tools.setInteractionLocked(true);
+    durable.resolve();
+
+    await expect(pending).resolves.toEqual({ status: 'locked' });
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({ hasPreview: true, status: 'ready' });
+    getCanvasOperations(h.engine).cancelSelectObjectSession();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('blocks Select Object apply mutation when an external lock begins during final decode', async () => {
+    const finalDecode = createDeferred<Blob>();
+    let resolutions = 0;
+    const h = await createCommittingSamHarness(() => {
+      resolutions += 1;
+      return resolutions === 1 ? Promise.resolve(new Blob()) : finalDecode.promise;
+    });
+    const pending = getCanvasOperations(h.engine).applySelectObjectSession(() => Promise.resolve());
+    await vi.waitFor(() => expect(resolutions).toBe(2));
+
+    h.engine.tools.setInteractionLocked(true);
+    finalDecode.resolve(new Blob());
+
+    await expect(pending).resolves.not.toMatchObject({ status: 'committed' });
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({ hasPreview: true, status: 'ready' });
+    getCanvasOperations(h.engine).cancelSelectObjectSession();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('interrupts Select Object processing on an external lock without losing inputs or operation', async () => {
+    const graph = createDeferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const runGraph = vi.fn(() => graph.promise);
+    const h = await createSamHarness({ runGraph });
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+    const input = { prompt: 'keep this prompt', type: 'prompt' as const };
+    expect(getCanvasOperations(h.engine).updateSelectObjectSession({ input, invert: true })).toBe('updated');
+    const pending = getCanvasOperations(h.engine).processSelectObjectSession();
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.status).toBe('preparing-source');
+    await vi.waitFor(() => expect(runGraph).toHaveBeenCalledOnce());
+
+    h.engine.tools.setInteractionLocked(true);
+    graph.resolve({ height: 100, imageName: 'late.png', origin: 'test', width: 100 });
+
+    await expect(pending).resolves.toBe('stale');
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      hasPreview: false,
+      input,
+      invert: true,
+      status: 'ready',
+    });
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({ phase: 'ready', status: 'active' });
+    getCanvasOperations(h.engine).cancelSelectObjectSession();
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each(['input', 'reset', 'process'] as const)(
+    'does not apply or close when %s invalidates ownership during final selection decode',
+    async (kind) => {
+      const finalDecode = createDeferred<Blob>();
+      let resolutions = 0;
+      const h = await createCommittingSamHarness(() => {
+        resolutions += 1;
+        return resolutions === 1 ? Promise.resolve(new Blob()) : finalDecode.promise;
+      });
+      const pending = getCanvasOperations(h.engine).applySelectObjectSession(() => Promise.resolve());
+      await vi.waitFor(() => expect(resolutions).toBe(2));
+
+      await invalidateSelectObjectCommit(h.engine, kind);
+      finalDecode.resolve(new Blob());
+
+      await expect(pending).resolves.not.toMatchObject({ status: 'committed' });
+      expect(h.engine.document.getDocument()).toEqual(h.document);
+      expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+      h.engine.lifecycle.dispose();
+    }
+  );
+
+  it('does not invalidate a pending save when preview isolation changes', async () => {
+    const h = await createCommittingSamHarness();
+    const durable = createDeferred<void>();
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession('inpaint_mask', () => durable.promise);
+
+    getCanvasOperations(h.engine).updateSelectObjectSession({ isolatedPreview: false });
+    durable.resolve();
+
+    await expect(pending).resolves.toMatchObject({ status: 'committed' });
+    expect(h.engine.document.getDocument()?.layers[0]?.type).toBe('inpaint_mask');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('Reset clears inputs, preview, and error while keeping the operation active', async () => {
+    const h = await createCommittingSamHarness();
+    getCanvasOperations(h.engine).updateSelectObjectSession({ input: { prompt: 'cat', type: 'prompt' }, invert: true });
+
+    getCanvasOperations(h.engine).resetSelectObjectSession();
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      error: null,
+      hasPreview: false,
+      input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' },
+      invert: false,
+      status: 'ready',
+    });
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({ status: 'active' });
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each([
+    ['raster', 'Segmented Object'],
+    ['control', 'Segmented Object Control'],
+    ['inpaint_mask', null],
+    ['regional_guidance', null],
+  ] as const)(
+    'promotes then atomically saves the guarded preview as %s at the top of its group, keeping the session',
+    async (target, copyName) => {
+      const calls: string[] = [];
+      const h = await createCommittingSamHarness();
+
+      const result = await getCanvasOperations(h.engine).saveSelectObjectSession(target, () => {
+        calls.push('durable');
+        return Promise.resolve();
+      });
+
+      expect(result.status).toBe('committed');
+      expect(calls[0]).toBe('durable');
+      expect(h.engine.document.getDocument()?.layers[0]?.type).toBe(target);
+      expect(h.engine.document.getDocument()?.layers[1]?.id).toBe('source');
+      const created = h.engine.document.getDocument()?.layers[0];
+      if (!created) {
+        throw new Error('expected a saved object layer');
+      }
+      if (created.type === 'raster' || created.type === 'control') {
+        expect(created.name).toBe(copyName);
+        expect(created.source).toMatchObject({ offset: { x: 0, y: 0 }, type: 'paint' });
+      } else {
+        expect(created.mask).toMatchObject({ offset: { x: 0, y: 0 } });
+      }
+      expect(created.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+
+      // Save As keeps the session and its preview open; only Apply, the
+      // Selection target, and Cancel end it.
+      expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+        hasPreview: true,
+        status: 'ready',
+      });
+      expect(h.engine.stores.activeTool.get()).toBe('sam');
+      getCanvasOperations(h.engine).cancelSelectObjectSession();
+
+      expect(h.engine.stores.canUndo.get()).toBe(true);
+      h.engine.history.undo();
+      expect(h.engine.document.getDocument()?.layers.map((layer) => layer.id)).toEqual(['source']);
+      h.engine.history.redo();
+      expect(h.engine.document.getDocument()?.layers[0]?.type).toBe(target);
+      h.engine.lifecycle.dispose();
+    }
+  );
+
+  it('keeps the session open across saves so a second save also succeeds without touching the source', async () => {
+    const h = await createCommittingSamHarness();
+
+    await expect(
+      getCanvasOperations(h.engine).saveSelectObjectSession('raster', () => Promise.resolve())
+    ).resolves.toMatchObject({
+      status: 'committed',
+    });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({ hasPreview: true, status: 'ready' });
+
+    await expect(
+      getCanvasOperations(h.engine).saveSelectObjectSession('raster', () => Promise.resolve())
+    ).resolves.toMatchObject({
+      status: 'committed',
+    });
+
+    expect(h.engine.document.getDocument()?.layers.map((layer) => layer.name)).toEqual([
+      'Segmented Object',
+      'Segmented Object',
+      'source',
+    ]);
+    expect(h.engine.document.getDocument()?.layers[2]).toEqual(h.document.layers[0]);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({ hasPreview: true, status: 'ready' });
+    expect(h.engine.stores.activeTool.get()).toBe('sam');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('saves the exact non-zero source rect origin and dimensions', async () => {
+    const rect = { height: 30, width: 40, x: -11, y: 7 };
+    const h = await createCommittingSamHarness(undefined, undefined, rect);
+
+    const result = await getCanvasOperations(h.engine).saveSelectObjectSession('raster', () => Promise.resolve());
+
+    expect(result.status).toBe('committed');
+    const created = h.engine.document.getDocument()?.layers[0];
+    expect(created?.type).toBe('raster');
+    if (created?.type === 'raster') {
+      expect(created.source).toMatchObject({
+        bitmap: { height: rect.height, width: rect.width },
+        offset: { x: rect.x, y: rect.y },
+      });
+    }
+    h.engine.lifecycle.dispose();
+  });
+
+  it('publishes a committing phase and mutually excludes Apply and Save', async () => {
+    const h = await createCommittingSamHarness();
+    const durable = createDeferred<void>();
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession('raster', () => durable.promise);
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.status).toBe('committing');
+    await expect(getCanvasOperations(h.engine).applySelectObjectSession(() => Promise.resolve())).resolves.toEqual({
+      status: 'busy',
+    });
+    await expect(
+      getCanvasOperations(h.engine).saveSelectObjectSession('control', () => Promise.resolve())
+    ).resolves.toEqual({
+      status: 'busy',
+    });
+    durable.resolve();
+    await expect(pending).resolves.toMatchObject({ status: 'committed' });
+    h.engine.lifecycle.dispose();
+  });
+
+  it.each(['input', 'reset', 'process'] as const)(
+    'does not save or close when %s invalidates ownership during durability promotion',
+    async (kind) => {
+      const h = await createCommittingSamHarness();
+      const durable = createDeferred<void>();
+      const pending = getCanvasOperations(h.engine).saveSelectObjectSession('regional_guidance', () => durable.promise);
+
+      await invalidateSelectObjectCommit(h.engine, kind);
+      durable.resolve();
+
+      await expect(pending).resolves.not.toMatchObject({ status: 'committed' });
+      expect(h.engine.document.getDocument()).toEqual(h.document);
+      expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+      h.engine.lifecycle.dispose();
+    }
+  );
+
+  it.each([
+    ['raster', 'input'],
+    ['raster', 'reset'],
+    ['raster', 'process'],
+    ['control', 'input'],
+    ['control', 'reset'],
+    ['control', 'process'],
+  ] as const)('does not commit %s when %s invalidates ownership during final decode', async (target, kind) => {
+    const finalDecode = createDeferred<Blob>();
+    let resolutions = 0;
+    const h = await createCommittingSamHarness(() => {
+      resolutions += 1;
+      return resolutions === 1 ? Promise.resolve(new Blob()) : finalDecode.promise;
+    });
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession(target, () => Promise.resolve());
+    await vi.waitFor(() => expect(resolutions).toBe(2));
+
+    await invalidateSelectObjectCommit(h.engine, kind);
+    finalDecode.resolve(new Blob());
+
+    await expect(pending).resolves.not.toMatchObject({ status: 'committed' });
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not report an old durability failure into a replacement session', async () => {
+    const document = samDocument([samLayer('first'), samLayer('second', 30)]);
+    const reactive = createReducerBackedStore(document);
+    const engine = createCanvasEngine({
+      backend: withSamPreviewBitmapDimensions(createTestStubRasterBackend()),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reactive.projectId,
+      selectObjectDeps: {
+        runGraph: () => Promise.resolve({ height: 100, imageName: 'sam-mask.png', origin: 'test', width: 100 }),
+        uploadIntermediate: () => Promise.resolve({ height: 100, imageName: 'sam-source.png', width: 100 }),
+      },
+      store: reactive.store,
+    });
+    await engine.exports.exportLayerPixels('first');
+    await engine.exports.exportLayerPixels('second');
+    getCanvasOperations(engine).startSelectObject('first');
+    getCanvasOperations(engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    await getCanvasOperations(engine).processSelectObjectSession();
+    let rejectDurability!: (error: Error) => void;
+    const durability = new Promise<void>((_resolve, reject) => {
+      rejectDurability = reject;
+    });
+    const oldSave = getCanvasOperations(engine).saveSelectObjectSession('raster', () => durability);
+
+    expect(getCanvasOperations(engine).startSelectObject('second')).toBe('started');
+    rejectDurability(new Error('old failure'));
+
+    await expect(oldSave).resolves.toMatchObject({ status: 'failed' });
+    expect(getCanvasOperations(engine).stores.samSession.get()).toMatchObject({ error: null });
+    engine.lifecycle.dispose();
+  });
+
+  it('does not close a replacement session when the old selection save finishes authoritatively', async () => {
+    const document = samDocument([samLayer('first'), samLayer('second', 30)]);
+    const reactive = createReducerBackedStore(document);
+    const { backend } = createOpaqueSamBackend();
+    const engine = createCanvasEngine({
+      backend: withSamPreviewBitmapDimensions(backend),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reactive.projectId,
+      selectObjectDeps: {
+        runGraph: () => Promise.resolve({ height: 100, imageName: 'sam-mask.png', origin: 'test', width: 100 }),
+        uploadIntermediate: () => Promise.resolve({ height: 100, imageName: 'sam-source.png', width: 100 }),
+      },
+      store: reactive.store,
+    });
+    await engine.exports.exportLayerPixels('first');
+    await engine.exports.exportLayerPixels('second');
+    getCanvasOperations(engine).startSelectObject('first');
+    getCanvasOperations(engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    await getCanvasOperations(engine).processSelectObjectSession();
+    let replaced = false;
+    const unsubscribe = engine.stores.hasSelection.subscribe(() => {
+      if (!replaced && engine.stores.hasSelection.get()) {
+        replaced = true;
+        getCanvasOperations(engine).startSelectObject('second');
+      }
+    });
+
+    await expect(
+      getCanvasOperations(engine).saveSelectObjectSession('selection', () => Promise.resolve())
+    ).resolves.toEqual({
+      status: 'selected',
+    });
+
+    expect(getCanvasOperations(engine).stores.samSession.get()).toMatchObject({ error: null });
+    unsubscribe();
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['apply', 'save'] as const)(
+    'preserves a replacement started by the SAM subscriber when old %s succeeds',
+    async (kind) => {
+      const document = samDocument([samLayer('first'), samLayer('second', 30)]);
+      const reactive = createReducerBackedStore(document);
+      const { backend } = createOpaqueSamBackend();
+      const engine = createCanvasEngine({
+        backend: withSamPreviewBitmapDimensions(backend),
+        bitmapStore: createSpyBitmapStore(),
+        imageResolver: () => Promise.resolve(new Blob()),
+        projectId: reactive.projectId,
+        selectObjectDeps: {
+          runGraph: () => Promise.resolve({ height: 100, imageName: 'sam-mask.png', origin: 'test', width: 100 }),
+          uploadIntermediate: () => Promise.resolve({ height: 100, imageName: 'sam-source.png', width: 100 }),
+        },
+        store: reactive.store,
+      });
+      await engine.exports.exportLayerPixels('first');
+      await engine.exports.exportLayerPixels('second');
+      getCanvasOperations(engine).startSelectObject('first');
+      getCanvasOperations(engine).updateSelectObjectSession({
+        input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+      });
+      await getCanvasOperations(engine).processSelectObjectSession();
+      let sawCommitting = false;
+      let replaced = false;
+      const unsubscribe = getCanvasOperations(engine).stores.samSession.subscribe(() => {
+        const snapshot = getCanvasOperations(engine).stores.samSession.get();
+        if (snapshot?.status === 'committing') {
+          sawCommitting = true;
+        } else if (sawCommitting && !replaced) {
+          replaced = true;
+          expect(getCanvasOperations(engine).startSelectObject('second')).toBe('started');
+        }
+      });
+
+      const result =
+        kind === 'apply'
+          ? await getCanvasOperations(engine).applySelectObjectSession(() => Promise.resolve())
+          : await getCanvasOperations(engine).saveSelectObjectSession('inpaint_mask', () => Promise.resolve());
+
+      expect(result.status).toBe('committed');
+      expect(replaced).toBe(true);
+      expect(getCanvasOperations(engine).stores.samSession.get()).toMatchObject({ error: null });
+      expect(engine.stores.activeTool.get()).toBe('sam');
+      unsubscribe();
+      engine.lifecycle.dispose();
+    }
+  );
+
+  it('keeps the session and exact preview retryable when durability fails', async () => {
+    const h = await createCommittingSamHarness();
+    const previewInput = getCanvasOperations(h.engine).stores.samSession.get()?.input;
+
+    await expect(
+      getCanvasOperations(h.engine).saveSelectObjectSession('raster', () =>
+        Promise.reject(new Error('promotion failed'))
+      )
+    ).resolves.toEqual({ message: 'promotion failed', status: 'failed' });
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      error: { code: 'unknown', detail: 'promotion failed' },
+      hasPreview: true,
+    });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.input).toEqual(previewInput);
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    await expect(
+      getCanvasOperations(h.engine).saveSelectObjectSession('raster', () => Promise.resolve())
+    ).resolves.toMatchObject({
+      status: 'committed',
+    });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('keeps the session and preview retryable when the structural save is rejected', async () => {
+    const h = await createCommittingSamHarness();
+    const previewInput = getCanvasOperations(h.engine).stores.samSession.get()?.input;
+    h.dispatch.mockImplementationOnce(() => {
+      throw new Error('commit rejected');
+    });
+
+    await expect(
+      getCanvasOperations(h.engine).saveSelectObjectSession('inpaint_mask', () => Promise.resolve())
+    ).resolves.toEqual({
+      message: 'commit rejected',
+      status: 'failed',
+    });
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({
+      error: { code: 'unknown', detail: 'commit rejected' },
+      hasPreview: true,
+    });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.input).toEqual(previewInput);
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not commit a preview that becomes stale during durability promotion', async () => {
+    const h = await createCommittingSamHarness();
+    const durable = createDeferred<void>();
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession('control', () => durable.promise);
+    h.dispatch({ id: 'source', patch: { opacity: 0.5 }, type: 'updateCanvasLayer' });
+    durable.resolve();
+
+    await expect(pending).resolves.toEqual({ status: 'stale' });
+    expect(h.engine.document.getDocument()?.layers).toHaveLength(1);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not treat a reentrant unrelated layer mutation as the owned Save insertion', async () => {
+    const document = samDocument([samLayer('source')]);
+    const reducer = createReducerBackedStore(document);
+    let engine!: CanvasEngine;
+    let reentered = false;
+    let sessionDuringReentry: ReturnType<ReturnType<typeof getCanvasOperations>['stores']['samSession']['get']> = null;
+    reducer.store.subscribe(() => {
+      const current = reducer.store.getState().projects[0]?.canvas.document;
+      if (!reentered && current?.layers.length === 2) {
+        reentered = true;
+        reducer.store.dispatch({ id: 'source', patch: { opacity: 0.5 }, type: 'updateCanvasLayer' });
+        sessionDuringReentry = getCanvasOperations(engine).stores.samSession.get();
+      }
+    });
+    engine = createCanvasEngine({
+      backend: withSamPreviewBitmapDimensions(createTestStubRasterBackend()),
+      bitmapStore: createSpyBitmapStore(),
+      imageResolver: () => Promise.resolve(new Blob()),
+      projectId: reducer.projectId,
+      selectObjectDeps: {
+        runGraph: () => Promise.resolve({ height: 100, imageName: 'sam-mask.png', origin: 'test', width: 100 }),
+        uploadIntermediate: () => Promise.resolve({ height: 100, imageName: 'sam-source.png', width: 100 }),
+      },
+      store: reducer.store,
+    });
+    await engine.exports.exportLayerPixels('source');
+    expect(getCanvasOperations(engine).startSelectObject('source')).toBe('started');
+    getCanvasOperations(engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    await expect(getCanvasOperations(engine).processSelectObjectSession()).resolves.toBe('published');
+
+    await expect(
+      getCanvasOperations(engine).saveSelectObjectSession('raster', () => Promise.resolve())
+    ).resolves.toMatchObject({
+      status: 'committed',
+    });
+
+    expect(reentered).toBe(true);
+    expect(sessionDuringReentry).toBeNull();
+    expect(getCanvasOperations(engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(engine.document.getDocument()?.layers.find((layer) => layer.id === 'source')?.opacity).toBe(0.5);
+    engine.lifecycle.dispose();
+  });
+
+  it.each(['source', 'project', 'document'] as const)('aborts a pending save on %s invalidation', async (kind) => {
+    const h = await createSamHarness();
+    getCanvasOperations(h.engine).startSelectObject('source');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    await getCanvasOperations(h.engine).processSelectObjectSession();
+    const durable = createDeferred<void>();
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession('inpaint_mask', () => durable.promise);
+    const document = h.engine.document.getDocument()!;
+
+    if (kind === 'source') {
+      h.setDocument({ ...document, layers: [{ ...document.layers[0]!, opacity: 0.5 }] });
+    } else if (kind === 'project') {
+      h.setActiveProjectId('p2');
+    } else {
+      h.setDocument({ ...document }, 1);
+    }
+    durable.resolve();
+
+    if (kind === 'project') {
+      await expect(pending).resolves.toMatchObject({ status: 'committed' });
+    } else {
+      await expect(pending).resolves.not.toMatchObject({ status: 'committed' });
+    }
+    if (kind === 'project') {
+      expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+    } else {
+      expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    }
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not commit when Cancel closes the operation during durability promotion', async () => {
+    const h = await createCommittingSamHarness();
+    const durable = createDeferred<void>();
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession('regional_guidance', () => durable.promise);
+
+    getCanvasOperations(h.engine).cancelSelectObjectSession();
+    durable.resolve();
+
+    await expect(pending).resolves.toEqual({ status: 'stale' });
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('aborts a raster save when Cancel lands during final image decoding', async () => {
+    const finalDecode = createDeferred<Blob>();
+    let resolutions = 0;
+    const h = await createCommittingSamHarness(() => {
+      resolutions += 1;
+      return resolutions === 1 ? Promise.resolve(new Blob()) : finalDecode.promise;
+    });
+    const pending = getCanvasOperations(h.engine).saveSelectObjectSession('raster', () => Promise.resolve());
+    await vi.waitFor(() => expect(resolutions).toBe(2));
+
+    getCanvasOperations(h.engine).cancelSelectObjectSession();
+    finalDecode.resolve(new Blob());
+
+    await expect(pending).resolves.toEqual({ status: 'aborted' });
+    expect(h.engine.document.getDocument()).toEqual(h.document);
+    expect(h.engine.stores.canUndo.get()).toBe(false);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('processes a sole bbox near-edge point after canonicalizing it to the last bbox pixel', async () => {
+    const runGraph = vi.fn(() =>
+      Promise.resolve({ height: 100, imageName: 'sam-mask.png', origin: 'test', width: 100 })
+    );
+    const h = await createSamHarness({ runGraph });
+    getCanvasOperations(h.engine).startSelectObject('source');
+
+    h.overlay.fire('pointerdown', pointerAt(99.8, 99.7));
+    h.overlay.fire('pointerup', pointerAt(99.8, 99.7, { buttons: 0 }));
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.input.includePoints).toEqual([{ x: 99, y: 99 }]);
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+    expect(runGraph).toHaveBeenCalledOnce();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('uses the half-open generation bbox as the only point domain', async () => {
+    const h = await createSamHarness();
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+
+    h.overlay.fire('pointerdown', pointerAt(100, 50));
+    h.overlay.fire('pointerup', pointerAt(100, 50, { buttons: 0 }));
+    h.overlay.fire('pointerdown', pointerAt(-0.01, 50));
+    h.overlay.fire('pointerup', pointerAt(-0.01, 50, { buttons: 0 }));
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.input.includePoints).toEqual([]);
+
+    h.overlay.fire('pointerdown', pointerAt(99.99, 99.99));
+    h.overlay.fire('pointerup', pointerAt(99.99, 99.99, { buttons: 0 }));
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.input.includePoints).toEqual([{ x: 99, y: 99 }]);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('keeps viewport changes current but invalidates on cache clears', async () => {
+    const h = await createSamHarness();
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+
+    h.engine.viewport.getViewport().panBy({ x: 20, y: -10 });
+    h.engine.viewport.getViewport().zoomAtPoint(2, { x: 50, y: 50 });
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'select-object' },
+      status: 'active',
+    });
+
+    await h.engine.diagnostics.clearCaches();
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('survives bbox moves, layer reorders, and other-layer edits but cancels on a source-layer edit', async () => {
+    const h = await createSamHarness({ layers: [samLayer('source'), samLayer('other', 30)] });
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+
+    const document = h.engine.document.getDocument()!;
+    h.setDocument({ ...document, bbox: { height: 80, width: 90, x: 3, y: 4 } });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+
+    const reordered = h.engine.document.getDocument()!;
+    h.setDocument({ ...reordered, layers: [...reordered.layers].reverse() });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+
+    const withOtherEdited = h.engine.document.getDocument()!;
+    h.setDocument({
+      ...withOtherEdited,
+      layers: withOtherEdited.layers.map((layer) => (layer.id === 'other' ? { ...layer, opacity: 0.5 } : layer)),
+    });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({
+      identity: { kind: 'select-object', layerId: 'source' },
+      status: 'active',
+    });
+
+    const withSourceEdited = h.engine.document.getDocument()!;
+    h.setDocument({
+      ...withSourceEdited,
+      layers: withSourceEdited.layers.map((layer) => (layer.id === 'source' ? { ...layer, opacity: 0.25 } : layer)),
+    });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not start from a stale cache whose replacement source is still decoding', async () => {
+    const nextImage = createDeferred<Blob>();
+    const outside = {
+      ...samLayer('moving-source'),
+      source: {
+        bitmap: { height: 10, imageName: 'outside.png', width: 10 },
+        offset: { x: 150, y: 0 },
+        type: 'paint' as const,
+      },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    };
+    const h = await createSamHarness({
+      imageResolver: (imageName) =>
+        imageName === 'inside.png' ? nextImage.promise : Promise.resolve(new Blob(['outside'])),
+      layers: [outside],
+    });
+    const document = h.engine.document.getDocument()!;
+    h.setDocument({
+      ...document,
+      layers: [
+        {
+          ...outside,
+          source: { image: { height: 10, imageName: 'inside.png', width: 10 }, type: 'image' },
+        },
+      ],
+    });
+
+    expect(getCanvasOperations(h.engine).startSelectObject('moving-source')).toBe('not-ready');
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+
+    nextImage.resolve(new Blob(['inside']));
+    await expect(h.engine.exports.exportLayerPixels('moving-source')).resolves.toMatchObject({ status: 'ok' });
+    expect(getCanvasOperations(h.engine).startSelectObject('moving-source')).toBe('started');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('refuses disabled and authoritatively empty source layers without rasterizing', async () => {
+    const imageResolver = vi.fn(() => Promise.reject(new Error('disabled layer must not rasterize')));
+    const empty = {
+      ...samLayer('empty'),
+      source: { bitmap: null, offset: { x: 0, y: 0 }, type: 'paint' as const },
+    };
+    const disabled = {
+      ...samLayer('disabled'),
+      isEnabled: false,
+      source: { image: { height: 10, imageName: 'disabled.png', width: 10 }, type: 'image' as const },
+    };
+    const h = await createSamHarness({ imageResolver, layers: [disabled, empty] });
+
+    expect(getCanvasOperations(h.engine).startSelectObject('disabled')).toBe('disabled');
+    expect(getCanvasOperations(h.engine).startSelectObject('empty')).toBe('not-ready');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(imageResolver).not.toHaveBeenCalled();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('validates the source layer on start: missing, unsupported, disabled, and locked', async () => {
+    const mask: CanvasInpaintMaskLayerContract = {
+      ...samLayer('mask'),
+      mask: { bitmap: null, fill: { color: '#fff', style: 'solid' } },
+      type: 'inpaint_mask',
+    };
+    const h = await createSamHarness({
+      layers: [
+        mask,
+        { ...samLayer('disabled'), isEnabled: false },
+        { ...samLayer('locked'), isLocked: true },
+        samLayer('ready'),
+      ],
+    });
+
+    expect(getCanvasOperations(h.engine).startSelectObject('missing')).toBe('missing');
+    expect(getCanvasOperations(h.engine).startSelectObject('mask')).toBe('unsupported');
+    expect(getCanvasOperations(h.engine).startSelectObject('disabled')).toBe('disabled');
+    expect(getCanvasOperations(h.engine).startSelectObject('locked')).toBe('locked');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+
+    expect(getCanvasOperations(h.engine).startSelectObject('ready')).toBe('started');
+    expect(h.engine.stores.activeTool.get()).toBe('sam');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('cancels the owned session and decoded preview on a real tool switch', async () => {
+    const h = await createSamHarness();
+    expect(getCanvasOperations(h.engine).startSelectObject('source')).toBe('started');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.hasPreview).toBe(true);
+
+    h.engine.tools.setTool('view');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('suppresses a late preview decode after cancellation and closes its bitmap', async () => {
+    const image = createDeferred<Blob>();
+    const bitmap = createDeferred<ImageBitmap>();
+    const close = vi.fn();
+    const base = createTestStubRasterBackend();
+    const backend = { ...base, createImageBitmap: vi.fn(() => bitmap.promise) };
+    const h = await createSamHarness({ backend, imageResolver: () => image.promise });
+    getCanvasOperations(h.engine).startSelectObject('source');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    const pending = getCanvasOperations(h.engine).processSelectObjectSession();
+    await vi.waitFor(() =>
+      expect(getCanvasOperations(h.engine).stores.samSession.get()?.status).toBe('rendering-preview')
+    );
+    image.resolve(new Blob());
+    await vi.waitFor(() => expect(backend.createImageBitmap).toHaveBeenCalledOnce());
+
+    getCanvasOperations(h.engine).cancelSelectObjectSession();
+    bitmap.resolve({ close, height: 20, width: 20 } as unknown as ImageBitmap);
+
+    await expect(pending).resolves.toBe('stale');
+    expect(close).toHaveBeenCalledOnce();
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('isolates only the source layer in the compositor while a preview is published', async () => {
+    const backend = createRecordingRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(recordingBitmap('sam-mask', 100, 100)));
+    const h = await createSamHarness({ backend, layers: [samLayer('source'), samLayer('other', 30)] });
+    h.engine.stores.checkerboard.set(false);
+    getCanvasOperations(h.engine).startSelectObject('source');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    await getCanvasOperations(h.engine).processSelectObjectSession();
+    h.screen.surface.callLog.length = 0;
+    h.raf.flush();
+
+    expect(h.screen.surface.callLog.filter((entry) => entry.op === 'drawImage')).toHaveLength(1);
+    expect(h.screen.surface.callLog).toEqual(
+      expect.arrayContaining([
+        { args: [0, 0, 100, 100], op: 'rect' },
+        { args: [], op: 'clip' },
+      ])
+    );
+    expect(h.engine.document.getDocument()!.layers.every((layer) => layer.isEnabled)).toBe(true);
+    h.engine.lifecycle.dispose();
+  });
+
+  it('isolates the transformed source layer with display semantics while excluding other layers', async () => {
+    const backend = createRecordingRasterBackend();
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(recordingBitmap('decoded', 20, 15)));
+    // Paint bitmap 10x10 at offset (-4, 6), scaled 2x1.5 and translated (12, 8):
+    // baked world rect {4, 17, 20, 15}.
+    const raster: CanvasLayerContract = {
+      ...samLayer('adjusted-raster'),
+      adjustments: { brightness: 0.2, contrast: -0.1, saturation: 0.3 },
+      blendMode: 'multiply',
+      opacity: 0.4,
+      source: {
+        bitmap: { height: 10, imageName: 'sparse.png', width: 10 },
+        offset: { x: -4, y: 6 },
+        type: 'paint',
+      },
+      transform: { rotation: 0, scaleX: 2, scaleY: 1.5, x: 12, y: 8 },
+    };
+    const control: CanvasLayerContract = {
+      adapter: { beginEndStepPct: [0, 0.75], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      blendMode: 'screen',
+      id: 'control',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Control',
+      opacity: 0.65,
+      source: { image: { height: 12, imageName: 'control.png', width: 14 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 30, y: 20 },
+      type: 'control',
+      withTransparencyEffect: true,
+    };
+    const mask: CanvasInpaintMaskLayerContract = {
+      ...samLayer('mask'),
+      mask: { bitmap: { height: 20, imageName: 'mask.png', width: 20 }, fill: { color: '#fff', style: 'solid' } },
+      type: 'inpaint_mask',
+    };
+    const h = await createSamHarness({
+      backend,
+      layers: [mask, control, raster],
+      runGraph: () => Promise.resolve({ height: 15, imageName: 'sam-mask.png', origin: 'test', width: 20 }),
+      uploadIntermediate: () => Promise.resolve({ height: 15, imageName: 'sam-source.png', width: 20 }),
+    });
+    h.engine.stores.checkerboard.set(false);
+    expect(getCanvasOperations(h.engine).startSelectObject('adjusted-raster')).toBe('started');
+    expect(getCanvasOperations(h.engine).stores.samSession.get()?.sourceRect).toEqual({
+      height: 15,
+      width: 20,
+      x: 4,
+      y: 17,
+    });
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 18 }], type: 'visual' },
+    });
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+    h.screen.surface.callLog.length = 0;
+    h.raf.flush();
+
+    const draws = h.screen.surface.callLog.filter((entry) => entry.op === 'drawImage');
+    expect(draws).toHaveLength(1);
+    expect(h.screen.surface.callLog).toEqual(
+      expect.arrayContaining([
+        { args: ['globalAlpha', 0.4], op: 'set' },
+        { args: ['globalCompositeOperation', 'multiply'], op: 'set' },
+        { args: [4, 17, 20, 15], op: 'rect' },
+      ])
+    );
+    expect(h.screen.surface.callLog).not.toContainEqual({ args: ['globalAlpha', 0.65], op: 'set' });
+    expect(h.screen.surface.callLog).not.toContainEqual({ args: ['globalCompositeOperation', 'screen'], op: 'set' });
+    expect(adjustedSurfaceCacheGets).toContain('adjusted-raster');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('encodes exactly the baked source layer surface, excluding other layers and previews', async () => {
+    const backend = createRecordingRasterBackend();
+    const encoded: StubRasterSurface[] = [];
+    backend.encodeSurface = vi.fn((surface) => {
+      encoded.push(surface as StubRasterSurface);
+      return Promise.resolve(new Blob(['baked-layer'], { type: 'image/png' }));
+    });
+    backend.createImageBitmap = vi.fn(() => Promise.resolve(recordingBitmap('decoded', 12, 24)));
+    // Paint bitmap 6x8 at offset (-4, 6), scaled 2x3 and translated (20, 30):
+    // baked world rect {12, 48, 12, 24}.
+    const raster: CanvasLayerContract = {
+      ...samLayer('raster'),
+      source: {
+        bitmap: { height: 8, imageName: 'raster.png', width: 6 },
+        offset: { x: -4, y: 6 },
+        type: 'paint',
+      },
+      transform: { rotation: 0, scaleX: 2, scaleY: 3, x: 20, y: 30 },
+    };
+    const control: CanvasLayerContract = {
+      adapter: { beginEndStepPct: [0, 0.75], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+      blendMode: 'normal',
+      id: 'control',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Control',
+      opacity: 1,
+      source: { image: { height: 10, imageName: 'control.png', width: 10 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 40, y: 50 },
+      type: 'control',
+      withTransparencyEffect: false,
+    };
+    const mask: CanvasInpaintMaskLayerContract = {
+      ...samLayer('mask'),
+      mask: { bitmap: { height: 10, imageName: 'mask.png', width: 10 }, fill: { color: '#fff', style: 'solid' } },
+      type: 'inpaint_mask',
+    };
+    const h = await createSamHarness({
+      backend,
+      layers: [mask, control, raster],
+      runGraph: () => Promise.resolve({ height: 24, imageName: 'sam-mask.png', origin: 'test', width: 12 }),
+      uploadIntermediate: () => Promise.resolve({ height: 24, imageName: 'sam-source.png', width: 12 }),
+    });
+    h.setDocument({ ...h.engine.document.getDocument()!, bbox: { height: 70, width: 80, x: 10, y: 15 } });
+    const rasterExport = await h.engine.exports.exportLayerPixels('raster');
+    const controlExport = await h.engine.exports.exportLayerPixels('control');
+    if (rasterExport.status !== 'ok' || controlExport.status !== 'ok') {
+      throw new Error('expected authoritative layer caches');
+    }
+    await expect(
+      h.engine.previews.setGuardedFilterPreview(
+        'raster',
+        { imageName: 'filter-preview.png', rect: rasterExport.rect },
+        rasterExport.guard
+      )
+    ).resolves.toBe('shown');
+    h.engine.previews.setStagedPreview({ imageName: 'staged.png' });
+    await flushMicrotasks();
+    expect(getCanvasOperations(h.engine).startSelectObject('raster')).toBe('started');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 15, y: 50 }], type: 'visual' },
+    });
+
+    await expect(getCanvasOperations(h.engine).processSelectObjectSession()).resolves.toBe('published');
+
+    const baked = encoded.find((surface) => surface.width === 12 && surface.height === 24);
+    expect(baked).toBeDefined();
+    const log = baked!.callLog;
+    const draws = log.filter((entry) => entry.op === 'drawImage');
+    expect(draws).toHaveLength(1);
+    expect(backend.drawSourcesFor(baked!)).toEqual([backend.surfaceId(rasterExport.surface as StubRasterSurface)]);
+    expect(draws.map((entry) => entry.args.slice(1))).toEqual([[-4, 6]]);
+    expect(log.filter((entry) => entry.op === 'setTransform').map((entry) => entry.args)).toEqual(
+      expect.arrayContaining([[2, 0, 0, 3, 8, -18]])
+    );
+    h.engine.lifecycle.dispose();
+  });
+
+  it('tears down the session when its captured source contract changes', async () => {
+    const h = await createSamHarness();
+    getCanvasOperations(h.engine).startSelectObject('source');
+
+    h.setDocument({
+      ...h.engine.document.getDocument()!,
+      layers: [{ ...h.engine.document.getDocument()!.layers[0]!, opacity: 0.5 }],
+    });
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('owns only the latest session and suppresses in-flight work from the replaced session', async () => {
+    const output = createDeferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const layers = [samLayer('first'), samLayer('second', 30)];
+    const h = await createSamHarness({ layers, runGraph: () => output.promise });
+    getCanvasOperations(h.engine).startSelectObject('first');
+    getCanvasOperations(h.engine).updateSelectObjectSession({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: 5, y: 5 }], type: 'visual' },
+    });
+    const pending = getCanvasOperations(h.engine).processSelectObjectSession();
+    await vi.waitFor(() =>
+      expect(getCanvasOperations(h.engine).stores.samSession.get()?.status).toBe('processing-sam')
+    );
+
+    expect(getCanvasOperations(h.engine).startSelectObject('second')).toBe('started');
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+    output.resolve({ height: 100, imageName: 'late.png', origin: 'late', width: 100 });
+
+    await expect(pending).resolves.toBe('stale');
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toMatchObject({ hasPreview: false });
+    h.engine.lifecycle.dispose();
+  });
+
+  it('lets Escape cancel a gesture before a later Escape cancels the operation', async () => {
+    const h = await createSamHarness();
+    getCanvasOperations(h.engine).startSelectObject('source');
+    h.overlay.fire('pointerdown', pointerAt(5, 5));
+    h.overlay.fire('pointermove', pointerAt(15, 15));
+    h.overlay.fire('pointercancel', pointerAt(15, 15));
+
+    h.engine.tools.handleEscapePriority({ gestureWasActive: true });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).not.toBeNull();
+
+    h.engine.tools.handleEscapePriority({ gestureWasActive: false });
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    h.engine.lifecycle.dispose();
+  });
+
+  it('keeps the Select Object operation active while Space temporarily switches to view', async () => {
+    const h = await createSamHarness();
+    getCanvasOperations(h.engine).startSelectObject('source');
+    h.overlay.fire('pointerenter', {});
+
+    h.fireKey('keydown', 'Space', ' ');
+
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+    expect(getCanvasOperations(h.engine).controller.getSnapshot()).toMatchObject({ status: 'active' });
+    h.fireKey('keyup', 'Space', ' ');
+    expect(h.engine.stores.activeTool.get()).toBe('sam');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not restore sessionless sam when Escape closes the session during a Space hold', async () => {
+    const h = await createSamHarness();
+    getCanvasOperations(h.engine).startSelectObject('source');
+    h.overlay.fire('pointerenter', {});
+    h.fireKey('keydown', 'Space', ' ');
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+
+    h.fireKey('keydown', 'Escape', 'Escape');
+    h.fireKey('keyup', 'Space', ' ');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+    h.engine.lifecycle.dispose();
+  });
+
+  it('does not restore sessionless sam when source invalidation closes the session during a Space hold', async () => {
+    const h = await createSamHarness();
+    getCanvasOperations(h.engine).startSelectObject('source');
+    h.overlay.fire('pointerenter', {});
+    h.fireKey('keydown', 'Space', ' ');
+
+    h.setDocument({
+      ...h.engine.document.getDocument()!,
+      layers: [{ ...h.engine.document.getDocument()!.layers[0]!, opacity: 0.5 }],
+    });
+    h.fireKey('keyup', 'Space', ' ');
+
+    expect(getCanvasOperations(h.engine).stores.samSession.get()).toBeNull();
+    expect(h.engine.stores.activeTool.get()).toBe('view');
+    h.engine.lifecycle.dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.ts
new file mode 100644
index 00000000000..05ca1979db3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/engine.ts
@@ -0,0 +1,3420 @@
+/**
+ * `CanvasEngine`: the per-project imperative heart of the canvas.
+ *
+ * One engine instance exists per project (managed by `engineRegistry.ts`) and
+ * shared by the canvas and layers widgets. It owns interaction, pixels, and
+ * rendering; the reducer owns the document. The document flows in one way
+ * through the {@link createDocumentMirror | document mirror}; the engine never
+ * dispatches from pointer input except for the single gesture-start
+ * `addCanvasLayer` a paint tool emits when auto-creating a layer.
+ *
+ * Responsibilities:
+ * - Hold the {@link Viewport} (pan/zoom) and the transient {@link EngineStores}
+ *   React subscribes to.
+ * - `attach`/`detach` bind two stacked canvases (composited document + overlay)
+ *   as render targets, wire pointer/wheel/key listeners, and drive the
+ *   scheduler; `resize` sizes the backing stores to `css × min(dpr, 2)`.
+ * - Route normalized pointer/wheel input to the active {@link Tool} via the
+ *   pointer pipeline and wheel handler (middle-mouse pan, space/alt temp tools,
+ *   plain-wheel zoom, ctrl+wheel brush-size step), and relay committed strokes
+ *   to `onStrokeCommitted` subscribers.
+ * - Orchestrate rasterization: ensure a raster cache per visible layer, compose
+ *   the document, and draw the overlay each scheduled frame.
+ *
+ * DOM APIs are confined to `attach`/`detach`/`resize` and the DOM raster
+ * backend, so importing this module stays node-safe. Zero React imports.
+ */
+
+import type {
+  CanvasHistoryCapability,
+  CanvasEditCapability,
+  CanvasCompositeExecutorDeps,
+  CanvasDocumentCapability,
+  CanvasDocumentSnapshot,
+  CanvasExportCapability,
+  CanvasRasterSnapshot,
+  CaptureRasterSnapshotResult,
+  CanvasLifecycleCapability,
+  CanvasLayerCapability,
+  CanvasPreviewCapability,
+  CanvasSelectionCapability,
+  CanvasSurfaceCapability,
+  CanvasToolCapability,
+  CanvasViewportCapability,
+  ExportBakedLayerPixelsOptions,
+  ExportLayerPixelsOptions,
+  LayerExportGuard,
+  PsdExportResult,
+} from '@workbench/canvas-engine/api';
+export type {
+  CommitGeneratedImageOptions,
+  CommitGeneratedImageResult,
+  CommitStagedImageOptions,
+  CommitStagedImageResult,
+  ExportBakedLayerBlobResult,
+  ExportBakedLayerPixelsOptions,
+  ExportLayerPixelsOptions,
+  GeneratedImageTarget,
+  LayerExportGuard,
+  LayerThumbnailRequestResult,
+  PsdExportResult,
+  ReplaceSelectionFromImageResult,
+} from '@workbench/canvas-engine/api';
+export type {
+  CommitMaskImageResult,
+  CommitMaskImageResultOptions,
+  MaskImageResultTarget,
+} from '@workbench/canvas-engine/controllers/maskResultController';
+export type {
+  CommitRasterFilterOptions,
+  CommitRasterFilterResult,
+} from '@workbench/canvas-engine/controllers/filterResultController';
+import type { CanvasApplicationHost, SelectObjectStartContext } from '@workbench/canvas-engine/applicationHost';
+import type { CreatePath2D } from '@workbench/canvas-engine/freehand';
+import type { FontLoadApi } from '@workbench/canvas-engine/render/fontLoader';
+import type { LayerCacheEntry, LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { OverlayCursor } from '@workbench/canvas-engine/render/overlayRenderer';
+import type { RenderScheduler } from '@workbench/canvas-engine/render/scheduler';
+import type { SamVisualInput } from '@workbench/canvas-engine/samInteraction';
+import type { Rect, RenderFlags, ToolId, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutationPort } from '@workbench/canvasProjectMutationPort';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type {
+  CanvasImageRef,
+  CanvasDocumentContractV2,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+} from '@workbench/types';
+
+import { ControlPixelController } from '@workbench/canvas-engine/controllers/controlPixelController';
+import { EditingController } from '@workbench/canvas-engine/controllers/editingController';
+import {
+  FilterResultController,
+  type CommitRasterFilterOptions,
+  type CommitRasterFilterResult,
+} from '@workbench/canvas-engine/controllers/filterResultController';
+import { GeneratedResultController } from '@workbench/canvas-engine/controllers/generatedResultController';
+import { HistoryController } from '@workbench/canvas-engine/controllers/historyController';
+import { InteractionController } from '@workbench/canvas-engine/controllers/interactionController';
+import { LayerController } from '@workbench/canvas-engine/controllers/layerController';
+import { LayerMutationController } from '@workbench/canvas-engine/controllers/layerMutationController';
+import {
+  MaskResultController,
+  type CommitMaskImageResult,
+  type CommitMaskImageResultOptions,
+} from '@workbench/canvas-engine/controllers/maskResultController';
+import { PersistenceController } from '@workbench/canvas-engine/controllers/persistenceController';
+import { PsdExportController } from '@workbench/canvas-engine/controllers/psdExportController';
+import { RasterController, type RasterizationJob } from '@workbench/canvas-engine/controllers/rasterController';
+import { RasterExportController } from '@workbench/canvas-engine/controllers/rasterExportController';
+import { RenderController } from '@workbench/canvas-engine/controllers/renderController';
+import { StagedResultController } from '@workbench/canvas-engine/controllers/stagedResultController';
+import { StructuralLayerController } from '@workbench/canvas-engine/controllers/structuralLayerController';
+import { createCanvasDiagnostics, type CanvasDiagnosticsSnapshot } from '@workbench/canvas-engine/diagnostics';
+import { createEngineStores, type EngineStores, type TextToolOptions } from '@workbench/canvas-engine/engineStores';
+import {
+  exportRasterComposite as exportRasterCompositeWithDeps,
+  RasterCompositeOverBudgetError,
+  type RasterCompositeExportRequest,
+  type RasterCompositeExportSnapshot,
+} from '@workbench/canvas-engine/exportRasterComposite';
+import { LayerFilterOutputDimensionError } from '@workbench/canvas-engine/filterError';
+import { createPointerPipeline, type PointerPipeline } from '@workbench/canvas-engine/input/pointerPipeline';
+import { createWheelHandler } from '@workbench/canvas-engine/input/wheel';
+import { fromTRS } from '@workbench/canvas-engine/math/mat2d';
+import { isEmpty, roundOut, transformBounds, union } from '@workbench/canvas-engine/math/rect';
+import {
+  compositeDocument,
+  createCheckerboardTile,
+  shouldSmoothAtZoom,
+} from '@workbench/canvas-engine/render/compositor';
+import { createFontLoader, domFontLoadApi } from '@workbench/canvas-engine/render/fontLoader';
+import { calculateActiveFrameLayerIds } from '@workbench/canvas-engine/render/frameDemand';
+import { createMaskPatternTile } from '@workbench/canvas-engine/render/maskFill';
+import { renderOverlay } from '@workbench/canvas-engine/render/overlayRenderer';
+import { createDomRasterBackend, type RasterBackend, type RasterSurface } from '@workbench/canvas-engine/render/raster';
+import { rasterizeSource, type ImageResolver, type RasterizeDeps } from '@workbench/canvas-engine/render/rasterizers';
+import { textFontString } from '@workbench/canvas-engine/render/rasterizers/textRasterizer';
+import { enforceSurfaceBudget } from '@workbench/canvas-engine/render/surfaceBudget';
+import { getLayerThumbnailDisplayKey } from '@workbench/canvas-engine/render/thumbnail';
+import { ANTS_STEP_PX, createAntsAnimator, type AntsAnimator } from '@workbench/canvas-engine/selection/marchingAnts';
+import { createBboxTool } from '@workbench/canvas-engine/tools/bboxTool';
+import { createBrushTool } from '@workbench/canvas-engine/tools/brushTool';
+import { createColorPickerTool } from '@workbench/canvas-engine/tools/colorPickerTool';
+import { createEraserTool } from '@workbench/canvas-engine/tools/eraserTool';
+import { createGradientTool } from '@workbench/canvas-engine/tools/gradientTool';
+import { createLassoTool } from '@workbench/canvas-engine/tools/lassoTool';
+import { hittableLayerRect, layerOutlineCorners, topLayerAt } from '@workbench/canvas-engine/tools/moveHitTest';
+import { createMoveTool } from '@workbench/canvas-engine/tools/moveTool';
+import { stepBrushSize } from '@workbench/canvas-engine/tools/paintConstants';
+import { createSamTool } from '@workbench/canvas-engine/tools/samTool';
+import { createShapeTool } from '@workbench/canvas-engine/tools/shapeTool';
+import { createTextTool } from '@workbench/canvas-engine/tools/textTool';
+import { createTransformTool } from '@workbench/canvas-engine/tools/transformTool';
+import { type LayerTransform, transformOverlayGeometry } from '@workbench/canvas-engine/transform/transformMath';
+import { createViewport, MAX_DPR, type Viewport } from '@workbench/canvas-engine/viewport';
+
+import type { HistoryEntry } from './history/history';
+import type { StrokeCommittedEvent, Tool, ToolContext } from './tools/tool';
+
+import { createBitmapStore, type BitmapStore } from './document/bitmapStore';
+import { createDocumentMirror, type DocumentMirror } from './document/documentMirror';
+import { getSourceBounds, getSourceContentRect, isRenderableLayer, renderableSourceOf } from './document/sources';
+import { createImagePatchEntry, type ImagePatchApply } from './history/imagePatch';
+import { createViewTool } from './tools/viewTool';
+
+/**
+ * The input to {@link CanvasEnginePreviewCapability.setStagedPreview}: either a persisted image
+ * (decoded via the engine's `imageResolver`, sized to the decoded pixels — the
+ * final staged candidate, optionally with candidate-specific placement) or an
+ * inline data-URL with explicit document-space dimensions (a live
+ * denoise-progress frame, scaled to fill those dims at the current bbox).
+ */
+export interface StagedPreviewPlacement extends Rect {
+  opacity: number;
+}
+
+export type StagedPreviewInput =
+  | { imageName: string; placement?: StagedPreviewPlacement }
+  | { dataUrl: string; width: number; height: number };
+
+export interface FilterPreviewInput {
+  imageName: string;
+  rect: Rect;
+  filterType?: string;
+}
+
+/**
+ * Result of {@link CanvasEngineLayerCapability.mergeVisibleRasterLayers}: `'merged'` when a new
+ * composite layer was inserted, `'not-ready'` when a contributor could not be
+ * rasterized consistently, `'busy'` when another edit owns the document, and
+ * `'nothing'` when fewer than two visible rasters have content.
+ */
+export type MergeVisibleResult = 'merged' | 'not-ready' | 'busy' | 'nothing';
+
+export type BooleanRasterOperation = 'intersect' | 'cutout' | 'cutaway' | 'exclude';
+export type BooleanRasterResult = 'merged' | 'missing' | 'unsupported' | 'not-ready' | 'busy' | 'empty';
+
+export type ExtractMaskedAreaResult =
+  | { status: 'extracted'; layerId: string }
+  | { status: 'missing' | 'unsupported' | 'not-ready' | 'busy' | 'empty' };
+
+export type CropLayerResult =
+  | { status: 'cropped' }
+  | { status: 'missing' | 'locked' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' | 'busy' }
+  | { status: 'failed'; message: string };
+
+/**
+ * Result of {@link CanvasEngineExportCapability.exportRasterLayersToPsd}: `'exported'` on
+ * success, `'nothing'` when there are no raster layers with content, `'too-large'`
+ * when the union bounds exceed the PSD dimension cap, and `'not-ready'` when a
+ * participant's cache is still decoding (nothing exported — surface feedback).
+ */
+/** Opaque snapshot identity carried through async layer operations. */
+export type ExportLayerPixelsResult =
+  | { status: 'ok'; surface: RasterSurface; rect: Rect; guard: LayerExportGuard; release(): void }
+  | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' | 'aborted' };
+
+export type ExportBakedLayerPixelsResult = ExportLayerPixelsResult;
+
+/** Runs every teardown step, then rethrows the first failure after cleanup is terminal. */
+const createCleanupAccumulator = (): { run: (step: () => void) => void; throwIfFailed: () => void } => {
+  let firstError: unknown;
+  let hasFailed = false;
+  return {
+    run: (step) => {
+      try {
+        step();
+      } catch (error) {
+        if (!hasFailed) {
+          firstError = error;
+          hasFailed = true;
+        }
+      }
+    },
+    throwIfFailed: () => {
+      if (hasFailed) {
+        throw firstError instanceof Error ? firstError : new Error(String(firstError));
+      }
+    },
+  };
+};
+
+/** Structural equality for JSON-safe canvas contracts (including synthetic mask paint sources). */
+const isDeeplyEqual = (left: unknown, right: unknown): boolean => {
+  if (Object.is(left, right)) {
+    return true;
+  }
+  if (typeof left !== 'object' || left === null || typeof right !== 'object' || right === null) {
+    return false;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return (
+      Array.isArray(left) &&
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((value, index) => isDeeplyEqual(value, right[index]))
+    );
+  }
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  const leftKeys = Object.keys(leftRecord);
+  const rightKeys = Object.keys(rightRecord);
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key) =>
+        Object.prototype.hasOwnProperty.call(rightRecord, key) && isDeeplyEqual(leftRecord[key], rightRecord[key])
+    )
+  );
+};
+
+export interface CanvasEngineErrorReport {
+  area: 'canvas-engine';
+  context: { error: string; layerId: string };
+  message: 'Layer thumbnail rasterization failed' | 'Bitmap persistence failed';
+  namespace: 'canvas';
+  projectId: string;
+}
+
+/** Options for {@link createCanvasEngine}. */
+export interface CanvasEngineOptions {
+  projectId: string;
+  mutationPort: CanvasProjectMutationPort;
+  /** Persists encoded engine-owned bitmaps. Application networking stays outside the core. */
+  uploadImage(blob: Blob): Promise<{ height: number; imageName: string; width: number }>;
+  /** Supplies the currently selected model base for core-created control layer contracts. */
+  getMainModelBase?: () => string | null;
+  /** Reports structured engine failures without exposing the global workbench dispatcher. */
+  reportError(report: CanvasEngineErrorReport): void;
+  /** Raster surface/bitmap factory. Defaults to the DOM backend. */
+  backend?: RasterBackend;
+  /** Resolves persisted image assets to blobs for decoding. */
+  imageResolver: ImageResolver;
+  /**
+   * Overrides the paint-persistence store. Defaults to a real {@link createBitmapStore}
+   * wired to the layer cache and the upload backend. Tests inject a fake to
+   * observe dirty-marking / avoid network uploads.
+   */
+  bitmapStore?: BitmapStore;
+  /**
+   * Overrides the web-font readiness api used to re-rasterize text layers once a
+   * pending font loads. Defaults to the browser's `document.fonts` (or a no-op
+   * in node). Tests inject a fake to drive the load without a real FontFaceSet.
+   */
+  fonts?: FontLoadApi | null;
+  /** Enables deterministic raster/render counters. Disabled by default. */
+  enableDiagnostics?: boolean;
+}
+
+export interface CanvasEngineToolCapability extends CanvasToolCapability {
+  contextMenuLayerIdAt(screenPoint: Vec2): string | null;
+  handleEscapePriority(options: { gestureWasActive: boolean }): void;
+  onStrokeCommitted(listener: (event: StrokeCommittedEvent) => void): () => void;
+  setInteractionLocked(locked: boolean): void;
+}
+
+export interface CanvasEngineLayerCapability extends CanvasLayerCapability {
+  applyTransform(): void;
+  booleanMergeRasterLayers(upperLayerId: string, operation: BooleanRasterOperation): Promise<BooleanRasterResult>;
+  cancelTextEdit(): void;
+  cancelTransform(): void;
+  clearMask(layerId: string): boolean;
+  commitLayerConversion(label: string, expectedLiveLayer: CanvasLayerContract, after: CanvasLayerContract): boolean;
+  commitLayerCopy(label: string, sourceLayerId: string, layer: CanvasLayerContract, index: number): boolean;
+  commitMaskImageResult(options: CommitMaskImageResultOptions): Promise<CommitMaskImageResult>;
+  commitOpenTextSession(): boolean;
+  commitRasterFilterResult(options: CommitRasterFilterOptions): Promise<CommitRasterFilterResult>;
+  commitTextEdit(content: string, styleChanges?: Partial<TextToolOptions>): void;
+  copyLayerToRaster(layerId: string): Promise<string | null>;
+  cropLayerToBbox(layerId: string): Promise<CropLayerResult>;
+  mergeLayerDown(upperLayerId: string): boolean;
+  mergeVisibleRasterLayers(): Promise<MergeVisibleResult>;
+  nudgeSelectedLayer(dx: number, dy: number): void;
+  openTextCreate(docPoint: Vec2): void;
+  openTextEdit(layerId: string): void;
+  rasterizeLayer(layerId: string): boolean;
+  setTextEditContentReader(reader: (() => string) | null): void;
+  updateTextEditStyle(patch: Partial<TextToolOptions>): void;
+  updateTransformSession(transform: LayerTransform): void;
+}
+
+export interface CanvasEngineExportCapability extends CanvasExportCapability {
+  exportBakedLayerPixels(
+    layerId: string,
+    options?: ExportBakedLayerPixelsOptions
+  ): Promise<ExportBakedLayerPixelsResult>;
+  exportLayerPixels(layerId: string, options?: ExportLayerPixelsOptions): Promise<ExportLayerPixelsResult>;
+  exportRasterLayersToPsd(fileName: string): Promise<PsdExportResult>;
+  extractMaskedArea(maskLayerId: string): Promise<ExtractMaskedAreaResult>;
+}
+
+export interface CanvasEngineSelectionCapability extends CanvasSelectionCapability {}
+
+export interface CanvasEnginePreviewCapability extends CanvasPreviewCapability {
+  setGuardedFilterPreview(
+    layerId: string,
+    input: FilterPreviewInput,
+    guard: LayerExportGuard
+  ): Promise<'shown' | 'missing' | 'stale'>;
+  setStagedPreview(input: StagedPreviewInput | null): void;
+}
+
+export interface CanvasDiagnosticsCapability {
+  clearCaches(): Promise<void>;
+  getDiagnostics(): Readonly<CanvasDiagnosticsSnapshot>;
+  logDebugInfo(): void;
+}
+
+/** The public engine handle. */
+export interface CanvasEngine {
+  readonly projectId: string;
+  readonly surface: CanvasSurfaceCapability;
+  readonly viewport: CanvasViewportCapability;
+  readonly tools: CanvasEngineToolCapability;
+  readonly history: CanvasHistoryCapability;
+  readonly lifecycle: CanvasLifecycleCapability;
+  readonly layers: CanvasEngineLayerCapability;
+  readonly previews: CanvasEnginePreviewCapability;
+  readonly selection: CanvasEngineSelectionCapability;
+  readonly edits: CanvasEditCapability;
+  readonly document: CanvasDocumentCapability;
+  readonly exports: CanvasEngineExportCapability;
+  readonly diagnostics: CanvasDiagnosticsCapability;
+  /** The transient stores React subscribes to. */
+  readonly stores: EngineStores;
+}
+
+export interface CanvasEngineCoreComposition {
+  readonly engine: CanvasEngine;
+  readonly applicationHost: CanvasApplicationHost;
+}
+
+/**
+ * Decodes a `data:` URL to a `Blob` without a DOM (`atob`/`Blob`/`Uint8Array`
+ * are all node-safe), so the staged-progress decode path runs in vitest through
+ * the injected raster backend just like the imageName path runs through the
+ * injected resolver.
+ */
+const dataUrlToBlob = (dataUrl: string): Blob => {
+  const commaIndex = dataUrl.indexOf(',');
+  const header = commaIndex >= 0 ? dataUrl.slice(0, commaIndex) : '';
+  const data = commaIndex >= 0 ? dataUrl.slice(commaIndex + 1) : dataUrl;
+  const mime = /^data:([^;,]+)/i.exec(header)?.[1] ?? 'application/octet-stream';
+  if (/;base64/i.test(header)) {
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return new Blob([bytes], { type: mime });
+  }
+  return new Blob([decodeURIComponent(data)], { type: mime });
+};
+
+const sourceImageName = (source: CanvasLayerSourceContract): string | null => {
+  if (source.type === 'image') {
+    return source.image.imageName;
+  }
+  if (source.type === 'paint') {
+    return source.bitmap?.imageName ?? null;
+  }
+  return null;
+};
+
+/** The image name a layer's source references, if any (raster/control source or mask bitmap). */
+const layerImageName = (layer: CanvasLayerContract): string | null => {
+  const source = renderableSourceOf(layer);
+  return source ? sourceImageName(source) : null;
+};
+
+/** Mints a fresh layer id for engine-created paint layers. */
+const createLayerId = (): string => `layer-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+const createEventId = (): string => `event-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const clearSurface = (surface: RasterSurface): void => {
+  surface.ctx.setTransform(1, 0, 0, 1, 0, 0);
+  surface.ctx.clearRect(0, 0, surface.width, surface.height);
+};
+
+/** Creates a per-project canvas engine. */
+export const createCanvasEngine = (opts: CanvasEngineOptions): CanvasEngineCoreComposition => {
+  const { imageResolver, mutationPort, projectId } = opts;
+  const reportError = (message: CanvasEngineErrorReport['message'], layerId: string, error: unknown): void =>
+    opts.reportError({
+      area: 'canvas-engine',
+      context: { error: error instanceof Error ? error.message : String(error), layerId },
+      message,
+      namespace: 'canvas',
+      projectId,
+    });
+  const backend = opts.backend ?? createDomRasterBackend();
+  const diagnostics = createCanvasDiagnostics(opts.enableDiagnostics);
+
+  const viewport = createViewport();
+  const rasterController = new RasterController({
+    backend,
+    diagnostics,
+    getDocument: () => mirror.getDocument(),
+    getLayerImageName: layerImageName,
+    imageResolver,
+    onVersionChange: (layerId) => editingController?.invalidateLayer(layerId),
+  });
+  const layerCache = rasterController.layers;
+  const stores = createEngineStores();
+  // Web-font readiness for text layers: re-rasterizes a text layer once its font
+  // resolves (a no-op in node / when `document.fonts` is absent). `undefined`
+  // opts.fonts falls back to the DOM api; an explicit `null` forces the no-op.
+  const fontLoader = createFontLoader(opts.fonts === undefined ? domFontLoadApi() : opts.fonts);
+
+  const tools = new Map<ToolId, Tool>([
+    ['view', createViewTool()],
+    ['brush', createBrushTool()],
+    ['eraser', createEraserTool()],
+    ['move', createMoveTool()],
+    ['transform', createTransformTool()],
+    ['bbox', createBboxTool()],
+    ['colorPicker', createColorPickerTool()],
+    ['lasso', createLassoTool()],
+    ['shape', createShapeTool()],
+    ['gradient', createGradientTool()],
+    ['text', createTextTool()],
+    ['sam', createSamTool()],
+  ]);
+  let interactionLocked = false;
+
+  // Transient per-layer transform overrides driving the move/transform drag
+  // preview (compositor + overlay read at render time; the mirror stays untouched).
+  // The move tool sets only x/y; the transform tool sets the full transform.
+  const transformOverrides = new Map<
+    string,
+    { x: number; y: number; scaleX?: number; scaleY?: number; rotation?: number }
+  >();
+
+  const cancelLayerRasterization = (layerId: string): void => rasterController.cancelRasterization(layerId);
+  const cancelAllLayerRasterizations = (): void => rasterController.cancelAllRasterization();
+
+  let disposed = false;
+  const activeRasterSnapshots = new Set<CanvasRasterSnapshot>();
+  let lifecycleState: 'active' | 'cooling' | 'cool' | 'disposed' = 'active';
+  let lifecycleGeneration = 0;
+  let cooldownPromise: Promise<'cooled' | 'dirty'> | null = null;
+
+  // The brush/eraser cursor ring, drawn on the overlay (set by the active tool).
+  let overlayCursor: OverlayCursor | null = null;
+
+  // The transparency checkerboard pattern tile, built once (lazily) through the
+  // raster backend and reused each frame (see `createCheckerboardTile`). It is
+  // rebuilt only when the fed checker colors change (theme/color-mode switch),
+  // signalled by nulling it in the `checkerColors` subscription below.
+  let checkerboardTile: RasterSurface | null = null;
+  const getCheckerboardTile = (): RasterSurface => {
+    checkerboardTile ??= createCheckerboardTile(backend, stores.checkerColors.get());
+    return checkerboardTile;
+  };
+
+  // Cached mask fill pattern tiles, keyed by `style:color` (a solid style has no
+  // tile → cached as `null`). Built lazily through the backend seam like the
+  // checkerboard and reused each frame by the compositor's mask colorize path.
+  const maskPatternTiles = new Map<string, RasterSurface | null>();
+  const getMaskPatternTile = (style: string, color: string): RasterSurface | null => {
+    const key = `${style}:${color}`;
+    if (!maskPatternTiles.has(key)) {
+      maskPatternTiles.set(
+        key,
+        createMaskPatternTile(backend, style as Parameters<typeof createMaskPatternTile>[1], color)
+      );
+    }
+    return maskPatternTiles.get(key) ?? null;
+  };
+
+  // Memoized adjusted surfaces for raster layers carrying brightness/contrast/
+  // saturation/curves — rebuilt only when a layer's cache version or its
+  // adjustments change (never per frame). Reused each frame by the compositor.
+  const derivedSurfaceCache = rasterController.derived;
+  const deleteDerivedSurfaces = (layerId: string): void => rasterController.deleteDerivedSurfaces(layerId);
+  const getAdjustedSurface = (layer: CanvasLayerContract, entry: LayerCacheEntry): RasterSurface | null =>
+    rasterController.getAdjustedSurface(layer, entry);
+
+  // Completed-stroke subscribers (persistence P2.2, history P2.3).
+  const strokeListeners = new Set<(event: StrokeCommittedEvent) => void>();
+  const toolChangeListeners = new Set<(change: { from: string; to: string; temporary: boolean }) => void>();
+  let samInputHandler: ((input: SamVisualInput) => void) | null = null;
+  let applicationEscapeHandler: ((gestureWasActive: boolean) => boolean) | null = null;
+
+  /**
+   * A layer's CURRENT document source (raster/control layers only), or `null`
+   * if the layer doesn't exist / isn't a source-bearing layer. Shared by the
+   * bitmap store's source-type flush guard and `onLayersChanged`'s self-echo
+   * check below — both need the same "what does this id currently point at"
+   * lookup. Reads `mirror` by closure; safe because neither caller invokes it
+   * before `mirror` is assigned further down.
+   */
+  const getLayerSourceById = (layerId: string): CanvasLayerSourceContract | null => {
+    const doc = mirror.getDocument();
+    const layer = doc?.layers.find((candidate) => candidate.id === layerId);
+    // Masks expose their alpha bitmap as a synthetic `paint` source so the bitmap
+    // store's source-type/redundant-dispatch guards and the mirror's self-echo
+    // check work uniformly across paint layers and masks.
+    return layer ? renderableSourceOf(layer) : null;
+  };
+
+  const getAuthoritativeLayerSourceById = (layerId: string): CanvasLayerSourceContract | null => {
+    const layer = mutationPort.getCanvasState()?.document.layers.find((candidate) => candidate.id === layerId);
+    return layer ? renderableSourceOf(layer) : null;
+  };
+
+  /**
+   * Applies a persisted bitmap ref + offset to a layer's document contract — the
+   * bitmap store's single swap-on-success dispatch. Raster/control layers take a
+   * `paint` source (`updateCanvasLayerSource`); mask layers take their `mask`
+   * bitmap + offset (`updateCanvasLayerConfig`, preserving the fill). The self-echo
+   * `lastApplied` name the store records covers both, so a mask flush round-tripping
+   * back through the mirror is skipped for re-rasterization exactly like a paint one.
+   */
+  const dispatchLayerBitmap = (layerId: string, bitmap: CanvasImageRef, offset: { x: number; y: number }): boolean => {
+    const doc = mirror.getDocument();
+    const layer = doc?.layers.find((candidate) => candidate.id === layerId);
+    if (!layer) {
+      return false;
+    }
+    if (layer.type === 'raster' || layer.type === 'control') {
+      return mutationPort.dispatch({
+        id: layerId,
+        source: { bitmap, offset, type: 'paint' },
+        type: 'updateCanvasLayerSource',
+      });
+    } else if (layer.type === 'inpaint_mask' || layer.type === 'regional_guidance') {
+      return mutationPort.dispatch({
+        config: { layerType: layer.type, mask: { bitmap, offset } },
+        id: layerId,
+        type: 'updateCanvasLayerConfig',
+      });
+    }
+    return false;
+  };
+
+  // Paint persistence: debounced PNG encode → SHA-256 dedupe → upload → a single
+  // swap-on-success `updateCanvasLayerSource` (paint) / `updateCanvasLayerConfig`
+  // (mask). Wired to committed strokes below.
+  const bitmapStore: BitmapStore =
+    opts.bitmapStore ??
+    createBitmapStore({
+      dispatch: (action) => mutationPort.dispatch(action),
+      dispatchBitmap: (layerId, bitmap, offset) => dispatchLayerBitmap(layerId, bitmap, offset),
+      encodeSurface: (surface) => backend.encodeSurface(surface),
+      getAuthoritativeLayerSource: getAuthoritativeLayerSourceById,
+      getLayerSource: getLayerSourceById,
+      getLayerSurface: (layerId) => {
+        const entry = layerCache.get(layerId);
+        // Content-sized: skip empty (zero-rect) caches — nothing to persist — and
+        // carry the cache's content-rect origin as the paint source offset.
+        if (!entry || entry.rect.width <= 0 || entry.rect.height <= 0) {
+          return null;
+        }
+        return { offset: { x: entry.rect.x, y: entry.rect.y }, surface: entry.surface };
+      },
+      onError: (error, layerId) => reportError('Bitmap persistence failed', layerId, error),
+      uploadImage: (blob) => opts.uploadImage(blob),
+    });
+  const persistenceController = new PersistenceController(bitmapStore);
+
+  // Engine-owned canvas history (paint pixel patches + structural patches).
+  // Project-level undo deliberately no longer covers the canvas (Phase 0).
+  const historyController = new HistoryController({
+    canEdit: () => canEditDocument(),
+    canRedoStore: stores.canRedo,
+    canUndoStore: stores.canUndo,
+    endBurst: () => endNudgeBurst(),
+    isGestureActive: () => pipeline.isGestureActive(),
+  });
+  const history = historyController.history;
+  // Direct pixel writes do not replace the reducer canvas object. Snapshot
+  // freshness therefore also binds to this engine-local content epoch.
+  let rasterContentEpoch = 0;
+  let controlPixelController: ControlPixelController | null = null;
+  const cancelOpenControlPixelEdit = (): void => {
+    controlPixelController?.cancel();
+  };
+
+  const structuralController = new StructuralLayerController({
+    canEdit: () => canEditDocument(),
+    dispatch: (action) => mutationPort.dispatch(action),
+    getDocument: () => mirror.getDocument(),
+    history,
+    isGestureActive: () => pipeline.isGestureActive(),
+  });
+  const endNudgeBurst = (): void => structuralController.endBurst();
+  const commitStructural = (label: string, forward: CanvasProjectMutation, inverse: CanvasProjectMutation): boolean =>
+    structuralController.commit(label, forward, inverse);
+  const nudgeSelectedLayer = (dx: number, dy: number): void => structuralController.nudge(dx, dy);
+
+  /**
+   * The pixel-write bridge shared by undo and redo: put the patch's pixels back
+   * into the layer's live cache surface, propagate the edit, and re-persist.
+   *
+   * ## Undo ↔ bitmap-store convergence (P2.2 reviewer note)
+   *
+   * Undo writes the OLD pixels into the cache and marks the layer dirty while an
+   * upload of the NEW pixels may still be in flight. The sequence converges:
+   *
+   * 1. The in-flight upload finishes and dispatches `updateCanvasLayerSource`
+   *    with the NEW bitmap ref. Because the store recorded that name in
+   *    `lastApplied` before dispatching, the engine's mirror sees it as a
+   *    self-echo ({@link BitmapStore.isSelfEcho}) and does NOT re-rasterize — so
+   *    the cache keeps the OLD pixels this undo just wrote (never clobbered).
+   *    The contract now *transiently* points at the NEW ref.
+   * 2. This `markLayerDirty` schedules a follow-up flush. The bitmap store
+   *    serializes per layer, so it runs after the in-flight upload settles. It
+   *    encodes the cache (now the OLD pixels), hashes it, and the content-hash
+   *    dedupe reuses the OLD pixels' already-uploaded image name — no re-upload.
+   * 3. That flush dispatches the OLD ref, moving `lastApplied` back and pointing
+   *    the contract at the OLD pixels: cache and contract have re-converged.
+   */
+  const applyImagePatch: ImagePatchApply = (layerId, rect, pixels) => {
+    if (!layerCache.get(layerId)) {
+      // The layer's cache is gone (removed/evicted); nothing to restore into.
+      return;
+    }
+    // The patch `rect` is in LAYER-LOCAL coordinates (stable across cache growth).
+    // Grow the cache to cover it before writing — an undo/redo whose region falls
+    // outside the current (possibly shrunk-since) extent must re-expand the cache
+    // rather than write out of bounds. `growToRect` preserves existing pixels.
+    const entry = layerCache.growToRect(layerId, rect);
+    // Match the paint hot path: write pixels straight into the live cache surface
+    // (no re-rasterize from source), translated to the surface's local origin,
+    // then bump version/thumbnail and recomposite.
+    entry.surface.ctx.putImageData(pixels, rect.x - entry.rect.x, rect.y - entry.rect.y);
+    notifyLayerPainted(layerId);
+    // Re-persist the restored pixels (converges the contract ref; see above).
+    bitmapStore.markLayerDirty(layerId);
+  };
+
+  /**
+   * REPLACES a layer's whole cache with a fresh content-sized surface holding
+   * `pixels` placed at `rect` (layer-local). Unlike {@link applyImagePatch} (which
+   * grows + overlays a dirty region into a persistent cache), this swaps the entire
+   * cache extent — used by the transform bake's undo/redo, where the pre- and
+   * post-bake states occupy DIFFERENT rects (an overlay would leave stale pixels
+   * outside the smaller rect). Shields the pixels from the async rasterize pass and
+   * re-persists through the normal dirty path.
+   */
+  const restoreLayerCache = (layerId: string, rect: Rect, pixels: ImageData): void => {
+    layerCache.delete(layerId);
+    deleteDerivedSurfaces(layerId);
+    const entry = layerCache.getOrCreateRect(layerId, rect);
+    if (rect.width > 0 && rect.height > 0) {
+      entry.surface.ctx.putImageData(pixels, 0, 0);
+    }
+    entry.stale = false;
+    notifyLayerPainted(layerId);
+    bitmapStore.markLayerDirty(layerId);
+  };
+
+  const createPath2DImpl: CreatePath2D = (d) => new Path2D(d);
+
+  /** Bumps a layer's cache version after a direct paint (pixels stay fresh) and recomposites. */
+  const notifyLayerPainted = (layerId: string): void => {
+    const entry = layerCache.publishPixels(layerId);
+    if (entry) {
+      rasterContentEpoch += 1;
+      stores.thumbnailVersion.set(layerId, entry.version);
+      stores.thumbnailStatus.set(layerId, 'ready');
+    }
+    if (renderController.previews.hasFilter(layerId)) {
+      clearFilterPreview(layerId);
+    }
+    scheduler.invalidate({ layers: [layerId] });
+  };
+
+  /** Invalidates cached pixels and drops only previews tied to that exact cache version. */
+  const invalidateLayerCache = (layerId: string): void => {
+    cancelLayerRasterization(layerId);
+    layerCache.invalidate(layerId);
+    stores.thumbnailStatus.delete(layerId);
+    if (renderController.previews.hasFilter(layerId)) {
+      clearFilterPreview(layerId);
+    }
+  };
+
+  /**
+   * A composed history entry for a stroke that auto-created its paint layer.
+   * Undo removes the created layer (its cache is dropped by the mirror, so no
+   * pixel restore is needed); redo re-adds the layer, recreates a blank cache,
+   * and re-applies the stroke's `after` pixels.
+   */
+  const createComposedPaintEntry = (
+    created: { layer: CanvasLayerContract; index: number },
+    event: StrokeCommittedEvent,
+    label: string
+  ): HistoryEntry => {
+    const { afterImageData, dirtyRect, layerId } = event;
+    const rect: Rect = { height: dirtyRect.height, width: dirtyRect.width, x: dirtyRect.x, y: dirtyRect.y };
+    const bytes = event.beforeImageData.data.byteLength + afterImageData.data.byteLength + 256;
+    return {
+      bytes,
+      label,
+      redo: () => {
+        mutationPort.dispatch({ index: created.index, layer: created.layer, type: 'addCanvasLayer' });
+        // Re-create an EMPTY cache marked fresh so the async rasterize pass can't
+        // clobber the restored stroke; `applyImagePatch` grows it to the stroke's
+        // content bounds and writes the `after` pixels.
+        const entry = layerCache.getOrCreateRect(layerId, { height: 0, width: 0, x: 0, y: 0 });
+        entry.stale = false;
+        applyImagePatch(layerId, rect, afterImageData);
+      },
+      undo: () => {
+        mutationPort.dispatch({ ids: [layerId], type: 'removeCanvasLayers' });
+      },
+    };
+  };
+
+  const commitOrdinaryStroke = (event: StrokeCommittedEvent): void => {
+    // A fresh stroke ends any open nudge-coalescing burst.
+    endNudgeBurst();
+    notifyLayerPainted(event.layerId);
+    // Persistence first: mark the layer dirty so a debounced upload fires even
+    // when no external subscriber is attached.
+    bitmapStore.markLayerDirty(event.layerId);
+    // Record the edit on the engine-owned history. Guarded against re-entrancy:
+    // an undo/redo replay routes pixels through `applyImagePatch`, not a fresh
+    // stroke, so this never fires during apply — the guard is belt-and-braces.
+    if (!history.isApplying()) {
+      const label = event.tool === 'eraser' ? 'Eraser stroke' : 'Brush stroke';
+      history.push(
+        event.createdLayer
+          ? createComposedPaintEntry(event.createdLayer, event, label)
+          : createImagePatchEntry({
+              after: event.afterImageData,
+              apply: applyImagePatch,
+              before: event.beforeImageData,
+              label,
+              layerId: event.layerId,
+              rect: event.dirtyRect,
+            })
+      );
+    }
+    for (const listener of strokeListeners) {
+      listener(event);
+    }
+  };
+
+  // ---- Selection (transient interaction state) + marching ants ------------
+  //
+  // The selection lives on the engine, never the reducer, and is not undoable
+  // (legacy parity). The lasso tool commits paths through `commitSelection`; the
+  // mask clips paint strokes and drives fill/erase. Marching ants animate on the
+  // overlay only (never recomposite — Task-22 gate) while a selection exists and
+  // the engine is attached.
+
+  let antsPhase = 0;
+
+  const onSelectionChanged = (): void => {
+    // Selection state is already authoritative before this notification runs.
+    // Keep each derived UI/render notification independent and best-effort so a
+    // faulty observer cannot make an applied selection report false failure.
+    try {
+      stores.hasSelection.set(selection.hasSelection());
+    } catch {
+      // The scalar store commits before notifying observers.
+    }
+    try {
+      updateAntsAnimation();
+    } catch {
+      // A later selection mutation/attach transition reconciles animation.
+    }
+    try {
+      scheduler.invalidate({ overlay: true });
+    } catch {
+      // The next render invalidation will draw the authoritative selection.
+    }
+  };
+
+  const editingController = new EditingController({
+    getDocument: () => mirror.getDocument(),
+    selection: {
+      backend,
+      createPath2D: createPath2DImpl,
+      getDocumentSize: () => {
+        const doc = mirror.getDocument();
+        return doc ? { height: doc.height, width: doc.width } : null;
+      },
+      onChange: () => onSelectionChanged(),
+    },
+    selectionPixels: {
+      applyImagePatch,
+      backend,
+      beginControlEdit: (layerId) => beginControlPixelEdit(layerId),
+      canEdit: () => canEditDocument(),
+      deleteDerived: deleteDerivedSurfaces,
+      endBurst: () => endNudgeBurst(),
+      getDocument: () => mirror.getDocument(),
+      getFillColor: () => stores.brushOptions.get().color,
+      history,
+      invalidateLayer: (layerId) => scheduler.invalidate({ layers: [layerId] }),
+      isGestureActive: () => pipeline.isGestureActive(),
+      layers: layerCache,
+      markDirty: (layerId) => bitmapStore.markLayerDirty(layerId),
+      notifyPainted: notifyLayerPainted,
+    },
+    selectionImage: {
+      capturePermit: (owner) => captureDocumentEditPermit(owner),
+      decodeImage: (image, options) => rasterController.decodeImage(image, options),
+      getDocument: () => mirror.getDocument(),
+      isGestureActive: () => pipeline.isGestureActive(),
+      isGuardCurrent: (guard) => isLayerExportGuardCurrent(guard),
+      isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+    },
+    text: {
+      canEdit: () => canEditDocument(),
+      commitStructural: (label, forward, inverse) => commitStructural(label, forward, inverse),
+      createLayerId,
+      getDocument: () => mirror.getDocument(),
+      invalidate: (payload) => scheduler.invalidate(payload),
+      isGestureActive: () => pipeline.isGestureActive(),
+      options: stores.textOptions,
+      session: stores.textEditSession,
+    },
+    transform: {
+      backend,
+      canEdit: () => canEditDocument(),
+      dispatch: (action) => mutationPort.dispatch(action),
+      endBurst: () => endNudgeBurst(),
+      getCache: (layerId) => layerCache.get(layerId) ?? null,
+      getDocument: () => mirror.getDocument(),
+      invalidate: (payload) => scheduler.invalidate(payload),
+      isGestureActive: () => pipeline.isGestureActive(),
+      pushHistory: (entry) => history.push(entry),
+      replaceCache: (layerId, rect, surface) => {
+        layerCache.delete(layerId);
+        const target = layerCache.getOrCreateRect(layerId, rect);
+        target.surface.ctx.drawImage(surface.canvas, 0, 0);
+        target.stale = false;
+        notifyLayerPainted(layerId);
+        bitmapStore.markLayerDirty(layerId);
+      },
+      restoreCache: restoreLayerCache,
+      session: stores.transformSession,
+      setOverride: (layerId, transform) => {
+        if (transform) {
+          transformOverrides.set(layerId, transform);
+        } else {
+          transformOverrides.delete(layerId);
+        }
+      },
+    },
+  });
+  const selection = editingController.selection;
+
+  const antsAnimator: AntsAnimator = createAntsAnimator({
+    cancelFrame: (handle) => globalThis.cancelAnimationFrame(handle),
+    now: () =>
+      typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance.now() : Date.now(),
+    onStep: () => {
+      antsPhase += ANTS_STEP_PX;
+      // Overlay-only: an ants tick never recomposites the document.
+      scheduler.invalidate({ overlay: true });
+    },
+    requestFrame: (callback) => globalThis.requestAnimationFrame(callback),
+  });
+
+  /** Runs the ants loop only while a selection exists AND render targets are bound. */
+  function updateAntsAnimation(): void {
+    if (!disposed && selection.hasSelection() && renderController.getInputElement()) {
+      antsAnimator.start();
+    } else {
+      antsAnimator.stop();
+    }
+  }
+
+  const toolContext: ToolContext = {
+    applyTransform: () => applyTransform(),
+    backend,
+    beginControlPixelEdit: (layerId) => beginControlPixelEdit(layerId),
+    beginTransformSession: (layerId) => beginTransformSession(layerId),
+    cancelTextEdit: () => cancelTextEdit(),
+    cancelTransform: () => cancelTransform(),
+    commitSelection: (commit) => selection.commit(commit),
+    commitStructural: (label, forward, inverse) => commitStructural(label, forward, inverse),
+    createLayerId,
+    createPath2D: createPath2DImpl,
+    dispatch: (action) => mutationPort.dispatch(action),
+    emitStrokeCommitted: (event) => commitOrdinaryStroke(event),
+    getDocument: () => mirror.getDocument(),
+    getSelectionMask: () => selection.mask(),
+    invalidate: (payload) => scheduler.invalidate(payload),
+    layers: layerCache,
+    notifyLayerPainted,
+    getSamInteraction: () => stores.samInteraction.get(),
+    openTextCreate: (docPoint) => openTextCreate(docPoint),
+    openTextEdit: (layerId) => openTextEdit(layerId),
+    setLayerTransformOverride: (layerId, override) => {
+      if (override) {
+        transformOverrides.set(layerId, override);
+      } else {
+        transformOverrides.delete(layerId);
+      }
+      scheduler.invalidate({ layers: [layerId], overlay: true });
+    },
+    setOverlayCursor: (cursor) => {
+      overlayCursor = cursor;
+    },
+    stores,
+    updateCursor: () => updateCursor(),
+    updateSamInput: (input) => samInputHandler?.(input),
+    updateTransformSession: (transform) => updateTransformSession(transform),
+    viewport,
+  };
+
+  const activeTool = (): Tool | undefined => tools.get(interactionController.getActiveToolId());
+
+  /** Applies a CSS cursor to the input element, guarded for node stubs without `style`. */
+  const applyCursorToInput = (cursor: string): void => {
+    const style = renderController.getInputElement()?.style;
+    if (style) {
+      style.cursor = cursor;
+    }
+  };
+
+  const updateCursor = (): void => {
+    const cursor = activeTool()?.cursor?.(toolContext) ?? 'default';
+    stores.cursor.set(cursor);
+    // The store write alone never changes the pointer; apply to the DOM directly.
+    applyCursorToInput(cursor);
+  };
+
+  /**
+   * Resizes the brush/eraser cursor ring in place when the active tool's size
+   * changes without a pointer event (`[`/`]` hotkeys, ctrl+wheel, or the
+   * options-bar slider). The ring's radius otherwise stays stale until the next
+   * pointermove; here we keep its last-known center and just refresh the radius,
+   * then invalidate the overlay so it redraws immediately.
+   */
+  const refreshBrushCursorRadius = (): void => {
+    if (!overlayCursor) {
+      return;
+    }
+    let size: number | null = null;
+    if (interactionController.getActiveToolId() === 'brush') {
+      size = stores.brushOptions.get().size;
+    } else if (interactionController.getActiveToolId() === 'eraser') {
+      size = stores.eraserOptions.get().size;
+    }
+    if (size === null) {
+      return;
+    }
+    overlayCursor = { point: overlayCursor.point, radiusDoc: size / 2 };
+    scheduler.invalidate({ overlay: true });
+  };
+
+  // ---- Rasterization orchestration ---------------------------------------
+
+  const rasterizeDeps = (doc: CanvasDocumentContractV2, signal?: AbortSignal): RasterizeDeps => ({
+    backend,
+    bitmapPool: rasterController.bitmaps,
+    documentSize: { height: doc.height, width: doc.width },
+    resolver: imageResolver,
+    signal,
+    store: layerCache,
+  });
+
+  const isSupportedExportSource = (source: CanvasLayerSourceContract): boolean => {
+    if (source.type === 'shape') {
+      return source.kind !== 'polygon';
+    }
+    return true;
+  };
+
+  const isCurrentRasterizationJob = (layer: CanvasLayerContract): boolean => {
+    const job = rasterController.getRasterizationJob(layer.id);
+    const source = renderableSourceOf(layer);
+    return (
+      !!job &&
+      !!source &&
+      job.version === layerCache.version(layer.id) &&
+      job.documentGeneration === rasterController.getDocumentGeneration() &&
+      isDeeplyEqual(job.source, source)
+    );
+  };
+
+  /**
+   * Starts (or joins) an isolated rasterization. Pixels land in a scratch
+   * surface and are copied into the live cache only while this exact job still
+   * describes the current layer source, cache version, and document.
+   */
+  const getOrStartLayerRasterization = (
+    layer: CanvasLayerContract,
+    document: CanvasDocumentContractV2,
+    signal?: AbortSignal
+  ): Promise<'published' | 'stale' | 'error' | 'aborted'> => {
+    if (signal?.aborted) {
+      return Promise.resolve('aborted');
+    }
+    if (disposed || mutationPort.getCanvasState() === null) {
+      return Promise.resolve('stale');
+    }
+    const liveSource = renderableSourceOf(layer);
+    if (!liveSource || !isSupportedExportSource(liveSource)) {
+      return Promise.resolve('stale');
+    }
+
+    const contentRect = getSourceContentRect(layer, document);
+    const entry = layerCache.getOrCreateRect(layer.id, contentRect);
+    const version = entry.version;
+    const documentGeneration = rasterController.getDocumentGeneration();
+    const source = structuredClone(liveSource);
+    const existing = rasterController.getRasterizationJob(layer.id);
+    if (
+      existing &&
+      existing.version === version &&
+      existing.documentGeneration === documentGeneration &&
+      isDeeplyEqual(existing.source, source)
+    ) {
+      if (!signal) {
+        return existing.promise;
+      }
+      const abort = (): void => {
+        existing.abortedByCaller = true;
+        existing.controller.abort(signal.reason);
+      };
+      signal.addEventListener('abort', abort, { once: true });
+      return existing.promise.finally(() => signal.removeEventListener('abort', abort));
+    }
+    cancelLayerRasterization(layer.id);
+
+    if (source.type === 'text') {
+      fontLoader.ensure(textFontString(source), () => {
+        const currentDocument = mirror.getDocument();
+        const currentLayer = currentDocument?.layers.find((candidate) => candidate.id === layer.id);
+        if (
+          disposed ||
+          mutationPort.getCanvasState() === null ||
+          !currentLayer ||
+          rasterController.getDocumentGeneration() !== documentGeneration ||
+          layerCache.version(layer.id) !== version ||
+          !isDeeplyEqual(renderableSourceOf(currentLayer), source)
+        ) {
+          return;
+        }
+        invalidateLayerCache(layer.id);
+        scheduler.invalidate({ layers: [layer.id] });
+      });
+    }
+
+    const scratch = backend.createSurface(contentRect.width, contentRect.height);
+    const controller = new AbortController();
+    let settleJob!: (result: 'published' | 'stale' | 'error' | 'aborted') => void;
+    const promise = new Promise<'published' | 'stale' | 'error' | 'aborted'>((resolve) => {
+      settleJob = resolve;
+    });
+    const job: RasterizationJob = {
+      controller,
+      documentGeneration,
+      promise,
+      source,
+      version,
+    };
+    const abort = (): void => {
+      job.abortedByCaller = true;
+      controller.abort(signal?.reason);
+    };
+    signal?.addEventListener('abort', abort, { once: true });
+    rasterController.installRasterizationJob(layer.id, job);
+    let published = false;
+    void (async () => {
+      try {
+        const result = await rasterizeSource(source, rasterizeDeps(document, controller.signal), scratch);
+        const currentDocument = mirror.getDocument();
+        const currentLayer = currentDocument?.layers.find((candidate) => candidate.id === layer.id);
+        const currentEntry = layerCache.get(layer.id);
+        if (
+          disposed ||
+          mutationPort.getCanvasState() === null ||
+          rasterController.getRasterizationJob(layer.id) !== job ||
+          rasterController.getDocumentGeneration() !== documentGeneration ||
+          !currentLayer ||
+          !currentEntry ||
+          currentEntry.version !== version ||
+          !isDeeplyEqual(renderableSourceOf(currentLayer), source)
+        ) {
+          return 'stale';
+        }
+
+        if (currentEntry.surface.width !== result.rect.width || currentEntry.surface.height !== result.rect.height) {
+          currentEntry.surface.resize(result.rect.width, result.rect.height);
+        }
+        const ctx = currentEntry.surface.ctx;
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        ctx.clearRect(0, 0, result.rect.width, result.rect.height);
+        if (!isEmpty(result.rect)) {
+          ctx.drawImage(result.surface.canvas, 0, 0);
+        }
+        currentEntry.rect = { ...result.rect };
+        const publishedEntry = layerCache.publishPixels(layer.id);
+        if (!publishedEntry) {
+          return 'stale';
+        }
+        trackPublishedLayerImage(currentLayer);
+        published = true;
+        stores.thumbnailVersion.set(layer.id, publishedEntry.version);
+        stores.thumbnailStatus.set(layer.id, 'ready');
+        scheduler.invalidate({ layers: [layer.id] });
+        return 'published';
+      } catch (error) {
+        if (job.abortedByCaller) {
+          return 'aborted';
+        }
+        const currentDocument = mirror.getDocument();
+        const currentLayer = currentDocument?.layers.find((candidate) => candidate.id === layer.id);
+        if (
+          disposed ||
+          mutationPort.getCanvasState() === null ||
+          rasterController.getRasterizationJob(layer.id) !== job ||
+          rasterController.getDocumentGeneration() !== documentGeneration ||
+          !currentLayer ||
+          layerCache.version(layer.id) !== version ||
+          !isDeeplyEqual(renderableSourceOf(currentLayer), source)
+        ) {
+          return 'stale';
+        }
+        stores.thumbnailStatus.set(layer.id, 'error');
+        try {
+          reportError('Layer thumbnail rasterization failed', layer.id, error);
+        } catch {
+          // Diagnostics must not turn a handled thumbnail failure into a rejection.
+        }
+        return 'error';
+      } finally {
+        signal?.removeEventListener('abort', abort);
+        rasterController.finishRasterizationJob(layer.id, job);
+        const imageName = sourceImageName(source);
+        if (!published && imageName) {
+          releaseBitmapIfUnreferenced(imageName);
+        }
+      }
+    })().then(settleJob, () => settleJob('stale'));
+    return promise;
+  };
+
+  const captureLayerExportGuard = (layer: CanvasLayerContract, entry: LayerCacheEntry): LayerExportGuard => ({
+    cacheVersion: entry.version,
+    documentGeneration: rasterController.getDocumentGeneration(),
+    layer,
+    layerId: layer.id,
+    projectId,
+  });
+
+  const isLayerExportGuardCurrent = (guard: LayerExportGuard): boolean => {
+    if (
+      disposed ||
+      guard.projectId !== projectId ||
+      mutationPort.getCanvasState() === null ||
+      guard.documentGeneration !== rasterController.getDocumentGeneration()
+    ) {
+      return false;
+    }
+    const document = mirror.getDocument();
+    const liveLayer = document?.layers.find((candidate) => candidate.id === guard.layerId);
+    const entry = layerCache.get(guard.layerId);
+    return !!entry && liveLayer === guard.layer && entry.version === guard.cacheVersion;
+  };
+
+  const captureCurrentLayerExportGuard = (layerId: string): LayerExportGuard | null => {
+    const document = mirror.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    const source = layer ? renderableSourceOf(layer) : null;
+    const entry = layerCache.get(layerId);
+    if (
+      !layer ||
+      !source ||
+      !isSupportedExportSource(source) ||
+      !entry ||
+      entry.stale ||
+      isCurrentRasterizationJob(layer) ||
+      isEmpty(entry.rect)
+    ) {
+      return null;
+    }
+    const guard = captureLayerExportGuard(layer, entry);
+    return isLayerExportGuardCurrent(guard) ? guard : null;
+  };
+
+  const documentEditOwner = Symbol('canvas-operation-document-edit-owner');
+  type DocumentEditPermit = { epoch: number; owner?: symbol };
+  let documentEditEpoch = 0;
+  let documentEditingLocked = false;
+  const syncDocumentEditingLock = (): void => {
+    const nextLocked = stores.documentEditingLocked.get();
+    if (nextLocked !== documentEditingLocked) {
+      documentEditingLocked = nextLocked;
+      documentEditEpoch += 1;
+    }
+  };
+  const unsubscribeDocumentEditingLock = stores.documentEditingLocked.subscribe(syncDocumentEditingLock);
+  const canEditDocument = (owner?: symbol): boolean =>
+    owner === documentEditOwner || !stores.documentEditingLocked.get();
+  const captureDocumentEditPermit = (owner?: symbol): DocumentEditPermit | null =>
+    canEditDocument(owner) ? { epoch: documentEditEpoch, owner } : null;
+  const isDocumentEditPermitCurrent = (permit: DocumentEditPermit): boolean =>
+    permit.owner === documentEditOwner || (!stores.documentEditingLocked.get() && permit.epoch === documentEditEpoch);
+
+  const ensureLayerCaches = (doc: CanvasDocumentContractV2, activeFrameLayerIds: ReadonlySet<string>): void => {
+    for (const layer of doc.layers) {
+      // The layer's rasterizable source: a raster/control `source`, or a mask
+      // layer's alpha bitmap viewed as a paint source (colorized at composite).
+      const source = renderableSourceOf(layer);
+      if (!layer.isEnabled || !source || !activeFrameLayerIds.has(layer.id)) {
+        continue;
+      }
+      if (!isRenderableLayer(layer)) {
+        continue;
+      }
+
+      // Ensure a cache entry exists WITHOUT resizing an existing one: a paint
+      // layer's live cache may have grown past its persisted content rect (fresh
+      // unflushed strokes), so we must never resize it down to the contract size
+      // here — that would destroy those pixels. The rasterizer (below, guarded by
+      // `stale`) owns sizing the surface + placing its content rect.
+      const entry = layerCache.getOrCreateRect(layer.id, getSourceContentRect(layer, doc));
+      if (!entry.stale) {
+        continue;
+      }
+
+      void getOrStartLayerRasterization(layer, doc);
+    }
+  };
+
+  const hasExportableLayerContent = (layerId: string): boolean => {
+    const doc = mirror.getDocument();
+    const layer = doc?.layers.find((candidate) => candidate.id === layerId);
+    if (!doc || !layer) {
+      return false;
+    }
+    const source = renderableSourceOf(layer);
+    if (!source || !isSupportedExportSource(source)) {
+      return false;
+    }
+    if (!isEmpty(getSourceContentRect(layer, doc))) {
+      return true;
+    }
+    // Only paint-backed layers (including masks through renderableSourceOf) can
+    // have real pixels beyond their persisted source rect. The live cache must
+    // describe the current source revision and must not be mid-rasterization.
+    if (source.type !== 'paint') {
+      return false;
+    }
+    const entry = layerCache.get(layerId);
+    return !!entry && !entry.stale && !isCurrentRasterizationJob(layer) && !isEmpty(entry.rect);
+  };
+
+  const rasterExportController = new RasterExportController({
+    backend,
+    captureGuard: captureLayerExportGuard,
+    getDocument: () => mirror.getDocument(),
+    getOrStartRasterization: getOrStartLayerRasterization,
+    isGuardCurrent: isLayerExportGuardCurrent,
+    isRasterizing: isCurrentRasterizationJob,
+    isSupportedSource: isSupportedExportSource,
+    layers: layerCache,
+    pin: (layerId) => rasterController.memory.pin(layerId, lifecycleGeneration),
+    reserve: (bytes) => {
+      rasterController.memory.setBaseBytes(layerCache.byteSize());
+      rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+      return rasterController.memory.reserve(bytes, { generation: lifecycleGeneration, purpose: 'raster-export' });
+    },
+  });
+  const rasterizeLayerPixels = rasterExportController.rasterize.bind(rasterExportController);
+  const exportBakedLayerPixels = rasterExportController.baked.bind(rasterExportController);
+  const exportBakedLayerBlob = rasterExportController.blob.bind(rasterExportController);
+  type StructuralExportLayerPixelsResult =
+    | Extract<ExportLayerPixelsResult, { status: 'ok' }>
+    | { status: 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' };
+  const normalizeStructuralExport = async (
+    result: Promise<ExportLayerPixelsResult>
+  ): Promise<StructuralExportLayerPixelsResult> => {
+    const resolved = await result;
+    if (resolved.status === 'ok') {
+      return resolved;
+    }
+    return { status: resolved.status === 'aborted' ? 'not-ready' : resolved.status };
+  };
+  const exportBakedLayerPixelsForStructural = (
+    layerId: string,
+    options?: ExportBakedLayerPixelsOptions
+  ): Promise<StructuralExportLayerPixelsResult> => normalizeStructuralExport(exportBakedLayerPixels(layerId, options));
+  const rasterizeLayerPixelsForStructural = (
+    layerId: string,
+    options?: ExportLayerPixelsOptions
+  ): Promise<StructuralExportLayerPixelsResult> => normalizeStructuralExport(rasterizeLayerPixels(layerId, options));
+  const rasterizeLayerForThumbnail = async (
+    layer: CanvasLayerContract,
+    document: CanvasDocumentContractV2
+  ): Promise<'published' | 'stale' | 'error'> => {
+    const result = await getOrStartLayerRasterization(layer, document);
+    return result === 'aborted' ? 'stale' : result;
+  };
+
+  const cropLayerToBbox = (layerId: string): Promise<CropLayerResult> => layerController.crop.crop(layerId);
+
+  const copyLayerToRaster = (layerId: string): Promise<string | null> => layerController.copy.copyToRaster(layerId);
+
+  /**
+   * Rasterizes a single layer on demand and returns its cache surface plus the
+   * content rect (layer-local origin/size) those pixels occupy, for the
+   * composite-for-generation executor. Rasterize-or-throw: a missing layer, a
+   * non-raster/control layer, or an unsupported source throws a descriptive error
+   * rather than returning a blank surface, so an invoke can never silently drop a
+   * contributing layer. Only invoked for layers the pure planner already selected
+   * (enabled image/paint rasters).
+   */
+  type LayerSurfaceForExportResult =
+    | { status: 'ok'; surface: RasterSurface; rect: Rect }
+    | { status: 'aborted' | 'not-ready' | 'over-budget' };
+  const getLayerSurfaceForExport = async (
+    layerId: string,
+    signal?: AbortSignal
+  ): Promise<LayerSurfaceForExportResult> => {
+    const result = await rasterizeLayerPixels(layerId, { signal });
+    if (result.status === 'ok') {
+      return { rect: result.rect, status: 'ok', surface: result.surface };
+    }
+    if (result.status === 'over-budget') {
+      return { status: 'over-budget' };
+    }
+    if (result.status === 'aborted') {
+      return { status: 'aborted' };
+    }
+    return { status: 'not-ready' };
+  };
+  const requireLayerSurfaceForExport = async (layerId: string): Promise<{ surface: RasterSurface; rect: Rect }> => {
+    const result = await getLayerSurfaceForExport(layerId);
+    if (result.status === 'ok') {
+      return result;
+    }
+    if (result.status === 'over-budget') {
+      throw new RasterCompositeOverBudgetError();
+    }
+    throw new Error(`Cannot rasterize layer ${layerId} for generation: ${result.status}.`);
+  };
+
+  const releaseBitmapIfUnreferenced = (imageName: string): void =>
+    rasterController.releaseBitmapIfUnreferenced(imageName);
+  const trackPublishedLayerImage = (layer: CanvasLayerContract): void =>
+    rasterController.trackPublishedLayerImage(layer);
+
+  const dropLayer = (layerId: string): void => {
+    // Generation-cancel persistence before the id can be restored by undo/redo.
+    // A late upload from the removed incarnation must never target a recreated
+    // paint layer with the same id.
+    try {
+      bitmapStore.discardLayer(layerId);
+    } catch {
+      // Keep authoritative removal cleanup observer-safe for injected stores.
+    }
+    rasterController.dropLayer(layerId);
+    stores.thumbnailVersion.delete(layerId);
+    stores.thumbnailStatus.delete(layerId);
+  };
+
+  // ---- Staged generation preview ------------------------------------------
+
+  /** Drops any staged preview and bumps the token so an in-flight decode is discarded. */
+  const clearStagedPreview = (): void => {
+    if (renderController.previews.clearStaged()) {
+      scheduler.invalidate({ all: true });
+    }
+  };
+
+  /** Decodes a staged-preview input to a surface (imageName via resolver, dataUrl via the backend seam). */
+  const decodeStagedPreview = async (
+    input: StagedPreviewInput
+  ): Promise<{ surface: RasterSurface; width: number; height: number; placement?: StagedPreviewPlacement }> => {
+    if ('imageName' in input) {
+      const blob = await imageResolver(input.imageName);
+      const decoded = await rasterController.decodeBlob(blob);
+      return {
+        height: decoded.decodedHeight,
+        placement: input.placement ? { ...input.placement } : undefined,
+        surface: decoded.surface,
+        width: decoded.decodedWidth,
+      };
+    }
+    const { dataUrl, height, width } = input;
+    const decoded = await rasterController.decodeBlob(dataUrlToBlob(dataUrl), { height, scale: true, width });
+    return { height, surface: decoded.surface, width };
+  };
+
+  const setStagedPreview = (input: StagedPreviewInput | null): void => {
+    if (input === null) {
+      clearStagedPreview();
+      return;
+    }
+    const token = renderController.previews.nextStagedToken();
+    decodeStagedPreview(input)
+      .then((decoded) => {
+        // A newer set/clear superseded this decode while it was in flight.
+        if (renderController.previews.publishStaged(token, decoded)) {
+          scheduler.invalidate({ all: true });
+        }
+      })
+      .catch(() => {
+        // A transient decode failure leaves any prior preview untouched rather
+        // than blanking the canvas; the next selection re-drives a decode.
+      });
+  };
+
+  /**
+   * Drops a layer's filter-preview state and bumps its token so an in-flight
+   * decode for it is discarded — even if the id is later reused (e.g. an undo
+   * that restores a deleted layer must not resurrect a stale decode result
+   * that resolves afterward). The token is bumped, never reset/deleted, so a
+   * later guarded preview for the same id can never collide with a
+   * still-in-flight decode's captured token.
+   */
+  const clearFilterPreview = (layerId: string): void => {
+    if (renderController.previews.clearFilter(layerId)) {
+      scheduler.invalidate({ layers: [layerId] });
+    }
+  };
+
+  /**
+   * Drops every layer's filter-preview state. Used on a wholesale document
+   * replace: none of the outgoing document's previews describe the incoming
+   * document, even if a layer id happens to be reused.
+   */
+  const clearAllFilterPreviews = (): void => {
+    for (const id of renderController.previews.filterLayerIds()) {
+      clearFilterPreview(id);
+    }
+  };
+
+  const publishFilterPreview = async (
+    layerId: string,
+    input: FilterPreviewInput,
+    validate: () => 'shown' | 'missing' | 'stale',
+    guard: LayerExportGuard
+  ): Promise<'shown' | 'missing' | 'stale'> => {
+    const nextToken = renderController.previews.beginGuardedFilter(layerId);
+    const dropGuardedRequest = (): void => {
+      renderController.previews.finishGuardedFilter(layerId, nextToken);
+    };
+    const beforeDecode = validate();
+    if (beforeDecode !== 'shown') {
+      dropGuardedRequest();
+      return beforeDecode;
+    }
+    try {
+      const decoded = await decodeStagedPreview({ imageName: input.imageName });
+      if (input.filterType && (decoded.width !== input.rect.width || decoded.height !== input.rect.height)) {
+        throw new LayerFilterOutputDimensionError(
+          input.filterType,
+          { height: decoded.height, width: decoded.width },
+          input.rect
+        );
+      }
+      const beforePublish = validate();
+      if (beforePublish !== 'shown') {
+        dropGuardedRequest();
+        return beforePublish;
+      }
+      // A newer set/clear for THIS layer superseded the decode in flight.
+      if (!renderController.previews.isFilterTokenCurrent(layerId, nextToken)) {
+        dropGuardedRequest();
+        return 'stale';
+      }
+      renderController.previews.publishFilter(layerId, nextToken, {
+        guard,
+        rect: { ...input.rect },
+        surface: decoded.surface,
+      });
+      scheduler.invalidate({ layers: [layerId] });
+      return 'shown';
+    } catch (error) {
+      // Transient decode failure leaves any prior preview untouched.
+      dropGuardedRequest();
+      if (error instanceof LayerFilterOutputDimensionError) {
+        throw error;
+      }
+      return 'stale';
+    }
+  };
+
+  const setGuardedFilterPreview = (
+    layerId: string,
+    input: FilterPreviewInput,
+    guard: LayerExportGuard
+  ): Promise<'shown' | 'missing' | 'stale'> => {
+    const validate = (): 'shown' | 'missing' | 'stale' => {
+      const liveLayer = mirror.getDocument()?.layers.find((candidate) => candidate.id === layerId);
+      if (!liveLayer) {
+        return 'missing';
+      }
+      if (layerId !== guard.layerId || !isLayerExportGuardCurrent(guard)) {
+        return 'stale';
+      }
+      return 'shown';
+    };
+    return publishFilterPreview(layerId, input, validate, guard);
+  };
+
+  // ---- Render loop --------------------------------------------------------
+
+  /**
+   * The selected-layer bounds outline for the move overlay, or `null`. Only the
+   * move tool draws it; a layer mid-drag (with a live override) is preferred over
+   * the committed selection so the marquee tracks the preview.
+   */
+  const moveOutlineCorners = (doc: CanvasDocumentContractV2): readonly { x: number; y: number }[] | null => {
+    if (interactionController.getActiveToolId() !== 'move') {
+      return null;
+    }
+    const overridden = doc.layers.find((layer) => transformOverrides.has(layer.id));
+    const target = overridden ?? doc.layers.find((layer) => layer.id === doc.selectedLayerId);
+    if (!target) {
+      return null;
+    }
+    return layerOutlineCorners(target, doc, transformOverrides.get(target.id) ?? null);
+  };
+
+  /** The transform-tool frame (rotated bounds + handles + rotation nub), or `null`. */
+  const transformFrameOverlay = (
+    doc: CanvasDocumentContractV2
+  ): {
+    corners: { x: number; y: number }[];
+    handles: { x: number; y: number }[];
+    center: { x: number; y: number };
+    rotationAnchor: { x: number; y: number };
+  } | null => {
+    if (interactionController.getActiveToolId() !== 'transform') {
+      return null;
+    }
+    const session = stores.transformSession.get();
+    if (!session) {
+      return null;
+    }
+    const layer = doc.layers.find((candidate) => candidate.id === session.layerId);
+    // The layer's LOCAL content rect (off-origin aware): the frame must wrap the
+    // pixels where the compositor draws them, not an assumed origin-anchored box.
+    const rect = layer ? hittableLayerRect(layer, doc) : null;
+    if (!rect) {
+      return null;
+    }
+    return transformOverlayGeometry(session.transform, rect);
+  };
+
+  const render = (flags: RenderFlags): void => {
+    const screen = renderController.getScreen();
+    const overlay = renderController.getOverlay();
+    if (!screen || !overlay) {
+      return;
+    }
+    const doc = mirror.getDocument();
+    const view = viewport.viewMatrix(viewport.getDpr());
+
+    if (!doc) {
+      clearSurface(screen);
+      clearSurface(overlay);
+      return;
+    }
+
+    // The composited document only needs redrawing when pixels, layer order, or
+    // the viewport transform changed. An overlay-ONLY invalidation (the common
+    // hover case: a cursor-ring move dispatches `{ overlay: true }`) must NOT
+    // recomposite: the screen canvas retains its last frame, and the overlay is
+    // redrawn on top. Skipping the composite here is the single biggest zoom-lag
+    // win — a full composite up-scales every doc-sized layer surface to fill the
+    // screen, and that fill-rate grows with zoom, so recompositing on every hover
+    // move at high zoom is exactly the reported "laggier the closer you zoom in".
+    const needsComposite = flags.all || flags.view || flags.layers.size > 0;
+    const stagedPreview = renderController.previews.getStaged();
+    const samPreview = renderController.previews.getSam();
+    const filterPreviews = renderController.previews.filterSnapshot();
+    if (needsComposite) {
+      const stagedPlacement = stagedPreview?.placement;
+      const isolatedGuard = samPreview?.isolated ? samPreview.guard : null;
+      const isolatedIds = isolatedGuard ? new Set([isolatedGuard.layerId]) : null;
+      const viewportSize = viewport.getViewportSize();
+      const dpr = viewport.getDpr();
+      const cssWidth = viewportSize.width > 0 ? viewportSize.width : screen.width / dpr;
+      const cssHeight = viewportSize.height > 0 ? viewportSize.height : screen.height / dpr;
+      const viewportTopLeft = viewport.screenToDocument({ x: 0, y: 0 });
+      const viewportBottomRight = viewport.screenToDocument({ x: cssWidth, y: cssHeight });
+      const liveCacheRects = new Map<string, Rect>();
+      for (const layer of doc.layers) {
+        const rect = layerCache.peek(layer.id)?.rect;
+        if (rect) {
+          liveCacheRects.set(layer.id, rect);
+        }
+      }
+      const activeFrameLayerIds = calculateActiveFrameLayerIds({
+        document: doc,
+        isolationLayerIds: isolatedIds ?? undefined,
+        liveCacheRects,
+        transformOverrides: !isolatedGuard ? transformOverrides : undefined,
+        viewport: {
+          height: Math.abs(viewportBottomRight.y - viewportTopLeft.y),
+          width: Math.abs(viewportBottomRight.x - viewportTopLeft.x),
+          x: Math.min(viewportTopLeft.x, viewportBottomRight.x),
+          y: Math.min(viewportTopLeft.y, viewportBottomRight.y),
+        },
+      });
+      ensureLayerCaches(doc, activeFrameLayerIds);
+      const compositeDoc = isolatedIds
+        ? { ...doc, layers: doc.layers.filter((layer) => isolatedIds.has(layer.id)) }
+        : doc;
+      compositeDocument(screen, compositeDoc, layerCache, view, {
+        // Memoized adjusted surfaces for raster layers with brightness/contrast/
+        // saturation/curves (not recomputed per frame — see adjustedSurfaceCache).
+        adjustedSurface: getAdjustedSurface,
+        derivedSurfaces: derivedSurfaceCache,
+        diagnostics,
+        // The raster backend + mask fill tile resolver drive the mask colorize
+        // path (alpha stencil → source-in fill colour/pattern, above all layers).
+        backend,
+        maskPatternTile: getMaskPatternTile,
+        // Non-destructive control-filter previews (drawn in place of the layer's
+        // committed pixels). Only allocated when a preview is actually active.
+        layerPreviews:
+          !isolatedGuard && filterPreviews.size > 0
+            ? new Map(Array.from(filterPreviews, ([id, preview]) => [id, preview]))
+            : null,
+        clipRect: isolatedGuard && samPreview ? samPreview.rect : null,
+        // Feed the cached checkerboard tile only while the toggle is ON; passing
+        // `null` renders transparent documents without a checkerboard.
+        checkerboardTile: stores.checkerboard.get() ? getCheckerboardTile() : null,
+        // Crisp + cheap when zoomed in (nearest-neighbor up-scale), smooth when
+        // shrinking (bilinear down-scale). See `shouldSmoothAtZoom`.
+        imageSmoothing: shouldSmoothAtZoom(viewport.getZoom()),
+        // Candidate-specific placement wins for final images. Progress frames
+        // and legacy image inputs continue to follow the CURRENT bbox origin.
+        stagedPreview:
+          !isolatedGuard && stagedPreview
+            ? {
+                opacity: stagedPlacement?.opacity ?? 1,
+                rect: stagedPlacement
+                  ? {
+                      height: stagedPlacement.height,
+                      width: stagedPlacement.width,
+                      x: stagedPlacement.x,
+                      y: stagedPlacement.y,
+                    }
+                  : { height: stagedPreview.height, width: stagedPreview.width, x: doc.bbox.x, y: doc.bbox.y },
+                surface: stagedPreview.surface,
+              }
+            : null,
+        // While a text-edit session is open on a layer, skip it in the composite —
+        // the contenteditable portal shows its live text instead (avoids double-draw).
+        skipLayerId: stores.textEditSession.get()?.layerId ?? null,
+        transformOverrides: !isolatedGuard && transformOverrides.size > 0 ? transformOverrides : null,
+      });
+
+      rasterController.memory.setBaseBytes(layerCache.byteSize());
+      rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+      const protectedIds = new Set([...activeFrameLayerIds, ...rasterController.memory.pinnedLayerIds()]);
+      const memory = rasterController.memory.snapshot();
+      const surfaceBudgetBytes = Math.max(
+        0,
+        rasterController.memory.budgetBytes - memory.decodedBytes - memory.detachedBytes - memory.reservedBytes
+      );
+      const { evictedBaseLayerIds: evicted } = enforceSurfaceBudget(
+        layerCache,
+        derivedSurfaceCache,
+        protectedIds,
+        surfaceBudgetBytes,
+        diagnostics
+      );
+      rasterController.memory.setBaseBytes(layerCache.byteSize());
+      rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+      // Prune version-keyed dependents for every evicted id (mirrors dropLayer):
+      // the evicted layer's surface is gone, so its adjusted-surface memo and
+      // thumbnail state must not linger keyed to a version the re-rasterized entry
+      // will exceed (the cache floor keeps versions monotonic across the recreate).
+      for (const id of evicted) {
+        deleteDerivedSurfaces(id);
+        stores.thumbnailVersion.delete(id);
+        stores.thumbnailStatus.delete(id);
+      }
+    }
+
+    // The overlay is cheap (a handful of screen-space strokes, independent of
+    // zoom and document size) and shares the `view` transform with the composite,
+    // so redraw it whenever any frame runs — including overlay-only frames.
+    // While the bbox tool drags, the transient preview stands in for the
+    // committed frame so the overlay (rect + handles) tracks the gesture.
+    const bboxPreview = stores.bboxPreview.get();
+    const samSession = stores.samInteraction.get();
+    renderOverlay(overlay, {
+      bbox: bboxPreview ?? doc.bbox,
+      bboxHandles: interactionController.getActiveToolId() === 'bbox',
+      cursor: overlayCursor,
+      // The grid spans the whole viewport at the bbox snap size when the setting
+      // is on (the document rect no longer bounds it).
+      gridSize: stores.bboxGrid.get(),
+      layerOutline: moveOutlineCorners(doc),
+      // The in-progress lasso path (transient) and the committed selection's
+      // animated marching ants. Both are overlay chrome; ants advance via the
+      // ants animator's overlay-only ticks.
+      gradientPreview: stores.gradientPreview.get(),
+      lassoPreview: stores.lassoPreview.get(),
+      marchingAnts: selection.hasSelection() ? { paths: selection.antsPaths(), phase: antsPhase } : null,
+      samInput: samSession?.input.type === 'visual' ? samSession.input : null,
+      samPreview: samPreview ? { opacity: 0.45, rect: samPreview.rect, surface: samPreview.data } : null,
+      bboxOverlay: stores.bboxOverlay.get(),
+      ruleOfThirds: stores.ruleOfThirds.get(),
+      shapePreview: stores.shapePreview.get(),
+      // The passive bbox frame follows the setting, but always renders while the
+      // bbox tool is active so its handles have a frame to attach to (editable).
+      showBbox: stores.showBbox.get() || interactionController.getActiveToolId() === 'bbox',
+      showGrid: stores.showGrid.get(),
+      transformFrame: transformFrameOverlay(doc),
+      view,
+    });
+  };
+
+  const renderController = new RenderController({
+    applyCursor: (value) => applyCursorToInput(value),
+    clearPreview: () => clearStagedPreview(),
+    getInputHandlers: () => ({ ...pipeline, onWheel, reset: () => pipeline.reset() }),
+    isEngineDisposed: () => disposed,
+    onPageHide: () => onPageHide(),
+    onVisibilityChange: () => onVisibilityChange(),
+    onWindowBlur: () => onWindowBlur(),
+    render,
+    setViewportReady: (ready) => stores.viewportReady.set(ready),
+    updateAnimation: () => updateAntsAnimation(),
+    updateCursor: () => updateCursor(),
+  });
+  const scheduler: RenderScheduler = renderController.scheduler;
+  // Stay paused until attached: invalidations accumulate but never request a
+  // (DOM) frame, keeping the engine node-safe before it has render targets.
+  scheduler.pause();
+
+  // ---- Document mirror ----------------------------------------------------
+
+  const mirror: DocumentMirror = createDocumentMirror(mutationPort, {
+    // The bbox rectangle/handles are overlay chrome, so a bbox move is normally
+    // overlay-only (no recomposite). The one exception: a legacy/progress staged
+    // preview is drawn in the COMPOSITE at the current bbox origin, so it must
+    // recomposite to follow the bbox. Explicitly placed candidates do not.
+    onBboxChanged: () => {
+      const staged = renderController.previews.getStaged();
+      scheduler.invalidate(staged && !staged.placement ? { all: true } : { overlay: true });
+    },
+    onDocumentReplaced: () => {
+      const cleanup = createCleanupAccumulator();
+      cleanup.run(() => editingController.invalidateDocument());
+      cleanup.run(() => pipeline.cancelActiveGesture());
+      cleanup.run(cancelOpenControlPixelEdit);
+      const previousImageNames = rasterController.mirroredImageNames();
+      cleanup.run(() => rasterController.invalidateDocument());
+      cleanup.run(() => stores.thumbnailStatus.clear());
+      // A wholesale document swap — project switch, dims/background change, or a
+      // snapshot restore that changes dims — invalidates the pixel history: its
+      // entries reference layers/pixels that no longer describe the live document.
+      //
+      // Cancel any in-flight tool gesture FIRST: a swap mid-drag leaves stale tool
+      // state (a bbox `startBbox`, a move drag anchor) whose pointer-up would
+      // otherwise commit against the replaced document. Routing through the
+      // pipeline clears `gestureActive` and runs the tool's `onPointerCancel`, so
+      // the tool drops its own transient state.
+      // Defensive: a non-bbox active tool won't have cleared a lingering preview.
+      cleanup.run(() => stores.bboxPreview.set(null));
+      cleanup.run(() => history.clear());
+      cleanup.run(endNudgeBurst);
+      // A transform session (which outlives individual gestures) belongs to the
+      // outgoing document; tear it down alongside its preview override.
+      cleanup.run(() => stores.transformSession.set(null));
+      cleanup.run(() => transformOverrides.clear());
+      // A text-edit session likewise belongs to the outgoing document; drop it.
+      cleanup.run(() => stores.textEditSession.set(null));
+      // A staged preview belongs to the outgoing document's bbox/candidates; a
+      // wholesale swap (project switch, snapshot restore) invalidates it.
+      cleanup.run(clearStagedPreview);
+      // Per-layer control-filter previews likewise belong to the outgoing
+      // document — a swap can reuse a layer id with different content, so
+      // pruning only "missing" ids isn't enough; drop them all.
+      cleanup.run(clearAllFilterPreviews);
+      // The selection is document-scoped interaction state: a swap drops it (and
+      // any in-progress lasso preview), stopping the ants loop via onChange.
+      cleanup.run(() => selection.clear());
+      cleanup.run(() => stores.lassoPreview.set(null));
+      const doc = mirror.getDocument();
+      const present = new Set(doc ? doc.layers.map((layer) => layer.id) : []);
+      rasterController.clearMirroredImages();
+      rasterController.clearThumbnailKeys();
+      for (const layer of doc?.layers ?? []) {
+        rasterController.setThumbnailKey(layer.id, getLayerThumbnailDisplayKey(layer));
+        const imageName = layerImageName(layer);
+        if (imageName) {
+          rasterController.setMirroredImage(layer.id, imageName);
+        }
+      }
+      const trackedIds = rasterController.trackedImageIds();
+      for (const layerId of trackedIds) {
+        if (!present.has(layerId)) {
+          cleanup.run(() => dropLayer(layerId));
+        } else {
+          cleanup.run(() => rasterController.untrackLayerImage(layerId));
+        }
+      }
+      // A wholesale replacement can reuse a layer id with a DIFFERENT source, so
+      // a surviving cache entry may hold pixels from the outgoing document.
+      // Invalidate EVERY id in the incoming document — not just ids whose
+      // reference happened to change — to force a re-rasterize from the new
+      // source; a diff can't be trusted across a full swap.
+      for (const layerId of present) {
+        cleanup.run(() => invalidateLayerCache(layerId));
+      }
+      for (const imageName of previousImageNames) {
+        cleanup.run(() => releaseBitmapIfUnreferenced(imageName));
+      }
+      // Persistence bookkeeping (the self-echo `lastApplied` map and pending
+      // debounced flushes) described the OLD document. Drop it so a reused layer
+      // id can't have its next legit persistence dispatch suppressed as a stale
+      // self-echo.
+      cleanup.run(() => bitmapStore.reset());
+      cleanup.run(() => scheduler.invalidate({ all: true }));
+      cleanup.throwIfFailed();
+    },
+    onLayerOrderChanged: () => {
+      scheduler.invalidate({ all: true });
+    },
+    onLayersChanged: (ids, sourceChangedIds) => {
+      const cleanup = createCleanupAccumulator();
+      if (controlPixelController?.isOpenFor(ids)) {
+        cleanup.run(() => pipeline.cancelActiveGesture());
+        cleanup.run(cancelOpenControlPixelEdit);
+      }
+      const doc = mirror.getDocument();
+      for (const id of sourceChangedIds) {
+        cleanup.run(() => editingController.invalidateLayer(id));
+      }
+      for (const id of ids) {
+        cleanup.run(() => editingController.invalidateLayer(id));
+      }
+      const present = new Set(doc ? doc.layers.map((layer) => layer.id) : []);
+      const sourceChanged = new Set(sourceChangedIds);
+      const previousImageNames = new Map(ids.map((id) => [id, rasterController.getMirroredImage(id)]));
+      for (const id of ids) {
+        const layer = doc?.layers.find((candidate) => candidate.id === id);
+        const imageName = layer ? layerImageName(layer) : null;
+        if (imageName) {
+          rasterController.setMirroredImage(id, imageName);
+        } else {
+          rasterController.deleteMirroredImage(id);
+        }
+      }
+      // A transform session outlives individual gestures (and any tool switch,
+      // including a temp modifier-hold), so it can easily outlive its own layer
+      // being deleted out from under it — e.g. deleted via the layers panel
+      // while the pointer is elsewhere, or while temp-switched to view/colorPicker.
+      // Tear it down (session + preview override) the same way a document
+      // replace does, rather than leaving a ghost session/override pointing at
+      // a layer id that no longer exists.
+      const session = stores.transformSession.get();
+      const textSession = stores.textEditSession.get();
+      for (const id of ids) {
+        const layer = doc?.layers.find((candidate) => candidate.id === id);
+        if (!present.has(id)) {
+          rasterController.deleteThumbnailKey(id);
+          cleanup.run(() => dropLayer(id));
+          const previousImageName = previousImageNames.get(id);
+          if (previousImageName) {
+            cleanup.run(() => releaseBitmapIfUnreferenced(previousImageName));
+          }
+          // A control-filter preview (session + decoded surface) belongs to a
+          // specific layer; a layer removed out from under an in-flight or
+          // already-decoded preview (delete via the layers panel, or an undo
+          // that removes it) must have its preview dropped and its decode
+          // token bumped, or a late-resolving decode — or a later undo that
+          // restores this same id — would repopulate a stale preview.
+          cleanup.run(() => clearFilterPreview(id));
+          if (session && session.layerId === id) {
+            cleanup.run(cancelTransform);
+          }
+          // An edit-mode text session whose layer was deleted out from under it
+          // (layers panel, or undo of the add) is torn down the same way.
+          if (textSession && textSession.layerId === id) {
+            cleanup.run(cancelTextEdit);
+          }
+          continue;
+        }
+        const preview = renderController.previews.getFilter(id);
+        if (preview && !isLayerExportGuardCurrent(preview.guard)) {
+          cleanup.run(() => clearFilterPreview(id));
+        }
+        if (!sourceChanged.has(id)) {
+          if (layer) {
+            const displayKey = getLayerThumbnailDisplayKey(layer);
+            if (rasterController.getThumbnailKey(id) !== displayKey) {
+              rasterController.setThumbnailKey(id, displayKey);
+              const currentVersion = stores.thumbnailVersion.get(id);
+              // Cache versions are positive. Negative display tokens cannot
+              // collide with the next cache publication and suppress its redraw.
+              stores.thumbnailVersion.set(
+                id,
+                currentVersion !== undefined && currentVersion < 0 ? currentVersion - 1 : -1
+              );
+            }
+          }
+          // Prop/transform-only change (opacity, blend, lock, visibility,
+          // rename, nudge): the layer object was replaced but its SOURCE
+          // reference is unchanged, so the rasterized pixels are still valid.
+          // Invalidating here would be wasteful for an image layer and
+          // *destructive* for an unflushed paint layer — a `bitmap: null` paint
+          // source rasterizes to a CLEARED surface, wiping strokes that live
+          // only in the cache until their debounced upload lands. The compositor
+          // applies transform/opacity/blend at draw time, so the scheduled
+          // recomposite below is all a prop change needs.
+          continue;
+        }
+        // The layer's source genuinely changed (image swap, or a paint-bitmap
+        // swap from undo/import). Self-echo guard: skip when it's the exact
+        // paint-bitmap ref the bitmap store just applied — the cache already
+        // holds those pixels, so re-rasterizing would needlessly re-fetch and
+        // could flicker. Any other swap invalidates → re-rasterizes.
+        if (layer) {
+          rasterController.setThumbnailKey(id, getLayerThumbnailDisplayKey(layer));
+        }
+        cleanup.run(() => rasterController.untrackLayerImage(id));
+        const previousImageName = previousImageNames.get(id);
+        if (previousImageName) {
+          cleanup.run(() => releaseBitmapIfUnreferenced(previousImageName));
+        }
+        const source = getLayerSourceById(id);
+        if (bitmapStore.isSelfEcho(id, source)) {
+          continue;
+        }
+        cleanup.run(() => invalidateLayerCache(id));
+      }
+      cleanup.run(() => scheduler.invalidate({ layers: ids }));
+      cleanup.throwIfFailed();
+    },
+    onStagingChanged: () => scheduler.invalidate({ overlay: true }),
+  });
+
+  for (const layer of mirror.getDocument()?.layers ?? []) {
+    rasterController.setThumbnailKey(layer.id, getLayerThumbnailDisplayKey(layer));
+    const imageName = layerImageName(layer);
+    if (imageName) {
+      rasterController.setMirroredImage(layer.id, imageName);
+    }
+  }
+
+  // A guarded filter preview belongs to one continuous active-project epoch.
+  // Switching away invalidates published and in-flight work, so returning to
+  // this project cannot resurrect it.
+  let projectWasPresent = mutationPort.getCanvasState() !== null;
+  const unsubscribeProjectPreviewLifecycle = mutationPort.subscribe(() => {
+    const projectIsPresent = mutationPort.getCanvasState() !== null;
+    if (projectWasPresent && !projectIsPresent) {
+      const cleanup = createCleanupAccumulator();
+      cleanup.run(() => editingController.invalidateProject());
+      cleanup.run(() => pipeline.cancelActiveGesture());
+      cleanup.run(cancelOpenControlPixelEdit);
+      cleanup.run(() => rasterController.invalidateDocument());
+      cleanup.run(() => stores.thumbnailStatus.clear());
+      const ids = new Set<string>(renderController.previews.filterLayerIds());
+      for (const layerId of ids) {
+        cleanup.run(() => clearFilterPreview(layerId));
+      }
+      projectWasPresent = false;
+      cleanup.throwIfFailed();
+      return;
+    }
+    projectWasPresent = projectIsPresent;
+  });
+
+  // ---- Viewport → stores/scheduler ---------------------------------------
+
+  // Set while `resize` drives `setViewportSize` synchronously: the resize path
+  // composites in the same task (the anti-strobe fix), so the viewport
+  // subscription must NOT also schedule a `{ view: true }` frame — that pending
+  // flag would recomposite identical content on the next rAF (a second full
+  // composite per ResizeObserver event during a panel-drag resize).
+  let suppressViewportInvalidate = false;
+
+  const unsubscribeViewport = viewport.subscribe(() => {
+    stores.zoom.set(viewport.getZoom());
+    if (!suppressViewportInvalidate) {
+      scheduler.invalidate({ view: true });
+    }
+  });
+
+  // ---- Tool-option / setting stores → overlay + recomposite ---------------
+  //
+  // A brush/eraser size change must resize the cursor ring even with no pointer
+  // event; toggling the checkerboard must recomposite the document.
+  const unsubscribeBrushOptions = stores.brushOptions.subscribe(refreshBrushCursorRadius);
+  const unsubscribeEraserOptions = stores.eraserOptions.subscribe(refreshBrushCursorRadius);
+  const unsubscribeCheckerboard = stores.checkerboard.subscribe(() => scheduler.invalidate({ all: true }));
+  // New checker colors (theme/color-mode switch): drop the cached tile so it
+  // rebuilds with the fed colors on the next composite, then force a recomposite.
+  const unsubscribeCheckerColors = stores.checkerColors.subscribe(() => {
+    checkerboardTile = null;
+    scheduler.invalidate({ all: true });
+  });
+  // The grid lives on the (cheap) overlay; toggling it or changing its snap size
+  // only needs an overlay redraw, never a recomposite.
+  const unsubscribeShowGrid = stores.showGrid.subscribe(() => scheduler.invalidate({ overlay: true }));
+  const unsubscribeBboxGrid = stores.bboxGrid.subscribe(() => {
+    if (stores.showGrid.get()) {
+      scheduler.invalidate({ overlay: true });
+    }
+  });
+  // The bbox frame, bbox overlay shade, and rule-of-thirds guides live on the
+  // (cheap) overlay; toggling any only needs an overlay redraw, never a
+  // recomposite. (`snapToGrid` is a pure interaction preference the bbox tool
+  // reads on gesture — no render effect.)
+  const unsubscribeShowBbox = stores.showBbox.subscribe(() => scheduler.invalidate({ overlay: true }));
+  const unsubscribeBboxOverlay = stores.bboxOverlay.subscribe(() => scheduler.invalidate({ overlay: true }));
+  const unsubscribeRuleOfThirds = stores.ruleOfThirds.subscribe(() => scheduler.invalidate({ overlay: true }));
+
+  // ---- Pointer / wheel / key input ---------------------------------------
+  //
+  // Normalization, capture, coalescing, temp-tool holds, and gesture cancel live
+  // in the pointer pipeline; wheel routing (zoom vs brush-size step) lives in the
+  // wheel handler. The engine just supplies seams and wires the DOM listeners.
+
+  /** Steps the active brush/eraser diameter by one notch (ctrl+wheel or the `[`/`]` hotkeys). */
+  const stepActiveBrushSize = (direction: 1 | -1): void => {
+    if (interactionController.getActiveToolId() === 'brush') {
+      const opts = stores.brushOptions.get();
+      stores.brushOptions.set({ ...opts, size: stepBrushSize(opts.size, direction) });
+    } else if (interactionController.getActiveToolId() === 'eraser') {
+      const opts = stores.eraserOptions.get();
+      stores.eraserOptions.set({ ...opts, size: stepBrushSize(opts.size, direction) });
+    }
+  };
+
+  const interactionController = new InteractionController({
+    beforeSwitch: (from, to, switchOptions) => {
+      for (const listener of toolChangeListeners) {
+        listener({ from, temporary: switchOptions?.temporary === true, to });
+      }
+    },
+    getTool: (toolId) => tools.get(toolId),
+    getToolContext: () => toolContext,
+    invalidateOverlay: () => scheduler.invalidate({ overlay: true }),
+    isLocked: () => interactionLocked,
+    publishActiveTool: (toolId) => stores.activeTool.set(toolId),
+    stepBrushSize: stepActiveBrushSize,
+    updateCursor,
+  });
+  const setTool = (toolId: ToolId, options?: { temporary?: boolean }): void =>
+    interactionController.setTool(toolId, options);
+
+  /**
+   * The engine's Escape priority ladder, run by the pointer pipeline AFTER it
+   * cancels any in-flight gesture, matching the planned chain "gesture → text
+   * session → transform → deselect": cancel an open text-edit session, else an
+   * open transform session, else deselect. A focused text portal consumes Escape
+   * itself (stopPropagation), so this window-level handler only reaches a
+   * defocused-but-open text session. Deselect is suppressed when a drag just
+   * consumed the Escape (`gestureWasActive`), so a mid-lasso Escape drops only the
+   * in-progress path, never the committed selection. Exposed for the pipeline
+   * wiring and node tests (the real DOM keydown listener can't run in node-env).
+   */
+  const handleEscapePriority = ({ gestureWasActive }: { gestureWasActive: boolean }): void => {
+    if (stores.textEditSession.get()) {
+      cancelTextEdit();
+      return;
+    }
+    if (stores.transformSession.get()) {
+      cancelTransform();
+      return;
+    }
+    if (applicationEscapeHandler?.(gestureWasActive)) {
+      return;
+    }
+    if (!gestureWasActive && selection.hasSelection()) {
+      selection.clear();
+    }
+  };
+
+  const pipeline: PointerPipeline = createPointerPipeline({
+    getActiveTool: activeTool,
+    getActiveToolId: () => interactionController.getActiveToolId(),
+    getInputElement: () => renderController.getInputElement(),
+    getToolContext: () => toolContext,
+    handleEscape: handleEscapePriority,
+    hasTool: (id) => tools.has(id),
+    // A primary-button pointerdown while a text-edit session is open commits it
+    // (engine reads the live portal content). The pipeline swallows that press.
+    maybeCommitModalSession: () => commitOpenTextSession(),
+    setTool: (id, opts) => setTool(id, opts),
+    updateCursor,
+    viewport,
+  });
+
+  const onWheel = createWheelHandler({
+    getActiveTool: activeTool,
+    getInputElement: () => renderController.getInputElement(),
+    getInvertBrushSizeScroll: () => stores.invertBrushSizeScroll.get(),
+    getToolContext: () => toolContext,
+    invalidate: (payload) => scheduler.invalidate(payload),
+    stepActiveBrushSize,
+    viewport,
+  });
+
+  // ---- Lifecycle: shrink the paint-loss window ---------------------------
+  //
+  // Unload cannot be reliably blocked, so these are fire-and-forget kicks that
+  // narrow the gap between the last paint and its upload; the real barrier is
+  // `flushPendingUploads()`, which invoke/export await. `blur` additionally
+  // resets the pointer pipeline so a held space/alt temp tool doesn't strand
+  // when the window loses focus mid-hold.
+  const kickPendingFlush = (): void => {
+    void persistenceController.flush();
+  };
+  const onPageHide = (): void => {
+    kickPendingFlush();
+  };
+  const onVisibilityChange = (): void => {
+    if (typeof document !== 'undefined' && document.visibilityState === 'hidden') {
+      kickPendingFlush();
+    }
+  };
+  const onWindowBlur = (): void => {
+    pipeline.reset();
+  };
+
+  const clearSamPreview = (): void => {
+    const previous = renderController.previews.clearSam();
+    if (previous) {
+      scheduler.invalidate(previous.isolated ? { all: true } : { overlay: true });
+    }
+  };
+
+  const decodeSelectObjectPreview = async (
+    result: { image: CanvasImageRef; rect: Rect },
+    signal: AbortSignal
+  ): Promise<RasterSurface> => {
+    const validateDecoded = (width: number, height: number): void => {
+      const valid =
+        Number.isInteger(width) &&
+        width > 0 &&
+        Number.isInteger(height) &&
+        height > 0 &&
+        width === result.image.width &&
+        height === result.image.height &&
+        width === result.rect.width &&
+        height === result.rect.height;
+      if (!valid) {
+        throw Object.assign(
+          new Error(
+            `Decoded Select Object preview dimensions ${String(width)}x${String(height)} do not match SAM output ${result.image.width}x${result.image.height} and preview rect ${result.rect.width}x${result.rect.height}.`
+          ),
+          { samErrorCode: 'output-dimension' as const }
+        );
+      }
+    };
+    const decoded = await rasterController.decodeImage(result.image, {
+      scaleToImage: false,
+      signal,
+      validateDecoded,
+    });
+    if (decoded.status !== 'ok') {
+      throw new DOMException('Select Object preview decode was aborted.', 'AbortError');
+    }
+    const surface = decoded.surface;
+    surface.ctx.globalCompositeOperation = 'source-in';
+    surface.ctx.fillStyle = '#38bdf8';
+    surface.ctx.fillRect(0, 0, surface.width, surface.height);
+    surface.ctx.globalCompositeOperation = 'source-over';
+    if (signal.aborted) {
+      throw new DOMException('Select Object preview decode was aborted.', 'AbortError');
+    }
+    return surface;
+  };
+
+  // ---- Public API ---------------------------------------------------------
+
+  const setInteractionLocked = (locked: boolean): void => {
+    if (interactionLocked === locked) {
+      return;
+    }
+    interactionLocked = locked;
+    if (locked) {
+      pipeline.cancelActiveGesture();
+      setTool('view', { temporary: true });
+    }
+  };
+
+  const attach = (screenCanvas: HTMLCanvasElement, overlayCanvas: HTMLCanvasElement): void =>
+    renderController.attach(screenCanvas, overlayCanvas);
+  const detach = (): void => renderController.detach();
+
+  const activate = (): void => {
+    if (disposed) {
+      return;
+    }
+    rasterController.memory.releaseGeneration(lifecycleGeneration);
+    lifecycleGeneration += 1;
+    lifecycleState = 'active';
+    editingController.activate();
+    cooldownPromise = null;
+  };
+
+  const beginCooldown = (): Promise<'cooled' | 'dirty'> => {
+    if (disposed) {
+      return Promise.resolve('cooled');
+    }
+    if (lifecycleState === 'cooling' && cooldownPromise) {
+      return cooldownPromise;
+    }
+    if (lifecycleState === 'cool') {
+      return Promise.resolve('cooled');
+    }
+    psdExportController.cancel();
+    rasterController.memory.releaseGeneration(lifecycleGeneration);
+    lifecycleGeneration += 1;
+    const generation = lifecycleGeneration;
+    lifecycleState = 'cooling';
+    editingController.cooldown();
+    detach();
+    cancelAllLayerRasterizations();
+    cooldownPromise = persistenceController.flush().then(
+      () => {
+        if (disposed || lifecycleState !== 'cooling' || lifecycleGeneration !== generation) {
+          return 'cooled';
+        }
+        layerCache.dispose();
+        derivedSurfaceCache.dispose();
+        renderController.previews.clearFilters();
+        clearStagedPreview();
+        checkerboardTile = null;
+        maskPatternTiles.clear();
+        stores.thumbnailStatus.clear();
+        historyController.cooldown();
+        lifecycleState = 'cool';
+        return 'cooled';
+      },
+      () => {
+        if (!disposed && lifecycleGeneration === generation) {
+          // Retain the cooling state and live caches, but clear the completed
+          // attempt so a zero-reference registry entry can retry persistence.
+          cooldownPromise = null;
+        }
+        return 'dirty';
+      }
+    );
+    return cooldownPromise;
+  };
+
+  const resize = (cssWidth: number, cssHeight: number, dpr: number): void => {
+    // Suppress the viewport subscription's `{ view: true }` invalidate: the
+    // synchronous `render` below already repaints this size change, so letting the
+    // subscription schedule a frame would composite the identical result again on
+    // the next rAF (two full composites per resize event).
+    suppressViewportInvalidate = true;
+    viewport.setViewportSize(cssWidth, cssHeight, dpr);
+    suppressViewportInvalidate = false;
+    const backingDpr = Math.min(dpr, MAX_DPR);
+    const backingWidth = Math.round(cssWidth * backingDpr);
+    const backingHeight = Math.round(cssHeight * backingDpr);
+    renderController.resize(backingWidth, backingHeight);
+    // Composite SYNCHRONOUSLY, in this same task, right after the backing-store
+    // resize. Sizing a `<canvas>` backing store clears it, so deferring the
+    // recomposite to the next rAF (the normal dirty-path) leaves a blank frame
+    // on screen until then — during a continuous panel-drag resize that reads as
+    // a flash/strobe. A same-task repaint lands before the browser paints, so the
+    // canvas never shows empty. `all: true` forces the composite through the T22
+    // dirty gate; `render` no-ops when detached (no surfaces).
+    render({ all: true, layers: new Set<string>(), overlay: true, view: true });
+  };
+
+  const fitToView = (): void => {
+    const doc = mirror.getDocument();
+    if (!doc) {
+      return;
+    }
+    // The document rect is no longer a spatial boundary — fit content ∪ bbox. The
+    // bbox (generation frame) is the primary anchor, so an empty canvas fits it;
+    // any renderable layer beyond the bbox is unioned in so it lands in view.
+    let bounds: Rect = { ...doc.bbox };
+    for (const layer of doc.layers) {
+      if (isRenderableLayer(layer)) {
+        bounds = union(bounds, getSourceBounds(layer, doc));
+      }
+    }
+    viewport.fitToView(bounds, viewport.getViewportSize());
+  };
+
+  const isLayerCacheReadyForOp = (layer: CanvasLayerContract, doc: CanvasDocumentContractV2): boolean => {
+    if (isEmpty(getSourceContentRect(layer, doc))) {
+      return true;
+    }
+    const entry = layerCache.get(layer.id);
+    return !!entry && !entry.stale && !isCurrentRasterizationJob(layer);
+  };
+
+  const prepareGeneratedPaintCache = (layerId: string, rect: Rect, pixels: RasterSurface) =>
+    layerCache.prepareReplacement(layerId, rect, pixels);
+
+  const installGeneratedPaintCache = (
+    prepared: ReturnType<LayerCacheStore['prepareReplacement']>,
+    persist = true
+  ): void => {
+    const { layerId } = prepared;
+    const target = layerCache.installReplacement(prepared);
+
+    // Allocation and raster drawing happen in prepareGeneratedPaintCache().
+    // Once a document mutation has been dispatched and this detached cache has
+    // been installed, observer/scheduling/persistence hooks are notifications:
+    // none may veto the already-applied document+cache transaction. In normal
+    // production code these hooks do not throw; containment protects the
+    // transaction from a faulty subscriber or host scheduling implementation.
+    const notifyBestEffort = (notify: () => void): void => {
+      try {
+        notify();
+      } catch {
+        // The document and cache are already converged. A later render or dirty
+        // mark can retry ancillary work without reporting a false failed commit.
+      }
+    };
+    notifyBestEffort(() => deleteDerivedSurfaces(layerId));
+    notifyBestEffort(() => stores.thumbnailVersion.set(layerId, target.version));
+    if (renderController.previews.hasFilter(layerId)) {
+      notifyBestEffort(() => clearFilterPreview(layerId));
+    }
+    notifyBestEffort(() => scheduler.invalidate({ layers: [layerId] }));
+    if (persist) {
+      notifyBestEffort(() => bitmapStore.markLayerDirty(layerId));
+    }
+  };
+
+  const getReducerDocument = (): CanvasDocumentContractV2 | null => mutationPort.getCanvasState()?.document ?? null;
+  const getMainModelBase = (): string | null => {
+    return opts.getMainModelBase?.() ?? null;
+  };
+
+  const dispatchPreparedMutation = (
+    action: CanvasProjectMutation,
+    isApplied: () => boolean,
+    isMirrored: () => boolean
+  ): void => {
+    try {
+      if (!mutationPort.dispatch(action)) {
+        throw new Error('Canvas document mutation was rejected');
+      }
+    } catch (error) {
+      // Store subscribers run after the reducer has accepted an action. A
+      // faulty observer must not strand an applied document mutation before
+      // its matching engine state and history are published. Preserve real
+      // reducer/dispatch failures by swallowing only when the exact intended
+      // postcondition is visible in the authoritative reducer state.
+      if (!isApplied()) {
+        throw error;
+      }
+      // Notification may have been interrupted before DocumentMirror's
+      // subscriber ran. Reconcile it synchronously from authoritative state
+      // before publishing follow-up state or history.
+      try {
+        mirror.refresh();
+      } catch (refreshError) {
+        if (!isMirrored()) {
+          throw refreshError;
+        }
+      }
+      if (!isMirrored()) {
+        throw error;
+      }
+      return;
+    }
+
+    // A reducer may reject a guarded transaction by returning the unchanged
+    // state without throwing. Do not install its prepared cache or consume a
+    // failure-atomic history entry unless the authoritative postcondition
+    // actually landed.
+    if (!isApplied()) {
+      throw new Error('Canvas document mutation was rejected');
+    }
+    if (!isMirrored()) {
+      try {
+        mirror.refresh();
+      } catch (refreshError) {
+        if (!isMirrored()) {
+          throw refreshError;
+        }
+      }
+      if (!isMirrored()) {
+        throw new Error('Canvas document mutation was not mirrored');
+      }
+    }
+  };
+
+  /** Conversion reducers clone contracts, so their publication postcondition compares by value. */
+  const documentHasLayerContract = (
+    document: CanvasDocumentContractV2 | null,
+    expected: CanvasLayerContract
+  ): boolean => {
+    const current = document?.layers.find((candidate) => candidate.id === expected.id);
+    return current !== undefined && isDeeplyEqual(current, expected);
+  };
+
+  controlPixelController = new ControlPixelController({
+    applyImagePatch,
+    backend,
+    bitmapStore,
+    canEdit: () => canEditDocument(),
+    deleteDerived: deleteDerivedSurfaces,
+    dispatchReplacement: (layer) =>
+      dispatchPreparedMutation(
+        { layer, layerId: layer.id, type: 'replaceCanvasLayer' },
+        () => documentHasLayerContract(getReducerDocument(), layer),
+        () => documentHasLayerContract(mirror.getDocument(), layer)
+      ),
+    endBurst: () => endNudgeBurst(),
+    getActiveProjectId: () => projectId,
+    getDocument: () => mirror.getDocument(),
+    getTransformSession: () => stores.transformSession.get(),
+    history,
+    installPrepared: installGeneratedPaintCache,
+    invalidate: (layerId, overlay) => scheduler.invalidate({ layers: [layerId], overlay: overlay || undefined }),
+    isCacheReady: isLayerCacheReadyForOp,
+    isOperationIdle: () => !stores.documentEditingLocked.get(),
+    layers: layerCache,
+    notifyPainted: notifyLayerPainted,
+    preparePixels: prepareGeneratedPaintCache,
+    projectId,
+    publishStroke: (event) => {
+      for (const listener of strokeListeners) {
+        listener(event);
+      }
+    },
+    setTransformOverride: (layerId, transform) => {
+      if (transform) {
+        transformOverrides.set(layerId, transform);
+      } else {
+        transformOverrides.delete(layerId);
+      }
+    },
+  });
+  const beginControlPixelEdit = controlPixelController.begin.bind(controlPixelController);
+
+  const captureLayerCache = (
+    layer: CanvasLayerContract,
+    doc: CanvasDocumentContractV2
+  ): { pixels: RasterSurface; rect: Rect } | null | 'not-ready' => {
+    const entry = layerCache.get(layer.id);
+    if (!entry || isEmpty(entry.rect)) {
+      return null;
+    }
+    if (isCurrentRasterizationJob(layer) || (entry.stale && !isEmpty(getSourceContentRect(layer, doc)))) {
+      return 'not-ready';
+    }
+    const pixels = backend.createSurface(entry.rect.width, entry.rect.height);
+    pixels.ctx.drawImage(entry.surface.canvas, 0, 0);
+    return { pixels, rect: { ...entry.rect } };
+  };
+
+  const layerNeedsPixelPersistence = (layer: CanvasLayerContract): boolean =>
+    renderableSourceOf(layer)?.type === 'paint';
+
+  const layerMutationController = new LayerMutationController({
+    canEdit: () => canEditDocument(),
+    captureCache: captureLayerCache,
+    discardPersisted: (layerId) => bitmapStore.discardLayer(layerId),
+    dispatchPrepared: dispatchPreparedMutation,
+    endBurst: () => endNudgeBurst(),
+    getDocument: () => mirror.getDocument(),
+    getReducerDocument,
+    history,
+    installPrepared: installGeneratedPaintCache,
+    isGestureActive: () => pipeline.isGestureActive(),
+    needsPixelPersistence: layerNeedsPixelPersistence,
+    preparePixels: prepareGeneratedPaintCache,
+    sameContract: documentHasLayerContract,
+  });
+  const commitLayerCopy = layerMutationController.copy.bind(layerMutationController);
+  const commitLayerConversion = layerMutationController.convert.bind(layerMutationController);
+
+  const replaceSelectionFromImage = editingController.selectionImage.replace.bind(editingController.selectionImage);
+
+  const maskResultController = new MaskResultController({
+    canEdit: (owner) => canEditDocument(owner),
+    createLayerId,
+    dispatchPrepared: dispatchPreparedMutation,
+    endBurst: () => endNudgeBurst(),
+    getDocument: () => mirror.getDocument(),
+    getReducerDocument,
+    history,
+    isGestureActive: () => pipeline.isGestureActive(),
+    isGuardCurrent: isLayerExportGuardCurrent,
+  });
+  const commitMaskImageResult = maskResultController.commit.bind(maskResultController);
+
+  const filterResultController = new FilterResultController({
+    captureCache: captureLayerCache,
+    capturePermit: (owner) => captureDocumentEditPermit(owner),
+    createLayerId,
+    decodeImage: (image, options) => rasterController.decodeImage(image, options),
+    discardPersisted: (layerId) => bitmapStore.discardLayer(layerId),
+    dispatchPrepared: dispatchPreparedMutation,
+    endBurst: () => endNudgeBurst(),
+    getDocument: () => mirror.getDocument(),
+    getMainModelBase,
+    getReducerDocument,
+    history,
+    installPrepared: installGeneratedPaintCache,
+    isGestureActive: () => pipeline.isGestureActive(),
+    isGuardCurrent: isLayerExportGuardCurrent,
+    isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+    needsPixelPersistence: layerNeedsPixelPersistence,
+    preparePixels: prepareGeneratedPaintCache,
+  });
+  const commitRasterFilterResult = filterResultController.commit.bind(filterResultController);
+
+  const generatedResultController = new GeneratedResultController({
+    captureCache: captureLayerCache,
+    capturePermit: (owner) => captureDocumentEditPermit(owner),
+    clearPreview: clearFilterPreview,
+    createLayerId,
+    decodeImage: (image, options) => rasterController.decodeImage(image, options),
+    discardPersisted: (layerId) => bitmapStore.discardLayer(layerId),
+    dispatchPrepared: dispatchPreparedMutation,
+    endBurst: () => endNudgeBurst(),
+    getDocument: () => mirror.getDocument(),
+    getMainModelBase,
+    getReducerDocument,
+    history,
+    installPrepared: installGeneratedPaintCache,
+    isGestureActive: () => pipeline.isGestureActive(),
+    isGuardCurrent: isLayerExportGuardCurrent,
+    isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+    needsPixelPersistence: layerNeedsPixelPersistence,
+    preparePixels: prepareGeneratedPaintCache,
+  });
+  const commitGeneratedImageResult = generatedResultController.commit.bind(generatedResultController);
+
+  const stagedResultController = new StagedResultController({
+    capturePermit: (owner) => captureDocumentEditPermit(owner),
+    createEventId,
+    createLayerId,
+    dispatchPrepared: dispatchPreparedMutation,
+    endBurst: () => endNudgeBurst(),
+    getCanvasState: () => mutationPort.getCanvasState(),
+    getDocument: () => mirror.getDocument(),
+    history,
+    isGestureActive: () => pipeline.isGestureActive(),
+    isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+    now: () => new Date().toISOString(),
+  });
+  const commitStagedImage = stagedResultController.commit.bind(stagedResultController);
+
+  const booleanMergeRasterLayers = (
+    upperLayerId: string,
+    operation: BooleanRasterOperation
+  ): Promise<BooleanRasterResult> => layerController.booleanMerge.merge(upperLayerId, operation);
+
+  const extractMaskedArea = (maskLayerId: string): Promise<ExtractMaskedAreaResult> =>
+    layerController.extractMaskedArea.extract(maskLayerId);
+
+  const mergeLayerDown = (upperLayerId: string): boolean => layerController.merge.mergeDown(upperLayerId);
+  const mergeVisibleRasterLayers = (): Promise<MergeVisibleResult> => layerController.merge.mergeVisible();
+
+  let captureDocumentSnapshot!: () => CanvasDocumentSnapshot | null;
+  let isDocumentSnapshotCurrent!: (snapshot: CanvasDocumentSnapshot) => boolean;
+  let captureRasterSnapshot!: (
+    documentSnapshot: CanvasDocumentSnapshot,
+    layerIds: readonly string[],
+    options?: { signal?: AbortSignal; includeDisabled?: boolean }
+  ) => Promise<CaptureRasterSnapshotResult>;
+  const psdExportController = new PsdExportController({
+    backend,
+    captureDocumentSnapshot: () => captureDocumentSnapshot(),
+    captureRasterSnapshot: (snapshot, layerIds, options) => captureRasterSnapshot(snapshot, layerIds, options),
+    getAvailableBytes: () => {
+      rasterController.memory.setBaseBytes(layerCache.byteSize());
+      rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+      return rasterController.memory.getAvailableBytes();
+    },
+    isDocumentSnapshotCurrent: (snapshot) => isDocumentSnapshotCurrent(snapshot),
+    reserve: (bytes) => {
+      rasterController.memory.setBaseBytes(layerCache.byteSize());
+      rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+      return rasterController.memory.reserve(bytes, { generation: lifecycleGeneration, purpose: 'psd-export' });
+    },
+  });
+  const exportRasterLayersToPsd = (fileName: string): Promise<PsdExportResult> => psdExportController.export(fileName);
+
+  const rasterizeLayer = (layerId: string): boolean => layerController.rasterize.rasterize(layerId);
+
+  // ---- Transform session --------------------------------------------------
+  //
+  // The transform tool opens a session on one layer (start/live transform in
+  // `stores.transformSession`, preview via `transformOverrides`) that outlives
+  // individual pointer gestures. Apply commits — a param edit for image layers,
+  // a pixel bake for paint layers — as ONE undoable entry; Cancel drops the
+  // preview. The transform tool drives begin/update/cancel through the tool
+  // context; React (numeric bar + Apply/Cancel buttons) drives the public API.
+
+  const beginTransformSession = (layerId: string): void => editingController.transform.begin(layerId);
+  const updateTransformSession = (transform: LayerTransform): void => editingController.transform.update(transform);
+  const cancelTransform = (): void => editingController.transform.cancel();
+  const applyTransform = (): void => editingController.transform.apply();
+
+  // ---- Text editing session -----------------------------------------------
+  //
+  // The text tool opens a session (create or edit) exposed through
+  // `stores.textEditSession`; React renders a contenteditable portal over it and
+  // drives the commit (blur / mod+enter) — the engine never sees per-keystroke
+  // content, so commit takes the final content from React. ONE commit per close:
+  // create → `addCanvasLayer` (inverse removes), edit → `updateCanvasLayerSource`
+  // (exact inverse). A no-change / empty-create commit dispatches nothing (cancel
+  // semantics). The options bar restyles the live session via `updateTextEditStyle`.
+
+  const setTextEditContentReader = (reader: (() => string) | null): void =>
+    editingController.text.setContentReader(reader);
+  const openTextCreate = (point: Vec2): void => editingController.text.openCreate(point);
+  const openTextEdit = (layerId: string): void => editingController.text.openEdit(layerId);
+  const updateTextEditStyle = (patch: Partial<TextToolOptions>): void => editingController.text.updateStyle(patch);
+  const cancelTextEdit = (): void => editingController.text.cancel();
+  const commitTextEdit = (content: string, styleChanges?: Partial<TextToolOptions>): void =>
+    editingController.text.commit(content, styleChanges);
+  const commitOpenTextSession = (): boolean => editingController.text.commitOpen();
+
+  // ---- Selection public API -----------------------------------------------
+
+  /**
+   * The bounded domain selectAll/invert operate over now that the document rect is
+   * retired: `content ∪ bbox` — the same union `fitToView` fits. The bbox anchors
+   * an empty canvas; any renderable layer beyond it is unioned in. The closest
+   * coherent analogue of legacy's bounded canvas for the complement in `invert`.
+   */
+  const selectAll = (): void => editingController.selectAll();
+  const deselect = (): void => editingController.deselect();
+  const invertSelection = (): void => editingController.invertSelection();
+
+  const fillSelection = (): void => editingController.selectionPixels.run('fill');
+  const eraseSelection = (): void => editingController.selectionPixels.run('erase');
+
+  const clearMask = (layerId: string): boolean => layerController.mask.clear(layerId);
+  const dispose = (): void => {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    for (const snapshot of activeRasterSnapshots) {
+      snapshot.release();
+    }
+    rasterController.memory.releaseGeneration(lifecycleGeneration);
+    lifecycleGeneration += 1;
+    lifecycleState = 'disposed';
+    const cleanup = createCleanupAccumulator();
+    cleanup.run(() => pipeline.cancelActiveGesture());
+    cleanup.run(cancelOpenControlPixelEdit);
+    cleanup.run(() => controlPixelController?.dispose());
+    cleanup.run(() => filterResultController.dispose());
+    cleanup.run(() => generatedResultController.dispose());
+    cleanup.run(() => stagedResultController.dispose());
+    cleanup.run(() => editingController.dispose());
+    cleanup.run(() => layerController.dispose());
+    cleanup.run(() => layerMutationController.dispose());
+    cleanup.run(() => maskResultController.dispose());
+    cleanup.run(() => interactionController.dispose());
+    cleanup.run(() => psdExportController.dispose());
+    cleanup.run(() => rasterExportController.dispose());
+    cleanup.run(cancelAllLayerRasterizations);
+    cleanup.run(detach);
+    // Drop any open text-edit session (its layer belongs to a document this
+    // engine no longer serves).
+    cleanup.run(() => stores.textEditSession.set(null));
+    // Drop any guarded filter previews outright — the engine is going away, so
+    // there's no render loop left to invalidate for them.
+    cleanup.run(() => antsAnimator.stop());
+    cleanup.run(() => activeTool()?.onDeactivate?.(toolContext));
+    cleanup.run(unsubscribeViewport);
+    cleanup.run(unsubscribeBrushOptions);
+    cleanup.run(unsubscribeEraserOptions);
+    cleanup.run(unsubscribeCheckerboard);
+    cleanup.run(unsubscribeCheckerColors);
+    cleanup.run(unsubscribeShowGrid);
+    cleanup.run(unsubscribeBboxGrid);
+    cleanup.run(unsubscribeShowBbox);
+    cleanup.run(unsubscribeBboxOverlay);
+    cleanup.run(unsubscribeRuleOfThirds);
+    cleanup.run(unsubscribeProjectPreviewLifecycle);
+    cleanup.run(unsubscribeDocumentEditingLock);
+    cleanup.run(() => historyController.dispose());
+    cleanup.run(() => persistenceController.dispose());
+    cleanup.run(() => mirror.dispose());
+    cleanup.run(() => renderController.dispose());
+    cleanup.run(() => rasterController.dispose());
+    cleanup.run(() => stores.thumbnailStatus.clear());
+    cleanup.run(() => strokeListeners.clear());
+    cleanup.run(() => toolChangeListeners.clear());
+    cleanup.run(() => {
+      samInputHandler = null;
+    });
+    cleanup.throwIfFailed();
+  };
+
+  const onStrokeCommitted = (listener: (event: StrokeCommittedEvent) => void): (() => void) => {
+    strokeListeners.add(listener);
+    return () => {
+      strokeListeners.delete(listener);
+    };
+  };
+
+  const clearCaches = async (): Promise<void> => {
+    // Flush pending paint-bitmap uploads FIRST: an unflushed stroke lives only in
+    // the live `layerCache` until the debounced (1500ms) flush persists it. If we
+    // invalidated the cache before flushing, that in-flight stroke would be
+    // destroyed — the next composite re-rasterizes from the (older) source.
+    await persistenceController.flush();
+    const doc = mirror.getDocument();
+    // Invalidate (mark stale → re-rasterize) every live layer cache and drop its
+    // memoized adjusted surface; the next composite rebuilds them from source.
+    for (const layer of doc?.layers ?? []) {
+      invalidateLayerCache(layer.id);
+      deleteDerivedSurfaces(layer.id);
+    }
+    // Drop the derived pattern tiles so they rebuild from the current fed colors.
+    checkerboardTile = null;
+    maskPatternTiles.clear();
+    scheduler.invalidate({ all: true });
+  };
+
+  const clearHistory = (): void => historyController.clear();
+
+  const logDebugInfo = (): void => {
+    const doc = mirror.getDocument();
+    // eslint-disable-next-line no-console
+    console.info('[canvas-engine] debug info', {
+      activeTool: interactionController.getActiveToolId(),
+      bbox: doc?.bbox ?? null,
+      canRedo: history.canRedo(),
+      canUndo: history.canUndo(),
+      document: doc ? { height: doc.height, layers: doc.layers.length, width: doc.width } : null,
+      hasSelection: selection.hasSelection(),
+      projectId,
+      selectedLayerId: doc?.selectedLayerId ?? null,
+      zoom: viewport.getZoom(),
+    });
+  };
+
+  const contextMenuLayerIdAt = (screenPoint: Vec2): string | null => {
+    // Never open the menu over an in-progress edit: a live paint/drag gesture, or
+    // an open transform / text-edit session. Right-click during those belongs to
+    // the interaction, not to picking a layer. Mirrors the mid-gesture guards on
+    // merge/nudge/undo above.
+    if (pipeline.isGestureActive() || stores.transformSession.get() || stores.textEditSession.get()) {
+      return null;
+    }
+    const doc = mirror.getDocument();
+    if (!doc) {
+      return null;
+    }
+    // Same screen→document conversion and group-rank-consistent, live-cache-aware
+    // hit-test the move tool uses for click-selection, so right-clicking a layer
+    // targets exactly the layer a left-click there would select.
+    const documentPoint = viewport.screenToDocument(screenPoint);
+    const hit = topLayerAt(
+      doc,
+      documentPoint,
+      (layer) => layer.isEnabled,
+      (layerId) => layerCache.get(layerId)?.rect
+    );
+    return hit?.id ?? null;
+  };
+
+  const undo = (): void => historyController.undo();
+  const redo = (): void => historyController.redo();
+  const setBboxGrid = (size: number): void => stores.bboxGrid.set(size > 0 ? size : 1);
+  const getViewport = (): Viewport => viewport;
+  const getCompositeExecutorDeps = (): CanvasCompositeExecutorDeps => ({
+    backend,
+    getLayerSurface: requireLayerSurfaceForExport,
+    reserve: (bytes) => {
+      rasterController.memory.setBaseBytes(layerCache.byteSize());
+      rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+      return rasterController.memory.reserveOperation(bytes, { purpose: 'invocation-composite' });
+    },
+    uploadImage: (blob) => opts.uploadImage(blob),
+  });
+  const exportRasterComposite = (request: RasterCompositeExportRequest) =>
+    exportRasterCompositeWithDeps(request, {
+      backend,
+      captureSnapshot: (): RasterCompositeExportSnapshot => ({
+        contentEpoch: rasterContentEpoch,
+        document: mirror.getDocument(),
+        documentGeneration: rasterController.getDocumentGeneration(),
+        lifecycleGeneration,
+      }),
+      getLayerSurface: requireLayerSurfaceForExport,
+      isSnapshotCurrent: (snapshot) =>
+        !disposed &&
+        mutationPort.getCanvasState() !== null &&
+        snapshot.contentEpoch === rasterContentEpoch &&
+        snapshot.document === mirror.getDocument() &&
+        snapshot.documentGeneration === rasterController.getDocumentGeneration() &&
+        snapshot.lifecycleGeneration === lifecycleGeneration,
+      pin: (layerIds) => {
+        const leases = layerIds.map((layerId) => rasterController.memory.pinOperation(layerId));
+        let released = false;
+        return {
+          release: () => {
+            if (released) {
+              return;
+            }
+            released = true;
+            for (const lease of leases) {
+              lease.release();
+            }
+          },
+        };
+      },
+      reserve: (bytes) => {
+        rasterController.memory.setBaseBytes(layerCache.byteSize());
+        rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+        return rasterController.memory.reserveOperation(bytes, { purpose: 'background-snapshot' });
+      },
+    });
+  const surface: CanvasSurfaceCapability = { attach, detach, resize };
+  const viewportCapability: CanvasViewportCapability = { fitToView, getViewport, setBboxGrid };
+  const historyCapability: CanvasHistoryCapability = { clearHistory, redo, undo };
+  const lifecycle: CanvasLifecycleCapability = {
+    activate,
+    beginCooldown,
+    dispose,
+    flushPendingUploads: () => persistenceController.flush(),
+    getLifecycleState: () => lifecycleState,
+  };
+  const layerController = new LayerController({
+    booleanMerge: {
+      backend,
+      capturePermit: () => captureDocumentEditPermit(),
+      createLayerId,
+      dispatchPrepared: dispatchPreparedMutation,
+      endBurst: () => endNudgeBurst(),
+      exportBaked: (layerId) => exportBakedLayerPixelsForStructural(layerId),
+      getDocument: () => mirror.getDocument(),
+      getReducerDocument,
+      history,
+      installPrepared: (prepared) =>
+        installGeneratedPaintCache(prepared as ReturnType<LayerCacheStore['prepareReplacement']>),
+      isCacheReady: isLayerCacheReadyForOp,
+      isGestureActive: () => pipeline.isGestureActive(),
+      isGuardCurrent: isLayerExportGuardCurrent,
+      isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+      preparePixels: prepareGeneratedPaintCache,
+    },
+    crop: {
+      backend,
+      captureCache: captureLayerCache,
+      capturePermit: () => captureDocumentEditPermit(),
+      discardPersisted: (layerId) => bitmapStore.discardLayer(layerId),
+      dispatchPrepared: dispatchPreparedMutation,
+      endBurst: () => endNudgeBurst(),
+      exportBaked: (layerId) => exportBakedLayerPixelsForStructural(layerId, { includeDisabled: true }),
+      getDocument: () => mirror.getDocument(),
+      getReducerDocument,
+      history,
+      installPrepared: (prepared) =>
+        installGeneratedPaintCache(prepared as ReturnType<LayerCacheStore['prepareReplacement']>),
+      isGestureActive: () => pipeline.isGestureActive(),
+      isGuardCurrent: isLayerExportGuardCurrent,
+      isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+      isSupportedSource: isSupportedExportSource,
+      preparePixels: prepareGeneratedPaintCache,
+    },
+    copy: {
+      capturePermit: () => captureDocumentEditPermit(),
+      createLayerId,
+      dispatchPrepared: dispatchPreparedMutation,
+      endBurst: () => endNudgeBurst(),
+      exportBaked: (layerId) => exportBakedLayerPixelsForStructural(layerId, { includeDisabled: true }),
+      getDocument: () => mirror.getDocument(),
+      getReducerDocument,
+      history,
+      installPrepared: (prepared) =>
+        installGeneratedPaintCache(prepared as ReturnType<LayerCacheStore['prepareReplacement']>),
+      isGestureActive: () => pipeline.isGestureActive(),
+      isGuardCurrent: isLayerExportGuardCurrent,
+      isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+      preparePixels: prepareGeneratedPaintCache,
+    },
+    extractMaskedArea: {
+      backend,
+      capturePermit: () => captureDocumentEditPermit(),
+      createLayerId,
+      derived: derivedSurfaceCache,
+      diagnostics,
+      dispatchPrepared: dispatchPreparedMutation,
+      endBurst: () => endNudgeBurst(),
+      exportBaked: (layerId, includeDisabled) => exportBakedLayerPixelsForStructural(layerId, { includeDisabled }),
+      getAdjustedSurface,
+      getDocument: () => mirror.getDocument(),
+      getMaskPattern: getMaskPatternTile,
+      getReducerDocument,
+      hasExportableContent: hasExportableLayerContent,
+      history,
+      installPrepared: (prepared) =>
+        installGeneratedPaintCache(prepared as ReturnType<LayerCacheStore['prepareReplacement']>),
+      isCacheReady: isLayerCacheReadyForOp,
+      isGestureActive: () => pipeline.isGestureActive(),
+      isGuardCurrent: isLayerExportGuardCurrent,
+      isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+      layers: layerCache,
+      preparePixels: prepareGeneratedPaintCache,
+      rasterize: (layerId) => rasterizeLayerPixelsForStructural(layerId),
+    },
+    commitGeneratedImageResult,
+    mask: {
+      applyImagePatch,
+      canEdit: () => canEditDocument(),
+      deleteDerived: deleteDerivedSurfaces,
+      discardPersisted: (layerId) => bitmapStore.discardLayer(layerId),
+      dispatch: (action) => mutationPort.dispatch(action),
+      endBurst: () => endNudgeBurst(),
+      getDocument: () => mirror.getDocument(),
+      history,
+      isCacheReady: isLayerCacheReadyForOp,
+      isGestureActive: () => pipeline.isGestureActive(),
+      layers: layerCache,
+      markDirty: (layerId) => bitmapStore.markLayerDirty(layerId),
+      notifyPainted: notifyLayerPainted,
+      restoreCache: restoreLayerCache,
+    },
+    merge: {
+      backend,
+      canEdit: () => canEditDocument(),
+      capturePermit: () => captureDocumentEditPermit(),
+      createLayerId,
+      dispatch: (action) => mutationPort.dispatch(action),
+      dispatchPrepared: dispatchPreparedMutation,
+      endBurst: () => endNudgeBurst(),
+      exportBaked: (layerId) => exportBakedLayerPixelsForStructural(layerId),
+      getDocument: () => mirror.getDocument(),
+      getReducerDocument,
+      hasExportableContent: hasExportableLayerContent,
+      history,
+      installPrepared: (prepared) =>
+        installGeneratedPaintCache(prepared as ReturnType<LayerCacheStore['prepareReplacement']>),
+      isCacheReady: isLayerCacheReadyForOp,
+      isGestureActive: () => pipeline.isGestureActive(),
+      isGuardCurrent: isLayerExportGuardCurrent,
+      isPermitCurrent: (permit) => isDocumentEditPermitCurrent(permit as DocumentEditPermit),
+      layers: layerCache,
+      markDirty: (layerId) => bitmapStore.markLayerDirty(layerId),
+      notifyPainted: notifyLayerPainted,
+      preparePixels: prepareGeneratedPaintCache,
+    },
+    rasterize: {
+      backend,
+      canEdit: () => canEditDocument(),
+      dispatch: (action) => mutationPort.dispatch(action),
+      endBurst: () => endNudgeBurst(),
+      getDocument: () => mirror.getDocument(),
+      history,
+      isGestureActive: () => pipeline.isGestureActive(),
+      layers: layerCache,
+      markDirty: (layerId) => bitmapStore.markLayerDirty(layerId),
+      notifyPainted: notifyLayerPainted,
+      rasterizeDeps: (document) => rasterizeDeps(document),
+    },
+    structural: structuralController,
+    thumbnail: {
+      backend,
+      getActiveProjectId: () => projectId,
+      getCheckerboard: getCheckerboardTile,
+      getDocument: () => mirror.getDocument(),
+      getEntry: (layerId) => layerCache.get(layerId),
+      getMaskPattern: getMaskPatternTile,
+      isDisposed: () => disposed,
+      isSupportedSource: isSupportedExportSource,
+      pin: (layerId) => rasterController.memory.pin(layerId, lifecycleGeneration),
+      projectId,
+      rasterize: rasterizeLayerForThumbnail,
+      reportError: (layerId, error) => {
+        try {
+          reportError('Layer thumbnail rasterization failed', layerId, error);
+        } catch {
+          // Diagnostics must not turn a handled thumbnail failure into a rejection.
+        }
+      },
+      reserve: (bytes) => {
+        rasterController.memory.setBaseBytes(layerCache.byteSize());
+        rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+        return rasterController.memory.reserve(bytes, { generation: lifecycleGeneration, purpose: 'thumbnail' });
+      },
+      setStatus: (layerId, status) => {
+        if (status) {
+          stores.thumbnailStatus.set(layerId, status);
+        } else {
+          stores.thumbnailStatus.delete(layerId);
+        }
+      },
+    },
+  });
+  const documentSnapshotSources = new WeakMap<
+    CanvasDocumentSnapshot,
+    {
+      canvas: NonNullable<ReturnType<typeof mutationPort.getCanvasState>>;
+      contentEpoch: number;
+      lifecycleGeneration: number;
+    }
+  >();
+  isDocumentSnapshotCurrent = (snapshot: CanvasDocumentSnapshot): boolean => {
+    const source = documentSnapshotSources.get(snapshot);
+    return (
+      !disposed &&
+      source !== undefined &&
+      source.canvas === mutationPort.getCanvasState() &&
+      source.contentEpoch === rasterContentEpoch &&
+      source.lifecycleGeneration === lifecycleGeneration &&
+      snapshot.documentGeneration === rasterController.getDocumentGeneration()
+    );
+  };
+  captureRasterSnapshot = async (
+    documentSnapshot: CanvasDocumentSnapshot,
+    layerIds: readonly string[],
+    options?: { signal?: AbortSignal; includeDisabled?: boolean }
+  ): Promise<CaptureRasterSnapshotResult> => {
+    if (options?.signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    if (!documentSnapshotSources.has(documentSnapshot)) {
+      return { status: 'not-ready' };
+    }
+    if (!isDocumentSnapshotCurrent(documentSnapshot)) {
+      return { status: 'stale' };
+    }
+    const snapshotSource = documentSnapshotSources.get(documentSnapshot)!;
+    const captureLifecycleGeneration = snapshotSource.lifecycleGeneration;
+
+    const uniqueLayerIds = [...new Set(layerIds)];
+    const layerById = new Map(documentSnapshot.canvas.document.layers.map((layer) => [layer.id, layer]));
+    let requestedBytes = 0;
+    for (const layerId of uniqueLayerIds) {
+      const layer = layerById.get(layerId);
+      const source = layer ? renderableSourceOf(layer) : null;
+      if (!layer || !source || !isSupportedExportSource(source)) {
+        return { status: 'not-ready' };
+      }
+      if (source.type === 'image') {
+        requestedBytes += source.image.width * source.image.height * 4;
+      } else if (source.type === 'paint' && source.bitmap) {
+        requestedBytes += source.bitmap.width * source.bitmap.height * 4;
+      } else {
+        const contentRect = getSourceContentRect(layer, documentSnapshot.canvas.document);
+        requestedBytes += contentRect.width * contentRect.height * 4;
+      }
+    }
+
+    rasterController.memory.setBaseBytes(layerCache.byteSize());
+    rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+    const reservation = rasterController.memory.reserve(requestedBytes, {
+      generation: captureLifecycleGeneration,
+      purpose: 'background-snapshot',
+    });
+    if (reservation.status === 'over-budget') {
+      return { status: 'over-budget' };
+    }
+    const reservationLeases: { release(): void }[] = [reservation.lease];
+    const pinLeases = uniqueLayerIds.map((layerId) => rasterController.memory.pin(layerId, captureLifecycleGeneration));
+    const layerSurfaces = new Map<string, { rect: Rect; surface: RasterSurface }>();
+    const emptyLayerIds = new Set<string>();
+    const capturedGuards: LayerExportGuard[] = [];
+    let actualDetachedBytes = 0;
+    try {
+      for (const layerId of uniqueLayerIds) {
+        if (options?.signal?.aborted) {
+          return { status: 'aborted' };
+        }
+        if (!isDocumentSnapshotCurrent(documentSnapshot)) {
+          return { status: 'stale' };
+        }
+        const liveResult = await rasterizeLayerPixels(layerId, {
+          includeDisabled: options?.includeDisabled,
+          signal: options?.signal,
+        });
+        if (options?.signal?.aborted) {
+          return { status: 'aborted' };
+        }
+        if (!isDocumentSnapshotCurrent(documentSnapshot)) {
+          return { status: 'stale' };
+        }
+        if (liveResult.status === 'empty') {
+          emptyLayerIds.add(layerId);
+          continue;
+        }
+        if (liveResult.status !== 'ok') {
+          return {
+            status:
+              liveResult.status === 'aborted' || liveResult.status === 'over-budget' ? liveResult.status : 'not-ready',
+          };
+        }
+        const live = liveResult;
+        if (!isLayerExportGuardCurrent(live.guard)) {
+          live.release();
+          return { status: 'stale' };
+        }
+        capturedGuards.push(live.guard);
+        try {
+          const actualBytes = live.surface.width * live.surface.height * 4;
+          const source = renderableSourceOf(layerById.get(layerId)!);
+          const estimatedBytes =
+            source?.type === 'image'
+              ? source.image.width * source.image.height * 4
+              : source?.type === 'paint' && source.bitmap
+                ? source.bitmap.width * source.bitmap.height * 4
+                : getSourceContentRect(layerById.get(layerId)!, documentSnapshot.canvas.document).width *
+                  getSourceContentRect(layerById.get(layerId)!, documentSnapshot.canvas.document).height *
+                  4;
+          const additionalBytes = Math.max(0, actualBytes - estimatedBytes);
+          if (additionalBytes > 0) {
+            rasterController.memory.setBaseBytes(layerCache.byteSize());
+            rasterController.memory.setDerivedBytes(derivedSurfaceCache.byteSize());
+            const additional = rasterController.memory.reserve(additionalBytes, {
+              generation: captureLifecycleGeneration,
+              purpose: 'background-snapshot',
+            });
+            if (additional.status === 'over-budget') {
+              return { status: 'over-budget' };
+            }
+            reservationLeases.push(additional.lease);
+          }
+          const detached = backend.createSurface(live.surface.width, live.surface.height);
+          detached.ctx.setTransform(1, 0, 0, 1, 0, 0);
+          detached.ctx.clearRect(0, 0, detached.width, detached.height);
+          detached.ctx.drawImage(live.surface.canvas, 0, 0);
+          layerSurfaces.set(layerId, { rect: { ...live.rect }, surface: detached });
+          actualDetachedBytes += actualBytes;
+        } finally {
+          live.release();
+        }
+      }
+      if (
+        !isDocumentSnapshotCurrent(documentSnapshot) ||
+        capturedGuards.some((guard) => !isLayerExportGuardCurrent(guard))
+      ) {
+        return { status: 'stale' };
+      }
+
+      for (const lease of reservationLeases) {
+        lease.release();
+      }
+      const detachedLease = rasterController.memory.trackDetached(actualDetachedBytes, captureLifecycleGeneration);
+      let released = false;
+      const snapshot: CanvasRasterSnapshot = {
+        ...documentSnapshot,
+        emptyLayerIds,
+        layerSurfaces,
+        release: () => {
+          if (released) {
+            return;
+          }
+          released = true;
+          emptyLayerIds.clear();
+          layerSurfaces.clear();
+          detachedLease.release();
+          activeRasterSnapshots.delete(snapshot);
+        },
+      };
+      activeRasterSnapshots.add(snapshot);
+      return { snapshot, status: 'ok' };
+    } finally {
+      for (const lease of reservationLeases) {
+        lease.release();
+      }
+      for (const lease of pinLeases) {
+        lease.release();
+      }
+    }
+  };
+  const exportCapability: CanvasEngineExportCapability = {
+    captureLayerExportGuard: captureCurrentLayerExportGuard,
+    captureRasterSnapshot,
+    exportBakedLayerBlob,
+    exportBakedLayerPixels,
+    exportLayerPixels: rasterizeLayerPixels,
+    exportRasterComposite,
+    exportRasterLayersToPsd,
+    extractMaskedArea,
+    getCompositeExecutorDeps,
+    hasExportableLayerContent,
+    isLayerExportGuardCurrent,
+  };
+  captureDocumentSnapshot = (): CanvasDocumentSnapshot | null => {
+    const canvas = mutationPort.getCanvasState();
+    if (disposed || !canvas) {
+      return null;
+    }
+    const snapshot: CanvasDocumentSnapshot = {
+      canvas: structuredClone(canvas),
+      documentGeneration: rasterController.getDocumentGeneration(),
+    };
+    documentSnapshotSources.set(snapshot, {
+      canvas,
+      contentEpoch: rasterContentEpoch,
+      lifecycleGeneration,
+    });
+    return snapshot;
+  };
+  const documentCapability: CanvasDocumentCapability = {
+    captureSnapshot: captureDocumentSnapshot,
+    getDocument: () => mirror.getDocument(),
+  };
+  const selectionCapability: CanvasEngineSelectionCapability = {
+    deselect,
+    eraseSelection,
+    fillSelection,
+    getSelectionBounds: () => selection.bounds(),
+    getSelectionMaskRect: () => selection.mask()?.rect ?? null,
+    invertSelection,
+    replaceSelectionFromImage,
+    selectAll,
+  };
+  const toolsCapability: CanvasEngineToolCapability = {
+    ...interactionController.tools,
+    contextMenuLayerIdAt,
+    handleEscapePriority,
+    onStrokeCommitted,
+    setInteractionLocked,
+  };
+  const layersCapability: CanvasEngineLayerCapability = {
+    ...layerController.layers,
+    applyTransform,
+    booleanMergeRasterLayers,
+    cancelTextEdit,
+    cancelTransform,
+    clearMask,
+    commitLayerConversion,
+    commitLayerCopy,
+    commitMaskImageResult,
+    commitOpenTextSession,
+    commitRasterFilterResult,
+    commitStagedImage,
+    commitTextEdit,
+    copyLayerToRaster,
+    cropLayerToBbox,
+    mergeLayerDown,
+    mergeVisibleRasterLayers,
+    nudgeSelectedLayer,
+    openTextCreate,
+    openTextEdit,
+    rasterizeLayer,
+    setTextEditContentReader,
+    updateTextEditStyle,
+    updateTransformSession,
+  };
+  const previewCapability: CanvasEnginePreviewCapability = {
+    ...layerController.previews,
+    setGuardedFilterPreview,
+    setStagedPreview,
+  };
+  const diagnosticsCapability: CanvasDiagnosticsCapability = {
+    clearCaches,
+    getDiagnostics: diagnostics.snapshot,
+    logDebugInfo,
+  };
+
+  const prepareSelectObjectStart = (layerId: string): SelectObjectStartContext => {
+    const document = mirror.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer) {
+      return { status: 'missing' };
+    }
+    if (layer.type !== 'raster' && layer.type !== 'control') {
+      return { status: 'unsupported' };
+    }
+    if (!layer.isEnabled) {
+      return { status: 'disabled' };
+    }
+    if (layer.isLocked) {
+      return { status: 'locked' };
+    }
+    const guard = captureCurrentLayerExportGuard(layer.id);
+    const entry = layerCache.get(layer.id);
+    if (!guard || !entry) {
+      return { status: 'not-ready' };
+    }
+    const sourceRect = roundOut(
+      transformBounds(
+        fromTRS(
+          { x: layer.transform.x, y: layer.transform.y },
+          layer.transform.rotation,
+          layer.transform.scaleX,
+          layer.transform.scaleY
+        ),
+        entry.rect
+      )
+    );
+    if (isEmpty(sourceRect)) {
+      return { status: 'not-ready' };
+    }
+    return { guard, layerId, layerName: layer.name, layerType: layer.type, sourceRect, status: 'ready' };
+  };
+
+  const applicationHost: CanvasApplicationHost = {
+    captureGuard: captureCurrentLayerExportGuard,
+    clearFilterPreview,
+    clearSamPreview,
+    commitFilter: (options) => commitRasterFilterResult(options, documentEditOwner),
+    commitGenerated: (options) => commitGeneratedImageResult(options, documentEditOwner),
+    commitMask: (options) => commitMaskImageResult(options, documentEditOwner),
+    decodeSelectObjectPreview,
+    encodeSurface: (surface) => backend.encodeSurface(surface, 'image/png'),
+    exportBakedLayerBlob: (layerId) => exportBakedLayerBlob(layerId, { includeDisabled: true }),
+    exportLayerPixels: rasterizeLayerPixelsForStructural,
+    getCompositeExecutorDeps,
+    getDocument: () => mirror.getDocument(),
+    isGuardCurrent: isLayerExportGuardCurrent,
+    isInteractionLocked: () => interactionLocked,
+    isSamToolActive: () => interactionController.getActiveToolId() === 'sam',
+    prepareSelectObjectStart,
+    publishFilterPreview: (layerId, imageName, rect, guard, filterType) =>
+      setGuardedFilterPreview(layerId, { filterType, imageName, rect }, guard),
+    publishSamPreview: (preview) => {
+      const isolationChanged = renderController.previews.getSam()?.isolated !== preview.isolated;
+      renderController.previews.setSam(preview);
+      scheduler.invalidate(preview.isolated || isolationChanged ? { all: true } : { overlay: true });
+      return undefined;
+    },
+    replaceSelection: (guard, image, rect, signal) =>
+      replaceSelectionFromImage(guard, image, rect, signal, documentEditOwner),
+    replaceTemporaryRestoreTool: () => pipeline.replaceTemporaryRestoreTool('sam', 'view'),
+    selectLayer: (layerId) => {
+      if (mirror.getDocument()?.selectedLayerId !== layerId) {
+        mutationPort.dispatch({ id: layerId, type: 'setCanvasSelectedLayer' });
+      }
+    },
+    setSamInputHandler: (handler) => {
+      samInputHandler = handler;
+    },
+    setEscapeHandler: (handler) => {
+      applicationEscapeHandler = handler;
+    },
+    setSamInteraction: (state) => {
+      stores.samInteraction.set(state);
+      scheduler.invalidate({ overlay: true });
+    },
+    setSamTool: () => setTool('sam'),
+    setViewTool: () => setTool('view'),
+    subscribeToolChanges: (listener) => {
+      toolChangeListeners.add(listener);
+      return () => toolChangeListeners.delete(listener);
+    },
+  };
+
+  const engine: CanvasEngine = {
+    diagnostics: diagnosticsCapability,
+    document: documentCapability,
+    edits: editingController.edits,
+    exports: exportCapability,
+    history: historyCapability,
+    lifecycle,
+    layers: layersCapability,
+    projectId,
+    previews: previewCapability,
+    selection: selectionCapability,
+    stores,
+    surface,
+    tools: toolsCapability,
+    viewport: viewportCapability,
+  };
+  return { applicationHost, engine };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/engineStores.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/engineStores.ts
new file mode 100644
index 00000000000..ec0830f9ca4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/engineStores.ts
@@ -0,0 +1,646 @@
+/**
+ * Per-engine transient external stores.
+ *
+ * These are the narrow, imperative channels React subscribes to (in the widget
+ * task) to observe engine-owned interaction state — active tool, zoom,
+ * readiness, cursor, and per-layer thumbnail versions — without the engine ever
+ * importing React. They follow the `externalStore.ts` pattern (a listener
+ * channel plus a snapshot getter, `useSyncExternalStore`-compatible) but
+ * deliberately do NOT import it: `externalStore.ts` pulls in React, and this
+ * module must stay node-safe and React-free. The React hooks live with the
+ * widget shell.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { SamInteractionState } from '@workbench/canvas-engine/samInteraction';
+import type { LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+import type { Rect, SelectionOp, ToolId, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import { type CheckerColors, DEFAULT_CHECKER_COLORS } from '@workbench/canvas-engine/render/compositor';
+
+export type { CheckerColors };
+
+/** A `text` layer source (content + style params). */
+export type TextSource = Extract<CanvasLayerSourceContract, { type: 'text' }>;
+
+/** Brush tool options (document-space size, style, and pressure behavior). */
+export interface BrushOptions {
+  /** Base stroke diameter in document units. */
+  size: number;
+  /** Fill color (any CSS color string). */
+  color: string;
+  /** Per-stroke opacity in [0, 1]. */
+  opacity: number;
+  /** Whether pen pressure modulates the stroke width. */
+  pressureSensitivity: boolean;
+}
+
+/** Eraser tool options. */
+export interface EraserOptions {
+  /** Base eraser diameter in document units. */
+  size: number;
+  /** Per-stroke erase strength in [0, 1]. */
+  opacity: number;
+}
+
+/** Lasso (selection) tool options: the boolean op applied when a path commits. */
+export interface LassoToolOptions {
+  /** The op a committed lasso path applies to the selection, when no modifier overrides it. */
+  mode: SelectionOp;
+}
+
+/** Default lasso options: a fresh path replaces the selection. */
+export const DEFAULT_LASSO_OPTIONS: LassoToolOptions = {
+  mode: 'replace',
+};
+
+/** A single gradient stop (offset in [0,1], any CSS color). */
+export interface GradientStop {
+  offset: number;
+  color: string;
+}
+
+/**
+ * Shape tool options: the kind drawn on the next drag, and the fill/stroke
+ * style applied to it (and, when a shape layer is selected, edited live on it).
+ * `fill`/`stroke` are `null` for "none".
+ */
+export interface ShapeToolOptions {
+  kind: 'rect' | 'ellipse';
+  fill: string | null;
+  stroke: string | null;
+  strokeWidth: number;
+}
+
+/** Sensible starting shape options: a filled black rect, no stroke. */
+export const DEFAULT_SHAPE_OPTIONS: ShapeToolOptions = {
+  fill: '#000000',
+  kind: 'rect',
+  stroke: null,
+  strokeWidth: 8,
+};
+
+/** Largest shape stroke width (document px) the options bar clamps to. */
+export const MAX_SHAPE_STROKE_WIDTH = 2000;
+
+/**
+ * Gradient tool options: the kind, the linear angle (degrees), and the stops.
+ * The minimal two-stop editor edits `stops[0]` (start) and the last stop (end);
+ * a full multi-stop editor is a follow-up.
+ */
+export interface GradientToolOptions {
+  kind: 'linear' | 'radial';
+  angle: number;
+  stops: GradientStop[];
+}
+
+/** Sensible starting gradient options: black→transparent, horizontal linear. */
+export const DEFAULT_GRADIENT_OPTIONS: GradientToolOptions = {
+  angle: 0,
+  kind: 'linear',
+  stops: [
+    { color: '#000000ff', offset: 0 },
+    { color: '#00000000', offset: 1 },
+  ],
+};
+
+/** The text style the text tool applies to a newly created layer (and edits live). */
+export interface TextToolOptions {
+  fontFamily: string;
+  fontSize: number;
+  /** CSS numeric weight (400/500/600/700). */
+  fontWeight: number;
+  /** Unitless line-height multiplier over `fontSize`. */
+  lineHeight: number;
+  align: 'left' | 'center' | 'right';
+  color: string;
+}
+
+/**
+ * A small curated font list offered by the text options bar. Values are CSS
+ * `font-family` stacks so each falls back gracefully; keep it short this phase
+ * (a full system-font enumeration is a follow-up).
+ */
+export const TEXT_FONT_FAMILIES: readonly { label: string; value: string }[] = [
+  { label: 'Inter', value: "'Inter Variable', Inter, sans-serif" },
+  { label: 'Sans-serif', value: 'system-ui, sans-serif' },
+  { label: 'Serif', value: "Georgia, 'Times New Roman', serif" },
+  { label: 'Monospace', value: "'JetBrains Mono', ui-monospace, monospace" },
+];
+
+/** Weights the text options bar offers. */
+export const TEXT_FONT_WEIGHTS: readonly number[] = [400, 500, 600, 700];
+
+/** Smallest / largest font size (document px) the text options bar clamps to. */
+export const MIN_TEXT_FONT_SIZE = 1;
+export const MAX_TEXT_FONT_SIZE = 2000;
+
+/** Sensible starting text options: black left-aligned Inter at 48px. */
+export const DEFAULT_TEXT_OPTIONS: TextToolOptions = {
+  align: 'left',
+  color: '#000000',
+  fontFamily: TEXT_FONT_FAMILIES[0]!.value,
+  fontSize: 48,
+  fontWeight: 400,
+  lineHeight: 1.2,
+};
+
+/** Bbox (generation-frame) tool options: the aspect-ratio lock. */
+export interface BboxToolOptions {
+  /** Whether corner/edge resize preserves {@link BboxToolOptions.aspectRatio}. */
+  aspectLocked: boolean;
+  /** The locked width / height ratio. */
+  aspectRatio: number;
+}
+
+/** Default grid size (document px) the bbox snaps to before a model feeds a real one. */
+export const DEFAULT_BBOX_GRID = 8;
+
+/** Default bbox tool options: aspect unlocked, square ratio. */
+export const DEFAULT_BBOX_OPTIONS: BboxToolOptions = {
+  aspectLocked: false,
+  aspectRatio: 1,
+};
+
+/** Smallest and largest brush/eraser diameters (document units) the size step clamps to. */
+export const MIN_BRUSH_SIZE = 1;
+export const MAX_BRUSH_SIZE = 2000;
+
+/** Sensible starting brush options. */
+export const DEFAULT_BRUSH_OPTIONS: BrushOptions = {
+  color: '#000000',
+  opacity: 1,
+  pressureSensitivity: true,
+  size: 50,
+};
+
+/** Sensible starting eraser options. */
+export const DEFAULT_ERASER_OPTIONS: EraserOptions = {
+  opacity: 1,
+  size: 50,
+};
+
+/**
+ * An active transform-tool session on one layer. Outlives individual pointer
+ * gestures (drag handles, adjust numerics) until Apply or Cancel. `startTransform`
+ * is the committed transform captured at session start (restored on Cancel /
+ * used as the undo inverse); `transform` is the live, edited transform the
+ * compositor previews and the options bar renders as numerics.
+ */
+export interface TransformSession {
+  layerId: string;
+  startTransform: LayerTransform;
+  transform: LayerTransform;
+}
+
+/**
+ * An active text-editing session. Set by the text tool; while it is active the
+ * contenteditable portal (in `widgets/canvas`) shows the live text and the
+ * compositor SKIPS the session's layer (edit mode) so the two don't double-draw.
+ *
+ * Two modes:
+ * - **create**: no layer exists yet (`layerId === null`, `startSource === null`).
+ *   Commit dispatches ONE `addCanvasLayer` with the final content; cancel adds
+ *   nothing. This keeps a new text layer to a single, cleanly-undoable commit.
+ * - **edit**: an existing text layer is being re-edited. `startSource` is its
+ *   committed source (the exact undo inverse / no-change baseline); `source` is
+ *   the live, style-edited source. Commit dispatches ONE `updateCanvasLayerSource`.
+ *
+ * `source` carries the live style (font/size/weight/lineHeight/align/color) the
+ * portal renders WYSIWYG and the options bar edits; `content` on it is only the
+ * seed — the live typed content lives in the contenteditable DOM until commit.
+ * `transform` positions/scales the portal (document→screen via the view matrix).
+ * `id` increments per session so React can key (remount) the editable per open.
+ */
+export interface TextEditSession {
+  id: number;
+  mode: 'create' | 'edit';
+  layerId: string | null;
+  startSource: TextSource | null;
+  source: TextSource;
+  transform: LayerTransform;
+}
+
+/** A single-value store, `useSyncExternalStore`-compatible. */
+export interface ScalarStore<T> {
+  get(): T;
+  set(next: T): void;
+  subscribe(listener: () => void): () => void;
+}
+
+const createScalarStore = <T>(initial: T, isEqual: (a: T, b: T) => boolean = Object.is): ScalarStore<T> => {
+  let value = initial;
+  const listeners = new Set<() => void>();
+
+  return {
+    get: () => value,
+    set: (next) => {
+      if (isEqual(value, next)) {
+        return;
+      }
+      value = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+};
+
+/**
+ * A keyed numeric store with per-key subscription granularity, so a React
+ * component watching one layer's thumbnail version only re-renders when that
+ * layer changes. A global `subscribe` is also exposed for coarse observers.
+ */
+export interface KeyedVersionStore {
+  get(key: string): number | undefined;
+  set(key: string, value: number): void;
+  delete(key: string): void;
+  /** Subscribes to changes for a single key. */
+  subscribeKey(key: string, listener: () => void): () => void;
+  /** Subscribes to any change across all keys. */
+  subscribe(listener: () => void): () => void;
+}
+
+export type LayerThumbnailStatus = 'loading' | 'ready' | 'error';
+
+/** A per-layer thumbnail request state; absence represents `idle`. */
+export interface KeyedThumbnailStatusStore {
+  get(key: string): LayerThumbnailStatus | undefined;
+  set(key: string, value: LayerThumbnailStatus): void;
+  delete(key: string): void;
+  clear(): void;
+  subscribeKey(key: string, listener: () => void): () => void;
+}
+
+const createKeyedVersionStore = (): KeyedVersionStore => {
+  const values = new Map<string, number>();
+  const keyedListeners = new Map<string, Set<() => void>>();
+  const globalListeners = new Set<() => void>();
+
+  const notify = (key: string): void => {
+    for (const listener of keyedListeners.get(key) ?? []) {
+      listener();
+    }
+    for (const listener of globalListeners) {
+      listener();
+    }
+  };
+
+  return {
+    delete: (key) => {
+      if (values.delete(key)) {
+        notify(key);
+      }
+    },
+    get: (key) => values.get(key),
+    set: (key, value) => {
+      if (values.get(key) === value) {
+        return;
+      }
+      values.set(key, value);
+      notify(key);
+    },
+    subscribe: (listener) => {
+      globalListeners.add(listener);
+      return () => {
+        globalListeners.delete(listener);
+      };
+    },
+    subscribeKey: (key, listener) => {
+      const listeners = keyedListeners.get(key) ?? new Set<() => void>();
+      listeners.add(listener);
+      keyedListeners.set(key, listeners);
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          keyedListeners.delete(key);
+        }
+      };
+    },
+  };
+};
+
+const createKeyedThumbnailStatusStore = (): KeyedThumbnailStatusStore => {
+  const values = new Map<string, LayerThumbnailStatus>();
+  const keyedListeners = new Map<string, Set<() => void>>();
+  const notify = (key: string): void => {
+    for (const listener of keyedListeners.get(key) ?? []) {
+      listener();
+    }
+  };
+
+  return {
+    clear: () => {
+      const keys = [...values.keys()];
+      values.clear();
+      for (const key of keys) {
+        notify(key);
+      }
+    },
+    delete: (key) => {
+      if (values.delete(key)) {
+        notify(key);
+      }
+    },
+    get: (key) => values.get(key),
+    set: (key, value) => {
+      if (values.get(key) === value) {
+        return;
+      }
+      values.set(key, value);
+      notify(key);
+    },
+    subscribeKey: (key, listener) => {
+      const listeners = keyedListeners.get(key) ?? new Set<() => void>();
+      listeners.add(listener);
+      keyedListeners.set(key, listeners);
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          keyedListeners.delete(key);
+        }
+      };
+    },
+  };
+};
+
+/** The bundle of transient stores owned by one engine instance. */
+export interface EngineStores {
+  activeTool: ScalarStore<ToolId>;
+  zoom: ScalarStore<number>;
+  viewportReady: ScalarStore<boolean>;
+  cursor: ScalarStore<string>;
+  thumbnailVersion: KeyedVersionStore;
+  thumbnailStatus: KeyedThumbnailStatusStore;
+  /** Brush tool options (size / color / opacity / pressure). */
+  brushOptions: ScalarStore<BrushOptions>;
+  /** Eraser tool options (size / opacity). */
+  eraserOptions: ScalarStore<EraserOptions>;
+  /** Whether the engine-owned canvas history has an entry to undo. */
+  canUndo: ScalarStore<boolean>;
+  /** Whether the engine-owned canvas history has an entry to redo. */
+  canRedo: ScalarStore<boolean>;
+  /** Bbox tool options (aspect lock / ratio). */
+  bboxOptions: ScalarStore<BboxToolOptions>;
+  /** Lasso tool options (the committed boolean op mode). */
+  lassoOptions: ScalarStore<LassoToolOptions>;
+  /** Shape tool options (kind / fill / stroke / stroke width). */
+  shapeOptions: ScalarStore<ShapeToolOptions>;
+  /** Gradient tool options (kind / angle / stops). */
+  gradientOptions: ScalarStore<GradientToolOptions>;
+  /** Text tool options (font family / size / weight / line-height / align / color). */
+  textOptions: ScalarStore<TextToolOptions>;
+  /**
+   * The active text-editing session, or `null`. React reads it to render the
+   * contenteditable portal and enable the text options bar's live-restyle path;
+   * the engine reads it to skip the session layer in the composite. Cleared on
+   * commit, cancel, real tool switch, layer delete, or document replace.
+   */
+  textEditSession: ScalarStore<TextEditSession | null>;
+  /**
+   * The live shape-tool drag preview (document-space rect + kind), or `null`
+   * when idle. The overlay renders the shape outline in place of a committed
+   * layer so the drag tracks without dispatching; cleared on commit/cancel.
+   */
+  shapePreview: ScalarStore<{ rect: Rect; kind: 'rect' | 'ellipse' } | null>;
+  /**
+   * The live gradient-tool drag preview: the drag vector's start/end points in
+   * document space, drawn on the overlay as a direction indicator (a gradient
+   * necessarily fills the document, so only its ANGLE is previewed, not a
+   * bounding box). `null` when idle; cleared on commit/cancel.
+   */
+  gradientPreview: ScalarStore<{ start: Vec2; end: Vec2 } | null>;
+  /**
+   * Whether a pixel selection currently exists. React reads it to enable the
+   * fill/erase/invert/deselect controls and the engine gates selection hotkeys
+   * and marching-ants animation off it. The engine writes it as the selection
+   * mask gains/loses content.
+   */
+  hasSelection: ScalarStore<boolean>;
+  /** Core-only visual SAM interaction state; application session status remains outside the engine. */
+  samInteraction: ScalarStore<SamInteractionState | null>;
+  /**
+   * The in-progress lasso polygon (document-space points) during a lasso drag,
+   * or `null` when idle. The overlay renders it as a live dashed preview in
+   * place of a committed selection; cleared on commit/cancel. Like `bboxPreview`,
+   * it is a transient channel — no dispatch, no React subscriber.
+   */
+  lassoPreview: ScalarStore<readonly Vec2[] | null>;
+  /** Model-dependent grid size (document px) the bbox snaps to. React feeds this from generate settings. */
+  bboxGrid: ScalarStore<number>;
+  /**
+   * The live bbox preview rect during a bbox-tool gesture (document space), or
+   * `null` when idle. The overlay renders this in place of the committed bbox so
+   * the frame tracks the drag without dispatching; cleared on commit/cancel.
+   */
+  bboxPreview: ScalarStore<Rect | null>;
+  /**
+   * The active transform-tool session (layer id + start/live transform), or
+   * `null` when no session is open. React reads it to render the numeric options
+   * and enable Apply/Cancel; the engine drives the live preview from it. Cleared
+   * on Apply, Cancel, tool switch, or document replace.
+   */
+  transformSession: ScalarStore<TransformSession | null>;
+  /**
+   * Whether the transparency checkerboard is drawn behind transparent documents
+   * (default ON). Off shows the widget surface through the document instead. The
+   * compositor reads this each frame; the canvas settings menu toggles it.
+   */
+  checkerboard: ScalarStore<boolean>;
+  /**
+   * The two square colors of the transparency checkerboard, resolved from Chakra
+   * semantic tokens in React and fed down (see `widgets/canvas/checkerColors.ts`).
+   * The engine rebuilds its cached checker tile and recomposites when these
+   * change (e.g. a theme/color-mode switch); {@link DEFAULT_CHECKER_COLORS} is the
+   * React-free fallback until the first feed.
+   */
+  checkerColors: ScalarStore<CheckerColors>;
+  /**
+   * Whether the document-space grid (at the bbox snap size) is drawn on the
+   * overlay (default OFF). The overlay reads this each frame; the canvas settings
+   * menu toggles it.
+   */
+  showGrid: ScalarStore<boolean>;
+  /**
+   * Whether ctrl+wheel brush/eraser sizing is inverted (default OFF): normally
+   * wheel-up grows the size. The wheel handler reads this; the canvas settings
+   * menu toggles it. Purely an input preference — no render effect.
+   */
+  invertBrushSizeScroll: ScalarStore<boolean>;
+  /**
+   * Whether the generation bbox (dashed frame) is drawn as passive overlay chrome
+   * (default ON). The overlay reads this each frame; the canvas settings popover
+   * toggles it. The bbox is still drawn (with its handles) while the bbox TOOL is
+   * active regardless, so it stays editable — this only hides the passive frame.
+   */
+  showBbox: ScalarStore<boolean>;
+  /**
+   * Whether the bbox overlay shade is drawn (default OFF): a translucent dark
+   * fill over everything OUTSIDE the bbox, focusing attention on the generation
+   * region (legacy `CanvasBboxToolModule` overlayRect parity). Overlay-only —
+   * toggling never recomposites the document.
+   */
+  bboxOverlay: ScalarStore<boolean>;
+  /**
+   * Whether the rule-of-thirds composition guide (two vertical + two horizontal
+   * lines dividing the bbox into thirds) is drawn inside the bbox (default OFF).
+   * The overlay reads this each frame; the canvas settings popover toggles it.
+   */
+  ruleOfThirds: ScalarStore<boolean>;
+  /**
+   * Whether bbox-tool moves/resizes snap to the model grid (default ON). The bbox
+   * tool reads this; the canvas settings popover toggles it, and the fit-bbox
+   * header actions honor it too. Holding Alt bypasses snapping independently.
+   * Purely an interaction preference — no render effect.
+   */
+  snapToGrid: ScalarStore<boolean>;
+  /** Whether an engine-owned operation currently excludes ordinary document edits. */
+  documentEditingLocked: ScalarStore<boolean>;
+}
+
+const brushOptionsEqual = (a: BrushOptions, b: BrushOptions): boolean =>
+  a.size === b.size &&
+  a.color === b.color &&
+  a.opacity === b.opacity &&
+  a.pressureSensitivity === b.pressureSensitivity;
+
+const eraserOptionsEqual = (a: EraserOptions, b: EraserOptions): boolean =>
+  a.size === b.size && a.opacity === b.opacity;
+
+const checkerColorsEqual = (a: CheckerColors, b: CheckerColors): boolean => a.a === b.a && a.b === b.b;
+
+const bboxOptionsEqual = (a: BboxToolOptions, b: BboxToolOptions): boolean =>
+  a.aspectLocked === b.aspectLocked && a.aspectRatio === b.aspectRatio;
+
+const lassoOptionsEqual = (a: LassoToolOptions, b: LassoToolOptions): boolean => a.mode === b.mode;
+
+const shapeOptionsEqual = (a: ShapeToolOptions, b: ShapeToolOptions): boolean =>
+  a.kind === b.kind && a.fill === b.fill && a.stroke === b.stroke && a.strokeWidth === b.strokeWidth;
+
+const stopsEqual = (a: readonly GradientStop[], b: readonly GradientStop[]): boolean =>
+  a.length === b.length && a.every((stop, i) => stop.offset === b[i]?.offset && stop.color === b[i]?.color);
+
+const gradientOptionsEqual = (a: GradientToolOptions, b: GradientToolOptions): boolean =>
+  a.kind === b.kind && a.angle === b.angle && stopsEqual(a.stops, b.stops);
+
+const shapePreviewEqual = (
+  a: { rect: Rect; kind: 'rect' | 'ellipse' } | null,
+  b: { rect: Rect; kind: 'rect' | 'ellipse' } | null
+): boolean => {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return (
+    a.kind === b.kind &&
+    a.rect.x === b.rect.x &&
+    a.rect.y === b.rect.y &&
+    a.rect.width === b.rect.width &&
+    a.rect.height === b.rect.height
+  );
+};
+
+const gradientPreviewEqual = (a: { start: Vec2; end: Vec2 } | null, b: { start: Vec2; end: Vec2 } | null): boolean => {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return a.start.x === b.start.x && a.start.y === b.start.y && a.end.x === b.end.x && a.end.y === b.end.y;
+};
+
+const bboxPreviewEqual = (a: Rect | null, b: Rect | null): boolean => {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+};
+
+const transformEqual = (a: LayerTransform, b: LayerTransform): boolean =>
+  a.x === b.x && a.y === b.y && a.scaleX === b.scaleX && a.scaleY === b.scaleY && a.rotation === b.rotation;
+
+const transformSessionEqual = (a: TransformSession | null, b: TransformSession | null): boolean => {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return (
+    a.layerId === b.layerId &&
+    transformEqual(a.startTransform, b.startTransform) &&
+    transformEqual(a.transform, b.transform)
+  );
+};
+
+const textOptionsEqual = (a: TextToolOptions, b: TextToolOptions): boolean =>
+  a.fontFamily === b.fontFamily &&
+  a.fontSize === b.fontSize &&
+  a.fontWeight === b.fontWeight &&
+  a.lineHeight === b.lineHeight &&
+  a.align === b.align &&
+  a.color === b.color;
+
+const textSourceEqual = (a: TextSource, b: TextSource): boolean =>
+  a.content === b.content &&
+  a.fontFamily === b.fontFamily &&
+  a.fontSize === b.fontSize &&
+  a.fontWeight === b.fontWeight &&
+  a.lineHeight === b.lineHeight &&
+  a.align === b.align &&
+  a.color === b.color;
+
+const textEditSessionEqual = (a: TextEditSession | null, b: TextEditSession | null): boolean => {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return (
+    a.id === b.id &&
+    a.mode === b.mode &&
+    a.layerId === b.layerId &&
+    textSourceEqual(a.source, b.source) &&
+    transformEqual(a.transform, b.transform)
+  );
+};
+
+/** Creates a fresh bundle of engine stores with their initial values. */
+export const createEngineStores = (initialTool: ToolId = 'view'): EngineStores => ({
+  activeTool: createScalarStore<ToolId>(initialTool),
+  bboxGrid: createScalarStore<number>(DEFAULT_BBOX_GRID),
+  bboxOptions: createScalarStore<BboxToolOptions>({ ...DEFAULT_BBOX_OPTIONS }, bboxOptionsEqual),
+  bboxPreview: createScalarStore<Rect | null>(null, bboxPreviewEqual),
+  bboxOverlay: createScalarStore<boolean>(false),
+  brushOptions: createScalarStore<BrushOptions>({ ...DEFAULT_BRUSH_OPTIONS }, brushOptionsEqual),
+  canRedo: createScalarStore<boolean>(false),
+  canUndo: createScalarStore<boolean>(false),
+  checkerboard: createScalarStore<boolean>(true),
+  checkerColors: createScalarStore<CheckerColors>({ ...DEFAULT_CHECKER_COLORS }, checkerColorsEqual),
+  cursor: createScalarStore<string>('default'),
+  eraserOptions: createScalarStore<EraserOptions>({ ...DEFAULT_ERASER_OPTIONS }, eraserOptionsEqual),
+  documentEditingLocked: createScalarStore<boolean>(false),
+  hasSelection: createScalarStore<boolean>(false),
+  invertBrushSizeScroll: createScalarStore<boolean>(false),
+  gradientOptions: createScalarStore<GradientToolOptions>(
+    { ...DEFAULT_GRADIENT_OPTIONS, stops: DEFAULT_GRADIENT_OPTIONS.stops.map((s) => ({ ...s })) },
+    gradientOptionsEqual
+  ),
+  gradientPreview: createScalarStore<{ start: Vec2; end: Vec2 } | null>(null, gradientPreviewEqual),
+  lassoOptions: createScalarStore<LassoToolOptions>({ ...DEFAULT_LASSO_OPTIONS }, lassoOptionsEqual),
+  lassoPreview: createScalarStore<readonly Vec2[] | null>(null),
+  ruleOfThirds: createScalarStore<boolean>(false),
+  samInteraction: createScalarStore(null),
+  shapeOptions: createScalarStore<ShapeToolOptions>({ ...DEFAULT_SHAPE_OPTIONS }, shapeOptionsEqual),
+  shapePreview: createScalarStore<{ rect: Rect; kind: 'rect' | 'ellipse' } | null>(null, shapePreviewEqual),
+  showBbox: createScalarStore<boolean>(true),
+  showGrid: createScalarStore<boolean>(false),
+  snapToGrid: createScalarStore<boolean>(true),
+  textEditSession: createScalarStore<TextEditSession | null>(null, textEditSessionEqual),
+  textOptions: createScalarStore<TextToolOptions>({ ...DEFAULT_TEXT_OPTIONS }, textOptionsEqual),
+  thumbnailVersion: createKeyedVersionStore(),
+  thumbnailStatus: createKeyedThumbnailStatusStore(),
+  transformSession: createScalarStore<TransformSession | null>(null, transformSessionEqual),
+  viewportReady: createScalarStore<boolean>(false),
+  zoom: createScalarStore<number>(1),
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/export/psdExport.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/export/psdExport.test.ts
new file mode 100644
index 00000000000..5881ed568c9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/export/psdExport.test.ts
@@ -0,0 +1,165 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasBlendMode } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import type { PsdExportLayerInput } from './psdExport';
+
+import { blendModeToPsd, planPsdExport, PSD_MAX_DIMENSION } from './psdExport';
+
+const IDENTITY = { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+
+const layer = (over: Partial<PsdExportLayerInput> = {}): PsdExportLayerInput => ({
+  blendMode: 'normal',
+  contentRect: { height: 50, width: 100, x: 0, y: 0 },
+  id: 'a',
+  isEnabled: true,
+  name: 'Layer',
+  opacity: 1,
+  transform: { ...IDENTITY },
+  ...over,
+});
+
+const findLayer = (plan: ReturnType<typeof planPsdExport>, id: string) => {
+  if (plan.status !== 'ok') {
+    throw new Error(`expected ok plan, got ${plan.status}`);
+  }
+  const found = plan.layers.find((l) => l.id === id);
+  if (!found) {
+    throw new Error(`layer ${id} not in plan`);
+  }
+  return found;
+};
+
+describe('blendModeToPsd', () => {
+  it('maps every canvas blend mode to a PSD blend key', () => {
+    const cases: [CanvasBlendMode, string][] = [
+      ['normal', 'normal'],
+      ['multiply', 'multiply'],
+      ['screen', 'screen'],
+      ['overlay', 'overlay'],
+      ['darken', 'darken'],
+      ['lighten', 'lighten'],
+      ['color-dodge', 'color dodge'],
+      ['color-burn', 'color burn'],
+      ['hard-light', 'hard light'],
+      ['soft-light', 'soft light'],
+      ['difference', 'difference'],
+      ['exclusion', 'exclusion'],
+      ['hue', 'hue'],
+      ['saturation', 'saturation'],
+      ['color', 'color'],
+      ['luminosity', 'luminosity'],
+    ];
+    for (const [mode, key] of cases) {
+      expect(blendModeToPsd(mode)).toBe(key);
+    }
+  });
+
+  it('falls back to normal for an unknown blend mode', () => {
+    expect(blendModeToPsd('made-up' as CanvasBlendMode)).toBe('normal');
+  });
+});
+
+describe('planPsdExport', () => {
+  it('returns empty when there are no layers', () => {
+    expect(planPsdExport([])).toEqual({ status: 'empty' });
+  });
+
+  it('returns empty when every layer has empty content', () => {
+    expect(planPsdExport([layer({ contentRect: { height: 0, width: 0, x: 0, y: 0 } })])).toEqual({
+      status: 'empty',
+    });
+  });
+
+  it('sizes the PSD canvas to a single layer content bounds', () => {
+    const plan = planPsdExport([layer()]);
+    expect(plan.status).toBe('ok');
+    if (plan.status !== 'ok') {
+      return;
+    }
+    expect(plan.width).toBe(100);
+    expect(plan.height).toBe(50);
+    expect(plan.canvasRect).toEqual<Rect>({ height: 50, width: 100, x: 0, y: 0 });
+    const only = plan.layers[0]!;
+    expect(only).toMatchObject({ bottom: 50, hidden: false, left: 0, opacity: 1, right: 100, top: 0 });
+  });
+
+  it('unions world-space bounds across layers and positions each relative to the origin', () => {
+    const plan = planPsdExport([
+      layer({ id: 'top', transform: { ...IDENTITY, x: 50, y: 20 } }),
+      layer({ id: 'bottom', transform: { ...IDENTITY, x: -30, y: -10 } }),
+    ]);
+    if (plan.status !== 'ok') {
+      throw new Error('expected ok');
+    }
+    // union of [-30,-10,100,50] and [50,20,100,50] = [-30,-10, 180, 80]
+    expect(plan.canvasRect).toEqual<Rect>({ height: 80, width: 180, x: -30, y: -10 });
+    expect(plan.width).toBe(180);
+    expect(plan.height).toBe(80);
+    // positions are relative to the union origin (-30, -10)
+    expect(findLayer(plan, 'bottom')).toMatchObject({ left: 0, top: 0, right: 100, bottom: 50 });
+    expect(findLayer(plan, 'top')).toMatchObject({ left: 80, top: 30, right: 180, bottom: 80 });
+  });
+
+  it('emits layers bottom-to-top (input is top-first, PSD children are bottom-first)', () => {
+    const plan = planPsdExport([layer({ id: 'top' }), layer({ id: 'mid' }), layer({ id: 'bottom' })]);
+    if (plan.status !== 'ok') {
+      throw new Error('expected ok');
+    }
+    expect(plan.layers.map((l) => l.id)).toEqual(['bottom', 'mid', 'top']);
+  });
+
+  it('marks disabled layers hidden but still exports them, and clamps opacity to 0..1', () => {
+    const plan = planPsdExport([
+      layer({ id: 'shown', isEnabled: true, opacity: 0.5 }),
+      layer({ id: 'over', isEnabled: true, opacity: 2 }),
+      layer({ id: 'hidden', isEnabled: false, opacity: -1 }),
+    ]);
+    expect(findLayer(plan, 'shown')).toMatchObject({ hidden: false, opacity: 0.5 });
+    expect(findLayer(plan, 'over')).toMatchObject({ opacity: 1 });
+    expect(findLayer(plan, 'hidden')).toMatchObject({ hidden: true, opacity: 0 });
+  });
+
+  it('maps blend modes and reports unmapped ones (falling back to normal)', () => {
+    const plan = planPsdExport([
+      layer({ blendMode: 'multiply', id: 'a' }),
+      layer({ blendMode: 'nonsense' as CanvasBlendMode, id: 'b' }),
+    ]);
+    if (plan.status !== 'ok') {
+      throw new Error('expected ok');
+    }
+    expect(findLayer(plan, 'a').blendMode).toBe('multiply');
+    expect(findLayer(plan, 'b').blendMode).toBe('normal');
+    expect(plan.unmappedBlends).toEqual(['nonsense']);
+  });
+
+  it('passes non-destructive adjustments through for the executor to bake', () => {
+    const adjustments = { brightness: 0.2, contrast: 0, saturation: 0 };
+    const plan = planPsdExport([layer({ adjustments })]);
+    expect(findLayer(plan, 'a').adjustments).toBe(adjustments);
+  });
+
+  it('drops empty-content layers from the plan but keeps the rest', () => {
+    const plan = planPsdExport([
+      layer({ contentRect: { height: 0, width: 0, x: 0, y: 0 }, id: 'empty' }),
+      layer({ id: 'real' }),
+    ]);
+    if (plan.status !== 'ok') {
+      throw new Error('expected ok');
+    }
+    expect(plan.layers.map((l) => l.id)).toEqual(['real']);
+  });
+
+  it('refuses an export whose union bounds exceed the dimension cap', () => {
+    const plan = planPsdExport([layer({ contentRect: { height: 10, width: 100, x: 0, y: 0 } })], {
+      maxDimension: 50,
+    });
+    expect(plan).toEqual({ height: 10, status: 'too-large', width: 100 });
+  });
+
+  it('accepts bounds exactly at the cap', () => {
+    const plan = planPsdExport([layer({ contentRect: { height: 10, width: PSD_MAX_DIMENSION, x: 0, y: 0 } })]);
+    expect(plan.status).toBe('ok');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/export/psdExport.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/export/psdExport.ts
new file mode 100644
index 00000000000..94ca2a06ba0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/export/psdExport.ts
@@ -0,0 +1,413 @@
+/**
+ * Export raster layers to a Photoshop (.psd) document.
+ *
+ * Split into a PURE planner and an IMPURE executor, mirroring the
+ * planner/executor split of `compositeForGeneration.ts`:
+ *
+ * - {@link planPsdExport} is pure geometry (no DOM, no `ag-psd`, no engine): it
+ *   turns each raster layer's transform + content rect into a PSD layer entry
+ *   (position, opacity, blend, hidden, order) and the document bounds. Unit
+ *   tested in node.
+ * - {@link executePsdExport} is the side-effecting half: it bakes each layer's
+ *   pixels through the {@link RasterBackend} seam, lazily imports `ag-psd`
+ *   (`writePsd`) at call time so the library never enters the main bundle, and
+ *   triggers a browser download. Verified by types + manual QA (opening the PSD).
+ *
+ * ### Conventions
+ * - **Order.** The canvas document stores layers top-first (index 0 = top-most).
+ *   ag-psd's `children` array is BOTTOM-to-top (`children[0]` is the bottom-most
+ *   layer, written first to the PSD layer records, which the format stores
+ *   bottom-up). So the plan reverses the top-first input into bottom-to-top.
+ * - **Bounds.** The PSD canvas is the union of every EXPORTED layer's
+ *   world-space (document-space) content AABB — document/bbox-independent. An
+ *   empty union means nothing to export.
+ * - **Opacity.** ag-psd's `Layer.opacity` is 0..1 (the writer multiplies by 255
+ *   internally), NOT 0..255. Our `layer.opacity` is already 0..1, so it passes
+ *   through unchanged (clamped).
+ * - **Hidden.** Every raster layer with content is exported; hidden (disabled)
+ *   layers are written with `hidden: true` rather than dropped.
+ * - **Adjustments.** Non-destructive raster adjustments are BAKED into the
+ *   layer's pixels (PSD has no matching non-destructive representation we emit),
+ *   exactly as `compositeForGeneration` bakes them, so the PSD matches what the
+ *   user sees. Opacity/blend stay as PSD layer properties (not baked).
+ */
+
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Mat2d, Rect } from '@workbench/canvas-engine/types';
+import type { CanvasAdjustmentsContract, CanvasBlendMode } from '@workbench/types';
+import type { BlendMode, Layer as AgPsdLayer, Psd } from 'ag-psd';
+
+import { fromTRS } from '@workbench/canvas-engine/math/mat2d';
+import { isEmpty, roundOut, transformBounds, union } from '@workbench/canvas-engine/math/rect';
+import { applyAdjustments } from '@workbench/canvas-engine/render/adjustments';
+import { blendToComposite } from '@workbench/canvas-engine/render/compositor';
+
+/**
+ * Maximum PSD side length. ag-psd/Photoshop tolerate up to 300000px, but a
+ * multi-gigabyte export from an unbounded-canvas union helps nobody — refuse
+ * past a sane cap and tell the user. Legacy Photoshop's own PSD limit is 30000.
+ */
+export const PSD_MAX_DIMENSION = 30000;
+
+/** A canvas layer transform (TRS), duplicated to keep this module contract-light. */
+export interface PsdLayerTransform {
+  x: number;
+  y: number;
+  scaleX: number;
+  scaleY: number;
+  rotation: number;
+}
+
+/**
+ * Maps a document blend mode to ag-psd's blend key. Every blend mode the canvas
+ * supports has a direct PSD equivalent (Photoshop is the origin of these modes),
+ * so this is total; an unknown value falls back to 'normal' and is reported via
+ * {@link PsdExportOk.unmappedBlends}.
+ */
+const BLEND_MODE_TO_PSD: Record<CanvasBlendMode, BlendMode> = {
+  color: 'color',
+  'color-burn': 'color burn',
+  'color-dodge': 'color dodge',
+  darken: 'darken',
+  difference: 'difference',
+  exclusion: 'exclusion',
+  'hard-light': 'hard light',
+  hue: 'hue',
+  lighten: 'lighten',
+  luminosity: 'luminosity',
+  multiply: 'multiply',
+  normal: 'normal',
+  overlay: 'overlay',
+  saturation: 'saturation',
+  screen: 'screen',
+  'soft-light': 'soft light',
+};
+
+/** The ag-psd blend key for a document blend mode ('normal' for anything unmapped). */
+export const blendModeToPsd = (mode: CanvasBlendMode): BlendMode => BLEND_MODE_TO_PSD[mode] ?? 'normal';
+
+/** One raster layer's export-relevant facts, in the document's top-first order. */
+export interface PsdExportLayerInput {
+  id: string;
+  name: string;
+  transform: PsdLayerTransform;
+  /** The layer's content rect in LOCAL space (origin may be negative). */
+  contentRect: Rect;
+  /** 0..1. */
+  opacity: number;
+  blendMode: CanvasBlendMode;
+  /** Hidden (disabled) layers are exported with `hidden: true`, not dropped. */
+  isEnabled: boolean;
+  /** Non-destructive adjustments to bake into the layer's pixels, if any. */
+  adjustments?: CanvasAdjustmentsContract;
+}
+
+/** A single planned PSD layer (already in ag-psd bottom-to-top order). */
+export interface PsdPlanLayer {
+  id: string;
+  name: string;
+  /** Position within the PSD canvas (relative to the union origin). */
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  /** The layer's world-space AABB (document space) the executor bakes into. */
+  worldRect: Rect;
+  transform: PsdLayerTransform;
+  /** Layer-local content rect (executor draws the cache at its origin). */
+  contentRect: Rect;
+  /** 0..1 (ag-psd's range). */
+  opacity: number;
+  blendMode: BlendMode;
+  /** Canvas `globalCompositeOperation` for the flattened composite preview. */
+  compositeBlend: GlobalCompositeOperation;
+  hidden: boolean;
+  adjustments?: CanvasAdjustmentsContract;
+}
+
+/** A successful export plan. */
+export interface PsdExportOk {
+  status: 'ok';
+  /** PSD canvas dimensions (= union bounds). */
+  width: number;
+  height: number;
+  /** The union bounds in document space (origin is the PSD's (0,0)). */
+  canvasRect: Rect;
+  /** Layers in ag-psd order (bottom-to-top). */
+  layers: PsdPlanLayer[];
+  /** Distinct blend modes that had no PSD equivalent (fell back to 'normal'). */
+  unmappedBlends: string[];
+}
+
+/** The plan, or a refusal (`empty` / `too-large`). */
+export type PsdExportPlan = PsdExportOk | { status: 'empty' } | { status: 'too-large'; width: number; height: number };
+
+/** Options for {@link planPsdExport}. */
+export interface PlanPsdExportOptions {
+  /** Override the per-side dimension cap (default {@link PSD_MAX_DIMENSION}). */
+  maxDimension?: number;
+}
+
+const layerMatrix = (t: PsdLayerTransform): Mat2d => fromTRS({ x: t.x, y: t.y }, t.rotation, t.scaleX, t.scaleY);
+
+/** Clamps to [0, 1] (defensive against out-of-range opacities). */
+const clamp01 = (value: number): number => (value < 0 ? 0 : value > 1 ? 1 : value);
+
+/**
+ * Plans a PSD export from raster layers (top-first). Computes each layer's
+ * world-space AABB, unions them for the PSD canvas, and produces per-layer PSD
+ * entries in bottom-to-top order. Layers with no content (empty rect, or a
+ * degenerate zero-area transform) contribute nothing and are omitted. Returns
+ * `empty` when nothing has content and `too-large` when the union exceeds the
+ * dimension cap.
+ */
+export const planPsdExport = (
+  inputs: readonly PsdExportLayerInput[],
+  options: PlanPsdExportOptions = {}
+): PsdExportPlan => {
+  const maxDimension = options.maxDimension ?? PSD_MAX_DIMENSION;
+
+  // World-space AABB per layer (null = no content: empty local rect or a
+  // zero-area transform that collapses the bounds).
+  const withBounds = inputs.map((input) => {
+    if (isEmpty(input.contentRect)) {
+      return { input, worldRect: null as Rect | null };
+    }
+    const worldRect = roundOut(transformBounds(layerMatrix(input.transform), input.contentRect));
+    return { input, worldRect: isEmpty(worldRect) ? null : worldRect };
+  });
+
+  let bounds: Rect | null = null;
+  for (const { worldRect } of withBounds) {
+    if (worldRect) {
+      bounds = bounds === null ? worldRect : union(bounds, worldRect);
+    }
+  }
+  if (bounds === null || isEmpty(bounds)) {
+    return { status: 'empty' };
+  }
+  const canvasRect = roundOut(bounds);
+  if (canvasRect.width > maxDimension || canvasRect.height > maxDimension) {
+    return { height: canvasRect.height, status: 'too-large', width: canvasRect.width };
+  }
+
+  const unmappedBlends = new Set<string>();
+  // ag-psd order is bottom-to-top; inputs are top-first, so reverse. Layers
+  // without content are dropped.
+  const layers: PsdPlanLayer[] = [];
+  for (let i = withBounds.length - 1; i >= 0; i -= 1) {
+    const { input, worldRect } = withBounds[i]!;
+    if (!worldRect) {
+      continue;
+    }
+    const mapped = BLEND_MODE_TO_PSD[input.blendMode];
+    if (!mapped) {
+      unmappedBlends.add(input.blendMode);
+    }
+    const left = worldRect.x - canvasRect.x;
+    const top = worldRect.y - canvasRect.y;
+    layers.push({
+      adjustments: input.adjustments,
+      blendMode: mapped ?? 'normal',
+      bottom: top + worldRect.height,
+      compositeBlend: blendToComposite(input.blendMode),
+      contentRect: input.contentRect,
+      hidden: !input.isEnabled,
+      id: input.id,
+      left,
+      name: input.name,
+      opacity: clamp01(input.opacity),
+      right: left + worldRect.width,
+      top,
+      transform: input.transform,
+      worldRect,
+    });
+  }
+
+  return {
+    canvasRect,
+    height: canvasRect.height,
+    layers,
+    status: 'ok',
+    unmappedBlends: [...unmappedBlends],
+    width: canvasRect.width,
+  };
+};
+
+// ---- Executor (impure) -----------------------------------------------------
+
+type Ctx = RasterSurface['ctx'];
+
+/** Reads a surface region's pixels (real DOM path; injectable for tests). */
+const defaultReadImageData = (surface: RasterSurface, rect: Rect): ImageData =>
+  surface.ctx.getImageData(rect.x, rect.y, rect.width, rect.height);
+
+/** Writes pixels back to a surface (real DOM path; injectable for tests). */
+const defaultWriteImageData = (surface: RasterSurface, imageData: ImageData, x: number, y: number): void =>
+  surface.ctx.putImageData(imageData, x, y);
+
+/**
+ * Serializes a {@link Psd} to bytes via a LAZILY-imported `ag-psd`, so the
+ * library is never pulled into the main bundle (Vite code-splits the dynamic
+ * import into its own chunk, loaded only when an export runs).
+ */
+const defaultWritePsd = async (psd: Psd): Promise<ArrayBuffer> => {
+  const { writePsd } = await import('ag-psd');
+  return writePsd(psd);
+};
+
+/** Triggers a browser download of the PSD bytes (Blob + anchor click). */
+const defaultDownload = (data: ArrayBuffer, fileName: string): void => {
+  const blob = new Blob([data], { type: 'image/vnd.adobe.photoshop' });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = fileName;
+  anchor.click();
+  URL.revokeObjectURL(url);
+};
+
+/** Injected dependencies for {@link executePsdExport}. */
+export interface ExecutePsdExportDeps {
+  /** Surface factory (usually the engine's `RasterBackend`). */
+  backend: { createSurface(width: number, height: number): RasterSurface };
+  /** Cancels before the next background allocation or side effect. */
+  signal?: AbortSignal;
+  /**
+   * Ensures a layer's cache is rasterized and returns its surface plus the
+   * content `rect` (layer-local origin/size) those pixels occupy. The engine
+   * wires this to its rasterize path (reading live paint caches when present).
+   */
+  getLayerSurface(layerId: string): Promise<{ surface: RasterSurface; rect: Rect }>;
+  /** Reads a surface region's pixels (default `getImageData`). */
+  readImageData?(surface: RasterSurface, rect: Rect): ImageData;
+  /** Writes pixels back to a surface (default `putImageData`). */
+  writeImageData?(surface: RasterSurface, imageData: ImageData, x: number, y: number): void;
+  /** Serializes a PSD to bytes (default: lazy `ag-psd` `writePsd`). */
+  writePsd?(psd: Psd): Promise<ArrayBuffer>;
+  /** Triggers the download (default: Blob + anchor click). */
+  download?(data: ArrayBuffer, fileName: string): void;
+}
+
+/** Sets a 2D context transform from a matrix. */
+const setTransform = (ctx: Ctx, m: Mat2d): void => {
+  ctx.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
+};
+
+const throwIfAborted = (signal?: AbortSignal): void => {
+  if (signal?.aborted) {
+    throw new DOMException('PSD export was aborted.', 'AbortError');
+  }
+};
+
+/**
+ * Bakes one planned layer's pixels into a world-AABB-sized surface: draws the
+ * layer's cache through its transform (offset into the AABB), then bakes any
+ * non-destructive adjustments in place. Opacity/blend are NOT baked — they ride
+ * on the PSD layer. Returns the surface + its straight-alpha `ImageData`.
+ */
+const bakeLayer = async (
+  planLayer: PsdPlanLayer,
+  deps: ExecutePsdExportDeps,
+  read: (surface: RasterSurface, rect: Rect) => ImageData,
+  write: (surface: RasterSurface, imageData: ImageData, x: number, y: number) => void
+): Promise<{ surface: RasterSurface; imageData: ImageData }> => {
+  throwIfAborted(deps.signal);
+  const { worldRect } = planLayer;
+  const width = worldRect.width;
+  const height = worldRect.height;
+  const surface = deps.backend.createSurface(width, height);
+  const ctx = surface.ctx;
+  setTransform(ctx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+  ctx.clearRect(0, 0, width, height);
+
+  const { rect, surface: cache } = await deps.getLayerSurface(planLayer.id);
+  throwIfAborted(deps.signal);
+  // local→world then shift into AABB-local (translation only affects e/f).
+  const local = layerMatrix(planLayer.transform);
+  setTransform(ctx, { ...local, e: local.e - worldRect.x, f: local.f - worldRect.y });
+  // The cache holds pixels for `rect` in layer-local space; draw at that origin.
+  if (rect.width > 0 && rect.height > 0) {
+    ctx.drawImage(cache.canvas, rect.x, rect.y);
+  }
+
+  const fullRect: Rect = { height, width, x: 0, y: 0 };
+  const imageData = read(surface, fullRect);
+  if (planLayer.adjustments) {
+    applyAdjustments(imageData, planLayer.adjustments);
+    // Write the adjusted pixels back so the flattened composite (below) reuses
+    // this surface directly.
+    write(surface, imageData, 0, 0);
+  }
+  return { imageData, surface };
+};
+
+/**
+ * Executes a PSD export plan: bakes each layer, flattens the enabled layers into
+ * a merged composite (so Photoshop/Bridge show a correct preview — ag-psd does
+ * NOT regenerate the composite), assembles the {@link Psd}, serializes via the
+ * lazily-imported `ag-psd`, and triggers a download. No-op for a non-`ok` plan.
+ */
+export const executePsdExport = async (
+  plan: PsdExportPlan,
+  fileName: string,
+  deps: ExecutePsdExportDeps
+): Promise<void> => {
+  if (plan.status !== 'ok') {
+    return;
+  }
+  const read = deps.readImageData ?? defaultReadImageData;
+  const write = deps.writeImageData ?? defaultWriteImageData;
+  const writePsdFn = deps.writePsd ?? defaultWritePsd;
+  const download = deps.download ?? defaultDownload;
+
+  const children: AgPsdLayer[] = [];
+  const baked: { planLayer: PsdPlanLayer; surface: RasterSurface }[] = [];
+
+  for (const planLayer of plan.layers) {
+    throwIfAborted(deps.signal);
+    const { imageData, surface } = await bakeLayer(planLayer, deps, read, write);
+    baked.push({ planLayer, surface });
+    children.push({
+      blendMode: planLayer.blendMode,
+      bottom: planLayer.bottom,
+      hidden: planLayer.hidden,
+      imageData,
+      left: planLayer.left,
+      name: planLayer.name,
+      opacity: planLayer.opacity,
+      right: planLayer.right,
+      top: planLayer.top,
+    });
+  }
+
+  // Flatten the enabled layers (bottom-to-top = plan order) into the merged
+  // composite the PSD carries as its full-document preview.
+  throwIfAborted(deps.signal);
+  const composite = deps.backend.createSurface(plan.width, plan.height);
+  const cctx = composite.ctx;
+  setTransform(cctx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+  cctx.clearRect(0, 0, plan.width, plan.height);
+  for (const { planLayer, surface } of baked) {
+    if (planLayer.hidden) {
+      continue;
+    }
+    cctx.globalAlpha = planLayer.opacity;
+    cctx.globalCompositeOperation = planLayer.compositeBlend;
+    cctx.drawImage(surface.canvas, planLayer.left, planLayer.top);
+  }
+  cctx.globalAlpha = 1;
+  cctx.globalCompositeOperation = 'source-over';
+
+  const psd: Psd = {
+    children,
+    height: plan.height,
+    imageData: read(composite, { height: plan.height, width: plan.width, x: 0, y: 0 }),
+    width: plan.width,
+  };
+
+  throwIfAborted(deps.signal);
+  const bytes = await writePsdFn(psd);
+  throwIfAborted(deps.signal);
+  download(bytes, fileName);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/exportRasterComposite.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/exportRasterComposite.test.ts
new file mode 100644
index 00000000000..8a5c55a2f1a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/exportRasterComposite.test.ts
@@ -0,0 +1,191 @@
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasImageRef, CanvasLayerContract } from '@workbench/types';
+
+import { RasterMemoryBudgetController } from '@workbench/canvas-engine/controllers/rasterMemoryBudgetController';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ExportRasterCompositeDeps, RasterCompositeExportSnapshot } from './exportRasterComposite';
+
+import { exportRasterComposite } from './exportRasterComposite';
+
+const imageRef = (imageName: string, width = 64, height = 32): CanvasImageRef => ({ height, imageName, width });
+
+const createDeferred = <T>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+const rasterLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: imageRef(id), type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: -4, y: 8 },
+  type: 'raster',
+});
+
+const controlLayer = (id: string): CanvasLayerContract => ({
+  adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: imageRef(id), type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: false,
+});
+
+const makeDoc = (layers: CanvasLayerContract[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 128, width: 128, x: 0, y: 0 },
+  height: 128,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 128,
+});
+
+const makeDeps = (document: CanvasDocumentContractV2) => {
+  const stub = createTestStubRasterBackend();
+  const snapshot: RasterCompositeExportSnapshot = {
+    contentEpoch: 1,
+    document,
+    documentGeneration: 1,
+    lifecycleGeneration: 1,
+  };
+  const encodeSurface = vi.fn((surface: RasterSurface, type?: string) => stub.encodeSurface(surface, type));
+  const deps: ExportRasterCompositeDeps = {
+    backend: {
+      createSurface: (width, height) => stub.createSurface(width, height),
+      encodeSurface,
+    },
+    captureSnapshot: vi.fn(() => snapshot),
+    getLayerSurface: vi.fn(() =>
+      Promise.resolve({
+        rect: { height: 32, width: 64, x: 0, y: 0 },
+        surface: stub.createSurface(64, 32),
+      })
+    ),
+    isSnapshotCurrent: vi.fn(() => true),
+  };
+  return { deps, encodeSurface };
+};
+
+describe('exportRasterComposite', () => {
+  it('exports tight content as a PNG without uploading it', async () => {
+    const { deps, encodeSurface } = makeDeps(makeDoc([rasterLayer('raster')]));
+
+    const result = await exportRasterComposite({ bounds: 'content' }, deps);
+
+    expect(result).toMatchObject({ status: 'ok', rect: { x: -4, y: 8, width: 64, height: 32 } });
+    expect(encodeSurface).toHaveBeenCalledOnce();
+    expect(encodeSurface).toHaveBeenCalledWith(expect.anything(), 'image/png');
+    expect(deps).not.toHaveProperty('uploadImage');
+  });
+
+  it('exports the exact requested bbox', async () => {
+    const { deps } = makeDeps(makeDoc([rasterLayer('raster')]));
+    const bbox: Rect = { height: 48, width: 96, x: 12, y: -6 };
+
+    await expect(exportRasterComposite({ bounds: 'rect', rect: bbox }, deps)).resolves.toMatchObject({
+      status: 'ok',
+      rect: bbox,
+    });
+  });
+
+  it('returns empty when the document has no enabled raster content', async () => {
+    const { deps: noContentDeps } = makeDeps(makeDoc([controlLayer('control')]));
+
+    await expect(exportRasterComposite({ bounds: 'content' }, noContentDeps)).resolves.toEqual({ status: 'empty' });
+  });
+
+  it('returns empty for a zero-area requested rect', async () => {
+    const { deps } = makeDeps(makeDoc([rasterLayer('raster')]));
+
+    await expect(
+      exportRasterComposite({ bounds: 'rect', rect: { x: 0, y: 0, width: 0, height: 32 } }, deps)
+    ).resolves.toEqual({ status: 'empty' });
+  });
+
+  it('returns over-budget before allocating a background composite', async () => {
+    const { deps, encodeSurface } = makeDeps(makeDoc([rasterLayer('raster')]));
+    deps.reserve = vi.fn(() => ({ availableBytes: 1_000, requestedBytes: 8_192, status: 'over-budget' as const }));
+
+    await expect(exportRasterComposite({ bounds: 'content' }, deps)).resolves.toEqual({ status: 'over-budget' });
+    expect(deps.getLayerSurface).not.toHaveBeenCalled();
+    expect(encodeSurface).not.toHaveBeenCalled();
+  });
+
+  it('releases the reservation and cache pins after export', async () => {
+    const { deps } = makeDeps(makeDoc([rasterLayer('raster')]));
+    const releaseReservation = vi.fn();
+    const releasePins = vi.fn();
+    deps.reserve = vi.fn(() => ({ lease: { release: releaseReservation }, status: 'ok' as const }));
+    deps.pin = vi.fn(() => ({ release: releasePins }));
+
+    await expect(exportRasterComposite({ bounds: 'content' }, deps)).resolves.toMatchObject({ status: 'ok' });
+    expect(deps.pin).toHaveBeenCalledWith(['raster']);
+    expect(releasePins).toHaveBeenCalledOnce();
+    expect(releaseReservation).toHaveBeenCalledOnce();
+  });
+
+  it('keeps its reservation and cache pins while rendering across generation release', async () => {
+    const { deps } = makeDeps(makeDoc([rasterLayer('raster')]));
+    const memory = new RasterMemoryBudgetController({ budgetBytes: 100_000 });
+    const layerSurface = createDeferred<{ rect: Rect; surface: RasterSurface }>();
+    deps.getLayerSurface = vi.fn(() => layerSurface.promise);
+    deps.reserve = (bytes) => memory.reserveOperation(bytes, { purpose: 'background-snapshot' });
+    deps.pin = (layerIds) => {
+      const leases = layerIds.map((layerId) => memory.pinOperation(layerId));
+      return { release: () => leases.forEach((lease) => lease.release()) };
+    };
+
+    const exported = exportRasterComposite({ bounds: 'content' }, deps);
+    await vi.waitFor(() => expect(memory.snapshot().reservedBytes).toBeGreaterThan(0));
+    memory.releaseGeneration(1);
+
+    expect(memory.snapshot().reservedBytes).toBeGreaterThan(0);
+    expect(memory.isPinned('raster')).toBe(true);
+
+    const backend = createTestStubRasterBackend();
+    layerSurface.resolve({
+      rect: { height: 32, width: 64, x: 0, y: 0 },
+      surface: backend.createSurface(64, 32),
+    });
+    await expect(exported).resolves.toMatchObject({ status: 'ok' });
+    expect(memory.snapshot().reservedBytes).toBe(0);
+    expect(memory.isPinned('raster')).toBe(false);
+  });
+
+  it('reserves both the temporary surface and ImageData for an adjusted layer', async () => {
+    const layer = rasterLayer('raster');
+    if (layer.type !== 'raster') {
+      throw new Error('Expected raster layer');
+    }
+    const { deps } = makeDeps(makeDoc([{ ...layer, adjustments: { brightness: 0.1, contrast: 0, saturation: 0 } }]));
+    const reserve = vi.fn(() => ({ lease: { release: vi.fn() }, status: 'ok' as const }));
+    deps.reserve = reserve;
+
+    await expect(exportRasterComposite({ bounds: 'content' }, deps)).resolves.toMatchObject({ status: 'ok' });
+
+    expect(reserve).toHaveBeenCalledWith(24_576);
+  });
+
+  it('discards an encoded blob if the document changes during export', async () => {
+    const { deps } = makeDeps(makeDoc([rasterLayer('raster')]));
+    vi.mocked(deps.isSnapshotCurrent).mockReturnValueOnce(true).mockReturnValue(false);
+
+    await expect(exportRasterComposite({ bounds: 'content' }, deps)).resolves.toEqual({ status: 'stale' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/exportRasterComposite.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/exportRasterComposite.ts
new file mode 100644
index 00000000000..ac78c2041d2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/exportRasterComposite.ts
@@ -0,0 +1,101 @@
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { isEmpty } from '@workbench/canvas-engine/math/rect';
+import {
+  getBaseRasterContentBounds,
+  planBaseRasterComposite,
+  renderRasterComposite,
+  type RenderRasterCompositeDeps,
+} from '@workbench/canvas-engine/render/rasterComposite';
+
+export type RasterCompositeExportRequest = { bounds: 'content' } | { bounds: 'rect'; rect: Rect };
+
+export type RasterCompositeExportResult =
+  | { status: 'ok'; blob: Blob; rect: Rect }
+  | { status: 'empty' | 'stale' | 'not-ready' | 'over-budget' };
+
+export interface RasterCompositeExportSnapshot {
+  contentEpoch: number;
+  document: CanvasDocumentContractV2 | null;
+  documentGeneration: number;
+  lifecycleGeneration: number;
+}
+
+export class RasterCompositeOverBudgetError extends Error {
+  constructor() {
+    super('Raster composite allocation is over budget.');
+    this.name = 'RasterCompositeOverBudgetError';
+  }
+}
+
+export interface ExportRasterCompositeDeps extends RenderRasterCompositeDeps {
+  backend: RenderRasterCompositeDeps['backend'] & {
+    encodeSurface(surface: RasterSurface, type?: string): Promise<Blob>;
+  };
+  captureSnapshot(): RasterCompositeExportSnapshot;
+  isSnapshotCurrent(snapshot: RasterCompositeExportSnapshot): boolean;
+  reserve?(
+    bytes: number
+  ):
+    | { status: 'ok'; lease: { release(): void } }
+    | { status: 'over-budget'; requestedBytes: number; availableBytes: number };
+  pin?(layerIds: readonly string[]): { release(): void };
+}
+
+export const exportRasterComposite = async (
+  request: RasterCompositeExportRequest,
+  deps: ExportRasterCompositeDeps
+): Promise<RasterCompositeExportResult> => {
+  const snapshot = deps.captureSnapshot();
+  const document = snapshot.document;
+  if (!document) {
+    return { status: 'not-ready' };
+  }
+
+  const rect = request.bounds === 'content' ? getBaseRasterContentBounds(document) : request.rect;
+  if (!rect || isEmpty(rect)) {
+    return { status: 'empty' };
+  }
+
+  const entry = planBaseRasterComposite(document, rect);
+  if (entry.layers.length === 0) {
+    return { status: 'empty' };
+  }
+
+  // Each adjusted layer needs both a temporary surface and a same-sized
+  // ImageData buffer in addition to the final composite surface.
+  const surfaceCount = 1 + entry.layers.filter((layer) => layer.adjustments !== undefined).length * 2;
+  const reservation = deps.reserve?.(rect.width * rect.height * 4 * surfaceCount);
+  if (reservation?.status === 'over-budget') {
+    return { status: 'over-budget' };
+  }
+  const pinLease = deps.pin?.(entry.layers.map((layer) => layer.id));
+
+  try {
+    let surface: RasterSurface;
+    try {
+      surface = await renderRasterComposite(entry, deps);
+    } catch (error) {
+      if (error instanceof RasterCompositeOverBudgetError) {
+        return { status: 'over-budget' };
+      }
+      if (!deps.isSnapshotCurrent(snapshot)) {
+        return { status: 'stale' };
+      }
+      throw error;
+    }
+    if (!deps.isSnapshotCurrent(snapshot)) {
+      return { status: 'stale' };
+    }
+
+    const blob = await deps.backend.encodeSurface(surface, 'image/png');
+    return deps.isSnapshotCurrent(snapshot) ? { status: 'ok', blob, rect } : { status: 'stale' };
+  } finally {
+    pinLease?.release();
+    if (reservation?.status === 'ok') {
+      reservation.lease.release();
+    }
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/filterError.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/filterError.ts
new file mode 100644
index 00000000000..e641a9ac1fd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/filterError.ts
@@ -0,0 +1,18 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+
+const filterName = (filterType: string): string =>
+  filterType
+    .split('_')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+
+export class LayerFilterOutputDimensionError extends Error {
+  readonly code = 'output-dimension' as const;
+
+  constructor(filterType: string, output: { width: number; height: number }, source: Rect) {
+    super(
+      `${filterName(filterType)} output dimensions ${String(output.width)}x${String(output.height)} do not match source dimensions ${source.width}x${source.height}.`
+    );
+    this.name = 'LayerFilterOutputDimensionError';
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/freehand.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/freehand.test.ts
new file mode 100644
index 00000000000..c9eff1ac481
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/freehand.test.ts
@@ -0,0 +1,85 @@
+import type { StrokeSamplePoint } from '@workbench/canvas-engine/freehand';
+import type { Vec2 } from '@workbench/canvas-engine/types';
+
+import { polygonBounds, polygonToSvgPath, strokeOutlinePolygon, strokeToPath } from '@workbench/canvas-engine/freehand';
+import { describe, expect, it } from 'vitest';
+
+/** Signed polygon area (shoelace); sign indicates winding, magnitude the area. */
+const signedArea = (polygon: readonly Vec2[]): number => {
+  let sum = 0;
+  for (let i = 0; i < polygon.length; i++) {
+    const a = polygon[i]!;
+    const b = polygon[(i + 1) % polygon.length]!;
+    sum += a.x * b.y - b.x * a.y;
+  }
+  return sum / 2;
+};
+
+const horizontalLine = (pressure: number): StrokeSamplePoint[] =>
+  Array.from({ length: 9 }, (_, i) => ({ pressure, x: 10 + i * 10, y: 50 }));
+
+describe('strokeOutlinePolygon', () => {
+  it('returns an empty polygon for no points', () => {
+    expect(strokeOutlinePolygon([], { size: 20 })).toEqual([]);
+  });
+
+  it('produces a closed, non-degenerate outline around a straight line', () => {
+    const polygon = strokeOutlinePolygon(horizontalLine(0.5), { size: 20, thinning: 0 });
+    expect(polygon.length).toBeGreaterThan(2);
+    // A real 2D band, not a collinear degenerate: non-zero winding area.
+    expect(Math.abs(signedArea(polygon))).toBeGreaterThan(0);
+  });
+
+  it('brackets the input points with a width near the base size (no thinning)', () => {
+    const size = 20;
+    const bounds = polygonBounds(strokeOutlinePolygon(horizontalLine(0.5), { size, thinning: 0 }));
+    // The band spans the drawn length (~80px) plus the round caps.
+    expect(bounds.width).toBeGreaterThan(80);
+    // With thinning disabled the perpendicular extent tracks the base diameter.
+    expect(bounds.height).toBeGreaterThan(size * 0.5);
+    expect(bounds.height).toBeLessThan(size * 2);
+    // Centered on the y=50 line the points sit on.
+    expect(bounds.y).toBeLessThan(50);
+    expect(bounds.y + bounds.height).toBeGreaterThan(50);
+  });
+
+  it('widens the stroke as pressure increases when thinning is enabled', () => {
+    const opts = { size: 40, thinning: 0.8 } as const;
+    const light = polygonBounds(strokeOutlinePolygon(horizontalLine(0.1), opts));
+    const heavy = polygonBounds(strokeOutlinePolygon(horizontalLine(0.95), opts));
+    expect(heavy.height).toBeGreaterThan(light.height);
+  });
+});
+
+describe('polygonToSvgPath', () => {
+  it('serializes a polygon to a closed move/line path', () => {
+    const path = polygonToSvgPath([
+      { x: 0, y: 0 },
+      { x: 10, y: 0 },
+      { x: 10, y: 5 },
+    ]);
+    expect(path).toBe('M 0 0 L 10 0 L 10 5 Z');
+  });
+
+  it('returns an empty string for an empty polygon', () => {
+    expect(polygonToSvgPath([])).toBe('');
+  });
+});
+
+describe('strokeToPath', () => {
+  it('builds the path via the injected factory and returns the polygon bounds', () => {
+    const seen: string[] = [];
+    const marker = { __brand: 'path' } as unknown as Path2D;
+    const createPath2D = (d?: string): Path2D => {
+      seen.push(d ?? '');
+      return marker;
+    };
+    const result = strokeToPath(horizontalLine(0.5), { size: 20, thinning: 0 }, createPath2D);
+
+    expect(result.path).toBe(marker);
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatch(/^M /);
+    expect(result.polygon.length).toBeGreaterThan(2);
+    expect(result.bounds).toEqual(polygonBounds(result.polygon));
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/freehand.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/freehand.ts
new file mode 100644
index 00000000000..83e57cd3d4f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/freehand.ts
@@ -0,0 +1,122 @@
+/**
+ * A thin wrapper over `perfect-freehand`, turning a pressure-sampled point path
+ * into the filled outline polygon of a variable-width stroke.
+ *
+ * The polygon math ({@link strokeOutlinePolygon}) is pure and DOM-free, so it is
+ * fully unit-testable in node. `Path2D` does not exist in node, so building the
+ * fillable path is split out into {@link strokeToPath}, which takes an injected
+ * `createPath2D` factory (the engine passes `(d) => new Path2D(d)`; tests pass a
+ * stub). This keeps the interesting geometry testable without a DOM.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+import { getStroke } from 'perfect-freehand';
+
+/** A single pressure-sampled input point for a stroke. */
+export interface StrokeSamplePoint {
+  x: number;
+  y: number;
+  /** Pressure in [0, 1]. */
+  pressure: number;
+}
+
+/** Tuning for the freehand outline. `size` is the base stroke diameter in document units. */
+export interface FreehandOptions {
+  /** Base stroke diameter (document units). */
+  size: number;
+  /** Effect of pressure on width, [0, 1]. 0 disables pressure sensitivity. */
+  thinning?: number;
+  /** Edge softening, [0, 1]. */
+  smoothing?: number;
+  /** Input smoothing / lag, [0, 1]. */
+  streamline?: number;
+  /** Whether the stroke is complete (adds the end cap). */
+  last?: boolean;
+}
+
+/** Factory for a `Path2D`; injected so the polygon math stays node-testable. */
+export type CreatePath2D = (d?: string) => Path2D;
+
+const DEFAULT_SMOOTHING = 0.5;
+const DEFAULT_STREAMLINE = 0.5;
+const DEFAULT_THINNING = 0.5;
+
+/**
+ * Computes the filled outline polygon (a closed ring of document-space points)
+ * of a variable-width stroke through `points`. Pure and DOM-free.
+ */
+export const strokeOutlinePolygon = (points: readonly StrokeSamplePoint[], opts: FreehandOptions): Vec2[] => {
+  if (points.length === 0) {
+    return [];
+  }
+  const outline = getStroke(
+    points.map((p) => [p.x, p.y, p.pressure]),
+    {
+      last: opts.last ?? false,
+      simulatePressure: false,
+      size: opts.size,
+      smoothing: opts.smoothing ?? DEFAULT_SMOOTHING,
+      streamline: opts.streamline ?? DEFAULT_STREAMLINE,
+      thinning: opts.thinning ?? DEFAULT_THINNING,
+    }
+  );
+  return outline.map(([x, y]) => ({ x, y }));
+};
+
+/** Serializes an outline polygon to an SVG path string (`M … L … Z`). */
+export const polygonToSvgPath = (polygon: readonly Vec2[]): string => {
+  if (polygon.length === 0) {
+    return '';
+  }
+  const [first, ...rest] = polygon;
+  let d = `M ${first.x} ${first.y}`;
+  for (const p of rest) {
+    d += ` L ${p.x} ${p.y}`;
+  }
+  return `${d} Z`;
+};
+
+/** Axis-aligned bounds of an outline polygon; an empty polygon yields a zero-size rect. */
+export const polygonBounds = (polygon: readonly Vec2[]): Rect => {
+  if (polygon.length === 0) {
+    return { height: 0, width: 0, x: 0, y: 0 };
+  }
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const p of polygon) {
+    if (p.x < minX) {
+      minX = p.x;
+    }
+    if (p.y < minY) {
+      minY = p.y;
+    }
+    if (p.x > maxX) {
+      maxX = p.x;
+    }
+    if (p.y > maxY) {
+      maxY = p.y;
+    }
+  }
+  return { height: maxY - minY, width: maxX - minX, x: minX, y: minY };
+};
+
+/**
+ * Builds a fillable `Path2D` for the stroke through `points`, using the injected
+ * `createPath2D` factory (so callers in node can stub it). Returns the built
+ * path and the polygon's document-space {@link Rect} bounds so the caller can
+ * derive the dirty region without recomputing the outline.
+ */
+export const strokeToPath = (
+  points: readonly StrokeSamplePoint[],
+  opts: FreehandOptions,
+  createPath2D: CreatePath2D
+): { path: Path2D; polygon: Vec2[]; bounds: Rect } => {
+  const polygon = strokeOutlinePolygon(points, opts);
+  const path = createPath2D(polygonToSvgPath(polygon));
+  return { bounds: polygonBounds(polygon), path, polygon };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/documentPatch.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/documentPatch.test.ts
new file mode 100644
index 00000000000..b112710d1ff
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/documentPatch.test.ts
@@ -0,0 +1,30 @@
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createDocumentPatchEntry, DOCUMENT_PATCH_DEFAULT_BYTES } from './documentPatch';
+
+const forward: CanvasProjectMutation = { direction: 1, type: 'cycleStagedImage' };
+const inverse: CanvasProjectMutation = { direction: -1, type: 'cycleStagedImage' };
+
+describe('createDocumentPatchEntry', () => {
+  it('dispatches inverse on undo and forward on redo', () => {
+    const dispatch = vi.fn();
+    const entry = createDocumentPatchEntry({ dispatch, forward, inverse, label: 'Cycle' });
+
+    entry.undo();
+    expect(dispatch).toHaveBeenNthCalledWith(1, inverse);
+    entry.redo();
+    expect(dispatch).toHaveBeenNthCalledWith(2, forward);
+  });
+
+  it('defaults bytes to a small nominal cost, overridable', () => {
+    const dispatch = vi.fn();
+    const entry = createDocumentPatchEntry({ dispatch, forward, inverse, label: 'Cycle' });
+    expect(entry.bytes).toBe(DOCUMENT_PATCH_DEFAULT_BYTES);
+
+    const heavier = createDocumentPatchEntry({ bytes: 4096, dispatch, forward, inverse, label: 'Cycle' });
+    expect(heavier.bytes).toBe(4096);
+    expect(heavier.label).toBe('Cycle');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/documentPatch.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/documentPatch.ts
new file mode 100644
index 00000000000..c1c296b30a6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/documentPatch.ts
@@ -0,0 +1,49 @@
+/**
+ * A structural history entry: a pair of reducer actions (forward + inverse)
+ * dispatched to undo/redo a document-shape change.
+ *
+ * Unlike a pixel {@link createImagePatchEntry | image patch}, a document patch
+ * carries no bitmaps — just two {@link CanvasProjectMutation}s. Undo dispatches the
+ * `inverse`, redo dispatches the `forward`. It exists so structural canvas edits
+ * (add/remove/reorder layer, rename, …) can live on the same engine-owned undo
+ * stack as paint edits. Phase 3's layers-panel operations lean on this; P2.1 uses
+ * it lightly (if at all) for composing an auto-created layer into a stroke's undo.
+ *
+ * Byte cost is tiny (actions are small plain objects); the default keeps it off
+ * the byte budget's radar while still counting as one of the entry-count slots.
+ *
+ * Zero React, zero DOM, zero import-time side effects.
+ */
+
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+
+import type { HistoryEntry } from './history';
+
+/** Nominal byte cost for a structural entry (small; actions are plain objects). */
+export const DOCUMENT_PATCH_DEFAULT_BYTES = 256;
+
+/** Options for {@link createDocumentPatchEntry}. */
+export interface CreateDocumentPatchEntryOptions {
+  label: string;
+  /** The action that performs the change (dispatched on redo). */
+  forward: CanvasProjectMutation;
+  /** The action that reverses the change (dispatched on undo). */
+  inverse: CanvasProjectMutation;
+  /** The reducer bridge. */
+  dispatch(action: CanvasProjectMutation): void;
+  /** Approximate retained size (default {@link DOCUMENT_PATCH_DEFAULT_BYTES}). */
+  bytes?: number;
+}
+
+/** Creates a reversible structural entry that dispatches inverse on undo, forward on redo. */
+export const createDocumentPatchEntry = (opts: CreateDocumentPatchEntryOptions): HistoryEntry => {
+  const { dispatch, forward, inverse, label } = opts;
+  const bytes = opts.bytes ?? DOCUMENT_PATCH_DEFAULT_BYTES;
+
+  return {
+    bytes,
+    label,
+    redo: () => dispatch(forward),
+    undo: () => dispatch(inverse),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/history.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/history.test.ts
new file mode 100644
index 00000000000..b2d27d70551
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/history.test.ts
@@ -0,0 +1,502 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { HistoryEntry } from './history';
+
+import { createHistory, HISTORY_BYTE_BUDGET, HISTORY_MAX_ENTRIES } from './history';
+
+/** A tiny entry that records undo/redo calls into a shared log. */
+const makeEntry = (label: string, log: string[], bytes = 0): HistoryEntry => ({
+  bytes,
+  label,
+  redo: () => log.push(`redo:${label}`),
+  undo: () => log.push(`undo:${label}`),
+});
+
+describe('createHistory: push / undo / redo ordering', () => {
+  it('undoes and redoes entries in LIFO order', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    history.push(makeEntry('a', log));
+    history.push(makeEntry('b', log));
+    history.push(makeEntry('c', log));
+
+    history.undo();
+    history.undo();
+    expect(log).toEqual(['undo:c', 'undo:b']);
+
+    history.redo();
+    expect(log).toEqual(['undo:c', 'undo:b', 'redo:b']);
+
+    history.undo();
+    history.undo();
+    expect(log).toEqual(['undo:c', 'undo:b', 'redo:b', 'undo:b', 'undo:a']);
+  });
+
+  it('undo / redo are no-ops on empty stacks', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    history.undo();
+    history.redo();
+    expect(log).toEqual([]);
+    expect(history.canUndo()).toBe(false);
+    expect(history.canRedo()).toBe(false);
+  });
+});
+
+describe('createHistory: redo cleared on push', () => {
+  it('drops the redo stack when a new entry is pushed', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    history.push(makeEntry('a', log));
+    history.push(makeEntry('b', log));
+    history.undo(); // b -> redo
+    expect(history.canRedo()).toBe(true);
+
+    history.push(makeEntry('c', log));
+    expect(history.canRedo()).toBe(false);
+
+    // Redoing does nothing: the redo stack was cleared by the push.
+    history.redo();
+    expect(log).toEqual(['undo:b']);
+  });
+});
+
+describe('createHistory: entry-count eviction', () => {
+  it('evicts the oldest entry beyond the 64-entry budget', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    // Push one past the default cap.
+    for (let i = 0; i < HISTORY_MAX_ENTRIES + 1; i += 1) {
+      history.push(makeEntry(`e${i}`, log));
+    }
+    // Undo every retained entry: there should be exactly the cap, and the very
+    // first entry (e0) should have been evicted (never undone).
+    let undos = 0;
+    while (history.canUndo()) {
+      history.undo();
+      undos += 1;
+    }
+    expect(undos).toBe(HISTORY_MAX_ENTRIES);
+    expect(log).not.toContain('undo:e0');
+    expect(log).toContain('undo:e1');
+    expect(log[log.length - 1]).toBe('undo:e1');
+  });
+
+  it('honors a custom maxEntries', () => {
+    const log: string[] = [];
+    const history = createHistory({ maxEntries: 2 });
+    history.push(makeEntry('a', log));
+    history.push(makeEntry('b', log));
+    history.push(makeEntry('c', log)); // evicts 'a'
+    let undos = 0;
+    while (history.canUndo()) {
+      history.undo();
+      undos += 1;
+    }
+    expect(undos).toBe(2);
+    expect(log).toEqual(['undo:c', 'undo:b']);
+  });
+});
+
+describe('createHistory: byte-budget eviction', () => {
+  it('evicts oldest entries until under the byte budget', () => {
+    const log: string[] = [];
+    // Budget fits two 10-byte entries but not three.
+    const history = createHistory({ byteBudget: 25 });
+    history.push(makeEntry('a', log, 10));
+    history.push(makeEntry('b', log, 10));
+    expect(history.canUndo()).toBe(true);
+    history.push(makeEntry('c', log, 10)); // total 30 > 25 -> evict 'a'
+
+    let undos = 0;
+    while (history.canUndo()) {
+      history.undo();
+      undos += 1;
+    }
+    expect(undos).toBe(2);
+    expect(log).toEqual(['undo:c', 'undo:b']);
+  });
+
+  it('exports the 256 MB default byte budget', () => {
+    expect(HISTORY_BYTE_BUDGET).toBe(256 * 1024 * 1024);
+  });
+});
+
+describe('createHistory: change listener', () => {
+  it('fires on push / undo / redo / clear', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    const listener = vi.fn();
+    const unsubscribe = history.subscribe(listener);
+
+    history.push(makeEntry('a', log));
+    expect(listener).toHaveBeenCalledTimes(1);
+    history.undo();
+    expect(listener).toHaveBeenCalledTimes(2);
+    history.redo();
+    expect(listener).toHaveBeenCalledTimes(3);
+    history.clear();
+    expect(listener).toHaveBeenCalledTimes(4);
+
+    // Clear again with empty stacks: no change, no notification.
+    history.clear();
+    expect(listener).toHaveBeenCalledTimes(4);
+
+    unsubscribe();
+    history.push(makeEntry('b', log));
+    expect(listener).toHaveBeenCalledTimes(4);
+  });
+
+  it('reflects canUndo / canRedo transitions', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    expect(history.canUndo()).toBe(false);
+    history.push(makeEntry('a', log));
+    expect(history.canUndo()).toBe(true);
+    expect(history.canRedo()).toBe(false);
+    history.undo();
+    expect(history.canUndo()).toBe(false);
+    expect(history.canRedo()).toBe(true);
+  });
+});
+
+describe('createHistory: amendLast', () => {
+  it('replaces the most recent entry in place and adjusts the byte total', () => {
+    const log: string[] = [];
+    const history = createHistory({ byteBudget: 25 });
+    history.push(makeEntry('a', log, 10));
+    history.push(makeEntry('b', log, 10)); // burst start
+
+    // Coalesce: replace 'b' with 'b2' (still one burst entry).
+    history.amendLast(makeEntry('b2', log, 10));
+
+    let undos = 0;
+    while (history.canUndo()) {
+      history.undo();
+      undos += 1;
+    }
+    // Two entries retained (a + b2), not three: amend did not grow the stack.
+    expect(undos).toBe(2);
+    expect(log).toEqual(['undo:b2', 'undo:a']);
+  });
+
+  it('pushes when the undo stack is empty', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    history.amendLast(makeEntry('a', log));
+    expect(history.canUndo()).toBe(true);
+    history.undo();
+    expect(log).toEqual(['undo:a']);
+  });
+
+  it('clears the redo stack like push', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    history.push(makeEntry('a', log));
+    history.push(makeEntry('b', log));
+    history.undo(); // b -> redo
+    expect(history.canRedo()).toBe(true);
+    history.amendLast(makeEntry('a2', log));
+    expect(history.canRedo()).toBe(false);
+  });
+
+  it('is a no-op while applying', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    const reentrant: HistoryEntry = {
+      bytes: 0,
+      label: 'reentrant',
+      redo: () => {},
+      undo: () => history.amendLast(makeEntry('sneaky', log)),
+    };
+    history.push(reentrant);
+    history.undo();
+    // The amend during undo was dropped; only the reentrant entry is reachable.
+    history.redo();
+    let undos = 0;
+    while (history.canUndo()) {
+      history.undo();
+      undos += 1;
+    }
+    expect(undos).toBe(1);
+  });
+});
+
+describe('createHistory: re-entrancy guard', () => {
+  it('reports isApplying during undo/redo and drops entries pushed while applying', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    const observed: boolean[] = [];
+
+    const reentrant: HistoryEntry = {
+      bytes: 0,
+      label: 'reentrant',
+      redo: () => {
+        observed.push(history.isApplying());
+        // A replay must not be able to record a new entry.
+        history.push(makeEntry('sneaky', log));
+      },
+      undo: () => {
+        observed.push(history.isApplying());
+        history.push(makeEntry('sneaky', log));
+      },
+    };
+
+    expect(history.isApplying()).toBe(false);
+    history.push(reentrant);
+    history.undo();
+    expect(observed).toEqual([true]);
+    expect(history.isApplying()).toBe(false);
+    // The sneaky push during undo was dropped: redo stack still holds only the
+    // reentrant entry, and no 'sneaky' entry is reachable.
+    expect(history.canRedo()).toBe(true);
+
+    history.redo();
+    expect(observed).toEqual([true, true]);
+    // Still exactly one undoable entry (the reentrant one); the sneaky pushes
+    // never landed.
+    let undos = 0;
+    while (history.canUndo()) {
+      history.undo();
+      undos += 1;
+    }
+    expect(undos).toBe(1);
+  });
+});
+
+describe('createHistory: failure-atomic replay', () => {
+  it('keeps a failed undo on the undo stack and allows an exact retry', () => {
+    const history = createHistory();
+    const listener = vi.fn();
+    let shouldFail = true;
+    const undo = vi.fn(() => {
+      if (shouldFail) {
+        throw new Error('undo preparation failed');
+      }
+    });
+    const redo = vi.fn();
+    history.subscribe(listener);
+    history.push({ bytes: 17, label: 'fallible', redo, replayFailureAtomic: true, undo });
+    listener.mockClear();
+
+    expect(() => history.undo()).toThrow('undo preparation failed');
+    expect(history.canUndo()).toBe(true);
+    expect(history.canRedo()).toBe(false);
+    expect(history.isApplying()).toBe(false);
+    expect(listener).not.toHaveBeenCalled();
+
+    shouldFail = false;
+    history.undo();
+    expect(undo).toHaveBeenCalledTimes(2);
+    expect(history.canUndo()).toBe(false);
+    expect(history.canRedo()).toBe(true);
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it('keeps a failed redo on the redo stack and allows an exact retry', () => {
+    const history = createHistory();
+    const listener = vi.fn();
+    let shouldFail = true;
+    const undo = vi.fn();
+    const redo = vi.fn(() => {
+      if (shouldFail) {
+        throw new Error('redo preparation failed');
+      }
+    });
+    history.subscribe(listener);
+    history.push({ bytes: 23, label: 'fallible', redo, replayFailureAtomic: true, undo });
+    history.undo();
+    listener.mockClear();
+
+    expect(() => history.redo()).toThrow('redo preparation failed');
+    expect(history.canUndo()).toBe(false);
+    expect(history.canRedo()).toBe(true);
+    expect(history.isApplying()).toBe(false);
+    expect(listener).not.toHaveBeenCalled();
+
+    shouldFail = false;
+    history.redo();
+    expect(redo).toHaveBeenCalledTimes(2);
+    expect(history.canUndo()).toBe(true);
+    expect(history.canRedo()).toBe(false);
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it('preserves byte-budget accounting after a failed replay', () => {
+    const log: string[] = [];
+    const history = createHistory({ byteBudget: 20 });
+    let shouldFail = true;
+    history.push(makeEntry('a', log, 10));
+    history.push({
+      bytes: 10,
+      label: 'b',
+      redo: () => log.push('redo:b'),
+      replayFailureAtomic: true,
+      undo: () => {
+        if (shouldFail) {
+          throw new Error('failed');
+        }
+        log.push('undo:b');
+      },
+    });
+
+    expect(() => history.undo()).toThrow('failed');
+    shouldFail = false;
+    history.push(makeEntry('c', log, 10));
+
+    // Correct restored accounting is 30 bytes, so the oldest entry is evicted.
+    history.undo();
+    history.undo();
+    expect(log).toEqual(['undo:c', 'undo:b']);
+    expect(history.canUndo()).toBe(false);
+  });
+
+  it.each([false, true])(
+    'does not resurrect an entry when undo clears history (failure-atomic: %s)',
+    (replayFailureAtomic) => {
+      const history = createHistory();
+      const listener = vi.fn();
+      history.subscribe(listener);
+      history.push({
+        bytes: 10,
+        label: 'clear-on-undo',
+        redo: () => {},
+        replayFailureAtomic,
+        undo: () => history.clear(),
+      });
+      listener.mockClear();
+
+      history.undo();
+
+      expect(history.canUndo()).toBe(false);
+      expect(history.canRedo()).toBe(false);
+      expect(listener).toHaveBeenCalledOnce();
+    }
+  );
+
+  it.each([false, true])(
+    'does not resurrect an entry when redo clears history (failure-atomic: %s)',
+    (replayFailureAtomic) => {
+      const history = createHistory();
+      const listener = vi.fn();
+      let clearOnRedo = false;
+      history.subscribe(listener);
+      history.push({
+        bytes: 10,
+        label: 'clear-on-redo',
+        redo: () => {
+          if (clearOnRedo) {
+            history.clear();
+          }
+        },
+        replayFailureAtomic,
+        undo: () => {},
+      });
+      history.undo();
+      clearOnRedo = true;
+      listener.mockClear();
+
+      history.redo();
+
+      expect(history.canUndo()).toBe(false);
+      expect(history.canRedo()).toBe(false);
+      expect(listener).toHaveBeenCalledOnce();
+    }
+  );
+
+  it('moves a legacy undo before replay, notifies, and rethrows a post-application failure', () => {
+    const history = createHistory();
+    const listener = vi.fn();
+    const applied: string[] = [];
+    history.subscribe(listener);
+    history.push({
+      bytes: 10,
+      label: 'legacy-fallible-undo',
+      redo: () => applied.push('redo'),
+      undo: () => {
+        applied.push('undo');
+        throw new Error('undo observer failed');
+      },
+    });
+    listener.mockClear();
+
+    expect(() => history.undo()).toThrow('undo observer failed');
+
+    expect(history.canUndo()).toBe(false);
+    expect(history.canRedo()).toBe(true);
+    expect(history.isApplying()).toBe(false);
+    expect(applied).toEqual(['undo']);
+    expect(listener).toHaveBeenCalledOnce();
+
+    history.redo();
+    expect(applied).toEqual(['undo', 'redo']);
+  });
+
+  it('moves a legacy redo before replay, notifies, and rethrows a post-application failure', () => {
+    const history = createHistory();
+    const listener = vi.fn();
+    const applied: string[] = [];
+    let shouldFail = false;
+    history.subscribe(listener);
+    history.push({
+      bytes: 10,
+      label: 'legacy-fallible-redo',
+      redo: () => {
+        applied.push('redo');
+        if (shouldFail) {
+          throw new Error('redo observer failed');
+        }
+      },
+      undo: () => applied.push('undo'),
+    });
+    history.undo();
+    shouldFail = true;
+    listener.mockClear();
+
+    expect(() => history.redo()).toThrow('redo observer failed');
+
+    expect(history.canUndo()).toBe(true);
+    expect(history.canRedo()).toBe(false);
+    expect(history.isApplying()).toBe(false);
+    expect(applied).toEqual(['undo', 'redo']);
+    expect(listener).toHaveBeenCalledOnce();
+
+    history.undo();
+    expect(applied).toEqual(['undo', 'redo', 'undo']);
+  });
+
+  it('isolates listener failures after successful stack mutations', () => {
+    const log: string[] = [];
+    const history = createHistory();
+    const listener = vi.fn();
+    history.subscribe(() => {
+      throw new Error('history listener failed');
+    });
+    history.subscribe(listener);
+
+    expect(() => history.push(makeEntry('a', log))).not.toThrow();
+    expect(() => history.undo()).not.toThrow();
+    expect(() => history.redo()).not.toThrow();
+    expect(() => history.clear()).not.toThrow();
+
+    expect(listener).toHaveBeenCalledTimes(4);
+    expect(history.canUndo()).toBe(false);
+    expect(history.canRedo()).toBe(false);
+  });
+
+  it('trims oldest entries by retained bytes while preserving the newest undo history', () => {
+    const log: string[] = [];
+    const history = createHistory({ byteBudget: 1_000 });
+    history.push({ ...makeEntry('oldest', log), bytes: 40 });
+    history.push({ ...makeEntry('middle', log), bytes: 50 });
+    history.push({ ...makeEntry('newest', log), bytes: 60 });
+
+    history.trimToBytes(110);
+
+    expect(history.byteSize()).toBe(110);
+    history.undo();
+    history.undo();
+    history.undo();
+    expect(log).toEqual(['undo:newest', 'undo:middle']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/history.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/history.ts
new file mode 100644
index 00000000000..ddcef4b29ab
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/history.ts
@@ -0,0 +1,334 @@
+/**
+ * Engine-owned canvas history: a bounded undo/redo stack of opaque entries.
+ *
+ * Project-level undo (`pushUndo` in the reducer) deliberately no longer covers
+ * the canvas (Phase 0) — pixels never cross the reducer boundary, so the reducer
+ * can't cheaply snapshot them. Instead the canvas keeps its OWN history here,
+ * living entirely inside the engine. Each {@link HistoryEntry} is a self-contained
+ * undo/redo pair (a paint {@link createImagePatchEntry | pixel patch} or a
+ * structural {@link createDocumentPatchEntry | document patch}) plus a byte cost
+ * used to bound memory.
+ *
+ * Budgets (evict oldest beyond EITHER dimension):
+ * - at most {@link HISTORY_MAX_ENTRIES} undo entries, and
+ * - at most {@link HISTORY_BYTE_BUDGET} bytes across both stacks.
+ *
+ * Re-entrancy: while an entry's `undo`/`redo` runs, {@link History.isApplying}
+ * is `true`. The engine's paint/apply paths check it and skip recording, and
+ * `push` is a hard no-op during apply — so replaying an entry can never spawn a
+ * new entry (which would corrupt the stacks).
+ *
+ * Zero React, zero DOM, zero import-time side effects.
+ */
+
+/** Max number of undo entries retained before the oldest is evicted. */
+export const HISTORY_MAX_ENTRIES = 64;
+
+/** Max total bytes retained across the undo + redo stacks before the oldest is evicted (256 MB). */
+export const HISTORY_BYTE_BUDGET = 256 * 1024 * 1024;
+
+/** One reversible step. `bytes` is the (approximate) memory the entry pins, for the budget. */
+export interface HistoryEntry {
+  /** Human-readable label (e.g. "Brush stroke"). */
+  readonly label: string;
+  /** Approximate retained size in bytes (e.g. before+after ImageData byteLength). */
+  readonly bytes: number;
+  /**
+   * Opts into failure-atomic replay. When true, History moves this entry only
+   * after `undo`/`redo` returns successfully, so a preparation failure remains
+   * exactly retryable. The callback must leave its domain unchanged on throw.
+   *
+   * Legacy entries default to move-before-replay semantics: a throw is treated
+   * as post-application observer failure and the entry stays on its destination
+   * stack, preventing a retry from applying the same mutation twice.
+   */
+  readonly replayFailureAtomic?: boolean;
+  /** Reverts the change. Must not push new history entries. */
+  undo(): void;
+  /** Re-applies the change. Must not push new history entries. */
+  redo(): void;
+}
+
+/** Options for {@link createHistory}. */
+export interface CreateHistoryOptions {
+  /** Undo-entry cap (default {@link HISTORY_MAX_ENTRIES}). */
+  maxEntries?: number;
+  /** Total-byte cap across both stacks (default {@link HISTORY_BYTE_BUDGET}). */
+  byteBudget?: number;
+}
+
+/** The imperative history handle. */
+export interface History {
+  /** Records a new entry (clearing the redo stack) and enforces the budgets. No-op while applying. */
+  push(entry: HistoryEntry): void;
+  /**
+   * Replaces the most recent undo entry in place (adjusting the byte total),
+   * used to coalesce a rapid burst of same-target edits — e.g. arrow-key nudges —
+   * into a single reversible step. Falls back to {@link push} when the undo stack
+   * is empty. Clears the redo stack like `push`. No-op while applying.
+   */
+  amendLast(entry: HistoryEntry): void;
+  /** Reverts the most recent entry (moving it onto the redo stack). No-op when empty or already applying. */
+  undo(): void;
+  /** Re-applies the most recently undone entry (moving it back onto the undo stack). No-op when empty or applying. */
+  redo(): void;
+  /** True when there is at least one entry that can be undone. */
+  canUndo(): boolean;
+  /** True when there is at least one entry that can be redone. */
+  canRedo(): boolean;
+  /** True while an entry's `undo`/`redo` is executing (re-entrancy guard). */
+  isApplying(): boolean;
+  /** Drops both stacks (document replace / project switch / snapshot restore). */
+  clear(): void;
+  /** Current retained bytes across undo and redo stacks. */
+  byteSize(): number;
+  /** Evicts oldest entries until retained bytes are at or below `budgetBytes`. */
+  trimToBytes(budgetBytes: number): void;
+  /** Subscribes to any change in `canUndo`/`canRedo`. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+}
+
+/** Creates a bounded history stack. */
+export const createHistory = (opts: CreateHistoryOptions = {}): History => {
+  const maxEntries = Math.max(1, opts.maxEntries ?? HISTORY_MAX_ENTRIES);
+  const byteBudget = Math.max(0, opts.byteBudget ?? HISTORY_BYTE_BUDGET);
+
+  const undoStack: HistoryEntry[] = [];
+  const redoStack: HistoryEntry[] = [];
+  const listeners = new Set<() => void>();
+
+  // Running byte totals, kept in sync with the stacks so eviction is O(1) per drop.
+  let undoBytes = 0;
+  let redoBytes = 0;
+  // Re-entrancy flag: true while replaying an entry.
+  let applying = false;
+
+  const notify = (): void => {
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+        // Stack mutation is already complete. One faulty observer must neither
+        // report a false operation failure nor block later subscribers.
+      }
+    }
+  };
+
+  const clearRedo = (): void => {
+    if (redoStack.length === 0) {
+      return;
+    }
+    redoStack.length = 0;
+    redoBytes = 0;
+  };
+
+  /** Evicts the oldest undo entries until BOTH budgets are satisfied. */
+  const enforceBudgets = (): void => {
+    while (undoStack.length > maxEntries && undoStack.length > 0) {
+      const evicted = undoStack.shift();
+      if (evicted) {
+        undoBytes -= evicted.bytes;
+      }
+    }
+    while (undoBytes + redoBytes > byteBudget && undoStack.length > 0) {
+      const evicted = undoStack.shift();
+      if (evicted) {
+        undoBytes -= evicted.bytes;
+      }
+    }
+  };
+
+  const push = (entry: HistoryEntry): void => {
+    // Replaying an entry must never record a new one; drop it defensively.
+    if (applying) {
+      return;
+    }
+    clearRedo();
+    undoStack.push(entry);
+    undoBytes += entry.bytes;
+    enforceBudgets();
+    // A push always clears redo and grows undo, so both booleans may have moved
+    // (canUndo→true on the first push, canRedo→false when redo was non-empty).
+    notify();
+  };
+
+  const amendLast = (entry: HistoryEntry): void => {
+    if (applying) {
+      return;
+    }
+    if (undoStack.length === 0) {
+      push(entry);
+      return;
+    }
+    clearRedo();
+    const replaced = undoStack.pop();
+    if (replaced) {
+      undoBytes -= replaced.bytes;
+    }
+    undoStack.push(entry);
+    undoBytes += entry.bytes;
+    enforceBudgets();
+    notify();
+  };
+
+  const undo = (): void => {
+    if (applying || undoStack.length === 0) {
+      return;
+    }
+    const entry = undoStack.at(-1);
+    if (!entry) {
+      return;
+    }
+    if (!entry.replayFailureAtomic) {
+      // Legacy callbacks may mutate their domain before an observer throws.
+      // Move first so a retry cannot apply that mutation twice. If replay
+      // clears history, `clear()` owns the notification and the reset wins.
+      undoStack.pop();
+      undoBytes -= entry.bytes;
+      redoStack.push(entry);
+      redoBytes += entry.bytes;
+      let replayError: unknown;
+      let didThrow = false;
+      applying = true;
+      try {
+        entry.undo();
+      } catch (error) {
+        replayError = error;
+        didThrow = true;
+      } finally {
+        applying = false;
+      }
+      if (redoStack.at(-1) === entry) {
+        notify();
+      }
+      if (didThrow) {
+        // Preserve the callback's exact exception value for legacy callers.
+        // eslint-disable-next-line no-throw-literal
+        throw replayError;
+      }
+      return;
+    }
+    applying = true;
+    try {
+      entry.undo();
+    } finally {
+      applying = false;
+    }
+    // A replay callback may intentionally clear history (for example a
+    // synchronous document replacement). Let that reset win; never resurrect
+    // the entry onto the opposite stack after its original stack changed.
+    if (undoStack.at(-1) !== entry) {
+      return;
+    }
+    // Move the entry only after replay succeeds. A fallible callback (for
+    // example detached raster-cache preparation) may throw before applying
+    // anything; keeping the stacks and byte totals untouched makes retry exact.
+    undoStack.pop();
+    undoBytes -= entry.bytes;
+    redoStack.push(entry);
+    redoBytes += entry.bytes;
+    notify();
+  };
+
+  const redo = (): void => {
+    if (applying || redoStack.length === 0) {
+      return;
+    }
+    const entry = redoStack.at(-1);
+    if (!entry) {
+      return;
+    }
+    if (!entry.replayFailureAtomic) {
+      redoStack.pop();
+      redoBytes -= entry.bytes;
+      undoStack.push(entry);
+      undoBytes += entry.bytes;
+      let replayError: unknown;
+      let didThrow = false;
+      applying = true;
+      try {
+        entry.redo();
+      } catch (error) {
+        replayError = error;
+        didThrow = true;
+      } finally {
+        applying = false;
+      }
+      if (undoStack.at(-1) === entry) {
+        notify();
+      }
+      if (didThrow) {
+        // Preserve the callback's exact exception value for legacy callers.
+        // eslint-disable-next-line no-throw-literal
+        throw replayError;
+      }
+      return;
+    }
+    applying = true;
+    try {
+      entry.redo();
+    } finally {
+      applying = false;
+    }
+    if (redoStack.at(-1) !== entry) {
+      return;
+    }
+    redoStack.pop();
+    redoBytes -= entry.bytes;
+    undoStack.push(entry);
+    undoBytes += entry.bytes;
+    notify();
+  };
+
+  const clear = (): void => {
+    if (undoStack.length === 0 && redoStack.length === 0) {
+      return;
+    }
+    undoStack.length = 0;
+    redoStack.length = 0;
+    undoBytes = 0;
+    redoBytes = 0;
+    notify();
+  };
+
+  const trimToBytes = (budgetBytes: number): void => {
+    const budget = Math.max(0, budgetBytes);
+    let changed = false;
+    while (undoBytes + redoBytes > budget && undoStack.length > 0) {
+      const evicted = undoStack.shift();
+      if (evicted) {
+        undoBytes -= evicted.bytes;
+        changed = true;
+      }
+    }
+    while (undoBytes + redoBytes > budget && redoStack.length > 0) {
+      const evicted = redoStack.shift();
+      if (evicted) {
+        redoBytes -= evicted.bytes;
+        changed = true;
+      }
+    }
+    if (changed) {
+      notify();
+    }
+  };
+
+  return {
+    amendLast,
+    byteSize: () => undoBytes + redoBytes,
+    canRedo: () => redoStack.length > 0,
+    canUndo: () => undoStack.length > 0,
+    clear,
+    isApplying: () => applying,
+    push,
+    redo,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    trimToBytes,
+    undo,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/imagePatch.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/imagePatch.test.ts
new file mode 100644
index 00000000000..c112243e10c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/imagePatch.test.ts
@@ -0,0 +1,71 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createImagePatchEntry } from './imagePatch';
+
+/** A fake ImageData carrier sized to `w`x`h` (byteLength = w*h*4). */
+const fakeImageData = (w: number, h: number): ImageData =>
+  ({ colorSpace: 'srgb', data: new Uint8ClampedArray(w * h * 4), height: h, width: w }) as unknown as ImageData;
+
+const rect: Rect = { height: 3, width: 4, x: 5, y: 6 };
+
+describe('createImagePatchEntry', () => {
+  it('applies before on undo and after on redo with the patch rect', () => {
+    const before = fakeImageData(4, 3);
+    const after = fakeImageData(4, 3);
+    const apply = vi.fn();
+
+    const entry = createImagePatchEntry({ after, apply, before, label: 'Brush stroke', layerId: 'L1', rect });
+
+    entry.undo();
+    expect(apply).toHaveBeenNthCalledWith(1, 'L1', rect, before);
+    entry.redo();
+    expect(apply).toHaveBeenNthCalledWith(2, 'L1', rect, after);
+  });
+
+  it('accounts bytes as both buffers combined', () => {
+    const before = fakeImageData(4, 3); // 48 bytes
+    const after = fakeImageData(4, 3); // 48 bytes
+    const entry = createImagePatchEntry({
+      after,
+      apply: vi.fn(),
+      before,
+      label: 'Brush stroke',
+      layerId: 'L1',
+      rect,
+    });
+    expect(entry.bytes).toBe(before.data.byteLength + after.data.byteLength);
+    expect(entry.bytes).toBe(96);
+    expect(entry.label).toBe('Brush stroke');
+  });
+
+  it('snapshots the rect so later caller mutation does not shift the write', () => {
+    const before = fakeImageData(4, 3);
+    const after = fakeImageData(4, 3);
+    const apply = vi.fn();
+    const mutableRect: Rect = { height: 3, width: 4, x: 5, y: 6 };
+    const entry = createImagePatchEntry({
+      after,
+      apply,
+      before,
+      label: 'Brush stroke',
+      layerId: 'L1',
+      rect: mutableRect,
+    });
+    mutableRect.x = 999;
+    entry.undo();
+    expect(apply).toHaveBeenCalledWith('L1', { height: 3, width: 4, x: 5, y: 6 }, before);
+  });
+
+  it('throws when an ImageData dimension disagrees with the rect', () => {
+    const good = fakeImageData(4, 3);
+    const wrong = fakeImageData(2, 3);
+    expect(() =>
+      createImagePatchEntry({ after: wrong, apply: vi.fn(), before: good, label: 'x', layerId: 'L1', rect })
+    ).toThrow(/does not match rect/);
+    expect(() =>
+      createImagePatchEntry({ after: good, apply: vi.fn(), before: wrong, label: 'x', layerId: 'L1', rect })
+    ).toThrow(/before ImageData/);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/imagePatch.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/imagePatch.ts
new file mode 100644
index 00000000000..a7825d94118
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/imagePatch.ts
@@ -0,0 +1,73 @@
+/**
+ * A paint-edit history entry: a before/after pair of `ImageData` over a
+ * LAYER-LOCAL rect, reversed by putting the pixels back into the layer's cache
+ * surface. Layer-local coordinates are stable across cache growth/reallocation
+ * (the cache's content rect origin can shift as strokes grow it), so an old
+ * entry replays correctly no matter how the cache has been resized since.
+ *
+ * Painting (P2.1) commits a stroke as a {@link StrokeCommittedEvent} carrying the
+ * `dirtyRect` plus `beforeImageData`/`afterImageData` (both sized to that rect).
+ * This wraps that pair into a {@link HistoryEntry}: undo puts `before`, redo puts
+ * `after`. The actual pixel write is delegated to an engine-provided
+ * {@link ImagePatchApply} so this module stays free of the cache/backend/bitmap
+ * store — it just owns the before/after bookkeeping and the byte accounting.
+ *
+ * Byte cost = both buffers' `byteLength`, which is what the history budget bounds.
+ *
+ * Zero React, zero DOM (ImageData is a plain data carrier here), zero import-time
+ * side effects.
+ */
+
+import type { Rect } from '@workbench/canvas-engine/types';
+
+import type { HistoryEntry } from './history';
+
+/**
+ * Writes `pixels` into `layerId`'s cache at `rect`'s origin and propagates the
+ * edit (invalidate/version bump + mark the layer dirty for persistence). Provided
+ * by the engine; the entry never touches the cache or backend directly.
+ */
+export type ImagePatchApply = (layerId: string, rect: Rect, pixels: ImageData) => void;
+
+/** Options for {@link createImagePatchEntry}. */
+export interface CreateImagePatchEntryOptions {
+  layerId: string;
+  /** The painted region in LAYER-LOCAL space; its w/h must match the ImageData. */
+  rect: Rect;
+  /** Cache pixels within `rect` before the stroke. */
+  before: ImageData;
+  /** Cache pixels within `rect` after the stroke. */
+  after: ImageData;
+  /** Entry label (e.g. "Brush stroke" / "Eraser stroke"). */
+  label: string;
+  /** The engine's pixel-write bridge. */
+  apply: ImagePatchApply;
+}
+
+/** Throws if an ImageData's dimensions disagree with the patch rect. */
+const assertDims = (rect: Rect, image: ImageData, which: 'before' | 'after'): void => {
+  if (image.width !== rect.width || image.height !== rect.height) {
+    throw new Error(
+      `imagePatch: ${which} ImageData (${image.width}x${image.height}) does not match rect (${rect.width}x${rect.height})`
+    );
+  }
+};
+
+/** Creates a reversible paint-edit entry from a committed stroke's before/after pixels. */
+export const createImagePatchEntry = (opts: CreateImagePatchEntryOptions): HistoryEntry => {
+  const { after, apply, before, label, layerId, rect } = opts;
+  assertDims(rect, before, 'before');
+  assertDims(rect, after, 'after');
+
+  // Snapshot the rect so a later external mutation of the caller's object can't
+  // shift where undo/redo write.
+  const patchRect: Rect = { height: rect.height, width: rect.width, x: rect.x, y: rect.y };
+  const bytes = before.data.byteLength + after.data.byteLength;
+
+  return {
+    bytes,
+    label,
+    redo: () => apply(layerId, patchRect, after),
+    undo: () => apply(layerId, patchRect, before),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/layerSnapshot.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/layerSnapshot.test.ts
new file mode 100644
index 00000000000..39de4f79f49
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/layerSnapshot.test.ts
@@ -0,0 +1,99 @@
+import type { CanvasControlLayerContract } from '@workbench/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createLayerSnapshotEntry, type LayerPixelSnapshot } from './layerSnapshot';
+
+const fakeImageData = (width: number, height: number): ImageData =>
+  ({
+    colorSpace: 'srgb',
+    data: new Uint8ClampedArray(width * height * 4),
+    height,
+    width,
+  }) as unknown as ImageData;
+
+const layer = (source: CanvasControlLayerContract['source']): CanvasControlLayerContract => ({
+  adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: 'm', weight: 1 },
+  blendMode: 'normal',
+  id: 'control',
+  isEnabled: true,
+  isLocked: false,
+  name: 'Control',
+  opacity: 1,
+  source,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: true,
+});
+
+const snapshot = (which: 'before' | 'after'): LayerPixelSnapshot => ({
+  layer: layer(
+    which === 'before'
+      ? { image: { height: 2, imageName: 'before', width: 3 }, type: 'image' }
+      : { bitmap: null, offset: { x: 4, y: 5 }, type: 'paint' }
+  ),
+  pixels: fakeImageData(3, 2),
+  rect: { height: 2, width: 3, x: which === 'before' ? 0 : 4, y: which === 'before' ? 0 : 5 },
+});
+
+describe('createLayerSnapshotEntry', () => {
+  it('replays exact before/after snapshots and accounts for both buffers', () => {
+    const before = snapshot('before');
+    const after = snapshot('after');
+    const apply = vi.fn();
+    const entry = createLayerSnapshotEntry({ after, apply, before, label: 'Brush stroke' });
+
+    expect(entry.bytes).toBe(before.pixels!.data.byteLength + after.pixels!.data.byteLength + 256);
+    expect(entry.replayFailureAtomic).toBe(true);
+    entry.undo();
+    entry.redo();
+    expect(apply).toHaveBeenNthCalledWith(1, before);
+    expect(apply).toHaveBeenNthCalledWith(2, after);
+  });
+
+  it('rejects mismatched layer ids', () => {
+    const before = snapshot('before');
+    const after = { ...snapshot('after'), layer: { ...snapshot('after').layer, id: 'other' } };
+    expect(() => createLayerSnapshotEntry({ after, apply: vi.fn(), before, label: 'Edit' })).toThrow(
+      'layerSnapshot: before/after layer ids differ'
+    );
+  });
+
+  it('rejects pixel dimensions that do not match the rect', () => {
+    const before = { ...snapshot('before'), pixels: fakeImageData(1, 1) };
+    expect(() => createLayerSnapshotEntry({ after: snapshot('after'), apply: vi.fn(), before, label: 'Edit' })).toThrow(
+      'layerSnapshot: before pixels do not match rect'
+    );
+  });
+
+  it('accepts null pixels only for an empty cache extent', () => {
+    const before = { ...snapshot('before'), pixels: null, rect: { height: 0, width: 0, x: 0, y: 0 } };
+    expect(() =>
+      createLayerSnapshotEntry({ after: snapshot('after'), apply: vi.fn(), before, label: 'First stroke' })
+    ).not.toThrow();
+    expect(() =>
+      createLayerSnapshotEntry({
+        after: snapshot('after'),
+        apply: vi.fn(),
+        before: { ...snapshot('before'), pixels: null },
+        label: 'Edit',
+      })
+    ).toThrow('layerSnapshot: before non-empty rect requires pixels');
+  });
+
+  it('protects contract and rect snapshots from later caller mutation', () => {
+    const before = snapshot('before');
+    const after = snapshot('after');
+    const apply = vi.fn();
+    const entry = createLayerSnapshotEntry({ after, apply, before, label: 'Edit' });
+    before.layer.name = 'mutated';
+    before.rect.x = 999;
+    entry.undo();
+    expect(apply).toHaveBeenCalledWith(
+      expect.objectContaining({
+        layer: expect.objectContaining({ name: 'Control' }),
+        rect: expect.objectContaining({ x: 0 }),
+      })
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/history/layerSnapshot.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/layerSnapshot.ts
new file mode 100644
index 00000000000..7a407444a40
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/history/layerSnapshot.ts
@@ -0,0 +1,65 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasControlLayerContract } from '@workbench/types';
+
+import type { HistoryEntry } from './history';
+
+export interface LayerPixelSnapshot {
+  layer: CanvasControlLayerContract;
+  rect: Rect;
+  /** Null represents the exact pixel state of a zero-width or zero-height cache. */
+  pixels: ImageData | null;
+}
+
+export type LayerPixelSnapshotApply = (snapshot: LayerPixelSnapshot) => void;
+
+export interface CreateLayerSnapshotEntryOptions {
+  before: LayerPixelSnapshot;
+  after: LayerPixelSnapshot;
+  label: string;
+  apply: LayerPixelSnapshotApply;
+}
+
+const assertSnapshot = (snapshot: LayerPixelSnapshot, which: 'before' | 'after'): void => {
+  if (snapshot.rect.width === 0 || snapshot.rect.height === 0) {
+    if (snapshot.pixels !== null) {
+      throw new Error(`layerSnapshot: ${which} empty rect requires null pixels`);
+    }
+    return;
+  }
+  if (snapshot.pixels === null) {
+    throw new Error(`layerSnapshot: ${which} non-empty rect requires pixels`);
+  }
+  if (snapshot.pixels.width !== snapshot.rect.width || snapshot.pixels.height !== snapshot.rect.height) {
+    throw new Error(`layerSnapshot: ${which} pixels do not match rect`);
+  }
+};
+
+export const createLayerSnapshotEntry = ({
+  after,
+  apply,
+  before,
+  label,
+}: CreateLayerSnapshotEntryOptions): HistoryEntry => {
+  if (before.layer.id !== after.layer.id) {
+    throw new Error('layerSnapshot: before/after layer ids differ');
+  }
+  assertSnapshot(before, 'before');
+  assertSnapshot(after, 'after');
+  const beforeSnapshot: LayerPixelSnapshot = {
+    layer: structuredClone(before.layer),
+    pixels: before.pixels,
+    rect: { ...before.rect },
+  };
+  const afterSnapshot: LayerPixelSnapshot = {
+    layer: structuredClone(after.layer),
+    pixels: after.pixels,
+    rect: { ...after.rect },
+  };
+  return {
+    bytes: (before.pixels?.data.byteLength ?? 0) + (after.pixels?.data.byteLength ?? 0) + 256,
+    label,
+    redo: () => apply(afterSnapshot),
+    replayFailureAtomic: true,
+    undo: () => apply(beforeSnapshot),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/importBoundaries.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/importBoundaries.test.ts
new file mode 100644
index 00000000000..80ce2d192b4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/importBoundaries.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+const forbiddenPrefixes = [
+  '@workbench/backend',
+  '@workbench/canvas-operations',
+  '@workbench/generation',
+  '@workbench/widgets',
+];
+
+const modules = import.meta.glob('./**/*.ts', { eager: true, import: 'default', query: '?raw' });
+
+const violations = (): string[] => {
+  const result: string[] = [];
+  for (const [file, loaded] of Object.entries(modules)) {
+    if (file.endsWith('.test.ts') || typeof loaded !== 'string') {
+      continue;
+    }
+    const source = loaded;
+    for (const match of source.matchAll(/from\s+['"]([^'"]+)['"]/g)) {
+      const specifier = match[1];
+      if (specifier && forbiddenPrefixes.some((prefix) => specifier.startsWith(prefix))) {
+        result.push(`${file.slice(2)} -> ${specifier}`);
+      }
+    }
+  }
+  return result.sort();
+};
+
+describe('canvas-engine import boundary', () => {
+  it('does not import application workflows, widgets, generation graphs, or backend networking', () => {
+    expect(violations()).toEqual([]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/input/pointerPipeline.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/pointerPipeline.test.ts
new file mode 100644
index 00000000000..d6947d58d86
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/pointerPipeline.test.ts
@@ -0,0 +1,510 @@
+import type { PointerPipelineDeps } from '@workbench/canvas-engine/input/pointerPipeline';
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput, ToolId } from '@workbench/canvas-engine/types';
+
+import { createPointerPipeline } from '@workbench/canvas-engine/input/pointerPipeline';
+import { createViewport } from '@workbench/canvas-engine/viewport';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+// ---- Fakes -----------------------------------------------------------------
+
+interface FakePointerInit {
+  button?: number;
+  buttons?: number;
+  clientX?: number;
+  clientY?: number;
+  pointerId?: number;
+  pointerType?: string;
+  pressure?: number;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  coalesced?: FakePointerInit[];
+}
+
+const makePointerEvent = (init: FakePointerInit = {}): PointerEvent => {
+  const self: Record<string, unknown> = {
+    altKey: init.altKey ?? false,
+    button: init.button ?? 0,
+    buttons: init.buttons ?? 1,
+    clientX: init.clientX ?? 0,
+    clientY: init.clientY ?? 0,
+    ctrlKey: init.ctrlKey ?? false,
+    metaKey: false,
+    pointerId: init.pointerId ?? 1,
+    pointerType: init.pointerType ?? 'mouse',
+    preventDefault: vi.fn(),
+    pressure: init.pressure ?? 0,
+    shiftKey: false,
+    timeStamp: 0,
+  };
+  self.getCoalescedEvents = () => (init.coalesced ?? []).map(makePointerEvent);
+  return self as unknown as PointerEvent;
+};
+
+const makeKeyEvent = (init: {
+  code?: string;
+  key?: string;
+  repeat?: boolean;
+  shiftKey?: boolean;
+  target?: unknown;
+}): KeyboardEvent =>
+  ({
+    code: init.code ?? '',
+    key: init.key ?? '',
+    preventDefault: vi.fn(),
+    repeat: init.repeat ?? false,
+    shiftKey: init.shiftKey ?? false,
+    target: init.target ?? null,
+  }) as unknown as KeyboardEvent;
+
+const createHarness = (
+  opts: {
+    tools?: ToolId[];
+    handleEscape?: (o: { gestureWasActive: boolean }) => void;
+    maybeCommitModalSession?: () => boolean;
+  } = {}
+) => {
+  const registered = new Set<ToolId>(opts.tools ?? ['view', 'brush']);
+  const tool: Tool & {
+    downs: PointerInput[];
+    moves: { input: PointerInput; batch: readonly PointerInput[] }[];
+    ups: PointerInput[];
+    cancels: number;
+  } = {
+    cancels: 0,
+    downs: [],
+    id: 'brush',
+    moves: [],
+    onPointerCancel: () => {
+      tool.cancels += 1;
+    },
+    onPointerDown: (_ctx, input) => {
+      tool.downs.push(input);
+    },
+    onPointerMove: (_ctx, input, batch) => {
+      tool.moves.push({ batch, input });
+    },
+    onPointerUp: (_ctx, input) => {
+      tool.ups.push(input);
+    },
+    ups: [],
+  };
+
+  const captures: number[] = [];
+  const releases: number[] = [];
+  const element = {
+    getBoundingClientRect: () => ({ left: 0, top: 0 }) as DOMRect,
+    releasePointerCapture: (id: number) => releases.push(id),
+    setPointerCapture: (id: number) => captures.push(id),
+  } as unknown as HTMLElement;
+
+  let activeToolId: ToolId = 'brush';
+  const setTool = vi.fn((id: ToolId) => {
+    activeToolId = id;
+  });
+  const ctx = {} as ToolContext;
+
+  const deps: PointerPipelineDeps = {
+    getActiveTool: () => tool,
+    getActiveToolId: () => activeToolId,
+    getInputElement: () => element,
+    getToolContext: () => ctx,
+    handleEscape: opts.handleEscape,
+    hasTool: (id) => registered.has(id),
+    maybeCommitModalSession: opts.maybeCommitModalSession,
+    setTool,
+    updateCursor: vi.fn(),
+    viewport: createViewport(),
+  };
+
+  return { captures, deps, pipeline: createPointerPipeline(deps), releases, setTool, tool };
+};
+
+// ---- Tests -----------------------------------------------------------------
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('pointer pipeline: pressure + capture', () => {
+  it('captures the pointer on primary down and defaults mouse pressure to 0.5', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 7, pointerType: 'mouse', pressure: 0 }));
+
+    expect(h.captures).toEqual([7]);
+    expect(h.tool.downs).toHaveLength(1);
+    expect(h.tool.downs[0]!.pressure).toBe(0.5);
+  });
+
+  it('preserves reported pen pressure', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerType: 'pen', pressure: 0.73 }));
+    expect(h.tool.downs[0]!.pressure).toBeCloseTo(0.73);
+    expect(h.tool.downs[0]!.pointerType).toBe('pen');
+  });
+
+  it('releases capture on pointer up and forwards the up sample', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 3 }));
+    h.pipeline.onPointerUp(makePointerEvent({ buttons: 0, pointerId: 3 }));
+    expect(h.releases).toEqual([3]);
+    expect(h.tool.ups).toHaveLength(1);
+  });
+});
+
+describe('pointer pipeline: coalesced batching', () => {
+  it('expands coalesced events into a batch whose last element is the primary sample', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({}));
+    h.pipeline.onPointerMove(
+      makePointerEvent({
+        clientX: 30,
+        coalesced: [
+          { clientX: 10, clientY: 10 },
+          { clientX: 20, clientY: 15 },
+          { clientX: 30, clientY: 20 },
+        ],
+      })
+    );
+
+    expect(h.tool.moves).toHaveLength(1);
+    const { batch, input } = h.tool.moves[0]!;
+    expect(batch).toHaveLength(3);
+    expect(input).toBe(batch[2]);
+    expect(batch[0]!.screenPoint).toEqual({ x: 10, y: 10 });
+  });
+
+  it('falls back to a single-sample batch when no coalesced events exist', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({}));
+    h.pipeline.onPointerMove(makePointerEvent({ clientX: 42, coalesced: [] }));
+    expect(h.tool.moves[0]!.batch).toHaveLength(1);
+    expect(h.tool.moves[0]!.input.screenPoint.x).toBe(42);
+  });
+});
+
+describe('pointer pipeline: modal (text-edit) session commit on pointerdown', () => {
+  it('commits and swallows a primary press when a modal session is open (no capture/gesture/tool routing)', () => {
+    const maybeCommitModalSession = vi.fn(() => true);
+    const h = createHarness({ maybeCommitModalSession });
+    const event = makePointerEvent({ pointerId: 5 });
+
+    h.pipeline.onPointerDown(event);
+
+    expect(maybeCommitModalSession).toHaveBeenCalledTimes(1);
+    expect(h.captures).toEqual([]); // no pointer capture
+    expect(h.tool.downs).toHaveLength(0); // not routed to the active tool
+    expect(h.pipeline.isGestureActive()).toBe(false); // ran before the gesture flag is set
+    expect(event.preventDefault).toHaveBeenCalled();
+  });
+
+  it('starts a normal gesture when no modal session is open (returns false)', () => {
+    const maybeCommitModalSession = vi.fn(() => false);
+    const h = createHarness({ maybeCommitModalSession });
+
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 6 }));
+
+    expect(maybeCommitModalSession).toHaveBeenCalledTimes(1);
+    expect(h.tool.downs).toHaveLength(1);
+    expect(h.pipeline.isGestureActive()).toBe(true);
+    expect(h.captures).toEqual([6]);
+  });
+});
+
+describe('pointer pipeline: Escape priority (handleEscape)', () => {
+  it('runs handleEscape with gestureWasActive=false when Escape is pressed idle', () => {
+    const handleEscape = vi.fn();
+    const h = createHarness({ handleEscape });
+    h.pipeline.onKeyDown(makeKeyEvent({ key: 'Escape' }));
+    expect(handleEscape).toHaveBeenCalledTimes(1);
+    expect(handleEscape).toHaveBeenCalledWith({ gestureWasActive: false });
+  });
+
+  it('cancels the active gesture AND flags it to handleEscape (gestureWasActive=true)', () => {
+    const handleEscape = vi.fn();
+    const h = createHarness({ handleEscape });
+    h.pipeline.onPointerDown(makePointerEvent({}));
+    h.pipeline.onKeyDown(makeKeyEvent({ key: 'Escape' }));
+    expect(h.tool.cancels).toBe(1);
+    expect(handleEscape).toHaveBeenCalledWith({ gestureWasActive: true });
+  });
+
+  it('does not run handleEscape when Escape targets an editable field', () => {
+    const handleEscape = vi.fn();
+    const h = createHarness({ handleEscape });
+    h.pipeline.onKeyDown(makeKeyEvent({ key: 'Escape', target: { tagName: 'INPUT' } }));
+    expect(handleEscape).not.toHaveBeenCalled();
+  });
+});
+
+describe('pointer pipeline: gesture cancel + secondary buttons', () => {
+  it('routes pointercancel to the tool and releases capture', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 5 }));
+    h.pipeline.onPointerCancel(makePointerEvent({ pointerId: 5 }));
+    expect(h.tool.cancels).toBe(1);
+    expect(h.releases).toEqual([5]);
+  });
+
+  it('cancels the active gesture on Escape', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 9 }));
+    h.pipeline.onKeyDown(makeKeyEvent({ key: 'Escape' }));
+    expect(h.tool.cancels).toBe(1);
+    // A subsequent up is ignored (the gesture already ended).
+    h.pipeline.onPointerUp(makePointerEvent({ buttons: 0, pointerId: 9 }));
+    expect(h.tool.ups).toHaveLength(0);
+  });
+
+  it('ignores secondary-button presses during an active gesture', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ button: 0 }));
+    h.pipeline.onPointerDown(makePointerEvent({ button: 2, buttons: 3 }));
+    expect(h.tool.downs).toHaveLength(1);
+  });
+
+  it('ignores a standalone secondary-button press', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ button: 2, buttons: 2 }));
+    expect(h.tool.downs).toHaveLength(0);
+    expect(h.captures).toHaveLength(0);
+  });
+});
+
+describe('pointer pipeline: middle-mouse pan', () => {
+  it('pans the viewport on middle drag without routing to the tool', () => {
+    const h = createHarness();
+    const panBy = vi.spyOn(h.deps.viewport, 'panBy');
+    h.pipeline.onPointerDown(makePointerEvent({ button: 1, buttons: 4, clientX: 0 }));
+    h.pipeline.onPointerMove(makePointerEvent({ buttons: 4, clientX: 25 }));
+    expect(panBy).toHaveBeenCalledWith({ x: 25, y: 0 });
+    expect(h.tool.moves).toHaveLength(0);
+  });
+});
+
+describe('pointer pipeline: multi-pointer isolation during an active gesture', () => {
+  it('ignores move events from a second pointer while the first pointer is gesturing', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 1 }));
+    h.pipeline.onPointerMove(makePointerEvent({ pointerId: 2, clientX: 99 }));
+    expect(h.tool.moves).toHaveLength(0);
+    h.pipeline.onPointerMove(makePointerEvent({ pointerId: 1, clientX: 10 }));
+    expect(h.tool.moves).toHaveLength(1);
+  });
+
+  it('ignores a second pointer up but ends the gesture on the first pointer up', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 1 }));
+    h.pipeline.onPointerUp(makePointerEvent({ buttons: 0, pointerId: 2 }));
+    expect(h.tool.ups).toHaveLength(0);
+    expect(h.releases).toHaveLength(0);
+    h.pipeline.onPointerUp(makePointerEvent({ buttons: 0, pointerId: 1 }));
+    expect(h.tool.ups).toHaveLength(1);
+    expect(h.releases).toEqual([1]);
+  });
+
+  it('ignores cancel events from a second pointer during an active gesture', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 1 }));
+    h.pipeline.onPointerCancel(makePointerEvent({ pointerId: 2 }));
+    expect(h.tool.cancels).toBe(0);
+    h.pipeline.onPointerCancel(makePointerEvent({ pointerId: 1 }));
+    expect(h.tool.cancels).toBe(1);
+  });
+
+  it('ignores a second pointerdown while a gesture is active', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 1 }));
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 2 }));
+    expect(h.tool.downs).toHaveLength(1);
+    expect(h.captures).toEqual([1]);
+  });
+});
+
+describe('pointer pipeline: gesture-active state', () => {
+  it('reports the primary-button gesture from down to up', () => {
+    const h = createHarness();
+    expect(h.pipeline.isGestureActive()).toBe(false);
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 1 }));
+    expect(h.pipeline.isGestureActive()).toBe(true);
+    h.pipeline.onPointerMove(makePointerEvent({ pointerId: 1, clientX: 10 }));
+    expect(h.pipeline.isGestureActive()).toBe(true);
+    h.pipeline.onPointerUp(makePointerEvent({ buttons: 0, pointerId: 1 }));
+    expect(h.pipeline.isGestureActive()).toBe(false);
+  });
+
+  it('clears on pointercancel, Escape, and reset', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 1 }));
+    h.pipeline.onPointerCancel(makePointerEvent({ pointerId: 1 }));
+    expect(h.pipeline.isGestureActive()).toBe(false);
+
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 2 }));
+    h.pipeline.onKeyDown(makeKeyEvent({ key: 'Escape' }));
+    expect(h.pipeline.isGestureActive()).toBe(false);
+
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 3 }));
+    h.pipeline.reset();
+    expect(h.pipeline.isGestureActive()).toBe(false);
+  });
+
+  it('does not report a middle-mouse pan as a gesture', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ button: 1, buttons: 4 }));
+    expect(h.pipeline.isGestureActive()).toBe(false);
+  });
+});
+
+describe('pointer pipeline: cancelActiveGesture + reset run onPointerCancel', () => {
+  it('cancelActiveGesture releases capture and runs the tool cancel once; a no-op with no gesture', () => {
+    const h = createHarness();
+    // No gesture: a no-op (the tool cancel must not fire).
+    h.pipeline.cancelActiveGesture();
+    expect(h.tool.cancels).toBe(0);
+
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 5 }));
+    h.pipeline.cancelActiveGesture();
+    expect(h.tool.cancels).toBe(1);
+    expect(h.releases).toContain(5);
+    expect(h.pipeline.isGestureActive()).toBe(false);
+
+    // A second call is a no-op — the gesture is already cancelled.
+    h.pipeline.cancelActiveGesture();
+    expect(h.tool.cancels).toBe(1);
+  });
+
+  it('reset cancels an in-flight gesture (runs onPointerCancel + releases capture), unlike a bare flag clear', () => {
+    const h = createHarness();
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 9 }));
+    expect(h.pipeline.isGestureActive()).toBe(true);
+
+    h.pipeline.reset();
+    expect(h.tool.cancels).toBe(1);
+    expect(h.releases).toContain(9);
+    expect(h.pipeline.isGestureActive()).toBe(false);
+  });
+});
+
+describe('pointer pipeline: temporary modifier tools', () => {
+  it('holds view while space is down and restores the prior tool on release', () => {
+    const h = createHarness();
+    h.pipeline.onPointerEnter();
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'Space' }));
+    // Flagged `temporary` so a session-bearing tool (transform) can tell this
+    // apart from a real switch and keep its session alive across the hold.
+    expect(h.setTool).toHaveBeenLastCalledWith('view', { temporary: true });
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'Space' }));
+    expect(h.setTool).toHaveBeenLastCalledWith('brush', { temporary: true });
+  });
+
+  it('replaces a matching pending restore target when its session closes', () => {
+    const h = createHarness({ tools: ['view', 'brush', 'sam'] });
+    h.deps.setTool('sam');
+    h.pipeline.onPointerEnter();
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'Space' }));
+    expect(h.setTool).toHaveBeenLastCalledWith('view', { temporary: true });
+
+    h.pipeline.replaceTemporaryRestoreTool('sam', 'view');
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'Space' }));
+
+    expect(h.setTool).toHaveBeenLastCalledWith('view', { temporary: true });
+    expect(h.setTool).not.toHaveBeenCalledWith('sam', { temporary: true });
+  });
+
+  it('does not replace an unrelated temporary restore target', () => {
+    const h = createHarness({ tools: ['view', 'brush', 'sam'] });
+    h.pipeline.onPointerEnter();
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'Space' }));
+
+    h.pipeline.replaceTemporaryRestoreTool('sam', 'view');
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'Space' }));
+
+    expect(h.setTool).toHaveBeenLastCalledWith('brush', { temporary: true });
+  });
+
+  it('does not switch on space when the pointer is not over the canvas', () => {
+    const h = createHarness();
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'Space' }));
+    expect(h.setTool).not.toHaveBeenCalled();
+  });
+
+  it('alt-hold is a no-op switch when colorPicker is not registered', () => {
+    const h = createHarness({ tools: ['view', 'brush'] });
+    h.pipeline.onPointerEnter();
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'AltLeft' }));
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'AltLeft' }));
+    expect(h.setTool).not.toHaveBeenCalled();
+  });
+
+  it('alt-hold switches to colorPicker when registered and restores on release', () => {
+    const h = createHarness({ tools: ['view', 'brush', 'colorPicker'] });
+    h.pipeline.onPointerEnter();
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'AltLeft' }));
+    expect(h.setTool).toHaveBeenLastCalledWith('colorPicker', { temporary: true });
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'AltLeft' }));
+    expect(h.setTool).toHaveBeenLastCalledWith('brush', { temporary: true });
+  });
+
+  it('quick-tapping C sticky-selects the bbox tool after the temporary preview switch', () => {
+    const h = createHarness({ tools: ['view', 'brush', 'bbox'] });
+    h.pipeline.onPointerEnter();
+
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'KeyC', key: 'c' }));
+    expect(h.setTool).toHaveBeenLastCalledWith('bbox', { temporary: true });
+
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'KeyC', key: 'c' }));
+    expect(h.setTool).toHaveBeenLastCalledWith('bbox');
+    expect(h.setTool.mock.calls.slice(-2)).toEqual([['brush', { temporary: true }], ['bbox']]);
+  });
+
+  it('leaves Shift+C to the registered clear-mask hotkey', () => {
+    const h = createHarness({ tools: ['view', 'brush', 'bbox'] });
+    h.pipeline.onPointerEnter();
+
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'KeyC', key: 'C', shiftKey: true }));
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'KeyC', key: 'C', shiftKey: true }));
+
+    expect(h.setTool).not.toHaveBeenCalled();
+  });
+
+  it('holding C restores the prior tool on release without sticky-selecting bbox', () => {
+    vi.useFakeTimers();
+    const h = createHarness({ tools: ['view', 'brush', 'bbox'] });
+    h.pipeline.onPointerEnter();
+
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'KeyC', key: 'c' }));
+    vi.runAllTimers();
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'KeyC', key: 'c' }));
+
+    expect(h.setTool).toHaveBeenLastCalledWith('brush', { temporary: true });
+  });
+
+  it('keeps temporary bbox active until pointerup when C is released mid-gesture', () => {
+    const h = createHarness({ tools: ['view', 'brush', 'bbox'] });
+    h.pipeline.onPointerEnter();
+
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'KeyC', key: 'c' }));
+    h.pipeline.onPointerDown(makePointerEvent({ pointerId: 11 }));
+    h.pipeline.onKeyUp(makeKeyEvent({ code: 'KeyC', key: 'c' }));
+    expect(h.setTool).toHaveBeenLastCalledWith('bbox', { temporary: true });
+
+    h.pipeline.onPointerUp(makePointerEvent({ buttons: 0, pointerId: 11 }));
+    expect(h.setTool).toHaveBeenLastCalledWith('brush', { temporary: true });
+  });
+
+  it('ignores space/alt holds when the key event targets an editable element', () => {
+    const h = createHarness({ tools: ['view', 'brush', 'colorPicker'] });
+    h.pipeline.onPointerEnter();
+
+    // Typing space/alt in an input, textarea, or contenteditable belongs to that
+    // field, not the canvas — the temp-tool hold must not fire.
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'Space', target: { tagName: 'INPUT' } }));
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'Space', target: { tagName: 'textarea' } }));
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'AltLeft', target: { isContentEditable: true } }));
+    expect(h.setTool).not.toHaveBeenCalled();
+
+    // A non-editable target (e.g. the canvas) still triggers the hold.
+    h.pipeline.onKeyDown(makeKeyEvent({ code: 'Space', target: { tagName: 'CANVAS' } }));
+    expect(h.setTool).toHaveBeenLastCalledWith('view', { temporary: true });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/input/pointerPipeline.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/pointerPipeline.ts
new file mode 100644
index 00000000000..322b974aea5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/pointerPipeline.ts
@@ -0,0 +1,458 @@
+/**
+ * The pointer pipeline: normalizes raw DOM pointer/key events into the engine's
+ * {@link PointerInput} vocabulary and routes them to the active tool.
+ *
+ * Responsibilities lifted out of the engine so `engine.ts` stays lean:
+ * - Pointer capture on down; `getCoalescedEvents()` batching on move (so fast
+ *   strokes keep every intermediate sample); mouse pressure defaulted to 0.5.
+ * - Middle-mouse pan (engine-level, tool-independent).
+ * - Modifier/key-hold temporary tools: space → view, alt → colorPicker, hold C
+ *   → bbox (quick-tap C still sticky-selects bbox). The prior tool is restored
+ *   on release. Temp switches are suppressed mid-gesture, and are
+ *   flagged `{ temporary: true }` on `setTool` so a session-bearing tool
+ *   (transform) can tell them apart from a real switch and keep its session
+ *   alive across the hold.
+ * - Gesture cancellation: pointercancel and Esc route to the tool's
+ *   `onPointerCancel`; secondary/extra buttons are ignored during a gesture.
+ *
+ * The pipeline reaches the DOM only through the injected `getInputElement`
+ * (for pointer capture / element rect) and the events passed to its handlers, so
+ * it is fully driveable by a fake harness in node tests. Zero React, zero
+ * import-time side effects.
+ */
+
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput, ToolId, Vec2 } from '@workbench/canvas-engine/types';
+import type { Viewport } from '@workbench/canvas-engine/viewport';
+
+/** The tool id temporarily activated while alt is held (ships in Task P2.4). */
+const ALT_TEMP_TOOL: ToolId = 'colorPicker';
+/** The tool id temporarily activated while space is held. */
+const SPACE_TEMP_TOOL: ToolId = 'view';
+/** The tool id temporarily activated while the bbox key is held. */
+const BBOX_TEMP_TOOL: ToolId = 'bbox';
+/** Key-up before this threshold keeps the bbox tool selected, preserving the old tap behavior. */
+const BBOX_QUICK_TAP_MS = 180;
+
+/** Dependencies injected by the engine. */
+export interface PointerPipelineDeps {
+  viewport: Viewport;
+  /** The element that owns pointer capture and defines the coordinate rect. */
+  getInputElement(): (HTMLElement & Partial<Pick<HTMLElement, 'setPointerCapture' | 'releasePointerCapture'>>) | null;
+  getActiveTool(): Tool | undefined;
+  getActiveToolId(): ToolId;
+  getToolContext(): ToolContext;
+  /**
+   * Switches the active tool. `opts.temporary` marks a modifier-hold switch
+   * (and its matching restore) so a session-bearing tool's `onActivate`/
+   * `onDeactivate` can preserve its session instead of tearing it down — see
+   * {@link beginTempTool} / {@link endTempTool}.
+   */
+  setTool(id: ToolId, opts?: { temporary?: boolean }): void;
+  hasTool(id: ToolId): boolean;
+  updateCursor(): void;
+  /**
+   * The engine's Escape priority, run AFTER the in-flight gesture is cancelled
+   * (and skipped in editable fields): cancel a transform session, else deselect.
+   * `gestureWasActive` tells it a drag just consumed this Escape, so it should
+   * cancel a session (session teardown is wanted mid-drag, matching the prior
+   * behavior) but NOT also deselect. Optional so minimal harnesses can omit it.
+   * See `engine.ts` `handleEscape`.
+   */
+  handleEscape?(opts: { gestureWasActive: boolean }): void;
+  /**
+   * Called on a primary-button pointerdown BEFORE any gesture starts. Returns
+   * `true` if the engine consumed the press to commit an open modal session (a
+   * text-edit session), in which case the pipeline swallows the press entirely —
+   * no capture, no gesture, no tool routing — because the click's sole job was to
+   * close the session (the next press then starts a fresh interaction). Running
+   * before `gestureActive` is set is what lets the commit through the engine's
+   * mid-gesture guard. Optional so minimal harnesses can omit it.
+   */
+  maybeCommitModalSession?(): boolean;
+}
+
+/** The pipeline handle: DOM handlers plus lifecycle reset. */
+export interface PointerPipeline {
+  onPointerDown(event: PointerEvent): void;
+  onPointerMove(event: PointerEvent): void;
+  onPointerUp(event: PointerEvent): void;
+  onPointerCancel(event: PointerEvent): void;
+  onPointerEnter(): void;
+  onPointerLeave(): void;
+  onKeyDown(event: KeyboardEvent): void;
+  onKeyUp(event: KeyboardEvent): void;
+  /**
+   * True while a primary-button paint/drag gesture is mid-stroke (pointer down,
+   * not yet up/cancel). The engine consults this to no-op undo/redo during a
+   * live stroke, so a mid-gesture mod+z can't inject pixels under the session.
+   */
+  isGestureActive(): boolean;
+  /**
+   * Cancels an in-flight primary-button gesture the same way Esc/pointercancel
+   * do: releases pointer capture, runs the active tool's `onPointerCancel` (so it
+   * drops its own transient state), and refreshes the cursor. A no-op when no
+   * gesture is active. The engine calls this on a wholesale document replacement
+   * so a mid-drag swap can't commit against the outgoing document on pointer-up.
+   */
+  cancelActiveGesture(): void;
+  /** Replaces a matching tool id that a currently-held temporary tool would restore on release. */
+  replaceTemporaryRestoreTool(current: ToolId, replacement: ToolId): void;
+  /** Clears hover/gesture/temp-tool state, cancelling any in-flight gesture (called on detach/blur). */
+  reset(): void;
+}
+
+const toPointerType = (type: string): PointerInput['pointerType'] =>
+  type === 'pen' ? 'pen' : type === 'touch' ? 'touch' : 'mouse';
+
+const isAltKey = (event: KeyboardEvent): boolean => event.code === 'AltLeft' || event.code === 'AltRight';
+const isBboxKey = (event: KeyboardEvent): boolean =>
+  event.code === 'KeyC' && !event.altKey && !event.ctrlKey && !event.metaKey && !event.shiftKey;
+
+/**
+ * True when the key event targets an editable element (text input, textarea, or
+ * a contenteditable node). The space/alt temp-tool holds are window-level, so
+ * without this guard typing a space in a rename field would hijack the canvas
+ * view tool. Duck-typed on `tagName`/`isContentEditable` so it stays node-safe
+ * (no `instanceof HTMLElement`, which throws where those globals are absent).
+ */
+const isEditableTarget = (target: EventTarget | null): boolean => {
+  const el = target as { tagName?: unknown; isContentEditable?: unknown } | null;
+  if (!el) {
+    return false;
+  }
+  const tagName = typeof el.tagName === 'string' ? el.tagName.toUpperCase() : '';
+  return tagName === 'INPUT' || tagName === 'TEXTAREA' || el.isContentEditable === true;
+};
+
+/** Creates a pointer pipeline bound to the engine's injected deps. */
+export const createPointerPipeline = (deps: PointerPipelineDeps): PointerPipeline => {
+  let hovered = false;
+  // Primary-button paint/drag gesture in progress.
+  let gestureActive = false;
+  let activePointerId: number | null = null;
+  // Middle-mouse pan.
+  let middlePanning = false;
+  let middleLast: Vec2 | null = null;
+  // Temporary modifier-hold tool.
+  let tempHold: 'space' | 'alt' | 'bbox' | null = null;
+  let priorToolId: ToolId = deps.getActiveToolId();
+  let tempSwitched = false;
+  let restoreTempAfterGesture = false;
+  let bboxQuickTap = false;
+  let bboxTapTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const buildPointerInput = (event: PointerEvent): PointerInput => {
+    const el = deps.getInputElement();
+    const rect = el?.getBoundingClientRect() ?? ({ left: 0, top: 0 } as DOMRect);
+    const screenPoint: Vec2 = { x: event.clientX - rect.left, y: event.clientY - rect.top };
+    return {
+      buttons: event.buttons,
+      documentPoint: deps.viewport.screenToDocument(screenPoint),
+      modifiers: { alt: event.altKey, ctrl: event.ctrlKey, meta: event.metaKey, shift: event.shiftKey },
+      pointerType: toPointerType(event.pointerType),
+      pressure: event.pressure > 0 ? event.pressure : 0.5,
+      screenPoint,
+      timeStamp: event.timeStamp,
+    };
+  };
+
+  const buildBatch = (event: PointerEvent): PointerInput[] => {
+    const coalesced = event.getCoalescedEvents?.();
+    if (coalesced && coalesced.length > 0) {
+      return coalesced.map(buildPointerInput);
+    }
+    return [buildPointerInput(event)];
+  };
+
+  const releaseCapture = (pointerId: number): void => {
+    deps.getInputElement()?.releasePointerCapture?.(pointerId);
+  };
+
+  const cancelGesture = (): void => {
+    if (!gestureActive) {
+      return;
+    }
+    gestureActive = false;
+    if (activePointerId !== null) {
+      releaseCapture(activePointerId);
+      activePointerId = null;
+    }
+    deps.getActiveTool()?.onPointerCancel?.(deps.getToolContext());
+    deps.updateCursor();
+    if (restoreTempAfterGesture && tempHold) {
+      endTempTool();
+    }
+  };
+
+  const clearBboxTapTimer = (): void => {
+    if (bboxTapTimer !== null) {
+      clearTimeout(bboxTapTimer);
+      bboxTapTimer = null;
+    }
+  };
+
+  const markBboxHold = (): void => {
+    if (tempHold !== 'bbox') {
+      return;
+    }
+    bboxQuickTap = false;
+    clearBboxTapTimer();
+  };
+
+  const beginTempTool = (hold: 'space' | 'alt', toolId: ToolId): void => {
+    if (tempHold || gestureActive || !hovered) {
+      return;
+    }
+    tempHold = hold;
+    priorToolId = deps.getActiveToolId();
+    if (deps.hasTool(toolId)) {
+      deps.setTool(toolId, { temporary: true });
+      tempSwitched = true;
+    } else {
+      tempSwitched = false;
+    }
+  };
+
+  const beginBboxTempTool = (): void => {
+    if (tempHold || gestureActive) {
+      return;
+    }
+    tempHold = 'bbox';
+    priorToolId = deps.getActiveToolId();
+    restoreTempAfterGesture = false;
+    bboxQuickTap = true;
+    clearBboxTapTimer();
+    bboxTapTimer = setTimeout(() => {
+      bboxQuickTap = false;
+      bboxTapTimer = null;
+    }, BBOX_QUICK_TAP_MS);
+
+    if (hovered && deps.hasTool(BBOX_TEMP_TOOL)) {
+      deps.setTool(BBOX_TEMP_TOOL, { temporary: true });
+      tempSwitched = true;
+    } else {
+      tempSwitched = false;
+    }
+  };
+
+  function endTempTool(): void {
+    clearBboxTapTimer();
+    if (tempSwitched) {
+      deps.setTool(priorToolId, { temporary: true });
+    }
+    tempHold = null;
+    tempSwitched = false;
+    restoreTempAfterGesture = false;
+    bboxQuickTap = false;
+  }
+
+  const releaseTempTool = (): void => {
+    if (!tempHold) {
+      return;
+    }
+    if (gestureActive) {
+      restoreTempAfterGesture = true;
+      return;
+    }
+    endTempTool();
+  };
+
+  const releaseBboxTempTool = (): void => {
+    if (tempHold !== 'bbox') {
+      return;
+    }
+    clearBboxTapTimer();
+    if (gestureActive) {
+      bboxQuickTap = false;
+      restoreTempAfterGesture = true;
+      return;
+    }
+    if (bboxQuickTap) {
+      if (tempSwitched) {
+        deps.setTool(priorToolId, { temporary: true });
+      }
+      deps.setTool(BBOX_TEMP_TOOL);
+      tempHold = null;
+      tempSwitched = false;
+      restoreTempAfterGesture = false;
+      bboxQuickTap = false;
+      return;
+    }
+    endTempTool();
+  };
+
+  return {
+    cancelActiveGesture: () => {
+      cancelGesture();
+    },
+    onKeyDown: (event) => {
+      if (event.key === 'Escape') {
+        // Cancel any active drag first, then run the engine's Escape priority
+        // (cancel a transform session, else deselect). The editable guard keeps
+        // Escape in a text field from tearing down a canvas session/selection the
+        // field isn't part of. A mid-drag Escape cancels the gesture here; the
+        // subsequent `handleEscape` still sees (and cancels) a transform session
+        // the reverted drag kept open, matching the prior gesture+session teardown,
+        // but skips deselect so a mid-lasso Escape drops only the in-progress path.
+        const gestureWasActive = gestureActive;
+        cancelGesture();
+        if (!isEditableTarget(event.target)) {
+          deps.handleEscape?.({ gestureWasActive });
+        }
+        return;
+      }
+      // Never let space/alt temp-tool holds (or Enter apply) fire while the user is
+      // typing in an editable field (e.g. a layer rename input) — that key belongs
+      // to the field, not the canvas.
+      if (isEditableTarget(event.target)) {
+        return;
+      }
+      if (event.key === 'Enter') {
+        // Enter applies a session-bearing tool's edit (transform). No-op otherwise.
+        deps.getActiveTool()?.onKeyCommand?.(deps.getToolContext(), 'apply');
+        return;
+      }
+      if (event.code === 'Space' && !event.repeat) {
+        beginTempTool('space', SPACE_TEMP_TOOL);
+        if (tempHold === 'space') {
+          event.preventDefault();
+        }
+        return;
+      }
+      if (isAltKey(event) && !event.repeat) {
+        beginTempTool('alt', ALT_TEMP_TOOL);
+        return;
+      }
+      if (isBboxKey(event) && !event.repeat) {
+        beginBboxTempTool();
+      }
+    },
+    isGestureActive: () => gestureActive,
+    onKeyUp: (event) => {
+      if (event.code === 'Space' && tempHold === 'space') {
+        releaseTempTool();
+      } else if (isAltKey(event) && tempHold === 'alt') {
+        releaseTempTool();
+      } else if (isBboxKey(event) && tempHold === 'bbox') {
+        releaseBboxTempTool();
+      }
+    },
+    onPointerCancel: (event) => {
+      // Ignore cancel events from a pointer other than the one driving the active gesture/pan
+      // (pointer capture on the active pointer does not suppress other pointers' events).
+      if (activePointerId !== null && event.pointerId !== activePointerId) {
+        return;
+      }
+      if (middlePanning) {
+        releaseCapture(event.pointerId);
+        middlePanning = false;
+        middleLast = null;
+        activePointerId = null;
+        return;
+      }
+      // `cancelGesture` releases the captured pointer itself.
+      cancelGesture();
+    },
+    onPointerDown: (event) => {
+      // Ignore extra/secondary buttons pressed during an active gesture or pan.
+      if (gestureActive || middlePanning) {
+        return;
+      }
+      const el = deps.getInputElement();
+      if (event.button === 1) {
+        el?.setPointerCapture?.(event.pointerId);
+        activePointerId = event.pointerId;
+        middlePanning = true;
+        middleLast = buildPointerInput(event).screenPoint;
+        return;
+      }
+      if (event.button !== 0) {
+        return;
+      }
+      // A primary press while a text-edit session is open commits it (engine-side,
+      // reading the live portal content) and is swallowed — no gesture, no tool
+      // routing. This must precede `gestureActive = true` so the engine's
+      // mid-gesture commit guard cannot drop it. `preventDefault` avoids a stray
+      // focus/selection default now that the session has already been closed.
+      if (deps.maybeCommitModalSession?.()) {
+        event.preventDefault();
+        return;
+      }
+      markBboxHold();
+      el?.setPointerCapture?.(event.pointerId);
+      activePointerId = event.pointerId;
+      gestureActive = true;
+      event.preventDefault();
+      deps.getActiveTool()?.onPointerDown?.(deps.getToolContext(), buildPointerInput(event));
+      deps.updateCursor();
+    },
+    onPointerEnter: () => {
+      hovered = true;
+    },
+    onPointerLeave: () => {
+      hovered = false;
+    },
+    onPointerMove: (event) => {
+      // Ignore move events from a pointer other than the one driving the active gesture/pan.
+      if (activePointerId !== null && event.pointerId !== activePointerId) {
+        return;
+      }
+      if (middlePanning && middleLast) {
+        const screenPoint = buildPointerInput(event).screenPoint;
+        deps.viewport.panBy({ x: screenPoint.x - middleLast.x, y: screenPoint.y - middleLast.y });
+        middleLast = screenPoint;
+        return;
+      }
+      const batch = buildBatch(event);
+      const last = batch[batch.length - 1];
+      if (!last) {
+        return;
+      }
+      deps.getActiveTool()?.onPointerMove?.(deps.getToolContext(), last, batch);
+    },
+    onPointerUp: (event) => {
+      // Ignore up events from a pointer other than the one driving the active gesture/pan.
+      if (activePointerId !== null && event.pointerId !== activePointerId) {
+        return;
+      }
+      releaseCapture(event.pointerId);
+      if (middlePanning) {
+        middlePanning = false;
+        middleLast = null;
+        activePointerId = null;
+        return;
+      }
+      if (!gestureActive) {
+        return;
+      }
+      gestureActive = false;
+      activePointerId = null;
+      deps.getActiveTool()?.onPointerUp?.(deps.getToolContext(), buildPointerInput(event));
+      deps.updateCursor();
+      if (restoreTempAfterGesture && tempHold) {
+        endTempTool();
+      }
+    },
+    replaceTemporaryRestoreTool: (current, replacement) => {
+      if (tempHold && priorToolId === current) {
+        priorToolId = replacement;
+      }
+    },
+    reset: () => {
+      clearBboxTapTimer();
+      if (tempHold) {
+        endTempTool();
+      }
+      // Cancel an in-flight gesture through the same path Esc uses, so the active
+      // tool's `onPointerCancel` runs and clears its transient state (rather than
+      // silently dropping `gestureActive` and stranding stale tool state).
+      cancelGesture();
+      hovered = false;
+      gestureActive = false;
+      activePointerId = null;
+      middlePanning = false;
+      middleLast = null;
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/input/wheel.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/wheel.test.ts
new file mode 100644
index 00000000000..b83e7df8ec0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/wheel.test.ts
@@ -0,0 +1,90 @@
+import type { WheelHandlerDeps } from '@workbench/canvas-engine/input/wheel';
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { ToolId } from '@workbench/canvas-engine/types';
+
+import { createWheelHandler } from '@workbench/canvas-engine/input/wheel';
+import { createViewport } from '@workbench/canvas-engine/viewport';
+import { describe, expect, it, vi } from 'vitest';
+
+const makeWheelEvent = (deltaY: number, opts: { ctrlKey?: boolean } = {}): WheelEvent =>
+  ({
+    altKey: false,
+    clientX: 10,
+    clientY: 10,
+    ctrlKey: opts.ctrlKey ?? false,
+    deltaY,
+    metaKey: false,
+    preventDefault: vi.fn(),
+    shiftKey: false,
+  }) as unknown as WheelEvent;
+
+const createHarness = (tool: Tool | undefined, invertBrushSizeScroll = false) => {
+  const viewport = createViewport();
+  const stepActiveBrushSize = vi.fn();
+  const invalidate = vi.fn();
+  const deps: WheelHandlerDeps = {
+    getActiveTool: () => tool,
+    getInputElement: () => ({ getBoundingClientRect: () => ({ left: 0, top: 0 }) }) as unknown as HTMLElement,
+    getInvertBrushSizeScroll: () => invertBrushSizeScroll,
+    getToolContext: () => ({}) as ToolContext,
+    invalidate,
+    stepActiveBrushSize,
+    viewport,
+  };
+  return { handler: createWheelHandler(deps), invalidate, stepActiveBrushSize, viewport };
+};
+
+const toolWithId = (id: ToolId, onWheel?: Tool['onWheel']): Tool => ({ id, onWheel });
+
+describe('wheel handler: ctrl+wheel brush size step', () => {
+  it('grows the size on ctrl+wheel-up when brush is active', () => {
+    const h = createHarness(toolWithId('brush'));
+    h.handler(makeWheelEvent(-100, { ctrlKey: true }));
+    expect(h.stepActiveBrushSize).toHaveBeenCalledWith(1);
+  });
+
+  it('shrinks the size on ctrl+wheel-down when eraser is active', () => {
+    const h = createHarness(toolWithId('eraser'));
+    h.handler(makeWheelEvent(100, { ctrlKey: true }));
+    expect(h.stepActiveBrushSize).toHaveBeenCalledWith(-1);
+  });
+
+  it('inverts the step direction when the invert-scroll preference is on', () => {
+    const grow = createHarness(toolWithId('brush'), true);
+    grow.handler(makeWheelEvent(-100, { ctrlKey: true }));
+    // Wheel-up normally grows (+1); inverted, it shrinks (-1).
+    expect(grow.stepActiveBrushSize).toHaveBeenCalledWith(-1);
+
+    const shrink = createHarness(toolWithId('eraser'), true);
+    shrink.handler(makeWheelEvent(100, { ctrlKey: true }));
+    // Wheel-down normally shrinks (-1); inverted, it grows (+1).
+    expect(shrink.stepActiveBrushSize).toHaveBeenCalledWith(1);
+  });
+
+  it('swallows ctrl+wheel (no size step, no zoom) for non-paint tools', () => {
+    const h = createHarness(toolWithId('view'));
+    const wheelZoom = vi.spyOn(h.viewport, 'wheelZoom');
+    h.handler(makeWheelEvent(-100, { ctrlKey: true }));
+    expect(h.stepActiveBrushSize).not.toHaveBeenCalled();
+    expect(wheelZoom).not.toHaveBeenCalled();
+  });
+});
+
+describe('wheel handler: plain wheel', () => {
+  it('zooms the viewport when the active tool defines no onWheel', () => {
+    const h = createHarness(toolWithId('brush'));
+    const wheelZoom = vi.spyOn(h.viewport, 'wheelZoom');
+    h.handler(makeWheelEvent(-120));
+    expect(wheelZoom).toHaveBeenCalledWith(-120, { x: 10, y: 10 });
+    expect(h.invalidate).toHaveBeenCalledWith({ view: true });
+  });
+
+  it('routes to the active tool onWheel when present', () => {
+    const onWheel = vi.fn();
+    const h = createHarness(toolWithId('view', onWheel));
+    const wheelZoom = vi.spyOn(h.viewport, 'wheelZoom');
+    h.handler(makeWheelEvent(-120));
+    expect(onWheel).toHaveBeenCalledTimes(1);
+    expect(wheelZoom).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/input/wheel.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/wheel.ts
new file mode 100644
index 00000000000..96ec4770f2a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/input/wheel.ts
@@ -0,0 +1,71 @@
+/**
+ * Wheel routing for the canvas.
+ *
+ * - Plain wheel → the active tool's `onWheel` if it defines one, else viewport
+ *   zoom about the cursor (the default navigation behavior).
+ * - Ctrl+wheel → when the active tool is brush/eraser, step its size; otherwise
+ *   it is swallowed (reserved for the browser pinch-zoom gesture).
+ *
+ * The handler is a pure function of injected deps (viewport, the active tool, and
+ * a `stepActiveBrushSize` callback the engine wires to the tool-options stores),
+ * so it is driven directly in node tests. DOM is touched only through the passed
+ * `WheelEvent`. Zero React, zero import-time side effects.
+ */
+
+import type { InvalidatePayload } from '@workbench/canvas-engine/render/scheduler';
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerModifiers, Vec2 } from '@workbench/canvas-engine/types';
+import type { Viewport } from '@workbench/canvas-engine/viewport';
+
+/** Dependencies for {@link createWheelHandler}. */
+export interface WheelHandlerDeps {
+  viewport: Viewport;
+  invalidate(payload: InvalidatePayload): void;
+  getInputElement(): HTMLElement | null;
+  getActiveTool(): Tool | undefined;
+  getToolContext(): ToolContext;
+  /** Steps the active brush/eraser diameter by one notch (`+1` grow, `-1` shrink). */
+  stepActiveBrushSize(direction: 1 | -1): void;
+  /**
+   * Whether ctrl+wheel brush sizing is inverted. `false` (default): wheel-up
+   * grows. `true`: wheel-up shrinks. A user preference read fresh per event.
+   */
+  getInvertBrushSizeScroll(): boolean;
+}
+
+const modifiersOf = (event: WheelEvent): PointerModifiers => ({
+  alt: event.altKey,
+  ctrl: event.ctrlKey,
+  meta: event.metaKey,
+  shift: event.shiftKey,
+});
+
+/** Creates the canvas wheel handler. See module docs for routing. */
+export const createWheelHandler = (deps: WheelHandlerDeps): ((event: WheelEvent) => void) => {
+  return (event: WheelEvent): void => {
+    event.preventDefault();
+
+    const rect = deps.getInputElement()?.getBoundingClientRect();
+    const screenAnchor: Vec2 = { x: event.clientX - (rect?.left ?? 0), y: event.clientY - (rect?.top ?? 0) };
+
+    const tool = deps.getActiveTool();
+
+    // Ctrl+wheel: brush/eraser size step, else reserved (pinch-zoom) — swallowed.
+    if (event.ctrlKey) {
+      if (tool && (tool.id === 'brush' || tool.id === 'eraser')) {
+        // Default: wheel-up (deltaY < 0) grows. The inversion preference flips it.
+        const grow = event.deltaY < 0;
+        const stepUp = grow !== deps.getInvertBrushSizeScroll();
+        deps.stepActiveBrushSize(stepUp ? 1 : -1);
+      }
+      return;
+    }
+
+    if (tool?.onWheel) {
+      tool.onWheel(deps.getToolContext(), event.deltaY, screenAnchor, modifiersOf(event));
+      return;
+    }
+    deps.viewport.wheelZoom(event.deltaY, screenAnchor);
+    deps.invalidate({ view: true });
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/math/mat2d.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/mat2d.test.ts
new file mode 100644
index 00000000000..4ff01baa28e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/mat2d.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest';
+
+import { applyToPoint, fromTRS, getScale, identity, invert, multiply, rotate, scale, translate } from './mat2d';
+
+describe('identity', () => {
+  it('returns the identity matrix', () => {
+    expect(identity()).toEqual({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+  });
+
+  it('applied to a point returns the same point', () => {
+    expect(applyToPoint(identity(), { x: 5, y: -3 })).toEqual({ x: 5, y: -3 });
+  });
+});
+
+describe('translate', () => {
+  it('shifts points by the translation vector', () => {
+    const m = translate(identity(), { x: 10, y: 20 });
+    expect(applyToPoint(m, { x: 0, y: 0 })).toEqual({ x: 10, y: 20 });
+    expect(applyToPoint(m, { x: 5, y: 5 })).toEqual({ x: 15, y: 25 });
+  });
+});
+
+describe('scale', () => {
+  it('scales points uniformly when sy is omitted', () => {
+    const m = scale(identity(), 2);
+    expect(applyToPoint(m, { x: 3, y: 4 })).toEqual({ x: 6, y: 8 });
+  });
+
+  it('scales points non-uniformly when sy is given', () => {
+    const m = scale(identity(), 2, 3);
+    expect(applyToPoint(m, { x: 1, y: 1 })).toEqual({ x: 2, y: 3 });
+  });
+});
+
+describe('rotate', () => {
+  it('rotates a point 90 degrees clockwise', () => {
+    const m = rotate(identity(), Math.PI / 2);
+    const p = applyToPoint(m, { x: 1, y: 0 });
+    expect(p.x).toBeCloseTo(0, 10);
+    expect(p.y).toBeCloseTo(1, 10);
+  });
+
+  it('rotating by 0 radians is a no-op', () => {
+    const m = rotate(identity(), 0);
+    expect(applyToPoint(m, { x: 7, y: -2 })).toEqual({ x: 7, y: -2 });
+  });
+});
+
+describe('multiply', () => {
+  it('composes transforms so the right operand applies first', () => {
+    // translate(10,0) * scale(2) applied to (1,1): scale first -> (2,2), then translate -> (12, 2)
+    const t = translate(identity(), { x: 10, y: 0 });
+    const s = scale(identity(), 2);
+    const m = multiply(t, s);
+    expect(applyToPoint(m, { x: 1, y: 1 })).toEqual({ x: 12, y: 2 });
+  });
+
+  it('multiplying by identity is a no-op on either side', () => {
+    const m = translate(scale(identity(), 3, 4), { x: 1, y: 2 });
+    expect(multiply(m, identity())).toEqual(m);
+    expect(multiply(identity(), m)).toEqual(m);
+  });
+});
+
+describe('invert', () => {
+  it('round-trips applyToPoint through a matrix and its inverse', () => {
+    const m = fromTRS({ x: 5, y: -3 }, Math.PI / 6, 2, 0.5);
+    const inv = invert(m);
+    expect(inv).not.toBeNull();
+    const p = { x: 13, y: -4 };
+    const roundTripped = applyToPoint(inv as NonNullable<typeof inv>, applyToPoint(m, p));
+    expect(roundTripped.x).toBeCloseTo(p.x, 8);
+    expect(roundTripped.y).toBeCloseTo(p.y, 8);
+  });
+
+  it('returns null for a singular matrix', () => {
+    // Zero determinant: a*d - b*c = 0
+    expect(invert({ a: 1, b: 2, c: 2, d: 4, e: 0, f: 0 })).toBeNull();
+    expect(invert({ a: 0, b: 0, c: 0, d: 0, e: 1, f: 1 })).toBeNull();
+  });
+
+  it('inverting identity returns identity', () => {
+    const inv = invert(identity());
+    expect(inv).not.toBeNull();
+    const nonNullInv = inv as NonNullable<typeof inv>;
+    expect(nonNullInv.a).toBeCloseTo(1, 10);
+    expect(nonNullInv.b).toBeCloseTo(0, 10);
+    expect(nonNullInv.c).toBeCloseTo(0, 10);
+    expect(nonNullInv.d).toBeCloseTo(1, 10);
+    expect(nonNullInv.e).toBeCloseTo(0, 10);
+    expect(nonNullInv.f).toBeCloseTo(0, 10);
+  });
+});
+
+describe('fromTRS', () => {
+  it('matches manual translate . rotate . scale composition', () => {
+    const translation = { x: 4, y: -2 };
+    const rad = 0.7;
+    const sx = 1.5;
+    const sy = 2.5;
+
+    const t = translate(identity(), translation);
+    const r = rotate(identity(), rad);
+    const s = scale(identity(), sx, sy);
+    const manual = multiply(multiply(t, r), s);
+    const composed = fromTRS(translation, rad, sx, sy);
+
+    expect(composed.a).toBeCloseTo(manual.a, 10);
+    expect(composed.b).toBeCloseTo(manual.b, 10);
+    expect(composed.c).toBeCloseTo(manual.c, 10);
+    expect(composed.d).toBeCloseTo(manual.d, 10);
+    expect(composed.e).toBeCloseTo(manual.e, 10);
+    expect(composed.f).toBeCloseTo(manual.f, 10);
+  });
+
+  it('defaults scaleY to scaleX for uniform scale', () => {
+    const composed = fromTRS({ x: 0, y: 0 }, 0, 3, 3);
+    const defaulted = fromTRS({ x: 0, y: 0 }, 0, 3);
+    expect(defaulted).toEqual(composed);
+  });
+
+  it('with no rotation/scale reduces to pure translation', () => {
+    expect(fromTRS({ x: 8, y: 9 }, 0, 1, 1)).toEqual(translate(identity(), { x: 8, y: 9 }));
+  });
+});
+
+describe('getScale', () => {
+  it('returns 1 for the identity matrix', () => {
+    expect(getScale(identity())).toBeCloseTo(1, 10);
+  });
+
+  it('returns the scale factor for a uniformly scaled matrix', () => {
+    expect(getScale(scale(identity(), 3))).toBeCloseTo(3, 10);
+  });
+
+  it('returns the geometric mean for a non-uniformly scaled matrix', () => {
+    expect(getScale(scale(identity(), 2, 8))).toBeCloseTo(4, 10);
+  });
+
+  it('is unaffected by translation', () => {
+    const m = translate(scale(identity(), 2), { x: 100, y: -50 });
+    expect(getScale(m)).toBeCloseTo(2, 10);
+  });
+
+  it('is unaffected by rotation for a uniformly scaled matrix', () => {
+    const m = rotate(scale(identity(), 5), 1.234);
+    expect(getScale(m)).toBeCloseTo(5, 8);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/math/mat2d.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/mat2d.ts
new file mode 100644
index 00000000000..cd6b641cc29
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/mat2d.ts
@@ -0,0 +1,95 @@
+/**
+ * Pure functions on `Mat2d`, the engine's 2D affine matrix type.
+ *
+ * Convention (matches `CanvasRenderingContext2D.setTransform`):
+ * ```
+ * x' = a*x + c*y + e
+ * y' = b*x + d*y + f
+ * ```
+ *
+ * No classes, no mutation — every function returns a new `Mat2d`.
+ */
+
+import type { Mat2d, Vec2 } from '@workbench/canvas-engine/types';
+
+/** Returns the identity matrix. */
+export const identity = (): Mat2d => ({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+
+/**
+ * Composes two matrices such that applying the result to a point is
+ * equivalent to applying `b` first, then `a` (i.e. `result = a * b`, using
+ * the same composition order as `DOMMatrix.multiply` / `ctx.transform`
+ * chaining: `a.multiply(b)` applies `b`'s transform in `a`'s coordinate
+ * space).
+ */
+export const multiply = (a: Mat2d, b: Mat2d): Mat2d => ({
+  a: a.a * b.a + a.c * b.b,
+  b: a.b * b.a + a.d * b.b,
+  c: a.a * b.c + a.c * b.d,
+  d: a.b * b.c + a.d * b.d,
+  e: a.a * b.e + a.c * b.f + a.e,
+  f: a.b * b.e + a.d * b.f + a.f,
+});
+
+/** Inverts a matrix. Returns `null` if the matrix is singular (determinant ~0). */
+export const invert = (m: Mat2d): Mat2d | null => {
+  const det = m.a * m.d - m.b * m.c;
+  if (Math.abs(det) < 1e-12) {
+    return null;
+  }
+  const invDet = 1 / det;
+  const a = m.d * invDet;
+  const b = -m.b * invDet;
+  const c = -m.c * invDet;
+  const d = m.a * invDet;
+  const e = -(a * m.e + c * m.f);
+  const f = -(b * m.e + d * m.f);
+  return { a, b, c, d, e, f };
+};
+
+/** Returns a matrix translated by `v` (post-multiplies a translation). */
+export const translate = (m: Mat2d, v: Vec2): Mat2d => multiply(m, { a: 1, b: 0, c: 0, d: 1, e: v.x, f: v.y });
+
+/** Returns a matrix scaled by `sx`/`sy` (defaults `sy` to `sx` for uniform scale). */
+export const scale = (m: Mat2d, sx: number, sy: number = sx): Mat2d =>
+  multiply(m, { a: sx, b: 0, c: 0, d: sy, e: 0, f: 0 });
+
+/** Returns a matrix rotated by `rad` radians (positive = clockwise in canvas space). */
+export const rotate = (m: Mat2d, rad: number): Mat2d => {
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  return multiply(m, { a: cos, b: sin, c: -sin, d: cos, e: 0, f: 0 });
+};
+
+/** Applies a matrix to a point, returning the transformed point. */
+export const applyToPoint = (m: Mat2d, p: Vec2): Vec2 => ({
+  x: m.a * p.x + m.c * p.y + m.e,
+  y: m.b * p.x + m.d * p.y + m.f,
+});
+
+/**
+ * Composes a matrix from translation, rotation, and scale, in the order
+ * translate · rotate · scale — i.e. scale is applied first (in local
+ * space), then rotation, then translation. This is the standard TRS
+ * composition used for layer transforms.
+ */
+export const fromTRS = (translation: Vec2, rotationRad: number, scaleX: number, scaleY: number = scaleX): Mat2d => {
+  let m = identity();
+  m = translate(m, translation);
+  m = rotate(m, rotationRad);
+  m = scale(m, scaleX, scaleY);
+  return m;
+};
+
+/**
+ * Extracts an approximate uniform scale magnitude from a matrix — the
+ * geometric mean of the transformed lengths of the unit x/y axis vectors.
+ * Useful for stroke-width and zoom math where an exact per-axis scale isn't
+ * needed. For a matrix with no shear/non-uniform scale this equals the
+ * true scale factor.
+ */
+export const getScale = (m: Mat2d): number => {
+  const scaleX = Math.hypot(m.a, m.b);
+  const scaleY = Math.hypot(m.c, m.d);
+  return Math.sqrt(scaleX * scaleY);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/math/rect.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/rect.test.ts
new file mode 100644
index 00000000000..8888aa85487
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/rect.test.ts
@@ -0,0 +1,202 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { identity, rotate, scale, translate } from './mat2d';
+import { containsPoint, expand, intersect, isEmpty, mergeDirtyRects, roundOut, transformBounds, union } from './rect';
+
+describe('isEmpty', () => {
+  it('is true for zero width or height', () => {
+    expect(isEmpty({ x: 0, y: 0, width: 0, height: 10 })).toBe(true);
+    expect(isEmpty({ x: 0, y: 0, width: 10, height: 0 })).toBe(true);
+  });
+
+  it('is true for negative width or height', () => {
+    expect(isEmpty({ x: 0, y: 0, width: -1, height: 10 })).toBe(true);
+  });
+
+  it('is false for a positive-area rect', () => {
+    expect(isEmpty({ x: 0, y: 0, width: 1, height: 1 })).toBe(false);
+  });
+});
+
+describe('intersect', () => {
+  it('returns the overlapping region for overlapping rects', () => {
+    const a: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    const b: Rect = { x: 5, y: 5, width: 10, height: 10 };
+    expect(intersect(a, b)).toEqual({ x: 5, y: 5, width: 5, height: 5 });
+  });
+
+  it('returns null for disjoint rects', () => {
+    const a: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    const b: Rect = { x: 20, y: 20, width: 10, height: 10 };
+    expect(intersect(a, b)).toBeNull();
+  });
+
+  it('returns null for rects that only touch at an edge', () => {
+    const a: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    const b: Rect = { x: 10, y: 0, width: 10, height: 10 };
+    expect(intersect(a, b)).toBeNull();
+  });
+
+  it('returns null when either rect is empty', () => {
+    const a: Rect = { x: 0, y: 0, width: 0, height: 10 };
+    const b: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    expect(intersect(a, b)).toBeNull();
+  });
+});
+
+describe('union', () => {
+  it('returns the bounding box of two rects', () => {
+    const a: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    const b: Rect = { x: 5, y: -5, width: 10, height: 10 };
+    expect(union(a, b)).toEqual({ x: 0, y: -5, width: 15, height: 15 });
+  });
+
+  it('returns the non-empty rect when the other is empty', () => {
+    const a: Rect = { x: 0, y: 0, width: 0, height: 0 };
+    const b: Rect = { x: 5, y: 5, width: 10, height: 10 };
+    expect(union(a, b)).toEqual(b);
+    expect(union(b, a)).toEqual(b);
+  });
+
+  it('returns the first rect when both are empty', () => {
+    const a: Rect = { x: 1, y: 1, width: 0, height: 0 };
+    const b: Rect = { x: 2, y: 2, width: 0, height: 0 };
+    expect(union(a, b)).toEqual(a);
+  });
+});
+
+describe('containsPoint', () => {
+  const r: Rect = { x: 0, y: 0, width: 10, height: 10 };
+
+  it('is true for points inside the rect', () => {
+    expect(containsPoint(r, { x: 5, y: 5 })).toBe(true);
+    expect(containsPoint(r, { x: 0, y: 0 })).toBe(true);
+  });
+
+  it('is false for points on the max edge (exclusive)', () => {
+    expect(containsPoint(r, { x: 10, y: 5 })).toBe(false);
+    expect(containsPoint(r, { x: 5, y: 10 })).toBe(false);
+  });
+
+  it('is false for points outside the rect', () => {
+    expect(containsPoint(r, { x: -1, y: 5 })).toBe(false);
+    expect(containsPoint(r, { x: 5, y: 20 })).toBe(false);
+  });
+});
+
+describe('expand', () => {
+  it('grows the rect on all sides by margin', () => {
+    const r: Rect = { x: 10, y: 10, width: 10, height: 10 };
+    expect(expand(r, 5)).toEqual({ x: 5, y: 5, width: 20, height: 20 });
+  });
+
+  it('shrinks the rect for negative margin', () => {
+    const r: Rect = { x: 10, y: 10, width: 10, height: 10 };
+    expect(expand(r, -2)).toEqual({ x: 12, y: 12, width: 6, height: 6 });
+  });
+});
+
+describe('roundOut', () => {
+  it('floors the min edges and ceils the max edges', () => {
+    const r: Rect = { x: 1.2, y: 1.8, width: 3.5, height: 2.1 };
+    // right edge = 1.2 + 3.5 = 4.7 -> ceil 5; bottom = 1.8 + 2.1 = 3.9 -> ceil 4
+    expect(roundOut(r)).toEqual({ x: 1, y: 1, width: 4, height: 3 });
+  });
+
+  it('is a no-op for already-integer rects', () => {
+    const r: Rect = { x: 2, y: 3, width: 4, height: 5 };
+    expect(roundOut(r)).toEqual(r);
+  });
+
+  it('handles negative coordinates', () => {
+    const r: Rect = { x: -1.5, y: -2.1, width: 3, height: 3 };
+    // right = 1.5 -> ceil 2; bottom = 0.9 -> ceil 1
+    expect(roundOut(r)).toEqual({ x: -2, y: -3, width: 4, height: 4 });
+  });
+});
+
+describe('transformBounds', () => {
+  it('returns the same rect for the identity matrix', () => {
+    const r: Rect = { x: 1, y: 2, width: 10, height: 20 };
+    expect(transformBounds(identity(), r)).toEqual(r);
+  });
+
+  it('translates the rect for a translation matrix', () => {
+    const r: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    const m = translate(identity(), { x: 5, y: -5 });
+    expect(transformBounds(m, r)).toEqual({ x: 5, y: -5, width: 10, height: 10 });
+  });
+
+  it('scales the rect for a scale matrix', () => {
+    const r: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    const m = scale(identity(), 2);
+    expect(transformBounds(m, r)).toEqual({ x: 0, y: 0, width: 20, height: 20 });
+  });
+
+  it('returns the axis-aligned bounding box of a rotated rect', () => {
+    const r: Rect = { x: -5, y: -5, width: 10, height: 10 };
+    const m = rotate(identity(), Math.PI / 4);
+    const bounds = transformBounds(m, r);
+    const diagonal = Math.sqrt(2) * 10;
+    expect(bounds.width).toBeCloseTo(diagonal, 8);
+    expect(bounds.height).toBeCloseTo(diagonal, 8);
+    expect(bounds.x).toBeCloseTo(-diagonal / 2, 8);
+    expect(bounds.y).toBeCloseTo(-diagonal / 2, 8);
+  });
+});
+
+describe('mergeDirtyRects', () => {
+  it('returns an empty array for no rects', () => {
+    expect(mergeDirtyRects([])).toEqual([]);
+  });
+
+  it('returns the single rect unchanged (filtering empties)', () => {
+    const r: Rect = { x: 0, y: 0, width: 5, height: 5 };
+    expect(mergeDirtyRects([r])).toEqual([r]);
+  });
+
+  it('filters out empty rects', () => {
+    const r: Rect = { x: 0, y: 0, width: 5, height: 5 };
+    const empty: Rect = { x: 0, y: 0, width: 0, height: 0 };
+    expect(mergeDirtyRects([r, empty])).toEqual([r]);
+  });
+
+  it('merges overlapping rects into one', () => {
+    const a: Rect = { x: 0, y: 0, width: 10, height: 10 };
+    const b: Rect = { x: 5, y: 5, width: 10, height: 10 };
+    const result = mergeDirtyRects([a, b]);
+    expect(result).toEqual([{ x: 0, y: 0, width: 15, height: 15 }]);
+  });
+
+  it('keeps far-apart rects separate when under the region cap', () => {
+    const a: Rect = { x: 0, y: 0, width: 5, height: 5 };
+    const b: Rect = { x: 1000, y: 1000, width: 5, height: 5 };
+    const result = mergeDirtyRects([a, b]);
+    expect(result).toHaveLength(2);
+    expect(result).toEqual(expect.arrayContaining([a, b]));
+  });
+
+  it('falls back to a single merged bounding rect beyond maxRegions', () => {
+    const rects: Rect[] = [
+      { x: 0, y: 0, width: 5, height: 5 },
+      { x: 100, y: 0, width: 5, height: 5 },
+      { x: 0, y: 100, width: 5, height: 5 },
+      { x: 100, y: 100, width: 5, height: 5 },
+      { x: 200, y: 200, width: 5, height: 5 },
+    ];
+    const result = mergeDirtyRects(rects, 4);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({ x: 0, y: 0, width: 205, height: 205 });
+  });
+
+  it('respects a custom maxRegions', () => {
+    const rects: Rect[] = [
+      { x: 0, y: 0, width: 5, height: 5 },
+      { x: 100, y: 0, width: 5, height: 5 },
+    ];
+    const result = mergeDirtyRects(rects, 1);
+    expect(result).toHaveLength(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/math/rect.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/rect.ts
new file mode 100644
index 00000000000..141aa548313
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/rect.ts
@@ -0,0 +1,167 @@
+/**
+ * Pure functions on `Rect`, the engine's axis-aligned rectangle type.
+ *
+ * No classes, no mutation — every function returns a new `Rect` (or a
+ * primitive / array of `Rect`).
+ */
+
+import type { Mat2d, Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+import { applyToPoint } from './mat2d';
+
+/** True if the rect has non-positive width or height. */
+export const isEmpty = (r: Rect): boolean => r.width <= 0 || r.height <= 0;
+
+/** Intersection of two rects, or `null` if they don't overlap (or either is empty). */
+export const intersect = (a: Rect, b: Rect): Rect | null => {
+  if (isEmpty(a) || isEmpty(b)) {
+    return null;
+  }
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  if (right <= x || bottom <= y) {
+    return null;
+  }
+  return { x, y, width: right - x, height: bottom - y };
+};
+
+/**
+ * Union (bounding box) of two rects. An empty rect is treated as
+ * contributing no area — the union of an empty rect and a non-empty rect is
+ * the non-empty rect; the union of two empty rects is the first rect.
+ */
+export const union = (a: Rect, b: Rect): Rect => {
+  if (isEmpty(a) && isEmpty(b)) {
+    return a;
+  }
+  if (isEmpty(a)) {
+    return b;
+  }
+  if (isEmpty(b)) {
+    return a;
+  }
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  const right = Math.max(a.x + a.width, b.x + b.width);
+  const bottom = Math.max(a.y + a.height, b.y + b.height);
+  return { x, y, width: right - x, height: bottom - y };
+};
+
+/** True if `p` lies within `r`, inclusive of the min edges and exclusive of the max edges. */
+export const containsPoint = (r: Rect, p: Vec2): boolean =>
+  p.x >= r.x && p.x < r.x + r.width && p.y >= r.y && p.y < r.y + r.height;
+
+/** Grows (or shrinks, for negative `margin`) a rect uniformly on all sides. */
+export const expand = (r: Rect, margin: number): Rect => ({
+  x: r.x - margin,
+  y: r.y - margin,
+  width: r.width + margin * 2,
+  height: r.height + margin * 2,
+});
+
+/**
+ * Rounds a rect outward to integer bounds (floor the min edges, ceil the
+ * max edges). Used to align dirty rects to pixel boundaries so patches
+ * fully cover the region that changed.
+ */
+export const roundOut = (r: Rect): Rect => {
+  const x = Math.floor(r.x);
+  const y = Math.floor(r.y);
+  const right = Math.ceil(r.x + r.width);
+  const bottom = Math.ceil(r.y + r.height);
+  return { x, y, width: right - x, height: bottom - y };
+};
+
+/** Axis-aligned bounds of `r` after being transformed by `m`. */
+export const transformBounds = (m: Mat2d, r: Rect): Rect => {
+  const corners: Vec2[] = [
+    { x: r.x, y: r.y },
+    { x: r.x + r.width, y: r.y },
+    { x: r.x, y: r.y + r.height },
+    { x: r.x + r.width, y: r.y + r.height },
+  ].map((p) => applyToPoint(m, p));
+
+  const xs = corners.map((p) => p.x);
+  const ys = corners.map((p) => p.y);
+  const minX = Math.min(...xs);
+  const maxX = Math.max(...xs);
+  const minY = Math.min(...ys);
+  const maxY = Math.max(...ys);
+
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+};
+
+/** Rect area, treating empty rects as zero area. */
+const area = (r: Rect): number => (isEmpty(r) ? 0 : r.width * r.height);
+
+/**
+ * True if two rects overlap or touch within `slack` pixels of each other
+ * (i.e. their `slack`-expanded bounds intersect).
+ */
+const isNearby = (a: Rect, b: Rect, slack: number): boolean => {
+  const expandedA = slack === 0 ? a : expand(a, slack);
+  return intersect(expandedA, b) !== null;
+};
+
+/**
+ * Coalesces a list of dirty rects into at most `maxRegions` rects.
+ *
+ * Algorithm: greedily merges any two rects that overlap or are within a
+ * small proximity slack (derived from the average rect size) whenever the
+ * merge doesn't waste too much area — specifically, whenever the merged
+ * rect's area is no more than 2x the sum of the two input areas, or the
+ * rects already overlap/touch. This repeats to a fixed point. If more than
+ * `maxRegions` rects remain, it falls back to merging everything into a
+ * single bounding rect (merge-all fallback) — simpler than picking which
+ * regions to keep, and cheap dirty-rect accounting favors correctness
+ * (never under-repaint) over minimizing painted area in the pathological
+ * case.
+ */
+export const mergeDirtyRects = (rects: Rect[], maxRegions = 4): Rect[] => {
+  const nonEmpty = rects.filter((r) => !isEmpty(r));
+  if (nonEmpty.length <= 1) {
+    return nonEmpty;
+  }
+
+  let current = nonEmpty.slice();
+  const avgDimension = current.reduce((sum, r) => sum + (r.width + r.height) / 2, 0) / current.length;
+  const slack = avgDimension * 0.1;
+
+  const findMergeablePair = (rectList: Rect[]): [number, number] | null => {
+    for (let i = 0; i < rectList.length; i++) {
+      for (let j = i + 1; j < rectList.length; j++) {
+        const a = rectList[i];
+        const b = rectList[j];
+        if (!a || !b) {
+          continue;
+        }
+        const overlaps = intersect(a, b) !== null;
+        const merged = union(a, b);
+        const wasteOk = area(merged) <= (area(a) + area(b)) * 2;
+        if (overlaps || (isNearby(a, b, slack) && wasteOk)) {
+          return [i, j];
+        }
+      }
+    }
+    return null;
+  };
+
+  let pair = findMergeablePair(current);
+  while (pair !== null && current.length > 1) {
+    const [i, j] = pair;
+    const a = current[i] as Rect;
+    const b = current[j] as Rect;
+    const next = current.filter((_, idx) => idx !== i && idx !== j);
+    next.push(union(a, b));
+    current = next;
+    pair = findMergeablePair(current);
+  }
+
+  if (current.length > maxRegions) {
+    return [current.reduce((acc, r) => union(acc, r))];
+  }
+
+  return current;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/math/snapping.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/snapping.test.ts
new file mode 100644
index 00000000000..174b70d7e50
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/snapping.test.ts
@@ -0,0 +1,141 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  clampZoom,
+  constrainAspect,
+  snapRectToGrid,
+  snapToGrid,
+  snapZoom,
+  ZOOM_MAX,
+  ZOOM_MIN,
+  ZOOM_SNAP_CANDIDATES,
+} from './snapping';
+
+describe('snapZoom', () => {
+  it('snaps to an exact candidate', () => {
+    expect(snapZoom(1)).toBe(1);
+    expect(snapZoom(0.25)).toBe(0.25);
+  });
+
+  it('snaps a value within tolerance of a candidate', () => {
+    expect(snapZoom(1.02)).toBe(1);
+    expect(snapZoom(0.98)).toBe(1);
+  });
+
+  it('passes through a value outside tolerance of any candidate', () => {
+    expect(snapZoom(1.2)).toBe(1.2);
+    expect(snapZoom(0.6)).toBe(0.6);
+  });
+
+  it('snaps at the tolerance boundary and passes through just beyond it', () => {
+    const candidate = 2;
+    const tolerance = candidate * 0.03;
+    expect(snapZoom(candidate + tolerance * 0.99)).toBe(candidate);
+    expect(snapZoom(candidate + tolerance * 1.5)).toBeCloseTo(candidate + tolerance * 1.5, 10);
+  });
+
+  it('supports custom candidates', () => {
+    expect(snapZoom(1.01, [1, 10])).toBe(1);
+    expect(snapZoom(5, [1, 10])).toBe(5);
+  });
+
+  it('exports the default candidates as a stable list', () => {
+    expect(ZOOM_SNAP_CANDIDATES).toEqual([0.25, 0.33, 0.5, 0.67, 0.75, 1, 1.25, 1.5, 2, 3, 4, 5]);
+  });
+});
+
+describe('clampZoom', () => {
+  it('clamps values below the minimum', () => {
+    expect(clampZoom(0)).toBe(ZOOM_MIN);
+    expect(clampZoom(-5)).toBe(ZOOM_MIN);
+  });
+
+  it('clamps values above the maximum', () => {
+    expect(clampZoom(100)).toBe(ZOOM_MAX);
+  });
+
+  it('passes through in-range values', () => {
+    expect(clampZoom(1)).toBe(1);
+    expect(clampZoom(ZOOM_MIN)).toBe(ZOOM_MIN);
+    expect(clampZoom(ZOOM_MAX)).toBe(ZOOM_MAX);
+  });
+});
+
+describe('snapToGrid', () => {
+  it('rounds to the nearest multiple of grid', () => {
+    expect(snapToGrid(10, 8)).toBe(8);
+    expect(snapToGrid(13, 8)).toBe(16);
+    expect(snapToGrid(0, 16)).toBe(0);
+  });
+
+  it('handles negative values', () => {
+    expect(snapToGrid(-10, 8)).toBe(-8);
+  });
+
+  it('returns the value unchanged for a non-positive grid', () => {
+    expect(snapToGrid(13.3, 0)).toBe(13.3);
+    expect(snapToGrid(13.3, -4)).toBe(13.3);
+  });
+});
+
+describe('snapRectToGrid', () => {
+  it('snaps position and the far edge to the grid, deriving size', () => {
+    const r: Rect = { x: 3, y: 5, width: 30, height: 30 };
+    // x: 3 -> 0, right: 33 -> 32 -> width 32
+    // y: 5 -> 8, bottom: 35 -> 32 -> height 24
+    expect(snapRectToGrid(r, 8)).toEqual({ x: 0, y: 8, width: 32, height: 24 });
+  });
+
+  it('is a no-op for a rect already aligned to the grid', () => {
+    const r: Rect = { x: 16, y: 32, width: 64, height: 16 };
+    expect(snapRectToGrid(r, 16)).toEqual(r);
+  });
+});
+
+describe('constrainAspect', () => {
+  const square: Rect = { x: 10, y: 10, width: 20, height: 20 };
+
+  it('keeps the nw corner fixed', () => {
+    const result = constrainAspect(square, 2, 'nw');
+    expect(result).toEqual({ x: 10, y: 10, width: 40, height: 20 });
+  });
+
+  it('keeps the ne corner fixed', () => {
+    const result = constrainAspect(square, 2, 'ne');
+    // right edge (30) stays fixed, width grows to 40, so x = 30 - 40 = -10
+    expect(result).toEqual({ x: -10, y: 10, width: 40, height: 20 });
+  });
+
+  it('keeps the sw corner fixed', () => {
+    const result = constrainAspect(square, 0.5, 'sw');
+    // bottom edge (30) stays fixed; height = width / aspect... width kept? currentAspect(1) < aspect? no aspect=0.5 <1
+    // currentAspect(1) > aspect(0.5) -> keep width(20), height = width/aspect = 40
+    expect(result).toEqual({ x: 10, y: -10, width: 20, height: 40 });
+  });
+
+  it('keeps the se corner fixed', () => {
+    const result = constrainAspect(square, 2, 'se');
+    expect(result).toEqual({ x: -10, y: 10, width: 40, height: 20 });
+  });
+
+  it('keeps the center fixed', () => {
+    const result = constrainAspect(square, 2, 'center');
+    expect(result).toEqual({ x: 0, y: 10, width: 40, height: 20 });
+  });
+
+  it('is a no-op-ish passthrough for a non-positive aspect or empty rect', () => {
+    expect(constrainAspect(square, 0, 'nw')).toEqual(square);
+    expect(constrainAspect(square, -1, 'nw')).toEqual(square);
+    const empty: Rect = { x: 0, y: 0, width: 0, height: 10 };
+    expect(constrainAspect(empty, 2, 'nw')).toEqual(empty);
+  });
+
+  it('leaves an already-matching aspect rect unchanged in size', () => {
+    const wide: Rect = { x: 0, y: 0, width: 40, height: 20 };
+    const result = constrainAspect(wide, 2, 'center');
+    expect(result.width).toBeCloseTo(40, 8);
+    expect(result.height).toBeCloseTo(20, 8);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/math/snapping.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/snapping.ts
new file mode 100644
index 00000000000..70c849277f7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/math/snapping.ts
@@ -0,0 +1,110 @@
+/**
+ * Pure snapping/clamping helpers for zoom, grid, and aspect-ratio math.
+ *
+ * No classes, no mutation — every function returns a new value.
+ */
+
+import type { Rect } from '@workbench/canvas-engine/types';
+
+/** Zoom levels the viewport snaps to when close enough. Single source of truth for the HUD. */
+export const ZOOM_SNAP_CANDIDATES: readonly number[] = [0.25, 0.33, 0.5, 0.67, 0.75, 1, 1.25, 1.5, 2, 3, 4, 5];
+
+/** Relative tolerance (fraction of the candidate value) used by `snapZoom`. */
+export const ZOOM_SNAP_TOLERANCE = 0.03;
+
+/** Minimum allowed zoom, used by `clampZoom`. */
+export const ZOOM_MIN = 0.1;
+
+/** Maximum allowed zoom, used by `clampZoom`. */
+export const ZOOM_MAX = 20;
+
+/**
+ * Snaps `zoom` to the nearest of `candidates` if it's within a ~3% relative
+ * tolerance of that candidate; otherwise returns `zoom` unchanged.
+ */
+export const snapZoom = (zoom: number, candidates: readonly number[] = ZOOM_SNAP_CANDIDATES): number => {
+  let closest: number | null = null;
+  let closestDelta = Infinity;
+  for (const candidate of candidates) {
+    const delta = Math.abs(zoom - candidate);
+    if (delta < closestDelta) {
+      closestDelta = delta;
+      closest = candidate;
+    }
+  }
+  if (closest === null) {
+    return zoom;
+  }
+  const tolerance = closest * ZOOM_SNAP_TOLERANCE;
+  return closestDelta <= tolerance ? closest : zoom;
+};
+
+/** Clamps `zoom` to `[ZOOM_MIN, ZOOM_MAX]`. */
+export const clampZoom = (zoom: number): number => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, zoom));
+
+/** Snaps a single value to the nearest multiple of `grid`. Returns `value` unchanged if `grid <= 0`. */
+export const snapToGrid = (value: number, grid: number): number => {
+  if (grid <= 0) {
+    return value;
+  }
+  return Math.round(value / grid) * grid;
+};
+
+/** Snaps a rect's position and size to the nearest multiple of `grid`. */
+export const snapRectToGrid = (rect: Rect, grid: number): Rect => {
+  const x = snapToGrid(rect.x, grid);
+  const y = snapToGrid(rect.y, grid);
+  const right = snapToGrid(rect.x + rect.width, grid);
+  const bottom = snapToGrid(rect.y + rect.height, grid);
+  return { x, y, width: right - x, height: bottom - y };
+};
+
+/** The corner or center kept fixed when `constrainAspect` resizes a rect. */
+export type AspectAnchor = 'nw' | 'ne' | 'sw' | 'se' | 'center';
+
+/**
+ * Resizes `rect` to match `aspect` (width / height), keeping the named
+ * anchor point fixed. The rect's area is preserved as closely as possible
+ * by scaling both dimensions from the current size to fit the target
+ * aspect ratio (the dimension that would grow beyond the current bounding
+ * box is chosen based on which axis needs less change).
+ */
+export const constrainAspect = (rect: Rect, aspect: number, anchor: AspectAnchor): Rect => {
+  if (aspect <= 0 || rect.width <= 0 || rect.height <= 0) {
+    return rect;
+  }
+
+  const currentAspect = rect.width / rect.height;
+  let width: number;
+  let height: number;
+
+  if (currentAspect > aspect) {
+    // Too wide for the target aspect: keep width, shrink/grow height to match.
+    width = rect.width;
+    height = width / aspect;
+  } else {
+    // Too tall (or exact): keep height, shrink/grow width to match.
+    height = rect.height;
+    width = height * aspect;
+  }
+
+  const left = rect.x;
+  const top = rect.y;
+  const right = rect.x + rect.width;
+  const bottom = rect.y + rect.height;
+  const centerX = rect.x + rect.width / 2;
+  const centerY = rect.y + rect.height / 2;
+
+  switch (anchor) {
+    case 'nw':
+      return { x: left, y: top, width, height };
+    case 'ne':
+      return { x: right - width, y: top, width, height };
+    case 'sw':
+      return { x: left, y: bottom - height, width, height };
+    case 'se':
+      return { x: right - width, y: bottom - height, width, height };
+    case 'center':
+      return { x: centerX - width / 2, y: centerY - height / 2, width, height };
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustedSurfaceCache.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustedSurfaceCache.test.ts
new file mode 100644
index 00000000000..f06df528437
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustedSurfaceCache.test.ts
@@ -0,0 +1,105 @@
+import type { CanvasAdjustmentsContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import type { LayerCacheEntry } from './layerCache';
+import type { StubRasterSurface } from './raster.testStub';
+
+import { createAdjustedSurfaceCache } from './adjustedSurfaceCache';
+import { createTestStubRasterBackend } from './raster.testStub';
+
+const BRIGHTEN: CanvasAdjustmentsContract = { brightness: 0.5, contrast: 0, saturation: 0 };
+const CONTRAST: CanvasAdjustmentsContract = { brightness: 0, contrast: 0.5, saturation: 0 };
+
+const makeEntry = (layerId: string, surface: StubRasterSurface, version = 0): LayerCacheEntry => ({
+  hasPublishedPixels: true,
+  lastUsed: 0,
+  layerId,
+  rect: { height: surface.height, width: surface.width, x: 0, y: 0 },
+  stale: false,
+  surface,
+  version,
+});
+
+const drawImageCount = (surface: StubRasterSurface): number =>
+  surface.callLog.filter((entry) => entry.op === 'drawImage').length;
+
+describe('createAdjustedSurfaceCache', () => {
+  it('returns null (and caches nothing) for identity adjustments', () => {
+    const backend = createTestStubRasterBackend();
+    const cache = createAdjustedSurfaceCache(backend);
+    const entry = makeEntry('a', backend.createSurface(10, 10));
+    expect(cache.get('a', entry, undefined)).toBeNull();
+    expect(cache.get('a', entry, { brightness: 0, contrast: 0, saturation: 0 })).toBeNull();
+    expect(cache.size()).toBe(0);
+  });
+
+  it('builds and reuses the adjusted surface while version + adjustments are unchanged', () => {
+    const backend = createTestStubRasterBackend();
+    const cache = createAdjustedSurfaceCache(backend);
+    const entry = makeEntry('a', backend.createSurface(10, 10));
+
+    const first = cache.get('a', entry, BRIGHTEN);
+    expect(first).not.toBeNull();
+    const stub = first as StubRasterSurface;
+    expect(drawImageCount(stub)).toBe(1);
+
+    // Same version + key: reuse the same surface, no rebuild.
+    const second = cache.get('a', entry, BRIGHTEN);
+    expect(second).toBe(first);
+    expect(drawImageCount(stub)).toBe(1);
+    expect(cache.size()).toBe(1);
+    expect(cache.byteSize()).toBe(10 * 10 * 4);
+  });
+
+  it('rebuilds when the adjustments value changes', () => {
+    const backend = createTestStubRasterBackend();
+    const cache = createAdjustedSurfaceCache(backend);
+    const entry = makeEntry('a', backend.createSurface(10, 10));
+
+    const first = cache.get('a', entry, BRIGHTEN) as StubRasterSurface;
+    expect(drawImageCount(first)).toBe(1);
+    // Different adjustments → rebuild (draws again into the reused surface).
+    cache.get('a', entry, CONTRAST);
+    expect(drawImageCount(first)).toBe(2);
+  });
+
+  it('invalidates only the edited layer when its cache version bumps', () => {
+    const backend = createTestStubRasterBackend();
+    const cache = createAdjustedSurfaceCache(backend);
+    const entryA = makeEntry('a', backend.createSurface(10, 10), 0);
+    const entryB = makeEntry('b', backend.createSurface(10, 10), 0);
+
+    const surfaceA = cache.get('a', entryA, BRIGHTEN) as StubRasterSurface;
+    const surfaceB = cache.get('b', entryB, BRIGHTEN) as StubRasterSurface;
+    expect(drawImageCount(surfaceA)).toBe(1);
+    expect(drawImageCount(surfaceB)).toBe(1);
+
+    // Layer 'a' is edited: its cache version bumps → its adjusted surface rebuilds.
+    const editedA = makeEntry('a', surfaceA, 1);
+    const rebuiltA = cache.get('a', editedA, BRIGHTEN) as StubRasterSurface;
+    expect(rebuiltA).not.toBe(surfaceA);
+    expect(drawImageCount(rebuiltA)).toBe(1);
+
+    // Layer 'b' is untouched (same version) → reused, no rebuild.
+    const reusedB = cache.get('b', entryB, BRIGHTEN);
+    expect(reusedB).toBe(surfaceB);
+    expect(drawImageCount(surfaceB)).toBe(1);
+  });
+
+  it('drops a layer slot on delete and reverting to identity', () => {
+    const backend = createTestStubRasterBackend();
+    const cache = createAdjustedSurfaceCache(backend);
+    const entry = makeEntry('a', backend.createSurface(10, 10));
+    cache.get('a', entry, BRIGHTEN);
+    expect(cache.size()).toBe(1);
+    // Reverting to identity clears the slot.
+    expect(cache.get('a', entry, undefined)).toBeNull();
+    expect(cache.size()).toBe(0);
+    // Re-cache then delete.
+    cache.get('a', entry, BRIGHTEN);
+    cache.delete('a');
+    expect(cache.size()).toBe(0);
+    expect(cache.byteSize()).toBe(0);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustedSurfaceCache.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustedSurfaceCache.ts
new file mode 100644
index 00000000000..176e5c51cca
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustedSurfaceCache.ts
@@ -0,0 +1,105 @@
+/**
+ * A cached, non-destructive "adjusted surface" per raster layer.
+ *
+ * Raster adjustments (brightness/contrast/saturation + curves) must be applied at
+ * composite time WITHOUT recomputing every frame (the plan explicitly forbids a
+ * third per-frame recompute alongside the mask-colorize and control-transparency
+ * smells). This store memoizes each layer's adjusted pixels, keyed by the source
+ * cache's `version` AND the adjustments' identity ({@link adjustmentsKey}), and
+ * rebuilds only when either changes — so a steady frame reuses the cached surface,
+ * an edit to the layer (cache version bump) invalidates it, and an unrelated
+ * layer's edit does not.
+ *
+ * Everything flows through the injected {@link RasterBackend} seam, so it runs
+ * unchanged in node tests. Zero React, zero import-time side effects.
+ */
+
+import type { CanvasAdjustmentsContract } from '@workbench/types';
+
+import type { LayerCacheEntry } from './layerCache';
+import type { RasterBackend, RasterSurface } from './raster';
+
+import { adjustmentsKey, applyAdjustments, isIdentityAdjustments } from './adjustments';
+import { createDerivedSurfaceCache, type DerivedSurfaceCache } from './derivedSurfaceCache';
+
+/** The imperative adjusted-surface store returned by {@link createAdjustedSurfaceCache}. */
+export interface AdjustedSurfaceCache {
+  /**
+   * Returns a surface holding `entry`'s pixels with `adjustments` applied, or
+   * `null` when the adjustments are identity (the caller should draw the original
+   * cache surface). The returned surface is memoized: an unchanged
+   * `(entry.version, adjustmentsKey)` reuses it with zero pixel work.
+   */
+  get(
+    layerId: string,
+    entry: LayerCacheEntry,
+    adjustments: CanvasAdjustmentsContract | undefined
+  ): RasterSurface | null;
+  /** Drops a layer's memoized adjusted surface (e.g. on layer delete). */
+  delete(layerId: string): void;
+  /** Number of memoized adjusted surfaces (for tests / accounting). */
+  size(): number;
+  /** Bytes held by adjusted surfaces. */
+  byteSize(): number;
+  /** Releases all memoized surfaces. */
+  dispose(): void;
+}
+
+/** Creates an {@link AdjustedSurfaceCache} backed by the given {@link RasterBackend}. */
+export const createAdjustedSurfaceCache = (
+  backend: RasterBackend,
+  cache: DerivedSurfaceCache = createDerivedSurfaceCache()
+): AdjustedSurfaceCache => {
+  const get = (
+    layerId: string,
+    entry: LayerCacheEntry,
+    adjustments: CanvasAdjustmentsContract | undefined
+  ): RasterSurface | null => {
+    if (isIdentityAdjustments(adjustments)) {
+      // Identity: nothing to cache — drop any stale slot and let the caller draw
+      // the original surface.
+      cache.delete(layerId, 'adjustments');
+      return null;
+    }
+    const { height, width } = entry.surface;
+    if (width <= 0 || height <= 0) {
+      return null;
+    }
+    const key = adjustmentsKey(adjustments);
+    return cache.get({
+      create: (target) => {
+        const surface = target ?? backend.createSurface(width, height);
+        if (surface.width !== width || surface.height !== height) {
+          surface.resize(width, height);
+        }
+        const ctx = surface.ctx;
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        ctx.clearRect(0, 0, width, height);
+        ctx.globalAlpha = 1;
+        ctx.globalCompositeOperation = 'source-over';
+        ctx.drawImage(entry.surface.canvas, 0, 0);
+        const imageData = ctx.getImageData(0, 0, width, height);
+        applyAdjustments(imageData, adjustments);
+        ctx.putImageData(imageData, 0, 0);
+        return surface;
+      },
+      kind: 'adjustments',
+      layerId,
+      paramsKey: key,
+      source: entry.surface,
+      sourceVersion: entry.version,
+    });
+  };
+
+  return {
+    byteSize: cache.byteSize,
+    delete: (layerId) => {
+      cache.delete(layerId, 'adjustments');
+    },
+    dispose: () => {
+      cache.dispose();
+    },
+    get,
+    size: cache.size,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustments.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustments.test.ts
new file mode 100644
index 00000000000..8fbe92e6b73
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustments.test.ts
@@ -0,0 +1,211 @@
+import type { CanvasAdjustmentsContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  adjustmentsKey,
+  applyAdjustments,
+  buildAdjustmentLuts,
+  buildCurveLut,
+  DEFAULT_ADJUSTMENTS,
+  isIdentityAdjustments,
+} from './adjustments';
+
+/** Builds an ImageData-like object (node has no DOM ImageData; the shape is enough). */
+const imageData = (pixels: number[]): ImageData =>
+  ({ data: new Uint8ClampedArray(pixels), height: 1, width: pixels.length / 4 }) as ImageData;
+
+describe('buildCurveLut', () => {
+  it('is the identity for absent / empty / diagonal curves', () => {
+    for (const pts of [
+      undefined,
+      [],
+      [
+        [0, 0],
+        [255, 255],
+      ],
+    ] as const) {
+      const lut = buildCurveLut(pts as never);
+      expect(lut[0]).toBe(0);
+      expect(lut[128]).toBe(128);
+      expect(lut[255]).toBe(255);
+    }
+  });
+
+  it('clamps values outside the first/last control point to the endpoints', () => {
+    // A curve that starts at x=64 (y=0) and ends at x=192 (y=255): below 64 → 0, above 192 → 255.
+    const lut = buildCurveLut([
+      [64, 0],
+      [192, 255],
+    ]);
+    expect(lut[0]).toBe(0);
+    expect(lut[64]).toBe(0);
+    expect(lut[192]).toBe(255);
+    expect(lut[255]).toBe(255);
+    // Midpoint between the two knots is roughly mid grey.
+    expect(lut[128]).toBeGreaterThan(100);
+    expect(lut[128]).toBeLessThan(160);
+  });
+
+  it('interpolates monotonically through interior points without overshoot', () => {
+    const lut = buildCurveLut([
+      [0, 0],
+      [128, 200],
+      [255, 255],
+    ]);
+    // The 128 knot is honoured.
+    expect(lut[128]).toBe(200);
+    // Monotonic non-decreasing, always within [0, 255].
+    for (let i = 1; i < 256; i++) {
+      expect(lut[i]).toBeGreaterThanOrEqual(lut[i - 1]);
+      expect(lut[i]).toBeLessThanOrEqual(255);
+      expect(lut[i]).toBeGreaterThanOrEqual(0);
+    }
+  });
+});
+
+describe('buildAdjustmentLuts', () => {
+  it('is the identity for default adjustments', () => {
+    const { b, g, r } = buildAdjustmentLuts(DEFAULT_ADJUSTMENTS);
+    for (let i = 0; i < 256; i++) {
+      expect(r[i]).toBe(i);
+      expect(g[i]).toBe(i);
+      expect(b[i]).toBe(i);
+    }
+  });
+
+  it('applies additive brightness and clamps', () => {
+    const { r } = buildAdjustmentLuts({ brightness: 0.5, contrast: 0, saturation: 0 });
+    // +0.5*255 ≈ +128 (rounded).
+    expect(r[0]).toBe(128);
+    expect(r[200]).toBe(255); // clamped
+  });
+
+  it('applies contrast about mid-grey', () => {
+    const { r } = buildAdjustmentLuts({ brightness: 0, contrast: 1, saturation: 0 });
+    // factor 2 about 128: 128 stays, 0 → -128 clamp 0, 255 → 382 clamp 255.
+    expect(r[128]).toBe(128);
+    expect(r[0]).toBe(0);
+    expect(r[255]).toBe(255);
+    expect(r[64]).toBe(0); // (64-128)*2+128 = 0
+    expect(r[192]).toBe(255); // (192-128)*2+128 = 256 → clamp
+  });
+
+  it('composes curve → brightness → contrast', () => {
+    // A curve mapping everything to 100, then +0 brightness, contrast 0 → all 100.
+    const { r } = buildAdjustmentLuts({
+      brightness: 0,
+      contrast: 0,
+      curves: {
+        b: [
+          [0, 0],
+          [255, 255],
+        ],
+        g: [
+          [0, 0],
+          [255, 255],
+        ],
+        r: [
+          [0, 100],
+          [255, 100],
+        ],
+      },
+      saturation: 0,
+    });
+    expect(r[0]).toBe(100);
+    expect(r[255]).toBe(100);
+  });
+});
+
+describe('isIdentityAdjustments / adjustmentsKey', () => {
+  it('treats zeros + diagonal / absent curves as identity', () => {
+    expect(isIdentityAdjustments(undefined)).toBe(true);
+    expect(isIdentityAdjustments(DEFAULT_ADJUSTMENTS)).toBe(true);
+    expect(
+      isIdentityAdjustments({
+        brightness: 0,
+        contrast: 0,
+        saturation: 0,
+        curves: {
+          b: [
+            [0, 0],
+            [255, 255],
+          ],
+          g: [
+            [0, 0],
+            [255, 255],
+          ],
+          r: [
+            [0, 0],
+            [255, 255],
+          ],
+        },
+      })
+    ).toBe(true);
+    expect(adjustmentsKey(DEFAULT_ADJUSTMENTS)).toBe('identity');
+  });
+
+  it('is non-identity for any non-zero param or bent curve', () => {
+    expect(isIdentityAdjustments({ brightness: 0.1, contrast: 0, saturation: 0 })).toBe(false);
+    expect(
+      isIdentityAdjustments({
+        brightness: 0,
+        contrast: 0,
+        saturation: 0,
+        curves: {
+          b: [
+            [0, 0],
+            [255, 255],
+          ],
+          g: [
+            [0, 0],
+            [255, 255],
+          ],
+          r: [
+            [0, 0],
+            [128, 200],
+            [255, 255],
+          ],
+        },
+      })
+    ).toBe(false);
+  });
+
+  it('produces distinct, stable keys per distinct adjustment', () => {
+    const a: CanvasAdjustmentsContract = { brightness: 0.2, contrast: 0, saturation: 0 };
+    const b: CanvasAdjustmentsContract = { brightness: 0.3, contrast: 0, saturation: 0 };
+    expect(adjustmentsKey(a)).toBe(adjustmentsKey({ ...a }));
+    expect(adjustmentsKey(a)).not.toBe(adjustmentsKey(b));
+  });
+});
+
+describe('applyAdjustments', () => {
+  it('is a no-op for identity adjustments', () => {
+    const img = imageData([10, 20, 30, 255]);
+    applyAdjustments(img, DEFAULT_ADJUSTMENTS);
+    expect(Array.from(img.data)).toEqual([10, 20, 30, 255]);
+  });
+
+  it('never modifies alpha', () => {
+    const img = imageData([10, 20, 30, 128]);
+    applyAdjustments(img, { brightness: 0.5, contrast: 0, saturation: 0 });
+    expect(img.data[3]).toBe(128);
+  });
+
+  it('brightens rgb', () => {
+    const img = imageData([10, 20, 30, 255]);
+    applyAdjustments(img, { brightness: 0.5, contrast: 0, saturation: 0 });
+    expect(img.data[0]).toBe(138); // 10 + 128
+    expect(img.data[1]).toBe(148);
+    expect(img.data[2]).toBe(158);
+  });
+
+  it('fully desaturates to luma at saturation -1', () => {
+    const img = imageData([200, 100, 50, 255]);
+    applyAdjustments(img, { brightness: 0, contrast: 0, saturation: -1 });
+    const luma = Math.round(0.299 * 200 + 0.587 * 100 + 0.114 * 50);
+    expect(img.data[0]).toBe(luma);
+    expect(img.data[1]).toBe(luma);
+    expect(img.data[2]).toBe(luma);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustments.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustments.ts
new file mode 100644
index 00000000000..9548f80b41c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/adjustments.ts
@@ -0,0 +1,239 @@
+/**
+ * Pure raster-adjustment math (no DOM, no engine, no React).
+ *
+ * Turns a {@link CanvasAdjustmentsContract} into per-channel 256-entry lookup
+ * tables and applies them (plus saturation) to raw `ImageData`. Kept pure and
+ * allocation-conscious so it can drive BOTH the non-destructive display cache
+ * (`adjustedSurfaceCache.ts`) and the generation composite
+ * (`export/compositeForGeneration.ts`), and so its correctness is exhaustively
+ * node-testable without any canvas.
+ *
+ * ## Composition order (documented, tested)
+ *
+ * Per channel, a single LUT is built as `contrast(brightness(curve(i)))`:
+ *  1. **Curve** — the per-channel monotone-cubic curve remaps the raw value.
+ *  2. **Brightness** — additive offset (`+ brightness * 255`).
+ *  3. **Contrast** — linear scale about mid-grey (`(v - 128) * (1 + contrast) + 128`).
+ * The LUT is applied to R/G/B; alpha is never touched. **Saturation** is applied
+ * last, per pixel, on the post-LUT values (a luminance lerp), since it mixes
+ * channels and cannot be expressed as an independent per-channel LUT.
+ *
+ * All scalar params are in `[-1, 1]` with `0` = identity; curve control points
+ * are `[input, output]` pairs in `[0, 255]`.
+ */
+
+import type { CanvasAdjustmentsContract } from '@workbench/types';
+
+/** The identity adjustment (no brightness/contrast/saturation, no curves). */
+export const DEFAULT_ADJUSTMENTS: CanvasAdjustmentsContract = { brightness: 0, contrast: 0, saturation: 0 };
+
+const LUT_SIZE = 256;
+
+/** ITU-R BT.601 luma weights, matching legacy grayscale/lightness math. */
+const LUMA_R = 0.299;
+const LUMA_G = 0.587;
+const LUMA_B = 0.114;
+
+const clamp255 = (v: number): number => (v < 0 ? 0 : v > 255 ? 255 : v);
+
+type CurvePoints = readonly (readonly [number, number])[];
+
+/** True when a channel's curve points describe the identity mapping (absent, or exactly 0→0 / 255→255). */
+const isIdentityCurve = (points: CurvePoints | undefined): boolean => {
+  if (!points || points.length === 0) {
+    return true;
+  }
+  // Any 2-point curve that is exactly the diagonal is identity.
+  if (points.length === 2) {
+    const sorted = [...points].sort((a, b) => a[0] - b[0]);
+    const [p0, p1] = sorted;
+    return p0[0] === 0 && p0[1] === 0 && p1[0] === 255 && p1[1] === 255;
+  }
+  return false;
+};
+
+/**
+ * Builds a 256-entry LUT that maps input → output through the channel's curve
+ * control points using monotone-cubic (Fritsch–Carlson) interpolation, so the
+ * result never overshoots between points. Fewer than two points → identity.
+ * Values before the first / after the last point are clamped to that point's
+ * output (flat extension).
+ */
+export const buildCurveLut = (points: CurvePoints | undefined): Uint8ClampedArray => {
+  const lut = new Uint8ClampedArray(LUT_SIZE);
+  if (isIdentityCurve(points)) {
+    for (let i = 0; i < LUT_SIZE; i++) {
+      lut[i] = i;
+    }
+    return lut;
+  }
+
+  // Clean + sort + dedupe by x (keep the last y for a duplicated x).
+  const byX = new Map<number, number>();
+  for (const [x, y] of points as CurvePoints) {
+    byX.set(clamp255(Math.round(x)), clamp255(y));
+  }
+  const xs = [...byX.keys()].sort((a, b) => a - b);
+  if (xs.length < 2) {
+    for (let i = 0; i < LUT_SIZE; i++) {
+      lut[i] = i;
+    }
+    return lut;
+  }
+  const ys = xs.map((x) => byX.get(x) as number);
+
+  const n = xs.length;
+  // Secant slopes between consecutive points.
+  const delta: number[] = [];
+  for (let i = 0; i < n - 1; i++) {
+    const dx = xs[i + 1] - xs[i];
+    delta.push(dx === 0 ? 0 : (ys[i + 1] - ys[i]) / dx);
+  }
+  // Fritsch–Carlson tangents (m) enforcing monotonicity.
+  const m: number[] = Array.from({ length: n }, () => 0);
+  m[0] = delta[0];
+  m[n - 1] = delta[n - 2];
+  for (let i = 1; i < n - 1; i++) {
+    if (delta[i - 1] * delta[i] <= 0) {
+      m[i] = 0;
+    } else {
+      m[i] = (delta[i - 1] + delta[i]) / 2;
+    }
+  }
+  for (let i = 0; i < n - 1; i++) {
+    if (delta[i] === 0) {
+      m[i] = 0;
+      m[i + 1] = 0;
+      continue;
+    }
+    const a = m[i] / delta[i];
+    const b = m[i + 1] / delta[i];
+    const h = Math.hypot(a, b);
+    if (h > 3) {
+      const t = 3 / h;
+      m[i] = t * a * delta[i];
+      m[i + 1] = t * b * delta[i];
+    }
+  }
+
+  let seg = 0;
+  for (let i = 0; i < LUT_SIZE; i++) {
+    if (i <= xs[0]) {
+      lut[i] = ys[0];
+      continue;
+    }
+    if (i >= xs[n - 1]) {
+      lut[i] = ys[n - 1];
+      continue;
+    }
+    while (seg < n - 2 && i > xs[seg + 1]) {
+      seg += 1;
+    }
+    const x0 = xs[seg];
+    const x1 = xs[seg + 1];
+    const hSeg = x1 - x0;
+    const t = (i - x0) / hSeg;
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const h00 = 2 * t3 - 3 * t2 + 1;
+    const h10 = t3 - 2 * t2 + t;
+    const h01 = -2 * t3 + 3 * t2;
+    const h11 = t3 - t2;
+    const value = h00 * ys[seg] + h10 * hSeg * m[seg] + h01 * ys[seg + 1] + h11 * hSeg * m[seg + 1];
+    lut[i] = clamp255(Math.round(value));
+  }
+  return lut;
+};
+
+/**
+ * Builds the composed per-channel LUTs for `adjustments`:
+ * `contrast(brightness(curve(i)))`, clamped to `[0, 255]`. Brightness/contrast are
+ * shared across channels; the curve is per-channel.
+ */
+export const buildAdjustmentLuts = (
+  adjustments: CanvasAdjustmentsContract
+): { r: Uint8ClampedArray; g: Uint8ClampedArray; b: Uint8ClampedArray } => {
+  const brightnessOffset = (adjustments.brightness ?? 0) * 255;
+  const contrastFactor = 1 + (adjustments.contrast ?? 0);
+  const curves = adjustments.curves;
+
+  const compose = (curveLut: Uint8ClampedArray): Uint8ClampedArray => {
+    const out = new Uint8ClampedArray(LUT_SIZE);
+    for (let i = 0; i < LUT_SIZE; i++) {
+      const curved = curveLut[i];
+      const brightened = curved + brightnessOffset;
+      const contrasted = (brightened - 128) * contrastFactor + 128;
+      out[i] = clamp255(Math.round(contrasted));
+    }
+    return out;
+  };
+
+  return {
+    b: compose(buildCurveLut(curves?.b)),
+    g: compose(buildCurveLut(curves?.g)),
+    r: compose(buildCurveLut(curves?.r)),
+  };
+};
+
+/** True when `adjustments` is a no-op (identity brightness/contrast/saturation + identity curves). */
+export const isIdentityAdjustments = (adjustments: CanvasAdjustmentsContract | undefined): boolean => {
+  if (!adjustments) {
+    return true;
+  }
+  if ((adjustments.brightness ?? 0) !== 0 || (adjustments.contrast ?? 0) !== 0 || (adjustments.saturation ?? 0) !== 0) {
+    return false;
+  }
+  const { curves } = adjustments;
+  if (!curves) {
+    return true;
+  }
+  return isIdentityCurve(curves.r) && isIdentityCurve(curves.g) && isIdentityCurve(curves.b);
+};
+
+/** A deterministic cache key fully identifying an adjustment's pixel effect. */
+export const adjustmentsKey = (adjustments: CanvasAdjustmentsContract | undefined): string => {
+  if (isIdentityAdjustments(adjustments)) {
+    return 'identity';
+  }
+  const a = adjustments as CanvasAdjustmentsContract;
+  const curveKey = (pts: CurvePoints | undefined): string =>
+    pts && pts.length > 0 ? pts.map(([x, y]) => `${x},${y}`).join(';') : '-';
+  return [
+    `b${a.brightness ?? 0}`,
+    `c${a.contrast ?? 0}`,
+    `s${a.saturation ?? 0}`,
+    `r:${curveKey(a.curves?.r)}`,
+    `g:${curveKey(a.curves?.g)}`,
+    `bl:${curveKey(a.curves?.b)}`,
+  ].join('|');
+};
+
+/**
+ * Applies `adjustments` to `imageData` IN PLACE: the composed per-channel LUTs
+ * remap R/G/B, then saturation lerps each channel toward its luma. Alpha is never
+ * modified. A no-op for identity adjustments.
+ */
+export const applyAdjustments = (imageData: ImageData, adjustments: CanvasAdjustmentsContract | undefined): void => {
+  if (isIdentityAdjustments(adjustments)) {
+    return;
+  }
+  const a = adjustments as CanvasAdjustmentsContract;
+  const { b: lutB, g: lutG, r: lutR } = buildAdjustmentLuts(a);
+  const sat = 1 + (a.saturation ?? 0);
+  const applySaturation = sat !== 1;
+  const { data } = imageData;
+  for (let i = 0; i + 3 < data.length; i += 4) {
+    let r = lutR[data[i]];
+    let g = lutG[data[i + 1]];
+    let b = lutB[data[i + 2]];
+    if (applySaturation) {
+      const lum = LUMA_R * r + LUMA_G * g + LUMA_B * b;
+      r = clamp255(Math.round(lum + (r - lum) * sat));
+      g = clamp255(Math.round(lum + (g - lum) * sat));
+      b = clamp255(Math.round(lum + (b - lum) * sat));
+    }
+    data[i] = r;
+    data[i + 1] = g;
+    data[i + 2] = b;
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/colorSample.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/colorSample.test.ts
new file mode 100644
index 00000000000..c2cd0871825
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/colorSample.test.ts
@@ -0,0 +1,147 @@
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import type { RasterBackend, RasterSurface } from './raster';
+
+import { sampleDocumentColor } from './colorSample';
+import { createLayerCacheStore } from './layerCache';
+
+/** A fake surface that records `drawImage`/`setTransform` calls, for asserting traversal order and translation math. */
+interface FakeSurface extends RasterSurface {
+  drawnCanvases: unknown[];
+  transforms: number[][];
+}
+
+/** A {@link RasterBackend} test double that also exposes every surface it created, for assertions. */
+interface FixedPixelBackend extends RasterBackend {
+  __surfaces: FakeSurface[];
+}
+
+/**
+ * A minimal `RasterBackend` whose scratch surfaces report a single fixed pixel
+ * for every `getImageData` call — enough to test `sampleDocumentColor`'s
+ * bounds/alpha/traversal logic without modeling real canvas compositing.
+ */
+const createFixedPixelBackend = (pixel: readonly [number, number, number, number]): FixedPixelBackend => {
+  const createdSurfaces: FakeSurface[] = [];
+
+  return {
+    createImageBitmap: () => Promise.resolve({} as ImageBitmap),
+    createSurface: (width: number, height: number): FakeSurface => {
+      const drawnCanvases: unknown[] = [];
+      const transforms: number[][] = [];
+      const canvas = { height, width } as unknown as OffscreenCanvas;
+      const ctx = {
+        clearRect: () => {},
+        drawImage: (image: unknown) => drawnCanvases.push(image),
+        getImageData: () => ({ data: Uint8ClampedArray.from(pixel), height: 1, width: 1 }) as unknown as ImageData,
+        restore: () => {},
+        save: () => {},
+        setTransform: (...args: number[]) => transforms.push(args),
+      } as unknown as OffscreenCanvasRenderingContext2D;
+      const surface: FakeSurface = {
+        canvas,
+        ctx,
+        drawnCanvases,
+        height,
+        resize: () => {},
+        transforms,
+        width,
+      };
+      createdSurfaces.push(surface);
+      return surface;
+    },
+    encodeSurface: () => Promise.resolve(new Blob()),
+    __surfaces: createdSurfaces,
+  };
+};
+
+const rasterLayer = (id: string, overrides: Partial<CanvasRasterLayerContractV2> = {}): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+  ...overrides,
+});
+
+const makeDoc = (layers: CanvasLayerContract[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 100,
+});
+
+describe('sampleDocumentColor', () => {
+  it('returns null for a point outside the document bounds (never allocates a scratch surface)', () => {
+    const backend = createFixedPixelBackend([10, 20, 30, 255]);
+    const layers = createLayerCacheStore(backend);
+    const doc = makeDoc([]);
+
+    expect(sampleDocumentColor(doc, layers, backend, { x: -1, y: 5 })).toBeNull();
+    expect(sampleDocumentColor(doc, layers, backend, { x: 100, y: 5 })).toBeNull();
+    expect(sampleDocumentColor(doc, layers, backend, { x: 5, y: -1 })).toBeNull();
+    expect(sampleDocumentColor(doc, layers, backend, { x: 5, y: 100 })).toBeNull();
+    expect(backend.__surfaces).toHaveLength(0);
+  });
+
+  it('returns null when the composited pixel is fully transparent', () => {
+    const backend = createFixedPixelBackend([10, 20, 30, 0]);
+    const layers = createLayerCacheStore(backend);
+    const doc = makeDoc([rasterLayer('a')]);
+    layers.getOrCreate('a', 100, 100);
+
+    expect(sampleDocumentColor(doc, layers, backend, { x: 5, y: 5 })).toBeNull();
+  });
+
+  it('returns the composited rgba when the sampled pixel has non-zero alpha', () => {
+    const backend = createFixedPixelBackend([10, 20, 30, 128]);
+    const layers = createLayerCacheStore(backend);
+    const doc = makeDoc([rasterLayer('a')]);
+    layers.getOrCreate('a', 100, 100);
+
+    expect(sampleDocumentColor(doc, layers, backend, { x: 5, y: 5 })).toEqual({ a: 128, b: 30, g: 20, r: 10 });
+  });
+
+  it('draws renderable layers bottom-to-top, skipping disabled and uncached layers', () => {
+    const backend = createFixedPixelBackend([1, 2, 3, 255]);
+    const layers = createLayerCacheStore(backend);
+    const topEntry = layers.getOrCreate('top', 100, 100);
+    const bottomEntry = layers.getOrCreate('bottom', 100, 100);
+    // 'disabled' and 'nocache' are deliberately excluded from compositing.
+    const doc = makeDoc([
+      rasterLayer('top'),
+      rasterLayer('disabled', { isEnabled: false }),
+      rasterLayer('nocache'),
+      rasterLayer('bottom'),
+    ]);
+
+    sampleDocumentColor(doc, layers, backend, { x: 5, y: 5 });
+
+    const scratch = backend.__surfaces.at(-1)!;
+    expect(scratch.drawnCanvases).toEqual([bottomEntry.surface.canvas, topEntry.surface.canvas]);
+  });
+
+  it('translates the view so the floored sample point lands at the scratch origin', () => {
+    const backend = createFixedPixelBackend([1, 2, 3, 255]);
+    const layers = createLayerCacheStore(backend);
+    layers.getOrCreate('a', 100, 100);
+    const doc = makeDoc([rasterLayer('a')]);
+
+    sampleDocumentColor(doc, layers, backend, { x: 12.7, y: 34.2 });
+
+    const scratch = backend.__surfaces.at(-1)!;
+    // Identity layer transform composed with the sample-point translation: e/f
+    // carry the floored, negated point (no per-layer offset/scale/rotation).
+    // The last `setTransform` is the per-layer draw (the first is the initial reset).
+    expect(scratch.transforms.at(-1)).toEqual([1, 0, 0, 1, -12, -34]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/colorSample.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/colorSample.ts
new file mode 100644
index 00000000000..e4a59d82d83
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/colorSample.ts
@@ -0,0 +1,94 @@
+/**
+ * Samples the composited document color at a document-space point, for the
+ * color-picker tool. Composites just the renderable layers (bottom → top,
+ * respecting opacity/blend/transform, matching {@link compositeDocument}'s
+ * paint order) into a 1×1 scratch surface translated so the sampled pixel
+ * lands at its origin — cheap regardless of document size, since only one
+ * destination pixel is ever rasterized.
+ *
+ * The document background (solid fill or checkerboard) and the staged
+ * preview are intentionally excluded: a point with no layer coverage samples
+ * as fully transparent (`null`), not the page chrome.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Mat2d, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { isRenderableLayer } from '@workbench/canvas-engine/document/sources';
+import { fromTRS, multiply } from '@workbench/canvas-engine/math/mat2d';
+
+import type { LayerCacheStore } from './layerCache';
+import type { RasterBackend } from './raster';
+
+import { blendToComposite } from './compositor';
+
+/** An RGBA sample, channels in `[0, 255]`. */
+export interface RgbaSample {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+const matToTuple = (m: Mat2d): [number, number, number, number, number, number] => [m.a, m.b, m.c, m.d, m.e, m.f];
+
+/**
+ * Samples the composited document color at `docPoint` (document space;
+ * fractional coordinates are floored to the covering pixel). Returns `null`
+ * when the point falls outside the document, or when no renderable layer
+ * covers it with non-zero alpha there.
+ */
+export const sampleDocumentColor = (
+  doc: CanvasDocumentContractV2,
+  layers: LayerCacheStore,
+  backend: RasterBackend,
+  docPoint: Vec2
+): RgbaSample | null => {
+  const px = Math.floor(docPoint.x);
+  const py = Math.floor(docPoint.y);
+  if (px < 0 || py < 0 || px >= doc.width || py >= doc.height) {
+    return null;
+  }
+
+  const scratch = backend.createSurface(1, 1);
+  const ctx = scratch.ctx;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, 1, 1);
+  // Translate so the sampled document pixel lands at the scratch surface's
+  // one pixel (0, 0); each layer's own transform composes on top of this.
+  const view: Mat2d = { a: 1, b: 0, c: 0, d: 1, e: -px, f: -py };
+
+  // Bottom → top, matching the real compositor's paint order.
+  for (let i = doc.layers.length - 1; i >= 0; i--) {
+    const layer = doc.layers[i];
+    if (!layer || !isRenderableLayer(layer)) {
+      continue;
+    }
+    const entry = layers.get(layer.id);
+    if (!entry) {
+      continue;
+    }
+
+    ctx.save();
+    ctx.globalAlpha = layer.opacity;
+    ctx.globalCompositeOperation = blendToComposite(layer.blendMode);
+    const layerMat = fromTRS(
+      { x: layer.transform.x, y: layer.transform.y },
+      layer.transform.rotation,
+      layer.transform.scaleX,
+      layer.transform.scaleY
+    );
+    ctx.setTransform(...matToTuple(multiply(view, layerMat)));
+    ctx.drawImage(entry.surface.canvas, 0, 0);
+    ctx.restore();
+  }
+
+  const { data } = ctx.getImageData(0, 0, 1, 1);
+  const alpha = data[3] ?? 0;
+  if (alpha === 0) {
+    return null;
+  }
+  return { a: alpha, b: data[2] ?? 0, g: data[1] ?? 0, r: data[0] ?? 0 };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/compositor.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/compositor.test.ts
new file mode 100644
index 00000000000..d7b7d0f41f8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/compositor.test.ts
@@ -0,0 +1,624 @@
+import type { Mat2d } from '@workbench/canvas-engine/types';
+import type {
+  CanvasBlendMode,
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { createCanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+import { identity } from '@workbench/canvas-engine/math/mat2d';
+import { describe, expect, it } from 'vitest';
+
+import type { RasterCallLogEntry, StubRasterSurface } from './raster.testStub';
+
+import { compositeDocument, createCheckerboardTile, shouldSmoothAtZoom } from './compositor';
+import { createDerivedSurfaceCache } from './derivedSurfaceCache';
+import { createLayerCacheStore } from './layerCache';
+import { createTestStubRasterBackend } from './raster.testStub';
+
+const VIEW: Mat2d = identity();
+
+const imageRef = (): CanvasImageRef => ({ height: 10, imageName: 'x', width: 10 });
+
+const rasterLayer = (id: string, overrides: Partial<CanvasRasterLayerContractV2> = {}): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: imageRef(), type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+  ...overrides,
+});
+
+const maskLayer = (id: string): CanvasLayerContract => ({
+  autoNegative: false,
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#ff0000', style: 'solid' } },
+  name: id,
+  negativePrompt: null,
+  opacity: 1,
+  positivePrompt: null,
+  referenceImages: [],
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'regional_guidance',
+});
+
+const controlLayer = (id: string): CanvasLayerContract => ({
+  adapter: { beginEndStepPct: [0, 0.75], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: imageRef(), type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: false,
+});
+
+const inpaintMaskLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#00ff00', style: 'solid' } },
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+const makeDoc = (
+  layers: CanvasLayerContract[],
+  overrides: Partial<CanvasDocumentContractV2> = {}
+): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 100,
+  ...overrides,
+});
+
+/** Sets are recorded as { op: 'set', args: [prop, value] }; find the value for a prop. */
+const findSet = (log: RasterCallLogEntry[], prop: string): unknown[] =>
+  log.filter((e) => e.op === 'set' && e.args[0] === prop).map((e) => e.args[1]);
+
+describe('compositeDocument', () => {
+  it('clears then draws layer caches bottom-to-top (array index 0 is top-most)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    // top -> bottom in array order.
+    const top = rasterLayer('top');
+    const bottom = rasterLayer('bottom');
+    const topCache = caches.getOrCreate('top', 10, 10);
+    const bottomCache = caches.getOrCreate('bottom', 10, 10);
+
+    const target = backend.createSurface(200, 200);
+    compositeDocument(target, makeDoc([top, bottom]), caches, VIEW);
+
+    const log = target.callLog;
+    // First op is a clearRect (after the outer save + identity setTransform).
+    expect(log.some((e) => e.op === 'clearRect')).toBe(true);
+
+    const drawImages = log.filter((e) => e.op === 'drawImage');
+    expect(drawImages).toHaveLength(2);
+    // Bottom layer's canvas is drawn before the top layer's.
+    expect(drawImages[0]!.args[0]).toBe(bottomCache.surface.canvas);
+    expect(drawImages[1]!.args[0]).toBe(topCache.surface.canvas);
+  });
+
+  it('skips layers that are disabled', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('a', 10, 10);
+    caches.getOrCreate('b', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    const doc = makeDoc([rasterLayer('a', { isEnabled: false }), rasterLayer('b')]);
+    compositeDocument(target, doc, caches, VIEW);
+
+    const drawImages = target.callLog.filter((e) => e.op === 'drawImage');
+    expect(drawImages).toHaveLength(1);
+    expect(drawImages[0]!.args[0]).toBe(caches.get('b')!.surface.canvas);
+  });
+
+  it('isolates the named layer even when disabled and suppresses unrelated staged content', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const isolated = caches.getOrCreate('isolated', 10, 10);
+    caches.getOrCreate('other', 10, 10);
+    const filterPreview = backend.createSurface(10, 10);
+    const staged = backend.createSurface(10, 10);
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(
+      target,
+      makeDoc([rasterLayer('isolated', { isEnabled: false }), rasterLayer('other')]),
+      caches,
+      VIEW,
+      {
+        layerPreviews: new Map([['isolated', { rect: { height: 10, width: 10, x: 0, y: 0 }, surface: filterPreview }]]),
+        onlyLayerId: 'isolated',
+        stagedPreview: { rect: { height: 10, width: 10, x: 0, y: 0 }, surface: staged },
+      }
+    );
+
+    const drawImages = target.callLog.filter((entry) => entry.op === 'drawImage');
+    expect(drawImages).toHaveLength(1);
+    expect(drawImages[0]!.args[0]).toBe(isolated.surface.canvas);
+  });
+
+  it('preserves disabled-layer and staged-preview semantics when isolation is absent', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('disabled', 10, 10);
+    const visible = caches.getOrCreate('visible', 10, 10);
+    const staged = backend.createSurface(10, 10);
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(
+      target,
+      makeDoc([rasterLayer('disabled', { isEnabled: false }), rasterLayer('visible')]),
+      caches,
+      VIEW,
+      { stagedPreview: { rect: { height: 10, width: 10, x: 0, y: 0 }, surface: staged } }
+    );
+
+    const drawImages = target.callLog.filter((entry) => entry.op === 'drawImage');
+    expect(drawImages.map((entry) => entry.args[0])).toEqual([visible.surface.canvas, staged.canvas]);
+  });
+
+  it('skips the layer named by skipLayerId (open text-edit session)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('a', 10, 10);
+    caches.getOrCreate('b', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    const doc = makeDoc([rasterLayer('a'), rasterLayer('b')]);
+    compositeDocument(target, doc, caches, VIEW, { skipLayerId: 'a' });
+
+    const drawImages = target.callLog.filter((e) => e.op === 'drawImage');
+    // 'a' is skipped (its live text is shown by the contenteditable portal); only 'b' draws.
+    expect(drawImages).toHaveLength(1);
+    expect(drawImages[0]!.args[0]).toBe(caches.get('b')!.surface.canvas);
+  });
+
+  it('skips layers that have no cache entry yet', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('a', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    // 'b' has no cache; only 'a' should draw.
+    compositeDocument(target, makeDoc([rasterLayer('a'), rasterLayer('b')]), caches, VIEW);
+    expect(target.callLog.filter((e) => e.op === 'drawImage')).toHaveLength(1);
+  });
+
+  it('applies per-layer opacity and maps blend mode to a composite operation', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('a', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    const blend: CanvasBlendMode = 'multiply';
+    compositeDocument(target, makeDoc([rasterLayer('a', { blendMode: blend, opacity: 0.4 })]), caches, VIEW);
+
+    expect(findSet(target.callLog, 'globalAlpha')).toContain(0.4);
+    expect(findSet(target.callLog, 'globalCompositeOperation')).toContain('multiply');
+  });
+
+  it('applies control transparency, opacity, and blend mode to a filter preview', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('control', 10, 10);
+    const preview = backend.createSurface(10, 10);
+    const target = backend.createSurface(100, 100);
+    const layer = {
+      ...controlLayer('control'),
+      blendMode: 'multiply' as const,
+      opacity: 0.4,
+      withTransparencyEffect: true,
+    };
+
+    compositeDocument(target, makeDoc([layer]), caches, VIEW, {
+      backend,
+      layerPreviews: new Map([['control', { rect: { height: 14, width: 16, x: -2, y: -3 }, surface: preview }]]),
+    });
+
+    const draw = target.callLog.find((entry) => entry.op === 'drawImage');
+    expect(draw?.args[0]).not.toBe(preview.canvas);
+    expect(draw?.args.slice(1)).toEqual([-2, -3]);
+    expect(findSet(target.callLog, 'globalAlpha')).toContain(0.4);
+    expect(findSet(target.callLog, 'globalCompositeOperation')).toContain('multiply');
+  });
+
+  it("maps the 'normal' blend mode to 'source-over'", () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('a', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(target, makeDoc([rasterLayer('a', { blendMode: 'normal' })]), caches, VIEW);
+    expect(findSet(target.callLog, 'globalCompositeOperation')).toContain('source-over');
+  });
+
+  it('fills the ENTIRE viewport with the checkerboard pattern (unbounded plane)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const tile = createCheckerboardTile(backend);
+
+    const target = backend.createSurface(200, 200);
+    compositeDocument(target, makeDoc([], { background: 'transparent' }), caches, VIEW, { checkerboardTile: tile });
+
+    // The pattern is created once from the tile (cheap: no per-cell fill loop).
+    const patternCalls = target.callLog.filter((e) => e.op === 'createPattern');
+    expect(patternCalls).toHaveLength(1);
+    expect(patternCalls[0]!.args[0]).toBe(tile.canvas);
+    expect(patternCalls[0]!.args[1]).toBe('repeat');
+
+    // The whole 200x200 target is filled with the pattern — NOT clipped to the
+    // 100x100 doc rect (the document is no longer a visual boundary).
+    const fills = target.callLog.filter((e) => e.op === 'fillRect');
+    expect(fills).toHaveLength(1);
+    expect(fills[0]!.args).toEqual([0, 0, 200, 200]);
+    // fillStyle was set to the pattern object (the stub's non-null marker), not a color string.
+    const styles = findSet(target.callLog, 'fillStyle');
+    expect(styles).toHaveLength(1);
+    expect(typeof styles[0]).toBe('object');
+  });
+
+  it('fills the full viewport regardless of the doc rect position/size (offset + scaled view)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const tile = createCheckerboardTile(backend);
+
+    // A tiny doc, panned far off-origin under a scaled view: the checker still
+    // covers the whole screen because it is screen-anchored, not doc-anchored.
+    const view: Mat2d = { a: 3, b: 0, c: 0, d: 3, e: -500, f: 220 };
+    const target = backend.createSurface(320, 240);
+    compositeDocument(target, makeDoc([], { height: 8, width: 8 }), caches, view, { checkerboardTile: tile });
+
+    const fills = target.callLog.filter((e) => e.op === 'fillRect');
+    expect(fills).toHaveLength(1);
+    expect(fills[0]!.args).toEqual([0, 0, 320, 240]);
+  });
+
+  it('draws NO checkerboard when the tile is absent (toggle off), leaving bg.inset through', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+
+    const target = backend.createSurface(200, 200);
+    compositeDocument(target, makeDoc([], { background: 'transparent' }), caches, VIEW);
+
+    // No tile → no pattern and no fill; the cleared surface shows the widget's bg.inset.
+    expect(target.callLog.some((e) => e.op === 'createPattern')).toBe(false);
+    expect(target.callLog.filter((e) => e.op === 'fillRect')).toHaveLength(0);
+    // The whole target is still cleared each frame.
+    expect(target.callLog.some((e) => e.op === 'clearRect')).toBe(true);
+  });
+
+  it('ignores the contract background field (checker fills the viewport even for a color background)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+
+    const solidTarget = backend.createSurface(200, 200);
+    // The `background` field no longer renders: a color-background doc with the
+    // checkerboard on still fills the whole viewport with the pattern, not a flat color.
+    compositeDocument(solidTarget, makeDoc([], { background: { color: '#123456' } }), caches, VIEW, {
+      checkerboardTile: createCheckerboardTile(backend),
+    });
+    const patternCalls = solidTarget.callLog.filter((e) => e.op === 'createPattern');
+    expect(patternCalls).toHaveLength(1);
+    const fills = solidTarget.callLog.filter((e) => e.op === 'fillRect');
+    expect(fills).toHaveLength(1);
+    expect(fills[0]!.args).toEqual([0, 0, 200, 200]);
+    // The flat color is never applied.
+    expect(findSet(solidTarget.callLog, 'fillStyle')).not.toContain('#123456');
+  });
+
+  it('builds the checker tile with the given colors on the diagonal', () => {
+    const backend = createTestStubRasterBackend();
+    const tile = createCheckerboardTile(backend, { a: '#111111', b: '#222222' }) as StubRasterSurface;
+    // The tile's two fillStyle sets are exactly the fed colors (base then diagonal).
+    const styles = findSet(tile.callLog, 'fillStyle');
+    expect(styles).toEqual(['#111111', '#222222']);
+  });
+
+  it('draws mask-bearing layers as a tinted fill of the mask color (backend-less fallback)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('rg', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(target, makeDoc([maskLayer('rg')]), caches, VIEW);
+
+    // Without a backend the mask draws its coverage then tints with a flat fill.
+    expect(target.callLog.some((e) => e.op === 'drawImage')).toBe(true);
+    expect(findSet(target.callLog, 'fillStyle')).toContain('#ff0000');
+  });
+
+  it('colorizes the mask alpha via source-in on an intermediate surface when a backend is supplied', () => {
+    const base = createTestStubRasterBackend();
+    const created: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        created.push(surface);
+        return surface;
+      },
+    };
+    const caches = createLayerCacheStore(backend);
+    const maskEntry = caches.getOrCreate('rg', 10, 10) as unknown as { surface: StubRasterSurface };
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(target, makeDoc([maskLayer('rg')]), caches, VIEW, { backend });
+
+    // The colorize happens on a NEW intermediate surface (not the target, not the
+    // mask cache): it blits the stencil then fills source-in with the fill colour.
+    const colorized = created.find(
+      (s) =>
+        s !== target &&
+        s !== maskEntry.surface &&
+        s.callLog.some((e) => e.op === 'set' && e.args[0] === 'globalCompositeOperation' && e.args[1] === 'source-in')
+    );
+    expect(colorized).toBeDefined();
+    expect(findSet(colorized!.callLog, 'fillStyle')).toContain('#ff0000');
+    // The colorized overlay is then blitted onto the target.
+    expect(target.callLog.some((e) => e.op === 'drawImage')).toBe(true);
+  });
+
+  it('performs no effect allocations or pixel readbacks on a warmed unchanged composite', () => {
+    const base = createTestStubRasterBackend();
+    const created: StubRasterSurface[] = [];
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        const surface = base.createSurface(w, h);
+        created.push(surface);
+        return surface;
+      },
+    };
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('control', 10, 10);
+    caches.getOrCreate('mask', 10, 10);
+    const target = backend.createSurface(100, 100);
+    const derivedSurfaces = createDerivedSurfaceCache();
+    const control = controlLayer('control');
+    if (control.type !== 'control') {
+      throw new Error('Expected control fixture');
+    }
+    const doc = makeDoc([{ ...control, withTransparencyEffect: true }, maskLayer('mask')]);
+
+    compositeDocument(target, doc, caches, VIEW, { backend, derivedSurfaces });
+    const allocationsAfterWarmup = created.length;
+    const readbacksAfterWarmup = created.reduce(
+      (count, surface) => count + surface.callLog.filter((entry) => entry.op === 'getImageData').length,
+      0
+    );
+
+    compositeDocument(target, doc, caches, VIEW, { backend, derivedSurfaces });
+    expect(created).toHaveLength(allocationsAfterWarmup);
+    expect(
+      created.reduce(
+        (count, surface) => count + surface.callLog.filter((entry) => entry.op === 'getImageData').length,
+        0
+      )
+    ).toBe(readbacksAfterWarmup);
+  });
+
+  it('culls a fully offscreen effect layer before derived work or drawing', () => {
+    const base = createTestStubRasterBackend();
+    let allocations = 0;
+    const backend = {
+      ...base,
+      createSurface: (w: number, h: number): StubRasterSurface => {
+        allocations += 1;
+        return base.createSurface(w, h);
+      },
+    };
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('control', 10, 10);
+    const target = backend.createSurface(100, 100);
+    const control = controlLayer('control');
+    if (control.type !== 'control') {
+      throw new Error('Expected control fixture');
+    }
+    const doc = makeDoc([{ ...control, transform: { ...control.transform, x: 1_000 }, withTransparencyEffect: true }]);
+    const allocationsBeforeComposite = allocations;
+    const diagnostics = createCanvasDiagnostics(true);
+
+    compositeDocument(target, doc, caches, VIEW, {
+      backend,
+      derivedSurfaces: createDerivedSurfaceCache(),
+      diagnostics,
+    });
+
+    expect(allocations).toBe(allocationsBeforeComposite);
+    expect(target.callLog.filter((entry) => entry.op === 'drawImage')).toHaveLength(0);
+    expect(diagnostics.snapshot()).toMatchObject({
+      compositeFrames: 1,
+      layersConsidered: 1,
+      layersCulled: 1,
+      layersDrawn: 0,
+    });
+  });
+
+  it('draws mask layers ABOVE all non-mask layers regardless of their global z position', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    // A mask placed at the BOTTOM of the z-order (last in the array) must still be
+    // composited after (above) the raster layer above it.
+    caches.getOrCreate('raster', 10, 10);
+    caches.getOrCreate('mask', 10, 10);
+    const target = backend.createSurface(200, 200) as StubRasterSurface;
+
+    const doc = makeDoc([rasterLayer('raster'), maskLayer('mask')]);
+    compositeDocument(target, doc, caches, VIEW, { backend });
+
+    // The mask's source-in colorize marks its draw pass; it must come AFTER the
+    // last raster blit. Find the first source-in op (mask pass) and assert every
+    // non-mask blit already ran — i.e. the mask pass draws last.
+    const firstDrawImage = target.callLog.findIndex((e) => e.op === 'drawImage');
+    expect(firstDrawImage).toBeGreaterThanOrEqual(0);
+    // Two draws land on the target: the raster blit, then the colorized mask blit;
+    // the mask blit is the LAST drawImage.
+    const drawIdxs = target.callLog.map((e, i) => (e.op === 'drawImage' ? i : -1)).filter((i) => i >= 0);
+    expect(drawIdxs.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('composites in strict group order: raster < control < regional < inpaint mask, ignoring global index', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    // Distinct cache sizes so each layer's blit is identifiable by source width
+    // (masks blit a colorized intermediate sized to their cache, not the cache
+    // surface itself, so identity matching won't work — width does).
+    caches.getOrCreate('raster', 10, 10);
+    caches.getOrCreate('control', 11, 11);
+    caches.getOrCreate('regional', 12, 12);
+    caches.getOrCreate('inpaint', 13, 13);
+    const widthToId: Record<number, string> = { 10: 'raster', 11: 'control', 12: 'regional', 13: 'inpaint' };
+    const target = backend.createSurface(200, 200) as StubRasterSurface;
+
+    // Deliberately SCRAMBLED array order (index 0 = top-most): a raster created
+    // above a control layer, masks interleaved below. Group order must win.
+    const doc = makeDoc([
+      rasterLayer('raster'),
+      inpaintMaskLayer('inpaint'),
+      controlLayer('control'),
+      maskLayer('regional'),
+    ]);
+    compositeDocument(target, doc, caches, VIEW, { backend });
+
+    const order = target.callLog
+      .filter((e) => e.op === 'drawImage')
+      .map((e) => widthToId[(e.args[0] as { width: number }).width])
+      .filter((id): id is string => id !== undefined);
+
+    // Raster (bottom) first, then control, then the masks — regardless of array index.
+    expect(order.indexOf('raster')).toBeLessThan(order.indexOf('control'));
+    expect(order.indexOf('control')).toBeLessThan(order.indexOf('regional'));
+    expect(order.indexOf('regional')).toBeLessThan(order.indexOf('inpaint'));
+  });
+
+  it('disables image smoothing for the composite when imageSmoothing is false (zoomed-in policy)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('a', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(target, makeDoc([rasterLayer('a')]), caches, VIEW, { imageSmoothing: false });
+    // The smoothing flag is set exactly once, to false, so every layer/staged
+    // blit up-scales nearest-neighbor (crisp + cheap) rather than bilinear.
+    expect(findSet(target.callLog, 'imageSmoothingEnabled')).toEqual([false]);
+  });
+
+  it('enables image smoothing by default and when imageSmoothing is true (down-scale/quality)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    caches.getOrCreate('a', 10, 10);
+
+    const defaulted = backend.createSurface(200, 200);
+    compositeDocument(defaulted, makeDoc([rasterLayer('a')]), caches, VIEW);
+    expect(findSet(defaulted.callLog, 'imageSmoothingEnabled')).toEqual([true]);
+
+    const explicit = backend.createSurface(200, 200);
+    compositeDocument(explicit, makeDoc([rasterLayer('a')]), caches, VIEW, { imageSmoothing: true });
+    expect(findSet(explicit.callLog, 'imageSmoothingEnabled')).toEqual([true]);
+  });
+
+  it('draws a staged preview over its bbox when provided', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const target = backend.createSurface(200, 200);
+    const staged = backend.createSurface(50, 50);
+
+    compositeDocument(target, makeDoc([]), caches, VIEW, {
+      stagedPreview: { rect: { height: 40, width: 40, x: 5, y: 5 }, surface: staged },
+    });
+
+    const drawImages = target.callLog.filter((e) => e.op === 'drawImage');
+    expect(drawImages).toHaveLength(1);
+    expect(drawImages[0]!.args).toEqual([staged.canvas, 5, 5, 40, 40]);
+  });
+
+  it('draws a placed staged preview at its candidate opacity and keeps the pending outline opaque', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const target = backend.createSurface(200, 200);
+    const staged = backend.createSurface(23, 17);
+
+    compositeDocument(target, makeDoc([]), caches, VIEW, {
+      stagedPreview: {
+        opacity: 0.35,
+        rect: { height: 34, width: 46, x: -8, y: 13 },
+        surface: staged,
+      },
+    });
+
+    const drawImages = target.callLog.filter((entry) => entry.op === 'drawImage');
+    expect(drawImages).toHaveLength(1);
+    expect(drawImages[0]!.args).toEqual([staged.canvas, -8, 13, 46, 34]);
+    expect(findSet(target.callLog, 'globalAlpha')).toEqual([0.35, 1]);
+  });
+});
+
+describe('compositeDocument — raster adjustments', () => {
+  it('draws the provided adjusted surface instead of the raw cache for a raster layer', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const layer = rasterLayer('a', { adjustments: { brightness: 0.5, contrast: 0, saturation: 0 } });
+    const cache = caches.getOrCreate('a', 10, 10);
+    const adjusted = backend.createSurface(10, 10);
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(target, makeDoc([layer]), caches, VIEW, {
+      adjustedSurface: (l) => (l.id === 'a' ? adjusted : null),
+    });
+
+    const drawImages = target.callLog.filter((e) => e.op === 'drawImage');
+    expect(drawImages).toHaveLength(1);
+    // The adjusted surface's canvas is drawn, NOT the raw cache surface.
+    expect(drawImages[0]!.args[0]).toBe(adjusted.canvas);
+    expect(drawImages[0]!.args[0]).not.toBe(cache.surface.canvas);
+  });
+
+  it('draws the raw cache when the provider returns null (identity / no adjustments)', () => {
+    const backend = createTestStubRasterBackend();
+    const caches = createLayerCacheStore(backend);
+    const layer = rasterLayer('a');
+    const cache = caches.getOrCreate('a', 10, 10);
+    const target = backend.createSurface(200, 200);
+
+    compositeDocument(target, makeDoc([layer]), caches, VIEW, { adjustedSurface: () => null });
+
+    const drawImages = target.callLog.filter((e) => e.op === 'drawImage');
+    expect(drawImages[0]!.args[0]).toBe(cache.surface.canvas);
+  });
+});
+
+describe('shouldSmoothAtZoom', () => {
+  it('smooths only when the document is down-scaled (zoom < 1)', () => {
+    expect(shouldSmoothAtZoom(0.1)).toBe(true);
+    expect(shouldSmoothAtZoom(0.5)).toBe(true);
+    expect(shouldSmoothAtZoom(0.99)).toBe(true);
+    // At or above 1× the document is magnified: keep pixels crisp and skip the
+    // per-frame bilinear up-scale whose cost grows with zoom.
+    expect(shouldSmoothAtZoom(1)).toBe(false);
+    expect(shouldSmoothAtZoom(4)).toBe(false);
+    expect(shouldSmoothAtZoom(20)).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/compositor.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/compositor.ts
new file mode 100644
index 00000000000..d80aa00a6b2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/compositor.ts
@@ -0,0 +1,473 @@
+/**
+ * Composites a canvas document onto a target surface.
+ *
+ * Draws (in order): a clear + a viewport-filling checkerboard (the unbounded
+ * plane's surround; omitted when the checkerboard is off), then each layer's
+ * cached surface from bottom to top applying opacity / blend mode / transform,
+ * and finally an optional staged-generation preview. Layers without a cache entry are
+ * skipped — rasterization is the caller's job (see `rasterizers/` +
+ * `layerCache.ts`); this module only draws what's already cached.
+ *
+ * Every pixel operation flows through the {@link RasterSurface} `ctx`, which
+ * in tests is the recording stub, so composite order is assertable in node.
+ * Zero React, zero import-time side effects.
+ */
+
+import type { CanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+import type { Mat2d, Rect, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasBlendMode, CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { LAYER_GROUP_COUNT, layerGroupRank } from '@workbench/canvas-engine/document/sources';
+import { fromTRS, multiply } from '@workbench/canvas-engine/math/mat2d';
+import { intersect, transformBounds } from '@workbench/canvas-engine/math/rect';
+
+import type { DerivedSurfaceCache } from './derivedSurfaceCache';
+import type { LayerCacheEntry, LayerCacheStore } from './layerCache';
+import type { RasterBackend, RasterSurface } from './raster';
+
+import { renderControlTransparency } from './controlTransparency';
+import { colorizeMask } from './maskFill';
+
+/** Screen-space size (px) of each checkerboard square for transparent backgrounds. */
+export const CHECKERBOARD_SQUARE_PX = 8;
+
+/**
+ * CSS-zoom threshold at/above which image smoothing is disabled while
+ * compositing. See {@link shouldSmoothAtZoom}.
+ */
+export const SMOOTHING_MAX_ZOOM = 1;
+
+/**
+ * Image-smoothing policy for compositing at a given CSS zoom.
+ *
+ * Smoothing is enabled only when the document is DOWN-scaled (`zoom < 1`) —
+ * bilinear interpolation keeps a shrunk image clean. When zoomed IN
+ * (`zoom >= 1`) the document is up-scaled to fill the screen; smoothing is
+ * disabled so (a) pixels stay crisp when magnified — the behavior legacy pixel
+ * editors adopt above ~1× — and (b) the browser skips the per-frame bilinear
+ * interpolation of an ever-larger upscale, whose fill-rate cost is precisely
+ * what grows with zoom. Nearest-neighbor upscaling is dramatically cheaper.
+ */
+export const shouldSmoothAtZoom = (zoom: number): boolean => zoom < SMOOTHING_MAX_ZOOM;
+
+/** The two square colors of the transparency checkerboard. */
+export interface CheckerColors {
+  /** The base color, filled across the whole tile. */
+  a: string;
+  /** The alternating color, drawn on the tile's diagonal cells. */
+  b: string;
+}
+
+/**
+ * Fallback checkerboard colors when no theme tokens have been fed to the engine
+ * (node tests, first frame before React resolves the tokens). Deliberately DARK,
+ * theme-appropriate greys (in the spirit of the legacy dark transparency pattern)
+ * so the indicator reads as "empty" against the dark workbench surface. In the
+ * app these are replaced by resolved Chakra semantic tokens (see
+ * `widgets/canvas/checkerColors.ts`).
+ */
+export const DEFAULT_CHECKER_COLORS: CheckerColors = { a: '#2a2a2a', b: '#363636' };
+
+/**
+ * Fallback tint alpha for a mask-bearing layer drawn WITHOUT a backend (a bare
+ * {@link compositeDocument} call in a minimal test): the mask coverage is blitted
+ * and a translucent flat fill laid over it. The real path (with a backend)
+ * colorizes the mask alpha via `source-in` at the layer opacity, matching legacy.
+ */
+export const MASK_TINT_ALPHA = 0.5;
+
+/** Dashed outline drawn around a staged-generation preview so it reads as pending, not committed. */
+const STAGED_PREVIEW_OUTLINE_COLOR = '#3b82f6';
+const STAGED_PREVIEW_OUTLINE_WIDTH = 2;
+const STAGED_PREVIEW_OUTLINE_DASH = 6;
+
+/** Optional inputs to {@link compositeDocument}. */
+export interface CompositeOptions {
+  /** Clips document layers to this document-space rect without clipping the background or staged preview. */
+  clipRect?: Rect | null;
+  /** A staged generation candidate to draw at its placement (document space). */
+  stagedPreview?: { surface: RasterSurface; rect: Rect; opacity?: number } | null;
+  /**
+   * The cached checkerboard pattern tile (see {@link createCheckerboardTile}) to
+   * fill the ENTIRE viewport with (the canvas is an unbounded plane — the checker
+   * is the world, not a document backdrop). Omit or pass `null` to draw NO
+   * checkerboard (the "checkerboard off" state) — the cleared surface then shows
+   * the widget's themed `bg.inset` through it.
+   */
+  checkerboardTile?: RasterSurface | null;
+  /**
+   * Whether `imageSmoothingEnabled` is on for this composite's `drawImage`
+   * blits (layer caches + staged preview). Defaults to `true` (the browser
+   * default) so non-viewport callers are unaffected; the engine feeds
+   * {@link shouldSmoothAtZoom} so zoomed-in frames composite crisp and cheap.
+   */
+  imageSmoothing?: boolean;
+  /**
+   * Transient per-layer transform overrides (a live move/transform preview): a
+   * layer with an entry here is drawn through the overridden transform instead of
+   * its committed one. `scaleX`/`scaleY`/`rotation` fall back to the committed
+   * transform when absent (the move tool overrides only `x`/`y`). The mirror stays
+   * untouched.
+   */
+  transformOverrides?: ReadonlyMap<
+    string,
+    { x: number; y: number; scaleX?: number; scaleY?: number; rotation?: number }
+  > | null;
+  /**
+   * A layer id to SKIP entirely (draw nothing for it). Used while a text-edit
+   * session is open: the contenteditable portal shows the layer's live text
+   * instead, so drawing its committed pixels underneath would double up. `null`
+   * (or absent) skips nothing.
+   */
+  skipLayerId?: string | null;
+  /**
+   * The raster backend, needed to colorize mask layers (an intermediate surface
+   * holds the alpha stencil while the fill is composited `source-in`). When
+   * absent, mask layers fall back to the flat-tint approximation
+   * ({@link MASK_TINT_ALPHA}); the engine always supplies it.
+   */
+  backend?: RasterBackend | null;
+  /**
+   * Returns a cached repeat tile for a mask fill (style, colour), or `null` for a
+   * solid fill (drawn directly). The engine caches tiles by `style:color` (like
+   * the checkerboard). Absent ⇒ solid fills only.
+   */
+  maskPatternTile?: ((style: string, color: string) => RasterSurface | null) | null;
+  /**
+   * Transient per-layer content previews (a non-destructive control-filter
+   * preview): a layer with an entry here draws the preview surface at its returned
+   * layer-local output rect, through the layer transform, INSTEAD of
+   * its committed cache, so the document is untouched until the filter is applied.
+   * `null`/absent ⇒ no previews.
+   */
+  layerPreviews?: ReadonlyMap<string, { surface: RasterSurface; rect: Rect }> | null;
+  /** When set, transiently composites only this layer (even if disabled) and suppresses staged content. */
+  onlyLayerId?: string | null;
+  /**
+   * Returns a raster layer's ADJUSTED cache surface (brightness/contrast/
+   * saturation/curves applied), or `null` when the layer has identity (or no)
+   * adjustments — in which case the committed cache surface is drawn directly.
+   * The engine wires this to a memoizing {@link
+   * import('./adjustedSurfaceCache').AdjustedSurfaceCache} so the adjusted pixels
+   * are NOT recomputed each frame (see that module). Only consulted for raster
+   * layers; absent ⇒ adjustments are ignored (a bare test call draws raw pixels).
+   */
+  adjustedSurface?: ((layer: CanvasLayerContract, entry: LayerCacheEntry) => RasterSurface | null) | null;
+  /** Shared memoized surfaces for mask and control display effects. */
+  derivedSurfaces?: DerivedSurfaceCache | null;
+  /** Optional deterministic render counters; omitted in the normal zero-overhead path. */
+  diagnostics?: CanvasDiagnostics | null;
+}
+
+type Ctx = RasterSurface['ctx'];
+
+/** Maps a document blend mode to the canvas `globalCompositeOperation`. Also used by `colorSample.ts`. */
+export const blendToComposite = (mode: CanvasBlendMode): GlobalCompositeOperation =>
+  mode === 'normal' ? 'source-over' : (mode as GlobalCompositeOperation);
+
+const setTransformFromMat = (ctx: Ctx, m: Mat2d): void => {
+  ctx.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
+};
+
+const identityTransform = (ctx: Ctx): void => {
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+};
+
+const getEffectiveLayerMatrix = (layer: CanvasLayerContract, opts: CompositeOptions): Mat2d => {
+  const override = opts.transformOverrides?.get(layer.id);
+  return fromTRS(
+    { x: override?.x ?? layer.transform.x, y: override?.y ?? layer.transform.y },
+    override?.rotation ?? layer.transform.rotation,
+    override?.scaleX ?? layer.transform.scaleX,
+    override?.scaleY ?? layer.transform.scaleY
+  );
+};
+
+const isDefinitelyOffscreen = (
+  layer: CanvasLayerContract,
+  entry: LayerCacheEntry,
+  view: Mat2d,
+  target: RasterSurface,
+  opts: CompositeOptions
+): boolean => {
+  const bounds = transformBounds(multiply(view, getEffectiveLayerMatrix(layer, opts)), entry.rect);
+  if (![bounds.x, bounds.y, bounds.width, bounds.height].every(Number.isFinite)) {
+    return false;
+  }
+  return intersect(bounds, { height: target.height, width: target.width, x: 0, y: 0 }) === null;
+};
+
+/**
+ * Builds a small, reusable two-tone checkerboard tile (a 2×2 grid of `squarePx`
+ * cells) through the {@link RasterBackend} seam. The engine creates this ONCE and
+ * feeds it back via {@link CompositeOptions.checkerboardTile}; each frame then
+ * only `createPattern`s over it, so no per-cell fill loop runs per frame.
+ */
+export const createCheckerboardTile = (
+  backend: RasterBackend,
+  colors: CheckerColors = DEFAULT_CHECKER_COLORS,
+  squarePx: number = CHECKERBOARD_SQUARE_PX
+): RasterSurface => {
+  const size = squarePx * 2;
+  const tile = backend.createSurface(size, size);
+  const ctx = tile.ctx;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, size, size);
+  // Base color across the whole tile, then the alternating cells on the diagonal.
+  ctx.fillStyle = colors.a;
+  ctx.fillRect(0, 0, size, size);
+  ctx.fillStyle = colors.b;
+  ctx.fillRect(0, 0, squarePx, squarePx);
+  ctx.fillRect(squarePx, squarePx, squarePx, squarePx);
+  return tile;
+};
+
+/**
+ * Fills the ENTIRE viewport with the checkerboard pattern. The canvas is a
+ * virtually infinite plane (like legacy): the checker IS the world surround, not
+ * a document backdrop — the document rect is no longer a visual boundary, so the
+ * contract's `background` field no longer renders. When no tile is provided the
+ * checkerboard is off and the cleared surface shows the widget's `bg.inset`.
+ *
+ * The pattern is laid with the identity transform in place, anchoring its cells
+ * to the screen (canvas) origin at a fixed pixel size — like legacy, which pins
+ * the pattern to the stage — so it stays visually stable and never swims or
+ * scales while panning/zooming.
+ */
+const drawBackground = (ctx: Ctx, target: RasterSurface, tile: RasterSurface | null): void => {
+  if (!tile) {
+    // Checkerboard disabled: leave the cleared surface showing `bg.inset`.
+    return;
+  }
+  const pattern = ctx.createPattern(tile.canvas, 'repeat');
+  if (!pattern) {
+    return;
+  }
+  ctx.fillStyle = pattern;
+  ctx.fillRect(0, 0, target.width, target.height);
+};
+
+const isMaskLayer = (
+  layer: CanvasLayerContract
+): layer is Extract<CanvasLayerContract, { type: 'regional_guidance' | 'inpaint_mask' }> =>
+  layer.type === 'regional_guidance' || layer.type === 'inpaint_mask';
+
+/**
+ * Draws a mask-bearing layer as a TINTED, TRANSLUCENT overlay. With a backend
+ * available (the engine path) it colorizes the mask's alpha stencil with the
+ * layer's fill colour/pattern (`source-in`) on an intermediate surface, then
+ * blits that through the current (already transformed, `globalAlpha =
+ * layer.opacity`) context — legacy's `source-in` compositing-rect technique.
+ * Without a backend it falls back to blitting the coverage plus a flat
+ * translucent fill.
+ */
+const drawMaskLayer = (
+  ctx: Ctx,
+  layer: Extract<CanvasLayerContract, { type: 'regional_guidance' | 'inpaint_mask' }>,
+  surface: RasterSurface,
+  sourceVersion: number,
+  origin: Vec2,
+  opts: CompositeOptions
+): void => {
+  const fill = layer.mask.fill;
+  if (opts.backend) {
+    const tile = opts.maskPatternTile ? opts.maskPatternTile(fill.style, fill.color) : null;
+    const colorized = opts.derivedSurfaces
+      ? opts.derivedSurfaces.get({
+          create: (target) => colorizeMask(opts.backend!, surface, surface.width, surface.height, fill, tile, target),
+          kind: 'mask-fill',
+          layerId: layer.id,
+          paramsKey: `${fill.style}:${fill.color}`,
+          source: surface,
+          sourceVersion,
+        })
+      : colorizeMask(opts.backend, surface, surface.width, surface.height, fill, tile);
+    // The outer loop already set globalAlpha = layer.opacity; blit the colorized
+    // overlay at the mask's local content origin.
+    ctx.drawImage(colorized.canvas, origin.x, origin.y);
+    return;
+  }
+  // Backend-less fallback (bare test call): coverage + flat translucent fill.
+  ctx.drawImage(surface.canvas, origin.x, origin.y);
+  ctx.globalAlpha = layer.opacity * MASK_TINT_ALPHA;
+  ctx.fillStyle = fill.color;
+  ctx.fillRect(origin.x, origin.y, surface.width, surface.height);
+};
+
+/**
+ * Draws one cached layer through its transform, applying opacity/blend and any
+ * transient transform override. Mask-bearing layers are colorized; everything
+ * else is a straight blit of its content-sized cache surface.
+ */
+const drawCachedLayer = (
+  ctx: Ctx,
+  layer: CanvasLayerContract,
+  entry: LayerCacheEntry,
+  view: Mat2d,
+  opts: CompositeOptions
+): void => {
+  ctx.save();
+  ctx.globalAlpha = layer.opacity;
+  ctx.globalCompositeOperation = blendToComposite(layer.blendMode);
+
+  const layerMat = getEffectiveLayerMatrix(layer, opts);
+  setTransformFromMat(ctx, multiply(view, layerMat));
+
+  // The cache surface holds pixels for `entry.rect` in layer-local space; draw
+  // it at that local origin (offset paint/mask layers place their content off-zero).
+  const origin = { x: entry.rect.x, y: entry.rect.y };
+  const preview = opts.onlyLayerId ? null : (opts.layerPreviews?.get(layer.id) ?? null);
+  if (preview) {
+    // Non-destructive filter preview: draw the full backend output at its
+    // layer-local rect (through the already-applied layer transform), including
+    // the same display-only control transparency effect used after commit.
+    const displayPreview =
+      layer.type === 'control' && layer.withTransparencyEffect && opts.backend
+        ? opts.derivedSurfaces
+          ? opts.derivedSurfaces.get({
+              create: (target) =>
+                renderControlTransparency(
+                  opts.backend!,
+                  preview.surface,
+                  preview.surface.width,
+                  preview.surface.height,
+                  target
+                ),
+              kind: 'control-transparency',
+              layerId: layer.id,
+              paramsKey: 'preview',
+              source: preview.surface,
+              sourceVersion: 0,
+            })
+          : renderControlTransparency(opts.backend, preview.surface, preview.surface.width, preview.surface.height)
+        : preview.surface;
+    ctx.drawImage(displayPreview.canvas, preview.rect.x, preview.rect.y);
+  } else if (isMaskLayer(layer)) {
+    drawMaskLayer(ctx, layer, entry.surface, entry.version, origin, opts);
+  } else if (layer.type === 'control' && layer.withTransparencyEffect && opts.backend) {
+    // Display-only lightness→alpha effect (legacy `LightnessToAlphaFilter`): dark
+    // areas of the control map drop out so underlying content shows through.
+    const effect = opts.derivedSurfaces
+      ? opts.derivedSurfaces.get({
+          create: (target) =>
+            renderControlTransparency(opts.backend!, entry.surface, entry.surface.width, entry.surface.height, target),
+          kind: 'control-transparency',
+          layerId: layer.id,
+          paramsKey: 'committed',
+          source: entry.surface,
+          sourceVersion: entry.version,
+        })
+      : renderControlTransparency(opts.backend, entry.surface, entry.surface.width, entry.surface.height);
+    ctx.drawImage(effect.canvas, origin.x, origin.y);
+  } else {
+    // Raster layers may carry non-destructive adjustments; the engine supplies a
+    // memoized adjusted surface (never recomputed per frame). Fall back to the raw
+    // cache when there are no adjustments or no provider.
+    const adjusted = layer.type === 'raster' && opts.adjustedSurface ? opts.adjustedSurface(layer, entry) : null;
+    ctx.drawImage((adjusted ?? entry.surface).canvas, origin.x, origin.y);
+  }
+
+  ctx.restore();
+};
+
+/**
+ * Composites `doc` onto `target`, using `caches` for each layer's pixels and
+ * `view` as the document→screen transform.
+ */
+export const compositeDocument = (
+  target: RasterSurface,
+  doc: CanvasDocumentContractV2,
+  caches: LayerCacheStore,
+  view: Mat2d,
+  opts: CompositeOptions = {}
+): void => {
+  const ctx = target.ctx;
+  opts.diagnostics?.increment('compositeFrames');
+
+  ctx.save();
+
+  // Smoothing policy for all layer/staged `drawImage` blits below. Set once
+  // under the outer save (inner per-layer save/restore preserves it). Off when
+  // zoomed in keeps magnified pixels crisp and skips the costly bilinear upscale.
+  ctx.imageSmoothingEnabled = opts.imageSmoothing ?? true;
+
+  // Clear the whole target in screen space, then lay the checkerboard across the
+  // entire viewport — the canvas is an unbounded plane, so the checker is the
+  // world, not a document backdrop. With the checkerboard off the cleared surface
+  // shows the widget's themed `bg.inset` through it.
+  identityTransform(ctx);
+  ctx.clearRect(0, 0, target.width, target.height);
+  drawBackground(ctx, target, opts.checkerboardTile ?? null);
+
+  if (opts.clipRect) {
+    ctx.save();
+    setTransformFromMat(ctx, view);
+    ctx.beginPath();
+    ctx.rect(opts.clipRect.x, opts.clipRect.y, opts.clipRect.width, opts.clipRect.height);
+    ctx.clip();
+  }
+
+  // Composite in STRICT GROUP ORDER (legacy `arrangeEntities` / `CanvasEntityRendererModule`):
+  // raster (bottom) < control < regional guidance < inpaint mask (top). This
+  // matches the layers panel, which renders these as fixed grouped sections, and
+  // makes a layer's global insertion index irrelevant ACROSS groups (a raster
+  // created after a control layer must still draw below it). WITHIN a group the
+  // panel/array relative order is preserved. The `stagedPreview` lands on top of
+  // all groups below. Index 0 is top-most, so iterate the array in reverse.
+  const drawGroup = (rank: number): void => {
+    for (let i = doc.layers.length - 1; i >= 0; i--) {
+      const layer = doc.layers[i];
+      if (
+        !layer ||
+        (!layer.isEnabled && layer.id !== opts.onlyLayerId) ||
+        layer.id === opts.skipLayerId ||
+        (opts.onlyLayerId && layer.id !== opts.onlyLayerId) ||
+        layerGroupRank(layer) !== rank
+      ) {
+        continue;
+      }
+      opts.diagnostics?.increment('layersConsidered');
+      const entry = caches.get(layer.id);
+      // Skip layers with no cache or an empty content rect (a brand-new / cleared
+      // paint / mask layer holds no pixels — nothing to draw).
+      if (!entry || entry.rect.width <= 0 || entry.rect.height <= 0) {
+        continue;
+      }
+      if (isDefinitelyOffscreen(layer, entry, view, target, opts)) {
+        opts.diagnostics?.increment('layersCulled');
+        continue;
+      }
+      drawCachedLayer(ctx, layer, entry, view, opts);
+      opts.diagnostics?.increment('layersDrawn');
+    }
+  };
+  for (let rank = 0; rank < LAYER_GROUP_COUNT; rank++) {
+    drawGroup(rank);
+  }
+
+  if (opts.clipRect) {
+    ctx.restore();
+  }
+
+  // Staged generation preview over its bbox (document space), with a subtle
+  // dashed outline so the pending result reads distinctly from committed pixels.
+  const staged = opts.onlyLayerId ? null : opts.stagedPreview;
+  if (staged) {
+    ctx.save();
+    setTransformFromMat(ctx, view);
+    ctx.globalAlpha = staged.opacity ?? 1;
+    ctx.drawImage(staged.surface.canvas, staged.rect.x, staged.rect.y, staged.rect.width, staged.rect.height);
+    // Keep the outline visually constant regardless of zoom by dividing the
+    // document-space stroke by the view scale (√det of the linear part).
+    const viewScale = Math.sqrt(Math.abs(view.a * view.d - view.b * view.c)) || 1;
+    ctx.globalAlpha = 1;
+    ctx.strokeStyle = STAGED_PREVIEW_OUTLINE_COLOR;
+    ctx.lineWidth = STAGED_PREVIEW_OUTLINE_WIDTH / viewScale;
+    ctx.setLineDash([STAGED_PREVIEW_OUTLINE_DASH / viewScale, STAGED_PREVIEW_OUTLINE_DASH / viewScale]);
+    ctx.strokeRect(staged.rect.x, staged.rect.y, staged.rect.width, staged.rect.height);
+    ctx.setLineDash([]);
+    ctx.restore();
+  }
+
+  ctx.restore();
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/controlTransparency.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/controlTransparency.test.ts
new file mode 100644
index 00000000000..2e2feb91e2c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/controlTransparency.test.ts
@@ -0,0 +1,193 @@
+import { describe, expect, it } from 'vitest';
+
+import type { RasterBackend, RasterSurface } from './raster';
+
+import { applyLightnessToAlpha, renderControlTransparency } from './controlTransparency';
+
+/** Builds a flat RGBA `Uint8ClampedArray` from a list of [r, g, b, a] pixels. */
+const pixels = (...rgba: [number, number, number, number][]): Uint8ClampedArray => new Uint8ClampedArray(rgba.flat());
+
+describe('applyLightnessToAlpha', () => {
+  it('sets alpha to the HSL lightness of each pixel, clamped to the existing alpha', () => {
+    const data = pixels(
+      [255, 255, 255, 255], // white: lightness 255 -> alpha stays 255
+      [0, 0, 0, 255], // black: lightness 0 -> alpha becomes 0
+      [128, 128, 128, 255], // mid-gray: lightness 128 -> alpha 128
+      [100, 50, 200, 255], // colored: min 50, max 200 -> lightness 125 -> alpha 125
+      [255, 255, 255, 100] // opaque-white but a=100: lightness 255, min(100, 255) keeps 100
+    );
+
+    applyLightnessToAlpha(data);
+
+    // Assert the resulting alpha channel for each pixel.
+    expect(data[3]).toBe(255);
+    expect(data[7]).toBe(0);
+    expect(data[11]).toBe(128);
+    expect(data[15]).toBe(125);
+    expect(data[19]).toBe(100);
+  });
+
+  it('leaves the RGB channels untouched', () => {
+    const data = pixels(
+      [255, 255, 255, 255],
+      [0, 0, 0, 255],
+      [128, 128, 128, 255],
+      [100, 50, 200, 255],
+      [255, 255, 255, 100]
+    );
+
+    applyLightnessToAlpha(data);
+
+    // Only the alpha byte of every quad may change; the RGB bytes are preserved.
+    expect([data[0], data[1], data[2]]).toEqual([255, 255, 255]);
+    expect([data[4], data[5], data[6]]).toEqual([0, 0, 0]);
+    expect([data[8], data[9], data[10]]).toEqual([128, 128, 128]);
+    expect([data[12], data[13], data[14]]).toEqual([100, 50, 200]);
+    expect([data[16], data[17], data[18]]).toEqual([255, 255, 255]);
+  });
+
+  it('mutates the buffer in place and returns void', () => {
+    const data = pixels([0, 0, 0, 255]);
+    const same = data;
+
+    const result = applyLightnessToAlpha(data);
+
+    // Same reference, mutated in place; the function returns nothing.
+    expect(result).toBeUndefined();
+    expect(data).toBe(same);
+    expect(same[3]).toBe(0);
+  });
+
+  it('handles an empty buffer without throwing', () => {
+    const data = new Uint8ClampedArray(0);
+    expect(() => applyLightnessToAlpha(data)).not.toThrow();
+    expect(data).toHaveLength(0);
+  });
+});
+
+/** A minimal `RasterSurface` recording drawImage/getImageData/putImageData against a fed bitmap. */
+interface FakeSurface extends RasterSurface {
+  readonly drawImageArgs: unknown[][];
+  readonly getImageDataArgs: unknown[][];
+  readonly putImageDataCalls: ImageData[];
+}
+
+/**
+ * A minimal but faithful `RasterBackend` for `renderControlTransparency`: every
+ * surface's `getImageData` returns a fresh copy of `sourcePixels`, and its
+ * `putImageData` is recorded so the transform's output can be inspected.
+ */
+const createFakeBackend = (sourcePixels: Uint8ClampedArray): RasterBackend & { readonly created: FakeSurface[] } => {
+  const created: FakeSurface[] = [];
+
+  const createSurface = (width: number, height: number): FakeSurface => {
+    const drawImageArgs: unknown[][] = [];
+    const getImageDataArgs: unknown[][] = [];
+    const putImageDataCalls: ImageData[] = [];
+
+    const ctx = {
+      clearRect: () => {},
+      drawImage: (...args: unknown[]) => {
+        drawImageArgs.push(args);
+      },
+      getImageData: (...args: unknown[]): ImageData => {
+        getImageDataArgs.push(args);
+        // Return a fresh copy so callers mutate their own buffer, not the source.
+        const data = new Uint8ClampedArray(sourcePixels);
+        return { colorSpace: 'srgb', data, height, width } as unknown as ImageData;
+      },
+      globalAlpha: 1,
+      globalCompositeOperation: 'source-over' as GlobalCompositeOperation,
+      putImageData: (imageData: ImageData) => {
+        putImageDataCalls.push(imageData);
+      },
+      setTransform: () => {},
+    } as unknown as OffscreenCanvasRenderingContext2D;
+
+    const surface: FakeSurface = {
+      canvas: { height, width } as unknown as OffscreenCanvas,
+      ctx,
+      drawImageArgs,
+      getImageDataArgs,
+      height,
+      putImageDataCalls,
+      resize: () => {},
+      width,
+    };
+    created.push(surface);
+    return surface;
+  };
+
+  return {
+    createImageBitmap: () => Promise.resolve({ close: () => {}, height: 0, width: 0 } as unknown as ImageBitmap),
+    createSurface,
+    created,
+    encodeSurface: (surface: RasterSurface, type = 'image/png') =>
+      Promise.resolve(new Blob([`fake-${surface.width}x${surface.height}`], { type })),
+  };
+};
+
+describe('renderControlTransparency', () => {
+  it('allocates the output surface at the requested dimensions', () => {
+    const backend = createFakeBackend(pixels([0, 0, 0, 255]));
+    const cache = backend.createSurface(64, 48);
+
+    const out = renderControlTransparency(backend, cache, 64, 48);
+
+    expect(out.width).toBe(64);
+    expect(out.height).toBe(48);
+    // The returned surface is a NEW allocation, not the cache itself.
+    expect(out).not.toBe(cache);
+  });
+
+  it('draws the cache canvas into the output surface', () => {
+    const backend = createFakeBackend(pixels([0, 0, 0, 255]));
+    const cache = backend.createSurface(10, 10);
+
+    const out = renderControlTransparency(backend, cache, 10, 10) as FakeSurface;
+
+    // The cache's canvas is blitted into the output at the origin.
+    expect(out.drawImageArgs).toHaveLength(1);
+    expect(out.drawImageArgs[0]![0]).toBe(cache.canvas);
+    expect(out.drawImageArgs[0]!.slice(1)).toEqual([0, 0]);
+  });
+
+  it('applies the lightness->alpha transform: opaque black pixels become fully transparent', () => {
+    // Feed a bitmap of opaque black pixels; after the transform each alpha is 0.
+    const backend = createFakeBackend(pixels([0, 0, 0, 255], [0, 0, 0, 255]));
+    const cache = backend.createSurface(2, 1);
+
+    const out = renderControlTransparency(backend, cache, 2, 1) as FakeSurface;
+
+    // getImageData was read over the full surface rect, and the result put back.
+    expect(out.getImageDataArgs).toHaveLength(1);
+    expect(out.getImageDataArgs[0]).toEqual([0, 0, 2, 1]);
+    expect(out.putImageDataCalls).toHaveLength(1);
+
+    const result = out.putImageDataCalls[0]!.data;
+    // Black -> lightness 0 -> alpha 0; RGB channels are preserved.
+    expect(result[3]).toBe(0);
+    expect(result[7]).toBe(0);
+    expect([result[0], result[1], result[2]]).toEqual([0, 0, 0]);
+  });
+
+  it('applies the lightness->alpha transform to a mixed bitmap', () => {
+    const backend = createFakeBackend(
+      pixels(
+        [255, 255, 255, 255], // white -> alpha 255
+        [0, 0, 0, 255], // black -> alpha 0
+        [100, 50, 200, 255] // colored -> lightness 125 -> alpha 125
+      )
+    );
+    const cache = backend.createSurface(3, 1);
+
+    const out = renderControlTransparency(backend, cache, 3, 1) as FakeSurface;
+
+    const result = out.putImageDataCalls[0]!.data;
+    expect(result[3]).toBe(255);
+    expect(result[7]).toBe(0);
+    expect(result[11]).toBe(125);
+    // RGB untouched by the transform.
+    expect([result[8], result[9], result[10]]).toEqual([100, 50, 200]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/controlTransparency.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/controlTransparency.ts
new file mode 100644
index 00000000000..20f99b3a6e0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/controlTransparency.ts
@@ -0,0 +1,64 @@
+/**
+ * The control-layer transparency effect (legacy `LightnessToAlphaFilter`).
+ *
+ * A control layer with `withTransparencyEffect` renders its source so DARK areas
+ * become transparent — for an edge/depth/pose map, the black background drops out
+ * and the underlying content shows through. This mirrors legacy
+ * `features/controlLayers/konva/filters.ts`: per pixel, HSL lightness
+ * `(min(r,g,b) + max(r,g,b)) / 2` becomes the new alpha, clamped to never EXCEED
+ * the pixel's existing alpha.
+ *
+ * It is DISPLAY-ONLY: at generation time the control image is composited at full
+ * opacity with NO transparency effect (see `generation/canvas/compositePlan.ts`
+ * `toControlLayerRef`), exactly like legacy (which rasterizes control with
+ * `filters: []`, `bg: 'black'`).
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterBackend, RasterSurface } from './raster';
+
+/**
+ * Applies the lightness→alpha transform to an RGBA pixel buffer in place: each
+ * pixel's alpha becomes `min(alpha, lightness)` where `lightness` is the HSL
+ * lightness of its RGB. Pure — the unit-testable core of the effect.
+ */
+export const applyLightnessToAlpha = (data: Uint8ClampedArray): void => {
+  for (let i = 0; i + 3 < data.length; i += 4) {
+    const r = data[i] ?? 0;
+    const g = data[i + 1] ?? 0;
+    const b = data[i + 2] ?? 0;
+    const a = data[i + 3] ?? 0;
+    const lightness = (Math.min(r, g, b) + Math.max(r, g, b)) / 2;
+    data[i + 3] = Math.min(a, lightness);
+  }
+};
+
+/**
+ * Produces a transparency-effect copy of a control layer's cache surface (same
+ * dimensions): the cache is drawn, its pixels transformed by
+ * {@link applyLightnessToAlpha}, and the result returned. The caller blits it
+ * through the layer transform in place of the raw cache.
+ */
+export const renderControlTransparency = (
+  backend: RasterBackend,
+  cache: RasterSurface,
+  width: number,
+  height: number,
+  target: RasterSurface | null = null
+): RasterSurface => {
+  const out = target ?? backend.createSurface(width, height);
+  if (out.width !== width || out.height !== height) {
+    out.resize(width, height);
+  }
+  const ctx = out.ctx;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+  ctx.globalAlpha = 1;
+  ctx.globalCompositeOperation = 'source-over';
+  ctx.drawImage(cache.canvas, 0, 0);
+  const imageData = ctx.getImageData(0, 0, width, height);
+  applyLightnessToAlpha(imageData.data);
+  ctx.putImageData(imageData, 0, 0);
+  return out;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/decodedBitmapPool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/decodedBitmapPool.test.ts
new file mode 100644
index 00000000000..21238816486
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/decodedBitmapPool.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createDecodedBitmapPool } from './decodedBitmapPool';
+
+const bitmap = () => {
+  const close = vi.fn();
+  return { close, height: 20, width: 10 } as unknown as ImageBitmap;
+};
+
+describe('DecodedBitmapPool', () => {
+  it('coalesces concurrent decodes and closes the bitmap after the final lease', async () => {
+    const decoded = bitmap();
+    const decode = vi.fn(() => Promise.resolve(decoded));
+    const byteChanges: number[] = [];
+    const pool = createDecodedBitmapPool({ onBytesChange: (bytes) => byteChanges.push(bytes) });
+
+    const [first, second] = await Promise.all([pool.acquire('image', decode), pool.acquire('image', decode)]);
+
+    expect(decode).toHaveBeenCalledTimes(1);
+    expect(pool.byteSize()).toBe(800);
+    first.release();
+    first.release();
+    expect(decoded.close).not.toHaveBeenCalled();
+    second.release();
+    second.release();
+    expect(decoded.close).toHaveBeenCalledTimes(1);
+    expect(pool.byteSize()).toBe(0);
+    expect(byteChanges).toEqual([800, 0]);
+  });
+
+  it('closes a decode that completes after disposal', async () => {
+    let resolve!: (value: ImageBitmap) => void;
+    const decode = () =>
+      new Promise<ImageBitmap>((next) => {
+        resolve = next;
+      });
+    const pool = createDecodedBitmapPool();
+    const pending = pool.acquire('late', decode);
+    pool.dispose();
+    const decoded = bitmap();
+    resolve(decoded);
+
+    await expect(pending).rejects.toThrow(/disposed/i);
+    expect(decoded.close).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/decodedBitmapPool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/decodedBitmapPool.ts
new file mode 100644
index 00000000000..440353dad11
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/decodedBitmapPool.ts
@@ -0,0 +1,159 @@
+export interface DecodedBitmapLease {
+  readonly bitmap: ImageBitmap;
+  release(): void;
+}
+
+export interface DecodedBitmapPool {
+  acquire(
+    key: string,
+    decode: (signal?: AbortSignal) => Promise<ImageBitmap>,
+    signal?: AbortSignal
+  ): Promise<DecodedBitmapLease>;
+  byteSize(): number;
+  dispose(): void;
+}
+
+interface PoolEntry {
+  controller: AbortController;
+  promise: Promise<ImageBitmap>;
+  bitmap: ImageBitmap | null;
+  bytes: number;
+  leases: number;
+}
+
+const bitmapBytes = (bitmap: ImageBitmap): number => bitmap.width * bitmap.height * 4;
+
+/** A decode-coalescing pool whose bitmaps live only while callers hold leases. */
+export const createDecodedBitmapPool = (
+  options: { onBytesChange?: (bytes: number) => void } = {}
+): DecodedBitmapPool => {
+  const entries = new Map<string, PoolEntry>();
+  let totalBytes = 0;
+  let disposed = false;
+
+  const reportBytes = (): void => options.onBytesChange?.(totalBytes);
+
+  const releaseInterest = (key: string, entry: PoolEntry): void => {
+    entry.leases = Math.max(0, entry.leases - 1);
+    if (entry.leases !== 0 || entries.get(key) !== entry) {
+      return;
+    }
+    entries.delete(key);
+    if (entry.bitmap) {
+      entry.bitmap.close();
+      totalBytes = Math.max(0, totalBytes - entry.bytes);
+      entry.bitmap = null;
+      entry.bytes = 0;
+      reportBytes();
+    } else {
+      entry.controller.abort();
+    }
+  };
+
+  const waitForBitmap = (
+    promise: Promise<ImageBitmap>,
+    signal: AbortSignal | undefined,
+    releaseOnAbort: () => void
+  ): Promise<ImageBitmap> => {
+    if (!signal) {
+      return promise;
+    }
+    if (signal.aborted) {
+      return Promise.reject(signal.reason);
+    }
+    return new Promise<ImageBitmap>((resolve, reject) => {
+      const onAbort = (): void => {
+        signal.removeEventListener('abort', onAbort);
+        releaseOnAbort();
+        reject(signal.reason);
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+      promise.then(
+        (bitmap) => {
+          signal.removeEventListener('abort', onAbort);
+          resolve(bitmap);
+        },
+        (error: unknown) => {
+          signal.removeEventListener('abort', onAbort);
+          reject(error);
+        }
+      );
+    });
+  };
+
+  const acquire = async (
+    key: string,
+    decode: (signal?: AbortSignal) => Promise<ImageBitmap>,
+    signal?: AbortSignal
+  ): Promise<DecodedBitmapLease> => {
+    if (disposed) {
+      throw new Error('DecodedBitmapPool is disposed.');
+    }
+    let entry = entries.get(key);
+    if (!entry) {
+      const created: PoolEntry = {
+        bitmap: null,
+        bytes: 0,
+        controller: new AbortController(),
+        leases: 0,
+        promise: Promise.resolve(null as never),
+      };
+      created.promise = decode(created.controller.signal).then((bitmap) => {
+        if (disposed) {
+          bitmap.close();
+          throw new Error('DecodedBitmapPool was disposed during decode.');
+        }
+        if (entries.get(key) !== created || created.leases === 0) {
+          bitmap.close();
+          throw created.controller.signal.reason ?? new Error('DecodedBitmapPool discarded an unowned decode.');
+        }
+        created.bitmap = bitmap;
+        created.bytes = bitmapBytes(bitmap);
+        totalBytes += created.bytes;
+        reportBytes();
+        return bitmap;
+      });
+      entry = created;
+      entries.set(key, entry);
+    }
+    entry.leases += 1;
+    let released = false;
+    const release = (): void => {
+      if (released) {
+        return;
+      }
+      released = true;
+      releaseInterest(key, entry);
+    };
+    let bitmap: ImageBitmap;
+    try {
+      bitmap = await waitForBitmap(entry.promise, signal, release);
+    } catch (error) {
+      release();
+      throw error;
+    }
+
+    return { bitmap, release };
+  };
+
+  const dispose = (): void => {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    for (const entry of entries.values()) {
+      entry.controller.abort();
+      if (entry.bitmap) {
+        entry.bitmap.close();
+        entry.bitmap = null;
+      }
+    }
+    entries.clear();
+    if (totalBytes !== 0) {
+      totalBytes = 0;
+      reportBytes();
+    }
+  };
+
+  return { acquire, byteSize: () => totalBytes, dispose };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/derivedSurfaceCache.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/derivedSurfaceCache.test.ts
new file mode 100644
index 00000000000..8f708d142b5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/derivedSurfaceCache.test.ts
@@ -0,0 +1,110 @@
+import { createCanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+import { describe, expect, it } from 'vitest';
+
+import type { StubRasterSurface } from './raster.testStub';
+
+import { createDerivedSurfaceCache } from './derivedSurfaceCache';
+import { createTestStubRasterBackend } from './raster.testStub';
+
+describe('createDerivedSurfaceCache', () => {
+  it('reuses an unchanged effect and rebuilds exactly once for a changed key', () => {
+    const backend = createTestStubRasterBackend();
+    const source = backend.createSurface(10, 20);
+    const cache = createDerivedSurfaceCache();
+    let builds = 0;
+    const get = (sourceVersion: number, paramsKey: string) =>
+      cache.get({
+        create: (target) => {
+          builds += 1;
+          return target ?? backend.createSurface(source.width, source.height);
+        },
+        kind: 'adjustments',
+        layerId: 'a',
+        paramsKey,
+        source,
+        sourceVersion,
+      });
+
+    const first = get(1, 'bright');
+    expect(get(1, 'bright')).toBe(first);
+    expect(builds).toBe(1);
+
+    expect(get(2, 'bright')).toBe(first);
+    expect(get(2, 'contrast')).toBe(first);
+    expect(builds).toBe(3);
+  });
+
+  it('keeps unrelated layer effects and removes every effect for a deleted layer', () => {
+    const backend = createTestStubRasterBackend();
+    const cache = createDerivedSurfaceCache();
+    const create = (layerId: string, kind: 'mask-fill' | 'control-transparency') => {
+      const source = backend.createSurface(4, 4);
+      return cache.get({
+        create: () => backend.createSurface(4, 4),
+        kind,
+        layerId,
+        paramsKey: 'x',
+        source,
+        sourceVersion: 0,
+      });
+    };
+
+    create('a', 'mask-fill');
+    create('a', 'control-transparency');
+    const b = create('b', 'mask-fill');
+    cache.deleteLayer('a');
+
+    expect(cache.size()).toBe(1);
+    expect(cache.byteSize()).toBe(4 * 4 * 4);
+    expect(create('b', 'mask-fill')).not.toBe(b); // different source identity is guarded
+  });
+
+  it('evicts least-recently-used entries to a deterministic byte budget', () => {
+    const backend = createTestStubRasterBackend();
+    const cache = createDerivedSurfaceCache();
+    const surfaces = new Map<string, StubRasterSurface>();
+    const get = (layerId: string) => {
+      const source = surfaces.get(layerId) ?? backend.createSurface(10, 10);
+      surfaces.set(layerId, source);
+      return cache.get({
+        create: () => backend.createSurface(10, 10),
+        kind: 'mask-fill',
+        layerId,
+        paramsKey: 'solid:red',
+        source,
+        sourceVersion: 0,
+      });
+    };
+
+    get('a');
+    get('b');
+    get('a'); // a is now most recently used
+    expect(cache.evictToBudget(400)).toEqual(['b']);
+    expect(cache.byteSize()).toBe(400);
+  });
+
+  it('reports cache hits, misses, evictions, and allocated bytes when diagnostics are enabled', () => {
+    const backend = createTestStubRasterBackend();
+    const diagnostics = createCanvasDiagnostics(true);
+    const cache = createDerivedSurfaceCache(diagnostics);
+    const source = backend.createSurface(5, 5);
+    const request = {
+      create: () => backend.createSurface(5, 5),
+      kind: 'adjustments' as const,
+      layerId: 'a',
+      paramsKey: 'x',
+      source,
+      sourceVersion: 0,
+    };
+    cache.get(request);
+    cache.get(request);
+    cache.evictToBudget(0);
+
+    expect(diagnostics.snapshot()).toMatchObject({
+      allocatedDerivedBytes: 100,
+      derivedCacheEvictions: 1,
+      derivedCacheHits: 1,
+      derivedCacheMisses: 1,
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/derivedSurfaceCache.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/derivedSurfaceCache.ts
new file mode 100644
index 00000000000..70c36b15171
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/derivedSurfaceCache.ts
@@ -0,0 +1,117 @@
+import type { CanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+
+import type { RasterSurface } from './raster';
+
+export type DerivedSurfaceKind = 'adjustments' | 'mask-fill' | 'control-transparency';
+
+export interface DerivedSurfaceRequest {
+  layerId: string;
+  sourceVersion: number;
+  kind: DerivedSurfaceKind;
+  paramsKey: string;
+  source: RasterSurface;
+  create(target: RasterSurface | null): RasterSurface;
+}
+
+export interface DerivedSurfaceCache {
+  get(request: DerivedSurfaceRequest): RasterSurface;
+  delete(layerId: string, kind: DerivedSurfaceKind): void;
+  deleteLayer(layerId: string): void;
+  byteSize(): number;
+  size(): number;
+  evictToBudget(budgetBytes: number): string[];
+  dispose(): void;
+}
+
+interface CacheEntry {
+  readonly layerId: string;
+  readonly kind: DerivedSurfaceKind;
+  paramsKey: string;
+  source: RasterSurface;
+  sourceVersion: number;
+  surface: RasterSurface;
+  lastUsed: number;
+}
+
+const BYTES_PER_PIXEL = 4;
+const entryKey = (layerId: string, kind: DerivedSurfaceKind): string => `${layerId}\u0000${kind}`;
+const surfaceBytes = (surface: RasterSurface): number => surface.width * surface.height * BYTES_PER_PIXEL;
+
+export const createDerivedSurfaceCache = (diagnostics?: CanvasDiagnostics): DerivedSurfaceCache => {
+  const entries = new Map<string, CacheEntry>();
+  let tick = 0;
+
+  const get = (request: DerivedSurfaceRequest): RasterSurface => {
+    const key = entryKey(request.layerId, request.kind);
+    const existing = entries.get(key);
+    tick += 1;
+    if (
+      existing &&
+      existing.source === request.source &&
+      existing.sourceVersion === request.sourceVersion &&
+      existing.paramsKey === request.paramsKey
+    ) {
+      diagnostics?.increment('derivedCacheHits');
+      existing.lastUsed = tick;
+      return existing.surface;
+    }
+
+    diagnostics?.increment('derivedCacheMisses');
+    const canReuse = existing?.source === request.source;
+    const surface = request.create(canReuse ? existing.surface : null);
+    if (!canReuse) {
+      diagnostics?.add('allocatedDerivedBytes', surfaceBytes(surface));
+    }
+    entries.set(key, {
+      kind: request.kind,
+      lastUsed: tick,
+      layerId: request.layerId,
+      paramsKey: request.paramsKey,
+      source: request.source,
+      sourceVersion: request.sourceVersion,
+      surface,
+    });
+    return surface;
+  };
+
+  return {
+    byteSize: () => {
+      let bytes = 0;
+      for (const entry of entries.values()) {
+        bytes += surfaceBytes(entry.surface);
+      }
+      return bytes;
+    },
+    delete: (layerId, kind) => {
+      entries.delete(entryKey(layerId, kind));
+    },
+    deleteLayer: (layerId) => {
+      for (const [key, entry] of entries) {
+        if (entry.layerId === layerId) {
+          entries.delete(key);
+        }
+      }
+    },
+    dispose: () => entries.clear(),
+    evictToBudget: (budgetBytes) => {
+      let bytes = 0;
+      for (const entry of entries.values()) {
+        bytes += surfaceBytes(entry.surface);
+      }
+      const evicted: string[] = [];
+      const oldestFirst = [...entries.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+      for (const [key, entry] of oldestFirst) {
+        if (bytes <= budgetBytes) {
+          break;
+        }
+        entries.delete(key);
+        bytes -= surfaceBytes(entry.surface);
+        evicted.push(entry.layerId);
+        diagnostics?.increment('derivedCacheEvictions');
+      }
+      return evicted;
+    },
+    get,
+    size: () => entries.size,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/fontLoader.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/fontLoader.test.ts
new file mode 100644
index 00000000000..d5cae5e72bf
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/fontLoader.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { FontLoadApi } from './fontLoader';
+
+import { createFontLoader } from './fontLoader';
+
+/** A fake fonts api with a controllable `check` and a deferred `load`. */
+const createFakeFonts = (initiallyLoaded = false) => {
+  let loaded = initiallyLoaded;
+  let resolveLoad: (() => void) | null = null;
+  const load = vi.fn(
+    (_font: string): Promise<unknown> =>
+      new Promise<void>((resolve) => {
+        resolveLoad = () => {
+          loaded = true;
+          resolve();
+        };
+      })
+  );
+  const api: FontLoadApi = {
+    check: () => loaded,
+    load,
+  };
+  return { api, load, settle: () => resolveLoad?.() };
+};
+
+const flush = (): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+
+describe('createFontLoader', () => {
+  it('is a silent no-op with no api (node-safe)', () => {
+    const loader = createFontLoader(null);
+    const onReady = vi.fn();
+    loader.ensure('400 20px Inter', onReady);
+    expect(onReady).not.toHaveBeenCalled();
+  });
+
+  it('does not load or call onReady when the font is already available', () => {
+    const { api, load } = createFakeFonts(true);
+    const loader = createFontLoader(api);
+    const onReady = vi.fn();
+    loader.ensure('400 20px Inter', onReady);
+    expect(load).not.toHaveBeenCalled();
+    expect(onReady).not.toHaveBeenCalled();
+  });
+
+  it('kicks a load for an unavailable font and calls onReady when it resolves', async () => {
+    const { api, load, settle } = createFakeFonts(false);
+    const loader = createFontLoader(api);
+    const onReady = vi.fn();
+    loader.ensure('400 20px Inter', onReady);
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(onReady).not.toHaveBeenCalled();
+    settle();
+    await flush();
+    expect(onReady).toHaveBeenCalledTimes(1);
+  });
+
+  it('dedupes concurrent loads of the same font (one load, both onReady fire)', async () => {
+    const { api, load, settle } = createFakeFonts(false);
+    const loader = createFontLoader(api);
+    const onReadyA = vi.fn();
+    const onReadyB = vi.fn();
+    loader.ensure('400 20px Inter', onReadyA);
+    loader.ensure('400 20px Inter', onReadyB);
+    expect(load).toHaveBeenCalledTimes(1);
+    settle();
+    await flush();
+    expect(onReadyA).toHaveBeenCalledTimes(1);
+    expect(onReadyB).toHaveBeenCalledTimes(1);
+  });
+
+  it('swallows a check() that throws (treats the font as unavailable)', () => {
+    const api: FontLoadApi = {
+      check: () => {
+        throw new Error('bad font string');
+      },
+      load: vi.fn(() => Promise.resolve()),
+    };
+    const loader = createFontLoader(api);
+    expect(() => loader.ensure('garbage', vi.fn())).not.toThrow();
+    expect(api.load).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/fontLoader.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/fontLoader.ts
new file mode 100644
index 00000000000..5d5759aaf97
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/fontLoader.ts
@@ -0,0 +1,85 @@
+/**
+ * Web-font readiness for text layers.
+ *
+ * A text layer's rasterized metrics depend on the font actually being available:
+ * if a web font isn't loaded yet, the platform substitutes a fallback and
+ * `measureText` reports the WRONG advances, so the cached text pixels (and the
+ * layer's extent) would be wrong until something else happened to re-rasterize.
+ *
+ * This loader is the seam the engine uses to fix that without importing the DOM
+ * into the rasterizer: given a `FontLoadApi` (the browser's `document.fonts`, or
+ * a fake in tests), it kicks a load for a not-yet-available font exactly once
+ * (concurrent requests for the same font string share one in-flight promise) and
+ * invokes `onReady` when it resolves — the engine's callback re-rasterizes the
+ * affected layer. A `null` api (node, or a browser without `document.fonts`) is
+ * a silent no-op, so importing this module and the engine stays node-safe.
+ *
+ * The loader holds NO permanent "loaded" set — it trusts `api.check()` (the
+ * browser flips it to `true` post-load) as the source of truth and only tracks
+ * in-flight promises (cleared on settle). Combined with the per-engine instance,
+ * that keeps it free of cross-test global state.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+/** The minimal slice of `FontFaceSet` the loader needs (so tests can inject a fake). */
+export interface FontLoadApi {
+  /** Whether every face for the CSS `font` shorthand is loaded and usable. */
+  check(font: string): boolean;
+  /** Loads the faces for the CSS `font` shorthand; resolves when they're ready. */
+  load(font: string): Promise<unknown>;
+}
+
+/** A per-engine font loader bound to one `FontLoadApi` (or `null` in node). */
+export interface FontLoader {
+  /**
+   * Ensures `font` is available, invoking `onReady` once when a pending load
+   * resolves. A no-op (never calls `onReady`) when there is no api or the font
+   * is already available — the caller's synchronous rasterize already used the
+   * correct metrics in that case.
+   */
+  ensure(font: string, onReady: () => void): void;
+}
+
+/** `check` can throw on an unparseable font string; treat a throw as "not available". */
+const safeCheck = (api: FontLoadApi, font: string): boolean => {
+  try {
+    return api.check(font);
+  } catch {
+    return false;
+  }
+};
+
+/** Creates a font loader bound to `api` (pass `null` for a node-safe no-op loader). */
+export const createFontLoader = (api: FontLoadApi | null): FontLoader => {
+  const pending = new Map<string, Promise<void>>();
+
+  return {
+    ensure: (font, onReady) => {
+      if (!api || safeCheck(api, font)) {
+        return;
+      }
+      const existing = pending.get(font);
+      if (existing) {
+        existing.then(onReady, () => {});
+        return;
+      }
+      const promise = Promise.resolve(api.load(font)).then(
+        () => {},
+        () => {}
+      );
+      const tracked = promise.finally(() => pending.delete(font));
+      pending.set(font, tracked);
+      tracked.then(onReady, () => {});
+    },
+  };
+};
+
+/** Resolves the browser's `document.fonts` api, or `null` where it is unavailable (node, older browsers). */
+export const domFontLoadApi = (): FontLoadApi | null => {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  const fonts = (document as Document & { fonts?: FontLoadApi }).fonts;
+  return fonts && typeof fonts.check === 'function' && typeof fonts.load === 'function' ? fonts : null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemand.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemand.test.ts
new file mode 100644
index 00000000000..86385ffe66b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemand.test.ts
@@ -0,0 +1,90 @@
+import type { CanvasDocumentContractV2, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { calculateActiveFrameLayerIds } from './frameDemand';
+
+const layer = (id: string, x: number, y: number, width = 100, height = 100): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height, imageName: `${id}.png`, width }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x, y },
+  type: 'raster',
+});
+
+const document = (layers: CanvasRasterLayerContractV2[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 1_000,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 1_000,
+});
+
+describe('calculateActiveFrameLayerIds', () => {
+  it('changes demand deterministically when panning reveals an offscreen layer', () => {
+    const doc = document([layer('left', 0, 0), layer('right', 500, 0)]);
+
+    expect(calculateActiveFrameLayerIds({ document: doc, viewport: { height: 200, width: 200, x: 0, y: 0 } })).toEqual(
+      new Set(['left'])
+    );
+    expect(
+      calculateActiveFrameLayerIds({ document: doc, viewport: { height: 200, width: 200, x: 450, y: 0 } })
+    ).toEqual(new Set(['right']));
+  });
+
+  it('uses live cache bounds for unflushed paint pixels', () => {
+    const paint = { ...layer('paint', 20, 20), source: { bitmap: null, type: 'paint' as const } };
+
+    expect(
+      calculateActiveFrameLayerIds({
+        document: document([paint]),
+        liveCacheRects: new Map([['paint', { height: 30, width: 40, x: 0, y: 0 }]]),
+        viewport: { height: 100, width: 100, x: 0, y: 0 },
+      })
+    ).toEqual(new Set(['paint']));
+  });
+
+  it('limits demand to isolated layers', () => {
+    const doc = document([layer('isolated', 0, 0), layer('covered', 0, 0)]);
+
+    expect(
+      calculateActiveFrameLayerIds({
+        document: doc,
+        isolationLayerIds: new Set(['isolated']),
+        viewport: { height: 200, width: 200, x: 0, y: 0 },
+      })
+    ).toEqual(new Set(['isolated']));
+  });
+
+  it('uses a transient transform override before cache allocation', () => {
+    const moving = layer('moving', 500, 0);
+
+    expect(
+      calculateActiveFrameLayerIds({
+        document: document([moving]),
+        transformOverrides: new Map([['moving', { x: 20, y: 20 }]]),
+        viewport: { height: 200, width: 200, x: 0, y: 0 },
+      })
+    ).toEqual(new Set(['moving']));
+  });
+
+  it('uses transformed corners for rotated-layer demand', () => {
+    const rotated = {
+      ...layer('rotated', 250, 0),
+      transform: { rotation: Math.PI / 2, scaleX: 1, scaleY: 1, x: 250, y: 0 },
+    };
+
+    expect(
+      calculateActiveFrameLayerIds({
+        document: document([rotated]),
+        viewport: { height: 120, width: 120, x: 140, y: 0 },
+      })
+    ).toEqual(new Set(['rotated']));
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemand.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemand.ts
new file mode 100644
index 00000000000..96e29c979ce
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemand.ts
@@ -0,0 +1,52 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { getSourceContentRect, renderableSourceOf } from '@workbench/canvas-engine/document/sources';
+import { fromTRS } from '@workbench/canvas-engine/math/mat2d';
+import { intersect, isEmpty, transformBounds, union } from '@workbench/canvas-engine/math/rect';
+
+export interface FrameDemandInput {
+  readonly document: CanvasDocumentContractV2;
+  readonly isolationLayerIds?: ReadonlySet<string>;
+  readonly liveCacheRects?: ReadonlyMap<string, Rect>;
+  readonly transformOverrides?: ReadonlyMap<
+    string,
+    { x: number; y: number; scaleX?: number; scaleY?: number; rotation?: number }
+  >;
+  readonly viewport: Rect;
+}
+
+/** Calculates the enabled raster caches whose transformed pixels intersect the next frame. */
+export const calculateActiveFrameLayerIds = ({
+  document,
+  isolationLayerIds,
+  liveCacheRects,
+  transformOverrides,
+  viewport,
+}: FrameDemandInput): Set<string> => {
+  const active = new Set<string>();
+  for (const layer of document.layers) {
+    if (!layer.isEnabled || !renderableSourceOf(layer) || (isolationLayerIds && !isolationLayerIds.has(layer.id))) {
+      continue;
+    }
+    const sourceRect = getSourceContentRect(layer, document);
+    const liveRect = liveCacheRects?.get(layer.id);
+    const localRect =
+      liveRect && !isEmpty(liveRect) ? (isEmpty(sourceRect) ? liveRect : union(sourceRect, liveRect)) : sourceRect;
+    const override = transformOverrides?.get(layer.id);
+    const transform = override
+      ? {
+          rotation: override.rotation ?? layer.transform.rotation,
+          scaleX: override.scaleX ?? layer.transform.scaleX,
+          scaleY: override.scaleY ?? layer.transform.scaleY,
+          x: override.x,
+          y: override.y,
+        }
+      : layer.transform;
+    const matrix = fromTRS({ x: transform.x, y: transform.y }, transform.rotation, transform.scaleX, transform.scaleY);
+    if (intersect(transformBounds(matrix, localRect), viewport)) {
+      active.add(layer.id);
+    }
+  }
+  return active;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemandBudget.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemandBudget.test.ts
new file mode 100644
index 00000000000..fe6deb56e4e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/frameDemandBudget.test.ts
@@ -0,0 +1,61 @@
+import type { CanvasDocumentContractV2, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { calculateActiveFrameLayerIds } from './frameDemand';
+import { createLayerCacheStore } from './layerCache';
+import { createTestStubRasterBackend } from './raster.testStub';
+
+const layer = (id: string, x: number): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: 100, imageName: `${id}.png`, width: 100 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x, y: 0 },
+  type: 'raster',
+});
+
+describe('frame demand cache allocation', () => {
+  it('allocates on reveal, evicts offscreen LRU, and re-allocates deterministically on return', () => {
+    const stub = createTestStubRasterBackend();
+    const createSurface = vi.fn(stub.createSurface);
+    const caches = createLayerCacheStore({ ...stub, createSurface });
+    const document: CanvasDocumentContractV2 = {
+      background: 'transparent',
+      bbox: { height: 100, width: 100, x: 0, y: 0 },
+      height: 1_000,
+      layers: [layer('left', 0), layer('right', 500)],
+      selectedLayerId: null,
+      version: 2,
+      width: 1_000,
+    };
+    const allocateDemand = (x: number): Set<string> => {
+      const active = calculateActiveFrameLayerIds({
+        document,
+        viewport: { height: 200, width: 200, x, y: 0 },
+      });
+      for (const id of active) {
+        caches.getOrCreate(id, 100, 100);
+      }
+      caches.evictHidden(active, 40_000);
+      return active;
+    };
+
+    expect(allocateDemand(0)).toEqual(new Set(['left']));
+    expect(createSurface).toHaveBeenCalledTimes(1);
+    expect(caches.byteSize()).toBe(40_000);
+
+    expect(allocateDemand(450)).toEqual(new Set(['right']));
+    expect(createSurface).toHaveBeenCalledTimes(2);
+    expect(caches.peek('left')).toBeUndefined();
+    expect(caches.byteSize()).toBe(40_000);
+
+    expect(allocateDemand(0)).toEqual(new Set(['left']));
+    expect(createSurface).toHaveBeenCalledTimes(3);
+    expect(caches.peek('right')).toBeUndefined();
+    expect(caches.byteSize()).toBe(40_000);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/layerCache.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/layerCache.test.ts
new file mode 100644
index 00000000000..9f15ec753e8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/layerCache.test.ts
@@ -0,0 +1,304 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { StubRasterSurface } from './raster.testStub';
+
+import { createLayerCacheStore, DEFAULT_CACHE_BUDGET_BYTES } from './layerCache';
+import { createTestStubRasterBackend } from './raster.testStub';
+
+describe('createLayerCacheStore', () => {
+  it('notifies version changes for pixel publication, invalidation, replacement, growth, and deletion', () => {
+    const backend = createTestStubRasterBackend();
+    const onVersionChange = vi.fn();
+    const store = createLayerCacheStore(backend, { onVersionChange });
+
+    store.getOrCreate('layer-1', 10, 10);
+    expect(onVersionChange).not.toHaveBeenCalled();
+
+    store.publishPixels('layer-1');
+    store.growToRect('layer-1', { height: 20, width: 20, x: 0, y: 0 });
+    store.invalidate('layer-1');
+    store.installReplacement(
+      store.prepareReplacement('layer-1', { height: 5, width: 5, x: 0, y: 0 }, backend.createSurface(5, 5))
+    );
+    store.delete('layer-1');
+
+    expect(onVersionChange).toHaveBeenCalledTimes(5);
+    expect(onVersionChange).toHaveBeenCalledWith('layer-1');
+  });
+
+  it('does not notify for ordinary fresh or stale allocation', () => {
+    const onVersionChange = vi.fn();
+    const store = createLayerCacheStore(createTestStubRasterBackend(), { onVersionChange });
+
+    store.getOrCreate('origin', 10, 10);
+    store.getOrCreateRect('rect', { height: 10, width: 10, x: 2, y: 3 });
+    store.growToRect('grown', { height: 10, width: 10, x: 2, y: 3 });
+
+    expect(onVersionChange).not.toHaveBeenCalled();
+  });
+
+  it('returns a stable entry identity for the same layer + size', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const a = store.getOrCreate('layer-1', 100, 50);
+    const b = store.getOrCreate('layer-1', 100, 50);
+    expect(b).toBe(a);
+    expect(store.get('layer-1')).toBe(a);
+  });
+
+  it('marks new allocations as never published', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+
+    expect(store.getOrCreate('origin', 10, 10).hasPublishedPixels).toBe(false);
+    expect(store.getOrCreateRect('rect', { height: 10, width: 10, x: 2, y: 3 }).hasPublishedPixels).toBe(false);
+    expect(store.growToRect('grown', { height: 10, width: 10, x: 2, y: 3 }).hasPublishedPixels).toBe(false);
+  });
+
+  it('marks installed raster replacements as published', () => {
+    const backend = createTestStubRasterBackend();
+    const store = createLayerCacheStore(backend);
+    const prepared = store.prepareReplacement(
+      'layer-1',
+      { height: 10, width: 10, x: 0, y: 0 },
+      backend.createSurface(10, 10)
+    );
+
+    expect(store.installReplacement(prepared).hasPublishedPixels).toBe(true);
+  });
+
+  it('preserves published pixels through invalidation so stale previews remain drawable', () => {
+    const backend = createTestStubRasterBackend();
+    const store = createLayerCacheStore(backend);
+    const entry = store.installReplacement(
+      store.prepareReplacement('layer-1', { height: 10, width: 10, x: 0, y: 0 }, backend.createSurface(10, 10))
+    );
+
+    store.invalidate('layer-1');
+
+    expect(entry.stale).toBe(true);
+    expect(entry.hasPublishedPixels).toBe(true);
+  });
+
+  it('resets publication readiness when a resize destroys the old pixels', () => {
+    const backend = createTestStubRasterBackend();
+    const store = createLayerCacheStore(backend);
+    const entry = store.installReplacement(
+      store.prepareReplacement('layer-1', { height: 10, width: 10, x: 0, y: 0 }, backend.createSurface(10, 10))
+    );
+
+    store.getOrCreate('layer-1', 20, 20);
+
+    expect(entry.hasPublishedPixels).toBe(false);
+  });
+
+  it('resizes the surface (and marks stale) when the requested size changes', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.getOrCreate('layer-1', 100, 50);
+    entry.stale = false;
+    const resized = store.getOrCreate('layer-1', 200, 80);
+    expect(resized).toBe(entry);
+    expect(resized.surface.width).toBe(200);
+    expect(resized.surface.height).toBe(80);
+    expect(resized.stale).toBe(true);
+  });
+
+  it('invalidate bumps the version and marks the cache stale', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.getOrCreate('layer-1', 10, 10);
+    entry.stale = false;
+    expect(store.version('layer-1')).toBe(0);
+
+    store.invalidate('layer-1');
+    expect(store.version('layer-1')).toBe(1);
+    expect(entry.version).toBe(1);
+    expect(entry.stale).toBe(true);
+
+    store.invalidate('layer-1');
+    expect(store.version('layer-1')).toBe(2);
+  });
+
+  it('version is 0 for an unknown layer', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    expect(store.version('nope')).toBe(0);
+  });
+
+  it('a recreated entry (after delete) resumes ABOVE the old version, never resetting to 0', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const first = store.getOrCreate('a', 10, 10);
+    store.invalidate('a');
+    store.invalidate('a');
+    expect(first.version).toBe(2);
+
+    // Delete + recreate (undo→redo / transform bake / merge / evict→re-show): the
+    // fresh entry must start above 2 so version-keyed caches (adjusted surface,
+    // thumbnails) can't mistake its new pixels for a version they already hold.
+    store.delete('a');
+    const recreated = store.getOrCreate('a', 10, 10);
+    expect(recreated.version).toBeGreaterThan(2);
+  });
+
+  it('an evicted-then-re-shown entry also resumes above its pre-eviction version', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    store.getOrCreate('hidden', 100, 100);
+    store.invalidate('hidden'); // version 1
+    const budget = 100 * 100 * 4; // room for one surface
+    store.getOrCreate('visible', 100, 100);
+    const evicted = store.evictHidden(['visible'], budget);
+    expect(evicted).toContain('hidden');
+
+    const reshown = store.getOrCreate('hidden', 100, 100);
+    expect(reshown.version).toBeGreaterThan(1);
+  });
+
+  it('byteSize sums w*h*4 across all cache surfaces', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    store.getOrCreate('a', 100, 100); // 40_000
+    store.getOrCreate('b', 10, 10); // 400
+    expect(store.byteSize()).toBe(100 * 100 * 4 + 10 * 10 * 4);
+  });
+
+  it('delete drops a cache entry', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    store.getOrCreate('a', 10, 10);
+    store.delete('a');
+    expect(store.get('a')).toBeUndefined();
+    expect(store.byteSize()).toBe(0);
+  });
+
+  it('evictHidden does nothing when already within budget', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    store.getOrCreate('a', 10, 10);
+    const evicted = store.evictHidden([], DEFAULT_CACHE_BUDGET_BYTES);
+    expect(evicted).toEqual([]);
+    expect(store.get('a')).toBeDefined();
+  });
+
+  it('evictHidden evicts least-recently-used hidden caches until within budget, never visible ones', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    // Each surface is 100*100*4 = 40_000 bytes.
+    store.getOrCreate('old-hidden', 100, 100);
+    store.getOrCreate('visible', 100, 100);
+    store.getOrCreate('new-hidden', 100, 100);
+    // Touch 'new-hidden' so 'old-hidden' is the LRU among hidden entries.
+    store.get('new-hidden');
+
+    // Budget allows exactly two surfaces; three exist -> one hidden must go.
+    const budget = 100 * 100 * 4 * 2;
+    const evicted = store.evictHidden(['visible'], budget);
+
+    expect(evicted).toEqual(['old-hidden']);
+    expect(store.get('old-hidden')).toBeUndefined();
+    expect(store.get('visible')).toBeDefined();
+    expect(store.get('new-hidden')).toBeDefined();
+    expect(store.byteSize()).toBeLessThanOrEqual(budget);
+  });
+
+  it('evictHidden will not evict visible caches even if still over budget', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    store.getOrCreate('visible', 100, 100);
+    const evicted = store.evictHidden(['visible'], 1);
+    expect(evicted).toEqual([]);
+    expect(store.get('visible')).toBeDefined();
+  });
+
+  it('dispose clears caches', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    store.getOrCreate('a', 10, 10);
+
+    store.dispose();
+    expect(store.byteSize()).toBe(0);
+  });
+});
+
+describe('getOrCreateRect (content-sized, off-origin placement)', () => {
+  it('creates a new surface placed at an off-origin (negative) layer-local rect', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.getOrCreateRect('L', { height: 40, width: 60, x: -15, y: -25 });
+    expect(entry.rect).toEqual({ height: 40, width: 60, x: -15, y: -25 });
+    expect(entry.surface.width).toBe(60);
+    expect(entry.surface.height).toBe(40);
+    expect(entry.stale).toBe(true);
+  });
+
+  it('NEVER resizes or re-places an existing entry (a grown paint cache must survive)', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.getOrCreateRect('L', { height: 40, width: 60, x: 5, y: 5 });
+    entry.stale = false;
+    // A later request with the (smaller/different) contract rect returns the
+    // live entry untouched: sizing belongs to the rasterizer/grow paths.
+    const again = store.getOrCreateRect('L', { height: 10, width: 10, x: 0, y: 0 });
+    expect(again).toBe(entry);
+    expect(again.rect).toEqual({ height: 40, width: 60, x: 5, y: 5 });
+    expect(again.surface.width).toBe(60);
+    expect(again.stale).toBe(false);
+  });
+
+  it('supports a zero-rect entry (brand-new empty paint layer)', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.getOrCreateRect('L', { height: 0, width: 0, x: 0, y: 0 });
+    expect(entry.rect).toEqual({ height: 0, width: 0, x: 0, y: 0 });
+    expect(entry.surface.width).toBe(0);
+    expect(entry.surface.height).toBe(0);
+  });
+});
+
+describe('growToRect (paint caches grow with strokes)', () => {
+  it('creates a fresh non-stale entry at the rounded target rect when none exists', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.growToRect('L', { height: 19.2, width: 10.6, x: 3.4, y: -2.7 });
+    expect(entry.rect).toEqual({ height: 19, width: 11, x: 3, y: -3 });
+    expect(entry.stale).toBe(false);
+  });
+
+  it('grows to the UNION of the current extent and the request, preserving old pixels at their shifted origin', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.growToRect('L', { height: 20, width: 20, x: 10, y: 10 });
+    const surfaceBefore = entry.surface;
+
+    const grown = store.growToRect('L', { height: 20, width: 20, x: -10, y: -10 });
+    expect(grown).toBe(entry);
+    // Union of [10,30)² and [-10,10)² = [-10,30)² → 40×40 at (-10,-10).
+    expect(grown.rect).toEqual({ height: 40, width: 40, x: -10, y: -10 });
+    // Resized in place: the surface identity is preserved (open sessions hold it).
+    expect(grown.surface).toBe(surfaceBefore);
+    expect(grown.surface.width).toBe(40);
+    expect(grown.surface.height).toBe(40);
+
+    // The old pixels were snapshotted before the (clearing) resize and blitted
+    // back at their layer-local position within the grown surface: old origin
+    // (10,10) minus new origin (-10,-10) = surface (20,20).
+    const log = (grown.surface as StubRasterSurface).callLog;
+    const snapshot = log.find((e) => e.op === 'getImageData');
+    expect(snapshot?.args).toEqual([0, 0, 20, 20]);
+    const resizeIndex = log.findIndex((e) => e.op === 'resize');
+    const putIndex = log.findIndex((e) => e.op === 'putImageData');
+    expect(resizeIndex).toBeGreaterThan(-1);
+    expect(putIndex).toBeGreaterThan(resizeIndex);
+    expect(log[putIndex]?.args.slice(1)).toEqual([20, 20]);
+  });
+
+  it('is a no-op (no resize, no blit) when the current extent already covers the request', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const entry = store.growToRect('L', { height: 100, width: 100, x: 0, y: 0 });
+    const logLength = (entry.surface as StubRasterSurface).callLog.length;
+
+    const again = store.growToRect('L', { height: 10, width: 10, x: 20, y: 20 });
+    expect(again).toBe(entry);
+    expect(again.rect).toEqual({ height: 100, width: 100, x: 0, y: 0 });
+    expect((again.surface as StubRasterSurface).callLog.length).toBe(logLength);
+  });
+
+  it('adopts the target rect from an EMPTY extent without snapshotting stale pixels', () => {
+    const store = createLayerCacheStore(createTestStubRasterBackend());
+    const empty = store.getOrCreateRect('L', { height: 0, width: 0, x: 0, y: 0 });
+    empty.stale = false;
+
+    const grown = store.growToRect('L', { height: 30, width: 30, x: 50, y: 60 });
+    expect(grown).toBe(empty);
+    // No union with the empty rect's (0,0) origin: the first stroke's bounds
+    // become the extent verbatim (no needless 0,0-anchored surface).
+    expect(grown.rect).toEqual({ height: 30, width: 30, x: 50, y: 60 });
+    const log = (grown.surface as StubRasterSurface).callLog;
+    expect(log.some((e) => e.op === 'getImageData')).toBe(false);
+    expect(log.some((e) => e.op === 'putImageData')).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/layerCache.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/layerCache.ts
new file mode 100644
index 00000000000..ad85bc16cd9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/layerCache.ts
@@ -0,0 +1,415 @@
+/**
+ * Per-layer raster cache store.
+ *
+ * Each layer's rendered pixels are cached on their own {@link RasterSurface}
+ * so the compositor can redraw the document without re-rasterizing every
+ * layer each frame. Caches are always re-rasterizable, so eviction is safe:
+ * a hidden layer's cache can be dropped to stay under a memory budget and
+ * rebuilt on demand when it becomes visible again.
+ *
+ * All surface allocation flows through the injected {@link RasterBackend}
+ * seam, so the store runs unchanged in node tests. Zero React, zero
+ * import-time side effects.
+ */
+
+import type { Rect } from '@workbench/canvas-engine/types';
+
+import type { RasterBackend, RasterSurface } from './raster';
+
+/** Default cache budget: ~512 MB of surface pixels before hidden caches are evicted. */
+export const DEFAULT_CACHE_BUDGET_BYTES = 512 * 1024 * 1024;
+
+const BYTES_PER_PIXEL = 4;
+
+/** A single layer's cache entry. */
+export interface LayerCacheEntry {
+  readonly layerId: string;
+  /** The backing surface holding the layer's rasterized pixels. */
+  surface: RasterSurface;
+  /** True only after real pixels have been published into this allocation. */
+  hasPublishedPixels: boolean;
+  /**
+   * The surface's content bounds in the layer's LOCAL coordinate space. The
+   * surface holds `rect.width`×`rect.height` pixels; surface pixel `(sx, sy)`
+   * maps to layer-local `(rect.x + sx, rect.y + sy)`. The origin can be negative
+   * (a paint layer grown up/left of its start). The compositor draws the surface
+   * at `transform × rect.origin`. An empty rect (0 width/height) marks an empty
+   * layer (a brand-new or cleared paint layer) — safe to skip everywhere.
+   */
+  rect: Rect;
+  /** Bumped every time the cache is invalidated; thumbnails/subscribers watch this. */
+  version: number;
+  /** True when the cached pixels are known to be out of date and need re-rasterizing. */
+  stale: boolean;
+  /** Monotonic access tick, used to order LRU eviction. */
+  lastUsed: number;
+}
+
+/**
+ * A fully-rasterized cache replacement that has not been published to the live
+ * cache map yet. Preparation may allocate/draw and therefore may fail; install
+ * performs only in-memory version/map bookkeeping.
+ */
+export interface PreparedLayerCacheReplacement {
+  readonly layerId: string;
+  readonly rect: Rect;
+  readonly surface: RasterSurface;
+}
+
+export interface LayerCacheStoreOptions {
+  /** Called after a cache identity or pixels change; fresh allocations stay silent. */
+  onVersionChange?(layerId: string): void;
+}
+
+/** The imperative store returned by {@link createLayerCacheStore}. */
+export interface LayerCacheStore {
+  /** Returns an entry without changing LRU order. */
+  peek(layerId: string): LayerCacheEntry | undefined;
+  /** Returns the existing cache entry for a layer, or `undefined`. Touches LRU order. */
+  get(layerId: string): LayerCacheEntry | undefined;
+  /**
+   * Returns the cache entry for a layer, creating (or resizing) its surface to
+   * `width`x`height` at the LOCAL origin `(0, 0)`. The returned entry identity is
+   * stable across calls that don't change the size, so callers can hold onto it
+   * between frames. Use this for origin-anchored layers (image / shape / text /
+   * gradient); paint caches, which can grow off-origin, use {@link getOrCreateRect}
+   * / {@link growToRect}.
+   */
+  getOrCreate(layerId: string, width: number, height: number): LayerCacheEntry;
+  /**
+   * Like {@link getOrCreate} but places the surface at an arbitrary layer-local
+   * `rect` origin (which may be negative). Creates the entry when absent; when it
+   * already exists the surface is left untouched (the caller — a rasterizer or a
+   * growth op — owns resizing), only ensuring existence. Used for paint layers
+   * whose content rect is not origin-anchored.
+   */
+  getOrCreateRect(layerId: string, rect: Rect): LayerCacheEntry;
+  /**
+   * Grows (never shrinks) a layer's cache to cover `rect` in layer-local space,
+   * preserving the existing pixels at their new offset. A no-op when `rect` is
+   * already within the current extent. Creates the entry (surface sized to `rect`)
+   * when absent. Returns the entry.
+   */
+  growToRect(layerId: string, rect: Rect): LayerCacheEntry;
+  /** Clones `pixels` into a detached replacement without mutating the live cache. */
+  prepareReplacement(layerId: string, rect: Rect, pixels: RasterSurface): PreparedLayerCacheReplacement;
+  /** Publishes a detached replacement without allocating, resizing, or drawing. */
+  installReplacement(prepared: PreparedLayerCacheReplacement): LayerCacheEntry;
+  /** Marks directly-written pixels current, bumps the version, and notifies observers. */
+  publishPixels(layerId: string): LayerCacheEntry | undefined;
+  /** Marks a layer's cache stale and bumps its `version`. */
+  invalidate(layerId: string): void;
+  /** Drops a layer's cache entry entirely. */
+  delete(layerId: string): void;
+  /** The current `version` for a layer (0 if it has no cache yet). */
+  version(layerId: string): number;
+  /** Total bytes held across all cache surfaces (w*h*4 each). */
+  byteSize(): number;
+  /**
+   * Evicts hidden-layer caches (those whose id is not in `visibleIds`) in
+   * least-recently-used order until the total {@link byteSize} is within
+   * `budgetBytes`. Visible layers are never evicted. Returns the evicted ids.
+   */
+  evictHidden(visibleIds: Iterable<string>, budgetBytes?: number): string[];
+  /** Releases every cache entry. Cache surfaces are GC'd with the store. */
+  dispose(): void;
+}
+
+const surfaceBytes = (surface: RasterSurface): number => surface.width * surface.height * BYTES_PER_PIXEL;
+
+/** Creates a per-layer raster cache store backed by the given {@link RasterBackend}. */
+export const createLayerCacheStore = (
+  backend: RasterBackend,
+  options: LayerCacheStoreOptions = {}
+): LayerCacheStore => {
+  const entries = new Map<string, LayerCacheEntry>();
+  // Per-id version FLOOR: the highest version each layer id has ever reached,
+  // retained across delete/recreate (delete, LRU eviction). A recreated entry
+  // (undo→redo, transform bake, merge, evict→re-show) starts ABOVE this floor
+  // rather than resetting to 0 — so version-keyed dependents (the adjusted-surface
+  // cache, thumbnail state) never mistake fresh pixels for a stale version they
+  // already have cached. Only ever grows; a plain number per id (negligible).
+  const versionFloors = new Map<string, number>();
+  let tick = 0;
+
+  const notifyVersionChange = (layerId: string): void => {
+    try {
+      options.onVersionChange?.(layerId);
+    } catch {
+      // Cache mutation is already complete; observers cannot roll it back.
+    }
+  };
+
+  const touch = (entry: LayerCacheEntry): void => {
+    tick += 1;
+    entry.lastUsed = tick;
+  };
+
+  /** The version a freshly-created entry for `layerId` must start at (monotonic). */
+  const initialVersion = (layerId: string): number => {
+    const floor = versionFloors.get(layerId);
+    return floor === undefined ? 0 : floor + 1;
+  };
+
+  /** Records a to-be-dropped entry's version as the id's floor, so a recreate exceeds it. */
+  const rememberFloor = (entry: LayerCacheEntry): void => {
+    const prev = versionFloors.get(entry.layerId) ?? -1;
+    if (entry.version > prev) {
+      versionFloors.set(entry.layerId, entry.version);
+    }
+  };
+
+  const get = (layerId: string): LayerCacheEntry | undefined => {
+    const entry = entries.get(layerId);
+    if (entry) {
+      touch(entry);
+    }
+    return entry;
+  };
+
+  const peek = (layerId: string): LayerCacheEntry | undefined => entries.get(layerId);
+
+  const getOrCreate = (layerId: string, width: number, height: number): LayerCacheEntry => {
+    const existing = entries.get(layerId);
+    if (existing) {
+      const changed =
+        existing.surface.width !== width ||
+        existing.surface.height !== height ||
+        existing.rect.x !== 0 ||
+        existing.rect.y !== 0;
+      const hadPublishedPixels = existing.hasPublishedPixels;
+      if (existing.surface.width !== width || existing.surface.height !== height) {
+        existing.surface.resize(width, height);
+        existing.hasPublishedPixels = false;
+        existing.stale = true;
+      }
+      // Origin-anchored: this variant always places the surface at (0, 0).
+      existing.rect = { height, width, x: 0, y: 0 };
+      touch(existing);
+      if (changed && hadPublishedPixels) {
+        existing.version += 1;
+        notifyVersionChange(layerId);
+      }
+      return existing;
+    }
+    const entry: LayerCacheEntry = {
+      hasPublishedPixels: false,
+      lastUsed: 0,
+      layerId,
+      rect: { height, width, x: 0, y: 0 },
+      stale: true,
+      surface: backend.createSurface(width, height),
+      version: initialVersion(layerId),
+    };
+    touch(entry);
+    entries.set(layerId, entry);
+    return entry;
+  };
+
+  const getOrCreateRect = (layerId: string, rect: Rect): LayerCacheEntry => {
+    const existing = entries.get(layerId);
+    if (existing) {
+      touch(existing);
+      return existing;
+    }
+    const width = Math.max(0, Math.round(rect.width));
+    const height = Math.max(0, Math.round(rect.height));
+    const entry: LayerCacheEntry = {
+      hasPublishedPixels: false,
+      lastUsed: 0,
+      layerId,
+      rect: { height, width, x: rect.x, y: rect.y },
+      stale: true,
+      surface: backend.createSurface(width, height),
+      version: initialVersion(layerId),
+    };
+    touch(entry);
+    entries.set(layerId, entry);
+    return entry;
+  };
+
+  const growToRect = (layerId: string, rect: Rect): LayerCacheEntry => {
+    const existing = entries.get(layerId);
+    const targetRect: Rect = {
+      height: Math.max(0, Math.round(rect.height)),
+      width: Math.max(0, Math.round(rect.width)),
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+    };
+    if (!existing) {
+      const entry: LayerCacheEntry = {
+        hasPublishedPixels: false,
+        lastUsed: 0,
+        layerId,
+        rect: targetRect,
+        stale: false,
+        surface: backend.createSurface(targetRect.width, targetRect.height),
+        version: initialVersion(layerId),
+      };
+      touch(entry);
+      entries.set(layerId, entry);
+      return entry;
+    }
+    const cur = existing.rect;
+    const curEmpty = cur.width <= 0 || cur.height <= 0;
+    // Union of the current extent and the requested rect (in layer-local space).
+    const minX = curEmpty ? targetRect.x : Math.min(cur.x, targetRect.x);
+    const minY = curEmpty ? targetRect.y : Math.min(cur.y, targetRect.y);
+    const maxX = curEmpty
+      ? targetRect.x + targetRect.width
+      : Math.max(cur.x + cur.width, targetRect.x + targetRect.width);
+    const maxY = curEmpty
+      ? targetRect.y + targetRect.height
+      : Math.max(cur.y + cur.height, targetRect.y + targetRect.height);
+    const newRect: Rect = { height: maxY - minY, width: maxX - minX, x: minX, y: minY };
+    if (newRect.x === cur.x && newRect.y === cur.y && newRect.width === cur.width && newRect.height === cur.height) {
+      // Already covers the request — no realloc.
+      touch(existing);
+      return existing;
+    }
+    // Snapshot the old pixels BEFORE resizing (resize clears the backing canvas),
+    // then blit them back at their new offset within the grown surface. Skip the
+    // copy when the old extent was empty (nothing to preserve).
+    const surface = existing.surface;
+    let snapshot: ImageData | null = null;
+    if (!curEmpty && cur.width > 0 && cur.height > 0) {
+      snapshot = surface.ctx.getImageData(0, 0, cur.width, cur.height);
+    }
+    surface.resize(newRect.width, newRect.height);
+    if (snapshot) {
+      surface.ctx.putImageData(snapshot, cur.x - newRect.x, cur.y - newRect.y);
+    }
+    existing.rect = newRect;
+    touch(existing);
+    if (existing.hasPublishedPixels) {
+      existing.version += 1;
+      notifyVersionChange(layerId);
+    }
+    return existing;
+  };
+
+  const prepareReplacement = (layerId: string, rect: Rect, pixels: RasterSurface): PreparedLayerCacheReplacement => {
+    const normalizedRect: Rect = {
+      height: Math.max(0, Math.round(rect.height)),
+      width: Math.max(0, Math.round(rect.width)),
+      x: rect.x,
+      y: rect.y,
+    };
+    const surface = backend.createSurface(normalizedRect.width, normalizedRect.height);
+    if (normalizedRect.width > 0 && normalizedRect.height > 0) {
+      surface.ctx.clearRect(0, 0, normalizedRect.width, normalizedRect.height);
+      surface.ctx.drawImage(pixels.canvas, 0, 0);
+    }
+    return { layerId, rect: normalizedRect, surface };
+  };
+
+  const installReplacement = (prepared: PreparedLayerCacheReplacement): LayerCacheEntry => {
+    const existing = entries.get(prepared.layerId);
+    if (existing) {
+      rememberFloor(existing);
+    }
+    const entry: LayerCacheEntry = {
+      hasPublishedPixels: true,
+      lastUsed: 0,
+      layerId: prepared.layerId,
+      rect: prepared.rect,
+      stale: false,
+      surface: prepared.surface,
+      // Directly-published pixels receive the same extra version bump that the
+      // old create-then-notify path applied, while remaining monotonic on swap.
+      version: initialVersion(prepared.layerId) + 1,
+    };
+    touch(entry);
+    entries.set(prepared.layerId, entry);
+    notifyVersionChange(prepared.layerId);
+    return entry;
+  };
+
+  const publishPixels = (layerId: string): LayerCacheEntry | undefined => {
+    const entry = entries.get(layerId);
+    if (!entry) {
+      return undefined;
+    }
+    entry.hasPublishedPixels = true;
+    entry.stale = false;
+    entry.version += 1;
+    notifyVersionChange(layerId);
+    return entry;
+  };
+
+  const invalidate = (layerId: string): void => {
+    const entry = entries.get(layerId);
+    if (entry) {
+      entry.version += 1;
+      entry.stale = true;
+      notifyVersionChange(layerId);
+    }
+  };
+
+  const del = (layerId: string): void => {
+    const entry = entries.get(layerId);
+    if (entry) {
+      rememberFloor(entry);
+      entries.delete(layerId);
+      notifyVersionChange(layerId);
+    }
+  };
+
+  const version = (layerId: string): number => entries.get(layerId)?.version ?? 0;
+
+  const byteSize = (): number => {
+    let total = 0;
+    for (const entry of entries.values()) {
+      total += surfaceBytes(entry.surface);
+    }
+    return total;
+  };
+
+  const evictHidden = (visibleIds: Iterable<string>, budgetBytes: number = DEFAULT_CACHE_BUDGET_BYTES): string[] => {
+    const visible = new Set(visibleIds);
+    const evicted: string[] = [];
+    let total = byteSize();
+    if (total <= budgetBytes) {
+      return evicted;
+    }
+    // Hidden entries, least-recently-used first.
+    const candidates = [...entries.values()]
+      .filter((entry) => !visible.has(entry.layerId))
+      .sort((a, b) => a.lastUsed - b.lastUsed);
+    for (const entry of candidates) {
+      if (total <= budgetBytes) {
+        break;
+      }
+      // Retain the version floor so a re-shown (re-rasterized) layer resumes ABOVE
+      // its pre-eviction version, not from 0 — otherwise the adjusted-surface /
+      // thumbnail caches would serve stale pixels keyed to the recycled version.
+      rememberFloor(entry);
+      entries.delete(entry.layerId);
+      evicted.push(entry.layerId);
+      total -= surfaceBytes(entry.surface);
+      notifyVersionChange(entry.layerId);
+    }
+    return evicted;
+  };
+
+  const dispose = (): void => {
+    entries.clear();
+  };
+
+  return {
+    byteSize,
+    delete: del,
+    dispose,
+    evictHidden,
+    get,
+    getOrCreate,
+    getOrCreateRect,
+    growToRect,
+    installReplacement,
+    invalidate,
+    peek,
+    prepareReplacement,
+    publishPixels,
+    version,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/maskFill.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/maskFill.test.ts
new file mode 100644
index 00000000000..889ed647e2e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/maskFill.test.ts
@@ -0,0 +1,93 @@
+import type { CanvasMaskFillContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import type { RasterCallLogEntry, StubRasterSurface } from './raster.testStub';
+
+import { colorizeMask, createMaskPatternTile } from './maskFill';
+import { createTestStubRasterBackend } from './raster.testStub';
+
+/** Values recorded for a set-property (e.g. `strokeStyle`), in order. */
+const setValues = (log: RasterCallLogEntry[], prop: string): unknown[] =>
+  log.filter((e) => e.op === 'set' && e.args[0] === prop).map((e) => e.args[1]);
+
+const countOp = (log: RasterCallLogEntry[], op: string): number => log.filter((e) => e.op === op).length;
+
+describe('createMaskPatternTile', () => {
+  it('returns null for the solid style (no pattern — filled directly)', () => {
+    const backend = createTestStubRasterBackend();
+    expect(createMaskPatternTile(backend, 'solid', '#ff0000')).toBeNull();
+  });
+
+  it('builds a colour-specific tile per non-solid style, stroking in the fill colour', () => {
+    const backend = createTestStubRasterBackend();
+    for (const style of ['grid', 'crosshatch', 'diagonal', 'horizontal', 'vertical'] as const) {
+      const tile = createMaskPatternTile(backend, style, '#00ff88') as StubRasterSurface;
+      expect(tile).not.toBeNull();
+      // Lines are drawn (stroke) in the fill colour.
+      expect(setValues(tile.callLog, 'strokeStyle')).toContain('#00ff88');
+      expect(countOp(tile.callLog, 'stroke')).toBeGreaterThan(0);
+    }
+  });
+
+  it('sizes tiles to the legacy specs (diagonal/crosshatch 6px, grid 12px, h/v 9px)', () => {
+    const backend = createTestStubRasterBackend();
+    const size = (style: CanvasMaskFillContract['style']): number =>
+      (createMaskPatternTile(backend, style, '#fff') as StubRasterSurface).width;
+    expect(size('diagonal')).toBe(6);
+    expect(size('crosshatch')).toBe(6);
+    expect(size('grid')).toBe(12);
+    expect(size('horizontal')).toBe(9);
+    expect(size('vertical')).toBe(9);
+  });
+
+  it('draws more lines for crosshatch (both directions) than diagonal (one direction)', () => {
+    const backend = createTestStubRasterBackend();
+    const diagonal = createMaskPatternTile(backend, 'diagonal', '#fff') as StubRasterSurface;
+    const crosshatch = createMaskPatternTile(backend, 'crosshatch', '#fff') as StubRasterSurface;
+    expect(countOp(crosshatch.callLog, 'stroke')).toBeGreaterThan(countOp(diagonal.callLog, 'stroke'));
+  });
+
+  it('horizontal draws only horizontal lines, vertical only vertical (equal counts, disjoint geometry)', () => {
+    const backend = createTestStubRasterBackend();
+    const horizontal = createMaskPatternTile(backend, 'horizontal', '#fff') as StubRasterSurface;
+    const vertical = createMaskPatternTile(backend, 'vertical', '#fff') as StubRasterSurface;
+    // Same 9px tile, same spacing → same number of strokes.
+    expect(countOp(horizontal.callLog, 'stroke')).toBe(countOp(vertical.callLog, 'stroke'));
+  });
+});
+
+describe('colorizeMask', () => {
+  const fill = (style: CanvasMaskFillContract['style'], color = '#ff0000'): CanvasMaskFillContract => ({
+    color,
+    style,
+  });
+
+  it('draws the mask stencil then fills the colour with source-in (solid)', () => {
+    const backend = createTestStubRasterBackend();
+    const mask = backend.createSurface(10, 10);
+    const out = colorizeMask(backend, mask, 10, 10, fill('solid'), null) as StubRasterSurface;
+
+    const ops = out.callLog;
+    const drawIdx = ops.findIndex((e) => e.op === 'drawImage');
+    const sourceInIdx = ops.findIndex(
+      (e) => e.op === 'set' && e.args[0] === 'globalCompositeOperation' && e.args[1] === 'source-in'
+    );
+    const fillRectIdx = ops.findIndex((e) => e.op === 'fillRect');
+    // Order: stencil blit → switch to source-in → fill the colour.
+    expect(drawIdx).toBeGreaterThanOrEqual(0);
+    expect(sourceInIdx).toBeGreaterThan(drawIdx);
+    expect(fillRectIdx).toBeGreaterThan(sourceInIdx);
+    expect(setValues(ops, 'fillStyle')).toContain('#ff0000');
+  });
+
+  it('uses the pattern tile as the fill when one is provided (pattern style)', () => {
+    const backend = createTestStubRasterBackend();
+    const mask = backend.createSurface(8, 8);
+    const tile = createMaskPatternTile(backend, 'diagonal', '#ff0000');
+    const out = colorizeMask(backend, mask, 8, 8, fill('diagonal'), tile) as StubRasterSurface;
+    // A repeat pattern was created and used as the source-in fill.
+    expect(countOp(out.callLog, 'createPattern')).toBe(1);
+    expect(out.callLog.some((e) => e.op === 'createPattern' && e.args[1] === 'repeat')).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/maskFill.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/maskFill.ts
new file mode 100644
index 00000000000..9967c413ee1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/maskFill.ts
@@ -0,0 +1,157 @@
+/**
+ * Mask fill rendering: turns a mask layer's alpha stencil into a tinted,
+ * translucent overlay coloured by its {@link CanvasMaskFillContract}.
+ *
+ * Mirrors legacy (`features/controlLayers/konva/CanvasEntity/CanvasEntityObjectRenderer.ts`):
+ * the mask objects are drawn as an opaque alpha stencil, then a fill (a solid
+ * colour, or one of five line PATTERNS) is composited over them with
+ * `globalCompositeOperation: 'source-in'` so the colour/pattern shows ONLY where
+ * the mask is painted. The whole overlay is drawn above all raster/control
+ * content at the layer's opacity (legacy default `1`).
+ *
+ * Pattern tiles are small, colour-specific, cached surfaces built through the
+ * {@link RasterBackend} seam (like the transparency checkerboard). Legacy anchors
+ * its pattern to the screen; here the colorized surface is drawn through the
+ * layer transform, so the pattern is OBJECT-anchored (it scales/pans with the
+ * mask content) — a deliberate, documented simplification of the screen-anchored
+ * legacy behaviour that keeps the whole pipeline node-testable through the seam.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { CanvasMaskFillContract } from '@workbench/types';
+
+import type { RasterBackend, RasterSurface } from './raster';
+
+/** Line specs (tile size, line spacing, stroke width) for each non-solid fill style. */
+const PATTERN_SPECS: Record<
+  Exclude<CanvasMaskFillContract['style'], 'solid'>,
+  { size: number; spacing: number; width: number }
+> = {
+  // 6px tile, two parallel 45° lines 3px apart (legacy `pattern-diagonal.svg`).
+  diagonal: { size: 6, spacing: 3, width: 1.3 },
+  // 6px tile, 45° lines in BOTH directions (legacy `pattern-crosshatch.svg`).
+  crosshatch: { size: 6, spacing: 3, width: 1.2 },
+  // 12px tile, 3 vertical + 3 horizontal lines 4px apart (legacy `pattern-grid.svg`).
+  grid: { size: 12, spacing: 4, width: 1 },
+  // 9px tile, 3 horizontal lines 3px apart (legacy `pattern-horizontal.svg`).
+  horizontal: { size: 9, spacing: 3, width: 1 },
+  // 9px tile, 3 vertical lines 3px apart (legacy `pattern-vertical.svg`).
+  vertical: { size: 9, spacing: 3, width: 1 },
+};
+
+/** Draws the anti-diagonal (`x + y = c`) or main-diagonal (`x - y = c`) line family across the tile. */
+const drawDiagonalLines = (
+  ctx: RasterSurface['ctx'],
+  size: number,
+  spacing: number,
+  direction: 'anti' | 'main'
+): void => {
+  // Sweep `c` well beyond the tile so every crossing line is drawn; the surface
+  // clips to its bounds. `spacing` divides `size`, so the family tiles seamlessly.
+  for (let c = -size; c <= 2 * size; c += spacing) {
+    ctx.beginPath();
+    if (direction === 'anti') {
+      // x + y = c: a long segment crossing the tile.
+      ctx.moveTo(c + size, -size);
+      ctx.lineTo(c - 2 * size, 2 * size);
+    } else {
+      // x - y = c.
+      ctx.moveTo(c - size, -size);
+      ctx.lineTo(c + 2 * size, 2 * size);
+    }
+    ctx.stroke();
+  }
+};
+
+/**
+ * Builds a colour-specific repeat tile for a non-solid fill `style`, or returns
+ * `null` for `'solid'` (no pattern — the colour is filled directly). The tile is
+ * drawn in `color` through the backend seam.
+ */
+export const createMaskPatternTile = (
+  backend: RasterBackend,
+  style: CanvasMaskFillContract['style'],
+  color: string
+): RasterSurface | null => {
+  if (style === 'solid') {
+    return null;
+  }
+  const spec = PATTERN_SPECS[style];
+  const tile = backend.createSurface(spec.size, spec.size);
+  const ctx = tile.ctx;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, spec.size, spec.size);
+  ctx.strokeStyle = color;
+  ctx.lineWidth = spec.width;
+
+  switch (style) {
+    case 'diagonal':
+      drawDiagonalLines(ctx, spec.size, spec.spacing, 'anti');
+      break;
+    case 'crosshatch':
+      drawDiagonalLines(ctx, spec.size, spec.spacing, 'anti');
+      drawDiagonalLines(ctx, spec.size, spec.spacing, 'main');
+      break;
+    case 'grid':
+    case 'horizontal':
+    case 'vertical': {
+      // Pixel-centred lines (0.5 offset) so 1px strokes stay crisp, matching
+      // the legacy SVG tiles (lines at 0.5 / 3.5 / 6.5, etc.).
+      for (let p = 0.5; p < spec.size; p += spec.spacing) {
+        if (style !== 'horizontal') {
+          ctx.beginPath();
+          ctx.moveTo(p, 0);
+          ctx.lineTo(p, spec.size);
+          ctx.stroke();
+        }
+        if (style !== 'vertical') {
+          ctx.beginPath();
+          ctx.moveTo(0, p);
+          ctx.lineTo(spec.size, p);
+          ctx.stroke();
+        }
+      }
+      break;
+    }
+  }
+  return tile;
+};
+
+/**
+ * Produces a colorized RGBA surface the size of the mask cache: the mask's alpha
+ * is the stencil, the `fill` supplies the colour (solid) or a repeat `tile`
+ * (pattern), composited `source-in`. The caller blits the result through the
+ * layer transform.
+ */
+export const colorizeMask = (
+  backend: RasterBackend,
+  mask: RasterSurface,
+  width: number,
+  height: number,
+  fill: CanvasMaskFillContract,
+  tile: RasterSurface | null,
+  target: RasterSurface | null = null
+): RasterSurface => {
+  const out = target ?? backend.createSurface(width, height);
+  if (out.width !== width || out.height !== height) {
+    out.resize(width, height);
+  }
+  const ctx = out.ctx;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+  // 1. The mask alpha stencil.
+  ctx.globalAlpha = 1;
+  ctx.globalCompositeOperation = 'source-over';
+  ctx.drawImage(mask.canvas, 0, 0);
+  // 2. Colour/pattern kept only where the stencil is opaque (`source-in`).
+  ctx.globalCompositeOperation = 'source-in';
+  if (tile) {
+    const pattern = ctx.createPattern(tile.canvas, 'repeat');
+    ctx.fillStyle = pattern ?? fill.color;
+  } else {
+    ctx.fillStyle = fill.color;
+  }
+  ctx.fillRect(0, 0, width, height);
+  return out;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/overlayRenderer.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/overlayRenderer.test.ts
new file mode 100644
index 00000000000..06a3f9eac00
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/overlayRenderer.test.ts
@@ -0,0 +1,186 @@
+import type { Mat2d, Rect } from '@workbench/canvas-engine/types';
+
+import { identity, scale } from '@workbench/canvas-engine/math/mat2d';
+import { describe, expect, it } from 'vitest';
+
+import type { OverlayState } from './overlayRenderer';
+import type { RasterCallLogEntry } from './raster.testStub';
+
+import { MIN_GRID_SPACING_PX, renderOverlay } from './overlayRenderer';
+import { createTestStubRasterBackend } from './raster.testStub';
+
+const BBOX: Rect = { height: 40, width: 40, x: 10, y: 10 };
+
+const findSet = (log: RasterCallLogEntry[], prop: string): unknown[] =>
+  log.filter((e) => e.op === 'set' && e.args[0] === prop).map((e) => e.args[1]);
+
+const baseState = (overrides: Partial<OverlayState> = {}): OverlayState => ({
+  bbox: BBOX,
+  view: identity(),
+  ...overrides,
+});
+
+describe('renderOverlay', () => {
+  it('clears then strokes ONLY the bbox (dashed) — no document outline (unbounded plane)', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+
+    renderOverlay(target, baseState());
+
+    const ops = target.callLog.map((e) => e.op);
+    expect(ops).toContain('clearRect');
+    // The document rect is retired as a visual boundary: the bbox is the only rect stroked.
+    expect(target.callLog.filter((e) => e.op === 'strokeRect')).toHaveLength(1);
+    // At least one dashed setLineDash for the bbox.
+    const dashArgs = target.callLog.filter((e) => e.op === 'setLineDash').map((e) => e.args[0]);
+    expect(dashArgs).toContainEqual([4, 4]);
+  });
+
+  it('draws no grid when showGrid is false', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(target, baseState({ gridSize: 10, showGrid: false }));
+    // No path building beyond stroking rects (no moveTo/lineTo for grid lines).
+    expect(target.callLog.some((e) => e.op === 'moveTo')).toBe(false);
+  });
+
+  it('draws grid lines when enabled and spacing is large enough', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(target, baseState({ gridSize: 20, showGrid: true, view: scale(identity(), 2) }));
+    expect(target.callLog.some((e) => e.op === 'moveTo')).toBe(true);
+    expect(target.callLog.some((e) => e.op === 'lineTo')).toBe(true);
+    expect(target.callLog.some((e) => e.op === 'stroke')).toBe(true);
+  });
+
+  it('skips the grid when zoomed out below the density threshold', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    // gridSize * scale below MIN_GRID_SPACING_PX -> too dense, skip.
+    const smallScale = (MIN_GRID_SPACING_PX - 1) / 10;
+    const view: Mat2d = scale(identity(), smallScale);
+    renderOverlay(target, baseState({ gridSize: 10, showGrid: true, view }));
+    expect(target.callLog.some((e) => e.op === 'moveTo')).toBe(false);
+  });
+
+  it('draws a brush cursor ring scaled from document units', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(
+      target,
+      baseState({ cursor: { point: { x: 50, y: 50 }, radiusDoc: 10 }, view: scale(identity(), 2) })
+    );
+
+    const arc = target.callLog.find((e) => e.op === 'arc');
+    expect(arc).toBeDefined();
+    // center = point * 2, radius = radiusDoc * scale(2) = 20.
+    expect(arc!.args.slice(0, 3)).toEqual([100, 100, 20]);
+  });
+
+  it('omits the cursor ring when cursor is null', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(target, baseState({ cursor: null }));
+    expect(target.callLog.some((e) => e.op === 'arc')).toBe(false);
+  });
+
+  it('strokes the bbox in its own accent color (no document-outline color)', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(target, baseState());
+    const strokeStyles = findSet(target.callLog, 'strokeStyle');
+    // With the document outline gone, the bbox is the only stroked chrome here:
+    // exactly one stroke color is applied.
+    expect(strokeStyles).toEqual(['#3b82f6']);
+  });
+
+  it('hides the passive bbox frame when showBbox is false', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(target, baseState({ showBbox: false }));
+    expect(target.callLog.filter((e) => e.op === 'strokeRect')).toHaveLength(0);
+  });
+
+  it('draws the bbox-overlay shade (evenodd punch-out) only when bboxOverlay is on', () => {
+    const backend = createTestStubRasterBackend();
+    const off = backend.createSurface(200, 200);
+    renderOverlay(off, baseState());
+    expect(off.callLog.some((e) => e.op === 'fill' && e.args[0] === 'evenodd')).toBe(false);
+
+    const on = backend.createSurface(200, 200);
+    renderOverlay(on, baseState({ bboxOverlay: true }));
+    // One even-odd fill: the viewport rect with the bbox rect punched out.
+    expect(on.callLog.filter((e) => e.op === 'fill' && e.args[0] === 'evenodd')).toHaveLength(1);
+    const rects = on.callLog.filter((e) => e.op === 'rect').map((e) => e.args);
+    expect(rects).toContainEqual([0, 0, 200, 200]);
+    expect(rects).toContainEqual([BBOX.x, BBOX.y, BBOX.width, BBOX.height]);
+  });
+
+  it('draws rule-of-thirds guides inside the bbox when enabled', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(target, baseState({ ruleOfThirds: true }));
+    // Four guide lines: two vertical + two horizontal moveTo/lineTo pairs.
+    const moveTos = target.callLog.filter((e) => e.op === 'moveTo');
+    expect(moveTos).toHaveLength(4);
+  });
+
+  it('draws the dedicated SAM mask preview before its bbox, handles, and colored points', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    const mask = backend.createSurface(20, 10);
+    renderOverlay(
+      target,
+      baseState({
+        samInput: {
+          bbox: { height: 30, width: 40, x: 20, y: 30 },
+          excludePoints: [{ x: 50, y: 60 }],
+          includePoints: [{ x: 30, y: 40 }],
+        },
+        samPreview: { opacity: 0.45, rect: { height: 10, width: 20, x: 20, y: 30 }, surface: mask },
+        showBbox: false,
+      })
+    );
+
+    const ops = target.callLog.map((entry) => entry.op);
+    const previewIndex = ops.indexOf('drawImage');
+    const bboxIndex = ops.indexOf('strokeRect');
+    const firstPointIndex = ops.indexOf('arc');
+    expect(previewIndex).toBeGreaterThan(-1);
+    expect(bboxIndex).toBeGreaterThan(previewIndex);
+    expect(firstPointIndex).toBeGreaterThan(bboxIndex);
+    expect(findSet(target.callLog, 'fillStyle')).toEqual(expect.arrayContaining(['#22c55e', '#ef4444']));
+  });
+
+  it.each([1, 4])('keeps SAM point and handle drawing screen-constant at %sx zoom', (zoom) => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(500, 500);
+    renderOverlay(
+      target,
+      baseState({
+        samInput: {
+          bbox: { height: 30, width: 40, x: 20, y: 30 },
+          excludePoints: [],
+          includePoints: [{ x: 30, y: 40 }],
+        },
+        showBbox: false,
+        view: scale(identity(), zoom),
+      })
+    );
+
+    const point = target.callLog.find((entry) => entry.op === 'arc');
+    const handles = target.callLog.filter((entry) => entry.op === 'fillRect');
+    expect(point?.args[2]).toBe(5);
+    expect(handles).toHaveLength(8);
+    expect(handles.every((entry) => entry.args[2] === 8 && entry.args[3] === 8)).toBe(true);
+  });
+
+  it('draws no SAM preview or geometry after cleanup', () => {
+    const backend = createTestStubRasterBackend();
+    const target = backend.createSurface(200, 200);
+    renderOverlay(target, baseState({ samInput: null, samPreview: null, showBbox: false }));
+
+    expect(target.callLog.some((entry) => entry.op === 'drawImage' || entry.op === 'arc')).toBe(false);
+    expect(target.callLog.filter((entry) => entry.op === 'strokeRect')).toHaveLength(0);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/overlayRenderer.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/overlayRenderer.ts
new file mode 100644
index 00000000000..a83e8232cfd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/overlayRenderer.ts
@@ -0,0 +1,546 @@
+/**
+ * Renders the interaction overlay — the second stacked canvas above the
+ * composited document: bbox rectangle, an optional viewport-wide grid, and
+ * the brush cursor ring. Everything is drawn in screen space (document points
+ * projected through `view`) so strokes stay a constant pixel width regardless
+ * of zoom. The canvas is an unbounded plane, so no document-bounds outline is
+ * drawn.
+ *
+ * Marching ants and transform handles come later; the functions here are kept
+ * small and composable so those can slot in. Every pixel operation flows
+ * through the {@link RasterSurface} `ctx` seam. Zero React, zero import-time
+ * side effects.
+ */
+
+import type { Mat2d, Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+import { applyToPoint, getScale, invert } from '@workbench/canvas-engine/math/mat2d';
+import { transformBounds } from '@workbench/canvas-engine/math/rect';
+import { drawMarchingAnts, type MarchingAntsRender } from '@workbench/canvas-engine/selection/marchingAnts';
+import { BBOX_HANDLES, bboxHandlePoint } from '@workbench/canvas-engine/tools/bboxHitTest';
+import { TRANSFORM_ROTATE_NUB_PX } from '@workbench/canvas-engine/transform/transformMath';
+
+import type { RasterSurface } from './raster';
+
+/** Minimum screen-space grid spacing (px) below which the grid is too dense to draw. */
+export const MIN_GRID_SPACING_PX = 8;
+
+const BBOX_COLOR = '#3b82f6';
+const BBOX_DASH: readonly number[] = [4, 4];
+/** The bbox-overlay dim fill (legacy `CanvasBboxToolModule` overlayRect parity). */
+const BBOX_OVERLAY_FILL = 'hsl(220 12% 10% / 0.8)';
+const GRID_COLOR = 'rgba(128, 128, 128, 0.25)';
+const CURSOR_COLOR = '#ffffff';
+/** Side length (screen px) of a drawn bbox resize handle. */
+const BBOX_HANDLE_DRAW_PX = 8;
+const BBOX_HANDLE_FILL = '#ffffff';
+/** Solid accent used for the selected-layer bounds outline while the move tool is active. */
+const LAYER_OUTLINE_COLOR = '#38bdf8';
+/** Accent for the transform frame (outline, handles, rotation nub). */
+const TRANSFORM_COLOR = '#38bdf8';
+const TRANSFORM_HANDLE_FILL = '#ffffff';
+/** Side length (screen px) of a drawn transform scale handle. */
+const TRANSFORM_HANDLE_DRAW_PX = 8;
+/** Screen-px radius of the rotation-indicator knob at the nub's tip. */
+const TRANSFORM_ROTATE_KNOB_PX = 3.5;
+
+/** The brush cursor ring: center in document space, radius in document units. */
+export interface OverlayCursor {
+  point: Vec2;
+  radiusDoc: number;
+}
+
+/** Everything the overlay needs to draw a frame. */
+export interface OverlayState {
+  /** Document→screen transform. */
+  view: Mat2d;
+  /** Generation bounding box in document space. */
+  bbox: Rect;
+  /** Whether to draw the eight bbox resize handles (bbox tool active). */
+  bboxHandles?: boolean;
+  /** Whether to draw the passive bbox frame (default when absent: drawn). */
+  showBbox?: boolean;
+  /** Whether to dim everything outside the bbox (the legacy "bbox overlay" shade). */
+  bboxOverlay?: boolean;
+  /** Whether to draw the rule-of-thirds guides inside the bbox. */
+  ruleOfThirds?: boolean;
+  /** Whether to draw the grid. */
+  showGrid?: boolean;
+  /** Grid spacing in document units. */
+  gridSize?: number;
+  /** Brush cursor ring, or `null`/absent to hide it. */
+  cursor?: OverlayCursor | null;
+  /**
+   * A layer's rendered-bounds outline (the move tool's selection marquee): the
+   * four document-space corners, projected through `view` and stroked as a closed
+   * polygon. Absent/`null` to hide it.
+   */
+  layerOutline?: readonly Vec2[] | null;
+  /**
+   * The active transform-tool frame: the layer's rotated bounds, its eight scale
+   * handles, and the center/top-edge points for the rotation nub — all in
+   * document space, projected through `view`. Absent/`null` when no transform
+   * session is active.
+   */
+  transformFrame?: TransformFrameOverlay | null;
+  /**
+   * The in-progress lasso polygon (document-space points), drawn as a live dashed
+   * outline while a lasso drag is underway. Absent/`null` when idle.
+   */
+  lassoPreview?: readonly Vec2[] | null;
+  /**
+   * The committed selection's marching ants: the outline paths (document space)
+   * plus the animated dash phase. Absent/`null` when there is no selection.
+   */
+  marchingAnts?: MarchingAntsRender | null;
+  /**
+   * The in-progress shape-tool drag (document-space rect + kind), drawn as a
+   * live outline while a shape is being created. Absent/`null` when idle.
+   */
+  shapePreview?: { rect: Rect; kind: 'rect' | 'ellipse' } | null;
+  /**
+   * The in-progress gradient-tool drag vector (document-space start/end),
+   * drawn as a direction indicator. Absent/`null` when idle.
+   */
+  gradientPreview?: { start: Vec2; end: Vec2 } | null;
+  /** Dedicated Select Object mask preview, already colorized by the engine. */
+  samPreview?: { surface: RasterSurface; rect: Rect; opacity: number } | null;
+  /** Select Object visual prompt geometry in document space. */
+  samInput?: { includePoints: readonly Vec2[]; excludePoints: readonly Vec2[]; bbox: Rect | null } | null;
+}
+
+/** Document-space geometry the overlay draws for an active transform session. */
+export interface TransformFrameOverlay {
+  /** The four rotated-rect corners (closed polygon). */
+  corners: readonly Vec2[];
+  /** The eight scale-handle positions. */
+  handles: readonly Vec2[];
+  /** The layer center (rotation nub direction reference). */
+  center: Vec2;
+  /** The top edge midpoint (root of the rotation nub). */
+  rotationAnchor: Vec2;
+}
+
+type Ctx = RasterSurface['ctx'];
+
+const strokeRectScreen = (ctx: Ctx, screenRect: Rect): void => {
+  ctx.strokeRect(screenRect.x, screenRect.y, screenRect.width, screenRect.height);
+};
+
+/**
+ * Draws grid lines across the entire viewport, in screen space, skipping when
+ * too dense. The canvas is an unbounded plane, so the grid is not clipped to any
+ * document rect: the visible screen rect is projected back into document space
+ * (via the inverse view) and snapped out to whole grid cells so the lines tile
+ * seamlessly while panning/zooming.
+ */
+const drawGrid = (ctx: Ctx, state: OverlayState, target: RasterSurface): void => {
+  const gridSize = state.gridSize ?? 0;
+  if (gridSize <= 0) {
+    return;
+  }
+  const scale = getScale(state.view);
+  if (gridSize * scale < MIN_GRID_SPACING_PX) {
+    return;
+  }
+
+  const { view } = state;
+  const inv = invert(view);
+  if (!inv) {
+    return;
+  }
+  // Document-space bounds of the viewport's four screen corners.
+  const corners = [
+    applyToPoint(inv, { x: 0, y: 0 }),
+    applyToPoint(inv, { x: target.width, y: 0 }),
+    applyToPoint(inv, { x: 0, y: target.height }),
+    applyToPoint(inv, { x: target.width, y: target.height }),
+  ];
+  const xs = corners.map((p) => p.x);
+  const ys = corners.map((p) => p.y);
+  // Snap outward to whole grid cells so lines are stable across pan/zoom.
+  const left = Math.floor(Math.min(...xs) / gridSize) * gridSize;
+  const top = Math.floor(Math.min(...ys) / gridSize) * gridSize;
+  const right = Math.ceil(Math.max(...xs) / gridSize) * gridSize;
+  const bottom = Math.ceil(Math.max(...ys) / gridSize) * gridSize;
+
+  ctx.save();
+  ctx.strokeStyle = GRID_COLOR;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([]);
+  ctx.beginPath();
+  for (let x = left; x <= right; x += gridSize) {
+    const a = applyToPoint(view, { x, y: top });
+    const b = applyToPoint(view, { x, y: bottom });
+    ctx.moveTo(a.x, a.y);
+    ctx.lineTo(b.x, b.y);
+  }
+  for (let y = top; y <= bottom; y += gridSize) {
+    const a = applyToPoint(view, { x: left, y });
+    const b = applyToPoint(view, { x: right, y });
+    ctx.moveTo(a.x, a.y);
+    ctx.lineTo(b.x, b.y);
+  }
+  ctx.stroke();
+  ctx.restore();
+};
+
+/** Draws the brush cursor ring at the pointer, radius scaled from document units. */
+const drawCursor = (ctx: Ctx, state: OverlayState): void => {
+  const cursor = state.cursor;
+  if (!cursor) {
+    return;
+  }
+  const center = applyToPoint(state.view, cursor.point);
+  const radius = cursor.radiusDoc * getScale(state.view);
+  ctx.save();
+  ctx.strokeStyle = CURSOR_COLOR;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([]);
+  ctx.beginPath();
+  ctx.arc(center.x, center.y, Math.max(0, radius), 0, Math.PI * 2);
+  ctx.stroke();
+  ctx.restore();
+};
+
+/** Draws a layer's rendered-bounds outline as a closed polygon in screen space. */
+const drawLayerOutline = (ctx: Ctx, state: OverlayState): void => {
+  const corners = state.layerOutline;
+  if (!corners || corners.length < 2) {
+    return;
+  }
+  ctx.save();
+  ctx.strokeStyle = LAYER_OUTLINE_COLOR;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([]);
+  ctx.beginPath();
+  corners.forEach((corner, index) => {
+    const p = applyToPoint(state.view, corner);
+    if (index === 0) {
+      ctx.moveTo(p.x, p.y);
+    } else {
+      ctx.lineTo(p.x, p.y);
+    }
+  });
+  ctx.closePath();
+  ctx.stroke();
+  ctx.restore();
+};
+
+/**
+ * Draws the transform frame (rotated bounds polygon, eight scale handles, and a
+ * rotation nub past the top edge) in screen space. Handles/nub stay a constant
+ * pixel size; the nub direction follows the rotated frame (top-edge → away from
+ * center), so it reads correctly at any layer rotation.
+ */
+const drawTransformFrame = (ctx: Ctx, state: OverlayState): void => {
+  const frame = state.transformFrame;
+  if (!frame || frame.corners.length < 3) {
+    return;
+  }
+  const { view } = state;
+  ctx.save();
+  ctx.setLineDash([]);
+  ctx.strokeStyle = TRANSFORM_COLOR;
+  ctx.lineWidth = 1;
+
+  // Bounds polygon.
+  ctx.beginPath();
+  frame.corners.forEach((corner, index) => {
+    const p = applyToPoint(view, corner);
+    if (index === 0) {
+      ctx.moveTo(p.x, p.y);
+    } else {
+      ctx.lineTo(p.x, p.y);
+    }
+  });
+  ctx.closePath();
+  ctx.stroke();
+
+  // Rotation nub: from the top-edge midpoint, outward (away from center), a
+  // constant screen length; a small knob at the tip.
+  const anchor = applyToPoint(view, frame.rotationAnchor);
+  const center = applyToPoint(view, frame.center);
+  const dx = anchor.x - center.x;
+  const dy = anchor.y - center.y;
+  const len = Math.hypot(dx, dy) || 1;
+  const nx = anchor.x + (dx / len) * TRANSFORM_ROTATE_NUB_PX;
+  const ny = anchor.y + (dy / len) * TRANSFORM_ROTATE_NUB_PX;
+  ctx.beginPath();
+  ctx.moveTo(anchor.x, anchor.y);
+  ctx.lineTo(nx, ny);
+  ctx.stroke();
+  ctx.beginPath();
+  ctx.fillStyle = TRANSFORM_HANDLE_FILL;
+  ctx.arc(nx, ny, TRANSFORM_ROTATE_KNOB_PX, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.stroke();
+
+  // Scale handles.
+  const half = TRANSFORM_HANDLE_DRAW_PX / 2;
+  ctx.fillStyle = TRANSFORM_HANDLE_FILL;
+  for (const handle of frame.handles) {
+    const p = applyToPoint(view, handle);
+    ctx.fillRect(p.x - half, p.y - half, TRANSFORM_HANDLE_DRAW_PX, TRANSFORM_HANDLE_DRAW_PX);
+    ctx.strokeRect(p.x - half, p.y - half, TRANSFORM_HANDLE_DRAW_PX, TRANSFORM_HANDLE_DRAW_PX);
+  }
+  ctx.restore();
+};
+
+const LASSO_PREVIEW_COLOR = '#38bdf8';
+const LASSO_PREVIEW_DASH: readonly number[] = [4, 4];
+
+/** Draws the in-progress lasso polygon as a dashed screen-space outline. */
+const drawLassoPreview = (ctx: Ctx, state: OverlayState): void => {
+  const points = state.lassoPreview;
+  if (!points || points.length < 2) {
+    return;
+  }
+  ctx.save();
+  ctx.strokeStyle = LASSO_PREVIEW_COLOR;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([...LASSO_PREVIEW_DASH]);
+  ctx.beginPath();
+  points.forEach((point, index) => {
+    const p = applyToPoint(state.view, point);
+    if (index === 0) {
+      ctx.moveTo(p.x, p.y);
+    } else {
+      ctx.lineTo(p.x, p.y);
+    }
+  });
+  // Close the loop back to the start so the enclosed region reads clearly.
+  ctx.closePath();
+  ctx.stroke();
+  ctx.setLineDash([]);
+  ctx.restore();
+};
+
+/** Draws the shape-tool drag preview (rect or ellipse outline) in screen space. */
+const drawShapePreview = (ctx: Ctx, state: OverlayState): void => {
+  const preview = state.shapePreview;
+  if (!preview || preview.rect.width <= 0 || preview.rect.height <= 0) {
+    return;
+  }
+  const screen = transformBounds(state.view, preview.rect);
+  ctx.save();
+  ctx.strokeStyle = LAYER_OUTLINE_COLOR;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([...BBOX_DASH]);
+  ctx.beginPath();
+  if (preview.kind === 'ellipse') {
+    ctx.ellipse(
+      screen.x + screen.width / 2,
+      screen.y + screen.height / 2,
+      Math.abs(screen.width) / 2,
+      Math.abs(screen.height) / 2,
+      0,
+      0,
+      Math.PI * 2
+    );
+  } else {
+    ctx.rect(screen.x, screen.y, screen.width, screen.height);
+  }
+  ctx.stroke();
+  ctx.setLineDash([]);
+  ctx.restore();
+};
+
+/** Draws the gradient-tool drag vector (a line with endpoint dots) in screen space. */
+const drawGradientPreview = (ctx: Ctx, state: OverlayState): void => {
+  const preview = state.gradientPreview;
+  if (!preview) {
+    return;
+  }
+  const start = applyToPoint(state.view, preview.start);
+  const end = applyToPoint(state.view, preview.end);
+  ctx.save();
+  ctx.strokeStyle = LAYER_OUTLINE_COLOR;
+  ctx.fillStyle = LAYER_OUTLINE_COLOR;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([]);
+  ctx.beginPath();
+  ctx.moveTo(start.x, start.y);
+  ctx.lineTo(end.x, end.y);
+  ctx.stroke();
+  for (const point of [start, end]) {
+    ctx.beginPath();
+    ctx.arc(point.x, point.y, 3, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  ctx.restore();
+};
+
+const SAM_BBOX_COLOR = '#f59e0b';
+const SAM_INCLUDE_COLOR = '#22c55e';
+const SAM_EXCLUDE_COLOR = '#ef4444';
+const SAM_POINT_RADIUS_PX = 5;
+const SAM_HANDLE_DRAW_PX = 8;
+
+const drawSamPreview = (ctx: Ctx, state: OverlayState): void => {
+  const preview = state.samPreview;
+  if (!preview) {
+    return;
+  }
+  const { view } = state;
+  ctx.save();
+  ctx.setTransform(view.a, view.b, view.c, view.d, view.e, view.f);
+  ctx.globalAlpha = preview.opacity;
+  ctx.drawImage(preview.surface.canvas, preview.rect.x, preview.rect.y, preview.rect.width, preview.rect.height);
+  ctx.restore();
+};
+
+const drawSamGeometry = (ctx: Ctx, state: OverlayState): void => {
+  const input = state.samInput;
+  if (!input) {
+    return;
+  }
+  ctx.save();
+  ctx.lineWidth = 1;
+  ctx.strokeStyle = SAM_BBOX_COLOR;
+  ctx.setLineDash([...BBOX_DASH]);
+  if (input.bbox) {
+    const screenRect = transformBounds(state.view, input.bbox);
+    ctx.strokeRect(screenRect.x, screenRect.y, screenRect.width, screenRect.height);
+    ctx.setLineDash([]);
+    ctx.fillStyle = BBOX_HANDLE_FILL;
+    const half = SAM_HANDLE_DRAW_PX / 2;
+    for (const handle of BBOX_HANDLES) {
+      const center = bboxHandlePoint(screenRect, handle);
+      ctx.fillRect(center.x - half, center.y - half, SAM_HANDLE_DRAW_PX, SAM_HANDLE_DRAW_PX);
+      ctx.strokeRect(center.x - half, center.y - half, SAM_HANDLE_DRAW_PX, SAM_HANDLE_DRAW_PX);
+    }
+  }
+  ctx.setLineDash([]);
+  for (const [points, color] of [
+    [input.includePoints, SAM_INCLUDE_COLOR],
+    [input.excludePoints, SAM_EXCLUDE_COLOR],
+  ] as const) {
+    ctx.fillStyle = color;
+    ctx.strokeStyle = '#ffffff';
+    for (const point of points) {
+      const screen = applyToPoint(state.view, point);
+      ctx.beginPath();
+      ctx.arc(screen.x, screen.y, SAM_POINT_RADIUS_PX, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.stroke();
+    }
+  }
+  ctx.restore();
+};
+
+/**
+ * Draws the bbox overlay shade: a translucent dark fill over the ENTIRE viewport
+ * with the bbox region punched out (even-odd fill rule — the two nested rect paths
+ * cancel inside the bbox), dimming everything outside the generation frame. Fill
+ * color matches legacy `CanvasBboxToolModule`'s overlayRect.
+ */
+const drawBboxOverlayShade = (ctx: Ctx, state: OverlayState, target: RasterSurface): void => {
+  if (!state.bboxOverlay) {
+    return;
+  }
+  const bboxScreen = transformBounds(state.view, state.bbox);
+  ctx.save();
+  ctx.fillStyle = BBOX_OVERLAY_FILL;
+  ctx.beginPath();
+  ctx.rect(0, 0, target.width, target.height);
+  ctx.rect(bboxScreen.x, bboxScreen.y, bboxScreen.width, bboxScreen.height);
+  ctx.fill('evenodd');
+  ctx.restore();
+};
+
+/**
+ * Draws the rule-of-thirds guides: two vertical and two horizontal lines dividing
+ * the bbox into thirds (screen space, solid, in the grid color). A composition aid
+ * over the generation frame.
+ */
+const drawRuleOfThirds = (ctx: Ctx, state: OverlayState): void => {
+  if (!state.ruleOfThirds) {
+    return;
+  }
+  const r = transformBounds(state.view, state.bbox);
+  ctx.save();
+  ctx.setLineDash([]);
+  ctx.strokeStyle = GRID_COLOR;
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  for (let i = 1; i <= 2; i++) {
+    const x = r.x + (r.width * i) / 3;
+    const y = r.y + (r.height * i) / 3;
+    ctx.moveTo(x, r.y);
+    ctx.lineTo(x, r.y + r.height);
+    ctx.moveTo(r.x, y);
+    ctx.lineTo(r.x + r.width, y);
+  }
+  ctx.stroke();
+  ctx.restore();
+};
+
+/** Draws the eight bbox resize handles as small squares at the frame's corners/edges (screen space). */
+const drawBboxHandles = (ctx: Ctx, state: OverlayState): void => {
+  if (!state.bboxHandles) {
+    return;
+  }
+  const screenRect = transformBounds(state.view, state.bbox);
+  const half = BBOX_HANDLE_DRAW_PX / 2;
+  ctx.save();
+  ctx.setLineDash([]);
+  ctx.fillStyle = BBOX_HANDLE_FILL;
+  ctx.strokeStyle = BBOX_COLOR;
+  ctx.lineWidth = 1;
+  for (const handle of BBOX_HANDLES) {
+    const center = bboxHandlePoint(screenRect, handle);
+    ctx.fillRect(center.x - half, center.y - half, BBOX_HANDLE_DRAW_PX, BBOX_HANDLE_DRAW_PX);
+    ctx.strokeRect(center.x - half, center.y - half, BBOX_HANDLE_DRAW_PX, BBOX_HANDLE_DRAW_PX);
+  }
+  ctx.restore();
+};
+
+/** Clears and redraws the entire overlay for the given `state`. */
+export const renderOverlay = (target: RasterSurface, state: OverlayState): void => {
+  const ctx = target.ctx;
+
+  ctx.save();
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, target.width, target.height);
+
+  // The document rect is retired as a visual boundary (unbounded plane), so no
+  // document outline is drawn. The bbox (generation frame) is the primary anchor.
+
+  // The bbox overlay shade first: it dims the composited document outside the
+  // bbox, and every piece of overlay chrome (grid, guides, frame) draws over it.
+  drawBboxOverlayShade(ctx, state, target);
+
+  // Grid next (behind the bbox), spanning the whole viewport.
+  if (state.showGrid) {
+    drawGrid(ctx, state, target);
+  }
+
+  // Rule-of-thirds guides sit inside the bbox, behind its frame.
+  drawRuleOfThirds(ctx, state);
+
+  // Bbox (dashed, distinct color). Drawn as passive chrome unless the setting hides
+  // it (`showBbox === false`); the handles below still render for the bbox tool so
+  // the frame stays editable even when hidden.
+  if (state.showBbox ?? true) {
+    ctx.strokeStyle = BBOX_COLOR;
+    ctx.setLineDash([...BBOX_DASH]);
+    strokeRectScreen(ctx, transformBounds(state.view, state.bbox));
+    ctx.setLineDash([]);
+  }
+
+  drawSamPreview(ctx, state);
+  drawSamGeometry(ctx, state);
+  drawLayerOutline(ctx, state);
+  drawBboxHandles(ctx, state);
+  drawTransformFrame(ctx, state);
+  if (state.marchingAnts) {
+    drawMarchingAnts(ctx, state.view, state.marchingAnts);
+  }
+  drawLassoPreview(ctx, state);
+  drawShapePreview(ctx, state);
+  drawGradientPreview(ctx, state);
+  drawCursor(ctx, state);
+
+  ctx.restore();
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.testStub.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.testStub.test.ts
new file mode 100644
index 00000000000..cbc1d62a1a1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.testStub.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import { createTestStubRasterBackend } from './raster.testStub';
+
+describe('createTestStubRasterBackend', () => {
+  it('creates a surface with the requested dimensions', () => {
+    const backend = createTestStubRasterBackend();
+    const surface = backend.createSurface(64, 32);
+    expect(surface.width).toBe(64);
+    expect(surface.height).toBe(32);
+  });
+
+  it('resize updates the surface dimensions and logs the call', () => {
+    const backend = createTestStubRasterBackend();
+    const surface = backend.createSurface(10, 10);
+    surface.resize(20, 40);
+    expect(surface.width).toBe(20);
+    expect(surface.height).toBe(40);
+    expect(surface.callLog).toContainEqual({ op: 'resize', args: [20, 40] });
+  });
+
+  it('records draw calls made against the surface context', () => {
+    const backend = createTestStubRasterBackend();
+    const surface = backend.createSurface(10, 10);
+    const ctx = surface.ctx;
+
+    ctx.save();
+    ctx.clearRect(0, 0, 10, 10);
+    ctx.setTransform(1, 0, 0, 1, 5, 5);
+    ctx.fill();
+    ctx.restore();
+
+    const ops = surface.callLog.map((entry) => entry.op);
+    expect(ops).toEqual(['save', 'clearRect', 'setTransform', 'fill', 'restore']);
+    expect(surface.callLog[1]).toEqual({ op: 'clearRect', args: [0, 0, 10, 10] });
+    expect(surface.callLog[2]).toEqual({ op: 'setTransform', args: [1, 0, 0, 1, 5, 5] });
+  });
+
+  it('getImageData returns a correctly-sized, zeroed buffer', () => {
+    const backend = createTestStubRasterBackend();
+    const surface = backend.createSurface(4, 3);
+    const imageData = surface.ctx.getImageData(0, 0, 4, 3);
+    expect(imageData.width).toBe(4);
+    expect(imageData.height).toBe(3);
+    expect(imageData.data.length).toBe(4 * 3 * 4);
+    expect(Array.from(imageData.data).every((v) => v === 0)).toBe(true);
+  });
+
+  it('putImageData is recorded in the call log', () => {
+    const backend = createTestStubRasterBackend();
+    const surface = backend.createSurface(2, 2);
+    const imageData = surface.ctx.getImageData(0, 0, 2, 2);
+    surface.ctx.putImageData(imageData, 0, 0);
+    expect(surface.callLog.at(-1)).toEqual({ op: 'putImageData', args: [imageData, 0, 0] });
+  });
+
+  it('createImageBitmap resolves to a bitmap-shaped object', async () => {
+    const backend = createTestStubRasterBackend();
+    const fakeSource = {} as ImageBitmapSource;
+    const bitmap = await backend.createImageBitmap(fakeSource);
+    expect(bitmap).toHaveProperty('width');
+    expect(bitmap).toHaveProperty('height');
+  });
+
+  it('encodeSurface resolves to a deterministic, size-keyed image blob', async () => {
+    const backend = createTestStubRasterBackend();
+    const surface = backend.createSurface(8, 4);
+    const blob = await backend.encodeSurface(surface);
+    expect(blob).toBeInstanceOf(Blob);
+    expect(blob.type).toBe('image/png');
+    // Deterministic: same-size surfaces encode to identical bytes.
+    const again = await backend.encodeSurface(backend.createSurface(8, 4));
+    expect(await blob.text()).toBe(await again.text());
+    // Size participates in the encoding, so different sizes differ.
+    const other = await backend.encodeSurface(backend.createSurface(8, 5));
+    expect(await other.text()).not.toBe(await blob.text());
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.testStub.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.testStub.ts
new file mode 100644
index 00000000000..ed281a8671b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.testStub.ts
@@ -0,0 +1,178 @@
+/**
+ * A node-safe `RasterBackend` stub for vitest. Surfaces are backed by a
+ * fake 2D context that records every call it receives instead of touching
+ * a real canvas, so engine tests can assert on what was drawn without a
+ * DOM or `OffscreenCanvas`.
+ *
+ * The subset of `CanvasRenderingContext2D` the engine currently uses is
+ * implemented as recorded methods (save/restore/clearRect/fillRect/
+ * strokeRect/drawImage/path building/fill/stroke/clip/createPattern/
+ * createLinearGradient/createRadialGradient/setTransform/
+ * getImageData/putImageData/setLineDash). Gradients returned by the
+ * `create*Gradient` factories record their `addColorStop` calls on the same
+ * surface call log. Property assignments (fillStyle,
+ * globalAlpha, globalCompositeOperation, ...) are recorded too, via a
+ * `{ op: 'set', args: [prop, value] }` entry, so tests can assert that
+ * opacity/blend/style state was applied in order. Extend the method table in
+ * `createStubCtx` below as later tasks need more of the API surface.
+ */
+
+import type { RasterBackend, RasterSurface } from './raster';
+
+/** A single recorded call made against a stub context. */
+export interface RasterCallLogEntry {
+  op: string;
+  args: unknown[];
+}
+
+/** A `RasterSurface` created by the test stub backend, with its call log exposed. */
+export interface StubRasterSurface extends RasterSurface {
+  readonly callLog: RasterCallLogEntry[];
+}
+
+/** A `RasterBackend` whose `createSurface` returns the call-log-bearing `StubRasterSurface`. */
+export interface StubRasterBackend extends RasterBackend {
+  createSurface(width: number, height: number): StubRasterSurface;
+}
+
+const createStubImageData = (width: number, height: number): ImageData => {
+  const data = new Uint8ClampedArray(Math.max(0, width) * Math.max(0, height) * 4);
+  return { colorSpace: 'srgb', data, height, width } as unknown as ImageData;
+};
+
+/**
+ * Deterministic per-character advance the stub's {@link measureText} multiplies
+ * by the current font's pixel size — the same `0.6` factor the text rasterizer's
+ * pure `estimateTextExtent` uses (`TEXT_CHAR_WIDTH_FACTOR`), so a text layer's
+ * measured surface size in node tests exactly matches its estimated extent.
+ */
+const STUB_CHAR_WIDTH_FACTOR = 0.6;
+
+/** Extracts the `px` size from a CSS `font` shorthand (e.g. `"700 48px Inter"` → 48), defaulting to 10. */
+const fontSizeFromShorthand = (font: unknown): number => {
+  const match = typeof font === 'string' ? /(\d+(?:\.\d+)?)px/.exec(font) : null;
+  return match ? parseFloat(match[1] ?? '10') : 10;
+};
+
+const createStubCtx = (callLog: RasterCallLogEntry[]): OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D => {
+  const log = (op: string, args: unknown[]): void => {
+    callLog.push({ args, op });
+  };
+
+  // Stored non-method property values (fillStyle, globalAlpha, font, etc.).
+  // Declared before the method table so `measureText` can read the current
+  // `font` to produce font-size-dependent metrics.
+  const props: Record<string, unknown> = {};
+
+  const methods: Record<string, (...args: unknown[]) => unknown> = {
+    arc: (...args: unknown[]) => log('arc', args),
+    beginPath: (...args: unknown[]) => log('beginPath', args),
+    clearRect: (...args: unknown[]) => log('clearRect', args),
+    clip: (...args: unknown[]) => log('clip', args),
+    closePath: (...args: unknown[]) => log('closePath', args),
+    fillText: (...args: unknown[]) => log('fillText', args),
+    // Deterministic, font-size-aware metrics: width = chars × fontSizePx × 0.6.
+    // No DOM/real canvas needed, so text measurement is reproducible in node.
+    measureText: (...args: unknown[]) => {
+      log('measureText', args);
+      const text = String(args[0] ?? '');
+      const width = text.length * fontSizeFromShorthand(props.font) * STUB_CHAR_WIDTH_FACTOR;
+      return { width } as unknown as TextMetrics;
+    },
+    createLinearGradient: (...args: unknown[]) => {
+      log('createLinearGradient', args);
+      // A recording CanvasGradient stand-in: every addColorStop is logged on
+      // the surface's own call log (as `addColorStop`), so tests can assert the
+      // stop offsets/colors that were applied to the gradient.
+      return {
+        addColorStop: (...stopArgs: unknown[]) => log('addColorStop', stopArgs),
+      } as unknown as CanvasGradient;
+    },
+    createPattern: (...args: unknown[]) => {
+      log('createPattern', args);
+      // A non-null marker standing in for a CanvasPattern, so callers that
+      // guard on a null return (e.g. the checkerboard fill) proceed.
+      return { __stubPattern: true } as unknown as CanvasPattern;
+    },
+    createRadialGradient: (...args: unknown[]) => {
+      log('createRadialGradient', args);
+      return {
+        addColorStop: (...stopArgs: unknown[]) => log('addColorStop', stopArgs),
+      } as unknown as CanvasGradient;
+    },
+    drawImage: (...args: unknown[]) => log('drawImage', args),
+    ellipse: (...args: unknown[]) => log('ellipse', args),
+    fill: (...args: unknown[]) => log('fill', args),
+    fillRect: (...args: unknown[]) => log('fillRect', args),
+    getImageData: (...args: unknown[]) => {
+      const [sx, sy, sw, sh] = args as [number, number, number, number];
+      log('getImageData', [sx, sy, sw, sh]);
+      return createStubImageData(sw, sh);
+    },
+    lineTo: (...args: unknown[]) => log('lineTo', args),
+    moveTo: (...args: unknown[]) => log('moveTo', args),
+    putImageData: (...args: unknown[]) => log('putImageData', args),
+    rect: (...args: unknown[]) => log('rect', args),
+    restore: (...args: unknown[]) => log('restore', args),
+    save: (...args: unknown[]) => log('save', args),
+    setLineDash: (...args: unknown[]) => log('setLineDash', args),
+    setTransform: (...args: unknown[]) => log('setTransform', args),
+    stroke: (...args: unknown[]) => log('stroke', args),
+    strokeRect: (...args: unknown[]) => log('strokeRect', args),
+  };
+
+  // The proxy records every property assignment (into `props`, declared above)
+  // so tests can assert on applied state.
+  const proxy = new Proxy(methods, {
+    get(target, prop: string) {
+      if (prop in target) {
+        return target[prop];
+      }
+      return props[prop];
+    },
+    set(_target, prop: string, value: unknown) {
+      props[prop] = value;
+      log('set', [prop, value]);
+      return true;
+    },
+  });
+
+  return proxy as unknown as OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+};
+
+class StubRasterSurfaceImpl implements StubRasterSurface {
+  readonly callLog: RasterCallLogEntry[] = [];
+  readonly canvas: OffscreenCanvas | HTMLCanvasElement;
+  readonly ctx: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+  width: number;
+  height: number;
+
+  constructor(width: number, height: number) {
+    this.width = width;
+    this.height = height;
+    this.canvas = { height, width } as unknown as OffscreenCanvas | HTMLCanvasElement;
+    this.ctx = createStubCtx(this.callLog);
+  }
+
+  resize(w: number, h: number): void {
+    this.callLog.push({ args: [w, h], op: 'resize' });
+    this.width = w;
+    this.height = h;
+  }
+}
+
+/**
+ * Creates a `RasterBackend` whose surfaces are backed by a fake, node-safe
+ * 2D context that records draw calls instead of executing them.
+ */
+export const createTestStubRasterBackend = (): StubRasterBackend => ({
+  createImageBitmap: (source: ImageBitmapSource): Promise<ImageBitmap> => {
+    void source;
+    return Promise.resolve({ close: () => {}, height: 0, width: 0 } as unknown as ImageBitmap);
+  },
+  createSurface: (width: number, height: number): StubRasterSurface => new StubRasterSurfaceImpl(width, height),
+  // Deterministic fake blob keyed on the surface size, so encode calls are
+  // reproducible in node without touching a real canvas.
+  encodeSurface: (surface: RasterSurface, type = 'image/png'): Promise<Blob> =>
+    Promise.resolve(new Blob([`stub-surface-${surface.width}x${surface.height}`], { type })),
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.ts
new file mode 100644
index 00000000000..d9768165a2c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/raster.ts
@@ -0,0 +1,119 @@
+/**
+ * The RasterBackend seam: every place the engine needs a 2D canvas surface
+ * or an ImageBitmap, it goes through an injected `RasterBackend` instead of
+ * calling `document.createElement('canvas')` / `new OffscreenCanvas(...)`
+ * directly. This keeps the engine testable in node — tests inject
+ * `render/raster.testStub.ts`'s stub backend instead of `createDomRasterBackend()`.
+ */
+
+/** A single drawable/resizable 2D surface, backed by either an OffscreenCanvas or an HTMLCanvasElement. */
+export interface RasterSurface {
+  readonly canvas: OffscreenCanvas | HTMLCanvasElement;
+  readonly ctx: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+  readonly width: number;
+  readonly height: number;
+  resize(w: number, h: number): void;
+}
+
+/** Injectable factory for raster surfaces and image bitmaps. */
+export interface RasterBackend {
+  createSurface(width: number, height: number): RasterSurface;
+  createImageBitmap(source: ImageBitmapSource): Promise<ImageBitmap>;
+  /**
+   * Encodes a surface's pixels to an image `Blob` (PNG by default). Used by the
+   * bitmap store to persist painted layers as content-hashed server images.
+   */
+  encodeSurface(surface: RasterSurface, type?: string): Promise<Blob>;
+}
+
+const isOffscreenCanvasSupported = (): boolean => typeof OffscreenCanvas !== 'undefined';
+
+/** Encodes a DOM/Offscreen surface's canvas to an image `Blob`. */
+const encodeDomSurface = (surface: RasterSurface, type: string): Promise<Blob> => {
+  const { canvas } = surface;
+  if (typeof (canvas as OffscreenCanvas).convertToBlob === 'function') {
+    return (canvas as OffscreenCanvas).convertToBlob({ type });
+  }
+  const htmlCanvas = canvas as HTMLCanvasElement;
+  return new Promise((resolve, reject) => {
+    htmlCanvas.toBlob((blob) => {
+      if (blob) {
+        resolve(blob);
+      } else {
+        reject(new Error('Failed to encode canvas surface to a Blob'));
+      }
+    }, type);
+  });
+};
+
+class OffscreenRasterSurface implements RasterSurface {
+  canvas: OffscreenCanvas;
+  ctx: OffscreenCanvasRenderingContext2D;
+  width: number;
+  height: number;
+
+  constructor(width: number, height: number) {
+    this.canvas = new OffscreenCanvas(width, height);
+    const ctx = this.canvas.getContext('2d');
+    if (!ctx) {
+      throw new Error('Failed to acquire a 2D context from OffscreenCanvas');
+    }
+    this.ctx = ctx;
+    this.width = width;
+    this.height = height;
+  }
+
+  resize(w: number, h: number): void {
+    this.canvas.width = w;
+    this.canvas.height = h;
+    this.width = w;
+    this.height = h;
+  }
+}
+
+class DomCanvasRasterSurface implements RasterSurface {
+  canvas: HTMLCanvasElement;
+  ctx: CanvasRenderingContext2D;
+  width: number;
+  height: number;
+
+  constructor(width: number, height: number) {
+    this.canvas = document.createElement('canvas');
+    this.canvas.width = width;
+    this.canvas.height = height;
+    const ctx = this.canvas.getContext('2d');
+    if (!ctx) {
+      throw new Error('Failed to acquire a 2D context from HTMLCanvasElement');
+    }
+    this.ctx = ctx;
+    this.width = width;
+    this.height = height;
+  }
+
+  resize(w: number, h: number): void {
+    this.canvas.width = w;
+    this.canvas.height = h;
+    this.width = w;
+    this.height = h;
+  }
+}
+
+/**
+ * Creates a `RasterBackend` backed by the DOM/browser: `OffscreenCanvas`
+ * when available, falling back to `HTMLCanvasElement` otherwise (notably
+ * Safari < 16.4, which lacks `OffscreenCanvas` support).
+ */
+export const createDomRasterBackend = (): RasterBackend => {
+  const useOffscreen = isOffscreenCanvasSupported();
+  return {
+    createSurface(width: number, height: number): RasterSurface {
+      return useOffscreen ? new OffscreenRasterSurface(width, height) : new DomCanvasRasterSurface(width, height);
+    },
+    createImageBitmap(source: ImageBitmapSource): Promise<ImageBitmap> {
+      return createImageBitmap(source);
+    },
+    encodeSurface(surface: RasterSurface, type = 'image/png'): Promise<Blob> {
+      return encodeDomSurface(surface, type);
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterComposite.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterComposite.ts
new file mode 100644
index 00000000000..ed392ee3530
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterComposite.ts
@@ -0,0 +1,244 @@
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Mat2d, Rect } from '@workbench/canvas-engine/types';
+import type {
+  CanvasAdjustmentsContract,
+  CanvasBlendMode,
+  CanvasDocumentContractV2,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { fromTRS, multiply } from '@workbench/canvas-engine/math/mat2d';
+import { roundOut, transformBounds, union } from '@workbench/canvas-engine/math/rect';
+import { adjustmentsKey, applyAdjustments, isIdentityAdjustments } from '@workbench/canvas-engine/render/adjustments';
+import { blendToComposite } from '@workbench/canvas-engine/render/compositor';
+
+type Ctx = RasterSurface['ctx'];
+
+/** The engine-owned structural subset needed to plan and render a raster layer contribution. */
+export interface CompositeLayerRef {
+  id: string;
+  sourceRef: string;
+  contentSize: { width: number; height: number };
+  contentOffset: { x: number; y: number };
+  transform: { x: number; y: number; scaleX: number; scaleY: number; rotation: number };
+  opacity: number;
+  blendMode: CanvasBlendMode;
+  adjustments?: CanvasAdjustmentsContract;
+}
+
+/** The engine-owned structural subset consumed by the raster compositor. */
+export interface CompositeEntry {
+  bbox: Rect;
+  layers: readonly CompositeLayerRef[];
+}
+
+export interface BaseRasterCompositeEntry extends CompositeEntry {
+  key: string;
+  kind: 'base-raster';
+  layers: CompositeLayerRef[];
+}
+
+export interface RenderRasterCompositeDeps {
+  backend: {
+    createSurface(width: number, height: number): RasterSurface;
+  };
+  getLayerSurface(layerId: string): Promise<{ surface: RasterSurface; rect: Rect }>;
+  readImageData?(surface: RasterSurface, rect: Rect): ImageData;
+  writeImageData?(surface: RasterSurface, imageData: ImageData, x: number, y: number): void;
+}
+
+const defaultReadImageData = (surface: RasterSurface, rect: Rect): ImageData =>
+  surface.ctx.getImageData(rect.x, rect.y, rect.width, rect.height);
+
+const defaultWriteImageData = (surface: RasterSurface, imageData: ImageData, x: number, y: number): void =>
+  surface.ctx.putImageData(imageData, x, y);
+
+/** True when a layer is an enabled raster layer with rasterizable, non-empty pixels. */
+const isBaseRasterLayer = (layer: CanvasLayerContract): layer is CanvasRasterLayerContractV2 => {
+  if (!layer.isEnabled || layer.type !== 'raster') {
+    return false;
+  }
+  if (layer.source.type === 'image') {
+    return true;
+  }
+  return layer.source.type === 'paint' && layer.source.bitmap !== null;
+};
+
+/** A stable string identifying a source's pixels (its asset name, or an empty sentinel). */
+const sourceRefOf = (source: CanvasLayerSourceContract): string => {
+  switch (source.type) {
+    case 'image':
+      return `image:${source.image.imageName}`;
+    case 'paint':
+      return source.bitmap ? `paint:${source.bitmap.imageName}` : 'paint:empty';
+    default:
+      return `${source.type}:unsupported`;
+  }
+};
+
+/** The native (unscaled) content rect of a base-raster layer's source (layer-local). */
+const contentRectOf = (layer: CanvasRasterLayerContractV2, doc: CanvasDocumentContractV2): Rect => {
+  const { source } = layer;
+  if (source.type === 'image') {
+    return { height: source.image.height, width: source.image.width, x: 0, y: 0 };
+  }
+  if (source.type === 'paint' && source.bitmap) {
+    const offset = source.offset ?? { x: 0, y: 0 };
+    return { height: source.bitmap.height, width: source.bitmap.width, x: offset.x, y: offset.y };
+  }
+  return { height: doc.height, width: doc.width, x: 0, y: 0 };
+};
+
+/** Projects a document layer into its frozen composite contribution. */
+const toLayerRef = (layer: CanvasRasterLayerContractV2, doc: CanvasDocumentContractV2): CompositeLayerRef => {
+  const rect = contentRectOf(layer, doc);
+  const hasAdjustments = !isIdentityAdjustments(layer.adjustments);
+  return {
+    blendMode: layer.blendMode,
+    contentOffset: { x: rect.x, y: rect.y },
+    contentSize: { height: rect.height, width: rect.width },
+    id: layer.id,
+    opacity: layer.opacity,
+    sourceRef: sourceRefOf(layer.source),
+    ...(hasAdjustments && layer.adjustments ? { adjustments: layer.adjustments } : {}),
+    transform: {
+      rotation: layer.transform.rotation,
+      scaleX: layer.transform.scaleX,
+      scaleY: layer.transform.scaleY,
+      x: layer.transform.x,
+      y: layer.transform.y,
+    },
+  };
+};
+
+const rectKey = (rect: Rect): string => `${rect.x},${rect.y},${rect.width},${rect.height}`;
+
+const layerKey = (ref: CompositeLayerRef): string => {
+  const t = ref.transform;
+  const o = ref.contentOffset;
+  return [
+    ref.id,
+    ref.sourceRef,
+    o.x,
+    o.y,
+    t.x,
+    t.y,
+    t.scaleX,
+    t.scaleY,
+    t.rotation,
+    ref.opacity,
+    ref.blendMode,
+    ref.adjustments ? adjustmentsKey(ref.adjustments) : '-',
+  ].join(':');
+};
+
+/** Union of the provided composite-layer bounds in document space, or `null` when empty. */
+export const getCompositeLayerBounds = (layers: readonly CompositeLayerRef[]): Rect | null => {
+  let bounds: Rect | null = null;
+  for (const ref of layers) {
+    const nativeRect: Rect = {
+      height: ref.contentSize.height,
+      width: ref.contentSize.width,
+      x: ref.contentOffset.x,
+      y: ref.contentOffset.y,
+    };
+    const layerBounds = transformBounds(layerMatrix(ref), nativeRect);
+    bounds = bounds === null ? layerBounds : union(bounds, layerBounds);
+  }
+  return bounds;
+};
+
+/** Plans the enabled base-raster layers over an exact document-space rectangle. */
+export const planBaseRasterComposite = (document: CanvasDocumentContractV2, rect: Rect): BaseRasterCompositeEntry => {
+  const layers = document.layers.filter(isBaseRasterLayer).map((layer) => toLayerRef(layer, document));
+  return {
+    bbox: rect,
+    key: `base-raster|${rectKey(rect)}|${layers.map(layerKey).join('|')}`,
+    kind: 'base-raster',
+    layers,
+  };
+};
+
+/** Tight outward-rounded bounds of all enabled raster content in the document. */
+export const getBaseRasterContentBounds = (document: CanvasDocumentContractV2): Rect | null => {
+  const bounds = getCompositeLayerBounds(planBaseRasterComposite(document, document.bbox).layers);
+  return bounds === null ? null : roundOut(bounds);
+};
+
+/** Document→bbox translate matrix (the "view" the entry is composited under). */
+const bboxView = (bbox: Rect): Mat2d => ({ a: 1, b: 0, c: 0, d: 1, e: -bbox.x, f: -bbox.y });
+
+/** Applies a matrix to a 2D context's transform. */
+const setTransform = (ctx: Ctx, m: Mat2d): void => {
+  ctx.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
+};
+
+/** The layer's local→document transform matrix. */
+const layerMatrix = (ref: CompositeLayerRef): Mat2d =>
+  fromTRS(
+    { x: ref.transform.x, y: ref.transform.y },
+    ref.transform.rotation,
+    ref.transform.scaleX,
+    ref.transform.scaleY
+  );
+
+/** Composites an entry's layers, in z-order, onto a fresh bbox-sized surface. */
+export const renderRasterComposite = async (
+  entry: CompositeEntry,
+  deps: RenderRasterCompositeDeps
+): Promise<RasterSurface> => {
+  const { bbox } = entry;
+  const width = Math.max(0, bbox.width);
+  const height = Math.max(0, bbox.height);
+  const surface = deps.backend.createSurface(width, height);
+  const ctx = surface.ctx;
+  const readImageData = deps.readImageData ?? defaultReadImageData;
+  const writeImageData = deps.writeImageData ?? defaultWriteImageData;
+
+  setTransform(ctx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+  ctx.clearRect(0, 0, surface.width, surface.height);
+
+  const view = bboxView(bbox);
+  // Layers are stored top-first (index 0 = top-most); draw bottom→top.
+  for (let i = entry.layers.length - 1; i >= 0; i--) {
+    const ref = entry.layers[i];
+    if (!ref) {
+      continue;
+    }
+    const layerSurface = await deps.getLayerSurface(ref.id);
+    if (ref.adjustments) {
+      // Bake non-destructive adjustments so the generated image matches what the
+      // user sees: render this layer alone into a bbox temp, apply the LUTs, then
+      // composite the adjusted temp with the layer's opacity/blend.
+      const temp = deps.backend.createSurface(width, height);
+      const tempCtx = temp.ctx;
+      setTransform(tempCtx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+      tempCtx.clearRect(0, 0, width, height);
+      setTransform(tempCtx, multiply(view, layerMatrix(ref)));
+      tempCtx.drawImage(layerSurface.surface.canvas, layerSurface.rect.x, layerSurface.rect.y);
+      const fullRect: Rect = { height, width, x: 0, y: 0 };
+      const pixels = readImageData(temp, fullRect);
+      applyAdjustments(pixels, ref.adjustments);
+      writeImageData(temp, pixels, 0, 0);
+      ctx.save();
+      setTransform(ctx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+      ctx.globalAlpha = ref.opacity;
+      ctx.globalCompositeOperation = blendToComposite(ref.blendMode);
+      ctx.drawImage(temp.canvas, 0, 0);
+      ctx.restore();
+      continue;
+    }
+    ctx.save();
+    ctx.globalAlpha = ref.opacity;
+    ctx.globalCompositeOperation = blendToComposite(ref.blendMode);
+    setTransform(ctx, multiply(view, layerMatrix(ref)));
+    // Draw the cache at its layer-local content origin (content-sized paint
+    // layers place their pixels off-zero).
+    ctx.drawImage(layerSurface.surface.canvas, layerSurface.rect.x, layerSurface.rect.y);
+    ctx.restore();
+  }
+
+  return surface;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/gradientRasterizer.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/gradientRasterizer.test.ts
new file mode 100644
index 00000000000..ba15212d22a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/gradientRasterizer.test.ts
@@ -0,0 +1,112 @@
+import type { StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it } from 'vitest';
+
+import type { RasterizeDeps } from './types';
+
+import { rasterizeGradientSource } from './gradientRasterizer';
+
+type GradientSource = Extract<CanvasLayerSourceContract, { type: 'gradient' }>;
+
+const makeDeps = (): RasterizeDeps => {
+  const backend = createTestStubRasterBackend();
+  return {
+    backend,
+    documentSize: { height: 200, width: 300 },
+    resolver: () => Promise.resolve(new Blob()),
+    store: createLayerCacheStore(backend),
+  };
+};
+
+const ops = (surface: StubRasterSurface): string[] => surface.callLog.map((e) => e.op);
+
+const grad = (over: Partial<GradientSource> = {}): GradientSource => ({
+  angle: 0,
+  kind: 'linear',
+  stops: [
+    { color: '#000000', offset: 0 },
+    { color: '#ffffff', offset: 1 },
+  ],
+  type: 'gradient',
+  ...over,
+});
+
+describe('rasterizeGradientSource — extent', () => {
+  it('defaults to the DOCUMENT extent for a legacy gradient (no explicit width/height)', async () => {
+    const deps = makeDeps();
+    const { rect, surface } = await rasterizeGradientSource(grad(), deps);
+    expect(surface.width).toBe(300);
+    expect(surface.height).toBe(200);
+    expect(rect).toEqual({ height: 200, width: 300, x: 0, y: 0 });
+    expect(ops(surface as StubRasterSurface)).toContain('fillRect');
+  });
+
+  it('uses the explicit width/height extent when present (content-sized)', async () => {
+    const deps = makeDeps();
+    const { rect, surface } = await rasterizeGradientSource(grad({ height: 90, width: 120 }), deps);
+    expect(surface.width).toBe(120);
+    expect(surface.height).toBe(90);
+    expect(rect).toEqual({ height: 90, width: 120, x: 0, y: 0 });
+  });
+});
+
+describe('rasterizeGradientSource — linear', () => {
+  it('creates a linear gradient and applies every stop', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeGradientSource(grad({ angle: 90 }), deps)).surface as StubRasterSurface;
+    expect(ops(surface)).toContain('createLinearGradient');
+    const stops = surface.callLog.filter((e) => e.op === 'addColorStop');
+    expect(stops).toHaveLength(2);
+    expect(stops[0]?.args).toEqual([0, '#000000']);
+    expect(stops[1]?.args).toEqual([1, '#ffffff']);
+  });
+
+  it('does not create a radial gradient for the linear kind', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeGradientSource(grad(), deps)).surface as StubRasterSurface;
+    expect(ops(surface)).not.toContain('createRadialGradient');
+  });
+});
+
+describe('rasterizeGradientSource — radial', () => {
+  it('creates a radial gradient covering the document and applies stops', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeGradientSource(grad({ kind: 'radial' }), deps)).surface as StubRasterSurface;
+    expect(ops(surface)).toContain('createRadialGradient');
+    expect(ops(surface)).not.toContain('createLinearGradient');
+    const stops = surface.callLog.filter((e) => e.op === 'addColorStop');
+    expect(stops).toHaveLength(2);
+  });
+
+  it('supports more than two stops', async () => {
+    const deps = makeDeps();
+    const surface = (
+      await rasterizeGradientSource(
+        grad({
+          stops: [
+            { color: '#000000', offset: 0 },
+            { color: '#ff0000', offset: 0.5 },
+            { color: '#ffffff', offset: 1 },
+          ],
+        }),
+        deps
+      )
+    ).surface as StubRasterSurface;
+    const stops = surface.callLog.filter((e) => e.op === 'addColorStop');
+    expect(stops).toHaveLength(3);
+  });
+});
+
+describe('rasterizeGradientSource — target reuse', () => {
+  it('resizes and reuses a provided target surface to the document size', async () => {
+    const deps = makeDeps();
+    const target = deps.backend.createSurface(10, 10);
+    const { surface } = await rasterizeGradientSource(grad(), deps, target);
+    expect(surface).toBe(target);
+    expect(surface.width).toBe(300);
+    expect(surface.height).toBe(200);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/gradientRasterizer.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/gradientRasterizer.ts
new file mode 100644
index 00000000000..fc314890140
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/gradientRasterizer.ts
@@ -0,0 +1,78 @@
+/**
+ * Rasterizes a `gradient` layer source (linear / radial). Gradient layers are
+ * PARAMETRIC and CONTENT-SIZED: the source carries an explicit `width`/`height`
+ * extent (set bbox-sized at creation, preserved across angle edits) and the
+ * gradient spans that extent. Legacy gradients that predate the extent field
+ * default to the document dims (see {@link RasterizeDeps.documentSize}), so they
+ * render identically. The compositor positions the extent via the layer transform.
+ *
+ * Linear: the gradient line runs through the extent center along `angle`
+ * (degrees; 0° = left→right), long enough to cover the box corners. Radial:
+ * centered on the extent, radius reaching the farthest corner.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import type { RasterizeDeps, RasterizeResult } from './types';
+
+type GradientSource = Extract<CanvasLayerSourceContract, { type: 'gradient' }>;
+type Ctx = RasterSurface['ctx'];
+
+/** Builds the CSS-like gradient for the source across a `width`×`height` box. */
+const buildGradient = (ctx: Ctx, source: GradientSource, width: number, height: number): CanvasGradient => {
+  const cx = width / 2;
+  const cy = height / 2;
+
+  let gradient: CanvasGradient;
+  if (source.kind === 'radial') {
+    const radius = Math.hypot(width / 2, height / 2);
+    gradient = ctx.createRadialGradient(cx, cy, 0, cx, cy, radius);
+  } else {
+    const rad = (source.angle * Math.PI) / 180;
+    const dx = Math.cos(rad);
+    const dy = Math.sin(rad);
+    // Half-length along the direction that just covers the box (projection of
+    // the box's half-extents onto the gradient direction).
+    const half = (Math.abs(dx) * width + Math.abs(dy) * height) / 2;
+    gradient = ctx.createLinearGradient(cx - dx * half, cy - dy * half, cx + dx * half, cy + dy * half);
+  }
+
+  for (const stop of source.stops) {
+    // Clamp offsets defensively: `addColorStop` throws for out-of-range values.
+    gradient.addColorStop(Math.min(1, Math.max(0, stop.offset)), stop.color);
+  }
+  return gradient;
+};
+
+/**
+ * Draws a gradient source into a surface sized to its explicit extent (or the
+ * document dims for legacy gradients), reusing `target` if provided. Synchronous
+ * work wrapped in a resolved promise so it shares the `rasterizeSource` dispatch
+ * signature.
+ */
+export const rasterizeGradientSource = (
+  source: GradientSource,
+  deps: RasterizeDeps,
+  target?: RasterSurface
+): Promise<RasterizeResult> => {
+  const width = Math.max(1, Math.round(source.width ?? deps.documentSize.width));
+  const height = Math.max(1, Math.round(source.height ?? deps.documentSize.height));
+
+  const surface = target ?? deps.backend.createSurface(width, height);
+  if (surface.width !== width || surface.height !== height) {
+    surface.resize(width, height);
+  }
+  const { ctx } = surface;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+
+  if (source.stops.length > 0) {
+    ctx.fillStyle = buildGradient(ctx, source, width, height);
+    ctx.fillRect(0, 0, width, height);
+  }
+
+  return Promise.resolve({ rect: { height, width, x: 0, y: 0 }, surface });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/imageRasterizer.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/imageRasterizer.ts
new file mode 100644
index 00000000000..270e04d2b99
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/imageRasterizer.ts
@@ -0,0 +1,75 @@
+/**
+ * Rasterizes an `image` layer source: decodes the referenced asset to an
+ * `ImageBitmap` (cached per image name in the store) and blits it onto a
+ * surface sized to the bitmap.
+ *
+ * Decoding is async and goes entirely through injected seams (the resolver
+ * for bytes, the backend for `createImageBitmap`), so it runs in node tests
+ * with fakes. Zero React, zero import-time side effects.
+ */
+
+import type { DecodedBitmapLease } from '@workbench/canvas-engine/render/decodedBitmapPool';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasImageRef } from '@workbench/types';
+
+import { createDecodedBitmapPool } from '@workbench/canvas-engine/render/decodedBitmapPool';
+
+import type { RasterizeDeps, RasterizeResult } from './types';
+
+/** Acquires a short-lived decoded bitmap lease, coalescing concurrent decodes by image name. */
+export const resolveBitmap = async (image: CanvasImageRef, deps: RasterizeDeps): Promise<DecodedBitmapLease> => {
+  deps.signal?.throwIfAborted();
+  const pool = deps.bitmapPool ?? createDecodedBitmapPool();
+  const lease = await pool.acquire(
+    image.imageName,
+    async (decodeSignal) => {
+      const blob = await deps.resolver(image.imageName, decodeSignal);
+      decodeSignal?.throwIfAborted();
+      const bitmap = await deps.backend.createImageBitmap(blob);
+      if (decodeSignal?.aborted) {
+        bitmap.close();
+        decodeSignal.throwIfAborted();
+      }
+      return bitmap;
+    },
+    deps.signal
+  );
+  if (deps.signal?.aborted) {
+    lease.release();
+    deps.signal.throwIfAborted();
+  }
+  return lease;
+};
+
+/** Draws a bitmap onto a surface sized to `width`x`height`, reusing `target` if given. */
+export const blitBitmap = (
+  bitmap: ImageBitmap,
+  width: number,
+  height: number,
+  deps: RasterizeDeps,
+  target?: RasterSurface
+): RasterSurface => {
+  const surface = target ?? deps.backend.createSurface(width, height);
+  if (surface.width !== width || surface.height !== height) {
+    surface.resize(width, height);
+  }
+  surface.ctx.clearRect(0, 0, width, height);
+  surface.ctx.drawImage(bitmap, 0, 0);
+  return surface;
+};
+
+/** Rasterizes an `image` source into a surface sized to the image ref. */
+export const rasterizeImageSource = async (
+  source: { type: 'image'; image: CanvasImageRef },
+  deps: RasterizeDeps,
+  target?: RasterSurface
+): Promise<RasterizeResult> => {
+  const lease = await resolveBitmap(source.image, deps);
+  try {
+    const { height, width } = source.image;
+    const surface = blitBitmap(lease.bitmap, width, height, deps, target);
+    return { rect: { height, width, x: 0, y: 0 }, surface };
+  } finally {
+    lease.release();
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/index.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/index.ts
new file mode 100644
index 00000000000..76c0c33676e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/index.ts
@@ -0,0 +1,54 @@
+/**
+ * Source rasterizer dispatch.
+ *
+ * Given a layer `source`, produces a {@link RasterSurface} holding its
+ * rasterized pixels. `image`, `paint`, `shape`, `gradient`, and `text` are
+ * implemented. A `polygon` shape (no points-editing UX yet) throws — the
+ * dispatch only routes rect/ellipse.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import type { RasterizeDeps, RasterizeResult } from './types';
+
+import { rasterizeGradientSource } from './gradientRasterizer';
+import { rasterizeImageSource } from './imageRasterizer';
+import { rasterizePaintSource } from './paintRasterizer';
+import { rasterizeShapeSource } from './shapeRasterizer';
+import { rasterizeTextSource } from './textRasterizer';
+
+export type { ImageResolver, RasterizeDeps, RasterizeResult } from './types';
+export { rasterizeGradientSource } from './gradientRasterizer';
+export { rasterizeImageSource } from './imageRasterizer';
+export { rasterizePaintSource } from './paintRasterizer';
+export { rasterizeShapeSource } from './shapeRasterizer';
+export { rasterizeTextSource } from './textRasterizer';
+
+/**
+ * Rasterizes any supported layer source into a surface. Throws only for the
+ * deferred `polygon` shape kind (no rasterizer yet).
+ */
+export const rasterizeSource = (
+  source: CanvasLayerSourceContract,
+  deps: RasterizeDeps,
+  target?: RasterSurface
+): Promise<RasterizeResult> => {
+  switch (source.type) {
+    case 'image':
+      return rasterizeImageSource(source, deps, target);
+    case 'paint':
+      return rasterizePaintSource(source, deps, target);
+    case 'shape':
+      if (source.kind === 'polygon') {
+        throw new Error("rasterizeSource: 'polygon' shapes are not implemented yet (deferred)");
+      }
+      return rasterizeShapeSource(source, deps, target);
+    case 'gradient':
+      return rasterizeGradientSource(source, deps, target);
+    case 'text':
+      return rasterizeTextSource(source, deps, target);
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/paintRasterizer.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/paintRasterizer.ts
new file mode 100644
index 00000000000..996f0282bb6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/paintRasterizer.ts
@@ -0,0 +1,47 @@
+/**
+ * Rasterizes a `paint` layer source. Paint layers are CONTENT-SIZED: the
+ * persisted bitmap covers only the painted region, positioned in the layer's
+ * local space by the source `offset` (default `{ x: 0, y: 0 }` for legacy
+ * document-sized bitmaps). When the source has a bitmap it is decoded and
+ * blitted onto a surface sized to the bitmap; when it is `null` the layer is
+ * empty and the result is a zero-rect surface (a brand-new / cleared layer).
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasImageRef } from '@workbench/types';
+
+import type { RasterizeDeps, RasterizeResult } from './types';
+
+import { blitBitmap, resolveBitmap } from './imageRasterizer';
+
+/** A `paint` source (its optional layer-local bitmap offset). */
+type PaintSource = { type: 'paint'; bitmap: CanvasImageRef | null; offset?: { x: number; y: number } };
+
+/** Rasterizes a `paint` source into a content-sized surface placed at its offset. */
+export const rasterizePaintSource = async (
+  source: PaintSource,
+  deps: RasterizeDeps,
+  target?: RasterSurface
+): Promise<RasterizeResult> => {
+  if (source.bitmap) {
+    const { height, width } = source.bitmap;
+    const offset = source.offset ?? { x: 0, y: 0 };
+    const lease = await resolveBitmap(source.bitmap, deps);
+    try {
+      const surface = blitBitmap(lease.bitmap, width, height, deps, target);
+      return { rect: { height, width, x: offset.x, y: offset.y }, surface };
+    } finally {
+      lease.release();
+    }
+  }
+
+  // No bitmap yet: an empty (zero-rect) layer. Collapse any reused target to 0×0
+  // so the empty-layer invariants (skip in composite/hit-test/flush) hold.
+  const surface = target ?? deps.backend.createSurface(0, 0);
+  if (surface.width !== 0 || surface.height !== 0) {
+    surface.resize(0, 0);
+  }
+  return { rect: { height: 0, width: 0, x: 0, y: 0 }, surface };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/rasterizeSource.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/rasterizeSource.test.ts
new file mode 100644
index 00000000000..4b5bc34e98e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/rasterizeSource.test.ts
@@ -0,0 +1,232 @@
+import type { RasterBackend } from '@workbench/canvas-engine/render/raster';
+import type { CanvasImageRef, CanvasLayerSourceContract } from '@workbench/types';
+
+import { createDecodedBitmapPool } from '@workbench/canvas-engine/render/decodedBitmapPool';
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ImageResolver, RasterizeDeps } from './types';
+
+import { rasterizeSource } from './index';
+
+const imageRef = (imageName: string, width = 32, height = 16): CanvasImageRef => ({ height, imageName, width });
+
+/** A backend whose `createImageBitmap` is a spy returning a closable fake bitmap. */
+const createSpyBackend = () => {
+  const stub = createTestStubRasterBackend();
+  const createImageBitmap = vi.fn((source: ImageBitmapSource): Promise<ImageBitmap> => {
+    void source;
+    return Promise.resolve({ close: vi.fn(), height: 16, width: 32 } as unknown as ImageBitmap);
+  });
+  const backend: RasterBackend = {
+    createImageBitmap,
+    createSurface: stub.createSurface,
+    encodeSurface: stub.encodeSurface,
+  };
+  return { backend, createImageBitmap, createSurface: stub.createSurface };
+};
+
+const makeDeps = (resolver: ImageResolver, backend: RasterBackend): RasterizeDeps => ({
+  backend,
+  bitmapPool: createDecodedBitmapPool(),
+  documentSize: { height: 200, width: 300 },
+  resolver,
+  store: createLayerCacheStore(backend),
+});
+
+describe('rasterizeSource — image', () => {
+  it('gives the shared image resolver a cancellable pool-owned signal', async () => {
+    const { backend } = createSpyBackend();
+    const controller = new AbortController();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = { ...makeDeps(resolver, backend), signal: controller.signal };
+
+    await rasterizeSource({ image: imageRef('signaled'), type: 'image' }, deps);
+
+    const resolverSignal = resolver.mock.calls[0]?.[1];
+    expect(resolverSignal).toBeInstanceOf(AbortSignal);
+    expect(resolverSignal).not.toBe(controller.signal);
+  });
+
+  it('closes a decoded bitmap instead of caching it when cancellation lands during decode', async () => {
+    const { backend } = createSpyBackend();
+    let resolveDecoded!: (bitmap: ImageBitmap) => void;
+    const decoded = new Promise<ImageBitmap>((resolve) => {
+      resolveDecoded = resolve;
+    });
+    const bitmap = { close: vi.fn(), height: 16, width: 32 } as unknown as ImageBitmap;
+    backend.createImageBitmap = vi.fn(() => decoded);
+    const controller = new AbortController();
+    const deps = { ...makeDeps(() => Promise.resolve(new Blob()), backend), signal: controller.signal };
+
+    const rasterized = rasterizeSource({ image: imageRef('cancelled-decode'), type: 'image' }, deps);
+    await Promise.resolve();
+    controller.abort();
+    resolveDecoded(bitmap);
+
+    await expect(rasterized).rejects.toBe(controller.signal.reason);
+    expect(bitmap.close).toHaveBeenCalledTimes(1);
+    expect(deps.bitmapPool?.byteSize()).toBe(0);
+  });
+
+  it('decodes via the resolver + backend and coalesces concurrent callers', async () => {
+    const { backend, createImageBitmap } = createSpyBackend();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = makeDeps(resolver, backend);
+    const source: CanvasLayerSourceContract = { image: imageRef('cat'), type: 'image' };
+
+    const [resultA, resultB] = await Promise.all([rasterizeSource(source, deps), rasterizeSource(source, deps)]);
+
+    // Both active rasterizations share one decode; the final release closes it.
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(createImageBitmap).toHaveBeenCalledTimes(1);
+    expect(deps.bitmapPool?.byteSize()).toBe(0);
+
+    // Surface sized to the image ref; content rect at the origin.
+    expect(resultA.surface.width).toBe(32);
+    expect(resultA.surface.height).toBe(16);
+    expect(resultA.rect).toEqual({ height: 16, width: 32, x: 0, y: 0 });
+    expect(resultB.surface.width).toBe(32);
+  });
+
+  it('keeps a shared decode alive when the first of two consumers aborts', async () => {
+    const { backend, createImageBitmap } = createSpyBackend();
+    let resolveBlob!: (blob: Blob) => void;
+    const resolver = vi.fn<ImageResolver>(
+      (_imageName, signal) =>
+        new Promise<Blob>((resolve, reject) => {
+          resolveBlob = resolve;
+          signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
+        })
+    );
+    const shared = makeDeps(resolver, backend);
+    const firstController = new AbortController();
+    const secondController = new AbortController();
+    const source: CanvasLayerSourceContract = { image: imageRef('shared'), type: 'image' };
+
+    const first = rasterizeSource(source, { ...shared, signal: firstController.signal });
+    const second = rasterizeSource(source, { ...shared, signal: secondController.signal });
+    await Promise.resolve();
+    firstController.abort();
+    resolveBlob(new Blob());
+
+    await expect(first).rejects.toBe(firstController.signal.reason);
+    await expect(second).resolves.toMatchObject({ rect: { height: 16, width: 32, x: 0, y: 0 } });
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(createImageBitmap).toHaveBeenCalledTimes(1);
+    expect(shared.bitmapPool?.byteSize()).toBe(0);
+  });
+
+  it('draws the decoded bitmap onto the surface', async () => {
+    const { backend } = createSpyBackend();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = makeDeps(resolver, backend);
+
+    const { surface } = await rasterizeSource({ image: imageRef('dog'), type: 'image' }, deps);
+    const ops = (surface as ReturnType<ReturnType<typeof createTestStubRasterBackend>['createSurface']>).callLog.map(
+      (e) => e.op
+    );
+    expect(ops).toContain('clearRect');
+    expect(ops).toContain('drawImage');
+  });
+});
+
+describe('rasterizeSource — paint', () => {
+  it('null bitmap produces an EMPTY (zero-rect) surface (no drawImage)', async () => {
+    const { backend, createImageBitmap } = createSpyBackend();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = makeDeps(resolver, backend);
+
+    const { rect, surface } = await rasterizeSource({ bitmap: null, type: 'paint' }, deps);
+
+    // Content-sized: an empty paint layer holds no pixels — a zero rect.
+    expect(rect).toEqual({ height: 0, width: 0, x: 0, y: 0 });
+    expect(surface.width).toBe(0);
+    expect(surface.height).toBe(0);
+    expect(resolver).not.toHaveBeenCalled();
+    expect(createImageBitmap).not.toHaveBeenCalled();
+    const ops = (surface as ReturnType<ReturnType<typeof createTestStubRasterBackend>['createSurface']>).callLog.map(
+      (e) => e.op
+    );
+    expect(ops).not.toContain('drawImage');
+  });
+
+  it('a paint bitmap is decoded and blitted onto a content-sized surface at its offset', async () => {
+    const { backend, createImageBitmap } = createSpyBackend();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = makeDeps(resolver, backend);
+
+    const { rect, surface } = await rasterizeSource(
+      { bitmap: imageRef('brush'), offset: { x: 40, y: 25 }, type: 'paint' },
+      deps
+    );
+
+    // Sized to the bitmap dims, placed at the persisted offset.
+    expect(surface.width).toBe(32);
+    expect(surface.height).toBe(16);
+    expect(rect).toEqual({ height: 16, width: 32, x: 40, y: 25 });
+    expect(createImageBitmap).toHaveBeenCalledTimes(1);
+  });
+
+  it('a paint bitmap without an offset defaults to origin (0,0) — legacy back-compat', async () => {
+    const { backend } = createSpyBackend();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = makeDeps(resolver, backend);
+
+    const { rect } = await rasterizeSource({ bitmap: imageRef('brush'), type: 'paint' }, deps);
+    expect(rect).toEqual({ height: 16, width: 32, x: 0, y: 0 });
+  });
+});
+
+describe('rasterizeSource — unimplemented sources', () => {
+  it('throws for the deferred polygon shape kind', () => {
+    const { backend } = createSpyBackend();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = makeDeps(resolver, backend);
+    const source = {
+      fill: '#000000',
+      height: 10,
+      kind: 'polygon',
+      stroke: null,
+      strokeWidth: 0,
+      type: 'shape',
+      width: 10,
+    } as unknown as CanvasLayerSourceContract;
+    expect(() => rasterizeSource(source, deps)).toThrow(/not implemented/i);
+  });
+
+  it('rasterizes shape, gradient, and text sources (no longer throwing)', async () => {
+    const { backend } = createSpyBackend();
+    const resolver = vi.fn<ImageResolver>(() => Promise.resolve(new Blob()));
+    const deps = makeDeps(resolver, backend);
+    const shape = {
+      fill: '#000000',
+      height: 10,
+      kind: 'rect',
+      stroke: null,
+      strokeWidth: 0,
+      type: 'shape',
+      width: 10,
+    } as CanvasLayerSourceContract;
+    const gradient = {
+      angle: 0,
+      kind: 'linear',
+      stops: [{ color: '#000000', offset: 0 }],
+      type: 'gradient',
+    } as CanvasLayerSourceContract;
+    const text = {
+      align: 'left',
+      color: '#000000',
+      content: 'hi',
+      fontFamily: 'Inter',
+      fontSize: 20,
+      fontWeight: 400,
+      lineHeight: 1.2,
+      type: 'text',
+    } as CanvasLayerSourceContract;
+    await expect(rasterizeSource(shape, deps)).resolves.toBeDefined();
+    await expect(rasterizeSource(gradient, deps)).resolves.toBeDefined();
+    await expect(rasterizeSource(text, deps)).resolves.toBeDefined();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/shapeRasterizer.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/shapeRasterizer.test.ts
new file mode 100644
index 00000000000..479963d8771
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/shapeRasterizer.test.ts
@@ -0,0 +1,111 @@
+import type { StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it } from 'vitest';
+
+import type { RasterizeDeps } from './types';
+
+import { rasterizeShapeSource } from './shapeRasterizer';
+
+type ShapeSource = Extract<CanvasLayerSourceContract, { type: 'shape' }>;
+
+const makeDeps = (): RasterizeDeps => {
+  const backend = createTestStubRasterBackend();
+  return {
+    backend,
+    documentSize: { height: 200, width: 300 },
+    resolver: () => Promise.resolve(new Blob()),
+    store: createLayerCacheStore(backend),
+  };
+};
+
+const ops = (surface: StubRasterSurface): string[] => surface.callLog.map((e) => e.op);
+
+const rect = (over: Partial<ShapeSource> = {}): ShapeSource => ({
+  fill: '#ff0000',
+  height: 40,
+  kind: 'rect',
+  stroke: null,
+  strokeWidth: 0,
+  type: 'shape',
+  width: 60,
+  ...over,
+});
+
+describe('rasterizeShapeSource — extent + sizing', () => {
+  it('sizes the surface to the source width/height (not the document)', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeShapeSource(rect(), deps)).surface as StubRasterSurface;
+    expect(surface.width).toBe(60);
+    expect(surface.height).toBe(40);
+  });
+
+  it('clears before drawing so re-rasterizing into a reused target is clean', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeShapeSource(rect(), deps)).surface as StubRasterSurface;
+    expect(ops(surface)).toContain('clearRect');
+  });
+});
+
+describe('rasterizeShapeSource — rect', () => {
+  it('fills a rect covering the full extent when fill is set and no stroke', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeShapeSource(rect({ fill: '#00ff00', stroke: null }), deps))
+      .surface as StubRasterSurface;
+    const log = surface.callLog;
+    // Fill style applied and a rect path filled.
+    expect(log.some((e) => e.op === 'set' && e.args[0] === 'fillStyle' && e.args[1] === '#00ff00')).toBe(true);
+    expect(ops(surface)).toContain('fill');
+    // No stroke was drawn.
+    expect(ops(surface)).not.toContain('stroke');
+  });
+
+  it('strokes with the stroke color + width, inset so it stays within the extent', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeShapeSource(rect({ fill: null, stroke: '#0000ff', strokeWidth: 8 }), deps))
+      .surface as StubRasterSurface;
+    const log = surface.callLog;
+    expect(log.some((e) => e.op === 'set' && e.args[0] === 'strokeStyle' && e.args[1] === '#0000ff')).toBe(true);
+    expect(log.some((e) => e.op === 'set' && e.args[0] === 'lineWidth' && e.args[1] === 8)).toBe(true);
+    expect(ops(surface)).toContain('stroke');
+    expect(ops(surface)).not.toContain('fill');
+  });
+
+  it('draws both fill and stroke when both are set', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeShapeSource(rect({ fill: '#111111', stroke: '#222222', strokeWidth: 4 }), deps))
+      .surface as StubRasterSurface;
+    expect(ops(surface)).toContain('fill');
+    expect(ops(surface)).toContain('stroke');
+  });
+
+  it('draws nothing when both fill and stroke are null', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeShapeSource(rect({ fill: null, stroke: null }), deps)).surface as StubRasterSurface;
+    expect(ops(surface)).not.toContain('fill');
+    expect(ops(surface)).not.toContain('stroke');
+  });
+});
+
+describe('rasterizeShapeSource — ellipse', () => {
+  it('draws an ellipse path (not a rect) for the ellipse kind', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeShapeSource(rect({ fill: '#abcdef', kind: 'ellipse' }), deps))
+      .surface as StubRasterSurface;
+    expect(ops(surface)).toContain('ellipse');
+    expect(ops(surface)).toContain('fill');
+  });
+});
+
+describe('rasterizeShapeSource — target reuse', () => {
+  it('resizes and reuses a provided target surface', async () => {
+    const deps = makeDeps();
+    const target = deps.backend.createSurface(10, 10);
+    const { surface } = await rasterizeShapeSource(rect({ height: 40, width: 60 }), deps, target);
+    expect(surface).toBe(target);
+    expect(surface.width).toBe(60);
+    expect(surface.height).toBe(40);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/shapeRasterizer.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/shapeRasterizer.ts
new file mode 100644
index 00000000000..c4150d75fc0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/shapeRasterizer.ts
@@ -0,0 +1,79 @@
+/**
+ * Rasterizes a `shape` layer source (rect / ellipse). Shape layers are
+ * PARAMETRIC: their pixels are derived from the source params (`width`,
+ * `height`, `fill`, `stroke`, `strokeWidth`, `kind`) rather than a persisted
+ * bitmap, so they re-render for free whenever a param changes.
+ *
+ * Extent semantics: a shape's surface is sized to the source's own
+ * `width`×`height` (its layer-local extent), NOT the document — the compositor
+ * applies the layer transform (position/scale/rotation) when drawing, exactly
+ * like an `image` layer. The stroke is drawn INSET by `strokeWidth / 2` so a
+ * thick outline stays entirely within the extent rather than clipping at the
+ * surface edge.
+ *
+ * `polygon` is intentionally NOT handled here (deferred until a points-editing
+ * UX exists); the dispatch never routes a polygon source to this rasterizer in
+ * this phase.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import type { RasterizeDeps, RasterizeResult } from './types';
+
+type ShapeSource = Extract<CanvasLayerSourceContract, { type: 'shape' }>;
+type Ctx = RasterSurface['ctx'];
+
+/** Builds the rect/ellipse path for `kind` inset by `inset` on every side into the current path. */
+const buildShapePath = (ctx: Ctx, kind: ShapeSource['kind'], width: number, height: number, inset: number): void => {
+  const w = Math.max(0, width - inset * 2);
+  const h = Math.max(0, height - inset * 2);
+  ctx.beginPath();
+  if (kind === 'ellipse') {
+    ctx.ellipse(width / 2, height / 2, w / 2, h / 2, 0, 0, Math.PI * 2);
+    return;
+  }
+  // `rect` (and, defensively, `polygon` which the dispatch never sends here).
+  ctx.rect(inset, inset, w, h);
+};
+
+/**
+ * Draws a shape source onto a surface sized to the source extent. Reuses
+ * `target` if provided (resizing it to the extent), matching the paint/image
+ * rasterizer contract. Synchronous work wrapped in a resolved promise so it
+ * shares the `rasterizeSource` dispatch signature.
+ */
+export const rasterizeShapeSource = (
+  source: ShapeSource,
+  deps: RasterizeDeps,
+  target?: RasterSurface
+): Promise<RasterizeResult> => {
+  const width = Math.max(1, Math.round(source.width));
+  const height = Math.max(1, Math.round(source.height));
+
+  const surface = target ?? deps.backend.createSurface(width, height);
+  if (surface.width !== width || surface.height !== height) {
+    surface.resize(width, height);
+  }
+  const { ctx } = surface;
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+
+  if (source.fill) {
+    ctx.fillStyle = source.fill;
+    buildShapePath(ctx, source.kind, width, height, 0);
+    ctx.fill();
+  }
+
+  if (source.stroke && source.strokeWidth > 0) {
+    ctx.strokeStyle = source.stroke;
+    ctx.lineWidth = source.strokeWidth;
+    // Inset by half the stroke width so the (centered) stroke stays inside the extent.
+    buildShapePath(ctx, source.kind, width, height, source.strokeWidth / 2);
+    ctx.stroke();
+  }
+
+  return Promise.resolve({ rect: { height, width, x: 0, y: 0 }, surface });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/textRasterizer.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/textRasterizer.test.ts
new file mode 100644
index 00000000000..d0556ace40c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/textRasterizer.test.ts
@@ -0,0 +1,133 @@
+import type { RasterCallLogEntry, StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it } from 'vitest';
+
+import type { TextSource } from './textRasterizer';
+import type { RasterizeDeps } from './types';
+
+import { estimateTextExtent, rasterizeTextSource, TEXT_CHAR_WIDTH_FACTOR, textFontString } from './textRasterizer';
+
+const makeDeps = (): RasterizeDeps => {
+  const backend = createTestStubRasterBackend();
+  return {
+    backend,
+    documentSize: { height: 200, width: 300 },
+    resolver: () => Promise.resolve(new Blob()),
+    store: createLayerCacheStore(backend),
+  };
+};
+
+const ops = (surface: StubRasterSurface): string[] => surface.callLog.map((e) => e.op);
+const entries = (surface: StubRasterSurface, op: string): RasterCallLogEntry[] =>
+  surface.callLog.filter((e) => e.op === op);
+
+const text = (over: Partial<TextSource> = {}): TextSource => ({
+  align: 'left',
+  color: '#112233',
+  content: 'hello',
+  fontFamily: 'Inter',
+  fontSize: 20,
+  fontWeight: 400,
+  lineHeight: 1.5,
+  type: 'text',
+  ...over,
+});
+
+// The stub's deterministic metric: width = chars × fontSizePx × TEXT_CHAR_WIDTH_FACTOR.
+const stubWidth = (chars: number, fontSize: number): number => Math.ceil(chars * fontSize * TEXT_CHAR_WIDTH_FACTOR);
+
+describe('rasterizeTextSource — measurement + extent', () => {
+  it('sizes the surface to the measured block (widest line × fontSize×0.6, lines × fontSize×lineHeight)', async () => {
+    const deps = makeDeps();
+    const source = text({ content: 'hello', fontSize: 20, lineHeight: 1.5 });
+    const surface = (await rasterizeTextSource(source, deps)).surface as StubRasterSurface;
+    expect(surface.width).toBe(stubWidth(5, 20)); // 'hello' = 5 chars → 60
+    expect(surface.height).toBe(Math.ceil(1 * 20 * 1.5)); // one line → 30
+  });
+
+  it('agrees with the pure estimateTextExtent (cache-size stability)', async () => {
+    const deps = makeDeps();
+    const source = text({ content: 'abc\ndefgh', fontSize: 16, lineHeight: 1.2 });
+    const surface = (await rasterizeTextSource(source, deps)).surface as StubRasterSurface;
+    const estimate = estimateTextExtent(source);
+    expect(surface.width).toBe(estimate.width);
+    expect(surface.height).toBe(estimate.height);
+  });
+
+  it('clears before drawing and applies the font + fill color', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeTextSource(text({ color: '#abcdef' }), deps)).surface as StubRasterSurface;
+    expect(ops(surface)).toContain('clearRect');
+    expect(
+      surface.callLog.some((e) => e.op === 'set' && e.args[0] === 'font' && e.args[1] === textFontString(text()))
+    ).toBe(true);
+    expect(surface.callLog.some((e) => e.op === 'set' && e.args[0] === 'fillStyle' && e.args[1] === '#abcdef')).toBe(
+      true
+    );
+  });
+});
+
+describe('rasterizeTextSource — line breaks', () => {
+  it('draws one fillText per manual line, stepped by fontSize×lineHeight', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeTextSource(text({ content: 'a\nbb\nccc', fontSize: 10, lineHeight: 2 }), deps))
+      .surface as StubRasterSurface;
+    const fills = entries(surface, 'fillText');
+    expect(fills).toHaveLength(3);
+    // step = 10 × 2 = 20; y anchors at 0, 20, 40.
+    expect(fills.map((e) => e.args[2])).toEqual([0, 20, 40]);
+    expect(fills.map((e) => e.args[0])).toEqual(['a', 'bb', 'ccc']);
+    // Height covers all three lines.
+    expect(surface.height).toBe(60);
+  });
+});
+
+describe('rasterizeTextSource — alignment', () => {
+  it('left-aligns at x=0', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeTextSource(text({ align: 'left' }), deps)).surface as StubRasterSurface;
+    expect(surface.callLog.some((e) => e.op === 'set' && e.args[0] === 'textAlign' && e.args[1] === 'left')).toBe(true);
+    expect(entries(surface, 'fillText')[0]?.args[1]).toBe(0);
+  });
+
+  it('center-aligns at x=width/2', async () => {
+    const deps = makeDeps();
+    const source = text({ align: 'center', content: 'hello', fontSize: 20 });
+    const surface = (await rasterizeTextSource(source, deps)).surface as StubRasterSurface;
+    expect(surface.callLog.some((e) => e.op === 'set' && e.args[0] === 'textAlign' && e.args[1] === 'center')).toBe(
+      true
+    );
+    expect(entries(surface, 'fillText')[0]?.args[1]).toBe(stubWidth(5, 20) / 2);
+  });
+
+  it('right-aligns at x=width', async () => {
+    const deps = makeDeps();
+    const source = text({ align: 'right', content: 'hello', fontSize: 20 });
+    const surface = (await rasterizeTextSource(source, deps)).surface as StubRasterSurface;
+    expect(surface.callLog.some((e) => e.op === 'set' && e.args[0] === 'textAlign' && e.args[1] === 'right')).toBe(
+      true
+    );
+    expect(entries(surface, 'fillText')[0]?.args[1]).toBe(stubWidth(5, 20));
+  });
+});
+
+describe('rasterizeTextSource — empty + reuse', () => {
+  it('produces a minimal 1×lineHeight surface for empty content', async () => {
+    const deps = makeDeps();
+    const surface = (await rasterizeTextSource(text({ content: '', fontSize: 20, lineHeight: 1.5 }), deps))
+      .surface as StubRasterSurface;
+    expect(surface.width).toBe(1);
+    expect(surface.height).toBe(30);
+  });
+
+  it('resizes and reuses a provided target surface', async () => {
+    const deps = makeDeps();
+    const target = deps.backend.createSurface(5, 5);
+    const source = text({ content: 'hello', fontSize: 20 });
+    const { surface } = await rasterizeTextSource(source, deps, target);
+    expect(surface).toBe(target);
+    expect(surface.width).toBe(stubWidth(5, 20));
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/textRasterizer.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/textRasterizer.ts
new file mode 100644
index 00000000000..63a57d3a335
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/textRasterizer.ts
@@ -0,0 +1,136 @@
+/**
+ * Rasterizes a `text` layer source. Text layers are PARAMETRIC and
+ * EDITABLE-FOREVER: their pixels are derived from the source params (`content`,
+ * `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `align`, `color`) rather
+ * than a persisted bitmap, so a style/content edit re-renders for free — the
+ * headline upgrade over legacy's rasterized (frozen) text.
+ *
+ * Layout is deliberately SIMPLE (Risk 8): manual line breaks on `\n`, a
+ * `lineHeight` multiplier over `fontSize`, and per-line horizontal alignment
+ * within the measured block width. There is NO shaping engine — no BiDi, no
+ * complex-script clustering, no automatic word wrap, no kerning beyond what the
+ * platform `fillText` applies. Metrics come through the {@link RasterSurface}
+ * `ctx` seam (`measureText`), so node tests run on the stub's deterministic
+ * `width = chars × fontSizePx × 0.6` (see `raster.testStub.ts`).
+ *
+ * Extent semantics: like a shape, the surface is sized to the text BLOCK's own
+ * measured `width`×`height` (its layer-local extent, top-left origin); the
+ * compositor applies the layer transform (position/scale) when drawing. A layer
+ * with an empty `content` still produces a minimal 1×lineHeight surface so its
+ * transform/anchor stays meaningful.
+ *
+ * Font loading (late web-font availability) is handled by the ENGINE, not here:
+ * this rasterizer draws with whatever metrics `ctx` currently reports, and the
+ * engine re-rasterizes when a pending font resolves (see `render/fontLoader.ts`).
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import type { RasterizeDeps, RasterizeResult } from './types';
+
+/** A `text` layer source. */
+export type TextSource = Extract<CanvasLayerSourceContract, { type: 'text' }>;
+type Ctx = RasterSurface['ctx'];
+
+/**
+ * Per-character horizontal advance as a fraction of the font's pixel size, used
+ * by the pure {@link estimateTextExtent}. It matches the test stub's
+ * `measureText` factor so a text layer's estimated extent and its
+ * stub-measured surface size agree exactly in node tests. In the browser the
+ * true `measureText` governs the rendered surface; the estimate is only a
+ * pre-measure cache-size / bounds approximation.
+ */
+export const TEXT_CHAR_WIDTH_FACTOR = 0.6;
+
+/** The CSS `font` shorthand for a text source (`"<weight> <size>px <family>"`). */
+export const textFontString = (source: TextSource): string =>
+  `${source.fontWeight} ${source.fontSize}px ${source.fontFamily}`;
+
+/** Splits a text source's content into lines on `\n`; always at least one (possibly empty) line. */
+export const textLines = (content: string): string[] => content.split('\n');
+
+/** The line-box height in document px for a source (`fontSize × lineHeight`). */
+const lineHeightPx = (source: TextSource): number => source.fontSize * source.lineHeight;
+
+/**
+ * A pure, DOM-free estimate of a text block's unscaled pixel extent, matching
+ * the stub's deterministic metrics (`TEXT_CHAR_WIDTH_FACTOR`). Used by the pure
+ * geometry helpers (`sources.ts`) to size caches / bounds before a real
+ * `measureText` runs; the rasterizer resizes the surface to the precise
+ * measured size, so a browser mismatch only affects the initial cache size.
+ */
+export const estimateTextExtent = (source: TextSource): { width: number; height: number } => {
+  const lines = textLines(source.content);
+  const widest = lines.reduce((max, line) => Math.max(max, line.length), 0);
+  return {
+    height: Math.max(1, Math.ceil(lines.length * lineHeightPx(source))),
+    width: Math.max(1, Math.ceil(widest * source.fontSize * TEXT_CHAR_WIDTH_FACTOR)),
+  };
+};
+
+/** Measures the block extent through the seam's `ctx` (font must be set first). */
+const measureBlock = (ctx: Ctx, source: TextSource, lines: string[]): { width: number; height: number } => {
+  let widest = 0;
+  for (const line of lines) {
+    widest = Math.max(widest, ctx.measureText(line).width);
+  }
+  return {
+    height: Math.max(1, Math.ceil(lines.length * lineHeightPx(source))),
+    width: Math.max(1, Math.ceil(widest)),
+  };
+};
+
+/**
+ * Draws a text source into a surface sized to the measured text block, reusing
+ * `target` if provided (resizing it to the measured extent), matching the
+ * paint/image/shape rasterizer contract. Synchronous work wrapped in a resolved
+ * promise so it shares the `rasterizeSource` dispatch signature.
+ */
+export const rasterizeTextSource = (
+  source: TextSource,
+  deps: RasterizeDeps,
+  target?: RasterSurface
+): Promise<RasterizeResult> => {
+  const lines = textLines(source.content);
+  const font = textFontString(source);
+
+  // Measure on the target's own ctx (or a fresh surface) with the font applied.
+  const surface = target ?? deps.backend.createSurface(1, 1);
+  surface.ctx.font = font;
+  const { height, width } = measureBlock(surface.ctx, source, lines);
+
+  if (surface.width !== width || surface.height !== height) {
+    surface.resize(width, height);
+  }
+  const { ctx } = surface;
+  // A resize resets the browser context state, so (re)apply the transform, font,
+  // and paint state AFTER resizing.
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+  ctx.font = font;
+  ctx.textBaseline = 'top';
+  ctx.fillStyle = source.color;
+
+  // Horizontal alignment within the block width, via the canvas text anchor.
+  let anchorX = 0;
+  if (source.align === 'center') {
+    ctx.textAlign = 'center';
+    anchorX = width / 2;
+  } else if (source.align === 'right') {
+    ctx.textAlign = 'right';
+    anchorX = width;
+  } else {
+    ctx.textAlign = 'left';
+    anchorX = 0;
+  }
+
+  const step = lineHeightPx(source);
+  for (let i = 0; i < lines.length; i++) {
+    ctx.fillText(lines[i] ?? '', anchorX, i * step);
+  }
+
+  return Promise.resolve({ rect: { height, width, x: 0, y: 0 }, surface });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/types.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/types.ts
new file mode 100644
index 00000000000..1e71ad666ec
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/rasterizers/types.ts
@@ -0,0 +1,51 @@
+/**
+ * Shared vocabulary for the source rasterizers.
+ *
+ * Type-only module (no runtime), so it can be imported by both the dispatch
+ * (`rasterizeSource`) and the per-source rasterizers without any import
+ * cycle. Zero React, zero side effects.
+ */
+
+import type { DecodedBitmapPool } from '@workbench/canvas-engine/render/decodedBitmapPool';
+import type { LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+
+/**
+ * Resolves a persisted image asset (referenced by name in the document) to a
+ * `Blob` for decoding. The DOM implementation (deriving a URL and fetching)
+ * ships with the React shell task; the engine only depends on this seam so it
+ * stays node-testable.
+ */
+export type ImageResolver = (imageName: string, signal?: AbortSignal) => Promise<Blob>;
+
+/**
+ * The result of rasterizing a source: the surface holding its pixels plus the
+ * content `rect` those pixels occupy in the layer's LOCAL coordinate space. For
+ * origin-anchored sources (image / shape / text / gradient) the rect origin is
+ * `(0, 0)`; a `paint` source places its bitmap at the persisted `offset`.
+ */
+export interface RasterizeResult {
+  surface: RasterSurface;
+  rect: Rect;
+}
+
+/** Dependencies shared by the source rasterizers. */
+export interface RasterizeDeps {
+  /** Surface + bitmap factory seam. */
+  backend: RasterBackend;
+  /** Fetches image blobs by name for decoding. */
+  resolver: ImageResolver;
+  /** Cancels pending image resolution and prevents decode/cache publication. */
+  signal?: AbortSignal;
+  /** Holds the decoded-bitmap cache (keyed by image name). */
+  store: LayerCacheStore;
+  /** Coalesces concurrent decodes and owns decoded pixels only for the duration of a rasterization. */
+  bitmapPool?: DecodedBitmapPool;
+  /**
+   * Document pixel size. Layers are content-sized, so this only backs the
+   * legacy default for gradients that predate the explicit extent field (they
+   * were document-sized by construction and must render identically).
+   */
+  documentSize: { width: number; height: number };
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/scheduler.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/scheduler.test.ts
new file mode 100644
index 00000000000..6de196fb26f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/scheduler.test.ts
@@ -0,0 +1,214 @@
+import type { RenderFlags } from '@workbench/canvas-engine/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createRenderScheduler } from './scheduler';
+
+/** A controllable fake rAF: `flush()` runs the pending callback, if any. */
+const createFakeRaf = () => {
+  let nextHandle = 1;
+  const callbacks = new Map<number, FrameRequestCallback>();
+  return {
+    cancelFrame: (handle: number): void => {
+      callbacks.delete(handle);
+    },
+    /** Runs all currently-queued frame callbacks (like the browser firing a frame). */
+    flush: (): void => {
+      const queued = [...callbacks.entries()];
+      callbacks.clear();
+      for (const [, cb] of queued) {
+        cb(performance.now());
+      }
+    },
+    pendingCount: (): number => callbacks.size,
+    requestFrame: (cb: FrameRequestCallback): number => {
+      const handle = nextHandle++;
+      callbacks.set(handle, cb);
+      return handle;
+    },
+  };
+};
+
+describe('createRenderScheduler', () => {
+  it('coalesces multiple invalidations into a single render with merged flags', () => {
+    const raf = createFakeRaf();
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    const scheduler = createRenderScheduler({ cancelFrame: raf.cancelFrame, render, requestFrame: raf.requestFrame });
+
+    scheduler.invalidate({ view: true });
+    scheduler.invalidate({ layers: ['a'] });
+    scheduler.invalidate({ layers: ['b'] });
+    scheduler.invalidate({ overlay: true });
+
+    // Only one frame is scheduled despite four invalidations.
+    expect(raf.pendingCount()).toBe(1);
+    expect(render).not.toHaveBeenCalled();
+
+    raf.flush();
+
+    expect(render).toHaveBeenCalledTimes(1);
+    const flags = render.mock.calls[0]![0];
+    expect(flags.view).toBe(true);
+    expect(flags.overlay).toBe(true);
+    expect(flags.all).toBe(false);
+    expect([...flags.layers].sort()).toEqual(['a', 'b']);
+  });
+
+  it('resets flags after the render callback runs', () => {
+    const raf = createFakeRaf();
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    const scheduler = createRenderScheduler({ cancelFrame: raf.cancelFrame, render, requestFrame: raf.requestFrame });
+
+    scheduler.invalidate({ layers: ['a'], view: true });
+    raf.flush();
+
+    scheduler.invalidate({ layers: ['b'] });
+    raf.flush();
+
+    expect(render).toHaveBeenCalledTimes(2);
+    const second = render.mock.calls[1]![0];
+    // No leftover 'a' or view flag from the first frame.
+    expect(second.view).toBe(false);
+    expect([...second.layers]).toEqual(['b']);
+  });
+
+  it('does not schedule a new frame when nothing was invalidated', () => {
+    const raf = createFakeRaf();
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    createRenderScheduler({ cancelFrame: raf.cancelFrame, render, requestFrame: raf.requestFrame });
+
+    expect(raf.pendingCount()).toBe(0);
+    raf.flush();
+    expect(render).not.toHaveBeenCalled();
+  });
+
+  it('accumulates invalidations while paused and flushes them on resume', () => {
+    const raf = createFakeRaf();
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    const scheduler = createRenderScheduler({ cancelFrame: raf.cancelFrame, render, requestFrame: raf.requestFrame });
+
+    scheduler.pause();
+    scheduler.invalidate({ layers: ['a'] });
+    scheduler.invalidate({ view: true });
+
+    // Nothing scheduled while paused.
+    expect(raf.pendingCount()).toBe(0);
+
+    scheduler.resume();
+    expect(raf.pendingCount()).toBe(1);
+    raf.flush();
+
+    expect(render).toHaveBeenCalledTimes(1);
+    const flags = render.mock.calls[0]![0];
+    expect(flags.view).toBe(true);
+    expect([...flags.layers]).toEqual(['a']);
+  });
+
+  it('pause cancels an already-scheduled frame; resume reschedules the same pending flags', () => {
+    const raf = createFakeRaf();
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    const scheduler = createRenderScheduler({ cancelFrame: raf.cancelFrame, render, requestFrame: raf.requestFrame });
+
+    scheduler.invalidate({ view: true });
+    expect(raf.pendingCount()).toBe(1);
+
+    scheduler.pause();
+    expect(raf.pendingCount()).toBe(0);
+    raf.flush();
+    expect(render).not.toHaveBeenCalled();
+
+    scheduler.resume();
+    raf.flush();
+    expect(render).toHaveBeenCalledTimes(1);
+    expect(render.mock.calls[0]![0].view).toBe(true);
+  });
+
+  it('resume with no pending work does not schedule a frame', () => {
+    const raf = createFakeRaf();
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    const scheduler = createRenderScheduler({ cancelFrame: raf.cancelFrame, render, requestFrame: raf.requestFrame });
+
+    scheduler.pause();
+    scheduler.resume();
+    expect(raf.pendingCount()).toBe(0);
+  });
+
+  it('dispose cancels a pending frame and ignores further invalidations', () => {
+    const raf = createFakeRaf();
+    const cancelFrame = vi.fn(raf.cancelFrame);
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    const scheduler = createRenderScheduler({ cancelFrame, render, requestFrame: raf.requestFrame });
+
+    scheduler.invalidate({ view: true });
+    expect(raf.pendingCount()).toBe(1);
+
+    scheduler.dispose();
+    expect(cancelFrame).toHaveBeenCalledTimes(1);
+    expect(raf.pendingCount()).toBe(0);
+
+    scheduler.invalidate({ all: true });
+    raf.flush();
+    expect(render).not.toHaveBeenCalled();
+    expect(raf.pendingCount()).toBe(0);
+  });
+
+  it('invalidations from within the render callback schedule a fresh frame', () => {
+    const raf = createFakeRaf();
+    let reentered = false;
+    const scheduler = createRenderScheduler({
+      cancelFrame: raf.cancelFrame,
+      render: () => {
+        if (!reentered) {
+          reentered = true;
+          scheduler.invalidate({ overlay: true });
+        }
+      },
+      requestFrame: raf.requestFrame,
+    });
+
+    scheduler.invalidate({ view: true });
+    raf.flush();
+    // The re-entrant invalidate scheduled another frame rather than being lost.
+    expect(raf.pendingCount()).toBe(1);
+  });
+
+  it('retains pending invalidations and retries when the host frame scheduler throws', () => {
+    const raf = createFakeRaf();
+    const render = vi.fn<(flags: RenderFlags) => void>();
+    let shouldThrow = true;
+    const scheduler = createRenderScheduler({
+      cancelFrame: raf.cancelFrame,
+      render,
+      requestFrame: (callback) => {
+        if (shouldThrow) {
+          throw new Error('host scheduler unavailable');
+        }
+        return raf.requestFrame(callback);
+      },
+    });
+
+    expect(() => scheduler.invalidate({ view: true })).not.toThrow();
+    expect(raf.pendingCount()).toBe(0);
+
+    shouldThrow = false;
+    scheduler.invalidate({ overlay: true });
+    raf.flush();
+
+    expect(render).toHaveBeenCalledOnce();
+    expect(render.mock.calls[0]![0]).toMatchObject({ overlay: true, view: true });
+  });
+
+  it('reflects paused state via isPaused', () => {
+    const raf = createFakeRaf();
+    const scheduler = createRenderScheduler({
+      cancelFrame: raf.cancelFrame,
+      render: () => {},
+      requestFrame: raf.requestFrame,
+    });
+    expect(scheduler.isPaused).toBe(false);
+    scheduler.pause();
+    expect(scheduler.isPaused).toBe(true);
+    scheduler.resume();
+    expect(scheduler.isPaused).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/scheduler.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/scheduler.ts
new file mode 100644
index 00000000000..1e8ba1e1a48
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/scheduler.ts
@@ -0,0 +1,170 @@
+/**
+ * A single-rAF render scheduler.
+ *
+ * Consumers call `invalidate(...)` many times per frame; the scheduler
+ * coalesces those into one pending `RenderFlags` set and runs the injected
+ * `render` callback at most once per animation frame. The rAF driver is
+ * injectable so the scheduler can be driven deterministically in node tests.
+ *
+ * Zero React, zero import-time side effects; the only DOM touch point is the
+ * default `requestFrame`/`cancelFrame`, which are resolved lazily at call
+ * time (never at import) and are always overridden in tests.
+ */
+
+import type { RenderFlags } from '@workbench/canvas-engine/types';
+
+/** The partial invalidation payload accepted by {@link RenderScheduler.invalidate}. */
+export interface InvalidatePayload {
+  /** The viewport transform (pan/zoom) changed. */
+  view?: true;
+  /** Ids of layers whose pixel content or transform changed. */
+  layers?: string[];
+  /** Interaction overlays (selection, cursors, guides) changed. */
+  overlay?: true;
+  /** Force a full repaint next frame. */
+  all?: true;
+}
+
+/** Dependencies for {@link createRenderScheduler}; the rAF pair is injectable for tests. */
+export interface RenderSchedulerDeps {
+  /** Invoked once per scheduled frame with the coalesced flags. */
+  render: (flags: RenderFlags) => void;
+  /** Defaults to `globalThis.requestAnimationFrame`. */
+  requestFrame?: (callback: FrameRequestCallback) => number;
+  /** Defaults to `globalThis.cancelAnimationFrame`. */
+  cancelFrame?: (handle: number) => void;
+}
+
+/** The imperative scheduler handle returned by {@link createRenderScheduler}. */
+export interface RenderScheduler {
+  /** Merge a partial invalidation into the pending flags and schedule a frame. */
+  invalidate(payload: InvalidatePayload): void;
+  /** Suspend frame scheduling (e.g. widget detach); invalidations still accumulate. */
+  pause(): void;
+  /** Resume scheduling; flushes any invalidations accumulated while paused. */
+  resume(): void;
+  /** True while paused. */
+  readonly isPaused: boolean;
+  /** Cancel any pending frame and stop accepting further work. */
+  dispose(): void;
+}
+
+const createEmptyFlags = (): RenderFlags => ({
+  all: false,
+  layers: new Set<string>(),
+  overlay: false,
+  view: false,
+});
+
+const hasPending = (flags: RenderFlags): boolean => flags.all || flags.view || flags.overlay || flags.layers.size > 0;
+
+const defaultRequestFrame = (callback: FrameRequestCallback): number => globalThis.requestAnimationFrame(callback);
+
+const defaultCancelFrame = (handle: number): void => {
+  globalThis.cancelAnimationFrame(handle);
+};
+
+/**
+ * Creates a coalescing, single-frame render scheduler. See module docs for
+ * the coalescing and pause/resume semantics.
+ */
+export const createRenderScheduler = (deps: RenderSchedulerDeps): RenderScheduler => {
+  const requestFrame = deps.requestFrame ?? defaultRequestFrame;
+  const cancelFrame = deps.cancelFrame ?? defaultCancelFrame;
+
+  let pending = createEmptyFlags();
+  let frameHandle: number | null = null;
+  let paused = false;
+  let disposed = false;
+
+  const runFrame = (): void => {
+    frameHandle = null;
+    if (disposed) {
+      return;
+    }
+    // Snapshot then reset before invoking render, so invalidations made from
+    // within the render callback accumulate into a fresh frame rather than
+    // being wiped by the post-render reset.
+    const flags = pending;
+    pending = createEmptyFlags();
+    deps.render(flags);
+  };
+
+  const schedule = (): void => {
+    if (disposed || paused || frameHandle !== null) {
+      return;
+    }
+    if (!hasPending(pending)) {
+      return;
+    }
+    try {
+      frameHandle = requestFrame(runFrame);
+    } catch {
+      // Rendering is ancillary to the document mutation that requested it. A
+      // faulty host scheduler must not make that already-applied mutation look
+      // failed; retain the pending flags so a later invalidation can retry.
+      frameHandle = null;
+    }
+  };
+
+  const invalidate = (payload: InvalidatePayload): void => {
+    if (disposed) {
+      return;
+    }
+    if (payload.all) {
+      pending.all = true;
+    }
+    if (payload.view) {
+      pending.view = true;
+    }
+    if (payload.overlay) {
+      pending.overlay = true;
+    }
+    if (payload.layers) {
+      for (const id of payload.layers) {
+        pending.layers.add(id);
+      }
+    }
+    schedule();
+  };
+
+  const pause = (): void => {
+    if (disposed || paused) {
+      return;
+    }
+    paused = true;
+    if (frameHandle !== null) {
+      cancelFrame(frameHandle);
+      frameHandle = null;
+    }
+  };
+
+  const resume = (): void => {
+    if (disposed || !paused) {
+      return;
+    }
+    paused = false;
+    schedule();
+  };
+
+  const dispose = (): void => {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    if (frameHandle !== null) {
+      cancelFrame(frameHandle);
+      frameHandle = null;
+    }
+  };
+
+  return {
+    dispose,
+    invalidate,
+    get isPaused() {
+      return paused;
+    },
+    pause,
+    resume,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/surfaceBudget.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/surfaceBudget.test.ts
new file mode 100644
index 00000000000..29f04bc8065
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/surfaceBudget.test.ts
@@ -0,0 +1,46 @@
+import { createCanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+import { describe, expect, it } from 'vitest';
+
+import { createDerivedSurfaceCache } from './derivedSurfaceCache';
+import { createLayerCacheStore } from './layerCache';
+import { createTestStubRasterBackend } from './raster.testStub';
+import { enforceSurfaceBudget } from './surfaceBudget';
+
+describe('enforceSurfaceBudget', () => {
+  it('evicts derived surfaces before hidden base surfaces', () => {
+    const backend = createTestStubRasterBackend();
+    const layers = createLayerCacheStore(backend);
+    const derived = createDerivedSurfaceCache();
+    layers.getOrCreate('visible', 10, 10);
+    layers.getOrCreate('hidden', 10, 10);
+    const source = backend.createSurface(10, 10);
+    derived.get({
+      create: () => backend.createSurface(10, 10),
+      kind: 'mask-fill',
+      layerId: 'visible',
+      paramsKey: 'red',
+      source,
+      sourceVersion: 0,
+    });
+
+    const result = enforceSurfaceBudget(layers, derived, ['visible'], 800);
+
+    expect(result.evictedDerivedLayerIds).toEqual(['visible']);
+    expect(result.evictedBaseLayerIds).toEqual([]);
+    expect(layers.get('hidden')).toBeDefined();
+  });
+
+  it('protects visible base pixels and reports their overage', () => {
+    const backend = createTestStubRasterBackend();
+    const layers = createLayerCacheStore(backend);
+    const derived = createDerivedSurfaceCache();
+    const diagnostics = createCanvasDiagnostics(true);
+    layers.getOrCreate('visible', 20, 20);
+
+    const result = enforceSurfaceBudget(layers, derived, ['visible'], 400, diagnostics);
+
+    expect(result.overBudgetVisibleBaseBytes).toBe(1_200);
+    expect(layers.get('visible')).toBeDefined();
+    expect(diagnostics.snapshot().overBudgetVisibleBaseBytes).toBe(1_200);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/surfaceBudget.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/surfaceBudget.ts
new file mode 100644
index 00000000000..1bb7da1d41c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/surfaceBudget.ts
@@ -0,0 +1,32 @@
+import type { CanvasDiagnostics } from '@workbench/canvas-engine/diagnostics';
+
+import type { DerivedSurfaceCache } from './derivedSurfaceCache';
+import type { LayerCacheStore } from './layerCache';
+
+export interface SurfaceBudgetResult {
+  readonly evictedDerivedLayerIds: string[];
+  readonly evictedBaseLayerIds: string[];
+  readonly overBudgetVisibleBaseBytes: number;
+}
+
+export const enforceSurfaceBudget = (
+  base: LayerCacheStore,
+  derived: DerivedSurfaceCache,
+  visibleLayerIds: Iterable<string>,
+  budgetBytes: number,
+  diagnostics?: CanvasDiagnostics
+): SurfaceBudgetResult => {
+  const budget = Math.max(0, budgetBytes);
+  const baseBytesBefore = base.byteSize();
+  const derivedBudget = Math.max(0, budget - baseBytesBefore);
+  const evictedDerivedLayerIds = derived.evictToBudget(derivedBudget);
+
+  const baseBudget = Math.max(0, budget - derived.byteSize());
+  const evictedBaseLayerIds = base.evictHidden(visibleLayerIds, baseBudget);
+  const overBudgetVisibleBaseBytes = Math.max(0, base.byteSize() + derived.byteSize() - budget);
+  if (overBudgetVisibleBaseBytes > 0) {
+    diagnostics?.add('overBudgetVisibleBaseBytes', overBudgetVisibleBaseBytes);
+  }
+
+  return { evictedBaseLayerIds, evictedDerivedLayerIds, overBudgetVisibleBaseBytes };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/thumbnail.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/thumbnail.test.ts
new file mode 100644
index 00000000000..1bdd7ba10b5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/thumbnail.test.ts
@@ -0,0 +1,202 @@
+import type { CanvasLayerContract, CanvasLayerSourceContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  fitThumbnailSize,
+  getLayerThumbnailFallbackRenderState,
+  getLayerThumbnailDisplayKey,
+  nextLayerThumbnailFallbackStage,
+  resolveLayerThumbnailImageRef,
+} from './thumbnail';
+
+const rasterLayer = (source: CanvasLayerSourceContract): CanvasLayerContract =>
+  ({
+    adjustments: { brightness: 0, contrast: 0, saturation: 0 },
+    blendMode: 'normal',
+    id: 'raster',
+    isEnabled: true,
+    isLocked: false,
+    name: 'Raster',
+    opacity: 1,
+    source,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'raster',
+  }) as CanvasLayerContract;
+
+const controlLayer = (source: CanvasLayerSourceContract): CanvasLayerContract =>
+  ({
+    adapter: {
+      beginEndStepPct: [0, 1],
+      controlMode: null,
+      kind: 'controlnet',
+      model: null,
+      weight: 1,
+    },
+    blendMode: 'normal',
+    id: 'control',
+    isEnabled: true,
+    isLocked: false,
+    name: 'Control',
+    opacity: 1,
+    source,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'control',
+    withTransparencyEffect: true,
+  }) as CanvasLayerContract;
+
+const maskLayer = (type: 'inpaint_mask' | 'regional_guidance', imageName: string | null): CanvasLayerContract =>
+  ({
+    autoNegative: true,
+    blendMode: 'normal',
+    id: type,
+    isEnabled: true,
+    isLocked: false,
+    mask: {
+      bitmap: imageName ? { height: 20, imageName, width: 30 } : null,
+      fill: { color: '#e07575', style: 'diagonal' },
+    },
+    name: type,
+    negativePrompt: null,
+    opacity: 1,
+    positivePrompt: null,
+    referenceImages: [],
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type,
+  }) as CanvasLayerContract;
+
+describe('fitThumbnailSize', () => {
+  it('scales a large landscape surface to fit the box width', () => {
+    expect(fitThumbnailSize(200, 100, 96)).toEqual({ height: 48, width: 96 });
+  });
+
+  it('scales a large portrait surface to fit the box height', () => {
+    expect(fitThumbnailSize(100, 200, 96)).toEqual({ height: 96, width: 48 });
+  });
+
+  it('keeps a square surface square', () => {
+    expect(fitThumbnailSize(300, 300, 96)).toEqual({ height: 96, width: 96 });
+  });
+
+  it('never upscales a surface smaller than the box', () => {
+    expect(fitThumbnailSize(40, 20, 96)).toEqual({ height: 20, width: 40 });
+  });
+
+  it('clamps a fitted dimension to at least 1px', () => {
+    expect(fitThumbnailSize(1000, 1, 96)).toEqual({ height: 1, width: 96 });
+  });
+
+  it('returns a zero size for a degenerate source or box', () => {
+    expect(fitThumbnailSize(0, 100, 96)).toEqual({ height: 0, width: 0 });
+    expect(fitThumbnailSize(100, 100, 0)).toEqual({ height: 0, width: 0 });
+  });
+});
+
+describe('resolveLayerThumbnailImageRef', () => {
+  const image = { height: 20, imageName: 'image', width: 30 };
+  const bitmap = { height: 20, imageName: 'bitmap', width: 30 };
+
+  it.each([
+    ['raster image', rasterLayer({ image, type: 'image' }), image],
+    ['control image', controlLayer({ image, type: 'image' }), image],
+    ['raster paint', rasterLayer({ bitmap, type: 'paint' }), bitmap],
+    ['control paint', controlLayer({ bitmap, type: 'paint' }), bitmap],
+    ['inpaint mask', maskLayer('inpaint_mask', 'inpaint'), expect.objectContaining({ imageName: 'inpaint' })],
+    [
+      'regional guidance mask',
+      maskLayer('regional_guidance', 'regional'),
+      expect.objectContaining({ imageName: 'regional' }),
+    ],
+  ])('resolves the %s image reference', (_name, layer, expected) => {
+    expect(resolveLayerThumbnailImageRef(layer as CanvasLayerContract)).toEqual(expected);
+  });
+
+  it.each([
+    ['empty raster paint', rasterLayer({ bitmap: null, type: 'paint' })],
+    ['empty control paint', controlLayer({ bitmap: null, type: 'paint' })],
+    ['empty inpaint mask', maskLayer('inpaint_mask', null)],
+    ['empty regional guidance mask', maskLayer('regional_guidance', null)],
+    [
+      'text source',
+      rasterLayer({
+        align: 'left',
+        color: '#fff',
+        content: 'text',
+        fontFamily: 'Inter',
+        fontSize: 16,
+        fontWeight: 400,
+        lineHeight: 1.2,
+        type: 'text',
+      }),
+    ],
+    [
+      'shape source',
+      rasterLayer({ fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 }),
+    ],
+    ['gradient source', rasterLayer({ angle: 0, kind: 'linear', stops: [], type: 'gradient' })],
+  ])('returns null for an %s', (_name, layer) => {
+    expect(resolveLayerThumbnailImageRef(layer as CanvasLayerContract)).toBeNull();
+  });
+
+  it('returns null instead of throwing for a malformed source', () => {
+    const malformed = rasterLayer({ image, type: 'image' });
+    Object.defineProperty(malformed, 'source', {
+      get: () => {
+        throw new Error('invalid source');
+      },
+    });
+    expect(resolveLayerThumbnailImageRef(malformed)).toBeNull();
+  });
+});
+
+describe('getLayerThumbnailDisplayKey', () => {
+  it('changes only for raster adjustments, mask fill, and control transparency', () => {
+    const raster = rasterLayer({ image: { height: 10, imageName: 'r', width: 10 }, type: 'image' });
+    const control = controlLayer({ image: { height: 10, imageName: 'c', width: 10 }, type: 'image' });
+    const mask = maskLayer('inpaint_mask', 'm');
+
+    expect(getLayerThumbnailDisplayKey({ ...raster, name: 'renamed' })).toBe(getLayerThumbnailDisplayKey(raster));
+    expect(getLayerThumbnailDisplayKey({ ...raster, opacity: 0.5 })).not.toBe(getLayerThumbnailDisplayKey(raster));
+    expect(getLayerThumbnailDisplayKey({ ...control, opacity: 0.5 })).not.toBe(getLayerThumbnailDisplayKey(control));
+    expect(getLayerThumbnailDisplayKey({ ...mask, opacity: 0.5 })).not.toBe(getLayerThumbnailDisplayKey(mask));
+    expect(
+      getLayerThumbnailDisplayKey({
+        ...raster,
+        adjustments: { brightness: 0.2, contrast: 0, saturation: 0 },
+      } as CanvasLayerContract)
+    ).not.toBe(getLayerThumbnailDisplayKey(raster));
+    expect(getLayerThumbnailDisplayKey({ ...control, withTransparencyEffect: false } as CanvasLayerContract)).not.toBe(
+      getLayerThumbnailDisplayKey(control)
+    );
+    expect(
+      getLayerThumbnailDisplayKey({
+        ...mask,
+        mask: { ...('mask' in mask ? mask.mask : {}), fill: { color: '#00ff00', style: 'solid' } },
+      } as CanvasLayerContract)
+    ).not.toBe(getLayerThumbnailDisplayKey(mask));
+  });
+});
+
+describe('nextLayerThumbnailFallbackStage', () => {
+  it('falls back from backend thumbnail to full image, then to the retry placeholder', () => {
+    expect(nextLayerThumbnailFallbackStage('thumbnail')).toBe('full');
+    expect(nextLayerThumbnailFallbackStage('full')).toBe('failed');
+    expect(nextLayerThumbnailFallbackStage('failed')).toBe('failed');
+  });
+
+  it('hides a failed URL fallback and its retry overlay after the engine draws successfully', () => {
+    const failed = nextLayerThumbnailFallbackStage(nextLayerThumbnailFallbackStage('thumbnail'));
+    expect(getLayerThumbnailFallbackRenderState(false, failed, false)).toEqual({
+      showFallback: true,
+      showRetry: true,
+    });
+    expect(getLayerThumbnailFallbackRenderState(true, failed, false)).toEqual({
+      showFallback: false,
+      showRetry: false,
+    });
+    expect(getLayerThumbnailFallbackRenderState(true, 'thumbnail', true)).toEqual({
+      showFallback: false,
+      showRetry: false,
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/render/thumbnail.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/thumbnail.ts
new file mode 100644
index 00000000000..2b3d0f24744
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/render/thumbnail.ts
@@ -0,0 +1,88 @@
+/**
+ * Pure helpers for layer thumbnails.
+ *
+ * A layer's cache surface can be any size (up to the document dimensions); a
+ * thumbnail must fit within a small square box while preserving aspect ratio
+ * and never upscaling past the source. Extracted from the engine's
+ * `drawLayerThumbnail` so the arithmetic is unit-testable without a canvas.
+ *
+ * Zero React, zero DOM, zero import-time side effects.
+ */
+
+import type { CanvasImageRef, CanvasLayerContract } from '@workbench/types';
+
+import { renderableSourceOf } from '@workbench/canvas-engine/document/sources';
+
+import { adjustmentsKey } from './adjustments';
+
+/** A thumbnail's integer pixel dimensions after fitting into a `maxSize` box. */
+export interface ThumbnailSize {
+  width: number;
+  height: number;
+}
+
+export type LayerThumbnailFallbackStage = 'thumbnail' | 'full' | 'failed';
+
+/**
+ * Scales a `srcW`x`srcH` surface to fit inside a `maxSize`x`maxSize` box,
+ * preserving aspect ratio and never upscaling (scale is clamped to ≤ 1). Both
+ * returned dimensions are at least 1px. Returns a zero size for a degenerate
+ * (non-positive) source.
+ */
+export const fitThumbnailSize = (srcW: number, srcH: number, maxSize: number): ThumbnailSize => {
+  if (srcW <= 0 || srcH <= 0 || maxSize <= 0) {
+    return { height: 0, width: 0 };
+  }
+  const scale = Math.min(1, maxSize / srcW, maxSize / srcH);
+  return {
+    height: Math.max(1, Math.round(srcH * scale)),
+    width: Math.max(1, Math.round(srcW * scale)),
+  };
+};
+
+/**
+ * Resolves the persisted image that can stand in for a layer while its engine
+ * cache is unavailable. Image and paint sources are handled uniformly through
+ * `renderableSourceOf`, including the synthetic paint source exposed by masks.
+ * Empty paint/mask and parametric sources have no persisted image fallback.
+ */
+export const resolveLayerThumbnailImageRef = (layer: CanvasLayerContract): CanvasImageRef | null => {
+  try {
+    const source = renderableSourceOf(layer);
+    if (source?.type === 'image') {
+      return source.image;
+    }
+    if (source?.type === 'paint') {
+      return source.bitmap;
+    }
+    return null;
+  } catch {
+    // Invalid persisted contracts should degrade to the explicit placeholder.
+    return null;
+  }
+};
+
+/** Display-only properties that alter a layer thumbnail without changing its raster cache. */
+export const getLayerThumbnailDisplayKey = (layer: CanvasLayerContract): string => {
+  if (layer.type === 'raster') {
+    return `raster:${layer.opacity}:${adjustmentsKey(layer.adjustments)}`;
+  }
+  if (layer.type === 'control') {
+    return `control:${layer.opacity}:${layer.withTransparencyEffect ? 'transparent' : 'opaque'}`;
+  }
+  return `mask:${layer.opacity}:${layer.mask.fill.style}:${layer.mask.fill.color}`;
+};
+
+/** Advances the persisted-image fallback after an image element load failure. */
+export const nextLayerThumbnailFallbackStage = (current: LayerThumbnailFallbackStage): LayerThumbnailFallbackStage =>
+  current === 'thumbnail' ? 'full' : 'failed';
+
+/** Pure render policy shared by the thumbnail fallback content and retry overlay. */
+export const getLayerThumbnailFallbackRenderState = (
+  drawn: boolean,
+  fallbackStage: LayerThumbnailFallbackStage,
+  hasRequestError: boolean
+): { showFallback: boolean; showRetry: boolean } => ({
+  showFallback: !drawn,
+  showRetry: !drawn && (hasRequestError || fallbackStage === 'failed'),
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/samCoordinates.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/samCoordinates.ts
new file mode 100644
index 00000000000..92929137996
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/samCoordinates.ts
@@ -0,0 +1,37 @@
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+const clamp = (value: number, min: number, max: number): number => Math.min(max, Math.max(min, value));
+
+const isPixelRect = (rect: Rect): boolean =>
+  Number.isFinite(rect.x) &&
+  Number.isFinite(rect.y) &&
+  Number.isInteger(rect.width) &&
+  Number.isInteger(rect.height) &&
+  rect.width > 0 &&
+  rect.height > 0;
+
+/** Converts a document point to the export's canonical half-open integer pixel domain. */
+export const documentToExportLocalSamPoint = (point: Vec2, exportRect: Rect, clampOutside = false): Vec2 | null => {
+  if (!isPixelRect(exportRect) || !Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+    return null;
+  }
+  if (
+    !clampOutside &&
+    (point.x < exportRect.x ||
+      point.x >= exportRect.x + exportRect.width ||
+      point.y < exportRect.y ||
+      point.y >= exportRect.y + exportRect.height)
+  ) {
+    return null;
+  }
+  return {
+    x: clamp(Math.round(point.x - exportRect.x), 0, exportRect.width - 1),
+    y: clamp(Math.round(point.y - exportRect.y), 0, exportRect.height - 1),
+  };
+};
+
+/** Canonicalizes a document point while retaining document-space coordinates. */
+export const canonicalizeDocumentSamPoint = (point: Vec2, exportRect: Rect, clampOutside = false): Vec2 | null => {
+  const local = documentToExportLocalSamPoint(point, exportRect, clampOutside);
+  return local ? { x: exportRect.x + local.x, y: exportRect.y + local.y } : null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/samInteraction.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/samInteraction.ts
new file mode 100644
index 00000000000..be75d4616ed
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/samInteraction.ts
@@ -0,0 +1,15 @@
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+/** Core interaction-only state for point and bounding-box manipulation. */
+export interface SamVisualInput {
+  type: 'visual';
+  includePoints: Vec2[];
+  excludePoints: Vec2[];
+  bbox: Rect | null;
+}
+
+export interface SamInteractionState {
+  input: SamVisualInput;
+  pointLabel: 'include' | 'exclude';
+  sourceRect: Rect;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/marchingAnts.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/marchingAnts.test.ts
new file mode 100644
index 00000000000..7f318967858
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/marchingAnts.test.ts
@@ -0,0 +1,136 @@
+import type { StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type { Mat2d } from '@workbench/canvas-engine/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { createAntsAnimator, drawMarchingAnts } from '@workbench/canvas-engine/selection/marchingAnts';
+import { describe, expect, it, vi } from 'vitest';
+
+const IDENTITY: Mat2d = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+const fakePath = (id: string): Path2D => ({ id }) as unknown as Path2D;
+
+describe('drawMarchingAnts', () => {
+  it('strokes each path twice (two-tone), applies a dash and the animated offset', () => {
+    const surface = createTestStubRasterBackend().createSurface(50, 50) as StubRasterSurface;
+    drawMarchingAnts(surface.ctx, IDENTITY, { paths: [fakePath('p')], phase: 3 });
+
+    const log = surface.callLog;
+    const ops = log.map((e) => e.op);
+    expect(ops.filter((op) => op === 'stroke')).toHaveLength(2);
+    expect(ops).toContain('setLineDash');
+    expect(ops).toContain('setTransform');
+
+    const strokeStyles = log.filter((e) => e.op === 'set' && e.args[0] === 'strokeStyle').map((e) => e.args[1]);
+    expect(strokeStyles).toContain('#000000');
+    expect(strokeStyles).toContain('#ffffff');
+    // The light run is offset from the dark run so the ants appear to crawl.
+    const offsets = log.filter((e) => e.op === 'set' && e.args[0] === 'lineDashOffset').map((e) => e.args[1]);
+    expect(new Set(offsets).size).toBeGreaterThan(1);
+  });
+
+  it('is a no-op with no paths', () => {
+    const surface = createTestStubRasterBackend().createSurface(10, 10) as StubRasterSurface;
+    drawMarchingAnts(surface.ctx, IDENTITY, { paths: [], phase: 0 });
+    expect(surface.callLog).toHaveLength(0);
+  });
+});
+
+/** A controllable rAF pair + clock for driving the animator deterministically. */
+const createDriver = () => {
+  let nextHandle = 1;
+  const callbacks = new Map<number, () => void>();
+  let clock = 0;
+  return {
+    advance: (ms: number): void => {
+      clock += ms;
+    },
+    cancelFrame: (handle: number): void => {
+      callbacks.delete(handle);
+    },
+    /** Runs every queued frame callback once (like the browser firing a frame). */
+    flush: (): void => {
+      const queued = [...callbacks.entries()];
+      callbacks.clear();
+      for (const [, cb] of queued) {
+        cb();
+      }
+    },
+    now: (): number => clock,
+    pending: (): number => callbacks.size,
+    requestFrame: (cb: () => void): number => {
+      const handle = nextHandle++;
+      callbacks.set(handle, cb);
+      return handle;
+    },
+  };
+};
+
+describe('createAntsAnimator', () => {
+  it('steps on the throttle boundary and reschedules each frame while running', () => {
+    const driver = createDriver();
+    const onStep = vi.fn();
+    const animator = createAntsAnimator({
+      cancelFrame: driver.cancelFrame,
+      intervalMs: 100,
+      now: driver.now,
+      onStep,
+      requestFrame: driver.requestFrame,
+    });
+
+    animator.start();
+    expect(animator.isRunning).toBe(true);
+    expect(driver.pending()).toBe(1);
+
+    // First frame steps immediately (start primes lastStep one interval back).
+    driver.flush();
+    expect(onStep).toHaveBeenCalledTimes(1);
+    // It rescheduled itself.
+    expect(driver.pending()).toBe(1);
+
+    // A frame before the interval elapses does not step, but keeps polling.
+    driver.advance(40);
+    driver.flush();
+    expect(onStep).toHaveBeenCalledTimes(1);
+    expect(driver.pending()).toBe(1);
+
+    // Crossing the interval steps again.
+    driver.advance(70);
+    driver.flush();
+    expect(onStep).toHaveBeenCalledTimes(2);
+  });
+
+  it('stop cancels the pending frame and halts rescheduling (no timer leak)', () => {
+    const driver = createDriver();
+    const onStep = vi.fn();
+    const animator = createAntsAnimator({
+      cancelFrame: driver.cancelFrame,
+      intervalMs: 100,
+      now: driver.now,
+      onStep,
+      requestFrame: driver.requestFrame,
+    });
+
+    animator.start();
+    animator.stop();
+    expect(animator.isRunning).toBe(false);
+    expect(driver.pending()).toBe(0);
+
+    // Any straggler frame that still fires must not step or reschedule.
+    driver.advance(1000);
+    driver.flush();
+    expect(onStep).not.toHaveBeenCalled();
+    expect(driver.pending()).toBe(0);
+  });
+
+  it('start is idempotent (no double scheduling)', () => {
+    const driver = createDriver();
+    const animator = createAntsAnimator({
+      cancelFrame: driver.cancelFrame,
+      now: driver.now,
+      onStep: vi.fn(),
+      requestFrame: driver.requestFrame,
+    });
+    animator.start();
+    animator.start();
+    expect(driver.pending()).toBe(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/marchingAnts.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/marchingAnts.ts
new file mode 100644
index 00000000000..7870d286f40
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/marchingAnts.ts
@@ -0,0 +1,155 @@
+/**
+ * Marching ants: the animated dashed outline of a pixel selection.
+ *
+ * Two concerns live here:
+ *
+ * 1. {@link drawMarchingAnts} strokes the selection's committed path list onto
+ *    the overlay surface as a two-tone (black/white) dashed outline. It draws in
+ *    document space (paths are document-space `Path2D`s) via the shared `view`
+ *    transform, scaling line width and dash by `1/scale` so the ants stay a
+ *    constant pixel size at any zoom — the same screen-constant convention the
+ *    rest of the overlay uses. The animated `lineDashOffset` (`phase`) makes the
+ *    white dashes crawl.
+ *
+ * 2. {@link createAntsAnimator} drives the `phase` advance. It self-reschedules
+ *    through an injected `requestFrame`/`cancelFrame` pair (the engine passes the
+ *    global rAF, so it rides the same frame clock as the scheduler) and, throttled
+ *    by an injected `now()` to ~a few fps (the legacy look, not 60fps), calls
+ *    `onStep` — the engine advances the phase and requests an OVERLAY-ONLY
+ *    invalidation there, so an ants tick never recomposites layers (Task-22 gate).
+ *    It runs only while started (a selection exists AND the engine is attached)
+ *    and cancels its pending frame on `stop`, so there are no timer leaks on
+ *    detach/deselect/dispose.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Mat2d } from '@workbench/canvas-engine/types';
+
+import { getScale } from '@workbench/canvas-engine/math/mat2d';
+
+/** Dash length in screen pixels; the offset advances by {@link ANTS_STEP_PX} per tick. */
+export const ANTS_DASH_PX = 4;
+/** Screen-pixel advance of the dash offset per animation step. */
+export const ANTS_STEP_PX = 1;
+/** Default step interval (ms) — ~5 fps, the legacy marching-ants cadence. */
+export const ANTS_INTERVAL_MS = 200;
+
+const ANTS_LINE_WIDTH_PX = 1;
+const ANTS_DARK = '#000000';
+const ANTS_LIGHT = '#ffffff';
+
+/** What {@link drawMarchingAnts} needs: the committed outlines and the animation phase. */
+export interface MarchingAntsRender {
+  paths: readonly Path2D[];
+  /** Animated dash offset in screen pixels. */
+  phase: number;
+}
+
+/**
+ * Strokes the selection outline(s) as animated two-tone marching ants, in
+ * document space projected through `view`. A no-op with no paths.
+ */
+export const drawMarchingAnts = (ctx: RasterSurface['ctx'], view: Mat2d, render: MarchingAntsRender): void => {
+  if (render.paths.length === 0) {
+    return;
+  }
+  const scale = getScale(view) || 1;
+  const dash = ANTS_DASH_PX / scale;
+  const lineWidth = ANTS_LINE_WIDTH_PX / scale;
+  const offset = render.phase / scale;
+
+  ctx.save();
+  ctx.setTransform(view.a, view.b, view.c, view.d, view.e, view.f);
+  ctx.lineWidth = lineWidth;
+
+  // Dark base run: a continuous dashed outline.
+  ctx.setLineDash([dash, dash]);
+  ctx.lineDashOffset = -offset;
+  ctx.strokeStyle = ANTS_DARK;
+  for (const path of render.paths) {
+    ctx.stroke(path);
+  }
+
+  // Light run, offset by one dash so it fills the gaps and appears to crawl.
+  ctx.lineDashOffset = -offset + dash;
+  ctx.strokeStyle = ANTS_LIGHT;
+  for (const path of render.paths) {
+    ctx.stroke(path);
+  }
+
+  ctx.restore();
+};
+
+/** The animator handle the engine starts/stops as selection presence + attachment change. */
+export interface AntsAnimator {
+  /** Begins the animation loop (idempotent). */
+  start(): void;
+  /** Stops the loop and cancels any pending frame (idempotent). */
+  stop(): void;
+  /** True while the loop is running. */
+  readonly isRunning: boolean;
+}
+
+/** Dependencies for {@link createAntsAnimator}; all injectable for deterministic tests. */
+export interface AntsAnimatorDeps {
+  requestFrame(callback: () => void): number;
+  cancelFrame(handle: number): void;
+  /** Monotonic clock (ms) used to throttle steps to {@link AntsAnimatorDeps.intervalMs}. */
+  now(): number;
+  /** Called on each throttled step (the engine advances the phase + invalidates the overlay). */
+  onStep(): void;
+  /** Step interval in ms; defaults to {@link ANTS_INTERVAL_MS}. */
+  intervalMs?: number;
+}
+
+/**
+ * Creates a self-rescheduling animation loop that fires `onStep` at most every
+ * `intervalMs`. It reschedules on every frame while running (to keep polling the
+ * clock) but only steps on the throttle boundary.
+ */
+export const createAntsAnimator = (deps: AntsAnimatorDeps): AntsAnimator => {
+  const intervalMs = deps.intervalMs ?? ANTS_INTERVAL_MS;
+  let running = false;
+  let handle: number | null = null;
+  let lastStep = 0;
+
+  const frame = (): void => {
+    handle = null;
+    if (!running) {
+      return;
+    }
+    const t = deps.now();
+    if (t - lastStep >= intervalMs) {
+      lastStep = t;
+      deps.onStep();
+    }
+    // Reschedule while running (even between steps) so the clock keeps advancing.
+    if (running) {
+      handle = deps.requestFrame(frame);
+    }
+  };
+
+  return {
+    get isRunning() {
+      return running;
+    },
+    start: () => {
+      if (running) {
+        return;
+      }
+      running = true;
+      // Force the first frame to step immediately.
+      lastStep = deps.now() - intervalMs;
+      handle = deps.requestFrame(frame);
+    },
+    stop: () => {
+      running = false;
+      if (handle !== null) {
+        deps.cancelFrame(handle);
+        handle = null;
+      }
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/maskOutline.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/maskOutline.test.ts
new file mode 100644
index 00000000000..229df87c77b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/maskOutline.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+
+import { traceMaskOutlinePath } from './maskOutline';
+
+/** Builds RGBA data from a row-major alpha grid. */
+const alphaGrid = (
+  rows: readonly (readonly number[])[]
+): { data: Uint8ClampedArray; height: number; width: number } => {
+  const height = rows.length;
+  const width = rows[0]?.length ?? 0;
+  const data = new Uint8ClampedArray(width * height * 4);
+  rows.forEach((row, y) =>
+    row.forEach((alpha, x) => {
+      data[(y * width + x) * 4 + 3] = alpha;
+    })
+  );
+  return { data, height, width };
+};
+
+const ORIGIN = { x: 0, y: 0 };
+
+describe('traceMaskOutlinePath', () => {
+  it('returns an empty path for an empty or sub-threshold mask', () => {
+    expect(traceMaskOutlinePath(alphaGrid([]), ORIGIN)).toBe('');
+    expect(
+      traceMaskOutlinePath(
+        alphaGrid([
+          [0, 0],
+          [0, 0],
+        ]),
+        ORIGIN
+      )
+    ).toBe('');
+    expect(
+      traceMaskOutlinePath(
+        alphaGrid([
+          [64, 64],
+          [64, 64],
+        ]),
+        ORIGIN
+      )
+    ).toBe('');
+  });
+
+  it('honors a lower threshold for faint coverage', () => {
+    const grid = alphaGrid([[64]]);
+    expect(traceMaskOutlinePath(grid, ORIGIN)).toBe('');
+    expect(traceMaskOutlinePath(grid, ORIGIN, 1)).toBe('M 0 0 L 1 0 L 1 1 L 0 1 Z');
+  });
+
+  it('traces a full mask as its bounding rectangle with merged collinear runs', () => {
+    const grid = alphaGrid([
+      [255, 255, 255],
+      [255, 255, 255],
+    ]);
+    expect(traceMaskOutlinePath(grid, { x: 10, y: 20 })).toBe('M 10 20 L 13 20 L 13 22 L 10 22 Z');
+  });
+
+  it('traces a single interior pixel offset by the document-space origin', () => {
+    const grid = alphaGrid([
+      [0, 0, 0],
+      [0, 255, 0],
+      [0, 0, 0],
+    ]);
+    expect(traceMaskOutlinePath(grid, { x: 7, y: -3 })).toBe('M 8 -2 L 9 -2 L 9 -1 L 8 -1 Z');
+  });
+
+  it('emits a counter-clockwise inner loop for a hole', () => {
+    const grid = alphaGrid([
+      [255, 255, 255],
+      [255, 0, 255],
+      [255, 255, 255],
+    ]);
+    const path = traceMaskOutlinePath(grid, ORIGIN);
+    const loops = path.split(' Z').filter((segment) => segment.trim().length > 0);
+    expect(loops).toHaveLength(2);
+    expect(path).toContain('M 0 0 L 3 0 L 3 3 L 0 3 Z');
+    // The hole loop winds opposite to the outer loop (counter-clockwise), so
+    // nonzero fill keeps the hole.
+    expect(path).toContain('M 2 1 L 1 1 L 1 2 L 2 2 Z');
+  });
+
+  it('keeps diagonally touching regions as two separate loops', () => {
+    const grid = alphaGrid([
+      [255, 0],
+      [0, 255],
+    ]);
+    const path = traceMaskOutlinePath(grid, ORIGIN);
+    const loops = path.split(' Z').filter((segment) => segment.trim().length > 0);
+    expect(loops).toHaveLength(2);
+    expect(path).toContain('M 0 0 L 1 0 L 1 1 L 0 1 Z');
+    expect(path).toContain('M 1 1 L 2 1 L 2 2 L 1 2 Z');
+  });
+
+  it('traces disjoint regions as independent closed loops', () => {
+    const grid = alphaGrid([
+      [255, 0, 255],
+      [255, 0, 255],
+    ]);
+    const path = traceMaskOutlinePath(grid, ORIGIN);
+    expect(path).toContain('M 0 0 L 1 0 L 1 2 L 0 2 Z');
+    expect(path).toContain('M 2 0 L 3 0 L 3 2 L 2 2 Z');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/maskOutline.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/maskOutline.ts
new file mode 100644
index 00000000000..0bc0338db25
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/maskOutline.ts
@@ -0,0 +1,143 @@
+/**
+ * Rectilinear boundary tracing for alpha masks.
+ *
+ * Converts a mask's alpha channel into closed pixel-edge contours so the
+ * marching ants can stroke the mask's true outline instead of its bounding
+ * rect. Outer boundaries wind clockwise (screen coordinates) and holes wind
+ * counter-clockwise, so the emitted path also nonzero-fills to the same shape
+ * it outlines.
+ */
+
+interface MaskAlphaSource {
+  /** RGBA pixel data (only the alpha channel is read). */
+  data: Uint8ClampedArray;
+  width: number;
+  height: number;
+}
+
+// Directions: 0 = right, 1 = down, 2 = left, 3 = up (screen coordinates).
+const DIRECTION_X = [1, 0, -1, 0] as const;
+const DIRECTION_Y = [0, 1, 0, -1] as const;
+
+/**
+ * Traces the outline of every alpha region as an SVG path in document space
+ * (`origin` offsets the mask-local pixel grid). Pixels count as inside at
+ * `alpha >= threshold`. Returns an empty string for an empty mask.
+ */
+export const traceMaskOutlinePath = (
+  source: MaskAlphaSource,
+  origin: { x: number; y: number },
+  threshold = 128
+): string => {
+  const { data, height, width } = source;
+  if (width <= 0 || height <= 0) {
+    return '';
+  }
+  const inside = (x: number, y: number): boolean =>
+    x >= 0 && y >= 0 && x < width && y < height && data[(y * width + x) * 4 + 3]! >= threshold;
+
+  // Directed boundary edges bucketed by start vertex on the (width+1)×(height+1)
+  // pixel-corner grid. Travelling each edge keeps the inside on the right, which
+  // makes outer loops clockwise and holes counter-clockwise.
+  const stride = width + 1;
+  const outgoing = new Map<number, number[]>();
+  const addEdge = (x: number, y: number, direction: number): void => {
+    const key = y * stride + x;
+    const bucket = outgoing.get(key);
+    if (bucket) {
+      bucket.push(direction);
+    } else {
+      outgoing.set(key, [direction]);
+    }
+  };
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      if (!inside(x, y)) {
+        continue;
+      }
+      if (!inside(x, y - 1)) {
+        addEdge(x, y, 0);
+      }
+      if (!inside(x + 1, y)) {
+        addEdge(x + 1, y, 1);
+      }
+      if (!inside(x, y + 1)) {
+        addEdge(x + 1, y + 1, 2);
+      }
+      if (!inside(x - 1, y)) {
+        addEdge(x, y + 1, 3);
+      }
+    }
+  }
+  if (outgoing.size === 0) {
+    return '';
+  }
+
+  // At a pinch vertex (two regions touching diagonally) two edges leave the
+  // same corner; preferring the tightest right turn keeps each loop around its
+  // own region instead of crossing over to the neighbour.
+  const takeEdge = (vertex: number, incoming: number): number | null => {
+    const bucket = outgoing.get(vertex);
+    if (!bucket || bucket.length === 0) {
+      return null;
+    }
+    for (const direction of [(incoming + 1) % 4, incoming, (incoming + 3) % 4]) {
+      const index = bucket.indexOf(direction);
+      if (index !== -1) {
+        bucket.splice(index, 1);
+        if (bucket.length === 0) {
+          outgoing.delete(vertex);
+        }
+        return direction;
+      }
+    }
+    return null;
+  };
+
+  const segments: string[] = [];
+  for (const [startVertex, bucket] of outgoing) {
+    while (bucket.length > 0) {
+      let direction = bucket[0]!;
+      bucket.splice(0, 1);
+      if (bucket.length === 0) {
+        outgoing.delete(startVertex);
+      }
+      let vertex = startVertex;
+      const startX = vertex % stride;
+      const startY = (vertex - startX) / stride;
+      const points: number[] = [startX, startY];
+      let lastDirection = direction;
+      for (;;) {
+        vertex += DIRECTION_Y[direction]! * stride + DIRECTION_X[direction]!;
+        const x = vertex % stride;
+        const y = (vertex - x) / stride;
+        if (direction === lastDirection && points.length >= 4) {
+          points[points.length - 2] = x;
+          points[points.length - 1] = y;
+        } else {
+          points.push(x, y);
+        }
+        lastDirection = direction;
+        if (vertex === startVertex) {
+          break;
+        }
+        const next = takeEdge(vertex, direction);
+        if (next === null) {
+          // Unreachable for well-formed edge sets; bail rather than loop forever.
+          break;
+        }
+        direction = next;
+      }
+      // The walk re-appends the start vertex before closing; `Z` already closes.
+      if (points.length >= 4 && points[points.length - 2] === startX && points[points.length - 1] === startY) {
+        points.length -= 2;
+      }
+      let d = `M ${origin.x + points[0]!} ${origin.y + points[1]!}`;
+      for (let index = 2; index < points.length; index += 2) {
+        d += ` L ${origin.x + points[index]!} ${origin.y + points[index + 1]!}`;
+      }
+      segments.push(`${d} Z`);
+    }
+  }
+  return segments.join(' ');
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionOps.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionOps.test.ts
new file mode 100644
index 00000000000..59314ea8be1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionOps.test.ts
@@ -0,0 +1,145 @@
+import type { StubRasterBackend, StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { eraseMaskedRegion, fillMaskedRegion } from '@workbench/canvas-engine/selection/selectionOps';
+import { describe, expect, it } from 'vitest';
+
+/** Wraps the stub backend so every scratch surface it mints is captured for assertions. */
+const createCapturingBackend = (): { backend: StubRasterBackend; created: StubRasterSurface[] } => {
+  const inner = createTestStubRasterBackend();
+  const created: StubRasterSurface[] = [];
+  return {
+    backend: {
+      ...inner,
+      createSurface: (w, h) => {
+        const s = inner.createSurface(w, h);
+        created.push(s);
+        return s;
+      },
+    },
+    created,
+  };
+};
+
+const compositeOps = (surface: StubRasterSurface): unknown[] =>
+  surface.callLog.filter((e) => e.op === 'set' && e.args[0] === 'globalCompositeOperation').map((e) => e.args[1]);
+
+describe('fillMaskedRegion', () => {
+  it('masks the color to the selection (destination-in scratch) and draws it over the target', () => {
+    const { backend, created } = createCapturingBackend();
+    const target = backend.createSurface(100, 100);
+    const mask = backend.createSurface(100, 100);
+    created.length = 0; // ignore target/mask; capture only the op's scratch
+
+    fillMaskedRegion({
+      backend,
+      color: '#ff0000',
+      mask,
+      maskOrigin: { x: 0, y: 0 },
+      rect: { height: 20, width: 20, x: 10, y: 10 },
+      target,
+      targetOrigin: { x: 0, y: 0 },
+    });
+
+    // The scratch: fill the color, then intersect with the mask.
+    const scratch = created[0]!;
+    const scratchOps = scratch.callLog.map((e) => e.op);
+    expect(scratchOps).toContain('fillRect');
+    expect(compositeOps(scratch)).toContain('destination-in');
+
+    // The target: the masked color is drawn source-over at the rect origin.
+    const targetDraw = target.callLog.find((e) => e.op === 'drawImage');
+    expect(targetDraw).toBeDefined();
+    expect(compositeOps(target)).toContain('source-over');
+  });
+
+  it('uses source-atop on the target when composite is source-atop (transparency lock)', () => {
+    const { backend, created } = createCapturingBackend();
+    const target = backend.createSurface(100, 100);
+    const mask = backend.createSurface(100, 100);
+    created.length = 0;
+
+    fillMaskedRegion({
+      backend,
+      color: '#ff0000',
+      composite: 'source-atop',
+      mask,
+      maskOrigin: { x: 0, y: 0 },
+      rect: { height: 20, width: 20, x: 10, y: 10 },
+      target,
+      targetOrigin: { x: 0, y: 0 },
+    });
+
+    // Transparency lock: the final blit is source-atop, so colour lands ONLY where
+    // the target is already opaque (never fills transparent space).
+    expect(compositeOps(target)).toContain('source-atop');
+    expect(compositeOps(target)).not.toContain('source-over');
+  });
+
+  it('translates the draws by the target/mask origins (content-sized placement)', () => {
+    const { backend, created } = createCapturingBackend();
+    const target = backend.createSurface(100, 100);
+    const mask = backend.createSurface(100, 100);
+    created.length = 0;
+
+    // Edit region at doc (50,50); mask surface origin (40,40); target cache
+    // origin (30,30). The mask is drawn into the region-local scratch at
+    // (maskOrigin - rect) = (-10,-10); the scratch is drawn onto the target at
+    // (rect - targetOrigin) = (20,20).
+    fillMaskedRegion({
+      backend,
+      color: '#ff0000',
+      mask,
+      maskOrigin: { x: 40, y: 40 },
+      rect: { height: 20, width: 20, x: 50, y: 50 },
+      target,
+      targetOrigin: { x: 30, y: 30 },
+    });
+
+    const scratch = created[0]!;
+    const scratchMaskDraw = scratch.callLog.find((e) => e.op === 'drawImage');
+    expect(scratchMaskDraw?.args.slice(1, 3)).toEqual([-10, -10]);
+    const targetDraw = target.callLog.find((e) => e.op === 'drawImage');
+    expect(targetDraw?.args.slice(1, 3)).toEqual([20, 20]);
+  });
+
+  it('is a no-op for an empty rect', () => {
+    const { backend } = createCapturingBackend();
+    const target = backend.createSurface(10, 10);
+    const mask = backend.createSurface(10, 10);
+    const before = target.callLog.length;
+    fillMaskedRegion({
+      backend,
+      color: '#000',
+      mask,
+      maskOrigin: { x: 0, y: 0 },
+      rect: { height: 0, width: 0, x: 0, y: 0 },
+      target,
+      targetOrigin: { x: 0, y: 0 },
+    });
+    expect(target.callLog.length).toBe(before);
+  });
+});
+
+describe('eraseMaskedRegion', () => {
+  it('composites destination-out through the mask onto the target', () => {
+    const { backend, created } = createCapturingBackend();
+    const target = backend.createSurface(100, 100);
+    const mask = backend.createSurface(100, 100);
+    created.length = 0;
+
+    eraseMaskedRegion({
+      backend,
+      mask,
+      maskOrigin: { x: 0, y: 0 },
+      rect: { height: 20, width: 20, x: 5, y: 5 },
+      target,
+      targetOrigin: { x: 0, y: 0 },
+    });
+
+    const scratch = created[0]!;
+    expect(scratch.callLog.map((e) => e.op)).toContain('drawImage');
+    expect(compositeOps(target)).toContain('destination-out');
+    expect(target.callLog.some((e) => e.op === 'drawImage')).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionOps.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionOps.ts
new file mode 100644
index 00000000000..73387d07680
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionOps.ts
@@ -0,0 +1,114 @@
+/**
+ * Selection-constrained raster primitives: fill and erase a layer's pixels
+ * within the selection mask.
+ *
+ * These are the pure pixel ops behind the engine's `fillSelection` /
+ * `eraseSelection` (the engine owns the layer-eligibility guards, dirty-rect
+ * before/after capture, undo history, and persistence around them). Each op
+ * composites through a scratch surface so the write lands ONLY where the mask is
+ * opaque — pixels outside the selection are never touched — and flows entirely
+ * through the {@link RasterBackend} `ctx` seam, so it runs on the node stub.
+ *
+ * Coordinate spaces: both the layer cache and the selection mask are content-
+ * sized (placed) surfaces with their own origins. `rect` is the edit region in
+ * document (= layer-local) space; `targetOrigin` / `maskOrigin` are the target
+ * cache surface's and the mask surface's document-space origins, so a document
+ * coordinate `d` maps to target-surface `d - targetOrigin` and mask-surface
+ * `d - maskOrigin`.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+/** Shared inputs for a masked layer edit over a document-space `rect`. */
+export interface MaskedEditParams {
+  backend: RasterBackend;
+  /** The layer cache surface (content-sized) and its document-space origin. */
+  target: RasterSurface;
+  /** The target surface's document-space origin (its cache rect's `x`/`y`). */
+  targetOrigin: Vec2;
+  /** The selection mask surface (alpha 255 inside). */
+  mask: RasterSurface;
+  /** The mask surface's document-space origin (its selection rect's `x`/`y`). */
+  maskOrigin: Vec2;
+  /** The dirty region to edit (document space), integer bounds. */
+  rect: Rect;
+}
+
+/**
+ * Fills `color` into `target` wherever `mask` is opaque, within `rect`. Builds a
+ * `color`-filled scratch (region-local), intersects it with the mask
+ * (`destination-in`), then draws the masked color over the target.
+ *
+ * `composite` is the final blit's op: `source-over` (default) fills every masked
+ * pixel; `source-atop` honours a transparency lock — colour lands ONLY where the
+ * target is already opaque, never into transparent space (mirrors the
+ * transparency-locked brush in `paintTool.ts`).
+ */
+export const fillMaskedRegion = ({
+  backend,
+  color,
+  composite = 'source-over',
+  mask,
+  maskOrigin,
+  rect,
+  target,
+  targetOrigin,
+}: MaskedEditParams & { color: string; composite?: 'source-over' | 'source-atop' }): void => {
+  if (rect.width <= 0 || rect.height <= 0) {
+    return;
+  }
+  const scratch = backend.createSurface(rect.width, rect.height);
+  const sctx = scratch.ctx;
+  sctx.setTransform(1, 0, 0, 1, 0, 0);
+  sctx.globalCompositeOperation = 'source-over';
+  sctx.globalAlpha = 1;
+  sctx.fillStyle = color;
+  sctx.fillRect(0, 0, rect.width, rect.height);
+  // Keep the color only where the mask is opaque (mask drawn at its offset within
+  // the region-local scratch).
+  sctx.globalCompositeOperation = 'destination-in';
+  sctx.drawImage(mask.canvas, maskOrigin.x - rect.x, maskOrigin.y - rect.y);
+
+  const ctx = target.ctx;
+  ctx.save();
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.globalCompositeOperation = composite;
+  ctx.globalAlpha = 1;
+  ctx.drawImage(scratch.canvas, rect.x - targetOrigin.x, rect.y - targetOrigin.y);
+  ctx.restore();
+};
+
+/**
+ * Erases (`destination-out`) `target`'s pixels wherever `mask` is opaque, within
+ * `rect`. The mask shape is copied into a region-local scratch and composited out
+ * of the target.
+ */
+export const eraseMaskedRegion = ({
+  backend,
+  mask,
+  maskOrigin,
+  rect,
+  target,
+  targetOrigin,
+}: MaskedEditParams): void => {
+  if (rect.width <= 0 || rect.height <= 0) {
+    return;
+  }
+  const scratch = backend.createSurface(rect.width, rect.height);
+  const sctx = scratch.ctx;
+  sctx.setTransform(1, 0, 0, 1, 0, 0);
+  sctx.globalCompositeOperation = 'source-over';
+  sctx.globalAlpha = 1;
+  sctx.drawImage(mask.canvas, maskOrigin.x - rect.x, maskOrigin.y - rect.y);
+
+  const ctx = target.ctx;
+  ctx.save();
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  ctx.globalCompositeOperation = 'destination-out';
+  ctx.globalAlpha = 1;
+  ctx.drawImage(scratch.canvas, rect.x - targetOrigin.x, rect.y - targetOrigin.y);
+  ctx.restore();
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionState.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionState.test.ts
new file mode 100644
index 00000000000..afd648fdb63
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionState.test.ts
@@ -0,0 +1,303 @@
+import type { StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type { PlacedSurface, Rect } from '@workbench/canvas-engine/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { createSelectionState, type SelectionState } from '@workbench/canvas-engine/selection/selectionState';
+import { describe, expect, it, vi } from 'vitest';
+
+const DOC = { height: 100, width: 100 };
+
+const rectBounds = (x: number, y: number, w: number, h: number): Rect => ({ height: h, width: w, x, y });
+
+/** A fake Path2D carrier (Path2D is absent in node); the stub ctx just records it. */
+const fakePath = (id: string): Path2D => ({ id }) as unknown as Path2D;
+
+const imageData = (alphas: readonly number[]): ImageData => {
+  const data = new Uint8ClampedArray(alphas.length * 4);
+  alphas.forEach((alpha, index) => {
+    data[index * 4] = index + 1;
+    data[index * 4 + 1] = index + 11;
+    data[index * 4 + 2] = index + 21;
+    data[index * 4 + 3] = alpha;
+  });
+  return { colorSpace: 'srgb', data, height: 2, width: 2 } as ImageData;
+};
+
+const placedMask = (alphas: readonly number[]): { placed: PlacedSurface; pixels: ImageData } => {
+  const backend = createTestStubRasterBackend();
+  const surface = backend.createSurface(2, 2);
+  const pixels = imageData(alphas);
+  Object.defineProperty(surface.ctx, 'getImageData', { value: () => pixels });
+  return { pixels, placed: { rect: rectBounds(7, -3, 2, 2), surface } };
+};
+
+const createHarness = (docSize: { width: number; height: number } | null = DOC) => {
+  const backend = createTestStubRasterBackend();
+  const onChange = vi.fn();
+  const selection: SelectionState = createSelectionState({
+    backend,
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    getDocumentSize: () => docSize,
+    onChange,
+  });
+  return { backend, onChange, selection };
+};
+
+/** The recorded op names on the mask surface. */
+const maskLog = (selection: SelectionState): { op: string; args: unknown[] }[] =>
+  (selection.mask()?.surface as StubRasterSurface | undefined)?.callLog ?? [];
+
+/** The last `globalCompositeOperation` value set before a given op, scanning the whole log. */
+const compositeOpsFor = (log: { op: string; args: unknown[] }[]): unknown[] =>
+  log.filter((e) => e.op === 'set' && e.args[0] === 'globalCompositeOperation').map((e) => e.args[1]);
+
+describe('selectionState: mask building from a path', () => {
+  it('replace clears then source-over fills the path, sets bounds + hasSelection', () => {
+    const { selection, onChange } = createHarness();
+    selection.commit({ bounds: rectBounds(10, 10, 20, 20), op: 'replace', path: fakePath('p1') });
+
+    expect(selection.hasSelection()).toBe(true);
+    expect(selection.bounds()).toEqual(rectBounds(10, 10, 20, 20));
+    expect(selection.antsPaths()).toHaveLength(1);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    const log = maskLog(selection);
+    const ops = log.map((e) => e.op);
+    expect(ops).toContain('clearRect');
+    expect(ops).toContain('fill');
+    expect(compositeOpsFor(log)).toContain('source-over');
+  });
+
+  it('no longer clamps bounds to the document rect (infinite plane); the mask is bounded to the path', () => {
+    const { selection } = createHarness();
+    selection.commit({ bounds: rectBounds(-10, -10, 200, 200), op: 'replace', path: fakePath('p') });
+    // Content-sized: the selection bounds are the path's own bounds, not clamped
+    // to the document. The mask surface is placed at that (negative) origin.
+    expect(selection.bounds()).toEqual(rectBounds(-10, -10, 200, 200));
+    expect(selection.mask()?.rect).toEqual(rectBounds(-10, -10, 200, 200));
+  });
+});
+
+describe('selectionState: boolean ops', () => {
+  it('add unions bounds with source-over and keeps both ant paths', () => {
+    const { selection } = createHarness();
+    selection.commit({ bounds: rectBounds(10, 10, 10, 10), op: 'replace', path: fakePath('a') });
+    selection.commit({ bounds: rectBounds(40, 40, 10, 10), op: 'add', path: fakePath('b') });
+
+    expect(selection.hasSelection()).toBe(true);
+    expect(selection.bounds()).toEqual(rectBounds(10, 10, 40, 40));
+    expect(selection.antsPaths()).toHaveLength(2);
+    expect(compositeOpsFor(maskLog(selection))).toContain('source-over');
+  });
+
+  it('subtract composites destination-out', () => {
+    const { selection } = createHarness();
+    selection.commit({ bounds: rectBounds(0, 0, 50, 50), op: 'replace', path: fakePath('a') });
+    selection.commit({ bounds: rectBounds(10, 10, 10, 10), op: 'subtract', path: fakePath('b') });
+    expect(selection.hasSelection()).toBe(true);
+    expect(compositeOpsFor(maskLog(selection))).toContain('destination-out');
+  });
+
+  it('intersect composites destination-in and intersects the bounds', () => {
+    const { selection } = createHarness();
+    selection.commit({ bounds: rectBounds(0, 0, 50, 50), op: 'replace', path: fakePath('a') });
+    selection.commit({ bounds: rectBounds(30, 30, 50, 50), op: 'intersect', path: fakePath('b') });
+    expect(selection.hasSelection()).toBe(true);
+    expect(selection.bounds()).toEqual(rectBounds(30, 30, 20, 20));
+    expect(compositeOpsFor(maskLog(selection))).toContain('destination-in');
+  });
+
+  it('intersect against no existing selection clears to nothing', () => {
+    const { selection } = createHarness();
+    selection.commit({ bounds: rectBounds(0, 0, 10, 10), op: 'intersect', path: fakePath('a') });
+    expect(selection.hasSelection()).toBe(false);
+    expect(selection.bounds()).toBeNull();
+    expect(selection.mask()).toBeNull();
+  });
+});
+
+describe('selectionState: selectAll / invert / clear', () => {
+  it('selectAll fills the whole document rect', () => {
+    const { selection } = createHarness();
+    selection.selectAll(rectBounds(0, 0, 100, 100));
+    expect(selection.hasSelection()).toBe(true);
+    expect(selection.bounds()).toEqual(rectBounds(0, 0, 100, 100));
+    expect(maskLog(selection).map((e) => e.op)).toContain('fillRect');
+  });
+
+  it('invert of an empty selection selects everything', () => {
+    const { selection } = createHarness();
+    selection.invert(rectBounds(0, 0, 100, 100));
+    expect(selection.hasSelection()).toBe(true);
+    expect(selection.bounds()).toEqual(rectBounds(0, 0, 100, 100));
+  });
+
+  it('invert of a selection keeps a document-border ants path plus the former outline', () => {
+    const { selection } = createHarness();
+    selection.commit({ bounds: rectBounds(10, 10, 20, 20), op: 'replace', path: fakePath('a') });
+    expect(selection.antsPaths()).toHaveLength(1);
+    selection.invert(rectBounds(0, 0, 100, 100));
+    expect(selection.hasSelection()).toBe(true);
+    // The document border plus the former outline.
+    expect(selection.antsPaths()).toHaveLength(2);
+  });
+
+  it('clear deselects and drops the mask + bounds', () => {
+    const { selection, onChange } = createHarness();
+    selection.commit({ bounds: rectBounds(10, 10, 20, 20), op: 'replace', path: fakePath('a') });
+    onChange.mockClear();
+    selection.clear();
+    expect(selection.hasSelection()).toBe(false);
+    expect(selection.bounds()).toBeNull();
+    expect(selection.mask()).toBeNull();
+    expect(selection.antsPaths()).toHaveLength(0);
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('selectionState: replaceMask', () => {
+  it('replaces prior pixels with an isolated, pixel-exact alpha mask at its world rect', () => {
+    const { selection, onChange } = createHarness();
+    selection.selectAll(rectBounds(0, 0, 50, 50));
+    const previousSurface = selection.mask()!.surface;
+    const source = placedMask([0, 64, 255, 0]);
+    onChange.mockClear();
+
+    selection.replaceMask(source.placed);
+
+    expect(selection.hasSelection()).toBe(true);
+    expect(selection.bounds()).toEqual(source.placed.rect);
+    expect(selection.mask()?.rect).toEqual(source.placed.rect);
+    expect(selection.mask()?.surface).not.toBe(source.placed.surface);
+    expect(selection.mask()?.surface).not.toBe(previousSurface);
+    // The ants trace the mask's true edge — here only the solid (0,1) pixel —
+    // rather than the replacement's bounding rect.
+    expect(selection.antsPaths()).toEqual([{ d: 'M 7 -2 L 8 -2 L 8 -1 L 7 -1 Z' } as unknown as Path2D]);
+
+    const put = maskLog(selection).find((entry) => entry.op === 'putImageData');
+    const copied = put?.args[0] as ImageData | undefined;
+    expect(copied).toBeDefined();
+    expect(copied).not.toBe(source.pixels);
+    expect([...copied!.data]).toEqual([...source.pixels.data]);
+
+    source.pixels.data.fill(0);
+    expect(copied!.data.filter((_, index) => index % 4 === 3)).toEqual(new Uint8ClampedArray([0, 64, 255, 0]));
+    expect(onChange).toHaveBeenCalledOnce();
+  });
+
+  it('clears the selection when the replacement has no alpha', () => {
+    const { selection, onChange } = createHarness();
+    selection.selectAll(rectBounds(0, 0, 50, 50));
+    onChange.mockClear();
+
+    selection.replaceMask(placedMask([0, 0, 0, 0]).placed);
+
+    expect(selection.hasSelection()).toBe(false);
+    expect(selection.bounds()).toBeNull();
+    expect(selection.mask()).toBeNull();
+    expect(selection.antsPaths()).toEqual([]);
+    expect(onChange).toHaveBeenCalledOnce();
+  });
+
+  it('detaches an empty replacement without touching the prior mask surface', () => {
+    const { selection, onChange } = createHarness();
+    selection.selectAll(rectBounds(1, 2, 30, 40));
+    const before = selection.mask()!;
+    const beforePath = selection.antsPaths()[0];
+    const previousLogLength = (before.surface as StubRasterSurface).callLog.length;
+    const clearRect = vi.fn(() => {
+      throw new Error('prior selection surface must not be cleared');
+    });
+    Object.defineProperty(before.surface.ctx, 'clearRect', { value: clearRect });
+    onChange.mockClear();
+
+    expect(() => selection.replaceMask(placedMask([0, 0, 0, 0]).placed)).not.toThrow();
+
+    expect(clearRect).not.toHaveBeenCalled();
+    expect((before.surface as StubRasterSurface).callLog).toHaveLength(previousLogLength);
+    expect(before.rect).toEqual(rectBounds(1, 2, 30, 40));
+    expect(beforePath).toBeDefined();
+    expect(selection.hasSelection()).toBe(false);
+    expect(selection.bounds()).toBeNull();
+    expect(selection.mask()).toBeNull();
+    expect(selection.antsPaths()).toEqual([]);
+    expect(onChange).toHaveBeenCalledOnce();
+  });
+
+  it('preserves the exact prior selection when staging replacement pixels fails', () => {
+    const { backend, selection, onChange } = createHarness();
+    selection.selectAll(rectBounds(1, 2, 30, 40));
+    const before = selection.mask()!;
+    const beforePaths = selection.antsPaths();
+    const createSurface = backend.createSurface;
+    vi.spyOn(backend, 'createSurface').mockImplementation((width, height) => {
+      const surface = createSurface(width, height);
+      Object.defineProperty(surface.ctx, 'putImageData', {
+        value: () => {
+          throw new Error('selection pixel staging failed');
+        },
+      });
+      return surface;
+    });
+    onChange.mockClear();
+
+    expect(() => selection.replaceMask(placedMask([0, 64, 255, 0]).placed)).toThrow('selection pixel staging failed');
+
+    expect(selection.mask()?.surface).toBe(before.surface);
+    expect(selection.mask()?.rect).toEqual(before.rect);
+    expect(selection.bounds()).toEqual(before.rect);
+    expect(selection.antsPaths()).toHaveLength(beforePaths.length);
+    expect(selection.antsPaths()[0]).toBe(beforePaths[0]);
+    expect(selection.hasSelection()).toBe(true);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('preserves the exact prior selection when staging its ants path fails', () => {
+    const backend = createTestStubRasterBackend();
+    const onChange = vi.fn();
+    let failPath = false;
+    const selection = createSelectionState({
+      backend,
+      createPath2D: (d) => {
+        if (failPath) {
+          throw new Error('selection path staging failed');
+        }
+        return { d } as unknown as Path2D;
+      },
+      getDocumentSize: () => DOC,
+      onChange,
+    });
+    selection.selectAll(rectBounds(1, 2, 30, 40));
+    const before = selection.mask()!;
+    const beforePaths = selection.antsPaths();
+    failPath = true;
+    onChange.mockClear();
+
+    expect(() => selection.replaceMask(placedMask([0, 64, 255, 0]).placed)).toThrow('selection path staging failed');
+
+    expect(selection.mask()?.surface).toBe(before.surface);
+    expect(selection.mask()?.rect).toEqual(before.rect);
+    expect(selection.bounds()).toEqual(before.rect);
+    expect(selection.antsPaths()).toHaveLength(beforePaths.length);
+    expect(selection.antsPaths()[0]).toBe(beforePaths[0]);
+    expect(selection.hasSelection()).toBe(true);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+describe('selectionState: teardown + guards', () => {
+  it('commit is a no-op with no document size', () => {
+    const { selection, onChange } = createHarness(null);
+    selection.commit({ bounds: rectBounds(0, 0, 10, 10), op: 'replace', path: fakePath('a') });
+    expect(selection.hasSelection()).toBe(false);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('dispose clears state (document-replace teardown path)', () => {
+    const { selection } = createHarness();
+    selection.commit({ bounds: rectBounds(0, 0, 10, 10), op: 'replace', path: fakePath('a') });
+    selection.dispose();
+    expect(selection.hasSelection()).toBe(false);
+    expect(selection.mask()).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionState.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionState.ts
new file mode 100644
index 00000000000..9862a9298e9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/selection/selectionState.ts
@@ -0,0 +1,410 @@
+/**
+ * Engine-transient pixel selection.
+ *
+ * Per the plan's state-tier table, a selection is *interaction* state: it lives
+ * on the engine, never in the reducer contract, and is not undoable. The source
+ * of truth is the set of closed `Path2D` polygons the lasso tool commits; the
+ * derived artifact is a bounded **mask surface** (alpha 255 inside the
+ * selection), sized to the selection extent and placed in document space (a
+ * {@link PlacedSurface}), built through the {@link RasterBackend} seam. Boolean ops
+ * (`replace`/`add`/`subtract`/`intersect`) are applied to the MASK — that is the
+ * single source of truth for painting/fill clipping. The committed path list is
+ * kept only for {@link marchingAnts} rendering (stroking the outlines), not for
+ * re-deriving the mask.
+ *
+ * ## Marching-ants approximation
+ *
+ * Ants are stroked from the committed path LIST (each path drawn dashed), not by
+ * tracing the mask's true edge. This matches the mask exactly for `replace` and
+ * `add`, and reads correctly for `subtract` (the cut-out path's outline shows as
+ * a hole) and `selectAll`/`invert` (a document-border path is included). It is an
+ * approximation for `intersect` and for heavily overlapping compositions, where
+ * the true selection outline is the boolean result rather than the union of the
+ * source outlines — the ants may show interior source edges that the mask does
+ * not. The exception is {@link SelectionState.replaceMask} (pixel-mask
+ * replacement, e.g. a Select Object result), whose ants ARE traced from the
+ * mask's true edge via {@link traceMaskOutlinePath}. The mask itself is always
+ * exact.
+ *
+ * ## Emptiness
+ *
+ * `hasSelection` is tracked structurally, not by scanning pixels (a scan is
+ * unavailable on the node raster stub and costly on the DOM). Consequently,
+ * `subtract`ing away the entire selection leaves `hasSelection` true until an
+ * explicit deselect — a known, documented limitation of this phase.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { CreatePath2D } from '@workbench/canvas-engine/freehand';
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { PlacedSurface, Rect, SelectionOp, Vec2 } from '@workbench/canvas-engine/types';
+
+import { intersect, isEmpty, roundOut, union } from '@workbench/canvas-engine/math/rect';
+import { traceMaskOutlinePath } from '@workbench/canvas-engine/selection/maskOutline';
+
+/** A committed selection contribution: the closed path and the op it applied. */
+export interface SelectionCommit {
+  path: Path2D;
+  /** The path's document-space bounds (used to maintain the selection bounds cheaply). */
+  bounds: Rect;
+  op: SelectionOp;
+}
+
+/** The engine-facing selection handle. */
+export interface SelectionState {
+  /** Whether a selection currently exists (drives clip/fill/ants gating). */
+  hasSelection(): boolean;
+  /** The selection's document-space bounds, or `null` when empty. */
+  bounds(): Rect | null;
+  /**
+   * The selection mask as a placed surface (alpha 255 inside) in document space,
+   * bounded to the selection extent (the `rect` records its origin/size), or
+   * `null` when empty.
+   */
+  mask(): PlacedSurface | null;
+  /** The committed path outlines, for marching-ants rendering. */
+  antsPaths(): readonly Path2D[];
+  /** True if `p` (document space) is inside the selection. Cheap 1×1 read; `false` when empty. */
+  containsPoint(p: Vec2): boolean;
+  /** Applies a committed lasso path against the mask with the given boolean op. */
+  commit(commit: SelectionCommit): void;
+  /** Replaces the selection with an alpha-bearing surface placed in document space. */
+  replaceMask(mask: PlacedSurface): void;
+  /** Selects the whole `domain` rectangle (the engine passes `content ∪ bbox`). */
+  selectAll(domain: Rect): void;
+  /**
+   * Inverts the selection within `domain` (empty → select `domain`). The domain
+   * is the bounded region the complement is taken over — the engine passes
+   * `content ∪ bbox`, the coherent analogue of legacy's bounded canvas now that
+   * the document rect is retired.
+   */
+  invert(domain: Rect): void;
+  /** Clears the selection (deselect). */
+  clear(): void;
+  /** Releases the mask surface reference. */
+  dispose(): void;
+}
+
+/** Dependencies injected by the engine. */
+export interface SelectionStateDeps {
+  backend: RasterBackend;
+  createPath2D: CreatePath2D;
+  /** Current document pixel size (the mask surface size), or `null` when no document. */
+  getDocumentSize(): { width: number; height: number } | null;
+  /** Called after every mutation (engine syncs the `hasSelection` store + overlay/ants). */
+  onChange(): void;
+}
+
+const MASK_FILL = '#ffffff';
+
+/** SVG path data for a closed rectangle in document space. */
+const rectToPathData = (r: Rect): string =>
+  `M ${r.x} ${r.y} L ${r.x + r.width} ${r.y} L ${r.x + r.width} ${r.y + r.height} L ${r.x} ${r.y + r.height} Z`;
+
+/** Builds a closed rectangle `Path2D` (document space) via the injected factory. */
+const rectPath = (createPath2D: CreatePath2D, r: Rect): Path2D => createPath2D(rectToPathData(r));
+
+/** The canvas composite op that realizes each boolean selection op on the mask. */
+const compositeForOp = (op: SelectionOp): GlobalCompositeOperation => {
+  switch (op) {
+    case 'add':
+    case 'replace':
+      return 'source-over';
+    case 'subtract':
+      return 'destination-out';
+    case 'intersect':
+      return 'destination-in';
+  }
+};
+
+/** Creates an engine-transient selection bound to the raster backend seam. */
+export const createSelectionState = (deps: SelectionStateDeps): SelectionState => {
+  const { backend, createPath2D, getDocumentSize, onChange } = deps;
+
+  let mask: RasterSurface | null = null;
+  // The mask surface's document-space bounds (its origin/extent). The mask is
+  // bounded to the selection, not the document — surface pixel (sx,sy) maps to
+  // document (maskRect.x+sx, maskRect.y+sy).
+  let maskRect: Rect | null = null;
+  let commits: SelectionCommit[] = [];
+  let selectionBounds: Rect | null = null;
+  let selected = false;
+
+  /**
+   * Ensures the mask surface exists and covers `rect` (integer bounds),
+   * preserving any existing mask pixels at their new offset when it must grow.
+   */
+  const ensureMask = (rect: Rect): RasterSurface => {
+    const want: Rect = roundOut(rect);
+    if (!mask || !maskRect) {
+      mask = backend.createSurface(Math.max(0, want.width), Math.max(0, want.height));
+      maskRect = want;
+      return mask;
+    }
+    const grown = union(maskRect, want);
+    if (
+      grown.x === maskRect.x &&
+      grown.y === maskRect.y &&
+      grown.width === maskRect.width &&
+      grown.height === maskRect.height
+    ) {
+      return mask;
+    }
+    // Grow, preserving old pixels at their new offset (snapshot before resize).
+    let snapshot: ImageData | null = null;
+    if (maskRect.width > 0 && maskRect.height > 0) {
+      snapshot = mask.ctx.getImageData(0, 0, maskRect.width, maskRect.height);
+    }
+    mask.resize(grown.width, grown.height);
+    if (snapshot) {
+      mask.ctx.putImageData(snapshot, maskRect.x - grown.x, maskRect.y - grown.y);
+    }
+    maskRect = grown;
+    return mask;
+  };
+
+  /** Resets the mask surface to exactly `rect` (cleared), for `replace`-style ops. */
+  const resetMask = (rect: Rect): RasterSurface => {
+    const want: Rect = roundOut(rect);
+    if (!mask) {
+      mask = backend.createSurface(Math.max(0, want.width), Math.max(0, want.height));
+    } else if (mask.width !== want.width || mask.height !== want.height) {
+      mask.resize(Math.max(0, want.width), Math.max(0, want.height));
+    }
+    maskRect = want;
+    clearSurface(mask);
+    return mask;
+  };
+
+  /**
+   * Fills a path into the mask under `op`'s composite mode. The mask surface is
+   * offset by `maskRect.origin`, so the (document-space) path is drawn through a
+   * translate that maps document → surface coordinates.
+   */
+  const fillPath = (surface: RasterSurface, origin: Vec2, path: Path2D, op: GlobalCompositeOperation): void => {
+    const ctx = surface.ctx;
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, -origin.x, -origin.y);
+    ctx.globalCompositeOperation = op;
+    ctx.globalAlpha = 1;
+    ctx.fillStyle = MASK_FILL;
+    ctx.fill(path);
+    ctx.restore();
+  };
+
+  const clearSurface = (surface: RasterSurface): void => {
+    const ctx = surface.ctx;
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalCompositeOperation = 'source-over';
+    ctx.clearRect(0, 0, surface.width, surface.height);
+    ctx.restore();
+  };
+
+  const clear = (): void => {
+    commits = [];
+    selectionBounds = null;
+    selected = false;
+    if (mask) {
+      clearSurface(mask);
+    }
+    onChange();
+  };
+
+  const replaceMask = (next: PlacedSurface): void => {
+    const rect = roundOut(next.rect);
+    const publishEmptyReplacement = (): void => {
+      // Replacing from a valid empty alpha result should not clear the old
+      // surface in place: clearSurface() is fallible and would run after the
+      // logical selection flags had already changed. Detach the old surface and
+      // atomically publish an empty selection instead; it is reclaimed by GC.
+      mask = null;
+      maskRect = null;
+      commits = [];
+      selectionBounds = null;
+      selected = false;
+      onChange();
+    };
+    if (isEmpty(rect) || next.surface.width <= 0 || next.surface.height <= 0) {
+      publishEmptyReplacement();
+      return;
+    }
+
+    const source = next.surface.ctx.getImageData(0, 0, next.surface.width, next.surface.height);
+    let hasAlpha = false;
+    for (let index = 3; index < source.data.length; index += 4) {
+      if (source.data[index] !== 0) {
+        hasAlpha = true;
+        break;
+      }
+    }
+    if (!hasAlpha) {
+      publishEmptyReplacement();
+      return;
+    }
+
+    const copiedData = new Uint8ClampedArray(source.data);
+    const copied =
+      typeof ImageData === 'undefined'
+        ? ({ colorSpace: source.colorSpace, data: copiedData, height: source.height, width: source.width } as ImageData)
+        : new ImageData(copiedData, source.width, source.height);
+    // Prepare every fallible replacement artifact before publishing any state.
+    // If allocation, pixel upload, or Path2D construction fails, the exact prior
+    // selection remains authoritative and the engine may safely report failure.
+    const nextMask = backend.createSurface(rect.width, rect.height);
+    nextMask.ctx.putImageData(copied, 0, 0);
+    // Trace the mask's true edge for the ants; a mask whose alpha never reaches
+    // the solid threshold still selected something (hasAlpha above), so fall
+    // back to tracing any non-zero coverage rather than showing no outline.
+    const alphaSource = { data: copiedData, height: source.height, width: source.width };
+    const outline =
+      traceMaskOutlinePath(alphaSource, rect) || traceMaskOutlinePath(alphaSource, rect, 1) || rectToPathData(rect);
+    const nextPath = createPath2D(outline);
+
+    mask = nextMask;
+    maskRect = rect;
+    commits = [{ bounds: rect, op: 'replace', path: nextPath }];
+    selectionBounds = rect;
+    selected = true;
+    onChange();
+  };
+
+  const commit = (next: SelectionCommit): void => {
+    if (!getDocumentSize()) {
+      // No active document ⇒ no selection surface to build.
+      return;
+    }
+    const bounds = isEmpty(next.bounds) ? null : roundOut(next.bounds);
+
+    if (next.op === 'replace') {
+      if (!bounds) {
+        clear();
+        return;
+      }
+      const surface = resetMask(bounds);
+      fillPath(surface, { x: maskRect!.x, y: maskRect!.y }, next.path, 'source-over');
+      commits = [next];
+      selectionBounds = bounds;
+      selected = true;
+      onChange();
+      return;
+    }
+
+    if (next.op === 'intersect' && (!selected || !selectionBounds)) {
+      // Intersecting with nothing yields nothing.
+      clear();
+      return;
+    }
+
+    // For `add` the mask may need to grow to include the new path; `subtract` /
+    // `intersect` never grow the covered region (they only remove).
+    const surface =
+      next.op === 'add' && bounds
+        ? ensureMask(bounds)
+        : ensureMask(selectionBounds ?? bounds ?? { height: 0, width: 0, x: 0, y: 0 });
+    fillPath(surface, { x: maskRect!.x, y: maskRect!.y }, next.path, compositeForOp(next.op));
+    commits.push(next);
+
+    switch (next.op) {
+      case 'add':
+        selectionBounds = selectionBounds && bounds ? union(selectionBounds, bounds) : (bounds ?? selectionBounds);
+        selected = selected || bounds !== null;
+        break;
+      case 'subtract':
+        // Bounds can only shrink; without a pixel scan we keep the (over-approx)
+        // prior bounds. `selected` stays true — see module docs.
+        break;
+      case 'intersect':
+        selectionBounds = selectionBounds && bounds ? intersect(selectionBounds, bounds) : null;
+        selected = selectionBounds !== null;
+        break;
+    }
+    onChange();
+  };
+
+  const selectAll = (domain: Rect): void => {
+    const rect = roundOut(domain);
+    const surface = resetMask(rect);
+    const ctx = surface.ctx;
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalCompositeOperation = 'source-over';
+    ctx.globalAlpha = 1;
+    ctx.fillStyle = MASK_FILL;
+    ctx.fillRect(0, 0, surface.width, surface.height);
+    ctx.restore();
+    commits = [{ bounds: rect, op: 'replace', path: rectPath(createPath2D, rect) }];
+    selectionBounds = rect;
+    selected = !isEmpty(rect);
+    onChange();
+  };
+
+  const invert = (domain: Rect): void => {
+    if (!selected || !mask || !maskRect) {
+      // Inverting an empty selection selects the whole domain.
+      selectAll(domain);
+      return;
+    }
+    const rect = roundOut(domain);
+    // The current mask, captured over the domain: draw the (offset) mask onto a
+    // domain-sized temp so the complement is taken in domain-local coordinates.
+    const temp = backend.createSurface(Math.max(0, rect.width), Math.max(0, rect.height));
+    const tctx = temp.ctx;
+    tctx.setTransform(1, 0, 0, 1, 0, 0);
+    tctx.globalCompositeOperation = 'source-over';
+    tctx.globalAlpha = 1;
+    tctx.fillStyle = MASK_FILL;
+    tctx.fillRect(0, 0, temp.width, temp.height);
+    tctx.globalCompositeOperation = 'destination-out';
+    // Punch out the current mask at its offset within the domain.
+    tctx.drawImage(mask.canvas, maskRect.x - rect.x, maskRect.y - rect.y);
+
+    const surface = resetMask(rect);
+    const ctx = surface.ctx;
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalCompositeOperation = 'source-over';
+    ctx.drawImage(temp.canvas, 0, 0);
+    ctx.restore();
+
+    // Ants: the outer domain border plus the former outlines (now holes).
+    commits = [{ bounds: rect, op: 'replace', path: rectPath(createPath2D, rect) }, ...commits];
+    selectionBounds = rect;
+    selected = true;
+    onChange();
+  };
+
+  const containsPoint = (p: Vec2): boolean => {
+    if (!selected || !mask || !maskRect) {
+      return false;
+    }
+    const x = Math.floor(p.x) - maskRect.x;
+    const y = Math.floor(p.y) - maskRect.y;
+    if (x < 0 || y < 0 || x >= mask.width || y >= mask.height) {
+      return false;
+    }
+    const pixel = mask.ctx.getImageData(x, y, 1, 1);
+    return pixel.data[3] !== undefined && pixel.data[3] > 0;
+  };
+
+  return {
+    antsPaths: () => commits.map((entry) => entry.path),
+    bounds: () => selectionBounds,
+    clear,
+    commit,
+    containsPoint,
+    dispose: () => {
+      mask = null;
+      maskRect = null;
+      commits = [];
+      selectionBounds = null;
+      selected = false;
+    },
+    hasSelection: () => selected,
+    invert,
+    mask: () => (selected && mask && maskRect ? { rect: maskRect, surface: mask } : null),
+    replaceMask,
+    selectAll,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxHitTest.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxHitTest.test.ts
new file mode 100644
index 00000000000..449bcc7ac63
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxHitTest.test.ts
@@ -0,0 +1,178 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  BBOX_HANDLE_HIT_PX,
+  bboxEquals,
+  bboxHandleAt,
+  bboxHandlePoint,
+  bboxTargetAt,
+  constrainBboxToRatio,
+  isInsideRect,
+  moveBbox,
+  resizeBbox,
+  roundBbox,
+} from './bboxHitTest';
+
+const rect = (x: number, y: number, width: number, height: number): Rect => ({ height, width, x, y });
+
+describe('bboxHandlePoint', () => {
+  it('places the eight handles on corners and edge midpoints', () => {
+    const r = rect(0, 0, 100, 80);
+    expect(bboxHandlePoint(r, 'nw')).toEqual({ x: 0, y: 0 });
+    expect(bboxHandlePoint(r, 'ne')).toEqual({ x: 100, y: 0 });
+    expect(bboxHandlePoint(r, 'se')).toEqual({ x: 100, y: 80 });
+    expect(bboxHandlePoint(r, 'sw')).toEqual({ x: 0, y: 80 });
+    expect(bboxHandlePoint(r, 'n')).toEqual({ x: 50, y: 0 });
+    expect(bboxHandlePoint(r, 'e')).toEqual({ x: 100, y: 40 });
+    expect(bboxHandlePoint(r, 's')).toEqual({ x: 50, y: 80 });
+    expect(bboxHandlePoint(r, 'w')).toEqual({ x: 0, y: 40 });
+  });
+});
+
+describe('bboxHandleAt (screen-space hit-testing)', () => {
+  it('returns the handle whose grab area contains the point', () => {
+    const screenRect = rect(0, 0, 100, 100);
+    expect(bboxHandleAt(screenRect, { x: 0, y: 0 })).toBe('nw');
+    expect(bboxHandleAt(screenRect, { x: 100, y: 100 })).toBe('se');
+    expect(bboxHandleAt(screenRect, { x: 50, y: 0 })).toBe('n');
+  });
+
+  it('tolerates a few pixels of slack around the handle', () => {
+    const screenRect = rect(0, 0, 100, 100);
+    const slack = BBOX_HANDLE_HIT_PX / 2 - 1;
+    expect(bboxHandleAt(screenRect, { x: slack, y: slack })).toBe('nw');
+    // Just outside the grab area → no handle.
+    expect(bboxHandleAt(screenRect, { x: BBOX_HANDLE_HIT_PX, y: BBOX_HANDLE_HIT_PX })).toBeNull();
+  });
+
+  it('keeps the grab area a constant screen size across zooms', () => {
+    // Same doc bbox {0,0,100,100} projected at two zooms. A point 5px from the
+    // top-left corner in SCREEN space hits 'nw' regardless of the frame's on-screen size.
+    const atZoom1 = rect(0, 0, 100, 100);
+    const atZoom4 = rect(0, 0, 400, 400);
+    expect(bboxHandleAt(atZoom1, { x: 5, y: 5 })).toBe('nw');
+    expect(bboxHandleAt(atZoom4, { x: 5, y: 5 })).toBe('nw');
+    // The midpoint of the top edge moves with zoom: 50 at zoom1, 200 at zoom4.
+    expect(bboxHandleAt(atZoom1, { x: 50, y: 0 })).toBe('n');
+    // At zoom4 the top-edge midpoint lives at 200, so 50 grabs nothing.
+    expect(bboxHandleAt(atZoom4, { x: 50, y: 0 })).toBeNull();
+    expect(bboxHandleAt(atZoom4, { x: 200, y: 0 })).toBe('n');
+  });
+
+  it('prefers a corner over an overlapping edge midpoint on a tiny frame', () => {
+    // At a 10px frame the edge midpoints sit within the corner grab areas; corners win.
+    const tiny = rect(0, 0, 10, 10);
+    expect(bboxHandleAt(tiny, { x: 0, y: 5 })).toBe('nw');
+  });
+});
+
+describe('bboxTargetAt', () => {
+  const screenRect = rect(10, 10, 100, 100);
+  it('returns a handle when over one', () => {
+    expect(bboxTargetAt(screenRect, { x: 10, y: 10 })).toBe('nw');
+  });
+  it("returns 'move' inside the frame away from handles", () => {
+    expect(bboxTargetAt(screenRect, { x: 60, y: 60 })).toBe('move');
+  });
+  it('returns null outside the frame (bbox is never deselected)', () => {
+    expect(bboxTargetAt(screenRect, { x: 200, y: 200 })).toBeNull();
+  });
+});
+
+describe('isInsideRect', () => {
+  it('includes the border', () => {
+    expect(isInsideRect(rect(0, 0, 10, 10), { x: 0, y: 10 })).toBe(true);
+    expect(isInsideRect(rect(0, 0, 10, 10), { x: 11, y: 5 })).toBe(false);
+  });
+});
+
+describe('resizeBbox — free (unconstrained)', () => {
+  const start = rect(0, 0, 100, 100);
+
+  it('grows the SE corner and snaps the moved edges to the grid', () => {
+    const out = resizeBbox({ constrain: false, dx: 10, dy: 10, grid: 8, handle: 'se', ratio: 1, snap: true, start });
+    // right = snap(110) = 112, bottom = snap(110) = 112, anchored at (0,0).
+    expect(out).toEqual(rect(0, 0, 112, 112));
+  });
+
+  it('drags the NW corner (moves origin) and snaps', () => {
+    const out = resizeBbox({ constrain: false, dx: -10, dy: -10, grid: 8, handle: 'nw', ratio: 1, snap: true, start });
+    // left = snap(-10) = -8, top = -8; right/bottom fixed at 100.
+    expect(out).toEqual(rect(-8, -8, 108, 108));
+  });
+
+  it('resizes a single edge, leaving the perpendicular axis untouched', () => {
+    const out = resizeBbox({ constrain: false, dx: 13, dy: 0, grid: 8, handle: 'e', ratio: 1, snap: true, start });
+    expect(out).toEqual(rect(0, 0, 112, 100));
+  });
+
+  it('bypasses snapping when snap is false (alt held)', () => {
+    const out = resizeBbox({ constrain: false, dx: 13, dy: 0, grid: 8, handle: 'e', ratio: 1, snap: false, start });
+    expect(out).toEqual(rect(0, 0, 113, 100));
+  });
+
+  it('clamps to a minimum of one grid cell when collapsing an edge', () => {
+    const out = resizeBbox({ constrain: false, dx: -500, dy: 0, grid: 8, handle: 'e', ratio: 1, snap: true, start });
+    expect(out).toEqual(rect(0, 0, 8, 100));
+  });
+
+  it('never goes below 1px when the grid is sub-pixel', () => {
+    const out = resizeBbox({ constrain: false, dx: -500, dy: 0, grid: 0, handle: 'e', ratio: 1, snap: false, start });
+    expect(out.width).toBe(1);
+  });
+});
+
+describe('resizeBbox — aspect constrained', () => {
+  const start = rect(0, 0, 100, 100);
+
+  it('preserves the ratio on a corner drag (anchored at the opposite corner)', () => {
+    const out = resizeBbox({ constrain: true, dx: 100, dy: 0, grid: 8, handle: 'se', ratio: 2, snap: false, start });
+    // Pointer widens to 200; ratio 2:1 → height 100. Anchor NW stays at (0,0).
+    expect(out).toEqual(rect(0, 0, 200, 100));
+  });
+
+  it('re-derives the free axis on an edge drag, keeping the center fixed', () => {
+    const out = resizeBbox({ constrain: true, dx: 100, dy: 0, grid: 8, handle: 'e', ratio: 2, snap: false, start });
+    // width 200 → height 100 (ratio 2), centered on the original vertical center (50).
+    expect(out).toEqual(rect(0, 0, 200, 100));
+  });
+
+  it('grid-aligns the driven dimension while keeping the ratio exact', () => {
+    const out = resizeBbox({ constrain: true, dx: 13, dy: 13, grid: 8, handle: 'se', ratio: 1, snap: true, start });
+    // se raw ~113 → snap width 112, height = width/ratio = 112.
+    expect(out.width).toBe(112);
+    expect(out.height).toBe(112);
+  });
+});
+
+describe('moveBbox', () => {
+  it('translates and snaps the origin to the grid', () => {
+    expect(moveBbox(rect(10, 10, 100, 100), 5, 5, 8, true)).toEqual(rect(16, 16, 100, 100));
+  });
+  it('bypasses snap when snap is false', () => {
+    expect(moveBbox(rect(10, 10, 100, 100), 5, 5, 8, false)).toEqual(rect(15, 15, 100, 100));
+  });
+});
+
+describe('constrainBboxToRatio', () => {
+  it('re-fits to the ratio around the center and snaps the width', () => {
+    const out = constrainBboxToRatio(rect(0, 0, 100, 100), 2, 8);
+    expect(out.width / out.height).toBeCloseTo(2, 5);
+    expect(out.width % 8).toBe(0);
+    // Center preserved.
+    expect(out.x + out.width / 2).toBeCloseTo(50, 5);
+    expect(out.y + out.height / 2).toBeCloseTo(50, 5);
+  });
+});
+
+describe('roundBbox / bboxEquals', () => {
+  it('rounds to integer document px with a ≥1 size', () => {
+    expect(roundBbox(rect(1.4, 2.6, 0.2, 10.5))).toEqual(rect(1, 3, 1, 11));
+  });
+  it('compares equality after rounding', () => {
+    expect(bboxEquals(rect(0, 0, 100, 100), rect(0.2, -0.1, 100.4, 99.6))).toBe(true);
+    expect(bboxEquals(rect(0, 0, 100, 100), rect(0, 0, 108, 100))).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxHitTest.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxHitTest.ts
new file mode 100644
index 00000000000..1d5066328b4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxHitTest.ts
@@ -0,0 +1,280 @@
+/**
+ * Pure geometry for the bbox (generation-frame) tool: handle layout, screen-space
+ * hit-testing, and resize/move math.
+ *
+ * The bbox is an axis-aligned document-space rectangle. Its eight resize handles
+ * (four corners + four edge midpoints) are hit-tested in SCREEN space so their
+ * grab areas stay a constant pixel size regardless of zoom — callers project the
+ * bbox to screen coordinates first. Resize math runs in DOCUMENT space: the edge
+ * opposite the grabbed handle stays fixed, the moved edge(s) follow a pointer
+ * delta, then snapping, min-size clamping, and (optionally) an aspect constraint
+ * are applied.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+import { type AspectAnchor, constrainAspect, snapToGrid } from '@workbench/canvas-engine/math/snapping';
+
+/** The eight resize handles: four corners + four edge midpoints. */
+export type BboxHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+
+/** What a pointer-down landed on: a resize handle, the interior (move), or nothing. */
+export type BboxTarget = BboxHandle | 'move';
+
+/**
+ * Handles in hit-test priority order: corners first, so at a small bbox where a
+ * corner and an adjacent edge midpoint overlap, the corner wins.
+ */
+export const BBOX_HANDLES: readonly BboxHandle[] = ['nw', 'ne', 'se', 'sw', 'n', 'e', 's', 'w'];
+
+/** Side length (screen px) of a handle's square grab area. */
+export const BBOX_HANDLE_HIT_PX = 14;
+
+const hasWest = (h: BboxHandle): boolean => h === 'nw' || h === 'w' || h === 'sw';
+const hasEast = (h: BboxHandle): boolean => h === 'ne' || h === 'e' || h === 'se';
+const hasNorth = (h: BboxHandle): boolean => h === 'nw' || h === 'n' || h === 'ne';
+const hasSouth = (h: BboxHandle): boolean => h === 'sw' || h === 's' || h === 'se';
+
+/** True for the four corner handles (two-letter ids), false for edge midpoints. */
+export const isCornerHandle = (h: BboxHandle): boolean => h.length === 2;
+
+/** The point of a handle on `rect` (works in any space — screen or document). */
+export const bboxHandlePoint = (rect: Rect, handle: BboxHandle): Vec2 => {
+  const x = hasWest(handle) ? rect.x : hasEast(handle) ? rect.x + rect.width : rect.x + rect.width / 2;
+  const y = hasNorth(handle) ? rect.y : hasSouth(handle) ? rect.y + rect.height : rect.y + rect.height / 2;
+  return { x, y };
+};
+
+/** The corner of `rect` opposite `handle` (stays fixed while `handle` is dragged). */
+const OPPOSITE_CORNER: Record<'nw' | 'ne' | 'se' | 'sw', AspectAnchor> = {
+  ne: 'sw',
+  nw: 'se',
+  se: 'nw',
+  sw: 'ne',
+};
+
+/** True when `point` is inside (or on the border of) `rect`. */
+export const isInsideRect = (rect: Rect, point: Vec2): boolean =>
+  point.x >= rect.x && point.x <= rect.x + rect.width && point.y >= rect.y && point.y <= rect.y + rect.height;
+
+/**
+ * The handle whose square grab area (side `hitSize`, screen px) contains
+ * `point`, or `null`. `screenRect` is the bbox already projected to screen space.
+ */
+export const bboxHandleAt = (
+  screenRect: Rect,
+  point: Vec2,
+  hitSize: number = BBOX_HANDLE_HIT_PX
+): BboxHandle | null => {
+  const half = hitSize / 2;
+  for (const handle of BBOX_HANDLES) {
+    const center = bboxHandlePoint(screenRect, handle);
+    if (Math.abs(point.x - center.x) <= half && Math.abs(point.y - center.y) <= half) {
+      return handle;
+    }
+  }
+  return null;
+};
+
+/**
+ * What a screen-space `point` targets on the bbox: a resize handle (grab area
+ * first), the interior (`'move'`), or `null` (outside — the bbox is never
+ * deselected).
+ */
+export const bboxTargetAt = (
+  screenRect: Rect,
+  point: Vec2,
+  hitSize: number = BBOX_HANDLE_HIT_PX
+): BboxTarget | null => {
+  const handle = bboxHandleAt(screenRect, point, hitSize);
+  if (handle) {
+    return handle;
+  }
+  return isInsideRect(screenRect, point) ? 'move' : null;
+};
+
+/** Minimum bbox side (document px): one grid cell, but never below 1px. */
+export const bboxMinSize = (grid: number): number => Math.max(1, grid);
+
+/** Translates `start` by a document-space delta, snapping the origin to `grid` unless bypassed. */
+export const moveBbox = (start: Rect, dx: number, dy: number, grid: number, snap: boolean): Rect => {
+  let x = start.x + dx;
+  let y = start.y + dy;
+  if (snap) {
+    x = snapToGrid(x, grid);
+    y = snapToGrid(y, grid);
+  }
+  return { height: start.height, width: start.width, x, y };
+};
+
+export interface ResizeBboxParams {
+  /** The bbox at gesture start. */
+  start: Rect;
+  handle: BboxHandle;
+  /** Document-space pointer delta since gesture start. */
+  dx: number;
+  dy: number;
+  /** Model grid size (document px). */
+  grid: number;
+  /** Whether to snap moved edges to the grid (false = alt-bypass). */
+  snap: boolean;
+  /** Whether to preserve `ratio` (aspect lock, or shift). */
+  constrain: boolean;
+  /** Target width / height ratio, used when `constrain`. */
+  ratio: number;
+}
+
+/** Builds a rect from a fixed anchor corner extending by `width`/`height` in the handle's directions. */
+const rectFromCorner = (fixed: Vec2, width: number, height: number, signX: number, signY: number): Rect => {
+  const x = signX >= 0 ? fixed.x : fixed.x - width;
+  const y = signY >= 0 ? fixed.y : fixed.y - height;
+  return { height, width, x, y };
+};
+
+/** Unconstrained resize: moved edges follow the delta; the opposite edge stays fixed. */
+const resizeFree = (p: ResizeBboxParams): Rect => {
+  const { dx, dy, grid, handle, snap, start } = p;
+  let left = start.x;
+  let top = start.y;
+  let right = start.x + start.width;
+  let bottom = start.y + start.height;
+
+  if (hasWest(handle)) {
+    left = snap ? snapToGrid(left + dx, grid) : left + dx;
+  }
+  if (hasEast(handle)) {
+    right = snap ? snapToGrid(right + dx, grid) : right + dx;
+  }
+  if (hasNorth(handle)) {
+    top = snap ? snapToGrid(top + dy, grid) : top + dy;
+  }
+  if (hasSouth(handle)) {
+    bottom = snap ? snapToGrid(bottom + dy, grid) : bottom + dy;
+  }
+
+  const min = bboxMinSize(grid);
+  // Clamp so the moved edge never crosses within `min` of the fixed edge.
+  if (hasWest(handle)) {
+    left = Math.min(left, right - min);
+  }
+  if (hasEast(handle)) {
+    right = Math.max(right, left + min);
+  }
+  if (hasNorth(handle)) {
+    top = Math.min(top, bottom - min);
+  }
+  if (hasSouth(handle)) {
+    bottom = Math.max(bottom, top + min);
+  }
+
+  return { height: bottom - top, width: right - left, x: left, y: top };
+};
+
+/** Aspect-constrained corner resize: anchored at the opposite corner, grid-aligning width. */
+const resizeCornerConstrained = (p: ResizeBboxParams): Rect => {
+  const { dx, dy, grid, handle, ratio, snap, start } = p;
+  const anchorCorner = OPPOSITE_CORNER[handle as 'nw' | 'ne' | 'se' | 'sw'];
+  const fixed = bboxHandlePoint(start, anchorCorner as BboxHandle);
+  const moveStart = bboxHandlePoint(start, handle);
+  const mx = moveStart.x + dx;
+  const my = moveStart.y + dy;
+  const signX = moveStart.x >= fixed.x ? 1 : -1;
+  const signY = moveStart.y >= fixed.y ? 1 : -1;
+
+  const rawW = Math.abs(mx - fixed.x);
+  const rawH = Math.abs(my - fixed.y);
+
+  // Pick the driven axis: whichever keeps the frame closest to the pointer.
+  let width = rawW / rawH >= ratio ? rawW : rawH * ratio;
+  const min = bboxMinSize(grid);
+  width = snap ? Math.max(min, snapToGrid(width, grid)) : Math.max(min, width);
+  let height = width / ratio;
+  if (height < 1) {
+    height = 1;
+    width = height * ratio;
+  }
+  return rectFromCorner(fixed, width, height, signX, signY);
+};
+
+/** Aspect-constrained edge resize: the free axis follows the delta, the other axis re-derives from `ratio`, centered. */
+const resizeEdgeConstrained = (p: ResizeBboxParams): Rect => {
+  const { dx, dy, grid, handle, ratio, snap, start } = p;
+  const min = bboxMinSize(grid);
+  const left = start.x;
+  const right = start.x + start.width;
+  const top = start.y;
+  const bottom = start.y + start.height;
+  const centerX = start.x + start.width / 2;
+  const centerY = start.y + start.height / 2;
+
+  if (handle === 'e' || handle === 'w') {
+    let width: number;
+    if (handle === 'e') {
+      const edge = snap ? snapToGrid(right + dx, grid) : right + dx;
+      width = Math.max(min, edge - left);
+    } else {
+      const edge = snap ? snapToGrid(left + dx, grid) : left + dx;
+      width = Math.max(min, right - edge);
+    }
+    const height = Math.max(1, width / ratio);
+    const x = handle === 'e' ? left : right - width;
+    return { height, width, x, y: centerY - height / 2 };
+  }
+
+  // 'n' | 's': height-driven.
+  let height: number;
+  if (handle === 's') {
+    const edge = snap ? snapToGrid(bottom + dy, grid) : bottom + dy;
+    height = Math.max(min, edge - top);
+  } else {
+    const edge = snap ? snapToGrid(top + dy, grid) : top + dy;
+    height = Math.max(min, bottom - edge);
+  }
+  const width = Math.max(1, height * ratio);
+  const y = handle === 's' ? top : bottom - height;
+  return { height, width, x: centerX - width / 2, y };
+};
+
+/**
+ * Resizes `start` for a handle drag. Applies (in order) the delta to the moved
+ * edge(s), grid snapping (unless bypassed), min-size clamping, and — when
+ * `constrain` — an aspect-ratio constraint anchored at the opposite corner
+ * (corners) or the center (edges).
+ */
+export const resizeBbox = (p: ResizeBboxParams): Rect => {
+  if (p.constrain && p.ratio > 0) {
+    return isCornerHandle(p.handle) ? resizeCornerConstrained(p) : resizeEdgeConstrained(p);
+  }
+  return resizeFree(p);
+};
+
+/** Re-fits `rect` to `ratio`, keeping its center fixed, then snaps to `grid` and clamps min size. */
+export const constrainBboxToRatio = (rect: Rect, ratio: number, grid: number): Rect => {
+  if (ratio <= 0) {
+    return rect;
+  }
+  const fitted = constrainAspect(rect, ratio, 'center');
+  const min = bboxMinSize(grid);
+  const width = Math.max(min, snapToGrid(fitted.width, grid));
+  const height = Math.max(1, width / ratio);
+  const centerX = rect.x + rect.width / 2;
+  const centerY = rect.y + rect.height / 2;
+  return { height, width, x: centerX - width / 2, y: centerY - height / 2 };
+};
+
+/** Rounds a rect's fields to integers (document px), enforcing a ≥1px size. */
+export const roundBbox = (rect: Rect): Rect => ({
+  height: Math.max(1, Math.round(rect.height)),
+  width: Math.max(1, Math.round(rect.width)),
+  x: Math.round(rect.x),
+  y: Math.round(rect.y),
+});
+
+/** True when two rects are equal after rounding to integer document px. */
+export const bboxEquals = (a: Rect, b: Rect): boolean => {
+  const ra = roundBbox(a);
+  const rb = roundBbox(b);
+  return ra.x === rb.x && ra.y === rb.y && ra.width === rb.width && ra.height === rb.height;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxTool.test.ts
new file mode 100644
index 00000000000..6987f3f2612
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxTool.test.ts
@@ -0,0 +1,232 @@
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+import type { Viewport } from '@workbench/canvas-engine/viewport';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createBboxTool } from './bboxTool';
+
+// Grid-aligned start frame (grid 8) so a zero-net-move gesture is a true no-op.
+const bbox = { height: 96, width: 96, x: 16, y: 16 };
+
+const makeDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { ...bbox },
+  height: 512,
+  layers: [],
+  selectedLayerId: null,
+  version: 2,
+  width: 512,
+});
+
+// Identity viewport: screen coordinates equal document coordinates (zoom 1, no pan),
+// so pointer inputs can use the same value for both spaces.
+const identityViewport = {
+  documentToScreen: (p: Vec2): Vec2 => ({ x: p.x, y: p.y }),
+} as unknown as Viewport;
+
+const pointer = (
+  x: number,
+  y: number,
+  opts: { shift?: boolean; alt?: boolean; buttons?: number } = {}
+): PointerInput => ({
+  buttons: opts.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: opts.alt ?? false, ctrl: false, meta: false, shift: opts.shift ?? false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+interface StructuralCommit {
+  label: string;
+  forward: CanvasProjectMutation;
+  inverse: CanvasProjectMutation;
+}
+
+interface Harness {
+  ctx: ToolContext;
+  dispatched: CanvasProjectMutation[];
+  commits: StructuralCommit[];
+  previewOf: () => CanvasDocumentContractV2['bbox'] | null;
+}
+
+const createHarness = (doc: CanvasDocumentContractV2): Harness => {
+  const dispatched: CanvasProjectMutation[] = [];
+  const commits: StructuralCommit[] = [];
+  const stores = createEngineStores();
+  const ctx: ToolContext = {
+    backend: null as never,
+    commitStructural: (label, forward, inverse) => commits.push({ forward, inverse, label }),
+    createLayerId: () => 'x',
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    dispatch: (action) => dispatched.push(action),
+    emitStrokeCommitted: vi.fn(),
+    getDocument: () => doc,
+    invalidate: vi.fn(),
+    layers: null as never,
+    notifyLayerPainted: vi.fn(),
+    setLayerTransformOverride: vi.fn(),
+    setOverlayCursor: vi.fn(),
+    stores,
+    updateCursor: vi.fn(),
+    viewport: identityViewport,
+  };
+  return { commits, ctx, dispatched, previewOf: () => stores.bboxPreview.get() };
+};
+
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerMove?.(ctx, i, [i]);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+const cancel = (t: Tool, ctx: ToolContext): void => t.onPointerCancel?.(ctx);
+
+describe('bbox tool: move gesture', () => {
+  it('previews on move then commits one setCanvasBbox on up (grid-snapped)', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+
+    down(tool, h.ctx, pointer(60, 60)); // inside the frame → move
+    move(tool, h.ctx, pointer(75, 75)); // delta (15,15) → moved
+    expect(h.previewOf()).not.toBeNull();
+
+    up(tool, h.ctx, pointer(75, 75));
+
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.commits).toHaveLength(1);
+    // origin snapped: 16+15 = 31 → grid 8 → 32.
+    expect(h.commits[0]?.forward).toEqual({ bbox: { height: 96, width: 96, x: 32, y: 32 }, type: 'setCanvasBbox' });
+    expect(h.commits[0]?.inverse).toEqual({ bbox: { ...bbox }, type: 'setCanvasBbox' });
+    // Preview cleared after commit.
+    expect(h.previewOf()).toBeNull();
+  });
+
+  it('bypasses snapping while alt is held', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    down(tool, h.ctx, pointer(60, 60, { alt: true }));
+    move(tool, h.ctx, pointer(75, 75, { alt: true }));
+    up(tool, h.ctx, pointer(75, 75, { alt: true }));
+    expect(h.commits[0]?.forward).toEqual({ bbox: { height: 96, width: 96, x: 31, y: 31 }, type: 'setCanvasBbox' });
+  });
+});
+
+describe('bbox tool: resize gesture', () => {
+  it('resizes from the SE handle and commits the grid-snapped frame', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+
+    down(tool, h.ctx, pointer(112, 112)); // SE corner handle
+    move(tool, h.ctx, pointer(130, 130)); // delta (18,18)
+    up(tool, h.ctx, pointer(130, 130));
+
+    expect(h.commits).toHaveLength(1);
+    // right/bottom = 112+18 = 130 → grid 8 → 128; anchored at (16,16).
+    expect(h.commits[0]?.forward).toEqual({ bbox: { height: 112, width: 112, x: 16, y: 16 }, type: 'setCanvasBbox' });
+  });
+
+  it('constrains the ratio while shift is held on an unlocked frame', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    // Start frame is square (96x96) → shift preserves 1:1.
+    down(tool, h.ctx, pointer(112, 112));
+    move(tool, h.ctx, pointer(150, 112, { shift: true })); // widen only, ratio 1:1 keeps square
+    up(tool, h.ctx, pointer(150, 112, { shift: true }));
+    const out = h.commits[0]?.forward as { bbox: { width: number; height: number } };
+    expect(out.bbox.width).toBe(out.bbox.height);
+  });
+});
+
+describe('bbox tool: no-op cases', () => {
+  it('commits nothing on a zero-delta gesture that returns to the origin', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    down(tool, h.ctx, pointer(60, 60));
+    move(tool, h.ctx, pointer(70, 70)); // crosses threshold → moved
+    move(tool, h.ctx, pointer(60, 60)); // back to origin
+    up(tool, h.ctx, pointer(60, 60));
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.previewOf()).toBeNull();
+  });
+
+  it('does nothing when pressing outside the frame (never deselects)', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    down(tool, h.ctx, pointer(400, 400));
+    move(tool, h.ctx, pointer(420, 420));
+    up(tool, h.ctx, pointer(420, 420));
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.previewOf()).toBeNull();
+  });
+
+  it('ignores a sub-threshold press (no drag)', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    down(tool, h.ctx, pointer(60, 60));
+    up(tool, h.ctx, pointer(61, 61));
+    expect(h.commits).toHaveLength(0);
+  });
+});
+
+describe('bbox tool: cancel', () => {
+  it('drops the preview and commits nothing on escape/cancel', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    down(tool, h.ctx, pointer(112, 112));
+    move(tool, h.ctx, pointer(130, 130));
+    expect(h.previewOf()).not.toBeNull();
+    cancel(tool, h.ctx);
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.previewOf()).toBeNull();
+  });
+});
+
+describe('bbox tool: hover cursors', () => {
+  it('reflects the hovered handle/interior in the cursor and refreshes it on change', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    // Hover (no gesture) then read the tool's CSS cursor. Frame is {16,16,96,96}.
+    const cursorAt = (x: number, y: number): string | undefined => {
+      move(tool, h.ctx, pointer(x, y));
+      return tool.cursor?.(h.ctx);
+    };
+
+    expect(cursorAt(112, 112)).toBe('nwse-resize'); // SE corner
+    expect(cursorAt(16, 112)).toBe('nesw-resize'); // SW corner
+    expect(cursorAt(16, 16)).toBe('nwse-resize'); // NW corner
+    expect(cursorAt(112, 16)).toBe('nesw-resize'); // NE corner
+    expect(cursorAt(64, 16)).toBe('ns-resize'); // N edge midpoint
+    expect(cursorAt(112, 64)).toBe('ew-resize'); // E edge midpoint
+    expect(cursorAt(64, 64)).toBe('move'); // interior
+    expect(cursorAt(400, 400)).toBe('default'); // off the frame
+
+    // The tool asked the engine to re-apply the cursor as the hover target changed.
+    expect(h.ctx.updateCursor).toHaveBeenCalled();
+  });
+
+  it('holds the grabbed handle cursor during a resize drag', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    down(tool, h.ctx, pointer(112, 112)); // grab SE corner
+    move(tool, h.ctx, pointer(130, 130)); // dragging
+    expect(tool.cursor?.(h.ctx)).toBe('nwse-resize');
+  });
+});
+
+describe('bbox tool: undo/redo contract', () => {
+  it('carries an inverse that restores the prior bbox', () => {
+    const h = createHarness(makeDoc());
+    const tool = createBboxTool();
+    down(tool, h.ctx, pointer(112, 112));
+    move(tool, h.ctx, pointer(130, 130));
+    up(tool, h.ctx, pointer(130, 130));
+    // The engine's commitStructural dispatches `inverse` on undo — restoring the original frame.
+    expect(h.commits[0]?.inverse).toEqual({ bbox: { ...bbox }, type: 'setCanvasBbox' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxTool.ts
new file mode 100644
index 00000000000..44015ceabf5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/bboxTool.ts
@@ -0,0 +1,203 @@
+/**
+ * The bbox tool: interactive editing of the generation bounding box
+ * (`document.bbox`).
+ *
+ * Interaction contract (CANVAS_PLAN Phase 4.1):
+ * - **Pointer-down** hit-tests the bbox: on a resize handle → a resize gesture;
+ *   inside the frame → a move gesture; outside → nothing (the bbox is never
+ *   "deselected").
+ * - **Pointer-move** updates an engine-transient preview rect (via
+ *   `stores.bboxPreview`) that the overlay renders — it never dispatches. Sizes
+ *   and positions snap to the model grid (`stores.bboxGrid`); hold **alt** to
+ *   bypass snapping. Corner/edge resize preserves the aspect ratio when the lock
+ *   is active (`stores.bboxOptions`); **shift** toggles the constraint on for an
+ *   unlocked frame (a locked ratio stays locked).
+ * - **Commit** (pointer-up after a real change): exactly one `commitStructural`
+ *   with the new/old bbox (`setCanvasBbox`, undoable). A zero-delta gesture
+ *   commits nothing.
+ * - **Cancel** (Esc / pointercancel): drops the preview, no dispatch.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+import type { Tool, ToolContext } from './tool';
+
+import { type BboxTarget, bboxEquals, bboxTargetAt, moveBbox, resizeBbox, roundBbox } from './bboxHitTest';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/**
+ * The CSS cursor for each bbox target: axis-aware resize arrows on the handles
+ * (opposite corners/edges share a cursor) and `move` inside the frame.
+ */
+const CURSOR_FOR_TARGET: Record<BboxTarget, string> = {
+  e: 'ew-resize',
+  move: 'move',
+  n: 'ns-resize',
+  ne: 'nesw-resize',
+  nw: 'nwse-resize',
+  s: 'ns-resize',
+  se: 'nwse-resize',
+  sw: 'nesw-resize',
+  w: 'ew-resize',
+};
+
+/** Screen-space distance (CSS px) the pointer must travel before a press becomes a drag. */
+export const BBOX_DRAG_THRESHOLD_PX = 3;
+
+interface GestureState {
+  target: BboxTarget;
+  /** The bbox at gesture start (document space). */
+  startBbox: Rect;
+  /** The pointer's document/screen position at gesture start. */
+  startDoc: Vec2;
+  startScreen: Vec2;
+  moved: boolean;
+}
+
+/** The bbox projected to screen space (axis-aligned; the view has no rotation). */
+const bboxToScreen = (ctx: ToolContext, bbox: Rect): Rect => {
+  const topLeft = ctx.viewport.documentToScreen({ x: bbox.x, y: bbox.y });
+  const bottomRight = ctx.viewport.documentToScreen({ x: bbox.x + bbox.width, y: bbox.y + bbox.height });
+  return {
+    height: bottomRight.y - topLeft.y,
+    width: bottomRight.x - topLeft.x,
+    x: topLeft.x,
+    y: topLeft.y,
+  };
+};
+
+/** Computes the next bbox for a gesture from the current pointer, applying snap/aspect rules. */
+const nextBboxFor = (
+  ctx: ToolContext,
+  state: GestureState,
+  point: Vec2,
+  modifiers: { alt: boolean; shift: boolean }
+): Rect => {
+  const grid = ctx.stores.bboxGrid.get();
+  // Snap to the model grid unless Alt bypasses it or the snap-to-grid setting is off.
+  const snap = !modifiers.alt && ctx.stores.snapToGrid.get();
+  const dx = point.x - state.startDoc.x;
+  const dy = point.y - state.startDoc.y;
+
+  if (state.target === 'move') {
+    return moveBbox(state.startBbox, dx, dy, grid, snap);
+  }
+
+  const options = ctx.stores.bboxOptions.get();
+  const constrain = options.aspectLocked || modifiers.shift;
+  // Locked → the option ratio; unlocked+shift → preserve the frame's own ratio.
+  const ratio = options.aspectLocked
+    ? options.aspectRatio
+    : state.startBbox.height > 0
+      ? state.startBbox.width / state.startBbox.height
+      : 1;
+
+  return resizeBbox({ constrain, dx, dy, grid, handle: state.target, ratio, snap, start: state.startBbox });
+};
+
+/** Creates a fresh bbox tool with its own gesture state. */
+export const createBboxTool = (): Tool => {
+  let state: GestureState | null = null;
+  // The bbox target under the pointer while idle (no gesture), driving the hover
+  // resize/move cursor. `null` = the pointer is off the frame.
+  let hoverTarget: BboxTarget | null = null;
+
+  const clearPreview = (ctx: ToolContext): void => {
+    ctx.stores.bboxPreview.set(null);
+    ctx.invalidate({ overlay: true });
+  };
+
+  return {
+    // During a drag the grabbed target's cursor holds; while idle the hovered
+    // handle/interior wins; off the frame it falls back to the default arrow.
+    cursor: () => {
+      const target = state?.target ?? hoverTarget;
+      return target ? CURSOR_FOR_TARGET[target] : 'default';
+    },
+    id: 'bbox',
+    onDeactivate: (ctx) => {
+      state = null;
+      hoverTarget = null;
+      clearPreview(ctx);
+    },
+    onPointerCancel: (ctx) => {
+      state = null;
+      clearPreview(ctx);
+    },
+    onPointerDown: (ctx, input) => {
+      if (state || (input.buttons & PRIMARY_BUTTON) === 0) {
+        return;
+      }
+      const doc = ctx.getDocument();
+      if (!doc) {
+        return;
+      }
+      const target = bboxTargetAt(bboxToScreen(ctx, doc.bbox), input.screenPoint);
+      if (!target) {
+        // Outside the frame: the bbox is never deselected, so do nothing.
+        return;
+      }
+      state = {
+        moved: false,
+        startBbox: doc.bbox,
+        startDoc: input.documentPoint,
+        startScreen: input.screenPoint,
+        target,
+      };
+    },
+    onPointerMove: (ctx, input) => {
+      if (!state) {
+        // Idle hover: reflect the handle/interior under the pointer in the cursor.
+        const doc = ctx.getDocument();
+        const target = doc ? bboxTargetAt(bboxToScreen(ctx, doc.bbox), input.screenPoint) : null;
+        if (target !== hoverTarget) {
+          hoverTarget = target;
+          ctx.updateCursor();
+        }
+        return;
+      }
+      if (!state.moved) {
+        const dxs = input.screenPoint.x - state.startScreen.x;
+        const dys = input.screenPoint.y - state.startScreen.y;
+        if (Math.hypot(dxs, dys) < BBOX_DRAG_THRESHOLD_PX) {
+          return;
+        }
+        state.moved = true;
+      }
+      const next = nextBboxFor(ctx, state, input.documentPoint, input.modifiers);
+      ctx.stores.bboxPreview.set(next);
+      ctx.invalidate({ overlay: true });
+    },
+    onPointerUp: (ctx, input) => {
+      if (!state) {
+        return;
+      }
+      const current = state;
+      state = null;
+
+      if (!current.moved) {
+        clearPreview(ctx);
+        return;
+      }
+
+      const next = roundBbox(nextBboxFor(ctx, current, input.documentPoint, input.modifiers));
+      if (bboxEquals(next, current.startBbox)) {
+        // Zero-delta gesture: nothing to commit.
+        clearPreview(ctx);
+        return;
+      }
+
+      ctx.commitStructural(
+        'Set generation frame',
+        { bbox: next, type: 'setCanvasBbox' },
+        { bbox: roundBbox(current.startBbox), type: 'setCanvasBbox' }
+      );
+      // The committed bbox now flows through the mirror; drop the preview.
+      clearPreview(ctx);
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/brushTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/brushTool.ts
new file mode 100644
index 00000000000..2d99e2ee339
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/brushTool.ts
@@ -0,0 +1,26 @@
+/**
+ * The brush tool: paints variable-width, pressure-sensitive strokes in the brush
+ * color into the target paint layer's cache surface. It is a thin binding over
+ * {@link createPaintTool} that sources its size/color/opacity/pressure from the
+ * engine's `brushOptions` store; all gesture and pixel logic lives in the shared
+ * paint tool and {@link createStrokeSession}.
+ *
+ * Each engine builds its own instance so gesture state is per-engine. Zero React,
+ * zero import-time side effects.
+ */
+
+import { PRESSURE_THINNING } from '@workbench/canvas-engine/tools/paintConstants';
+import { createPaintTool } from '@workbench/canvas-engine/tools/paintTool';
+
+import type { Tool } from './tool';
+
+/** Creates a fresh brush tool with its own gesture state. */
+export const createBrushTool = (): Tool =>
+  createPaintTool({
+    color: (ctx) => ctx.stores.brushOptions.get().color,
+    composite: 'source-over',
+    id: 'brush',
+    opacity: (ctx) => ctx.stores.brushOptions.get().opacity,
+    size: (ctx) => ctx.stores.brushOptions.get().size,
+    thinning: (ctx) => (ctx.stores.brushOptions.get().pressureSensitivity ? PRESSURE_THINNING : 0),
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/colorPickerTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/colorPickerTool.test.ts
new file mode 100644
index 00000000000..4847530b031
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/colorPickerTool.test.ts
@@ -0,0 +1,192 @@
+import type { RasterBackend, RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { createLayerCacheStore, type LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createColorPickerTool } from './colorPickerTool';
+
+/** A mutable RGBA pixel a test can change between gesture steps, injected into every `getImageData` call. */
+type MutablePixel = { current: readonly [number, number, number, number] };
+
+/** A minimal `RasterBackend` whose scratch surfaces report `pixel.current` for every `getImageData` call. */
+const createFixedPixelBackend = (pixel: MutablePixel): RasterBackend => ({
+  createImageBitmap: () => Promise.resolve({} as ImageBitmap),
+  createSurface: (width: number, height: number): RasterSurface => {
+    const canvas = { height, width } as unknown as OffscreenCanvas;
+    const ctx = {
+      clearRect: () => {},
+      drawImage: () => {},
+      getImageData: () =>
+        ({ data: Uint8ClampedArray.from(pixel.current), height: 1, width: 1 }) as unknown as ImageData,
+      restore: () => {},
+      save: () => {},
+      setTransform: () => {},
+    } as unknown as OffscreenCanvasRenderingContext2D;
+    return { canvas, ctx, height, resize: () => {}, width };
+  },
+  encodeSurface: () => Promise.resolve(new Blob()),
+});
+
+const paintLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const makeDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers: [paintLayer('paint1')],
+  selectedLayerId: 'paint1',
+  version: 2,
+  width: 100,
+});
+
+const pointer = (x: number, y: number, opts: { buttons?: number } = {}): PointerInput => ({
+  buttons: opts.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: true, ctrl: false, meta: false, shift: false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+interface Harness {
+  ctx: ToolContext;
+  pixel: MutablePixel;
+  layers: LayerCacheStore;
+  dispatched: CanvasProjectMutation[];
+  strokes: unknown[];
+  overlayCursors: unknown[];
+}
+
+const createHarness = (doc: CanvasDocumentContractV2 | null): Harness => {
+  const pixel: MutablePixel = { current: [10, 20, 30, 255] };
+  const backend = createFixedPixelBackend(pixel);
+  const layers = createLayerCacheStore(backend);
+  if (doc) {
+    layers.getOrCreate('paint1', doc.width, doc.height);
+  }
+  const stores = createEngineStores();
+  const dispatched: CanvasProjectMutation[] = [];
+  const strokes: unknown[] = [];
+  const overlayCursors: unknown[] = [];
+
+  const ctx: ToolContext = {
+    backend,
+    commitStructural: vi.fn(),
+    createLayerId: () => 'unused',
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    dispatch: (action) => dispatched.push(action),
+    emitStrokeCommitted: (event) => strokes.push(event),
+    getDocument: () => doc,
+    invalidate: vi.fn(),
+    layers,
+    notifyLayerPainted: vi.fn(),
+    setLayerTransformOverride: vi.fn(),
+    setOverlayCursor: (cursor) => overlayCursors.push(cursor),
+    stores,
+    updateCursor: vi.fn(),
+    viewport: { getZoom: () => 1 } as unknown as ToolContext['viewport'],
+  };
+
+  return { ctx, dispatched, layers, overlayCursors, pixel, strokes };
+};
+
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerMove?.(ctx, i, [i]);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+
+describe('color picker tool', () => {
+  it('samples the composited color on pointer down and writes it into brushOptions.color', () => {
+    const h = createHarness(makeDoc());
+    const tool = createColorPickerTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+
+    expect(h.ctx.stores.brushOptions.get().color).toBe('#0a141e');
+  });
+
+  it('re-samples on drag (primary button held) as the sample changes', () => {
+    const h = createHarness(makeDoc());
+    const tool = createColorPickerTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    expect(h.ctx.stores.brushOptions.get().color).toBe('#0a141e');
+
+    h.pixel.current = [40, 50, 60, 255];
+    move(tool, h.ctx, pointer(20, 20));
+    expect(h.ctx.stores.brushOptions.get().color).toBe('#28323c');
+  });
+
+  it('does not sample on move when no button is held', () => {
+    const h = createHarness(makeDoc());
+    const tool = createColorPickerTool();
+    const defaultColor = h.ctx.stores.brushOptions.get().color;
+
+    move(tool, h.ctx, pointer(10, 10, { buttons: 0 }));
+
+    expect(h.ctx.stores.brushOptions.get().color).toBe(defaultColor);
+  });
+
+  it('leaves brushOptions untouched when the point falls outside the document', () => {
+    const h = createHarness(makeDoc());
+    const tool = createColorPickerTool();
+    const defaultColor = h.ctx.stores.brushOptions.get().color;
+
+    down(tool, h.ctx, pointer(-5, 10));
+
+    expect(h.ctx.stores.brushOptions.get().color).toBe(defaultColor);
+  });
+
+  it('leaves brushOptions untouched when there is no document', () => {
+    const h = createHarness(null);
+    const tool = createColorPickerTool();
+    const defaultColor = h.ctx.stores.brushOptions.get().color;
+
+    down(tool, h.ctx, pointer(10, 10));
+
+    expect(h.ctx.stores.brushOptions.get().color).toBe(defaultColor);
+  });
+
+  it('never dispatches and never emits a committed stroke', () => {
+    const h = createHarness(makeDoc());
+    const tool = createColorPickerTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(20, 20));
+    up(tool, h.ctx, pointer(20, 20));
+
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.strokes).toHaveLength(0);
+  });
+
+  it('shows a ring cursor while active and clears it on deactivate', () => {
+    const h = createHarness(makeDoc());
+    const tool = createColorPickerTool();
+
+    move(tool, h.ctx, pointer(10, 10, { buttons: 0 }));
+    expect(h.overlayCursors.at(-1)).toMatchObject({ point: { x: 10, y: 10 } });
+
+    tool.onDeactivate?.(h.ctx);
+    expect(h.overlayCursors.at(-1)).toBeNull();
+  });
+
+  it('reports a crosshair cursor', () => {
+    const tool = createColorPickerTool();
+    expect(tool.cursor?.({} as ToolContext)).toBe('crosshair');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/colorPickerTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/colorPickerTool.ts
new file mode 100644
index 00000000000..6d0b0cf5b28
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/colorPickerTool.ts
@@ -0,0 +1,74 @@
+/**
+ * The color-picker tool: while held down (usually via the alt-hold temp-tool
+ * switch the pointer pipeline already drives — see `input/pointerPipeline.ts`),
+ * it samples the composited document color under the cursor and writes it into
+ * the brush color option, so releasing alt drops the user right back into
+ * painting with the picked color. Sampling reads the layer cache directly
+ * through {@link sampleDocumentColor} — this tool never dispatches and never
+ * touches pixels.
+ *
+ * Each engine builds its own instance so cursor-ring state is per-engine.
+ * Zero React, zero import-time side effects.
+ */
+
+import type { PointerInput } from '@workbench/canvas-engine/types';
+
+import { rgbaToHex } from '@workbench/canvas-engine/color';
+import { sampleDocumentColor } from '@workbench/canvas-engine/render/colorSample';
+
+import type { Tool, ToolContext } from './tool';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/** Fixed on-screen radius (px) for the picker's ring cursor, independent of zoom. */
+const CURSOR_SCREEN_RADIUS_PX = 8;
+
+const updateCursorRing = (ctx: ToolContext, input: PointerInput): void => {
+  const zoom = ctx.viewport.getZoom();
+  ctx.setOverlayCursor({ point: input.documentPoint, radiusDoc: CURSOR_SCREEN_RADIUS_PX / Math.max(zoom, 1e-6) });
+  ctx.invalidate({ overlay: true });
+};
+
+/** Samples the composited color under `input` and writes it into the brush color option, if pickable. */
+const pickColorAt = (ctx: ToolContext, input: PointerInput): void => {
+  const doc = ctx.getDocument();
+  if (!doc) {
+    return;
+  }
+  const sample = sampleDocumentColor(doc, ctx.layers, ctx.backend, input.documentPoint);
+  if (!sample) {
+    return;
+  }
+  const hex = rgbaToHex(sample.r, sample.g, sample.b);
+  const opts = ctx.stores.brushOptions.get();
+  if (hex !== opts.color) {
+    ctx.stores.brushOptions.set({ ...opts, color: hex });
+  }
+};
+
+/** Creates a fresh color-picker tool. */
+export const createColorPickerTool = (): Tool => ({
+  cursor: () => 'crosshair',
+  id: 'colorPicker',
+  onDeactivate: (ctx) => {
+    ctx.setOverlayCursor(null);
+    ctx.invalidate({ overlay: true });
+  },
+  onPointerDown: (ctx, input) => {
+    if ((input.buttons & PRIMARY_BUTTON) === 0) {
+      return;
+    }
+    updateCursorRing(ctx, input);
+    pickColorAt(ctx, input);
+  },
+  onPointerMove: (ctx, input) => {
+    updateCursorRing(ctx, input);
+    if (input.buttons & PRIMARY_BUTTON) {
+      pickColorAt(ctx, input);
+    }
+  },
+  onPointerUp: (ctx, input) => {
+    updateCursorRing(ctx, input);
+  },
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/eraserTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/eraserTool.ts
new file mode 100644
index 00000000000..8914ae61166
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/eraserTool.ts
@@ -0,0 +1,25 @@
+/**
+ * The eraser tool: clears pixels along a stroke by compositing the same freehand
+ * shape as the brush with `destination-out` into the target paint layer's cache.
+ * A thin binding over {@link createPaintTool} sourcing size/opacity from the
+ * engine's `eraserOptions` store; the eraser is pressure-insensitive (thinning 0)
+ * and has no color (the shape alone drives the erase).
+ *
+ * Each engine builds its own instance so gesture state is per-engine. Zero React,
+ * zero import-time side effects.
+ */
+
+import { createPaintTool } from '@workbench/canvas-engine/tools/paintTool';
+
+import type { Tool } from './tool';
+
+/** Creates a fresh eraser tool with its own gesture state. */
+export const createEraserTool = (): Tool =>
+  createPaintTool({
+    color: () => '#000000',
+    composite: 'destination-out',
+    id: 'eraser',
+    opacity: (ctx) => ctx.stores.eraserOptions.get().opacity,
+    size: (ctx) => ctx.stores.eraserOptions.get().size,
+    thinning: () => 0,
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/gradientTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/gradientTool.test.ts
new file mode 100644
index 00000000000..348b8f279dc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/gradientTool.test.ts
@@ -0,0 +1,221 @@
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+import type { Viewport } from '@workbench/canvas-engine/viewport';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { describe, expect, it, vi } from 'vitest';
+
+import { angleFromDrag, createGradientTool } from './gradientTool';
+
+const gradientLayer = (over: Partial<CanvasLayerContract> = {}): CanvasLayerContract =>
+  ({
+    blendMode: 'normal',
+    id: 'grad-existing',
+    isEnabled: true,
+    isLocked: false,
+    name: 'Gradient',
+    opacity: 1,
+    source: {
+      angle: 0,
+      kind: 'linear',
+      stops: [
+        { color: '#000000', offset: 0 },
+        { color: '#ffffff', offset: 1 },
+      ],
+      type: 'gradient',
+    },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'raster',
+    ...over,
+  }) as CanvasLayerContract;
+
+const makeDoc = (over: Partial<CanvasDocumentContractV2> = {}): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 96, width: 96, x: 0, y: 0 },
+  height: 512,
+  layers: [],
+  selectedLayerId: null,
+  version: 2,
+  width: 512,
+  ...over,
+});
+
+const identityViewport = {
+  documentToScreen: (p: Vec2): Vec2 => ({ x: p.x, y: p.y }),
+} as unknown as Viewport;
+
+const pointer = (x: number, y: number, buttons = 1): PointerInput => ({
+  buttons,
+  documentPoint: { x, y },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+interface StructuralCommit {
+  label: string;
+  forward: CanvasProjectMutation;
+  inverse: CanvasProjectMutation;
+}
+
+const createHarness = (doc: CanvasDocumentContractV2) => {
+  const dispatched: CanvasProjectMutation[] = [];
+  const commits: StructuralCommit[] = [];
+  const stores = createEngineStores();
+  let idCounter = 0;
+  const ctx: ToolContext = {
+    backend: null as never,
+    commitStructural: (label, forward, inverse) => commits.push({ forward, inverse, label }),
+    createLayerId: () => `grad-${++idCounter}`,
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    dispatch: (action) => dispatched.push(action),
+    emitStrokeCommitted: vi.fn(),
+    getDocument: () => doc,
+    invalidate: vi.fn(),
+    layers: null as never,
+    notifyLayerPainted: vi.fn(),
+    setLayerTransformOverride: vi.fn(),
+    setOverlayCursor: vi.fn(),
+    stores,
+    updateCursor: vi.fn(),
+    viewport: identityViewport,
+  };
+  return { commits, ctx, dispatched, previewOf: () => stores.gradientPreview.get(), stores };
+};
+
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerMove?.(ctx, i, [i]);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+
+describe('angleFromDrag', () => {
+  it('is 0° for a left→right drag and 90° for a top→bottom drag', () => {
+    expect(angleFromDrag({ x: 0, y: 0 }, { x: 10, y: 0 })).toBeCloseTo(0);
+    expect(angleFromDrag({ x: 0, y: 0 }, { x: 0, y: 10 })).toBeCloseTo(90);
+  });
+});
+
+describe('gradient tool: create when no gradient selected', () => {
+  it('creates a document-covering gradient layer with the drag angle', () => {
+    const h = createHarness(makeDoc());
+    const tool = createGradientTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(10, 110));
+    expect(h.previewOf()).toEqual({ end: { x: 10, y: 110 }, start: { x: 10, y: 10 } });
+
+    up(tool, h.ctx, pointer(10, 110));
+
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.commits).toHaveLength(1);
+    const forward = h.commits[0]?.forward;
+    expect(forward?.type).toBe('addCanvasLayer');
+    if (
+      forward?.type === 'addCanvasLayer' &&
+      forward.layer.type === 'raster' &&
+      forward.layer.source.type === 'gradient'
+    ) {
+      expect(forward.layer.source.angle).toBeCloseTo(90);
+      expect(forward.layer.source.kind).toBe('linear');
+      expect(forward.layer.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+    } else {
+      throw new Error('expected a gradient layer');
+    }
+    expect(h.commits[0]?.inverse).toEqual({ ids: ['grad-1'], type: 'removeCanvasLayers' });
+    expect(h.previewOf()).toBeNull();
+  });
+});
+
+describe('gradient tool: edit selected gradient layer', () => {
+  it('commits ONE updateCanvasLayerSource with the new angle (kind/stops preserved)', () => {
+    const layer = gradientLayer();
+    const doc = makeDoc({ layers: [layer], selectedLayerId: 'grad-existing' });
+    const h = createHarness(doc);
+    const tool = createGradientTool();
+
+    down(tool, h.ctx, pointer(0, 0));
+    move(tool, h.ctx, pointer(100, 0));
+    up(tool, h.ctx, pointer(100, 0));
+
+    expect(h.commits).toHaveLength(1);
+    const forward = h.commits[0]?.forward;
+    const inverse = h.commits[0]?.inverse;
+    expect(forward?.type).toBe('updateCanvasLayerSource');
+    if (forward?.type === 'updateCanvasLayerSource' && forward.source.type === 'gradient') {
+      expect(forward.id).toBe('grad-existing');
+      expect(forward.source.angle).toBeCloseTo(0);
+      expect(forward.source.kind).toBe('linear');
+      expect(forward.source.stops).toHaveLength(2);
+    } else {
+      throw new Error('expected an updateCanvasLayerSource gradient edit');
+    }
+    // Inverse restores the exact original source object.
+    if (inverse?.type === 'updateCanvasLayerSource' && layer.type === 'raster') {
+      expect(inverse.source).toBe(layer.source);
+    } else {
+      throw new Error('expected an inverse source restore');
+    }
+  });
+
+  it('is a no-op when the selected gradient layer is locked', () => {
+    const layer = gradientLayer({ isLocked: true });
+    const doc = makeDoc({ layers: [layer], selectedLayerId: 'grad-existing' });
+    const h = createHarness(doc);
+    const tool = createGradientTool();
+
+    down(tool, h.ctx, pointer(0, 0));
+    move(tool, h.ctx, pointer(100, 0));
+    up(tool, h.ctx, pointer(100, 0));
+
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.previewOf()).toBeNull();
+  });
+
+  it('is a no-op when the selected gradient layer is radial (angle has no visual effect)', () => {
+    const layer = gradientLayer({
+      source: {
+        angle: 0,
+        kind: 'radial',
+        stops: [
+          { color: '#000000', offset: 0 },
+          { color: '#ffffff', offset: 1 },
+        ],
+        type: 'gradient',
+      },
+    } as Partial<CanvasLayerContract>);
+    const doc = makeDoc({ layers: [layer], selectedLayerId: 'grad-existing' });
+    const h = createHarness(doc);
+    const tool = createGradientTool();
+
+    down(tool, h.ctx, pointer(0, 0));
+    move(tool, h.ctx, pointer(100, 0));
+    up(tool, h.ctx, pointer(100, 0));
+
+    // A radial gradient ignores `angle`, so dragging on one would only ever
+    // produce an angle-only, visually-inert commit. Skipped entirely: no
+    // commit, no dispatch, no dangling preview.
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.previewOf()).toBeNull();
+  });
+
+  it('creates a new gradient when the selected layer is not a gradient', () => {
+    const paint = gradientLayer({
+      id: 'paint-1',
+      source: { bitmap: null, type: 'paint' },
+    } as Partial<CanvasLayerContract>);
+    const doc = makeDoc({ layers: [paint], selectedLayerId: 'paint-1' });
+    const h = createHarness(doc);
+    const tool = createGradientTool();
+
+    down(tool, h.ctx, pointer(0, 0));
+    move(tool, h.ctx, pointer(50, 50));
+    up(tool, h.ctx, pointer(50, 50));
+
+    expect(h.commits[0]?.forward.type).toBe('addCanvasLayer');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/gradientTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/gradientTool.ts
new file mode 100644
index 00000000000..109ce6201fa
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/gradientTool.ts
@@ -0,0 +1,174 @@
+/**
+ * The gradient tool: drag to set a gradient's ANGLE from the drag vector.
+ *
+ * Interaction contract (CANVAS_PLAN Phase 6.1):
+ * - **Pointer-down** (primary button) starts a gesture at the press point.
+ * - **Pointer-move** (past a small threshold) updates a transient overlay
+ *   preview (`stores.gradientPreview`, the drag vector) — it never dispatches.
+ * - **Commit** (pointer-up after a real drag): exactly ONE commit.
+ *   - A gradient layer is selected (unlocked + visible) → one `commitStructural`
+ *     with `updateCanvasLayerSource` (new/old angle; kind + stops preserved).
+ *   - Otherwise → create a new bbox-sized gradient layer (angle from the drag,
+ *     kind + stops from the tool options, extent = the generation frame) via
+ *     `addCanvasLayer`.
+ *   - A selected gradient layer that is locked/hidden is a no-op (don't silently
+ *     spawn a new layer over it), mirroring the paint tool's locked-target rule.
+ * - **Cancel** (Esc / pointercancel): drops the preview, no dispatch.
+ *
+ * Gradient layers are content-sized via the contract's explicit `width`/`height`
+ * extent — set at creation (bbox-sized) and preserved across angle edits — so
+ * only the ANGLE is derived from the drag, not a bounding box. The selection
+ * mask does NOT constrain gradient layers (parametric, not pixels).
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasLayerSourceContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import type { Tool, ToolContext } from './tool';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/** Screen-space distance (CSS px) the pointer must travel before a press becomes a drag. */
+export const GRADIENT_DRAG_THRESHOLD_PX = 3;
+
+interface GestureState {
+  startDoc: Vec2;
+  startScreen: Vec2;
+  moved: boolean;
+}
+
+/** Degrees of the vector from `start` to `end` (0° = left→right). */
+export const angleFromDrag = (start: Vec2, end: Vec2): number =>
+  (Math.atan2(end.y - start.y, end.x - start.x) * 180) / Math.PI;
+
+/** Creates a fresh gradient tool with its own gesture state. */
+export const createGradientTool = (): Tool => {
+  let state: GestureState | null = null;
+
+  const clearPreview = (ctx: ToolContext): void => {
+    ctx.stores.gradientPreview.set(null);
+    ctx.invalidate({ overlay: true });
+  };
+
+  return {
+    cursor: () => 'crosshair',
+    id: 'gradient',
+    onDeactivate: (ctx) => {
+      state = null;
+      clearPreview(ctx);
+    },
+    onKeyCommand: (ctx, command) => {
+      if (command === 'cancel' && state) {
+        state = null;
+        clearPreview(ctx);
+      }
+    },
+    onPointerCancel: (ctx) => {
+      state = null;
+      clearPreview(ctx);
+    },
+    onPointerDown: (ctx, input) => {
+      if (state || (input.buttons & PRIMARY_BUTTON) === 0) {
+        return;
+      }
+      if (!ctx.getDocument()) {
+        return;
+      }
+      state = { moved: false, startDoc: input.documentPoint, startScreen: input.screenPoint };
+    },
+    onPointerMove: (ctx, input) => {
+      if (!state) {
+        return;
+      }
+      if (!state.moved) {
+        const dxs = input.screenPoint.x - state.startScreen.x;
+        const dys = input.screenPoint.y - state.startScreen.y;
+        if (Math.hypot(dxs, dys) < GRADIENT_DRAG_THRESHOLD_PX) {
+          return;
+        }
+        state.moved = true;
+      }
+      ctx.stores.gradientPreview.set({ end: input.documentPoint, start: state.startDoc });
+      ctx.invalidate({ overlay: true });
+    },
+    onPointerUp: (ctx, input) => {
+      if (!state) {
+        return;
+      }
+      const current = state;
+      state = null;
+
+      if (!current.moved) {
+        clearPreview(ctx);
+        return;
+      }
+
+      const doc = ctx.getDocument();
+      if (!doc) {
+        clearPreview(ctx);
+        return;
+      }
+      const angle = angleFromDrag(current.startDoc, input.documentPoint);
+      const selected = doc.selectedLayerId ? doc.layers.find((layer) => layer.id === doc.selectedLayerId) : undefined;
+
+      if (selected && selected.type === 'raster' && selected.source.type === 'gradient') {
+        // Edit the selected gradient layer — unless it's locked/hidden (no-op).
+        if (selected.isLocked || !selected.isEnabled) {
+          clearPreview(ctx);
+          return;
+        }
+        const old = selected.source;
+        // A radial gradient's rendering ignores `angle` entirely — dragging on
+        // one would only ever change that inert field, producing a commit with
+        // zero visual effect and a useless history entry. Skip it.
+        if (old.kind === 'radial') {
+          clearPreview(ctx);
+          return;
+        }
+        const forward: CanvasProjectMutation = {
+          id: selected.id,
+          source: { ...old, angle },
+          type: 'updateCanvasLayerSource',
+        };
+        const inverse: CanvasProjectMutation = { id: selected.id, source: old, type: 'updateCanvasLayerSource' };
+        ctx.commitStructural('Edit gradient', forward, inverse);
+        clearPreview(ctx);
+        return;
+      }
+
+      // Create a new bbox-sized gradient layer. The document rect is retired, so
+      // creation covers the generation frame (bbox): the extent is the bbox size,
+      // positioned at the bbox origin via the layer transform. Angle-drag edits on
+      // an existing gradient preserve its extent (the `...old` spread above).
+      const options = ctx.stores.gradientOptions.get();
+      const layerId = ctx.createLayerId();
+      const source: CanvasLayerSourceContract = {
+        angle,
+        height: doc.bbox.height,
+        kind: options.kind,
+        stops: options.stops.map((stop) => ({ ...stop })),
+        type: 'gradient',
+        width: doc.bbox.width,
+      };
+      const layer: CanvasRasterLayerContractV2 = {
+        blendMode: 'normal',
+        id: layerId,
+        isEnabled: true,
+        isLocked: false,
+        name: `Gradient ${doc.layers.length + 1}`,
+        opacity: 1,
+        source,
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: doc.bbox.x, y: doc.bbox.y },
+        type: 'raster',
+      };
+      const forward: CanvasProjectMutation = { index: 0, layer, type: 'addCanvasLayer' };
+      const inverse: CanvasProjectMutation = { ids: [layerId], type: 'removeCanvasLayers' };
+      ctx.commitStructural('Add gradient', forward, inverse);
+      clearPreview(ctx);
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/lassoTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/lassoTool.test.ts
new file mode 100644
index 00000000000..4940cfa7ccd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/lassoTool.test.ts
@@ -0,0 +1,138 @@
+import type { SelectionCommit } from '@workbench/canvas-engine/selection/selectionState';
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput } from '@workbench/canvas-engine/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { createLassoTool, lassoOpFor } from '@workbench/canvas-engine/tools/lassoTool';
+import { describe, expect, it, vi } from 'vitest';
+
+const pointer = (
+  x: number,
+  y: number,
+  opts: { shift?: boolean; alt?: boolean; buttons?: number } = {}
+): PointerInput => ({
+  buttons: opts.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: opts.alt ?? false, ctrl: false, meta: false, shift: opts.shift ?? false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+const createHarness = () => {
+  const stores = createEngineStores();
+  const commits: SelectionCommit[] = [];
+  const dispatched: WorkbenchAction[] = [];
+  const ctx = {
+    commitSelection: (commit: SelectionCommit) => commits.push(commit),
+    createPath2D: (d?: string) => ({ d }) as unknown as Path2D,
+    dispatch: (action: WorkbenchAction) => dispatched.push(action),
+    invalidate: vi.fn(),
+    stores,
+  } as unknown as ToolContext;
+  return { commits, ctx, dispatched, stores };
+};
+
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerMove?.(ctx, i, [i]);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+
+describe('lassoOpFor', () => {
+  it('maps modifiers to ops, falling back to the persistent mode', () => {
+    const none = { alt: false, ctrl: false, meta: false, shift: false };
+    expect(lassoOpFor(none, 'replace')).toBe('replace');
+    expect(lassoOpFor(none, 'add')).toBe('add');
+    expect(lassoOpFor({ ...none, shift: true }, 'replace')).toBe('add');
+    expect(lassoOpFor({ ...none, alt: true }, 'replace')).toBe('subtract');
+    expect(lassoOpFor({ ...none, alt: true, shift: true }, 'replace')).toBe('intersect');
+  });
+});
+
+describe('lassoTool: drag → commit', () => {
+  const drag = (tool: Tool, ctx: ToolContext, upOpts: { shift?: boolean; alt?: boolean } = {}): void => {
+    down(tool, ctx, pointer(0, 0));
+    move(tool, ctx, pointer(20, 0));
+    move(tool, ctx, pointer(20, 20));
+    up(tool, ctx, pointer(0, 20, upOpts));
+  };
+
+  it('commits a replace by default and publishes/clears the live preview', () => {
+    const tool = createLassoTool();
+    const { commits, ctx, stores } = createHarness();
+
+    down(tool, ctx, pointer(0, 0));
+    move(tool, ctx, pointer(20, 0));
+    expect(stores.lassoPreview.get()).not.toBeNull();
+
+    move(tool, ctx, pointer(20, 20));
+    up(tool, ctx, pointer(0, 20));
+
+    expect(commits).toHaveLength(1);
+    expect(commits[0]!.op).toBe('replace');
+    expect(commits[0]!.bounds).toEqual({ height: 20, width: 20, x: 0, y: 0 });
+    // Preview cleared on commit.
+    expect(stores.lassoPreview.get()).toBeNull();
+  });
+
+  it('resolves each modifier op', () => {
+    for (const [mods, op] of [
+      [{ shift: true }, 'add'],
+      [{ alt: true }, 'subtract'],
+      [{ shift: true, alt: true }, 'intersect'],
+    ] as const) {
+      const tool = createLassoTool();
+      const { commits, ctx } = createHarness();
+      drag(tool, ctx, mods);
+      expect(commits[0]!.op).toBe(op);
+    }
+  });
+
+  it('uses the persistent lasso op mode when no modifier is held', () => {
+    const tool = createLassoTool();
+    const { commits, ctx, stores } = createHarness();
+    stores.lassoOptions.set({ mode: 'subtract' });
+    drag(tool, ctx);
+    expect(commits[0]!.op).toBe('subtract');
+  });
+
+  it('never dispatches to the reducer (selection is transient)', () => {
+    const tool = createLassoTool();
+    const { ctx, dispatched } = createHarness();
+    drag(tool, ctx);
+    expect(dispatched).toHaveLength(0);
+  });
+});
+
+describe('lassoTool: cancel + guards', () => {
+  it('Escape/pointercancel drops the in-progress path without committing', () => {
+    const tool = createLassoTool();
+    const { commits, ctx, stores } = createHarness();
+    down(tool, ctx, pointer(0, 0));
+    move(tool, ctx, pointer(20, 0));
+    move(tool, ctx, pointer(20, 20));
+    tool.onPointerCancel?.(ctx);
+    expect(commits).toHaveLength(0);
+    expect(stores.lassoPreview.get()).toBeNull();
+  });
+
+  it('a click (too few points) commits nothing', () => {
+    const tool = createLassoTool();
+    const { commits, ctx } = createHarness();
+    down(tool, ctx, pointer(5, 5));
+    up(tool, ctx, pointer(5, 5));
+    expect(commits).toHaveLength(0);
+  });
+
+  it('decimates points closer than the minimum distance', () => {
+    const tool = createLassoTool();
+    const { ctx, stores } = createHarness();
+    down(tool, ctx, pointer(0, 0));
+    // These are all within 1px of each other → decimated away.
+    move(tool, ctx, pointer(0.5, 0));
+    move(tool, ctx, pointer(1, 0));
+    const preview = stores.lassoPreview.get();
+    expect(preview).toHaveLength(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/lassoTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/lassoTool.ts
new file mode 100644
index 00000000000..48322c750fa
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/lassoTool.ts
@@ -0,0 +1,123 @@
+/**
+ * The lasso tool: freehand pixel-selection.
+ *
+ * A primary-button drag accumulates document-space polygon points (coalesced by
+ * the pipeline, then distance-decimated here like the brush thins its input); a
+ * live dashed preview of the in-progress path is published to the engine's
+ * `lassoPreview` store (a transient channel — no dispatch, no reducer traffic).
+ * Pointer-up closes the path and commits it to the engine's selection through
+ * {@link ToolContext.commitSelection}, with the boolean op resolved from the
+ * modifiers (shift = add, alt = subtract, shift+alt = intersect) or, with none
+ * held, the persistent op mode from `lassoOptions`. Escape / pointercancel drops
+ * the in-progress path.
+ *
+ * Selection edits are transient interaction state: they are NOT dispatches and
+ * NOT recorded on the engine's undo history this phase (legacy parity — selection
+ * changes aren't undoable). Zero React, zero import-time side effects.
+ */
+
+import type { PointerInput, SelectionOp, Vec2 } from '@workbench/canvas-engine/types';
+
+import { polygonBounds, polygonToSvgPath } from '@workbench/canvas-engine/freehand';
+
+import type { Tool, ToolContext } from './tool';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/** Minimum document-space gap between stored polygon points (input decimation). */
+export const LASSO_MIN_POINT_DISTANCE = 2;
+
+/** Fewest distinct points that make a fillable selection polygon. */
+const MIN_POLYGON_POINTS = 3;
+
+/** Resolves the boolean op for a commit: modifiers win, else the persistent mode. */
+export const lassoOpFor = (modifiers: PointerInput['modifiers'], mode: SelectionOp): SelectionOp => {
+  if (modifiers.shift && modifiers.alt) {
+    return 'intersect';
+  }
+  if (modifiers.shift) {
+    return 'add';
+  }
+  if (modifiers.alt) {
+    return 'subtract';
+  }
+  return mode;
+};
+
+const distance = (a: Vec2, b: Vec2): number => Math.hypot(a.x - b.x, a.y - b.y);
+
+/** Creates a fresh lasso tool with its own per-gesture point buffer. */
+export const createLassoTool = (): Tool => {
+  let points: Vec2[] = [];
+  let active = false;
+
+  const reset = (): void => {
+    points = [];
+    active = false;
+  };
+
+  /** Appends a point if it is far enough from the last stored one. */
+  const pushPoint = (p: Vec2): void => {
+    const last = points[points.length - 1];
+    if (!last || distance(last, p) >= LASSO_MIN_POINT_DISTANCE) {
+      points.push({ x: p.x, y: p.y });
+    }
+  };
+
+  const publishPreview = (ctx: ToolContext): void => {
+    ctx.stores.lassoPreview.set(points.length > 0 ? points.slice() : null);
+    ctx.invalidate({ overlay: true });
+  };
+
+  const clearPreview = (ctx: ToolContext): void => {
+    ctx.stores.lassoPreview.set(null);
+    ctx.invalidate({ overlay: true });
+  };
+
+  return {
+    cursor: () => 'crosshair',
+    id: 'lasso',
+    onDeactivate: (ctx) => {
+      reset();
+      clearPreview(ctx);
+    },
+    onPointerCancel: (ctx) => {
+      reset();
+      clearPreview(ctx);
+    },
+    onPointerDown: (ctx, input) => {
+      if (active || (input.buttons & PRIMARY_BUTTON) === 0) {
+        return;
+      }
+      active = true;
+      points = [{ x: input.documentPoint.x, y: input.documentPoint.y }];
+      publishPreview(ctx);
+    },
+    onPointerMove: (ctx, input, batch) => {
+      if (!active) {
+        return;
+      }
+      for (const sample of batch) {
+        pushPoint(sample.documentPoint);
+      }
+      publishPreview(ctx);
+    },
+    onPointerUp: (ctx, input) => {
+      if (!active) {
+        return;
+      }
+      pushPoint(input.documentPoint);
+      const polygon = points.slice();
+      reset();
+      clearPreview(ctx);
+      if (polygon.length < MIN_POLYGON_POINTS || !ctx.commitSelection) {
+        return;
+      }
+      const path = ctx.createPath2D(polygonToSvgPath(polygon));
+      const bounds = polygonBounds(polygon);
+      const op = lassoOpFor(input.modifiers, ctx.stores.lassoOptions.get().mode);
+      ctx.commitSelection({ bounds, op, path });
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveHitTest.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveHitTest.test.ts
new file mode 100644
index 00000000000..75403560c83
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveHitTest.test.ts
@@ -0,0 +1,348 @@
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { estimateTextExtent } from '@workbench/canvas-engine/render/rasterizers/textRasterizer';
+import { describe, expect, it } from 'vitest';
+
+import { hitTestLayer, hittableLayerSize, layerOutlineCorners, topLayerAt } from './moveHitTest';
+
+const shapeLayer = (id: string, width: number, height: number): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { fill: '#ffffff', height, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const gradientLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { angle: 0, kind: 'linear', stops: [], type: 'gradient' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const textLayer = (id: string, content: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: {
+    align: 'left',
+    color: '#000000',
+    content,
+    fontFamily: 'sans',
+    fontSize: 20,
+    fontWeight: 400,
+    lineHeight: 1.2,
+    type: 'text',
+  },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const imageLayer = (
+  id: string,
+  opts: {
+    x?: number;
+    y?: number;
+    scaleX?: number;
+    scaleY?: number;
+    rotation?: number;
+    width?: number;
+    height?: number;
+    isEnabled?: boolean;
+    isLocked?: boolean;
+  } = {}
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: opts.isEnabled ?? true,
+  isLocked: opts.isLocked ?? false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: opts.height ?? 20, imageName: id, width: opts.width ?? 20 }, type: 'image' },
+  transform: {
+    rotation: opts.rotation ?? 0,
+    scaleX: opts.scaleX ?? 1,
+    scaleY: opts.scaleY ?? 1,
+    x: opts.x ?? 0,
+    y: opts.y ?? 0,
+  },
+  type: 'raster',
+});
+
+/** A control layer (composite group rank 1) backed by an image source. */
+const controlLayer = (id: string, opts: { width?: number; height?: number } = {}): CanvasLayerContract => ({
+  adapter: {
+    beginEndStepPct: [0, 1],
+    controlMode: 'balanced',
+    kind: 'controlnet',
+    model: null,
+    weight: 1,
+  },
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: opts.height ?? 20, imageName: id, width: opts.width ?? 20 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: false,
+});
+
+const paintLayer = (
+  id: string,
+  bitmap?: { width: number; height: number; offset?: { x: number; y: number } }
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: bitmap
+    ? {
+        bitmap: { height: bitmap.height, imageName: `${id}-bmp`, width: bitmap.width },
+        offset: bitmap.offset,
+        type: 'paint',
+      }
+    : { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const maskLayer = (
+  id: string,
+  bitmap?: { width: number; height: number; offset?: { x: number; y: number } }
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: {
+    bitmap: bitmap ? { height: bitmap.height, imageName: `${id}-mask`, width: bitmap.width } : null,
+    fill: { color: '#ff0000', style: 'solid' },
+    ...(bitmap?.offset ? { offset: bitmap.offset } : {}),
+  },
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+const doc = (layers: CanvasLayerContract[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 100,
+});
+
+describe('hittableLayerSize', () => {
+  it('returns native size for image layers', () => {
+    expect(hittableLayerSize(imageLayer('a', { width: 30, height: 40 }), doc([]))).toEqual({ height: 40, width: 30 });
+  });
+
+  it('returns null for an EMPTY paint layer (content-sized: no bitmap ⇒ not hit-testable)', () => {
+    expect(hittableLayerSize(paintLayer('a'), doc([]))).toBeNull();
+  });
+
+  it('returns the persisted bitmap size for a paint layer with content', () => {
+    expect(hittableLayerSize(paintLayer('a', { height: 40, width: 60 }), doc([]))).toEqual({ height: 40, width: 60 });
+  });
+
+  it('returns null for an EMPTY (bitmap-less) mask, but the bitmap size for a painted mask (masks are movable)', () => {
+    expect(hittableLayerSize(maskLayer('m'), doc([]))).toBeNull();
+    expect(hittableLayerSize(maskLayer('m', { height: 24, width: 32 }), doc([]))).toEqual({ height: 24, width: 32 });
+  });
+
+  it('returns the shape extent for shape layers (param for parametric)', () => {
+    expect(hittableLayerSize(shapeLayer('s', 30, 40), doc([]))).toEqual({ height: 40, width: 30 });
+  });
+
+  it('returns document size for gradient layers', () => {
+    expect(hittableLayerSize(gradientLayer('g'), doc([]))).toEqual({ height: 100, width: 100 });
+  });
+
+  it('returns the estimated text extent for text layers', () => {
+    const layer = textLayer('t', 'hi');
+    expect(hittableLayerSize(layer, doc([]))).toEqual(
+      estimateTextExtent(layer.type === 'raster' && layer.source.type === 'text' ? layer.source : (null as never))
+    );
+  });
+});
+
+describe('hitTestLayer: parametric layers are now hit-testable', () => {
+  it('hits inside a shape layer and misses outside', () => {
+    const layer = shapeLayer('s', 30, 40);
+    const d = doc([layer]);
+    expect(hitTestLayer(layer, d, { x: 15, y: 20 })).toBe(true);
+    expect(hitTestLayer(layer, d, { x: 35, y: 20 })).toBe(false);
+  });
+});
+
+describe('hitTestLayer', () => {
+  it('hits inside the transformed bounds and misses outside', () => {
+    const layer = imageLayer('a', { x: 10, y: 10, width: 20, height: 20 });
+    const d = doc([layer]);
+    expect(hitTestLayer(layer, d, { x: 15, y: 15 })).toBe(true);
+    expect(hitTestLayer(layer, d, { x: 9, y: 15 })).toBe(false);
+    expect(hitTestLayer(layer, d, { x: 31, y: 15 })).toBe(false);
+  });
+
+  it('accounts for scale', () => {
+    // 20x20 image scaled x2 → covers [0,40]x[0,40] in document space.
+    const layer = imageLayer('a', { scaleX: 2, scaleY: 2, width: 20, height: 20 });
+    const d = doc([layer]);
+    expect(hitTestLayer(layer, d, { x: 39, y: 39 })).toBe(true);
+    expect(hitTestLayer(layer, d, { x: 41, y: 41 })).toBe(false);
+  });
+
+  it('accounts for rotation (90° about origin)', () => {
+    // Rotate a 20x40 image 90° clockwise about its origin: local (0,0)->(0,0),
+    // local (0,40) -> document (-40, 0). Document point (-10, 5) maps to a local
+    // point inside [0,20]x[0,40].
+    const layer = imageLayer('a', { rotation: Math.PI / 2, width: 20, height: 40 });
+    const d = doc([layer]);
+    expect(hitTestLayer(layer, d, { x: -10, y: 5 })).toBe(true);
+    expect(hitTestLayer(layer, d, { x: 10, y: 5 })).toBe(false);
+  });
+
+  it('never hits a mask layer (no source bounds)', () => {
+    const layer = maskLayer('m');
+    expect(hitTestLayer(layer, doc([layer]), { x: 5, y: 5 })).toBe(false);
+  });
+});
+
+describe('topLayerAt', () => {
+  it('returns the top-most (index 0) layer that passes the predicate and contains the point', () => {
+    const top = imageLayer('top', { width: 50, height: 50 });
+    const bottom = imageLayer('bottom', { width: 50, height: 50 });
+    const d = doc([top, bottom]);
+    expect(topLayerAt(d, { x: 10, y: 10 }, () => true)?.id).toBe('top');
+  });
+
+  it('skips layers the predicate rejects (e.g. locked/hidden)', () => {
+    const top = imageLayer('top', { width: 50, height: 50, isLocked: true });
+    const bottom = imageLayer('bottom', { width: 50, height: 50 });
+    const d = doc([top, bottom]);
+    // Drag predicate rejects locked → falls through to the bottom layer.
+    expect(topLayerAt(d, { x: 10, y: 10 }, (l) => !l.isLocked)?.id).toBe('bottom');
+  });
+
+  it('returns null on empty space', () => {
+    const layer = imageLayer('a', { x: 0, y: 0, width: 10, height: 10 });
+    expect(topLayerAt(doc([layer]), { x: 80, y: 80 }, () => true)).toBeNull();
+  });
+});
+
+describe('topLayerAt: composite-group ordering (batch finding N1)', () => {
+  // The compositor draws by group rank (raster < control < regional < inpaint
+  // mask), NOT by raw array index, so the hit-test must agree: a layer in a higher
+  // group wins the hit over a lower-group layer that sits EARLIER in the array.
+  it('a control layer wins the hit over an overlapping raster placed earlier in the array', () => {
+    const raster = imageLayer('raster'); // global index 0 — would win under naive array order
+    const control = controlLayer('control'); // index 1, but composites above the raster
+    const d = doc([raster, control]);
+    expect(topLayerAt(d, { x: 10, y: 10 }, () => true)?.id).toBe('control');
+  });
+
+  it('an inpaint mask (top group) wins over control and raster below it', () => {
+    const raster = imageLayer('raster');
+    const control = controlLayer('control');
+    const mask = maskLayer('mask', { width: 20, height: 20 });
+    // Array order deliberately does NOT match composite order.
+    const d = doc([raster, mask, control]);
+    expect(topLayerAt(d, { x: 10, y: 10 }, () => true)?.id).toBe('mask');
+  });
+
+  it('within a group, array order still decides (index 0 is top-most within the group)', () => {
+    const top = controlLayer('top');
+    const bottom = controlLayer('bottom');
+    const raster = imageLayer('raster');
+    const d = doc([top, bottom, raster]);
+    expect(topLayerAt(d, { x: 10, y: 10 }, () => true)?.id).toBe('top');
+  });
+
+  it('falls through to a lower group when the predicate rejects the higher one', () => {
+    const raster = imageLayer('raster');
+    const control = controlLayer('control');
+    const d = doc([raster, control]);
+    // e.g. move-tool auto-select excluding controls → the raster below is grabbed.
+    expect(topLayerAt(d, { x: 10, y: 10 }, (l) => l.type === 'raster')?.id).toBe('raster');
+  });
+});
+
+describe('layerOutlineCorners', () => {
+  it('returns the four document-space corners of the rendered rect', () => {
+    const layer = imageLayer('a', { x: 5, y: 5, width: 10, height: 10 });
+    const corners = layerOutlineCorners(layer, doc([layer]));
+    expect(corners).toEqual([
+      { x: 5, y: 5 },
+      { x: 15, y: 5 },
+      { x: 15, y: 15 },
+      { x: 5, y: 15 },
+    ]);
+  });
+
+  it('applies an x/y override without mutating the layer transform', () => {
+    const layer = imageLayer('a', { x: 5, y: 5, width: 10, height: 10 });
+    const corners = layerOutlineCorners(layer, doc([layer]), { x: 25, y: 30 });
+    expect(corners?.[0]).toEqual({ x: 25, y: 30 });
+    expect(corners?.[2]).toEqual({ x: 35, y: 40 });
+    expect(layer.transform.x).toBe(5);
+  });
+
+  it('returns null for a mask layer', () => {
+    const layer = maskLayer('m');
+    expect(layerOutlineCorners(layer, doc([layer]))).toBeNull();
+  });
+});
+
+describe('live cache rect (freshly-painted, not-yet-flushed content)', () => {
+  it('hitTestLayer misses an empty paint layer with no live rect', () => {
+    const layer = paintLayer('p'); // bitmap: null → empty persisted content
+    expect(hitTestLayer(layer, doc([layer]), { x: 30, y: 30 })).toBe(false);
+  });
+
+  it('hitTestLayer hits content present only in the live cache rect', () => {
+    const layer = paintLayer('p'); // persisted content still empty (unflushed stroke)
+    const liveRect = { height: 40, width: 40, x: 20, y: 20 };
+    // Inside the live rect: grabbable even though the contract bitmap is null.
+    expect(hitTestLayer(layer, doc([layer]), { x: 30, y: 30 }, liveRect)).toBe(true);
+    // Outside the live rect: still a miss.
+    expect(hitTestLayer(layer, doc([layer]), { x: 5, y: 5 }, liveRect)).toBe(false);
+  });
+
+  it('topLayerAt uses the liveRectOf resolver to grab unflushed content', () => {
+    const layer = paintLayer('p');
+    const d = doc([layer]);
+    const liveRectOf = (id: string) => (id === 'p' ? { height: 40, width: 40, x: 20, y: 20 } : undefined);
+    expect(topLayerAt(d, { x: 30, y: 30 }, () => true, liveRectOf)?.id).toBe('p');
+    // Without the resolver the empty layer is ungrabbable.
+    expect(topLayerAt(d, { x: 30, y: 30 }, () => true)).toBeNull();
+  });
+
+  it('unions the live rect with persisted content (both contribute to the hit area)', () => {
+    const layer = paintLayer('p', { width: 10, height: 10 }); // persisted content [0,0,10,10]
+    const liveRect = { height: 10, width: 10, x: 40, y: 40 }; // grown region off to the side
+    // A point only inside the grown live region is now hit-testable.
+    expect(hitTestLayer(layer, doc([layer]), { x: 45, y: 45 }, liveRect)).toBe(true);
+    // The original persisted region is still hit-testable.
+    expect(hitTestLayer(layer, doc([layer]), { x: 5, y: 5 }, liveRect)).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveHitTest.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveHitTest.ts
new file mode 100644
index 00000000000..2b11e9c9ffb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveHitTest.ts
@@ -0,0 +1,174 @@
+/**
+ * Pure geometry for the move tool: layer hit-testing and outline corners.
+ *
+ * A layer's raster cache holds unscaled pixels in the layer's LOCAL space; the
+ * compositor draws it through the layer transform (translate·rotate·scale). To
+ * hit-test a document-space point we invert that transform and check the point
+ * against the layer's native `[0,w]×[0,h]` rect — so rotation and scale are
+ * handled exactly, not via an axis-aligned approximation.
+ *
+ * Every renderable layer is hit-testable — image by its native size, paint by
+ * its content rect (bitmap dims at the persisted offset), the parametric sources
+ * (shape/gradient/text) by the same content rect the compositor/cache use
+ * (CANVAS_PLAN Phase 5: "param for parametric"), and MASK layers (inpaint /
+ * regional) by their alpha bitmap's content rect (legacy allows moving masks).
+ * An EMPTY layer (a brand-new / cleared paint or mask layer with no pixels)
+ * returns `null`/`false` rather than throwing, so the move/transform tools can
+ * scan a mixed stack safely.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasLayerBaseContract, CanvasLayerContract } from '@workbench/types';
+
+import {
+  getSourceContentRect,
+  LAYER_GROUP_COUNT,
+  layerGroupRank,
+  renderableSourceOf,
+} from '@workbench/canvas-engine/document/sources';
+import { applyToPoint, fromTRS, invert } from '@workbench/canvas-engine/math/mat2d';
+import { isEmpty, union } from '@workbench/canvas-engine/math/rect';
+
+type LayerTransform = CanvasLayerBaseContract['transform'];
+
+/**
+ * Resolves a layer's LIVE cache rect (layer-local), or `undefined`. Threaded from
+ * the engine so hit-testing covers freshly-painted content the debounced bitmap
+ * flush hasn't yet written back to the persisted contract — mirrors how
+ * `invertMask` unions the live cache rect. A pure caller (no engine) omits it.
+ */
+export type LiveCacheRectOf = (layerId: string) => Rect | undefined;
+
+/**
+ * A hit-testable layer's content rectangle in its LOCAL (untransformed) space —
+ * including its (possibly off-zero) origin for content-sized paint/mask layers —
+ * or `null` for a layer with no rasterizable content or an EMPTY layer (no
+ * pixels). Mask layers hit-test by their alpha bitmap's content rect, so the move
+ * tool can grab a painted mask (matching legacy). Every source (image/paint/
+ * shape/gradient/text) and mask reuses {@link getSourceContentRect} — the exact
+ * rect the cache/compositor render.
+ */
+export const hittableLayerRect = (
+  layer: CanvasLayerContract,
+  doc: CanvasDocumentContractV2,
+  liveRect?: Rect
+): Rect | null => {
+  if (!renderableSourceOf(layer)) {
+    return null;
+  }
+  const content = getSourceContentRect(layer, doc);
+  // Union the live cache rect (when present): a stroke painted moments ago lives
+  // in the cache but not yet in the persisted contract (the bitmap flush is
+  // debounced), so content alone would leave freshly-painted pixels ungrabbable —
+  // and content is EMPTY for a brand-new paint layer whose first stroke hasn't
+  // flushed. Mirrors `invertMask`'s live-cache union.
+  const rect = liveRect && !isEmpty(liveRect) ? (isEmpty(content) ? liveRect : union(content, liveRect)) : content;
+  if (rect.width <= 0 || rect.height <= 0) {
+    return null;
+  }
+  return rect;
+};
+
+/**
+ * The native (unscaled) local pixel size of a hit-testable layer, or `null` when
+ * not hit-testable. A thin wrapper over {@link hittableLayerRect} for callers
+ * that only need eligibility / dimensions (not the origin).
+ */
+export const hittableLayerSize = (
+  layer: CanvasLayerContract,
+  doc: CanvasDocumentContractV2
+): { width: number; height: number } | null => {
+  const rect = hittableLayerRect(layer, doc);
+  return rect ? { height: rect.height, width: rect.width } : null;
+};
+
+/** The layer's local→document affine matrix from its transform. */
+export const layerMatrix = (transform: LayerTransform) =>
+  fromTRS({ x: transform.x, y: transform.y }, transform.rotation, transform.scaleX, transform.scaleY);
+
+/** True when `point` (document space) falls inside `layer`'s rendered bounds. */
+export const hitTestLayer = (
+  layer: CanvasLayerContract,
+  doc: CanvasDocumentContractV2,
+  point: Vec2,
+  liveRect?: Rect
+): boolean => {
+  const rect = hittableLayerRect(layer, doc, liveRect);
+  if (!rect) {
+    return false;
+  }
+  const inverse = invert(layerMatrix(layer.transform));
+  if (!inverse) {
+    return false;
+  }
+  const local = applyToPoint(inverse, point);
+  return local.x >= rect.x && local.x <= rect.x + rect.width && local.y >= rect.y && local.y <= rect.y + rect.height;
+};
+
+/**
+ * The top-most layer that both satisfies `predicate` and contains `point`, or
+ * `null`. "Top-most" follows the COMPOSITE order, not the raw array order: layers
+ * are visited by group rank high→low (inpaint mask > regional guidance > control >
+ * raster — see {@link layerGroupRank}), and WITHIN a group by array order (index 0
+ * is top-most within its group). This matches what the compositor draws, so a
+ * control layer painted visually over a raster wins the hit even when the raster
+ * sits at a lower global index — keeping the move-tool auto-select and the canvas
+ * context-menu target consistent with the pixels on screen (batch finding N1). The
+ * predicate lets callers require visible/unlocked; `liveRectOf` (optional) supplies
+ * each layer's live cache rect so freshly-painted, not-yet-flushed content is
+ * hit-testable.
+ */
+export const topLayerAt = (
+  doc: CanvasDocumentContractV2,
+  point: Vec2,
+  predicate: (layer: CanvasLayerContract) => boolean,
+  liveRectOf?: LiveCacheRectOf
+): CanvasLayerContract | null => {
+  for (let rank = LAYER_GROUP_COUNT - 1; rank >= 0; rank--) {
+    for (const layer of doc.layers) {
+      if (layerGroupRank(layer) !== rank) {
+        continue;
+      }
+      if (predicate(layer) && hitTestLayer(layer, doc, point, liveRectOf?.(layer.id))) {
+        return layer;
+      }
+    }
+  }
+  return null;
+};
+
+/**
+ * The four document-space corners of a layer's rendered rectangle (for the move
+ * overlay outline), or `null` when the layer has no hit-testable bounds.
+ * `override` shifts/scales/rotates the rect for a live drag preview without
+ * mutating the layer (fields absent from the override fall back to the committed
+ * transform; the move tool passes only `x`/`y`).
+ */
+export const layerOutlineCorners = (
+  layer: CanvasLayerContract,
+  doc: CanvasDocumentContractV2,
+  override?: { x: number; y: number; scaleX?: number; scaleY?: number; rotation?: number } | null
+): Vec2[] | null => {
+  const rect = hittableLayerRect(layer, doc);
+  if (!rect) {
+    return null;
+  }
+  const transform: LayerTransform = override
+    ? {
+        rotation: override.rotation ?? layer.transform.rotation,
+        scaleX: override.scaleX ?? layer.transform.scaleX,
+        scaleY: override.scaleY ?? layer.transform.scaleY,
+        x: override.x,
+        y: override.y,
+      }
+    : layer.transform;
+  const matrix = layerMatrix(transform);
+  return [
+    { x: rect.x, y: rect.y },
+    { x: rect.x + rect.width, y: rect.y },
+    { x: rect.x + rect.width, y: rect.y + rect.height },
+    { x: rect.x, y: rect.y + rect.height },
+  ].map((corner) => applyToPoint(matrix, corner));
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveTool.test.ts
new file mode 100644
index 00000000000..c481a301802
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveTool.test.ts
@@ -0,0 +1,324 @@
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { constrainDelta, createMoveTool } from './moveTool';
+
+const imageLayer = (
+  id: string,
+  opts: { x?: number; y?: number; width?: number; height?: number; isLocked?: boolean; isEnabled?: boolean } = {}
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: opts.isEnabled ?? true,
+  isLocked: opts.isLocked ?? false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: opts.height ?? 40, imageName: id, width: opts.width ?? 40 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: opts.x ?? 0, y: opts.y ?? 0 },
+  type: 'raster',
+});
+
+const shapeLayer = (
+  id: string,
+  opts: { x?: number; y?: number; width?: number; height?: number } = {}
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: {
+    fill: '#ffffff',
+    height: opts.height ?? 40,
+    kind: 'rect',
+    stroke: null,
+    strokeWidth: 0,
+    type: 'shape',
+    width: opts.width ?? 40,
+  },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: opts.x ?? 0, y: opts.y ?? 0 },
+  type: 'raster',
+});
+
+const makeDoc = (layers: CanvasLayerContract[], selectedLayerId: string | null): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers,
+  selectedLayerId,
+  version: 2,
+  width: 100,
+});
+
+const pointer = (x: number, y: number, opts: { shift?: boolean; buttons?: number } = {}): PointerInput => ({
+  buttons: opts.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: opts.shift ?? false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+interface StructuralCommit {
+  label: string;
+  forward: CanvasProjectMutation;
+  inverse: CanvasProjectMutation;
+}
+
+interface Harness {
+  ctx: ToolContext;
+  dispatched: CanvasProjectMutation[];
+  commits: StructuralCommit[];
+  overrides: { layerId: string; override: { x: number; y: number } | null }[];
+}
+
+const createHarness = (doc: CanvasDocumentContractV2): Harness => {
+  const dispatched: CanvasProjectMutation[] = [];
+  const commits: StructuralCommit[] = [];
+  const overrides: { layerId: string; override: { x: number; y: number } | null }[] = [];
+  const ctx: ToolContext = {
+    backend: null as never,
+    commitStructural: (label, forward, inverse) => commits.push({ forward, inverse, label }),
+    createLayerId: () => 'x',
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    dispatch: (action) => dispatched.push(action),
+    emitStrokeCommitted: vi.fn(),
+    getDocument: () => doc,
+    invalidate: vi.fn(),
+    // A real (empty) layer cache so the move tool's live-cache-rect hit-test seam
+    // resolves; no test here relies on cached content, so entries stay absent.
+    layers: createLayerCacheStore(createTestStubRasterBackend()),
+    notifyLayerPainted: vi.fn(),
+    setLayerTransformOverride: (layerId, override) => overrides.push({ layerId, override }),
+    setOverlayCursor: vi.fn(),
+    stores: createEngineStores(),
+    updateCursor: vi.fn(),
+    viewport: null as never,
+  };
+  return { commits, ctx, dispatched, overrides };
+};
+
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerMove?.(ctx, i, [i]);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+const cancel = (t: Tool, ctx: ToolContext): void => t.onPointerCancel?.(ctx);
+
+describe('constrainDelta', () => {
+  it('passes the raw delta through without shift', () => {
+    expect(constrainDelta(3, 7, false)).toEqual({ x: 3, y: 7 });
+  });
+  it('zeroes the smaller axis under shift', () => {
+    expect(constrainDelta(10, 3, true)).toEqual({ x: 10, y: 0 });
+    expect(constrainDelta(2, -8, true)).toEqual({ x: 0, y: -8 });
+  });
+});
+
+describe('move tool: click selection', () => {
+  it('selects the top-most visible layer under the point (one dispatch, no commit)', () => {
+    const doc = makeDoc(
+      [imageLayer('top', { width: 50, height: 50 }), imageLayer('bottom', { width: 50, height: 50 })],
+      null
+    );
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    up(tool, h.ctx, pointer(10, 10));
+
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toEqual([{ id: 'top', type: 'setCanvasSelectedLayer' }]);
+  });
+
+  it('clears the selection when clicking empty space', () => {
+    const doc = makeDoc([imageLayer('a', { width: 10, height: 10 })], 'a');
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(80, 80));
+    up(tool, h.ctx, pointer(80, 80));
+
+    expect(h.dispatched).toEqual([{ id: null, type: 'setCanvasSelectedLayer' }]);
+  });
+
+  it('can click-select a locked layer', () => {
+    const doc = makeDoc([imageLayer('locked', { width: 50, height: 50, isLocked: true })], null);
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    up(tool, h.ctx, pointer(10, 10));
+
+    expect(h.dispatched).toEqual([{ id: 'locked', type: 'setCanvasSelectedLayer' }]);
+  });
+
+  it('does not click-select a hidden layer', () => {
+    const doc = makeDoc([imageLayer('hidden', { width: 50, height: 50, isEnabled: false })], null);
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    up(tool, h.ctx, pointer(10, 10));
+
+    // Hidden layer is not hit → empty-space clear.
+    expect(h.dispatched).toEqual([{ id: null, type: 'setCanvasSelectedLayer' }]);
+  });
+});
+
+describe('move tool: drag', () => {
+  it('previews via override on move then commits one structural transform on up', () => {
+    const doc = makeDoc([imageLayer('a', { x: 0, y: 0, width: 50, height: 50 })], 'a');
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(30, 25));
+    up(tool, h.ctx, pointer(30, 25));
+
+    // Preview override applied during the move, cleared on commit.
+    expect(h.overrides).toEqual([
+      { layerId: 'a', override: { x: 20, y: 15 } },
+      { layerId: 'a', override: null },
+    ]);
+    // Exactly one structural commit; the target was already selected → no extra dispatch.
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.commits).toHaveLength(1);
+    expect(h.commits[0]!.forward).toEqual({
+      id: 'a',
+      patch: { transform: { x: 20, y: 15 } },
+      type: 'updateCanvasLayer',
+    });
+    expect(h.commits[0]!.inverse).toEqual({
+      id: 'a',
+      patch: { transform: { x: 0, y: 0 } },
+      type: 'updateCanvasLayer',
+    });
+  });
+
+  it('drags a parametric shape layer, committing one structural transform', () => {
+    // Regression: shape/gradient/text layers were not hit-testable, so the move
+    // tool skipped them (Phase 5 "param for parametric" hit-testing).
+    const doc = makeDoc([shapeLayer('s', { x: 0, y: 0, width: 50, height: 50 })], 's');
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(30, 25));
+    up(tool, h.ctx, pointer(30, 25));
+
+    expect(h.commits).toHaveLength(1);
+    expect(h.commits[0]!.forward).toEqual({
+      id: 's',
+      patch: { transform: { x: 20, y: 15 } },
+      type: 'updateCanvasLayer',
+    });
+  });
+
+  it('auto-selects the pressed unlocked layer before committing the move', () => {
+    const doc = makeDoc(
+      [imageLayer('top', { width: 50, height: 50 }), imageLayer('bottom', { width: 50, height: 50 })],
+      'bottom'
+    );
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(30, 10));
+    up(tool, h.ctx, pointer(30, 10));
+
+    // Selection switched to the pressed layer, then the move committed on it.
+    expect(h.dispatched).toEqual([{ id: 'top', type: 'setCanvasSelectedLayer' }]);
+    expect(h.commits).toHaveLength(1);
+    expect(h.commits[0]!.forward).toMatchObject({ id: 'top' });
+  });
+
+  it('moves the selected layer when the press lands on empty space', () => {
+    const doc = makeDoc([imageLayer('a', { x: 0, y: 0, width: 10, height: 10 })], 'a');
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    // Press at empty (80,80): no layer hit there, but 'a' is the selected movable layer.
+    down(tool, h.ctx, pointer(80, 80));
+    move(tool, h.ctx, pointer(90, 85));
+    up(tool, h.ctx, pointer(90, 85));
+
+    expect(h.commits).toHaveLength(1);
+    expect(h.commits[0]!.forward).toEqual({
+      id: 'a',
+      patch: { transform: { x: 10, y: 5 } },
+      type: 'updateCanvasLayer',
+    });
+  });
+
+  it('does not drag a locked layer (auto-select finds nothing, no selected fallback)', () => {
+    const doc = makeDoc([imageLayer('locked', { width: 50, height: 50, isLocked: true })], null);
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(40, 40));
+    up(tool, h.ctx, pointer(40, 40));
+
+    expect(h.commits).toHaveLength(0);
+    expect(h.overrides).toHaveLength(0);
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('constrains to the dominant axis under shift', () => {
+    const doc = makeDoc([imageLayer('a', { x: 0, y: 0, width: 50, height: 50 })], 'a');
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(40, 15, { shift: true }));
+    up(tool, h.ctx, pointer(40, 15, { shift: true }));
+
+    expect(h.commits[0]!.forward).toEqual({
+      id: 'a',
+      patch: { transform: { x: 30, y: 0 } },
+      type: 'updateCanvasLayer',
+    });
+  });
+
+  it('commits nothing for a sub-threshold press+release (treated as a click)', () => {
+    const doc = makeDoc([imageLayer('a', { width: 50, height: 50 })], 'a');
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(11, 11)); // < 3px screen
+    up(tool, h.ctx, pointer(11, 11));
+
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toEqual([{ id: 'a', type: 'setCanvasSelectedLayer' }]);
+  });
+});
+
+describe('move tool: cancel', () => {
+  it('drops the override and commits nothing on Esc mid-drag', () => {
+    const doc = makeDoc([imageLayer('a', { width: 50, height: 50 })], 'a');
+    const h = createHarness(doc);
+    const tool = createMoveTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(40, 40));
+    cancel(tool, h.ctx);
+
+    expect(h.commits).toHaveLength(0);
+    expect(h.dispatched).toHaveLength(0);
+    // Last override op clears the preview.
+    expect(h.overrides.at(-1)).toEqual({ layerId: 'a', override: null });
+
+    // A subsequent up (from the released pointer) does nothing.
+    up(tool, h.ctx, pointer(40, 40));
+    expect(h.commits).toHaveLength(0);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveTool.ts
new file mode 100644
index 00000000000..4fdd5514667
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/moveTool.ts
@@ -0,0 +1,208 @@
+/**
+ * The move tool: click to select the top-most layer under the cursor, drag to
+ * move a layer (auto-selecting the pressed unlocked layer, photo-editor style).
+ *
+ * Interaction contract (see CANVAS_PLAN Phase 3):
+ * - **Click** (press+release under the drag threshold): selects the top-most
+ *   VISIBLE layer whose rendered bounds contain the point (locked layers may be
+ *   click-selected); empty space clears the selection. One `setCanvasSelectedLayer`
+ *   dispatch, no history entry.
+ * - **Drag**: moves a layer. The pressed point's top-most enabled+unlocked layer
+ *   becomes the target (auto-select); otherwise the currently-selected
+ *   enabled+unlocked layer is moved. Hidden/locked layers are never dragged.
+ *   `shift` constrains motion to the dominant axis. Pointer-move only sets a
+ *   transient transform override (live preview) — it never dispatches.
+ * - **Commit** (pointer-up after a real move): one `commitStructural` with the
+ *   new/old transform x/y (plus a selection dispatch when the target wasn't
+ *   already selected). A zero-delta drag commits nothing.
+ * - **Cancel** (Esc / pointercancel): drops the override, no dispatch.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasLayerContract } from '@workbench/types';
+
+import type { Tool, ToolContext } from './tool';
+
+import { type LiveCacheRectOf, topLayerAt } from './moveHitTest';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/**
+ * A live-cache-rect resolver over the tool's layer cache, so hit-testing grabs
+ * freshly-painted content the debounced bitmap flush hasn't yet written back to
+ * the persisted contract (a new layer + stroke is otherwise ungrabbable until the
+ * ~1.5s flush lands).
+ */
+const liveRectOf =
+  (ctx: ToolContext): LiveCacheRectOf =>
+  (layerId) =>
+    ctx.layers.get(layerId)?.rect;
+
+/** Screen-space distance (CSS px) the pointer must travel before a press becomes a drag. */
+export const MOVE_DRAG_THRESHOLD_PX = 3;
+
+const isVisible = (layer: CanvasLayerContract): boolean => layer.isEnabled;
+const isDraggable = (layer: CanvasLayerContract): boolean => layer.isEnabled && !layer.isLocked;
+
+/** Applies the shift-to-dominant-axis constraint to a document-space delta. */
+export const constrainDelta = (dx: number, dy: number, shift: boolean): Vec2 => {
+  if (!shift) {
+    return { x: dx, y: dy };
+  }
+  return Math.abs(dx) >= Math.abs(dy) ? { x: dx, y: 0 } : { x: 0, y: dy };
+};
+
+interface GestureState {
+  startDoc: Vec2;
+  startScreen: Vec2;
+  /** The layer being dragged (null when the press had nothing to move). */
+  targetId: string | null;
+  /** The drag target's original transform x/y. */
+  origin: { x: number; y: number } | null;
+  /** The top-most visible layer under the press, for click selection (lock allowed). */
+  clickTargetId: string | null;
+  /** The document's selected layer at press time. */
+  selectedAtStart: string | null;
+  moved: boolean;
+}
+
+/** Creates a fresh move tool with its own gesture state. */
+export const createMoveTool = (): Tool => {
+  let state: GestureState | null = null;
+
+  const clearOverride = (ctx: ToolContext): void => {
+    if (state?.targetId) {
+      ctx.setLayerTransformOverride(state.targetId, null);
+    }
+  };
+
+  const endGesture = (): void => {
+    state = null;
+  };
+
+  const resolveDragTarget = (ctx: ToolContext, point: Vec2, selectedId: string | null): CanvasLayerContract | null => {
+    const doc = ctx.getDocument();
+    if (!doc) {
+      return null;
+    }
+    // Auto-select: the pressed point's top-most enabled+unlocked layer wins.
+    const hit = topLayerAt(doc, point, isDraggable, liveRectOf(ctx));
+    if (hit) {
+      return hit;
+    }
+    // Otherwise fall back to moving the currently-selected layer (if movable).
+    const selected = selectedId ? doc.layers.find((layer) => layer.id === selectedId) : undefined;
+    return selected && isDraggable(selected) ? selected : null;
+  };
+
+  const previewAt = (ctx: ToolContext, input: PointerInput): void => {
+    if (!state || !state.targetId || !state.origin) {
+      return;
+    }
+    const delta = constrainDelta(
+      input.documentPoint.x - state.startDoc.x,
+      input.documentPoint.y - state.startDoc.y,
+      input.modifiers.shift
+    );
+    ctx.setLayerTransformOverride(state.targetId, { x: state.origin.x + delta.x, y: state.origin.y + delta.y });
+  };
+
+  return {
+    cursor: () => 'move',
+    id: 'move',
+    onDeactivate: (ctx) => {
+      clearOverride(ctx);
+      endGesture();
+    },
+    onPointerCancel: (ctx) => {
+      clearOverride(ctx);
+      ctx.invalidate({ overlay: true });
+      endGesture();
+    },
+    onPointerDown: (ctx, input) => {
+      if (state || (input.buttons & PRIMARY_BUTTON) === 0) {
+        return;
+      }
+      const doc = ctx.getDocument();
+      if (!doc) {
+        return;
+      }
+      const clickTarget = topLayerAt(doc, input.documentPoint, isVisible, liveRectOf(ctx));
+      const dragTarget = resolveDragTarget(ctx, input.documentPoint, doc.selectedLayerId);
+      state = {
+        clickTargetId: clickTarget?.id ?? null,
+        moved: false,
+        origin: dragTarget ? { x: dragTarget.transform.x, y: dragTarget.transform.y } : null,
+        selectedAtStart: doc.selectedLayerId,
+        startDoc: input.documentPoint,
+        startScreen: input.screenPoint,
+        targetId: dragTarget?.id ?? null,
+      };
+    },
+    onPointerMove: (ctx, input) => {
+      if (!state) {
+        return;
+      }
+      if (!state.moved) {
+        const dxs = input.screenPoint.x - state.startScreen.x;
+        const dys = input.screenPoint.y - state.startScreen.y;
+        if (Math.hypot(dxs, dys) < MOVE_DRAG_THRESHOLD_PX) {
+          return;
+        }
+        state.moved = true;
+      }
+      previewAt(ctx, input);
+    },
+    onPointerUp: (ctx, input) => {
+      if (!state) {
+        return;
+      }
+      const current = state;
+      endGesture();
+
+      if (!current.moved) {
+        // A click: select the top-most visible layer, or clear on empty space.
+        ctx.dispatch({ id: current.clickTargetId, type: 'setCanvasSelectedLayer' });
+        return;
+      }
+
+      if (!current.targetId || !current.origin) {
+        // Dragged over empty space with nothing to move — no-op.
+        return;
+      }
+
+      const delta = constrainDelta(
+        input.documentPoint.x - current.startDoc.x,
+        input.documentPoint.y - current.startDoc.y,
+        input.modifiers.shift
+      );
+      const next = { x: current.origin.x + delta.x, y: current.origin.y + delta.y };
+
+      if (next.x === current.origin.x && next.y === current.origin.y) {
+        // Zero-delta drag: behave like a click-select of the target, no commit.
+        ctx.setLayerTransformOverride(current.targetId, null);
+        ctx.dispatch({ id: current.targetId, type: 'setCanvasSelectedLayer' });
+        return;
+      }
+
+      // Auto-select the dragged layer if it wasn't already selected (no history).
+      if (current.targetId !== current.selectedAtStart) {
+        ctx.dispatch({ id: current.targetId, type: 'setCanvasSelectedLayer' });
+      }
+      ctx.commitStructural(
+        'Move layer',
+        { id: current.targetId, patch: { transform: { x: next.x, y: next.y } }, type: 'updateCanvasLayer' },
+        {
+          id: current.targetId,
+          patch: { transform: { x: current.origin.x, y: current.origin.y } },
+          type: 'updateCanvasLayer',
+        }
+      );
+      // The committed transform now flows through the mirror; drop the preview.
+      ctx.setLayerTransformOverride(current.targetId, null);
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintConstants.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintConstants.test.ts
new file mode 100644
index 00000000000..42177978f5b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintConstants.test.ts
@@ -0,0 +1,44 @@
+import { MAX_BRUSH_SIZE, MIN_BRUSH_SIZE } from '@workbench/canvas-engine/engineStores';
+import { describe, expect, it } from 'vitest';
+
+import { clampBrushSize, SIZE_STEP_FACTOR, stepBrushSize } from './paintConstants';
+
+describe('clampBrushSize', () => {
+  it('clamps to [MIN_BRUSH_SIZE, MAX_BRUSH_SIZE]', () => {
+    expect(clampBrushSize(0)).toBe(MIN_BRUSH_SIZE);
+    expect(clampBrushSize(-100)).toBe(MIN_BRUSH_SIZE);
+    expect(clampBrushSize(1_000_000)).toBe(MAX_BRUSH_SIZE);
+  });
+
+  it('rounds to the nearest integer', () => {
+    expect(clampBrushSize(50.6)).toBe(51);
+    expect(clampBrushSize(50.4)).toBe(50);
+  });
+});
+
+describe('stepBrushSize', () => {
+  it('grows by SIZE_STEP_FACTOR for direction +1', () => {
+    expect(stepBrushSize(50, 1)).toBe(Math.round(50 * (1 + SIZE_STEP_FACTOR)));
+  });
+
+  it('shrinks by SIZE_STEP_FACTOR for direction -1', () => {
+    expect(stepBrushSize(50, -1)).toBe(Math.round(50 * (1 - SIZE_STEP_FACTOR)));
+  });
+
+  it('clamps growth at MAX_BRUSH_SIZE', () => {
+    expect(stepBrushSize(MAX_BRUSH_SIZE, 1)).toBe(MAX_BRUSH_SIZE);
+  });
+
+  it('clamps shrink at MIN_BRUSH_SIZE', () => {
+    expect(stepBrushSize(MIN_BRUSH_SIZE, -1)).toBe(MIN_BRUSH_SIZE);
+  });
+
+  it('is monotonic: repeated growth never decreases size', () => {
+    let size = MIN_BRUSH_SIZE;
+    for (let i = 0; i < 20; i++) {
+      const next = stepBrushSize(size, 1);
+      expect(next).toBeGreaterThanOrEqual(size);
+      size = next;
+    }
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintConstants.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintConstants.ts
new file mode 100644
index 00000000000..1989ef363a6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintConstants.ts
@@ -0,0 +1,24 @@
+/**
+ * Shared brush/eraser painting constants and the size-step math both the
+ * ctrl+wheel path (`input/wheel.ts`) and the `[`/`]` hotkeys drive through the
+ * same helper. Zero React, zero import-time side effects.
+ */
+
+import { MAX_BRUSH_SIZE, MIN_BRUSH_SIZE } from '@workbench/canvas-engine/engineStores';
+
+/** Freehand `thinning` applied when brush pressure sensitivity is on. */
+export const PRESSURE_THINNING = 0.5;
+
+/** Fraction to grow/shrink the brush/eraser diameter per size-step notch (ctrl+wheel or `[`/`]`). */
+export const SIZE_STEP_FACTOR = 0.1;
+
+/** Clamps a brush/eraser diameter to `[MIN_BRUSH_SIZE, MAX_BRUSH_SIZE]`, rounded to the nearest integer. */
+export const clampBrushSize = (value: number): number =>
+  Math.max(MIN_BRUSH_SIZE, Math.min(MAX_BRUSH_SIZE, Math.round(value)));
+
+/**
+ * Steps a brush/eraser diameter by one notch: `+1` grows by `SIZE_STEP_FACTOR`,
+ * `-1` shrinks by it, clamped to the valid size range.
+ */
+export const stepBrushSize = (size: number, direction: 1 | -1): number =>
+  clampBrushSize(size * (1 + direction * SIZE_STEP_FACTOR));
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintTool.test.ts
new file mode 100644
index 00000000000..03d6f690396
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintTool.test.ts
@@ -0,0 +1,503 @@
+import type { StubRasterBackend, StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type {
+  ControlPixelEditTransaction,
+  StrokeCommittedEvent,
+  Tool,
+  ToolContext,
+} from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasControlLayerContract, CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { isEmpty } from '@workbench/canvas-engine/math/rect';
+import { createLayerCacheStore, type LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { createBrushTool } from '@workbench/canvas-engine/tools/brushTool';
+import { createEraserTool } from '@workbench/canvas-engine/tools/eraserTool';
+import { describe, expect, it, vi } from 'vitest';
+
+const paintLayer = (
+  id: string,
+  opts: { isLocked?: boolean; isEnabled?: boolean; isTransparencyLocked?: boolean } = {}
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: opts.isEnabled ?? true,
+  isLocked: opts.isLocked ?? false,
+  ...(opts.isTransparencyLocked ? { isTransparencyLocked: true } : {}),
+  name: id,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const imageLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: 10, imageName: id, width: 10 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const inpaintMaskLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+const controlPaintLayer = (id: string): CanvasControlLayerContract => ({
+  adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: true,
+});
+
+const controlImageLayer = (id: string): CanvasControlLayerContract => ({
+  ...controlPaintLayer(id),
+  source: { image: { height: 20, imageName: id, width: 20 }, type: 'image' },
+});
+
+const controlTransaction = (): ControlPixelEditTransaction => ({
+  cancel: vi.fn(),
+  commitPatch: vi.fn(),
+  commitStroke: vi.fn(),
+  layerId: 'control',
+});
+
+const makeDoc = (layers: CanvasLayerContract[], selectedLayerId: string | null): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers,
+  selectedLayerId,
+  version: 2,
+  width: 100,
+});
+
+const pointer = (x: number, y: number, opts: { pressure?: number; buttons?: number } = {}): PointerInput => ({
+  buttons: opts.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: false },
+  pointerType: 'mouse',
+  pressure: opts.pressure ?? 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+// Optional-method drivers, so tests read as gestures rather than `?.` noise.
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput, batch: PointerInput[]): void =>
+  t.onPointerMove?.(ctx, i, batch);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+const cancel = (t: Tool, ctx: ToolContext): void => t.onPointerCancel?.(ctx);
+
+interface Harness {
+  beginControlPixelEdit: ReturnType<typeof vi.fn> | null;
+  ctx: ToolContext;
+  backend: StubRasterBackend;
+  layers: LayerCacheStore;
+  dispatched: CanvasProjectMutation[];
+  strokes: StrokeCommittedEvent[];
+  painted: string[];
+  createdIds: string[];
+}
+
+const createHarness = (
+  doc: CanvasDocumentContractV2,
+  transaction: ControlPixelEditTransaction | null | undefined = undefined
+): Harness => {
+  const backend = createTestStubRasterBackend();
+  const layers = createLayerCacheStore(backend);
+  const stores = createEngineStores();
+  const dispatched: CanvasProjectMutation[] = [];
+  const strokes: StrokeCommittedEvent[] = [];
+  const painted: string[] = [];
+  const createdIds: string[] = [];
+  const beginControlPixelEdit = transaction === undefined ? null : vi.fn(() => transaction);
+  let idCounter = 0;
+
+  const ctx: ToolContext = {
+    backend,
+    ...(beginControlPixelEdit ? { beginControlPixelEdit } : {}),
+    commitStructural: vi.fn(),
+    createLayerId: () => {
+      const id = `new-layer-${(idCounter += 1)}`;
+      createdIds.push(id);
+      return id;
+    },
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    dispatch: (action) => dispatched.push(action),
+    emitStrokeCommitted: (event) => {
+      painted.push(event.layerId);
+      strokes.push(event);
+    },
+    getDocument: () => doc,
+    invalidate: vi.fn(),
+    layers,
+    notifyLayerPainted: (layerId) => painted.push(layerId),
+    setLayerTransformOverride: vi.fn(),
+    setOverlayCursor: vi.fn(),
+    stores,
+    updateCursor: vi.fn(),
+    viewport: null as never,
+  };
+
+  return { backend, beginControlPixelEdit, createdIds, ctx, dispatched, layers, painted, strokes };
+};
+
+const cacheOps = (surface: StubRasterSurface): string[] => surface.callLog.map((entry) => entry.op);
+
+/** The value of the last `globalCompositeOperation` assignment recorded on the cache surface. */
+const lastCompositeOp = (surface: StubRasterSurface): unknown =>
+  surface.callLog
+    .filter((entry) => entry.op === 'set' && entry.args[0] === 'globalCompositeOperation')
+    .map((entry) => entry.args[1])
+    .pop();
+
+/** The value of the last `globalAlpha` assignment recorded on the cache surface. */
+const lastGlobalAlpha = (surface: StubRasterSurface): unknown =>
+  surface.callLog
+    .filter((entry) => entry.op === 'set' && entry.args[0] === 'globalAlpha')
+    .map((entry) => entry.args[1])
+    .pop();
+
+const cacheSurface = (h: Harness, layerId: string): StubRasterSurface =>
+  h.layers.get(layerId)!.surface as StubRasterSurface;
+
+describe('brush tool: stroke into an existing paint layer', () => {
+  it('paints, emits one strokeCommitted with a content-sized dirty rect, and does not dispatch', () => {
+    const doc = makeDoc([paintLayer('paint1')], 'paint1');
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    move(brush, h.ctx, pointer(40, 40), [pointer(30, 30), pointer(40, 40)]);
+    up(brush, h.ctx, pointer(40, 40));
+
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.strokes).toHaveLength(1);
+    const event = h.strokes[0]!;
+    expect(event.tool).toBe('brush');
+    expect(event.layerId).toBe('paint1');
+
+    // Dirty rect is integer and non-empty. Content-sized: it is the stroke's TRUE
+    // bounds (no document clamp), so it can extend past the document edges — a
+    // paint layer grows with its strokes.
+    const { dirtyRect } = event;
+    expect(Number.isInteger(dirtyRect.x)).toBe(true);
+    expect(Number.isInteger(dirtyRect.width)).toBe(true);
+    expect(isEmpty(dirtyRect)).toBe(false);
+
+    // Before/after snapshots are sized exactly to the dirty rect.
+    expect(event.beforeImageData.width).toBe(dirtyRect.width);
+    expect(event.beforeImageData.height).toBe(dirtyRect.height);
+    expect(event.afterImageData.width).toBe(dirtyRect.width);
+    expect(event.afterImageData.height).toBe(dirtyRect.height);
+
+    // The layer version was bumped exactly once (on commit).
+    expect(h.painted).toEqual(['paint1']);
+
+    // The cache surface received the buffered-stroke composite (source-over).
+    const ops = cacheOps(cacheSurface(h, 'paint1'));
+    expect(ops).toContain('getImageData');
+    expect(ops).toContain('drawImage');
+    expect(lastCompositeOp(cacheSurface(h, 'paint1'))).toBe('source-over');
+  });
+});
+
+describe('eraser tool', () => {
+  it('composites the stroke with destination-out and reports tool "eraser"', () => {
+    const doc = makeDoc([paintLayer('paint1')], 'paint1');
+    const h = createHarness(doc);
+    const eraser = createEraserTool();
+
+    down(eraser, h.ctx, pointer(20, 20));
+    move(eraser, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    up(eraser, h.ctx, pointer(40, 40));
+
+    expect(h.strokes).toHaveLength(1);
+    expect(h.strokes[0]!.tool).toBe('eraser');
+    expect(lastCompositeOp(cacheSurface(h, 'paint1'))).toBe('destination-out');
+  });
+});
+
+describe('brush tool: cancel', () => {
+  it('restores pixels via putImageData and emits no event', () => {
+    const doc = makeDoc([paintLayer('paint1')], 'paint1');
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    move(brush, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    cancel(brush, h.ctx);
+
+    expect(h.strokes).toHaveLength(0);
+    expect(h.painted).toHaveLength(0);
+    expect(cacheOps(cacheSurface(h, 'paint1'))).toContain('putImageData');
+  });
+});
+
+describe('paint tool: target resolution', () => {
+  it('commits a selected control stroke through its transaction without adding a raster layer', () => {
+    const transaction = controlTransaction();
+    const h = createHarness(makeDoc([controlPaintLayer('control')], 'control'), transaction);
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(10, 10));
+    move(brush, h.ctx, pointer(20, 20), [pointer(20, 20)]);
+    up(brush, h.ctx, pointer(20, 20, { buttons: 0 }));
+
+    expect(h.beginControlPixelEdit).toHaveBeenCalledWith('control');
+    expect(transaction.commitStroke).toHaveBeenCalledOnce();
+    expect(transaction.cancel).not.toHaveBeenCalled();
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it.each(['pointercancel', 'deactivate'] as const)('rolls back control preparation on %s', (ending) => {
+    const transaction = controlTransaction();
+    const h = createHarness(makeDoc([controlImageLayer('control')], 'control'), transaction);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(10, 10));
+    if (ending === 'pointercancel') {
+      cancel(brush, h.ctx);
+    } else {
+      brush.onDeactivate?.(h.ctx);
+    }
+    expect(transaction.cancel).toHaveBeenCalledOnce();
+    expect(transaction.commitStroke).not.toHaveBeenCalled();
+  });
+
+  it('aborts the control transaction and releases the gesture after pointer-move painting fails', () => {
+    const transaction = controlTransaction();
+    const h = createHarness(makeDoc([controlPaintLayer('control')], 'control'), transaction);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(10, 10));
+    const drawImage = vi.spyOn(cacheSurface(h, 'control').ctx, 'drawImage').mockImplementation(() => {
+      throw new Error('move paint failed');
+    });
+
+    expect(() => move(brush, h.ctx, pointer(20, 20), [pointer(20, 20)])).toThrow('move paint failed');
+
+    expect(transaction.cancel).toHaveBeenCalledOnce();
+    expect(transaction.commitStroke).not.toHaveBeenCalled();
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.painted).toHaveLength(0);
+    expect(h.strokes).toHaveLength(0);
+
+    drawImage.mockRestore();
+    down(brush, h.ctx, pointer(30, 30));
+    expect(h.beginControlPixelEdit).toHaveBeenCalledTimes(2);
+  });
+
+  it('aborts the control transaction and releases the gesture after stroke finalization fails', () => {
+    const transaction = controlTransaction();
+    const h = createHarness(makeDoc([controlPaintLayer('control')], 'control'), transaction);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(10, 10));
+    const getImageData = vi.spyOn(cacheSurface(h, 'control').ctx, 'getImageData').mockImplementation(() => {
+      throw new Error('stroke finalization failed');
+    });
+
+    expect(() => up(brush, h.ctx, pointer(10, 10, { buttons: 0 }))).toThrow('stroke finalization failed');
+
+    expect(transaction.cancel).toHaveBeenCalledOnce();
+    expect(transaction.commitStroke).not.toHaveBeenCalled();
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.painted).toHaveLength(0);
+    expect(h.strokes).toHaveLength(0);
+
+    getImageData.mockRestore();
+    down(brush, h.ctx, pointer(30, 30));
+    expect(h.beginControlPixelEdit).toHaveBeenCalledTimes(2);
+  });
+
+  it('still cancels the control transaction and releases the gesture when pixel restoration fails', () => {
+    const transaction = controlTransaction();
+    const h = createHarness(makeDoc([controlPaintLayer('control')], 'control'), transaction);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(10, 10));
+    const putImageData = vi.spyOn(cacheSurface(h, 'control').ctx, 'putImageData').mockImplementation(() => {
+      throw new Error('pixel restoration failed');
+    });
+
+    expect(() => cancel(brush, h.ctx)).toThrow('pixel restoration failed');
+
+    expect(transaction.cancel).toHaveBeenCalledOnce();
+    expect(transaction.commitStroke).not.toHaveBeenCalled();
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.painted).toHaveLength(0);
+    expect(h.strokes).toHaveLength(0);
+
+    putImageData.mockRestore();
+    down(brush, h.ctx, pointer(30, 30));
+    expect(h.beginControlPixelEdit).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not roll back an accepted stroke when transaction publication throws', () => {
+    const transaction = controlTransaction();
+    vi.mocked(transaction.commitStroke).mockImplementation(() => {
+      throw new Error('listener publication failed');
+    });
+    const h = createHarness(makeDoc([controlPaintLayer('control')], 'control'), transaction);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(10, 10));
+
+    expect(() => up(brush, h.ctx, pointer(10, 10, { buttons: 0 }))).toThrow('listener publication failed');
+
+    expect(transaction.commitStroke).toHaveBeenCalledOnce();
+    expect(transaction.cancel).not.toHaveBeenCalled();
+    down(brush, h.ctx, pointer(30, 30));
+    expect(h.beginControlPixelEdit).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not fall through to raster auto-create when control preparation is rejected', () => {
+    const h = createHarness(makeDoc([controlImageLayer('control')], 'control'), null);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(10, 10));
+    expect(h.dispatched).toHaveLength(0);
+  });
+
+  it('auto-creates a paint layer (one dispatch) when the selection is not paintable', () => {
+    const doc = makeDoc([imageLayer('img1')], 'img1');
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    up(brush, h.ctx, pointer(20, 20));
+
+    expect(h.dispatched).toHaveLength(1);
+    const action = h.dispatched[0]!;
+    expect(action.type).toBe('addCanvasLayer');
+    if (action.type === 'addCanvasLayer' && action.layer.type === 'raster') {
+      expect(action.layer.source.type).toBe('paint');
+      expect(action.layer.id).toBe(h.createdIds[0]);
+    } else {
+      throw new Error('expected an addCanvasLayer with a raster layer');
+    }
+    // The stroke commits against the freshly-created layer.
+    expect(h.strokes).toHaveLength(1);
+    expect(h.strokes[0]!.layerId).toBe(h.createdIds[0]);
+  });
+
+  it('auto-creates when nothing is selected', () => {
+    const doc = makeDoc([paintLayer('paint1')], null);
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(20, 20));
+    expect(h.dispatched).toHaveLength(1);
+    expect(h.dispatched[0]!.type).toBe('addCanvasLayer');
+  });
+
+  it('no-ops on a locked selected paint layer (no dispatch, no paint)', () => {
+    const doc = makeDoc([paintLayer('paint1', { isLocked: true })], 'paint1');
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    move(brush, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    up(brush, h.ctx, pointer(40, 40));
+
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.strokes).toHaveLength(0);
+  });
+
+  it('no-ops on a disabled selected paint layer', () => {
+    const doc = makeDoc([paintLayer('paint1', { isEnabled: false })], 'paint1');
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+    down(brush, h.ctx, pointer(20, 20));
+    up(brush, h.ctx, pointer(20, 20));
+    expect(h.strokes).toHaveLength(0);
+  });
+});
+
+describe('transparency lock', () => {
+  it('brush composites source-atop on a transparency-locked layer (colour only on existing pixels)', () => {
+    const doc = makeDoc([paintLayer('paint1', { isTransparencyLocked: true })], 'paint1');
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    move(brush, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    up(brush, h.ctx, pointer(40, 40));
+
+    expect(h.strokes).toHaveLength(1);
+    expect(lastCompositeOp(cacheSurface(h, 'paint1'))).toBe('source-atop');
+  });
+
+  it('refuses the eraser entirely on a transparency-locked layer (no stroke, no alpha change)', () => {
+    const doc = makeDoc([paintLayer('paint1', { isTransparencyLocked: true })], 'paint1');
+    const h = createHarness(doc);
+    const eraser = createEraserTool();
+
+    down(eraser, h.ctx, pointer(20, 20));
+    move(eraser, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    up(eraser, h.ctx, pointer(40, 40));
+
+    expect(h.strokes).toHaveLength(0);
+    expect(h.painted).toEqual([]);
+  });
+
+  it('brush is unaffected (source-over) when transparency is NOT locked', () => {
+    const doc = makeDoc([paintLayer('paint1')], 'paint1');
+    const h = createHarness(doc);
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    move(brush, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    up(brush, h.ctx, pointer(40, 40));
+
+    expect(lastCompositeOp(cacheSurface(h, 'paint1'))).toBe('source-over');
+  });
+});
+
+describe('mask strokes are forced opaque', () => {
+  it('composites a mask stroke at globalAlpha 1 even when the brush opacity is 0.5', () => {
+    const doc = makeDoc([inpaintMaskLayer('mask1')], 'mask1');
+    const h = createHarness(doc);
+    // A half-opacity brush: on a raster layer this would land alpha ~128, but a
+    // mask is an all-or-nothing alpha stencil and must be forced fully opaque.
+    h.ctx.stores.brushOptions.set({ ...h.ctx.stores.brushOptions.get(), opacity: 0.5 });
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    move(brush, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    up(brush, h.ctx, pointer(40, 40));
+
+    expect(h.strokes).toHaveLength(1);
+    expect(h.strokes[0]!.layerId).toBe('mask1');
+    expect(lastGlobalAlpha(cacheSurface(h, 'mask1'))).toBe(1);
+  });
+
+  it('still respects brush opacity on a normal raster paint layer', () => {
+    const doc = makeDoc([paintLayer('paint1')], 'paint1');
+    const h = createHarness(doc);
+    h.ctx.stores.brushOptions.set({ ...h.ctx.stores.brushOptions.get(), opacity: 0.5 });
+    const brush = createBrushTool();
+
+    down(brush, h.ctx, pointer(20, 20));
+    move(brush, h.ctx, pointer(40, 40), [pointer(40, 40)]);
+    up(brush, h.ctx, pointer(40, 40));
+
+    expect(lastGlobalAlpha(cacheSurface(h, 'paint1'))).toBe(0.5);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintTool.ts
new file mode 100644
index 00000000000..fddfc198870
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/paintTool.ts
@@ -0,0 +1,279 @@
+/**
+ * The shared machinery behind the brush and eraser tools. Both are the same
+ * gesture — resolve a paintable target layer on pointer-down (auto-creating a
+ * fresh paint layer when the selection can't be painted into), drive a
+ * {@link StrokeSession} across the move batches, and commit or cancel on release —
+ * differing only in their blend (`source-over` fill vs `destination-out`) and in
+ * which options store they read. `createBrushTool` / `createEraserTool`
+ * (in `brushTool.ts` / `eraserTool.ts`) are thin wrappers over
+ * {@link createPaintTool}.
+ *
+ * This is the ONE place a painting tool is allowed to dispatch, and only ever
+ * the single gesture-start `addCanvasLayer`. Pointer-move never dispatches.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { PointerInput } from '@workbench/canvas-engine/types';
+import type { CanvasLayerContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import type { StrokeCommittedEvent, Tool, ToolContext } from './tool';
+
+import { createStrokeSession, type StrokeSession } from './strokeSession';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/** The resolved config for one gesture, derived from the tool's options store. */
+export interface PaintToolSpec {
+  id: 'brush' | 'eraser';
+  composite: 'source-over' | 'destination-out';
+  /** Reads the current size (document units) from the options store. */
+  size(ctx: ToolContext): number;
+  /** Reads the current per-stroke opacity from the options store. */
+  opacity(ctx: ToolContext): number;
+  /** The fill color; `null` for the eraser (shape only). */
+  color(ctx: ToolContext): string;
+  /** Freehand thinning for this gesture; 0 disables pressure sensitivity. */
+  thinning(ctx: ToolContext): number;
+}
+
+/** Colour brush strokes paint into a MASK cache: an opaque stencil (only alpha matters). */
+const MASK_STROKE_COLOR = '#ffffff';
+
+/** The resolved paint target for a gesture. `createdLayer` is set only when auto-created. */
+interface PaintTarget {
+  layerId: string;
+  commit(event: StrokeCommittedEvent): void;
+  cancel(): void;
+  /** When the gesture auto-created its layer, the created contract + insert index (for history). */
+  createdLayer?: { layer: CanvasLayerContract; index: number };
+  /**
+   * Overrides the brush colour for this gesture (mask targets paint an opaque
+   * stencil — the stored RGB is irrelevant, the compositor colorizes by alpha).
+   * Absent ⇒ the tool's own colour.
+   */
+  color?: string;
+  /**
+   * True when the target is a transparency-LOCKED raster paint layer. The brush
+   * then composites `source-atop` (colour only on existing pixels); the eraser is
+   * refused (erasing would change the locked alpha). Never set for mask targets.
+   */
+  transparencyLocked?: boolean;
+  /**
+   * True for mask targets (inpaint / regional guidance). A mask is an opaque
+   * alpha stencil, so the stroke is forced to opacity 1 regardless of the brush's
+   * opacity slider — a 50%-opacity brush would otherwise land alpha ~128 and
+   * silently attenuate the mask (a ~50% denoise, invisible in the tinted overlay).
+   */
+  forceOpaque?: boolean;
+}
+
+/** True for a mask-bearing layer (inpaint mask / regional guidance) — a paintable alpha stencil. */
+const isMaskLayer = (layer: CanvasLayerContract): boolean =>
+  layer.type === 'inpaint_mask' || layer.type === 'regional_guidance';
+
+/** Resolves (or auto-creates) the paint target for a gesture, or `null` to no-op. */
+const resolveTarget = (ctx: ToolContext): PaintTarget | null => {
+  const doc = ctx.getDocument();
+  if (!doc) {
+    return null;
+  }
+  const selected = doc.selectedLayerId ? doc.layers.find((layer) => layer.id === doc.selectedLayerId) : undefined;
+
+  if (selected && selected.type === 'raster' && selected.source.type === 'paint') {
+    // The selection is a paint layer: paint into it, unless it's locked/disabled
+    // (a no-op — don't silently spawn a new layer over the user's locked target).
+    if (selected.isLocked || !selected.isEnabled) {
+      return null;
+    }
+    // The cache (if any) keeps its current content extent; the stroke grows it.
+    return {
+      cancel: () => undefined,
+      commit: (event) => ctx.emitStrokeCommitted(event),
+      layerId: selected.id,
+      transparencyLocked: selected.isTransparencyLocked === true,
+    };
+  }
+
+  if (selected && isMaskLayer(selected)) {
+    // The selection is a mask: paint the stroke into its alpha stencil cache
+    // (brush adds coverage, eraser removes — the shared stroke session handles
+    // both via its composite op). Never auto-create a paint layer here. A
+    // locked/hidden mask refuses the stroke (a no-op, not a spawn).
+    if (selected.isLocked || !selected.isEnabled) {
+      return null;
+    }
+    return {
+      cancel: () => undefined,
+      color: MASK_STROKE_COLOR,
+      commit: (event) => ctx.emitStrokeCommitted(event),
+      forceOpaque: true,
+      layerId: selected.id,
+    };
+  }
+
+  if (selected?.type === 'control') {
+    const transaction = ctx.beginControlPixelEdit?.(selected.id) ?? null;
+    if (!transaction) {
+      return null;
+    }
+    return {
+      cancel: transaction.cancel,
+      commit: transaction.commitStroke,
+      layerId: transaction.layerId,
+    };
+  }
+
+  // Selection is an image/other raster, another layer type, or nothing: create a
+  // fresh paint layer (inserted on top and selected by the reducer) and paint
+  // into it. This is the single allowed gesture-start dispatch.
+  const layerId = ctx.createLayerId();
+  const layer: CanvasRasterLayerContractV2 = {
+    blendMode: 'normal',
+    id: layerId,
+    isEnabled: true,
+    isLocked: false,
+    name: `Layer ${doc.layers.length + 1}`,
+    opacity: 1,
+    source: { bitmap: null, type: 'paint' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'raster',
+  };
+  // Auto-create inserts at the top (index 0); the reducer selects it.
+  ctx.dispatch({ layer, type: 'addCanvasLayer' });
+
+  // A brand-new empty paint layer: create a zero-rect cache marked fresh so the
+  // async rasterize pass doesn't clobber the stroke mid-gesture. The first stroke
+  // grows it from empty to the stroke's content bounds.
+  const entry = ctx.layers.getOrCreateRect(layerId, { height: 0, width: 0, x: 0, y: 0 });
+  entry.stale = false;
+  return {
+    cancel: () => undefined,
+    commit: (event) => ctx.emitStrokeCommitted(event),
+    createdLayer: { index: 0, layer },
+    layerId,
+  };
+};
+
+/** Creates a brush-family tool from its per-gesture {@link PaintToolSpec}. */
+export const createPaintTool = (spec: PaintToolSpec): Tool => {
+  let session: StrokeSession | null = null;
+  let target: PaintTarget | null = null;
+
+  const cursorRadiusDoc = (ctx: ToolContext): number => spec.size(ctx) / 2;
+
+  const updateCursorRing = (ctx: ToolContext, input: PointerInput): void => {
+    ctx.setOverlayCursor({ point: input.documentPoint, radiusDoc: cursorRadiusDoc(ctx) });
+    ctx.invalidate({ overlay: true });
+  };
+
+  const endSession = (): void => {
+    session = null;
+    target = null;
+  };
+
+  const abortSession = (): void => {
+    const activeSession = session;
+    const activeTarget = target;
+    try {
+      activeSession?.cancel();
+    } finally {
+      try {
+        activeTarget?.cancel();
+      } finally {
+        endSession();
+      }
+    }
+  };
+
+  return {
+    cursor: () => 'crosshair',
+    id: spec.id,
+    onDeactivate: (ctx, opts) => {
+      try {
+        if ((session || target) && !opts?.temporary) {
+          abortSession();
+        }
+      } finally {
+        ctx.setOverlayCursor(null);
+        ctx.invalidate({ overlay: true });
+      }
+    },
+    onPointerCancel: () => {
+      if (session || target) {
+        abortSession();
+      }
+    },
+    onPointerDown: (ctx, input) => {
+      if (session || (input.buttons & PRIMARY_BUTTON) === 0) {
+        return;
+      }
+      const resolvedTarget = resolveTarget(ctx);
+      updateCursorRing(ctx, input);
+      if (!resolvedTarget) {
+        return;
+      }
+      // Transparency lock: the eraser is refused (it would alter the locked alpha);
+      // the brush switches to `source-atop` so colour lands only on existing pixels.
+      if (resolvedTarget.transparencyLocked && spec.id === 'eraser') {
+        return;
+      }
+      const composite = resolvedTarget.transparencyLocked && spec.id === 'brush' ? 'source-atop' : spec.composite;
+      target = resolvedTarget;
+      try {
+        session = createStrokeSession({
+          // Resolve the selection clip ONCE per gesture: when a selection exists the
+          // stroke is masked to it; with none the field is null and the hot path is
+          // untouched (no per-point mask lookup).
+          clipMask: ctx.getSelectionMask?.() ?? null,
+          color: target.color ?? spec.color(ctx),
+          composite,
+          createdLayer: target.createdLayer ?? null,
+          ctx,
+          layerId: target.layerId,
+          // Mask strokes are forced opaque (an alpha stencil is all-or-nothing); a
+          // brush-opacity mask stroke would silently attenuate the denoise strength.
+          opacity: target.forceOpaque ? 1 : spec.opacity(ctx),
+          size: spec.size(ctx),
+          thinning: spec.thinning(ctx),
+          tool: spec.id,
+        });
+        session.addPoints([input]);
+      } catch {
+        abortSession();
+      }
+    },
+    onPointerMove: (ctx, input, batch) => {
+      updateCursorRing(ctx, input);
+      if (session) {
+        try {
+          session.addPoints(batch);
+        } catch (error) {
+          abortSession();
+          throw error;
+        }
+      }
+    },
+    onPointerUp: (ctx, input) => {
+      updateCursorRing(ctx, input);
+      if (session && target) {
+        const activeSession = session;
+        const activeTarget = target;
+        let event: StrokeCommittedEvent | null;
+        try {
+          event = activeSession.commit();
+        } catch (error) {
+          abortSession();
+          throw error;
+        }
+        endSession();
+        if (event) {
+          activeTarget.commit(event);
+        } else {
+          activeTarget.cancel();
+        }
+      }
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samHitTest.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samHitTest.test.ts
new file mode 100644
index 00000000000..d46e13ad0f3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samHitTest.test.ts
@@ -0,0 +1,93 @@
+import { identity, scale } from '@workbench/canvas-engine/math/mat2d';
+import { describe, expect, it } from 'vitest';
+
+import { clipPointToRect, clipRectToRect, moveSamBbox, rectFromPoints, resizeSamBbox, samHitTest } from './samHitTest';
+
+const source = { height: 80, width: 100, x: 10, y: 20 };
+
+describe('samHitTest', () => {
+  it.each([1, 4])('keeps point and bbox handle hit regions screen-constant at %sx zoom', (zoom) => {
+    const view = scale(identity(), zoom);
+    const point = { x: 30, y: 40 };
+    const bbox = { height: 30, width: 40, x: 40, y: 30 };
+
+    expect(
+      samHitTest({
+        bbox,
+        excludePoints: [],
+        includePoints: [point],
+        screenPoint: { x: point.x * zoom + 5, y: point.y * zoom },
+        view,
+      })
+    ).toEqual({ index: 0, kind: 'point', label: 'include' });
+    expect(
+      samHitTest({
+        bbox,
+        excludePoints: [],
+        includePoints: [],
+        screenPoint: { x: bbox.x * zoom + 5, y: bbox.y * zoom },
+        view,
+      })
+    ).toEqual({ handle: 'nw', kind: 'bbox-handle' });
+  });
+
+  it('prioritizes points, then handles, then the bbox body', () => {
+    const bbox = { height: 30, width: 40, x: 40, y: 30 };
+    const common = { bbox, excludePoints: [{ x: 40, y: 30 }], includePoints: [], view: identity() };
+
+    expect(samHitTest({ ...common, screenPoint: { x: 40, y: 30 } })).toEqual({
+      index: 0,
+      kind: 'point',
+      label: 'exclude',
+    });
+    expect(samHitTest({ ...common, excludePoints: [], screenPoint: { x: 80, y: 45 } })).toEqual({
+      handle: 'e',
+      kind: 'bbox-handle',
+    });
+    expect(samHitTest({ ...common, excludePoints: [], screenPoint: { x: 60, y: 45 } })).toEqual({
+      kind: 'bbox-body',
+    });
+    expect(samHitTest({ ...common, excludePoints: [], screenPoint: { x: 95, y: 70 } })).toBeNull();
+  });
+});
+
+describe('SAM bbox geometry', () => {
+  it('normalizes dragged corners and clips to the source export bounds', () => {
+    expect(rectFromPoints({ x: 120, y: 120 }, { x: 0, y: 0 }, source)).toEqual(source);
+    expect(clipRectToRect({ height: 30, width: 30, x: 100, y: 80 }, source)).toEqual({
+      height: 20,
+      width: 10,
+      x: 100,
+      y: 80,
+    });
+  });
+
+  it('clips points and bbox moves without changing bbox size', () => {
+    expect(clipPointToRect({ x: -5, y: 200 }, source)).toEqual({ x: 10, y: 99 });
+    expect(moveSamBbox({ height: 20, width: 30, x: 20, y: 30 }, 500, -500, source)).toEqual({
+      height: 20,
+      width: 30,
+      x: 80,
+      y: 20,
+    });
+  });
+
+  it('resizes from screen-constant handles and clamps to source bounds and one document pixel', () => {
+    expect(
+      resizeSamBbox({
+        bounds: source,
+        delta: { x: 100, y: 100 },
+        handle: 'nw',
+        start: { height: 30, width: 40, x: 40, y: 30 },
+      })
+    ).toEqual({ height: 1, width: 1, x: 79, y: 59 });
+    expect(
+      resizeSamBbox({
+        bounds: source,
+        delta: { x: 100, y: 100 },
+        handle: 'se',
+        start: { height: 30, width: 40, x: 40, y: 30 },
+      })
+    ).toEqual({ height: 70, width: 70, x: 40, y: 30 });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samHitTest.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samHitTest.ts
new file mode 100644
index 00000000000..463f1cd32b9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samHitTest.ts
@@ -0,0 +1,109 @@
+import type { Mat2d, Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+import { applyToPoint } from '@workbench/canvas-engine/math/mat2d';
+import { transformBounds } from '@workbench/canvas-engine/math/rect';
+import { canonicalizeDocumentSamPoint } from '@workbench/canvas-engine/samCoordinates';
+
+import { BBOX_HANDLES, bboxHandleAt, type BboxHandle, isInsideRect } from './bboxHitTest';
+
+export const SAM_POINT_HIT_RADIUS_PX = 8;
+export const SAM_BBOX_HANDLE_HIT_PX = 14;
+
+export type SamPointLabel = 'include' | 'exclude';
+
+export type SamHitTarget =
+  | { kind: 'point'; label: SamPointLabel; index: number }
+  | { kind: 'bbox-handle'; handle: BboxHandle }
+  | { kind: 'bbox-body' };
+
+export interface SamHitTestOptions {
+  view: Mat2d;
+  screenPoint: Vec2;
+  includePoints: readonly Vec2[];
+  excludePoints: readonly Vec2[];
+  bbox: Rect | null;
+}
+
+export const samHitTest = (options: SamHitTestOptions): SamHitTarget | null => {
+  for (const label of ['include', 'exclude'] as const) {
+    const points = label === 'include' ? options.includePoints : options.excludePoints;
+    for (let index = points.length - 1; index >= 0; index -= 1) {
+      const point = points[index];
+      if (!point) {
+        continue;
+      }
+      const screen = applyToPoint(options.view, point);
+      if (Math.hypot(options.screenPoint.x - screen.x, options.screenPoint.y - screen.y) <= SAM_POINT_HIT_RADIUS_PX) {
+        return { index, kind: 'point', label };
+      }
+    }
+  }
+
+  if (!options.bbox) {
+    return null;
+  }
+  const screenRect = transformBounds(options.view, options.bbox);
+  const handle = bboxHandleAt(screenRect, options.screenPoint, SAM_BBOX_HANDLE_HIT_PX);
+  if (handle) {
+    return { handle, kind: 'bbox-handle' };
+  }
+  return isInsideRect(screenRect, options.screenPoint) ? { kind: 'bbox-body' } : null;
+};
+
+const clamp = (value: number, min: number, max: number): number => Math.min(max, Math.max(min, value));
+
+export const clipPointToRect = (point: Vec2, bounds: Rect): Vec2 =>
+  canonicalizeDocumentSamPoint(point, bounds, true) ?? { x: bounds.x, y: bounds.y };
+
+export const clipRectToRect = (rect: Rect, bounds: Rect): Rect => {
+  const left = clamp(rect.x, bounds.x, bounds.x + bounds.width);
+  const top = clamp(rect.y, bounds.y, bounds.y + bounds.height);
+  const right = clamp(rect.x + rect.width, left, bounds.x + bounds.width);
+  const bottom = clamp(rect.y + rect.height, top, bounds.y + bounds.height);
+  return { height: bottom - top, width: right - left, x: left, y: top };
+};
+
+export const rectFromPoints = (start: Vec2, end: Vec2, bounds: Rect): Rect =>
+  clipRectToRect(
+    {
+      height: Math.abs(end.y - start.y),
+      width: Math.abs(end.x - start.x),
+      x: Math.min(start.x, end.x),
+      y: Math.min(start.y, end.y),
+    },
+    bounds
+  );
+
+export const moveSamBbox = (start: Rect, dx: number, dy: number, bounds: Rect): Rect => ({
+  height: start.height,
+  width: start.width,
+  x: clamp(start.x + dx, bounds.x, bounds.x + bounds.width - start.width),
+  y: clamp(start.y + dy, bounds.y, bounds.y + bounds.height - start.height),
+});
+
+const hasWest = (handle: BboxHandle): boolean => BBOX_HANDLES.includes(handle) && handle.includes('w');
+const hasEast = (handle: BboxHandle): boolean => handle.includes('e');
+const hasNorth = (handle: BboxHandle): boolean => handle.includes('n');
+const hasSouth = (handle: BboxHandle): boolean => handle.includes('s');
+
+export const resizeSamBbox = (options: { start: Rect; handle: BboxHandle; delta: Vec2; bounds: Rect }): Rect => {
+  const { bounds, delta, handle, start } = options;
+  let left = start.x;
+  let top = start.y;
+  let right = start.x + start.width;
+  let bottom = start.y + start.height;
+
+  if (hasWest(handle)) {
+    left = clamp(start.x + delta.x, bounds.x, right - 1);
+  }
+  if (hasEast(handle)) {
+    right = clamp(start.x + start.width + delta.x, left + 1, bounds.x + bounds.width);
+  }
+  if (hasNorth(handle)) {
+    top = clamp(start.y + delta.y, bounds.y, bottom - 1);
+  }
+  if (hasSouth(handle)) {
+    bottom = clamp(start.y + start.height + delta.y, top + 1, bounds.y + bounds.height);
+  }
+  return { height: bottom - top, width: right - left, x: left, y: top };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samTool.test.ts
new file mode 100644
index 00000000000..e36bd5fa6db
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samTool.test.ts
@@ -0,0 +1,184 @@
+import type { PointerInput } from '@workbench/canvas-engine/types';
+import type { SamSessionSnapshot } from '@workbench/canvas-operations/operationTypes';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { createCanvasOperationStores } from '@workbench/canvas-operations/operationStores';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ToolContext } from './tool';
+
+import { createSamTool } from './samTool';
+
+const sourceRect = { height: 100, width: 100, x: 0, y: 0 };
+
+const visualSnapshot = (overrides: Partial<SamSessionSnapshot> = {}): SamSessionSnapshot => ({
+  applyPolygonRefinement: false,
+  autoProcess: false,
+  error: null,
+  hasPreview: false,
+  input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' },
+  invert: false,
+  isolatedPreview: true,
+  layerName: 'Layer 1',
+  layerType: 'raster',
+  model: 'segment-anything-2-large',
+  pointLabel: 'include',
+  sourceRect,
+  status: 'ready',
+  ...overrides,
+});
+
+const pointer = (x: number, y: number, options: { buttons?: number; shift?: boolean } = {}): PointerInput => ({
+  buttons: options.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: options.shift ?? false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+const createHarness = (snapshot = visualSnapshot()) => {
+  const stores = createEngineStores();
+  const operationStores = createCanvasOperationStores();
+  operationStores.samSession.set(snapshot);
+  const invalidate = vi.fn();
+  const updateSamInput = vi.fn((input: SamSessionSnapshot['input']) => {
+    const current = operationStores.samSession.get();
+    if (current) {
+      operationStores.samSession.set({ ...current, input });
+    }
+  });
+  const ctx = {
+    getSamInteraction: () => {
+      const current = operationStores.samSession.get();
+      return current?.input.type === 'visual'
+        ? { input: current.input, pointLabel: current.pointLabel, sourceRect: current.sourceRect }
+        : null;
+    },
+    invalidate,
+    stores,
+    updateCursor: vi.fn(),
+    updateSamInput,
+    viewport: {
+      documentToScreen: (point: { x: number; y: number }) => point,
+      viewMatrix: () => ({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 }),
+    },
+  } as unknown as ToolContext;
+  return { ctx, invalidate, operationStores, stores, tool: createSamTool(), updateSamInput };
+};
+
+const down = (h: ReturnType<typeof createHarness>, input: PointerInput): void => h.tool.onPointerDown?.(h.ctx, input);
+const move = (h: ReturnType<typeof createHarness>, input: PointerInput): void =>
+  h.tool.onPointerMove?.(h.ctx, input, [input]);
+const up = (h: ReturnType<typeof createHarness>, input: PointerInput): void => h.tool.onPointerUp?.(h.ctx, input);
+
+describe('createSamTool', () => {
+  it('adds configured points on click and temporarily flips their label with Shift', () => {
+    const h = createHarness();
+
+    down(h, pointer(20, 30));
+    up(h, pointer(20, 30, { buttons: 0 }));
+    down(h, pointer(50, 60, { shift: true }));
+    up(h, pointer(50, 60, { buttons: 0, shift: true }));
+
+    expect(h.operationStores.samSession.get()?.input).toEqual({
+      bbox: null,
+      excludePoints: [{ x: 50, y: 60 }],
+      includePoints: [{ x: 20, y: 30 }],
+      type: 'visual',
+    });
+    expect(h.invalidate.mock.calls.every(([payload]) => payload.overlay === true && !payload.all)).toBe(true);
+  });
+
+  it('removes an existing point on click but drags it after the screen threshold', () => {
+    const h = createHarness(
+      visualSnapshot({
+        input: { bbox: null, excludePoints: [], includePoints: [{ x: 20, y: 20 }], type: 'visual' },
+      })
+    );
+
+    down(h, pointer(20, 20));
+    up(h, pointer(20, 20, { buttons: 0 }));
+    expect(h.operationStores.samSession.get()?.input.includePoints).toEqual([]);
+
+    h.operationStores.samSession.set(
+      visualSnapshot({ input: { bbox: null, excludePoints: [], includePoints: [{ x: 20, y: 20 }], type: 'visual' } })
+    );
+    down(h, pointer(20, 20));
+    move(h, pointer(21, 21));
+    expect(h.operationStores.samSession.get()?.input.includePoints).toEqual([{ x: 20, y: 20 }]);
+    move(h, pointer(35, 40));
+    up(h, pointer(35, 40, { buttons: 0 }));
+    expect(h.operationStores.samSession.get()?.input.includePoints).toEqual([{ x: 35, y: 40 }]);
+  });
+
+  it('creates a clipped bbox from an empty drag and treats a sub-threshold drag as a click', () => {
+    const h = createHarness();
+
+    down(h, pointer(80, 80));
+    move(h, pointer(120, 130));
+    up(h, pointer(120, 130, { buttons: 0 }));
+    expect(h.operationStores.samSession.get()?.input.bbox).toEqual({ height: 20, width: 20, x: 80, y: 80 });
+
+    down(h, pointer(10, 10));
+    move(h, pointer(12, 12));
+    up(h, pointer(12, 12, { buttons: 0 }));
+    expect(h.operationStores.samSession.get()?.input.includePoints).toEqual([{ x: 12, y: 12 }]);
+  });
+
+  it('does not publish a degenerate bbox when a boundary drag clips to zero area', () => {
+    const h = createHarness();
+
+    down(h, pointer(100, 100));
+    move(h, pointer(120, 130));
+    up(h, pointer(120, 130, { buttons: 0 }));
+
+    expect(h.operationStores.samSession.get()?.input.bbox).toBeNull();
+  });
+
+  it('accepts and canonicalizes a near-edge point but rejects the exact right and bottom edges', () => {
+    const h = createHarness();
+
+    down(h, pointer(99.8, 99.6));
+    up(h, pointer(99.8, 99.6, { buttons: 0 }));
+    down(h, pointer(100, 50));
+    up(h, pointer(100, 50, { buttons: 0 }));
+    down(h, pointer(50, 100));
+    up(h, pointer(50, 100, { buttons: 0 }));
+
+    expect(h.operationStores.samSession.get()?.input.includePoints).toEqual([{ x: 99, y: 99 }]);
+  });
+
+  it('moves the bbox body and resizes a handle while clipping to source bounds', () => {
+    const h = createHarness(
+      visualSnapshot({
+        input: { bbox: { height: 30, width: 40, x: 20, y: 20 }, excludePoints: [], includePoints: [], type: 'visual' },
+      })
+    );
+
+    down(h, pointer(40, 35));
+    move(h, pointer(90, 90));
+    up(h, pointer(90, 90, { buttons: 0 }));
+    expect(h.operationStores.samSession.get()?.input.bbox).toEqual({ height: 30, width: 40, x: 60, y: 70 });
+
+    down(h, pointer(100, 100));
+    move(h, pointer(150, 150));
+    up(h, pointer(150, 150, { buttons: 0 }));
+    expect(h.operationStores.samSession.get()?.input.bbox).toEqual({ height: 30, width: 40, x: 60, y: 70 });
+  });
+
+  it('restores the exact pre-gesture input on pointercancel', () => {
+    const initial = visualSnapshot({
+      input: { bbox: null, excludePoints: [{ x: 10, y: 10 }], includePoints: [], type: 'visual' },
+    });
+    const h = createHarness(initial);
+
+    down(h, pointer(10, 10));
+    move(h, pointer(50, 50));
+    expect(h.operationStores.samSession.get()?.input.excludePoints).toEqual([{ x: 50, y: 50 }]);
+    h.tool.onPointerCancel?.(h.ctx);
+
+    expect(h.operationStores.samSession.get()?.input).toEqual(initial.input);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samTool.ts
new file mode 100644
index 00000000000..93deef28c5f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/samTool.ts
@@ -0,0 +1,144 @@
+import type { SamVisualInput } from '@workbench/canvas-engine/samInteraction';
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+
+import { canonicalizeDocumentSamPoint } from '@workbench/canvas-engine/samCoordinates';
+
+import type { SamHitTarget } from './samHitTest';
+import type { Tool, ToolContext } from './tool';
+
+import { clipPointToRect, moveSamBbox, rectFromPoints, resizeSamBbox, samHitTest } from './samHitTest';
+
+const PRIMARY_BUTTON = 1;
+export const SAM_DRAG_THRESHOLD_PX = 3;
+
+interface GestureState {
+  startDoc: Vec2;
+  startScreen: Vec2;
+  startInput: SamVisualInput;
+  target: SamHitTarget | null;
+  moved: boolean;
+}
+
+const cloneInput = (input: SamVisualInput): SamVisualInput => ({
+  bbox: input.bbox ? { ...input.bbox } : null,
+  excludePoints: input.excludePoints.map((point) => ({ ...point })),
+  includePoints: input.includePoints.map((point) => ({ ...point })),
+  type: 'visual',
+});
+
+const flippedLabel = (label: 'include' | 'exclude'): 'include' | 'exclude' =>
+  label === 'include' ? 'exclude' : 'include';
+
+export const createSamTool = (): Tool => {
+  let gesture: GestureState | null = null;
+
+  const publish = (ctx: ToolContext, input: SamVisualInput): void => {
+    ctx.updateSamInput?.(input);
+    ctx.invalidate({ overlay: true });
+  };
+
+  const updateGesture = (ctx: ToolContext, input: PointerInput, state: GestureState): void => {
+    const snapshot = ctx.getSamInteraction?.();
+    if (!snapshot || snapshot.input.type !== 'visual') {
+      return;
+    }
+    const next = cloneInput(state.startInput);
+    const delta = {
+      x: input.documentPoint.x - state.startDoc.x,
+      y: input.documentPoint.y - state.startDoc.y,
+    };
+
+    if (state.target?.kind === 'point') {
+      const points = state.target.label === 'include' ? next.includePoints : next.excludePoints;
+      points[state.target.index] = clipPointToRect(input.documentPoint, snapshot.sourceRect);
+    } else if (state.target?.kind === 'bbox-body' && next.bbox) {
+      next.bbox = moveSamBbox(next.bbox, delta.x, delta.y, snapshot.sourceRect);
+    } else if (state.target?.kind === 'bbox-handle' && next.bbox) {
+      next.bbox = resizeSamBbox({ bounds: snapshot.sourceRect, delta, handle: state.target.handle, start: next.bbox });
+    } else {
+      const created = rectFromPoints(state.startDoc, input.documentPoint, snapshot.sourceRect);
+      next.bbox = created.width >= 1 && created.height >= 1 ? created : state.startInput.bbox;
+    }
+    publish(ctx, next);
+  };
+
+  const cancelGesture = (ctx: ToolContext): void => {
+    const current = gesture;
+    gesture = null;
+    if (current?.moved) {
+      publish(ctx, cloneInput(current.startInput));
+    }
+  };
+
+  return {
+    cursor: () => 'crosshair',
+    id: 'sam',
+    onDeactivate: (ctx) => cancelGesture(ctx),
+    onPointerCancel: (ctx) => cancelGesture(ctx),
+    onPointerDown: (ctx, input) => {
+      const snapshot = ctx.getSamInteraction?.();
+      if (
+        gesture ||
+        !snapshot ||
+        snapshot.input.type !== 'visual' ||
+        (input.buttons & PRIMARY_BUTTON) === 0 ||
+        !canonicalizeDocumentSamPoint(input.documentPoint, snapshot.sourceRect)
+      ) {
+        return;
+      }
+      gesture = {
+        moved: false,
+        startDoc: input.documentPoint,
+        startInput: cloneInput(snapshot.input),
+        startScreen: input.screenPoint,
+        target: samHitTest({
+          bbox: snapshot.input.bbox,
+          excludePoints: snapshot.input.excludePoints,
+          includePoints: snapshot.input.includePoints,
+          screenPoint: input.screenPoint,
+          view: ctx.viewport.viewMatrix(1),
+        }),
+      };
+    },
+    onPointerMove: (ctx, input) => {
+      if (!gesture) {
+        return;
+      }
+      if (!gesture.moved) {
+        const dx = input.screenPoint.x - gesture.startScreen.x;
+        const dy = input.screenPoint.y - gesture.startScreen.y;
+        if (Math.hypot(dx, dy) < SAM_DRAG_THRESHOLD_PX) {
+          return;
+        }
+        gesture.moved = true;
+      }
+      updateGesture(ctx, input, gesture);
+    },
+    onPointerUp: (ctx, input) => {
+      const current = gesture;
+      gesture = null;
+      if (!current) {
+        return;
+      }
+      if (current.moved) {
+        updateGesture(ctx, input, current);
+        return;
+      }
+
+      const snapshot = ctx.getSamInteraction?.();
+      if (!snapshot || snapshot.input.type !== 'visual') {
+        return;
+      }
+      const next = cloneInput(current.startInput);
+      if (current.target?.kind === 'point') {
+        const points = current.target.label === 'include' ? next.includePoints : next.excludePoints;
+        points.splice(current.target.index, 1);
+      } else {
+        const label = input.modifiers.shift ? flippedLabel(snapshot.pointLabel) : snapshot.pointLabel;
+        const points = label === 'include' ? next.includePoints : next.excludePoints;
+        points.push(clipPointToRect(input.documentPoint, snapshot.sourceRect));
+      }
+      publish(ctx, next);
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/shapeTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/shapeTool.test.ts
new file mode 100644
index 00000000000..cfa876f32ec
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/shapeTool.test.ts
@@ -0,0 +1,191 @@
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+import type { Viewport } from '@workbench/canvas-engine/viewport';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2 } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createShapeTool, rectFromDrag } from './shapeTool';
+
+const makeDoc = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 96, width: 96, x: 0, y: 0 },
+  height: 512,
+  layers: [],
+  selectedLayerId: null,
+  version: 2,
+  width: 512,
+});
+
+const identityViewport = {
+  documentToScreen: (p: Vec2): Vec2 => ({ x: p.x, y: p.y }),
+} as unknown as Viewport;
+
+const pointer = (x: number, y: number, opts: { shift?: boolean; buttons?: number } = {}): PointerInput => ({
+  buttons: opts.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: opts.shift ?? false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+interface StructuralCommit {
+  label: string;
+  forward: CanvasProjectMutation;
+  inverse: CanvasProjectMutation;
+}
+
+const createHarness = (doc: CanvasDocumentContractV2) => {
+  const dispatched: CanvasProjectMutation[] = [];
+  const commits: StructuralCommit[] = [];
+  const stores = createEngineStores();
+  let idCounter = 0;
+  const ctx: ToolContext = {
+    backend: null as never,
+    commitStructural: (label, forward, inverse) => commits.push({ forward, inverse, label }),
+    createLayerId: () => `shape-${++idCounter}`,
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    dispatch: (action) => dispatched.push(action),
+    emitStrokeCommitted: vi.fn(),
+    getDocument: () => doc,
+    invalidate: vi.fn(),
+    layers: null as never,
+    notifyLayerPainted: vi.fn(),
+    setLayerTransformOverride: vi.fn(),
+    setOverlayCursor: vi.fn(),
+    stores,
+    updateCursor: vi.fn(),
+    viewport: identityViewport,
+  };
+  return { commits, ctx, dispatched, previewOf: () => stores.shapePreview.get(), stores };
+};
+
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerMove?.(ctx, i, [i]);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+
+describe('rectFromDrag', () => {
+  it('normalizes a drag to a positive integer rect', () => {
+    expect(rectFromDrag({ x: 50, y: 60 }, { x: 20, y: 100 }, false)).toEqual({
+      height: 40,
+      width: 30,
+      x: 20,
+      y: 60,
+    });
+  });
+
+  it('constrains to a square using the larger dimension, preserving direction', () => {
+    expect(rectFromDrag({ x: 0, y: 0 }, { x: 30, y: 80 }, true)).toEqual({ height: 80, width: 80, x: 0, y: 0 });
+    // Dragging up-left: the square extends toward negative both axes.
+    expect(rectFromDrag({ x: 100, y: 100 }, { x: 70, y: 20 }, true)).toEqual({
+      height: 80,
+      width: 80,
+      x: 20,
+      y: 20,
+    });
+  });
+});
+
+describe('shape tool: creation', () => {
+  it('previews on move then commits ONE addCanvasLayer on up', () => {
+    const h = createHarness(makeDoc());
+    const tool = createShapeTool();
+
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(70, 50));
+    expect(h.previewOf()).toEqual({ kind: 'rect', rect: { height: 40, width: 60, x: 10, y: 10 } });
+
+    up(tool, h.ctx, pointer(70, 50));
+
+    // Creation goes through commitStructural (undoable), never a bare dispatch.
+    expect(h.dispatched).toHaveLength(0);
+    expect(h.commits).toHaveLength(1);
+    const forward = h.commits[0]?.forward;
+    expect(forward?.type).toBe('addCanvasLayer');
+    if (forward?.type === 'addCanvasLayer' && forward.layer.type === 'raster') {
+      expect(forward.layer.source).toEqual({
+        fill: '#000000',
+        height: 40,
+        kind: 'rect',
+        stroke: null,
+        strokeWidth: 8,
+        type: 'shape',
+        width: 60,
+      });
+      expect(forward.layer.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 10 });
+    }
+    // Inverse removes the created layer.
+    expect(h.commits[0]?.inverse).toEqual({ ids: ['shape-1'], type: 'removeCanvasLayers' });
+    expect(h.previewOf()).toBeNull();
+  });
+
+  it('uses the shape options kind/fill/stroke for the created layer', () => {
+    const h = createHarness(makeDoc());
+    h.stores.shapeOptions.set({ fill: '#ff0000', kind: 'ellipse', stroke: '#0000ff', strokeWidth: 4 });
+    const tool = createShapeTool();
+
+    down(tool, h.ctx, pointer(0, 0));
+    move(tool, h.ctx, pointer(100, 100));
+    up(tool, h.ctx, pointer(100, 100));
+
+    const forward = h.commits[0]?.forward;
+    if (
+      forward?.type === 'addCanvasLayer' &&
+      forward.layer.type === 'raster' &&
+      forward.layer.source.type === 'shape'
+    ) {
+      expect(forward.layer.source.kind).toBe('ellipse');
+      expect(forward.layer.source.fill).toBe('#ff0000');
+      expect(forward.layer.source.stroke).toBe('#0000ff');
+      expect(forward.layer.source.strokeWidth).toBe(4);
+    } else {
+      throw new Error('expected an ellipse shape layer');
+    }
+  });
+
+  it('constrains to a square while shift is held', () => {
+    const h = createHarness(makeDoc());
+    const tool = createShapeTool();
+    down(tool, h.ctx, pointer(0, 0, { shift: true }));
+    move(tool, h.ctx, pointer(30, 80, { shift: true }));
+    up(tool, h.ctx, pointer(30, 80, { shift: true }));
+    const forward = h.commits[0]?.forward;
+    if (
+      forward?.type === 'addCanvasLayer' &&
+      forward.layer.type === 'raster' &&
+      forward.layer.source.type === 'shape'
+    ) {
+      expect(forward.layer.source.width).toBe(80);
+      expect(forward.layer.source.height).toBe(80);
+    } else {
+      throw new Error('expected a shape layer');
+    }
+  });
+
+  it('commits nothing for a zero-area drag', () => {
+    const h = createHarness(makeDoc());
+    const tool = createShapeTool();
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(10, 10));
+    up(tool, h.ctx, pointer(10, 10));
+    expect(h.commits).toHaveLength(0);
+    expect(h.previewOf()).toBeNull();
+  });
+
+  it('escape (cancel key command) drops the gesture without committing', () => {
+    const h = createHarness(makeDoc());
+    const tool = createShapeTool();
+    down(tool, h.ctx, pointer(10, 10));
+    move(tool, h.ctx, pointer(70, 50));
+    expect(h.previewOf()).not.toBeNull();
+    tool.onKeyCommand?.(h.ctx, 'cancel');
+    expect(h.previewOf()).toBeNull();
+    // A subsequent up does nothing (gesture already dropped).
+    up(tool, h.ctx, pointer(70, 50));
+    expect(h.commits).toHaveLength(0);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/shapeTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/shapeTool.ts
new file mode 100644
index 00000000000..5bee9a84d06
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/shapeTool.ts
@@ -0,0 +1,159 @@
+/**
+ * The shape tool: drag on the canvas to CREATE a new shape layer sized by the
+ * drag rect. Scope is creation-only — dragging never edits an existing shape
+ * (param edits happen through the options bar and the transform tool).
+ *
+ * Interaction contract (CANVAS_PLAN Phase 6.1):
+ * - **Pointer-down** (primary button) starts a gesture at the press point.
+ * - **Pointer-move** (past a small threshold) updates a transient overlay
+ *   preview rect (`stores.shapePreview`) — it never dispatches. Hold **shift**
+ *   to constrain to a square/circle.
+ * - **Commit** (pointer-up after a real drag): exactly one `commitStructural`
+ *   whose forward is `addCanvasLayer` (a shape source sized to the rect, placed
+ *   at the rect origin) and whose inverse is `removeCanvasLayers` — so undo
+ *   removes the created layer. A zero-area drag commits nothing.
+ * - **Cancel** (Esc / pointercancel): drops the preview, no dispatch.
+ *
+ * The selection mask does NOT constrain shape creation — a shape layer is a
+ * parametric object, not a pixel edit into an existing layer.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import type { Tool, ToolContext } from './tool';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/** Screen-space distance (CSS px) the pointer must travel before a press becomes a drag. */
+export const SHAPE_DRAG_THRESHOLD_PX = 3;
+
+interface GestureState {
+  startDoc: Vec2;
+  startScreen: Vec2;
+  moved: boolean;
+}
+
+/** The integer, normalized document rect for a drag from `start` to `end`, optionally square-constrained. */
+export const rectFromDrag = (start: Vec2, end: Vec2, square: boolean): Rect => {
+  let dx = end.x - start.x;
+  let dy = end.y - start.y;
+  if (square) {
+    const side = Math.max(Math.abs(dx), Math.abs(dy));
+    dx = (dx < 0 ? -1 : 1) * side;
+    dy = (dy < 0 ? -1 : 1) * side;
+  }
+  const x = Math.round(Math.min(start.x, start.x + dx));
+  const y = Math.round(Math.min(start.y, start.y + dy));
+  return { height: Math.round(Math.abs(dy)), width: Math.round(Math.abs(dx)), x, y };
+};
+
+/** Creates a fresh shape tool with its own gesture state. */
+export const createShapeTool = (): Tool => {
+  let state: GestureState | null = null;
+
+  const clearPreview = (ctx: ToolContext): void => {
+    ctx.stores.shapePreview.set(null);
+    ctx.invalidate({ overlay: true });
+  };
+
+  return {
+    cursor: () => 'crosshair',
+    id: 'shape',
+    onDeactivate: (ctx) => {
+      state = null;
+      clearPreview(ctx);
+    },
+    onKeyCommand: (ctx, command) => {
+      if (command === 'cancel' && state) {
+        state = null;
+        clearPreview(ctx);
+      }
+    },
+    onPointerCancel: (ctx) => {
+      state = null;
+      clearPreview(ctx);
+    },
+    onPointerDown: (ctx, input) => {
+      if (state || (input.buttons & PRIMARY_BUTTON) === 0) {
+        return;
+      }
+      if (!ctx.getDocument()) {
+        return;
+      }
+      state = { moved: false, startDoc: input.documentPoint, startScreen: input.screenPoint };
+    },
+    onPointerMove: (ctx, input) => {
+      if (!state) {
+        return;
+      }
+      if (!state.moved) {
+        const dxs = input.screenPoint.x - state.startScreen.x;
+        const dys = input.screenPoint.y - state.startScreen.y;
+        if (Math.hypot(dxs, dys) < SHAPE_DRAG_THRESHOLD_PX) {
+          return;
+        }
+        state.moved = true;
+      }
+      const rect = rectFromDrag(state.startDoc, input.documentPoint, input.modifiers.shift);
+      ctx.stores.shapePreview.set({ kind: ctx.stores.shapeOptions.get().kind, rect });
+      ctx.invalidate({ overlay: true });
+    },
+    onPointerUp: (ctx, input) => {
+      if (!state) {
+        return;
+      }
+      const current = state;
+      state = null;
+
+      if (!current.moved) {
+        clearPreview(ctx);
+        return;
+      }
+
+      const rect = rectFromDrag(current.startDoc, input.documentPoint, input.modifiers.shift);
+      if (rect.width < 1 || rect.height < 1) {
+        // Degenerate drag: nothing to create.
+        clearPreview(ctx);
+        return;
+      }
+
+      const doc = ctx.getDocument();
+      if (!doc) {
+        clearPreview(ctx);
+        return;
+      }
+
+      const options = ctx.stores.shapeOptions.get();
+      const layerId = ctx.createLayerId();
+      const layer: CanvasRasterLayerContractV2 = {
+        blendMode: 'normal',
+        id: layerId,
+        isEnabled: true,
+        isLocked: false,
+        name: `Shape ${doc.layers.length + 1}`,
+        opacity: 1,
+        source: {
+          fill: options.fill,
+          height: rect.height,
+          kind: options.kind,
+          stroke: options.stroke,
+          strokeWidth: options.strokeWidth,
+          type: 'shape',
+          width: rect.width,
+        },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: rect.x, y: rect.y },
+        type: 'raster',
+      };
+
+      const forward: CanvasProjectMutation = { index: 0, layer, type: 'addCanvasLayer' };
+      const inverse: CanvasProjectMutation = { ids: [layerId], type: 'removeCanvasLayers' };
+      ctx.commitStructural('Add shape', forward, inverse);
+      clearPreview(ctx);
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/strokeSession.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/strokeSession.test.ts
new file mode 100644
index 00000000000..6304b3a82ac
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/strokeSession.test.ts
@@ -0,0 +1,282 @@
+import type { LayerCacheEntry } from '@workbench/canvas-engine/render/layerCache';
+import type { StubRasterBackend, StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type { ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput } from '@workbench/canvas-engine/types';
+
+import { createLayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { createStrokeSession } from '@workbench/canvas-engine/tools/strokeSession';
+import { describe, expect, it, vi } from 'vitest';
+
+const pointer = (x: number, y: number): PointerInput => ({
+  buttons: 1,
+  documentPoint: { x, y },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+/** A capturing backend so the stroke scratch surface can be identified. */
+const createCapturingBackend = (): { backend: StubRasterBackend; created: StubRasterSurface[] } => {
+  const inner = createTestStubRasterBackend();
+  const created: StubRasterSurface[] = [];
+  return {
+    backend: {
+      ...inner,
+      createSurface: (w, h) => {
+        const s = inner.createSurface(w, h);
+        created.push(s);
+        return s;
+      },
+    },
+    created,
+  };
+};
+
+const runStroke = (opts: { withMask: boolean }) => {
+  const { backend, created } = createCapturingBackend();
+  const layers = createLayerCacheStore(backend);
+  const entry: LayerCacheEntry = layers.getOrCreate('L', 100, 100);
+  const mask = opts.withMask ? backend.createSurface(100, 100) : null;
+  const clipMask = mask ? { rect: { height: 100, width: 100, x: 0, y: 0 }, surface: mask } : null;
+  const emitStrokeCommitted = vi.fn();
+  const notifyLayerPainted = vi.fn();
+
+  const ctx = {
+    backend,
+    createPath2D: (d?: string) => ({ d }) as unknown as Path2D,
+    emitStrokeCommitted,
+    invalidate: vi.fn(),
+    layers,
+    notifyLayerPainted,
+  } as unknown as ToolContext;
+
+  // Only the scratch is created after this point.
+  created.length = 0;
+  const session = createStrokeSession({
+    clipMask,
+    color: '#ff0000',
+    composite: 'source-over',
+    ctx,
+    layerId: 'L',
+    opacity: 1,
+    size: 20,
+    thinning: 0,
+    tool: 'brush',
+  });
+  session.addPoints([pointer(10, 10)]);
+  session.addPoints([pointer(40, 10), pointer(40, 40)]);
+  const event = session.commit();
+
+  const scratch = created[0]!;
+  return { cache: entry.surface as StubRasterSurface, emitStrokeCommitted, event, notifyLayerPainted, scratch };
+};
+
+const compositeOps = (surface: StubRasterSurface): unknown[] =>
+  surface.callLog.filter((e) => e.op === 'set' && e.args[0] === 'globalCompositeOperation').map((e) => e.args[1]);
+
+describe('strokeSession: selection-constrained painting', () => {
+  it('with a clip mask, intersects the scratch stroke with the mask (destination-in) before compositing', () => {
+    const { scratch } = runStroke({ withMask: true });
+    expect(compositeOps(scratch)).toContain('destination-in');
+    // The mask is drawn into the scratch to clip it.
+    expect(scratch.callLog.some((e) => e.op === 'drawImage')).toBe(true);
+  });
+
+  it('without a clip mask, the scratch stays a plain filled stroke (no extra clip ops)', () => {
+    const { scratch } = runStroke({ withMask: false });
+    expect(compositeOps(scratch)).not.toContain('destination-in');
+    expect(scratch.callLog.some((e) => e.op === 'drawImage')).toBe(false);
+    expect(scratch.callLog.filter((e) => e.op === 'fill')).not.toHaveLength(0);
+  });
+
+  it('applies the selection clip on the scratch, not by changing the cache composite ops', () => {
+    const withMask = runStroke({ withMask: true });
+    const noMask = runStroke({ withMask: false });
+    // The clip is a `destination-in` on the SCRATCH; the layer-cache composite op
+    // sequence (source-over blit of the clipped stroke) is unchanged — the clip
+    // never adds a mask op to the cache itself. (The cache's content EXTENT can
+    // differ: without a selection the cache grows to the stroke's true bounds,
+    // while a selection bounds the growth to the mask — content-sized behavior.)
+    expect(compositeOps(withMask.cache)).toEqual(compositeOps(noMask.cache));
+    expect(compositeOps(withMask.cache)).not.toContain('destination-in');
+  });
+
+  it('returns a commit with a dirty rect the mask does not shift', () => {
+    const { event } = runStroke({ withMask: true });
+    expect(event!.dirtyRect.width).toBeGreaterThan(0);
+    expect(event!.dirtyRect.height).toBeGreaterThan(0);
+  });
+});
+
+describe('strokeSession: content-sized cache growth', () => {
+  const makeSession = (initialRect: { x: number; y: number; width: number; height: number }) => {
+    const { backend } = createCapturingBackend();
+    const layers = createLayerCacheStore(backend);
+    const entry = layers.getOrCreateRect('L', initialRect);
+    entry.stale = false;
+    const emitStrokeCommitted = vi.fn();
+    const notifyLayerPainted = vi.fn();
+    const ctx = {
+      backend,
+      createPath2D: (d?: string) => ({ d }) as unknown as Path2D,
+      emitStrokeCommitted,
+      invalidate: vi.fn(),
+      layers,
+      notifyLayerPainted,
+    } as unknown as ToolContext;
+    const session = createStrokeSession({
+      clipMask: null,
+      color: '#ff0000',
+      composite: 'source-over',
+      ctx,
+      layerId: 'L',
+      opacity: 1,
+      size: 20,
+      thinning: 0,
+      tool: 'brush',
+    });
+    return { emitStrokeCommitted, entry, notifyLayerPainted, session };
+  };
+
+  it('grows an EMPTY (brand-new) paint cache to the stroke bounds on the first stroke', () => {
+    const { entry, session } = makeSession({ height: 0, width: 0, x: 0, y: 0 });
+    session.addPoints([pointer(50, 60)]);
+    const event = session.commit();
+
+    // The cache adopted the stroke's content bounds, snapped OUTWARD to the 64px
+    // growth-chunk grid — still content-sized (a couple of chunks), NOT an
+    // origin-anchored document-sized surface. A size-20 dab at (50,60) sits roughly
+    // at [40,60]×[50,70], which chunk-pads to a small chunk-aligned rect.
+    expect(entry.rect.width).toBeGreaterThan(0);
+    expect(entry.rect.height).toBeGreaterThan(0);
+    // Chunk-aligned extent (origin and size are multiples of the 64px chunk).
+    expect(entry.rect.x % 64).toBe(0);
+    expect(entry.rect.y % 64).toBe(0);
+    expect(entry.rect.width % 64).toBe(0);
+    expect(entry.rect.height % 64).toBe(0);
+    // Content-sized: a few chunks around the dab, not a huge (document) surface.
+    expect(entry.rect.width).toBeLessThanOrEqual(128);
+    expect(entry.rect.height).toBeLessThanOrEqual(128);
+    // The padded extent still fully contains the painted dab center (50,60).
+    expect(entry.rect.x).toBeLessThanOrEqual(50);
+    expect(entry.rect.x + entry.rect.width).toBeGreaterThan(50);
+    expect(entry.rect.y).toBeLessThanOrEqual(60);
+    expect(entry.rect.y + entry.rect.height).toBeGreaterThan(60);
+    expect(entry.surface.width).toBe(entry.rect.width);
+    expect(entry.surface.height).toBe(entry.rect.height);
+    // The committed dirty rect is the same (chunk-padded) layer-local region.
+    expect(event!.dirtyRect).toEqual(entry.rect);
+  });
+
+  it('returns the completed event without publishing engine side effects', () => {
+    const { emitStrokeCommitted, notifyLayerPainted, session } = makeSession({ height: 0, width: 0, x: 0, y: 0 });
+    session.addPoints([pointer(10, 10)]);
+    const event = session.commit();
+
+    expect(event).toMatchObject({ layerId: 'L', tool: 'brush' });
+    expect(event!.dirtyRect.width).toBeGreaterThan(0);
+    expect(event!.dirtyRect.height).toBeGreaterThan(0);
+    expect(emitStrokeCommitted).not.toHaveBeenCalled();
+    expect(notifyLayerPainted).not.toHaveBeenCalled();
+  });
+
+  it('returns null when the gesture produced no dirty pixels', () => {
+    const { session } = makeSession({ height: 0, width: 0, x: 0, y: 0 });
+    expect(session.commit()).toBeNull();
+  });
+
+  it('grows an existing cache to the UNION of its extent and an out-of-extent stroke (negative coords included)', () => {
+    const { entry, session } = makeSession({ height: 20, width: 20, x: 0, y: 0 });
+    session.addPoints([pointer(-40, -40)]);
+    session.commit();
+
+    // Union of the pre-stroke [0,20)² extent and the stroke bounds around
+    // (-40,-40): the origin moved into negative layer-local space and the old
+    // extent's far edge is still covered.
+    expect(entry.rect.x).toBeLessThan(-30);
+    expect(entry.rect.y).toBeLessThan(-30);
+    expect(entry.rect.x + entry.rect.width).toBeGreaterThanOrEqual(20);
+    expect(entry.rect.y + entry.rect.height).toBeGreaterThanOrEqual(20);
+    expect(entry.surface.width).toBe(entry.rect.width);
+    expect(entry.surface.height).toBe(entry.rect.height);
+  });
+
+  it('reallocates the cache surface O(stroke / chunk) times — NOT once per batch — across an extending drag', () => {
+    // Pre-size the cache to a chunk-aligned rect already covering the first dab, so
+    // only genuine growth (not the empty-cache adoption) counts as a reallocation.
+    const { entry, session } = makeSession({ height: 64, width: 64, x: 64, y: 64 });
+    const surface = entry.surface as StubRasterSurface;
+    const resizeCount = (): number => surface.callLog.filter((e) => e.op === 'resize').length;
+
+    // Ten 10px batches extending the stroke 100px rightward within a single chunk
+    // row. Without chunk-padding, growToRect grows to the EXACT union every batch,
+    // so each batch reallocates + full-copies the cache (≈10 resizes). With the
+    // 64px chunk grid, successive small extensions land inside the padded extent,
+    // so the surface reallocates only when the stroke crosses a chunk boundary
+    // (~100 / 64 ≈ 2 times).
+    const batches = 10;
+    for (let i = 0; i < batches; i++) {
+      session.addPoints([pointer(100 + i * 10, 100)]);
+    }
+    session.commit();
+
+    const resizes = resizeCount();
+    expect(resizes).toBeLessThanOrEqual(2);
+    // Sanity: far fewer reallocations than batches — the unpadded behavior this
+    // regression guards would resize on nearly every batch.
+    expect(resizes).toBeLessThan(batches);
+  });
+});
+
+describe('strokeSession: cache version bump (live adjusted-surface invalidation)', () => {
+  const makeVersionSession = () => {
+    const { backend } = createCapturingBackend();
+    const layers = createLayerCacheStore(backend);
+    const entry = layers.getOrCreate('L', 100, 100);
+    entry.stale = false;
+    const ctx = {
+      backend,
+      createPath2D: (d?: string) => ({ d }) as unknown as Path2D,
+      emitStrokeCommitted: vi.fn(),
+      invalidate: vi.fn(),
+      layers,
+      notifyLayerPainted: vi.fn(),
+    } as unknown as ToolContext;
+    const session = createStrokeSession({
+      clipMask: null,
+      color: '#ff0000',
+      composite: 'source-over',
+      ctx,
+      layerId: 'L',
+      opacity: 1,
+      size: 20,
+      thinning: 0,
+      tool: 'brush',
+    });
+    return { entry, session };
+  };
+
+  it('bumps the cache version on every mid-stroke frame (so the adjusted-surface memo recomputes live)', () => {
+    const { entry, session } = makeVersionSession();
+    const v0 = entry.version;
+    session.addPoints([pointer(10, 10)]);
+    const v1 = entry.version;
+    session.addPoints([pointer(40, 40)]);
+    const v2 = entry.version;
+    // Each painted frame advances the version — a version-keyed adjusted surface
+    // would otherwise serve stale (pre-stroke) adjusted pixels mid-stroke.
+    expect(v1).toBeGreaterThan(v0);
+    expect(v2).toBeGreaterThan(v1);
+  });
+
+  it('bumps the version on cancel so the restored pixels re-derive the adjusted surface', () => {
+    const { entry, session } = makeVersionSession();
+    session.addPoints([pointer(10, 10)]);
+    const vBeforeCancel = entry.version;
+    session.cancel();
+    expect(entry.version).toBeGreaterThan(vBeforeCancel);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/strokeSession.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/strokeSession.ts
new file mode 100644
index 00000000000..211e492d247
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/strokeSession.ts
@@ -0,0 +1,275 @@
+/**
+ * The per-gesture paint session shared by the brush and eraser tools.
+ *
+ * A session is created on pointer-down against a resolved target layer's cache
+ * surface and lives until commit (pointer-up) or cancel (Esc / pointercancel).
+ * It owns the hot path the plan pins as invariant: coalesced points accumulate,
+ * and on each batch the full freehand outline is filled into a scratch surface
+ * at **full alpha** and composited into the layer cache at the stroke's opacity —
+ * so overlapping segments within one stroke never darken (the "stroke buffer"
+ * approach). Brush composites `source-over` in the fill color; eraser composites
+ * `destination-out`. When the target raster layer's transparency is LOCKED, the
+ * brush composites `source-atop` instead, so colour only lands on already-opaque
+ * pixels and the layer's alpha channel is never grown (legacy "lock transparent
+ * pixels"). The eraser is refused entirely on a transparency-locked layer (it
+ * would alter alpha), handled by the tool before a session is created.
+ *
+ * ## Per-frame restore/recapture
+ *
+ * The cache is the live preview, so it must show `before ∪ stroke@opacity` each
+ * frame. To recomposite without compounding opacity, every frame first restores
+ * the previously-painted region from the captured "before" pixels, then
+ * recaptures the pristine "before" for the (monotonically growing) dirty region,
+ * then composites the whole accumulated stroke once. This keeps `beforeImageData`
+ * exactly equal to the pre-stroke pixels over the final dirty rect — which is
+ * what commit hands to history — and makes cancel a single `putImageData`.
+ *
+ * Everything flows through the {@link RasterSurface} `ctx` seam, so this runs
+ * unchanged on the node test stub. Zero React, zero dispatch on the move path.
+ */
+
+import type { LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { PlacedSurface, PointerInput, Rect } from '@workbench/canvas-engine/types';
+import type { CanvasLayerContract } from '@workbench/types';
+
+import { strokeToPath, type StrokeSamplePoint } from '@workbench/canvas-engine/freehand';
+import { intersect, isEmpty, roundOut, union } from '@workbench/canvas-engine/math/rect';
+
+import type { StrokeCommittedEvent, ToolContext } from './tool';
+
+/** Everything a stroke session needs, resolved by the owning tool on pointer-down. */
+export interface StrokeSessionConfig {
+  ctx: ToolContext;
+  /** The layer being painted into (its cache grows with the stroke). */
+  layerId: string;
+  /** Base stroke diameter (document units). */
+  size: number;
+  /** Per-stroke opacity in [0, 1]. */
+  opacity: number;
+  /** Freehand thinning; 0 disables pressure sensitivity. */
+  thinning: number;
+  /** Fill color (brush only; ignored for the eraser). */
+  color: string;
+  /**
+   * Cache composite operation: `source-over` (brush), `destination-out` (eraser),
+   * or `source-atop` (transparency-locked brush — colour only where the layer is
+   * already opaque, alpha never grows).
+   */
+  composite: 'source-over' | 'destination-out' | 'source-atop';
+  tool: 'brush' | 'eraser';
+  /** Set only when this gesture auto-created its paint layer (for the composed history entry). */
+  createdLayer?: { layer: CanvasLayerContract; index: number } | null;
+  /**
+   * The bounded selection mask to clip the stroke to (resolved once by the tool
+   * on pointer-down when a selection exists), as a placed surface in document
+   * (= layer-local) space. When set, the paint region is intersected with the
+   * mask bounds and the scratch stroke is masked (`destination-in`) before
+   * compositing, so pixels outside the selection are never written and the cache
+   * only grows within the selection. Absent ⇒ the no-selection hot path.
+   */
+  clipMask?: PlacedSurface | null;
+}
+
+/** The imperative handle a tool drives across a gesture. */
+export interface StrokeSession {
+  /** Appends coalesced samples and repaints the accumulated stroke. */
+  addPoints(inputs: readonly PointerInput[]): void;
+  /** Finalizes the stroke and returns the completed edit for its owner to publish. */
+  commit(): StrokeCommittedEvent | null;
+  /** Restores the pre-stroke pixels and drops the session without an event. */
+  cancel(): void;
+}
+
+const toSample = (input: PointerInput): StrokeSamplePoint => ({
+  pressure: input.pressure,
+  x: input.documentPoint.x,
+  y: input.documentPoint.y,
+});
+
+/**
+ * Cache/scratch growth is snapped OUTWARD to this pixel grid. Without it, an
+ * outward brush drag extends the paint region by a few pixels on every batch, so
+ * the cache (and the scratch) would reallocate + full-copy on every pointer-move.
+ * Snapping to a coarse chunk grid means successive small extensions land inside
+ * the current padded extent, so growth happens at most once per chunk crossed —
+ * O(stroke / CHUNK) reallocations instead of O(batches).
+ */
+const GROWTH_CHUNK = 64;
+
+/** Rounds a rect OUTWARD to the {@link GROWTH_CHUNK} grid (integer, chunk-aligned). */
+const padToChunk = (r: Rect): Rect => {
+  const x = Math.floor(r.x / GROWTH_CHUNK) * GROWTH_CHUNK;
+  const y = Math.floor(r.y / GROWTH_CHUNK) * GROWTH_CHUNK;
+  const right = Math.ceil((r.x + r.width) / GROWTH_CHUNK) * GROWTH_CHUNK;
+  const bottom = Math.ceil((r.y + r.height) / GROWTH_CHUNK) * GROWTH_CHUNK;
+  return { height: bottom - y, width: right - x, x, y };
+};
+
+/** Creates a paint session that grows the target layer's content-sized cache. */
+export const createStrokeSession = (config: StrokeSessionConfig): StrokeSession => {
+  const { clipMask, color, composite, createdLayer, ctx, layerId, opacity, size, thinning, tool } = config;
+
+  const layers: LayerCacheStore = ctx.layers;
+  // A per-frame scratch surface for the filled stroke, sized to the paint region.
+  let stroke: RasterSurface | null = null;
+
+  const points: StrokeSamplePoint[] = [];
+  // `beforeImageData` holds the pristine (pre-stroke) pixels of `accumRect`, in
+  // LAYER-LOCAL coordinates — so it stays valid across a cache growth-realloc
+  // (which only shifts the surface origin, not the layer-local geometry).
+  let beforeImageData: ImageData | null = null;
+  let accumRect: Rect | null = null;
+
+  /** Ensures the scratch surface is at least `w`×`h`. */
+  const ensureStroke = (w: number, h: number): RasterSurface => {
+    if (!stroke) {
+      stroke = ctx.backend.createSurface(w, h);
+    } else if (stroke.width < w || stroke.height < h) {
+      stroke.resize(Math.max(stroke.width, w), Math.max(stroke.height, h));
+    }
+    return stroke;
+  };
+
+  const paint = (last: boolean): void => {
+    if (points.length === 0) {
+      return;
+    }
+    const { bounds, path } = strokeToPath(points, { last, size, thinning }, ctx.createPath2D);
+    let dirty: Rect | null = roundOut(bounds);
+    // Selection clip: only the region inside the selection can ever change, so
+    // bound the dirty/growth region to the mask extent (and skip empty results).
+    if (clipMask) {
+      dirty = intersect(dirty, clipMask.rect);
+    }
+    if (!dirty || isEmpty(dirty)) {
+      return;
+    }
+    // Accumulate the dirty union, then round it OUTWARD to a coarse chunk grid.
+    // Chunk-padding is the allocation-light seam the plan pins as invariant: an
+    // extending drag now grows the cache/scratch at most once per chunk it crosses
+    // instead of on every pointer batch. The padded extent may exceed the true
+    // content bounds — fine: it is an internal cache extent, so the flush just
+    // encodes a slightly larger (mostly-transparent) PNG at a consistent offset,
+    // and the reported dirty/before/after all use this same padded region so every
+    // consumer stays coherent. When a selection clips the stroke, clamp the padded
+    // region back to the mask so growth still never escapes the selection.
+    let region = padToChunk(accumRect ? roundOut(union(accumRect, dirty)) : dirty);
+    if (clipMask) {
+      const clamped = intersect(region, clipMask.rect);
+      if (clamped) {
+        region = clamped;
+      }
+    }
+    if (isEmpty(region)) {
+      return;
+    }
+
+    // Grow the cache to cover the (chunk-padded, layer-local) region, preserving
+    // existing pixels. Because `region` is chunk-aligned and monotonically growing,
+    // `entry.surface` is reallocated at most once per chunk boundary the stroke
+    // crosses — not once per batch — keeping the hot path allocation-light. The
+    // surface is resized in place (identity preserved).
+    const entry = layers.growToRect(layerId, region);
+    const target = entry.surface;
+    const targetCtx = target.ctx;
+    // Surface origin in layer-local space: surface(sx,sy) ↔ local(ox+sx, oy+sy).
+    const ox = entry.rect.x;
+    const oy = entry.rect.y;
+
+    // 1. Restore the region painted last frame back to pristine "before" pixels,
+    //    so recompositing the (larger) stroke doesn't compound its opacity.
+    if (accumRect && beforeImageData) {
+      targetCtx.putImageData(beforeImageData, accumRect.x - ox, accumRect.y - oy);
+    }
+    // 2. Recapture the pristine "before" for the grown region (in surface coords).
+    beforeImageData = targetCtx.getImageData(region.x - ox, region.y - oy, region.width, region.height);
+    accumRect = region;
+
+    // 3. Render the whole accumulated stroke into the scratch surface at full
+    //    alpha — one filled polygon, so no self-overlap darkening. The scratch is
+    //    region-local: translate the (layer-local) path by -region.origin.
+    const scratch = ensureStroke(region.width, region.height);
+    const strokeCtx = scratch.ctx;
+    strokeCtx.setTransform(1, 0, 0, 1, -region.x, -region.y);
+    strokeCtx.clearRect(region.x, region.y, region.width, region.height);
+    strokeCtx.globalCompositeOperation = 'source-over';
+    strokeCtx.globalAlpha = 1;
+    strokeCtx.fillStyle = color;
+    strokeCtx.fill(path);
+
+    // 3b. Selection clip: keep only the stroke pixels inside the selection mask.
+    //     The mask is a placed surface; draw it at (maskOrigin - regionOrigin) in
+    //     the scratch's region-local space.
+    if (clipMask) {
+      strokeCtx.setTransform(1, 0, 0, 1, 0, 0);
+      strokeCtx.globalCompositeOperation = 'destination-in';
+      strokeCtx.globalAlpha = 1;
+      strokeCtx.drawImage(clipMask.surface.canvas, clipMask.rect.x - region.x, clipMask.rect.y - region.y);
+    }
+
+    // 4. Composite the scratch stroke into the cache over the region at the stroke
+    //    opacity, using the tool's blend (brush over / eraser out). Both are in
+    //    surface coords (region translated by the surface origin).
+    targetCtx.save();
+    targetCtx.setTransform(1, 0, 0, 1, 0, 0);
+    targetCtx.beginPath();
+    targetCtx.rect(region.x - ox, region.y - oy, region.width, region.height);
+    targetCtx.clip();
+    targetCtx.globalAlpha = opacity;
+    targetCtx.globalCompositeOperation = composite;
+    targetCtx.drawImage(scratch.canvas, region.x - ox, region.y - oy);
+    targetCtx.restore();
+
+    // The cache pixels changed THIS frame — bump the version so a version-keyed
+    // dependent (the memoized adjusted-surface cache) recomputes over the live
+    // stroke. Without this the compositor would keep serving the pre-stroke
+    // adjusted surface, and the live stroke would be invisible on an adjusted
+    // raster layer until pointer-up (and jump on rect growth). This does NOT
+    // touch `thumbnailVersion` (only `notifyLayerPainted`/rasterize do), so
+    // thumbnails don't churn mid-stroke.
+    layers.publishPixels(layerId);
+    ctx.invalidate({ layers: [layerId] });
+  };
+
+  return {
+    addPoints: (inputs) => {
+      for (const input of inputs) {
+        points.push(toSample(input));
+      }
+      paint(false);
+    },
+    cancel: () => {
+      const entry = layers.get(layerId);
+      if (entry && accumRect && beforeImageData) {
+        entry.surface.ctx.putImageData(beforeImageData, accumRect.x - entry.rect.x, accumRect.y - entry.rect.y);
+        // Bump the version so the adjusted-surface memo (which recomputed over the
+        // live stroke) re-derives from the RESTORED pixels — otherwise an adjusted
+        // raster layer would keep showing the cancelled stroke's adjusted preview.
+        layers.publishPixels(layerId);
+        ctx.invalidate({ layers: [layerId] });
+      }
+    },
+    commit: () => {
+      paint(true);
+      const entry = layers.get(layerId);
+      if (!entry || !accumRect || !beforeImageData) {
+        return null;
+      }
+      const afterImageData = entry.surface.ctx.getImageData(
+        accumRect.x - entry.rect.x,
+        accumRect.y - entry.rect.y,
+        accumRect.width,
+        accumRect.height
+      );
+      return {
+        afterImageData,
+        beforeImageData,
+        dirtyRect: accumRect,
+        layerId,
+        tool,
+        ...(createdLayer ? { createdLayer } : {}),
+      };
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/textTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/textTool.test.ts
new file mode 100644
index 00000000000..31cd513e97f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/textTool.test.ts
@@ -0,0 +1,192 @@
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createTextTool } from './textTool';
+
+const textLayer = (over: Partial<CanvasLayerContract> = {}): CanvasLayerContract =>
+  ({
+    blendMode: 'normal',
+    id: 'text-existing',
+    isEnabled: true,
+    isLocked: false,
+    name: 'Text',
+    opacity: 1,
+    source: {
+      align: 'left',
+      color: '#000000',
+      content: 'hello',
+      fontFamily: 'Inter',
+      fontSize: 20,
+      fontWeight: 400,
+      lineHeight: 1.2,
+      type: 'text',
+    },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'raster',
+    ...over,
+  }) as CanvasLayerContract;
+
+const makeDoc = (over: Partial<CanvasDocumentContractV2> = {}): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 96, width: 96, x: 0, y: 0 },
+  height: 512,
+  layers: [],
+  selectedLayerId: null,
+  version: 2,
+  width: 512,
+  ...over,
+});
+
+const pointer = (x: number, y: number, buttons = 1): PointerInput => ({
+  buttons,
+  documentPoint: { x, y },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+const createHarness = (doc: CanvasDocumentContractV2) => {
+  const stores = createEngineStores();
+  const openTextCreate = vi.fn<(point: Vec2) => void>();
+  const openTextEdit = vi.fn<(layerId: string) => void>();
+  const cancelTextEdit = vi.fn<() => void>();
+  const ctx = {
+    cancelTextEdit,
+    getDocument: () => doc,
+    // No layer cache in these tests, so hit-testing falls back to the pure
+    // estimateTextExtent (a `get` that always misses).
+    layers: { get: () => undefined },
+    openTextCreate,
+    openTextEdit,
+    stores,
+  } as unknown as ToolContext;
+  return { cancelTextEdit, ctx, openTextCreate, openTextEdit, stores };
+};
+
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+
+describe('text tool: click behaviour', () => {
+  it('opens a create-mode session at the click point on empty area', () => {
+    const h = createHarness(makeDoc());
+    const tool = createTextTool();
+
+    down(tool, h.ctx, pointer(40, 60));
+
+    expect(h.openTextCreate).toHaveBeenCalledTimes(1);
+    expect(h.openTextCreate).toHaveBeenCalledWith({ x: 40, y: 60 });
+    expect(h.openTextEdit).not.toHaveBeenCalled();
+  });
+
+  it('opens an edit-mode session when the click hits an existing text layer', () => {
+    const doc = makeDoc({ layers: [textLayer()] });
+    const h = createHarness(doc);
+    const tool = createTextTool();
+
+    // 'hello' at 20px → estimated block ~60×24, so (5,5) is inside.
+    down(tool, h.ctx, pointer(5, 5));
+
+    expect(h.openTextEdit).toHaveBeenCalledTimes(1);
+    expect(h.openTextEdit).toHaveBeenCalledWith('text-existing');
+    expect(h.openTextCreate).not.toHaveBeenCalled();
+  });
+
+  it('creates rather than edits when the click misses the text block', () => {
+    const doc = makeDoc({ layers: [textLayer()] });
+    const h = createHarness(doc);
+    const tool = createTextTool();
+
+    down(tool, h.ctx, pointer(500, 500));
+
+    expect(h.openTextEdit).not.toHaveBeenCalled();
+    expect(h.openTextCreate).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not edit a locked text layer (falls through to create)', () => {
+    const doc = makeDoc({ layers: [textLayer({ isLocked: true })] });
+    const h = createHarness(doc);
+    const tool = createTextTool();
+
+    down(tool, h.ctx, pointer(5, 5));
+
+    expect(h.openTextEdit).not.toHaveBeenCalled();
+    expect(h.openTextCreate).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not edit a hidden (disabled) text layer', () => {
+    const doc = makeDoc({ layers: [textLayer({ isEnabled: false })] });
+    const h = createHarness(doc);
+    const tool = createTextTool();
+
+    down(tool, h.ctx, pointer(5, 5));
+
+    expect(h.openTextEdit).not.toHaveBeenCalled();
+    expect(h.openTextCreate).toHaveBeenCalledTimes(1);
+  });
+
+  it('is a no-op while a session is already open (the click blurs/commits React-side)', () => {
+    const h = createHarness(makeDoc());
+    h.stores.textEditSession.set({
+      id: 1,
+      layerId: null,
+      mode: 'create',
+      source: {
+        align: 'left',
+        color: '#000000',
+        content: '',
+        fontFamily: 'Inter',
+        fontSize: 20,
+        fontWeight: 400,
+        lineHeight: 1.2,
+        type: 'text',
+      },
+      startSource: null,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    });
+    const tool = createTextTool();
+
+    down(tool, h.ctx, pointer(40, 60));
+
+    expect(h.openTextCreate).not.toHaveBeenCalled();
+    expect(h.openTextEdit).not.toHaveBeenCalled();
+  });
+
+  it('ignores a non-primary button press', () => {
+    const h = createHarness(makeDoc());
+    const tool = createTextTool();
+
+    down(tool, h.ctx, pointer(40, 60, 2));
+
+    expect(h.openTextCreate).not.toHaveBeenCalled();
+  });
+});
+
+describe('text tool: teardown', () => {
+  it('cancels the session on a real deactivate but not on a temporary one', () => {
+    const h = createHarness(makeDoc());
+    const tool = createTextTool();
+
+    tool.onDeactivate?.(h.ctx, { temporary: true });
+    expect(h.cancelTextEdit).not.toHaveBeenCalled();
+
+    tool.onDeactivate?.(h.ctx);
+    expect(h.cancelTextEdit).toHaveBeenCalledTimes(1);
+  });
+
+  it('cancels the session on an Escape key command', () => {
+    const h = createHarness(makeDoc());
+    const tool = createTextTool();
+
+    tool.onKeyCommand?.(h.ctx, 'cancel');
+    expect(h.cancelTextEdit).toHaveBeenCalledTimes(1);
+
+    // Apply is a no-op here (React owns the live content/commit).
+    tool.onKeyCommand?.(h.ctx, 'apply');
+    expect(h.cancelTextEdit).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/textTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/textTool.ts
new file mode 100644
index 00000000000..ab0d7cad091
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/textTool.ts
@@ -0,0 +1,132 @@
+/**
+ * The text tool: click to CREATE editable-forever text, or click an existing
+ * text layer to re-edit it.
+ *
+ * Interaction contract (CANVAS_PLAN Phase 6.2):
+ * - **Click on empty area** → open a CREATE-mode text-editing session at that
+ *   document point (style seeded from the text options bar). Nothing is added to
+ *   the document until the session commits (a single `addCanvasLayer`).
+ * - **Click on an existing text layer** (top-most, enabled, unlocked) → open an
+ *   EDIT-mode session on it. Hit-testing inverts the layer transform and checks
+ *   the point against the layer's rendered text-block rect (cache size, or the
+ *   pure estimate before a cache exists). Locked/hidden text layers are skipped.
+ * - **Click while a session is open** → the pointer pipeline commits the open
+ *   session engine-side (`maybeCommitModalSession` → `commitOpenTextSession`,
+ *   reading the live portal content) and swallows the press BEFORE it reaches
+ *   this tool, so `onPointerDown` below is never invoked for that press. A
+ *   subsequent click then places/edits. The `textEditSession` guard here is a
+ *   defensive backstop for a harness that routes the press through anyway.
+ * - **Commit** is engine-side on a canvas pointerdown (above); the portal's blur
+ *   (focus lost to non-canvas UI) and `mod+enter` also commit. The live typed
+ *   text is read from the portal only at commit time (no per-keystroke traffic).
+ * - **Escape** is handled by the focused contenteditable (cancels the session);
+ *   a defocused-but-open session is cancelled by the engine's Escape chain
+ *   (`handleEscape`: text → transform → deselect), not routed to this tool.
+ * - A **real** tool switch cancels the session (`onDeactivate`); a **temporary**
+ *   modifier-hold switch (space→view / alt→colorPicker) preserves it, mirroring
+ *   the transform tool.
+ *
+ * Text layers are not hit-testable by the move/transform tools (like shapes and
+ * gradients), so this tool owns its own text hit-test.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasLayerSourceContract } from '@workbench/types';
+
+import { applyToPoint, invert } from '@workbench/canvas-engine/math/mat2d';
+import { estimateTextExtent } from '@workbench/canvas-engine/render/rasterizers/textRasterizer';
+
+import type { Tool, ToolContext } from './tool';
+
+import { layerMatrix } from './moveHitTest';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+type TextSource = Extract<CanvasLayerSourceContract, { type: 'text' }>;
+/** A text-sourced raster layer. */
+type TextLayer = Extract<CanvasLayerContract, { type: 'raster' }> & { source: TextSource };
+
+/** True when `layer` is an enabled, unlocked text layer (an edit-session candidate). */
+const isEditableTextLayer = (layer: CanvasLayerContract): layer is TextLayer =>
+  layer.type === 'raster' && layer.source.type === 'text' && layer.isEnabled && !layer.isLocked;
+
+/**
+ * The rendered text-block size for hit-testing: the live cache surface size when
+ * one exists (the precise, measured extent), else the pure estimate (before the
+ * layer has been rasterized once).
+ */
+const textLayerSize = (layer: TextLayer, ctx: ToolContext): { width: number; height: number } => {
+  const cache = ctx.layers.get(layer.id);
+  if (cache) {
+    return { height: cache.surface.height, width: cache.surface.width };
+  }
+  return estimateTextExtent(layer.source);
+};
+
+/** The top-most editable text layer whose rendered block contains `point` (document space), or `null`. */
+const topTextLayerAt = (doc: CanvasDocumentContractV2, point: Vec2, ctx: ToolContext): TextLayer | null => {
+  for (const layer of doc.layers) {
+    if (!isEditableTextLayer(layer)) {
+      continue;
+    }
+    const inverse = invert(layerMatrix(layer.transform));
+    if (!inverse) {
+      continue;
+    }
+    const local = applyToPoint(inverse, point);
+    const size = textLayerSize(layer, ctx);
+    if (local.x >= 0 && local.x <= size.width && local.y >= 0 && local.y <= size.height) {
+      return layer;
+    }
+  }
+  return null;
+};
+
+/** Creates a fresh text tool. It holds no gesture state (a click opens a session and returns). */
+export const createTextTool = (): Tool => ({
+  cursor: () => 'text',
+  id: 'text',
+  onDeactivate: (ctx, opts) => {
+    if (opts?.temporary) {
+      // A modifier-hold switch (space/alt) preserves the open session for
+      // `onActivate` to resume when the hold ends — like the transform tool.
+      return;
+    }
+    // A real tool switch cancels the session (in practice the contenteditable's
+    // blur has already committed by now; this is the safety teardown).
+    ctx.cancelTextEdit?.();
+  },
+  onKeyCommand: (ctx, command) => {
+    // Defensive backstop: the pipeline does not route 'cancel' to tools (the
+    // engine's `handleEscape` chain owns text/transform/deselect), so this only
+    // fires if a harness routes it directly. Cancel drops a defocused session;
+    // apply is a no-op here (only the portal holds the live content to commit).
+    if (command === 'cancel') {
+      ctx.cancelTextEdit?.();
+    }
+  },
+  onPointerDown: (ctx, input) => {
+    if ((input.buttons & PRIMARY_BUTTON) === 0) {
+      return;
+    }
+    // Backstop: when a session is open the pipeline commits+swallows the press
+    // before it reaches this tool, so this branch is normally unreached. Guard
+    // anyway so a harness that routes the press through never opens a 2nd session.
+    if (ctx.stores.textEditSession.get()) {
+      return;
+    }
+    const doc = ctx.getDocument();
+    if (!doc) {
+      return;
+    }
+    const hit = topTextLayerAt(doc, input.documentPoint, ctx);
+    if (hit) {
+      ctx.openTextEdit?.(hit.id);
+    } else {
+      ctx.openTextCreate?.(input.documentPoint);
+    }
+  },
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/tool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/tool.ts
new file mode 100644
index 00000000000..d0dc350f8c3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/tool.ts
@@ -0,0 +1,221 @@
+/**
+ * The `Tool` seam: the engine routes normalized pointer/wheel input to whichever
+ * tool is active. Tools are pure interaction handlers — they read the viewport
+ * and mirrored document through the engine-provided {@link ToolContext} and
+ * request re-renders via `invalidate`.
+ *
+ * Navigation tools (view) never dispatch and never touch pixels. Painting tools
+ * (brush/eraser) reach the layer-cache surfaces and raster backend through the
+ * same context, dispatch at most once per gesture (auto-creating a paint layer
+ * on pointer-down when needed), and emit exactly one {@link StrokeCommittedEvent}
+ * on commit — persistence/history are wired to that event downstream, not here.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { EngineStores } from '@workbench/canvas-engine/engineStores';
+import type { CreatePath2D } from '@workbench/canvas-engine/freehand';
+import type { LayerCacheStore } from '@workbench/canvas-engine/render/layerCache';
+import type { OverlayCursor } from '@workbench/canvas-engine/render/overlayRenderer';
+import type { RasterBackend } from '@workbench/canvas-engine/render/raster';
+import type { InvalidatePayload } from '@workbench/canvas-engine/render/scheduler';
+import type { SamInteractionState, SamVisualInput } from '@workbench/canvas-engine/samInteraction';
+import type { SelectionCommit } from '@workbench/canvas-engine/selection/selectionState';
+import type { LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+import type { PlacedSurface, PointerInput, PointerModifiers, Rect, ToolId, Vec2 } from '@workbench/canvas-engine/types';
+import type { Viewport } from '@workbench/canvas-engine/viewport';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+/**
+ * Emitted once per completed brush/eraser gesture. Persistence (Task P2.2) and
+ * history (Task P2.3) subscribe via `engine.tools.onStrokeCommitted`. `beforeImageData`
+ * and `afterImageData` are both sized to `dirtyRect`, so an undo can restore the
+ * pre-stroke pixels and a redo can re-apply the post-stroke pixels cheaply.
+ */
+export interface StrokeCommittedEvent {
+  /** The layer that received the stroke. */
+  layerId: string;
+  /** The painted region in document space (integer bounds, clamped to the document). */
+  dirtyRect: Rect;
+  /** Cache pixels within `dirtyRect` before the stroke. */
+  beforeImageData: ImageData;
+  /** Cache pixels within `dirtyRect` after the stroke. */
+  afterImageData: ImageData;
+  /** Which tool produced the stroke. */
+  tool: 'brush' | 'eraser';
+  /**
+   * When the gesture auto-created its paint layer on pointer-down, the created
+   * layer contract (and where it was inserted). The engine composes this into
+   * the stroke's history entry so an undo removes BOTH the stroke and the
+   * now-empty auto-created layer (and a redo re-adds the layer + stroke).
+   * Absent for strokes painted into a pre-existing layer.
+   */
+  createdLayer?: { layer: CanvasLayerContract; index: number };
+}
+
+export interface PixelEditPatch {
+  rect: Rect;
+  before: ImageData;
+  after: ImageData;
+}
+
+export interface ControlPixelEditTransaction {
+  readonly layerId: string;
+  commitPatch(label: string, patch: PixelEditPatch): void;
+  commitStroke(event: StrokeCommittedEvent): void;
+  cancel(): void;
+}
+
+/**
+ * A transient per-layer transform override the compositor/overlay read at render
+ * time (a live drag preview that never touches the mirror). The move tool sets
+ * only `x`/`y` (rotation/scale fall back to the committed transform); the
+ * transform tool sets the full transform so a scale/rotate preview renders.
+ */
+export interface LayerTransformOverride {
+  x: number;
+  y: number;
+  scaleX?: number;
+  scaleY?: number;
+  rotation?: number;
+}
+
+/** Everything a tool is allowed to reach, injected by the engine. */
+export interface ToolContext {
+  /** The pan/zoom viewport. */
+  viewport: Viewport;
+  /** The current mirrored document, or `null` when none is available. */
+  getDocument(): CanvasDocumentContractV2 | null;
+  /** Requests a re-render for the given flags. */
+  invalidate(payload: InvalidatePayload): void;
+  /** Reducer bridge. Painting tools use it for the single gesture-start `addCanvasLayer`. */
+  dispatch(action: CanvasProjectMutation): void;
+  /**
+   * Records a structural document edit on the engine-owned canvas history:
+   * dispatches `forward` now, and an undo dispatches `inverse` / a redo
+   * re-dispatches `forward`. The move tool commits a layer nudge through this.
+   */
+  commitStructural(label: string, forward: CanvasProjectMutation, inverse: CanvasProjectMutation): void;
+  /**
+   * Sets (or clears with `null`) a transient per-layer transform override the
+   * compositor and overlay read at render time — a live drag preview that never
+   * touches the mirror/document. Cleared on commit or cancel.
+   */
+  setLayerTransformOverride(layerId: string, override: LayerTransformOverride | null): void;
+  /**
+   * Begins a transform session on `layerId` (captures its committed transform,
+   * shows the live preview). Provided by the engine; the transform tool calls it
+   * on activate / when a layer is clicked. Absent in minimal test harnesses.
+   */
+  beginTransformSession?(layerId: string): void;
+  /** Prepares direct or transactional pixel editing for a selected control layer. */
+  beginControlPixelEdit?(layerId: string): ControlPixelEditTransaction | null;
+  /** Updates the active transform session's live transform (drag or numeric edit). */
+  updateTransformSession?(transform: LayerTransform): void;
+  /**
+   * Commits the active transform session: a param commit (image layers) or a
+   * pixel bake (paint layers), as ONE undoable entry. Then clears the session.
+   */
+  applyTransform?(): void;
+  /** Cancels the active transform session (drops the preview, no dispatch). */
+  cancelTransform?(): void;
+  /**
+   * Opens a CREATE-mode text-editing session at `docPoint` (no layer yet; the
+   * commit later dispatches one `addCanvasLayer`). Seeds style from the text
+   * options store. The text tool calls it on an empty-area click. Absent in
+   * minimal test harnesses.
+   */
+  openTextCreate?(docPoint: Vec2): void;
+  /**
+   * Opens an EDIT-mode text-editing session on an existing text layer (captures
+   * its committed source for the undo inverse). The text tool calls it when a
+   * click hits a text layer. Absent in minimal test harnesses.
+   */
+  openTextEdit?(layerId: string): void;
+  /** Cancels the active text-editing session (drops it, no dispatch). */
+  cancelTextEdit?(): void;
+  /** The raster backend, for allocating scratch stroke surfaces. */
+  backend: RasterBackend;
+  /** The per-layer raster cache; painting tools fill directly into a layer's surface. */
+  layers: LayerCacheStore;
+  /** Builds a `Path2D` (node-safe seam; the engine passes `(d) => new Path2D(d)`). */
+  createPath2D: CreatePath2D;
+  /** Mints a fresh layer id for an auto-created paint layer. */
+  createLayerId(): string;
+  /** The transient engine stores (tool options live here). */
+  stores: EngineStores;
+  /** Reads core visual Select Object interaction state without depending on application sessions. */
+  getSamInteraction?(): SamInteractionState | null;
+  /** Sets (or clears) the brush cursor ring drawn on the overlay. */
+  setOverlayCursor(cursor: OverlayCursor | null): void;
+  /**
+   * Re-evaluates the active tool's CSS cursor and applies it to the input
+   * element. A tool calls this when its `cursor(ctx)` result changes off a plain
+   * pointer-move (e.g. the bbox tool switching to a resize cursor while hovering a
+   * handle) — pointer-move does not otherwise refresh the cursor.
+   */
+  updateCursor(): void;
+  /** Emits a completed-stroke event to `engine.tools.onStrokeCommitted` subscribers. */
+  emitStrokeCommitted(event: StrokeCommittedEvent): void;
+  /** Bumps a layer's cache version (without marking it stale) after a direct paint, and recomposites. */
+  notifyLayerPainted(layerId: string): void;
+  /**
+   * Commits a lasso path to the engine's transient selection (boolean op applied
+   * to the mask). Provided by the engine; the lasso tool calls it on pointer-up.
+   * Absent in minimal test harnesses.
+   */
+  commitSelection?(commit: SelectionCommit): void;
+  /**
+   * The current selection mask as a placed surface (alpha 255 inside) in document
+   * space — the mask is bounded to the selection extent, so its `rect` records
+   * where it sits. `null` when there is no selection. Painting tools read it ONCE
+   * on pointer-down to clip the stroke; a `null` result keeps the zero-overhead
+   * hot path. Absent in minimal test harnesses.
+   */
+  getSelectionMask?(): PlacedSurface | null;
+  /** Updates visual SAM input for the active engine-owned Select Object session. */
+  updateSamInput?(input: SamVisualInput): void;
+}
+
+/**
+ * Why a tool is being (de)activated, passed by the engine's `setTool` so a
+ * session-bearing tool (transform) can tell a temporary modifier-hold switch
+ * (space→view, alt→colorPicker; the pointer pipeline restores the prior tool
+ * on release) apart from a REAL tool switch. A temp switch must not tear down
+ * an in-progress session — only a real switch (or dispose) does.
+ */
+export interface ToolActivationOptions {
+  /** True for a pipeline modifier-hold switch (and its matching restore); absent/false for a real switch. */
+  temporary?: boolean;
+}
+
+/** A stateless-to-the-engine interaction handler. Implementations may hold private drag state. */
+export interface Tool {
+  readonly id: ToolId;
+  /** Called when the tool becomes active. */
+  onActivate?(ctx: ToolContext, opts?: ToolActivationOptions): void;
+  /** Called when the tool is deactivated (also on engine dispose). */
+  onDeactivate?(ctx: ToolContext, opts?: ToolActivationOptions): void;
+  onPointerDown?(ctx: ToolContext, input: PointerInput): void;
+  /**
+   * A pointer move. `batch` carries the coalesced samples for this move event
+   * (always at least one; its last element equals `input`); tools that paint
+   * consume the whole batch, navigation tools use only `input`.
+   */
+  onPointerMove?(ctx: ToolContext, input: PointerInput, batch: readonly PointerInput[]): void;
+  onPointerUp?(ctx: ToolContext, input: PointerInput): void;
+  /** The active gesture was cancelled (Esc, pointercancel, focus loss). */
+  onPointerCancel?(ctx: ToolContext): void;
+  /**
+   * A session-level key command routed from the pointer pipeline: Enter →
+   * `'apply'`, Escape → `'cancel'`. Tools with a multi-gesture session (transform)
+   * use it to commit/abort; other tools ignore it. Escape also runs the normal
+   * gesture cancel independently.
+   */
+  onKeyCommand?(ctx: ToolContext, command: 'apply' | 'cancel'): void;
+  /** Wheel over the canvas; `screenAnchor` is the CSS-pixel cursor position. */
+  onWheel?(ctx: ToolContext, deltaY: number, screenAnchor: { x: number; y: number }, modifiers: PointerModifiers): void;
+  /** The CSS cursor to show while this tool is active. */
+  cursor?(ctx: ToolContext): string;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/transformTool.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/transformTool.test.ts
new file mode 100644
index 00000000000..69dff9b25df
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/transformTool.test.ts
@@ -0,0 +1,440 @@
+import type { Tool, ToolContext } from '@workbench/canvas-engine/tools/tool';
+import type { LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { createEngineStores } from '@workbench/canvas-engine/engineStores';
+import { TRANSFORM_ROTATE_NUB_PX, transformOverlayGeometry } from '@workbench/canvas-engine/transform/transformMath';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createTransformTool } from './transformTool';
+
+const imageLayer = (
+  id: string,
+  opts: { x?: number; y?: number; width?: number; height?: number; isLocked?: boolean; isEnabled?: boolean } = {}
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: opts.isEnabled ?? true,
+  isLocked: opts.isLocked ?? false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: opts.height ?? 100, imageName: id, width: opts.width ?? 100 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: opts.x ?? 0, y: opts.y ?? 0 },
+  type: 'raster',
+});
+
+const makeDoc = (layers: CanvasLayerContract[], selectedLayerId: string | null): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 200, width: 200, x: 0, y: 0 },
+  height: 200,
+  layers,
+  selectedLayerId,
+  version: 2,
+  width: 200,
+});
+
+const pointer = (
+  x: number,
+  y: number,
+  opts: { shift?: boolean; alt?: boolean; buttons?: number } = {}
+): PointerInput => ({
+  buttons: opts.buttons ?? 1,
+  documentPoint: { x, y },
+  modifiers: { alt: opts.alt ?? false, ctrl: false, meta: false, shift: opts.shift ?? false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: { x, y },
+  timeStamp: 0,
+});
+
+/** A pointer input at an explicit SCREEN point, with the doc point derived at `zoom`. */
+const pointerAtScreen = (screen: Vec2, zoom: number): PointerInput => ({
+  buttons: 1,
+  documentPoint: { x: screen.x / zoom, y: screen.y / zoom },
+  modifiers: { alt: false, ctrl: false, meta: false, shift: false },
+  pointerType: 'mouse',
+  pressure: 0.5,
+  screenPoint: screen,
+  timeStamp: 0,
+});
+
+/** The screen-space tip of the drawn rotation nub for `transform` at `zoom`. */
+const nubTipScreen = (
+  transform: LayerTransform,
+  sz: { x: number; y: number; width: number; height: number },
+  zoom: number
+): Vec2 => {
+  const geo = transformOverlayGeometry(transform, sz);
+  const toScreen = (p: Vec2) => ({ x: zoom * p.x, y: zoom * p.y });
+  const a = toScreen(geo.rotationAnchor);
+  const c = toScreen(geo.center);
+  const dx = a.x - c.x;
+  const dy = a.y - c.y;
+  const len = Math.hypot(dx, dy) || 1;
+  return { x: a.x + (dx / len) * TRANSFORM_ROTATE_NUB_PX, y: a.y + (dy / len) * TRANSFORM_ROTATE_NUB_PX };
+};
+
+/** Rotates `p` about `pivot` by `rad` (screen space). */
+const rotateAbout = (p: Vec2, pivot: Vec2, rad: number): Vec2 => {
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  const dx = p.x - pivot.x;
+  const dy = p.y - pivot.y;
+  return { x: pivot.x + cos * dx - sin * dy, y: pivot.y + sin * dx + cos * dy };
+};
+
+interface Harness {
+  ctx: ToolContext;
+  applyCount: () => number;
+  session: () => ReturnType<ReturnType<typeof createEngineStores>['transformSession']['get']>;
+  overrides: { layerId: string; override: unknown }[];
+}
+
+/**
+ * A ToolContext whose transform-session seams mutate a real `transformSession`
+ * store (mirroring the engine), so the tool's reads reflect its own writes across
+ * a down→move→up drag. The viewport projects document→screen 1:1.
+ */
+const createHarness = (doc: CanvasDocumentContractV2, zoom = 1): Harness => {
+  const stores = createEngineStores();
+  const overrides: { layerId: string; override: unknown }[] = [];
+  const state = { applyCount: 0 };
+
+  const beginTransformSession = (layerId: string): void => {
+    const layer = doc.layers.find((entry) => entry.id === layerId);
+    if (!layer) {
+      return;
+    }
+    const start: LayerTransform = { ...layer.transform };
+    stores.transformSession.set({ layerId, startTransform: start, transform: start });
+    overrides.push({ layerId, override: start });
+  };
+  const updateTransformSession = (transform: LayerTransform): void => {
+    const session = stores.transformSession.get();
+    if (!session) {
+      return;
+    }
+    stores.transformSession.set({ ...session, transform });
+    overrides.push({ layerId: session.layerId, override: transform });
+  };
+  const cancelTransform = (): void => {
+    const session = stores.transformSession.get();
+    if (session) {
+      overrides.push({ layerId: session.layerId, override: null });
+    }
+    stores.transformSession.set(null);
+  };
+
+  const ctx: ToolContext = {
+    applyTransform: () => {
+      state.applyCount += 1;
+    },
+    backend: null as never,
+    beginTransformSession,
+    cancelTransform,
+    commitStructural: vi.fn(),
+    createLayerId: () => 'x',
+    createPath2D: (d) => ({ d }) as unknown as Path2D,
+    dispatch: vi.fn(),
+    emitStrokeCommitted: vi.fn(),
+    getDocument: () => doc,
+    invalidate: vi.fn(),
+    layers: null as never,
+    notifyLayerPainted: vi.fn(),
+    setLayerTransformOverride: vi.fn(),
+    setOverlayCursor: vi.fn(),
+    stores,
+    updateCursor: vi.fn(),
+    updateTransformSession,
+    viewport: {
+      documentToScreen: (p: Vec2) => ({ x: zoom * p.x, y: zoom * p.y }),
+      screenToDocument: (p: Vec2) => ({ x: p.x / zoom, y: p.y / zoom }),
+    } as never,
+  };
+
+  return {
+    applyCount: () => state.applyCount,
+    ctx,
+    overrides,
+    session: () => stores.transformSession.get(),
+  };
+};
+
+const activate = (t: Tool, ctx: ToolContext): void => t.onActivate?.(ctx);
+const down = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerDown?.(ctx, i);
+const move = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerMove?.(ctx, i, [i]);
+const up = (t: Tool, ctx: ToolContext, i: PointerInput): void => t.onPointerUp?.(ctx, i);
+
+describe('transform tool: session lifecycle', () => {
+  it('opens a session on the selected eligible layer when activated', () => {
+    const doc = makeDoc([imageLayer('a')], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+
+    activate(tool, h.ctx);
+
+    const s = h.session();
+    expect(s?.layerId).toBe('a');
+    expect(s?.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+  });
+
+  it('opens no session on a locked selected layer', () => {
+    const doc = makeDoc([imageLayer('a', { isLocked: true })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+
+    activate(tool, h.ctx);
+
+    expect(h.session()).toBeNull();
+  });
+
+  it('opens no session on a hidden selected layer', () => {
+    const doc = makeDoc([imageLayer('a', { isEnabled: false })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+
+    activate(tool, h.ctx);
+
+    expect(h.session()).toBeNull();
+  });
+
+  it('clicking a layer with no session starts a session (move gesture)', () => {
+    const doc = makeDoc([imageLayer('a', { width: 100, height: 100 })], null);
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+
+    down(tool, h.ctx, pointer(50, 50));
+    expect(h.session()?.layerId).toBe('a');
+  });
+});
+
+describe('transform tool: gestures', () => {
+  it('scales via a corner handle drag (updates the session, no dispatch)', () => {
+    const doc = makeDoc([imageLayer('a', { width: 100, height: 100 })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    // se corner is at doc (100,100); drag it to (150,150).
+    down(tool, h.ctx, pointer(100, 100));
+    move(tool, h.ctx, pointer(150, 150));
+    up(tool, h.ctx, pointer(150, 150));
+
+    const s = h.session();
+    expect(s?.transform.scaleX).toBeCloseTo(1.5, 5);
+    expect(s?.transform.scaleY).toBeCloseTo(1.5, 5);
+    // No structural dispatch — the session holds the preview until Apply.
+    expect(h.ctx.commitStructural).not.toHaveBeenCalled();
+  });
+
+  it('moves via an interior drag', () => {
+    const doc = makeDoc([imageLayer('a', { width: 100, height: 100 })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    down(tool, h.ctx, pointer(50, 50));
+    move(tool, h.ctx, pointer(70, 65));
+    up(tool, h.ctx, pointer(70, 65));
+
+    const s = h.session();
+    expect(s?.transform.x).toBeCloseTo(20, 5);
+    expect(s?.transform.y).toBeCloseTo(15, 5);
+  });
+
+  it('rotates via a corner rotate zone drag', () => {
+    const doc = makeDoc([imageLayer('a', { width: 100, height: 100 })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    // Just outside the se corner (100,100) is a rotate zone.
+    down(tool, h.ctx, pointer(112, 112));
+    move(tool, h.ctx, pointer(100, 130));
+    up(tool, h.ctx, pointer(100, 130));
+
+    const s = h.session();
+    expect(s?.transform.rotation).not.toBe(0);
+  });
+
+  it('ignores a sub-threshold drag (no session change)', () => {
+    const doc = makeDoc([imageLayer('a', { width: 100, height: 100 })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+    const startOverrides = h.overrides.length;
+
+    down(tool, h.ctx, pointer(100, 100));
+    move(tool, h.ctx, pointer(101, 101));
+    up(tool, h.ctx, pointer(101, 101));
+
+    // No update beyond the initial begin override.
+    expect(h.overrides.length).toBe(startOverrides);
+    expect(h.session()?.transform.scaleX).toBe(1);
+  });
+});
+
+describe('transform tool: rotation nub (regression — a nub press must rotate, not reset)', () => {
+  const transformed: LayerTransform = { rotation: 0.4, scaleX: 1.6, scaleY: 1.3, x: 30, y: 20 };
+  const layerSize = { height: 100, width: 100, x: 0, y: 0 };
+
+  const run = (zoom: number): void => {
+    const layer: CanvasLayerContract = { ...imageLayer('a'), transform: transformed };
+    const doc = makeDoc([layer], 'a');
+    const h = createHarness(doc, zoom);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    const startTransform = h.session()?.transform;
+    expect(startTransform).toEqual(transformed);
+    const overridesBefore = h.overrides.length;
+
+    // Pointer-down EXACTLY on the drawn rotation nub (above the top edge).
+    const tip = nubTipScreen(transformed, layerSize, zoom);
+    down(tool, h.ctx, pointerAtScreen(tip, zoom));
+
+    // (a) Gesture start must NOT touch the session/override values. The bug read
+    // the nub press as off-frame and re-opened the session, resetting its live
+    // transform back to the committed one.
+    expect(h.session()?.transform).toEqual(startTransform);
+    expect(h.overrides.length).toBe(overridesBefore);
+
+    // (b) A subsequent move begins a ROTATION: rotation changes by the swept
+    // angle, scale is untouched (not a move/scale/reset).
+    const geo = transformOverlayGeometry(transformed, layerSize);
+    const centerScreen: Vec2 = { x: zoom * geo.center.x, y: zoom * geo.center.y };
+    const moved = rotateAbout(tip, centerScreen, 0.5);
+    move(tool, h.ctx, pointerAtScreen(moved, zoom));
+
+    const after = h.session()?.transform;
+    expect(after).toBeDefined();
+    expect(after?.scaleX).toBeCloseTo(transformed.scaleX, 6);
+    expect(after?.scaleY).toBeCloseTo(transformed.scaleY, 6);
+    expect(after?.rotation).toBeCloseTo(transformed.rotation + 0.5, 6);
+  };
+
+  it('rotates (does not reset) at zoom 1', () => run(1));
+  it('rotates (does not reset) at a non-1 zoom', () => run(2.5));
+});
+
+describe('transform tool: apply / cancel', () => {
+  it('Enter applies the session', () => {
+    const doc = makeDoc([imageLayer('a')], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    tool.onKeyCommand?.(h.ctx, 'apply');
+
+    // The engine apply seam was invoked exactly once.
+    expect(h.applyCount()).toBe(1);
+  });
+
+  it('Escape cancels the session', () => {
+    const doc = makeDoc([imageLayer('a')], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+    expect(h.session()).not.toBeNull();
+
+    tool.onKeyCommand?.(h.ctx, 'cancel');
+
+    expect(h.session()).toBeNull();
+  });
+
+  it('tool switch (deactivate) cancels the session', () => {
+    const doc = makeDoc([imageLayer('a')], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    tool.onDeactivate?.(h.ctx);
+
+    expect(h.session()).toBeNull();
+  });
+
+  it('pointercancel reverts the drag but keeps the session', () => {
+    const doc = makeDoc([imageLayer('a', { width: 100, height: 100 })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    down(tool, h.ctx, pointer(100, 100));
+    move(tool, h.ctx, pointer(160, 160));
+    expect(h.session()?.transform.scaleX).toBeGreaterThan(1);
+
+    tool.onPointerCancel?.(h.ctx);
+
+    // Session persists, reverted to the start transform.
+    const s = h.session();
+    expect(s).not.toBeNull();
+    expect(s?.transform.scaleX).toBe(1);
+  });
+
+  it('Enter mid-drag no-ops: the gesture continues (a further move still updates the session) and pointer-up still works', () => {
+    const doc = makeDoc([imageLayer('a', { width: 100, height: 100 })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+
+    // se corner drag, past the threshold — a gesture is now in progress and
+    // holds (conceptually) pointer capture.
+    down(tool, h.ctx, pointer(100, 100));
+    move(tool, h.ctx, pointer(120, 120));
+    const midDrag = h.session()?.transform.scaleX;
+    expect(midDrag).toBeGreaterThan(1);
+
+    tool.onKeyCommand?.(h.ctx, 'apply');
+
+    // No-op: the engine apply seam was NOT invoked (unlike the "Enter applies
+    // the session" test above, which has no live gesture).
+    expect(h.applyCount()).toBe(0);
+
+    // The gesture is still alive — it did not silently freeze mid-drag.
+    move(tool, h.ctx, pointer(150, 150));
+    expect(h.session()?.transform.scaleX).toBeGreaterThan(midDrag!);
+
+    // Pointer-up still ends the gesture normally, keeping the session.
+    up(tool, h.ctx, pointer(150, 150));
+    expect(h.session()).not.toBeNull();
+  });
+});
+
+describe('transform tool: temp-tool switch (space/alt hold)', () => {
+  it('a temporary deactivate preserves the session; the matching temporary activate leaves it untouched', () => {
+    const doc = makeDoc([imageLayer('a', { x: 5, y: 5 })], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+    h.ctx.updateTransformSession?.({ rotation: 0, scaleX: 2, scaleY: 1, x: 40, y: 5 });
+    const edited = h.session()?.transform;
+
+    // Space down: a temporary deactivate must not cancel the session.
+    tool.onDeactivate?.(h.ctx, { temporary: true });
+    expect(h.session()?.transform).toEqual(edited);
+
+    // Space up: a temporary activate must not re-open the session from the
+    // current selection (which would stomp the preserved edit with the
+    // layer's committed transform).
+    tool.onActivate?.(h.ctx, { temporary: true });
+    expect(h.session()?.transform).toEqual(edited);
+  });
+
+  it('a temporary activate does not resurrect a session the engine already cancelled while held (e.g. its layer was deleted)', () => {
+    const doc = makeDoc([imageLayer('a')], 'a');
+    const h = createHarness(doc);
+    const tool = createTransformTool();
+    activate(tool, h.ctx);
+    expect(h.session()).not.toBeNull();
+
+    tool.onDeactivate?.(h.ctx, { temporary: true });
+    // Simulates the engine's layer-change teardown (Task 26 finding #3)
+    // cancelling the session out-of-band while temp-switched away.
+    h.ctx.cancelTransform?.();
+    expect(h.session()).toBeNull();
+
+    tool.onActivate?.(h.ctx, { temporary: true });
+    expect(h.session()).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/transformTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/transformTool.ts
new file mode 100644
index 00000000000..3833123d0cd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/transformTool.ts
@@ -0,0 +1,297 @@
+/**
+ * The transform tool: an interactive scale/rotate/move SESSION on a single layer.
+ *
+ * Interaction contract (CANVAS_PLAN Phase 5):
+ * - **Session**: selecting the tool with an eligible layer selected (or clicking a
+ *   layer) captures its committed transform and opens a session. The live preview
+ *   flows through the engine's transform-override channel; a `transformSession`
+ *   store exposes the layer id + live transform so the numeric options bar can
+ *   render and edit it. The session survives multiple gestures — drag handles,
+ *   drag to rotate/move, adjust numerics — until **Apply** or **Cancel**.
+ * - **Gestures** (each a fresh pointer drag on the session's frame): a scale
+ *   handle scales about the opposite handle (alt = center, shift = uniform on
+ *   corners); a corner rotate zone rotates about the center (shift = 15° snap);
+ *   the interior moves (shift = axis constrain). Pointer-move only updates the
+ *   session preview — it never dispatches.
+ * - **Apply** (`enter` / options button): the engine commits — a param edit for
+ *   image layers, a pixel bake for paint layers — as ONE undoable entry.
+ * - **Cancel** (`esc` / options button / a REAL tool switch): drops the
+ *   preview, no dispatch. A mid-gesture pointercancel reverts just that drag,
+ *   keeping the session; Escape aborts the whole session. A TEMPORARY tool
+ *   switch (space/alt modifier-hold) is not a cancel — the session and its
+ *   preview survive the hold and resume when it ends (see `onActivate`/
+ *   `onDeactivate`'s `opts.temporary`). If the session's layer is deleted
+ *   while held, the engine's layer-change teardown cancels it regardless of
+ *   which tool is active.
+ *
+ * Locked/hidden layers get no session (same guard as the move tool). Zero React,
+ * zero import-time side effects.
+ */
+
+import type { LayerTransform, TransformRect, TransformTarget } from '@workbench/canvas-engine/transform/transformMath';
+import type { PointerInput, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasLayerContract } from '@workbench/types';
+
+import {
+  applyMove,
+  applyRotate,
+  applyScale,
+  resizeCursorForHandle,
+  transformTargetAt,
+} from '@workbench/canvas-engine/transform/transformMath';
+
+import type { Tool, ToolContext } from './tool';
+
+import { hittableLayerRect, topLayerAt } from './moveHitTest';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/** Screen-space distance (CSS px) the pointer must travel before a press becomes a drag. */
+export const TRANSFORM_DRAG_THRESHOLD_PX = 3;
+
+interface GestureState {
+  target: TransformTarget;
+  /** The session transform captured at gesture start (revert target for cancel). */
+  startTransform: LayerTransform;
+  startPointerDoc: Vec2;
+  startScreen: Vec2;
+  /** The session layer's local content rect (off-origin aware). */
+  rect: TransformRect;
+  /** The cursor held for the duration of this gesture. */
+  cursor: string;
+  moved: boolean;
+}
+
+/** The cursor for a hovered/grabbed target, given the layer's current transform. */
+const cursorForTarget = (transform: LayerTransform, target: TransformTarget): string => {
+  if (target.kind === 'scale') {
+    return resizeCursorForHandle(transform, target.handle);
+  }
+  return target.kind === 'rotate' ? 'grab' : 'move';
+};
+
+/** Creates a fresh transform tool with its own session/gesture state. */
+export const createTransformTool = (): Tool => {
+  let gesture: GestureState | null = null;
+  // The cursor for the target under the pointer while idle (session but no drag).
+  let hoverCursor: string | null = null;
+
+  const isEligible = (layer: CanvasLayerContract, doc: NonNullable<ReturnType<ToolContext['getDocument']>>): boolean =>
+    // Masks are MOVE-able (legacy parity) but not transform-able in this phase:
+    // `applyTransform` has no mask bake path, so a transform session on a mask
+    // would preview then no-op on Apply. Exclude them until that lands (Phase 7+).
+    layer.isEnabled &&
+    !layer.isLocked &&
+    layer.type !== 'inpaint_mask' &&
+    layer.type !== 'regional_guidance' &&
+    hittableLayerRect(layer, doc) !== null;
+
+  /** Hit-tests the active session's frame at a screen point (or `null`). */
+  const targetAt = (ctx: ToolContext, screenPoint: Vec2): TransformTarget | null => {
+    const session = ctx.stores.transformSession.get();
+    const doc = ctx.getDocument();
+    if (!session || !doc) {
+      return null;
+    }
+    const layer = doc.layers.find((candidate) => candidate.id === session.layerId);
+    const rect = layer ? hittableLayerRect(layer, doc) : null;
+    if (!rect) {
+      return null;
+    }
+    return transformTargetAt({
+      point: screenPoint,
+      rect,
+      toScreen: (p) => ctx.viewport.documentToScreen(p),
+      transform: session.transform,
+    });
+  };
+
+  const nextTransform = (state: GestureState, input: PointerInput): LayerTransform => {
+    const delta: Vec2 = {
+      x: input.documentPoint.x - state.startPointerDoc.x,
+      y: input.documentPoint.y - state.startPointerDoc.y,
+    };
+    switch (state.target.kind) {
+      case 'move':
+        return applyMove(state.startTransform, delta, input.modifiers.shift);
+      case 'scale':
+        return applyScale({
+          alt: input.modifiers.alt,
+          handle: state.target.handle,
+          pointerDoc: input.documentPoint,
+          shift: input.modifiers.shift,
+          rect: state.rect,
+          start: state.startTransform,
+          startPointerDoc: state.startPointerDoc,
+        });
+      case 'rotate':
+        return applyRotate({
+          pointerDoc: input.documentPoint,
+          shift: input.modifiers.shift,
+          rect: state.rect,
+          start: state.startTransform,
+          startPointerDoc: state.startPointerDoc,
+        });
+    }
+  };
+
+  const endGesture = (): void => {
+    gesture = null;
+  };
+
+  return {
+    cursor: () => {
+      if (gesture) {
+        return gesture.cursor;
+      }
+      return hoverCursor ?? 'default';
+    },
+    id: 'transform',
+    onActivate: (ctx, opts) => {
+      if (opts?.temporary) {
+        // Resuming from a modifier-hold switch (space→view, alt→colorPicker):
+        // `onDeactivate` preserved the session (and its preview override)
+        // across the hold, so there is nothing to (re)open here. Re-opening
+        // from the current selection would stomp the live preview with the
+        // layer's committed transform, discarding accumulated drags/numeric
+        // edits. If the session's layer vanished mid-hold, the engine's
+        // layer-change teardown already cancelled it — leave that alone too.
+        return;
+      }
+      // Entering the tool on an eligible selected layer opens a session on it.
+      const doc = ctx.getDocument();
+      const selectedId = doc?.selectedLayerId;
+      const selected = selectedId ? doc?.layers.find((layer) => layer.id === selectedId) : undefined;
+      if (doc && selected && isEligible(selected, doc)) {
+        ctx.beginTransformSession?.(selected.id);
+      }
+    },
+    onDeactivate: (ctx, opts) => {
+      hoverCursor = null;
+      if (opts?.temporary) {
+        // A modifier-hold switch (space/alt) must not discard an in-progress
+        // session: the pipeline already suppresses temp switches mid-gesture,
+        // so `gesture` is guaranteed null here — this only clears the idle
+        // hover cursor. The session + preview override are left for
+        // `onActivate` to resume when the hold ends. A REAL tool switch (below)
+        // still cancels.
+        endGesture();
+        return;
+      }
+      // A real tool switch mid-session cancels it (drops the preview, no dispatch).
+      endGesture();
+      ctx.cancelTransform?.();
+    },
+    onKeyCommand: (ctx, command) => {
+      if (gesture) {
+        // A live drag holds pointer capture (its own pointerup/pointercancel
+        // will end it); applying or cancelling now would tear the gesture down
+        // out from under the still-open pointer session, freezing the preview
+        // mid-drag. No-op instead — mirrors `applyTransform`'s own mid-gesture
+        // guard (`pipeline.isGestureActive()`) for the same reason.
+        return;
+      }
+      if (command === 'apply') {
+        ctx.applyTransform?.();
+      } else {
+        ctx.cancelTransform?.();
+      }
+    },
+    onPointerCancel: (ctx) => {
+      // Revert just this drag (keep the session); Escape's session cancel is separate.
+      if (gesture) {
+        const session = ctx.stores.transformSession.get();
+        if (session) {
+          ctx.updateTransformSession?.(gesture.startTransform);
+        }
+        endGesture();
+        ctx.invalidate({ overlay: true });
+      }
+    },
+    onPointerDown: (ctx, input) => {
+      if (gesture || (input.buttons & PRIMARY_BUTTON) === 0) {
+        return;
+      }
+      const doc = ctx.getDocument();
+      if (!doc) {
+        return;
+      }
+      const session = ctx.stores.transformSession.get();
+
+      // 1) An open session: a press on its frame starts a scale/rotate/move gesture.
+      if (session) {
+        const layer = doc.layers.find((candidate) => candidate.id === session.layerId);
+        const rect = layer ? hittableLayerRect(layer, doc) : null;
+        const target = rect ? targetAt(ctx, input.screenPoint) : null;
+        if (rect && target) {
+          gesture = {
+            cursor: target.kind === 'rotate' ? 'grabbing' : cursorForTarget(session.transform, target),
+            moved: false,
+            rect,
+            startPointerDoc: input.documentPoint,
+            startScreen: input.screenPoint,
+            startTransform: session.transform,
+            target,
+          };
+          return;
+        }
+      }
+
+      // 2) No session, or a press off the session frame: adopt the top-most eligible
+      //    layer under the pointer and start a move gesture on it. Empty space is a
+      //    no-op (the current session, if any, persists).
+      const hit = topLayerAt(doc, input.documentPoint, (layer) => isEligible(layer, doc));
+      if (!hit) {
+        return;
+      }
+      const rect = hittableLayerRect(hit, doc);
+      if (!rect) {
+        return;
+      }
+      ctx.beginTransformSession?.(hit.id);
+      gesture = {
+        cursor: 'move',
+        moved: false,
+        rect,
+        startPointerDoc: input.documentPoint,
+        startScreen: input.screenPoint,
+        startTransform: hit.transform,
+        target: { kind: 'move' },
+      };
+    },
+    onPointerMove: (ctx, input) => {
+      if (gesture) {
+        if (!gesture.moved) {
+          const dxs = input.screenPoint.x - gesture.startScreen.x;
+          const dys = input.screenPoint.y - gesture.startScreen.y;
+          if (Math.hypot(dxs, dys) < TRANSFORM_DRAG_THRESHOLD_PX) {
+            return;
+          }
+          gesture.moved = true;
+        }
+        ctx.updateTransformSession?.(nextTransform(gesture, input));
+        return;
+      }
+      // Idle hover over a session frame: reflect the target under the pointer.
+      const session = ctx.stores.transformSession.get();
+      if (!session) {
+        if (hoverCursor !== null) {
+          hoverCursor = null;
+          ctx.updateCursor();
+        }
+        return;
+      }
+      const target = targetAt(ctx, input.screenPoint);
+      const cursor = target ? cursorForTarget(session.transform, target) : 'default';
+      if (cursor !== hoverCursor) {
+        hoverCursor = cursor;
+        ctx.updateCursor();
+      }
+    },
+    onPointerUp: () => {
+      // The session's live transform already reflects the drag; keep the session.
+      endGesture();
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/viewTool.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/viewTool.ts
new file mode 100644
index 00000000000..515e39a2720
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/tools/viewTool.ts
@@ -0,0 +1,59 @@
+/**
+ * The view tool: pan the canvas by dragging, zoom with the wheel. It is the
+ * default tool and the one the engine temporarily swaps in while space is held.
+ * All navigation flows through the viewport, so it never mutates the document
+ * and never dispatches.
+ *
+ * Each engine builds its own instance via {@link createViewTool} so the private
+ * drag state is per-engine (never module-global). Zero React, zero import-time
+ * side effects.
+ */
+
+import type { PointerInput, PointerModifiers, Vec2 } from '@workbench/canvas-engine/types';
+
+import type { Tool, ToolContext } from './tool';
+
+/** Bit for the primary (usually left) mouse button in `PointerEvent.buttons`. */
+const PRIMARY_BUTTON = 1;
+
+/** Creates a fresh view tool with its own drag state. */
+export const createViewTool = (): Tool => {
+  let panning = false;
+  let lastScreen: Vec2 | null = null;
+
+  const begin = (input: PointerInput): void => {
+    // Only the primary button pans; secondary/middle are handled by the engine.
+    if ((input.buttons & PRIMARY_BUTTON) === 0) {
+      return;
+    }
+    panning = true;
+    lastScreen = input.screenPoint;
+  };
+
+  const move = (ctx: ToolContext, input: PointerInput): void => {
+    if (!panning || !lastScreen) {
+      return;
+    }
+    ctx.viewport.panBy({ x: input.screenPoint.x - lastScreen.x, y: input.screenPoint.y - lastScreen.y });
+    lastScreen = input.screenPoint;
+    ctx.invalidate({ view: true });
+  };
+
+  const end = (): void => {
+    panning = false;
+    lastScreen = null;
+  };
+
+  return {
+    cursor: () => (panning ? 'grabbing' : 'grab'),
+    id: 'view',
+    onDeactivate: end,
+    onPointerDown: (_ctx, input) => begin(input),
+    onPointerMove: move,
+    onPointerUp: end,
+    onWheel: (ctx: ToolContext, deltaY: number, screenAnchor: Vec2, _modifiers: PointerModifiers) => {
+      ctx.viewport.wheelZoom(deltaY, screenAnchor);
+      ctx.invalidate({ view: true });
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/transform/transformMath.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/transform/transformMath.test.ts
new file mode 100644
index 00000000000..4a4951d355b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/transform/transformMath.test.ts
@@ -0,0 +1,449 @@
+import { applyToPoint } from '@workbench/canvas-engine/math/mat2d';
+import { describe, expect, it } from 'vitest';
+
+import type { LayerTransform, TransformRect } from './transformMath';
+
+import {
+  applyMove,
+  applyRotate,
+  applyScale,
+  bakeMatrix,
+  IDENTITY_TRANSFORM,
+  layerTransformMatrix,
+  localHandlePoint,
+  MIN_ABS_SCALE,
+  resizeCursorForHandle,
+  ROTATE_SNAP_RAD,
+  snapRotation,
+  TRANSFORM_ROTATE_NUB_PX,
+  transformOverlayGeometry,
+  transformTargetAt,
+} from './transformMath';
+
+/** The screen-space tip of the drawn rotation nub for `transform` at `zoom`. */
+const nubTip = (transform: LayerTransform, sz: TransformRect, zoom: number): { x: number; y: number } => {
+  const geo = transformOverlayGeometry(transform, sz);
+  const toScreen = (p: { x: number; y: number }) => ({ x: zoom * p.x, y: zoom * p.y });
+  const a = toScreen(geo.rotationAnchor);
+  const c = toScreen(geo.center);
+  const dx = a.x - c.x;
+  const dy = a.y - c.y;
+  const len = Math.hypot(dx, dy) || 1;
+  return { x: a.x + (dx / len) * TRANSFORM_ROTATE_NUB_PX, y: a.y + (dy / len) * TRANSFORM_ROTATE_NUB_PX };
+};
+
+const identity: LayerTransform = { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+const rect: TransformRect = { height: 100, width: 100, x: 0, y: 0 };
+
+/** A zoom-only screen projection (no rotation/flip), matching the real viewport. */
+const scaleToScreen =
+  (zoom: number, panX = 0, panY = 0) =>
+  (p: { x: number; y: number }) => ({ x: zoom * p.x + panX, y: zoom * p.y + panY });
+
+const identityScreen = scaleToScreen(1);
+
+const close = (a: number, b: number, eps = 1e-6): boolean => Math.abs(a - b) <= eps;
+
+describe('localHandlePoint', () => {
+  it('places corners and edge midpoints on the native rect', () => {
+    expect(localHandlePoint(rect, 'nw')).toEqual({ x: 0, y: 0 });
+    expect(localHandlePoint(rect, 'se')).toEqual({ x: 100, y: 100 });
+    expect(localHandlePoint(rect, 'e')).toEqual({ x: 100, y: 50 });
+    expect(localHandlePoint(rect, 'n')).toEqual({ x: 50, y: 0 });
+  });
+
+  it('honors an off-origin content rect (content-sized paint layers)', () => {
+    // A paint layer whose bitmap sits at offset (10, 20): every handle shifts
+    // by the origin — the frame must wrap the pixels, not [0,w]×[0,h].
+    const offOrigin: TransformRect = { height: 40, width: 60, x: 10, y: 20 };
+    expect(localHandlePoint(offOrigin, 'nw')).toEqual({ x: 10, y: 20 });
+    expect(localHandlePoint(offOrigin, 'se')).toEqual({ x: 70, y: 60 });
+    expect(localHandlePoint(offOrigin, 'e')).toEqual({ x: 70, y: 40 });
+  });
+});
+
+describe('off-origin content rect (content-sized layers)', () => {
+  const offOrigin: TransformRect = { height: 40, width: 60, x: 10, y: 20 };
+
+  it('transformOverlayGeometry wraps the off-origin rect at identity', () => {
+    const geo = transformOverlayGeometry(identity, offOrigin);
+    expect(geo.corners).toEqual([
+      { x: 10, y: 20 },
+      { x: 70, y: 20 },
+      { x: 70, y: 60 },
+      { x: 10, y: 60 },
+    ]);
+    expect(geo.center).toEqual({ x: 40, y: 40 });
+  });
+
+  it('transformTargetAt hit-tests the shifted frame (interior + corner)', () => {
+    const inside = transformTargetAt({
+      point: { x: 40, y: 40 },
+      rect: offOrigin,
+      toScreen: identityScreen,
+      transform: identity,
+    });
+    expect(inside).toEqual({ kind: 'move' });
+    const corner = transformTargetAt({
+      point: { x: 70, y: 60 },
+      rect: offOrigin,
+      toScreen: identityScreen,
+      transform: identity,
+    });
+    expect(corner).toEqual({ handle: 'se', kind: 'scale' });
+    // A point far from the shifted frame (outside its interior, handles, and
+    // rotate zones) is NOT a target, even though an (incorrect) origin-anchored
+    // frame would sit in that direction.
+    const stale = transformTargetAt({
+      point: { x: -40, y: -40 },
+      rect: offOrigin,
+      toScreen: identityScreen,
+      transform: identity,
+    });
+    expect(stale).toBeNull();
+  });
+
+  it('applyScale keeps the opposite (off-origin) anchor fixed in document space', () => {
+    // Drag the se handle from (70,60) to (130,100): 2× in both axes, anchored at nw.
+    const next = applyScale({
+      alt: false,
+      handle: 'se',
+      pointerDoc: { x: 130, y: 100 },
+      rect: offOrigin,
+      shift: false,
+      start: identity,
+      startPointerDoc: { x: 70, y: 60 },
+    });
+    expect(next.scaleX).toBeCloseTo(2, 6);
+    expect(next.scaleY).toBeCloseTo(2, 6);
+    // The nw corner (local 10,20) must not move: T = anchorDoc − S·anchorLocal.
+    const anchorAfter = applyToPoint(layerTransformMatrix(next), { x: 10, y: 20 });
+    expect(anchorAfter.x).toBeCloseTo(10, 6);
+    expect(anchorAfter.y).toBeCloseTo(20, 6);
+  });
+
+  it('applyRotate pivots about the off-origin rect center', () => {
+    const next = applyRotate({
+      pointerDoc: { x: 40, y: 100 },
+      rect: offOrigin,
+      shift: false,
+      start: identity,
+      // Start due east of the center (40,40); end due south → +90°.
+      startPointerDoc: { x: 100, y: 40 },
+    });
+    expect(next.rotation).toBeCloseTo(Math.PI / 2, 6);
+    const centerAfter = applyToPoint(layerTransformMatrix(next), { x: 40, y: 40 });
+    expect(centerAfter.x).toBeCloseTo(40, 6);
+    expect(centerAfter.y).toBeCloseTo(40, 6);
+  });
+});
+
+describe('transformTargetAt', () => {
+  it('hits a corner scale handle at zoom 1', () => {
+    const target = transformTargetAt({
+      point: { x: 100, y: 100 },
+      rect,
+      toScreen: identityScreen,
+      transform: identity,
+    });
+    expect(target).toEqual({ handle: 'se', kind: 'scale' });
+  });
+
+  it('reports the interior as move', () => {
+    const target = transformTargetAt({ point: { x: 50, y: 50 }, rect, toScreen: identityScreen, transform: identity });
+    expect(target).toEqual({ kind: 'move' });
+  });
+
+  it('reports a rotate zone just outside a corner', () => {
+    const target = transformTargetAt({
+      point: { x: 112, y: 112 },
+      rect,
+      toScreen: identityScreen,
+      transform: identity,
+    });
+    expect(target).toEqual({ handle: 'se', kind: 'rotate' });
+  });
+
+  it('hits the rotation nub above the top edge (drawn but previously not hit-testable)', () => {
+    // The nub tip sits `TRANSFORM_ROTATE_NUB_PX` above the top-edge midpoint —
+    // outside the frame polygon and away from every corner, so before the fix it
+    // fell through to `null` (misread by the tool as an off-frame press → reset).
+    const target = transformTargetAt({
+      point: nubTip(identity, rect, 1),
+      rect,
+      toScreen: identityScreen,
+      transform: identity,
+    });
+    expect(target).toEqual({ handle: 'n', kind: 'rotate' });
+  });
+
+  it('hits the rotation nub of a rotated + scaled layer at a non-1 zoom', () => {
+    const transform: LayerTransform = { rotation: 0.4, scaleX: 1.6, scaleY: 1.3, x: 30, y: 20 };
+    const target = transformTargetAt({
+      point: nubTip(transform, rect, 2),
+      rect,
+      toScreen: scaleToScreen(2),
+      transform,
+    });
+    expect(target).toEqual({ handle: 'n', kind: 'rotate' });
+  });
+
+  it('keeps the interior a move below the nub anchor (nub never steals an interior click)', () => {
+    // Inside the top edge, clear of the `'n'` scale handle: the polygon wins so a
+    // near-top interior click stays a move, never a rotate.
+    const target = transformTargetAt({ point: { x: 50, y: 20 }, rect, toScreen: identityScreen, transform: identity });
+    expect(target).toEqual({ kind: 'move' });
+  });
+
+  it('returns null far outside the frame', () => {
+    const target = transformTargetAt({
+      point: { x: 400, y: 400 },
+      rect,
+      toScreen: identityScreen,
+      transform: identity,
+    });
+    expect(target).toBeNull();
+  });
+
+  it('keeps a constant screen-space grab area under zoom (handle at scaled corner)', () => {
+    // At zoom 2 the se corner projects to (200,200); a point 3px away still hits.
+    const target = transformTargetAt({
+      point: { x: 202, y: 199 },
+      rect,
+      toScreen: scaleToScreen(2),
+      transform: identity,
+    });
+    expect(target).toEqual({ handle: 'se', kind: 'scale' });
+  });
+
+  it('hit-tests handles through the layer rotation', () => {
+    // Rotate 90° about origin: local se (100,100) → doc. Handle tracks the rotated corner.
+    const rotated: LayerTransform = { rotation: Math.PI / 2, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+    const seDoc = applyToPoint(layerTransformMatrix(rotated), localHandlePoint(rect, 'se'));
+    const target = transformTargetAt({ point: seDoc, rect, toScreen: identityScreen, transform: rotated });
+    expect(target).toEqual({ handle: 'se', kind: 'scale' });
+  });
+});
+
+describe('resizeCursorForHandle', () => {
+  it('gives axis cursors for an unrotated layer', () => {
+    expect(resizeCursorForHandle(identity, 'e')).toBe('ew-resize');
+    expect(resizeCursorForHandle(identity, 'w')).toBe('ew-resize');
+    expect(resizeCursorForHandle(identity, 'n')).toBe('ns-resize');
+    expect(resizeCursorForHandle(identity, 's')).toBe('ns-resize');
+  });
+
+  it('gives diagonal cursors for corners', () => {
+    // se outward normal (1,1) → screen y-down diagonal → nwse.
+    expect(resizeCursorForHandle(identity, 'se')).toBe('nwse-resize');
+    expect(resizeCursorForHandle(identity, 'ne')).toBe('nesw-resize');
+  });
+
+  it('rotates the cursor with the layer (45° turns an edge into a diagonal)', () => {
+    const rotated: LayerTransform = { rotation: Math.PI / 4, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+    // The n edge normal (0,-1) rotated 45° becomes a diagonal → nesw.
+    expect(resizeCursorForHandle(rotated, 'n')).toBe('nesw-resize');
+    // A 90° rotation swaps the axes: the e handle now reads vertical.
+    const quarter: LayerTransform = { rotation: Math.PI / 2, scaleX: 1, scaleY: 1, x: 0, y: 0 };
+    expect(resizeCursorForHandle(quarter, 'e')).toBe('ns-resize');
+  });
+});
+
+describe('applyScale: about the opposite handle', () => {
+  it('scales a corner about the opposite corner, tracking the pointer', () => {
+    const next = applyScale({
+      alt: false,
+      handle: 'se',
+      pointerDoc: { x: 150, y: 100 },
+      shift: false,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 100 },
+    });
+    // nw anchor fixed at (0,0); width doubled in x → scaleX 1.5, scaleY unchanged.
+    expect(close(next.scaleX, 1.5)).toBe(true);
+    expect(close(next.scaleY, 1)).toBe(true);
+    expect(close(next.x, 0)).toBe(true);
+    expect(close(next.y, 0)).toBe(true);
+  });
+
+  it('scales an edge handle on one axis only', () => {
+    const next = applyScale({
+      alt: false,
+      handle: 'e',
+      pointerDoc: { x: 150, y: 999 },
+      shift: false,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 50 },
+    });
+    expect(close(next.scaleX, 1.5)).toBe(true);
+    expect(close(next.scaleY, 1)).toBe(true);
+  });
+
+  it('keeps the opposite corner fixed in document space', () => {
+    const start: LayerTransform = { rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 20 };
+    const anchorBefore = applyToPoint(layerTransformMatrix(start), localHandlePoint(rect, 'nw'));
+    const next = applyScale({
+      alt: false,
+      handle: 'se',
+      pointerDoc: { x: 200, y: 200 },
+      shift: false,
+      rect,
+      start,
+      startPointerDoc: { x: 110, y: 120 },
+    });
+    const anchorAfter = applyToPoint(layerTransformMatrix(next), localHandlePoint(rect, 'nw'));
+    expect(close(anchorAfter.x, anchorBefore.x)).toBe(true);
+    expect(close(anchorAfter.y, anchorBefore.y)).toBe(true);
+  });
+});
+
+describe('applyScale: modifiers', () => {
+  it('alt scales about the center (center stays fixed)', () => {
+    const centerBefore = applyToPoint(layerTransformMatrix(identity), { x: 50, y: 50 });
+    const next = applyScale({
+      alt: true,
+      handle: 'se',
+      pointerDoc: { x: 150, y: 150 },
+      shift: false,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 100 },
+    });
+    const centerAfter = applyToPoint(layerTransformMatrix(next), { x: 50, y: 50 });
+    expect(close(centerAfter.x, centerBefore.x)).toBe(true);
+    expect(close(centerAfter.y, centerBefore.y)).toBe(true);
+  });
+
+  it('shift keeps a uniform aspect on a corner drag', () => {
+    const next = applyScale({
+      alt: false,
+      handle: 'se',
+      // Pointer moves mostly in x; uniform factor follows the larger axis.
+      pointerDoc: { x: 200, y: 110 },
+      shift: true,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 100 },
+    });
+    expect(close(next.scaleX, next.scaleY)).toBe(true);
+    expect(next.scaleX).toBeGreaterThan(1);
+  });
+});
+
+describe('applyScale: flip and clamp', () => {
+  it('allows a flip through the anchor (negative scale, no NaN)', () => {
+    const next = applyScale({
+      alt: false,
+      handle: 'e',
+      // Drag the east edge past the west anchor → negative scaleX.
+      pointerDoc: { x: -50, y: 50 },
+      shift: false,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 50 },
+    });
+    expect(next.scaleX).toBeLessThan(0);
+    expect(Number.isNaN(next.scaleX)).toBe(false);
+  });
+
+  it('clamps a collapsed axis to the minimum magnitude', () => {
+    const next = applyScale({
+      alt: false,
+      handle: 'e',
+      // Drag the east edge exactly onto the west anchor → zero width.
+      pointerDoc: { x: 0, y: 50 },
+      shift: false,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 50 },
+    });
+    expect(Math.abs(next.scaleX)).toBeGreaterThanOrEqual(MIN_ABS_SCALE - 1e-9);
+    expect(Number.isFinite(next.x)).toBe(true);
+  });
+});
+
+describe('applyRotate', () => {
+  it('rotates about the center by the swept angle', () => {
+    const next = applyRotate({
+      pointerDoc: { x: 50, y: 100 }, // 90° CCW around center from the start ray
+      shift: false,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 50 },
+    });
+    // start ray points +x; end ray points +y (down) → +90° in canvas space.
+    expect(close(next.rotation, Math.PI / 2)).toBe(true);
+    // Center stays fixed.
+    const center = applyToPoint(layerTransformMatrix(next), { x: 50, y: 50 });
+    expect(close(center.x, 50)).toBe(true);
+    expect(close(center.y, 50)).toBe(true);
+  });
+
+  it('snaps to 15° increments under shift', () => {
+    const next = applyRotate({
+      pointerDoc: { x: 100, y: 62 }, // a small angle just above 0
+      shift: true,
+      rect,
+      start: identity,
+      startPointerDoc: { x: 100, y: 50 },
+    });
+    const remainder = Math.abs(next.rotation % ROTATE_SNAP_RAD);
+    expect(remainder < 1e-9 || Math.abs(remainder - ROTATE_SNAP_RAD) < 1e-9).toBe(true);
+  });
+});
+
+describe('snapRotation', () => {
+  it('rounds to the nearest 15°', () => {
+    expect(close(snapRotation(ROTATE_SNAP_RAD * 0.4), 0)).toBe(true);
+    expect(close(snapRotation(ROTATE_SNAP_RAD * 0.6), ROTATE_SNAP_RAD)).toBe(true);
+  });
+});
+
+describe('applyMove', () => {
+  it('translates by the document delta', () => {
+    expect(applyMove(identity, { x: 5, y: -3 }, false)).toMatchObject({ x: 5, y: -3, rotation: 0, scaleX: 1 });
+  });
+  it('constrains to the dominant axis under shift', () => {
+    expect(applyMove(identity, { x: 8, y: 2 }, true)).toMatchObject({ x: 8, y: 0 });
+    expect(applyMove(identity, { x: 1, y: -9 }, true)).toMatchObject({ x: 0, y: -9 });
+  });
+});
+
+describe('bakeMatrix', () => {
+  it('equals the layer matrix so bake-then-draw ≡ transform-then-draw', () => {
+    const transform: LayerTransform = { rotation: Math.PI / 6, scaleX: 1.5, scaleY: 0.8, x: 12, y: 34 };
+    const bake = bakeMatrix(transform);
+    const direct = layerTransformMatrix(transform);
+    // For any local point, drawing the baked surface at identity reproduces the
+    // transformed point exactly.
+    for (const q of [
+      { x: 0, y: 0 },
+      { x: 100, y: 0 },
+      { x: 100, y: 100 },
+      { x: 40, y: 70 },
+    ]) {
+      const viaBake = applyToPoint(bake, q); // baked surface then identity draw
+      const viaTransform = applyToPoint(direct, q);
+      expect(close(viaBake.x, viaTransform.x)).toBe(true);
+      expect(close(viaBake.y, viaTransform.y)).toBe(true);
+    }
+  });
+});
+
+describe('transformOverlayGeometry', () => {
+  it('returns rotated corners, eight handles, center, and the top anchor', () => {
+    const geo = transformOverlayGeometry(identity, rect);
+    expect(geo.corners).toHaveLength(4);
+    expect(geo.handles).toHaveLength(8);
+    expect(geo.center).toEqual({ x: 50, y: 50 });
+    expect(geo.rotationAnchor).toEqual({ x: 50, y: 0 });
+  });
+});
+
+describe('IDENTITY_TRANSFORM', () => {
+  it('is a true identity', () => {
+    expect(IDENTITY_TRANSFORM).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/transform/transformMath.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/transform/transformMath.ts
new file mode 100644
index 00000000000..86a18d21aab
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/transform/transformMath.ts
@@ -0,0 +1,429 @@
+/**
+ * Pure transform math for the transform tool: handle geometry, screen-space
+ * hit-testing over a rotated/scaled layer, per-handle rotation-aware cursors, and
+ * the scale-about-anchor / rotate / move transform derivations.
+ *
+ * A layer's raster cache holds unscaled pixels in the layer's LOCAL space; the
+ * compositor draws it through `fromTRS(transform)` (translate·rotate·scale). The
+ * transform tool edits that {@link LayerTransform}. All handle positions are
+ * computed in LOCAL space, mapped to document space via the layer matrix, then
+ * projected to SCREEN space by the caller-supplied `toScreen` so grab areas stay
+ * a constant pixel size regardless of zoom (mirrors `bboxHitTest.ts`, generalized
+ * to a rotated frame). Every derivation returns a fresh transform from a captured
+ * `start` transform plus a pointer delta — negative scale (a flip past the anchor)
+ * is allowed and kept correct; `|scale|` is clamped to {@link MIN_ABS_SCALE} so a
+ * collapsed axis never produces a singular/NaN matrix.
+ *
+ * Zero React, zero DOM, zero import-time side effects.
+ */
+
+import type { Mat2d, Vec2 } from '@workbench/canvas-engine/types';
+import type { CanvasLayerBaseContract } from '@workbench/types';
+
+import { applyToPoint, fromTRS } from '@workbench/canvas-engine/math/mat2d';
+
+/** The editable layer transform (translate + per-axis scale + rotation in radians). */
+export type LayerTransform = CanvasLayerBaseContract['transform'];
+
+/**
+ * The layer's content rectangle in its LOCAL (untransformed) space — the extent
+ * being transformed. Content-sized layers can sit off-origin (a paint layer's
+ * persisted offset, negative for strokes up/left of the origin), so the frame,
+ * handles, and scale/rotate anchors are all derived from this rect, never from
+ * an assumed `[0,w]×[0,h]`.
+ */
+export interface TransformRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** The eight scale handles: four corners + four edge midpoints. */
+export type TransformHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+
+/**
+ * What a pointer landed on over the transform frame: a scale handle, a corner
+ * rotate zone (just outside a corner), or the interior (`'move'`).
+ */
+export type TransformTarget =
+  | { kind: 'scale'; handle: TransformHandle }
+  | { kind: 'rotate'; handle: TransformHandle }
+  | { kind: 'move' };
+
+/** Handles in hit-test priority order: corners first (they win over adjacent edges). */
+export const TRANSFORM_HANDLES: readonly TransformHandle[] = ['nw', 'ne', 'se', 'sw', 'n', 'e', 's', 'w'];
+
+/** The four corner handles (also the rotate-zone anchors). */
+export const CORNER_HANDLES: readonly TransformHandle[] = ['nw', 'ne', 'se', 'sw'];
+
+/** Side length (screen px) of a scale handle's square grab area. */
+export const TRANSFORM_HANDLE_HIT_PX = 14;
+
+/** Radius (screen px) of a corner's rotate zone, measured from the corner outward. */
+export const TRANSFORM_ROTATE_ZONE_PX = 22;
+
+/**
+ * Screen-px length of the rotation-indicator nub the overlay draws past the top
+ * edge midpoint (the `'n'` handle), outward away from the center. Shared with the
+ * overlay renderer so the drawn nub and its hit region stay in lock-step.
+ */
+export const TRANSFORM_ROTATE_NUB_PX = 18;
+
+/** Screen-px grab radius around the rotation nub/knob (the capsule half-width). */
+export const TRANSFORM_ROTATE_NUB_HIT_PX = 11;
+
+/** Rotation snap increment under shift: 15°. */
+export const ROTATE_SNAP_RAD = Math.PI / 12;
+
+/** Smallest permitted |scaleX|/|scaleY| — keeps the layer matrix invertible. */
+export const MIN_ABS_SCALE = 0.01;
+
+/** The corner/edge opposite a handle (the fixed anchor for a non-alt scale). */
+const OPPOSITE: Record<TransformHandle, TransformHandle> = {
+  e: 'w',
+  n: 's',
+  ne: 'sw',
+  nw: 'se',
+  s: 'n',
+  se: 'nw',
+  sw: 'ne',
+  w: 'e',
+};
+
+const hasWest = (h: TransformHandle): boolean => h === 'nw' || h === 'w' || h === 'sw';
+const hasEast = (h: TransformHandle): boolean => h === 'ne' || h === 'e' || h === 'se';
+const hasNorth = (h: TransformHandle): boolean => h === 'nw' || h === 'n' || h === 'ne';
+const hasSouth = (h: TransformHandle): boolean => h === 'sw' || h === 's' || h === 'se';
+
+/** True for the four corner handles (two-letter ids). */
+export const isCornerHandle = (h: TransformHandle): boolean => h.length === 2;
+
+/** A handle's position on the layer's local content rect (off-origin aware). */
+export const localHandlePoint = (rect: TransformRect, handle: TransformHandle): Vec2 => ({
+  x: rect.x + (hasWest(handle) ? 0 : hasEast(handle) ? rect.width : rect.width / 2),
+  y: rect.y + (hasNorth(handle) ? 0 : hasSouth(handle) ? rect.height : rect.height / 2),
+});
+
+/** The local content rect's center (the rotation pivot / alt-scale anchor). */
+const localCenter = (rect: TransformRect): Vec2 => ({
+  x: rect.x + rect.width / 2,
+  y: rect.y + rect.height / 2,
+});
+
+/** The layer's local→document affine matrix from its transform. */
+export const layerTransformMatrix = (t: LayerTransform): Mat2d =>
+  fromTRS({ x: t.x, y: t.y }, t.rotation, t.scaleX, t.scaleY);
+
+/** The rotation matrix for `rad` (linear part only). */
+const rotationMat = (rad: number): { a: number; b: number; c: number; d: number } => {
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  return { a: cos, b: sin, c: -sin, d: cos };
+};
+
+/** Applies a rotation matrix's linear part to a vector. */
+const applyLinear = (m: { a: number; b: number; c: number; d: number }, v: Vec2): Vec2 => ({
+  x: m.a * v.x + m.c * v.y,
+  y: m.b * v.x + m.d * v.y,
+});
+
+/** A handle's outward normal in LOCAL space (y-down, matching document/screen). */
+const localOutward = (handle: TransformHandle): Vec2 => ({
+  x: hasWest(handle) ? -1 : hasEast(handle) ? 1 : 0,
+  y: hasNorth(handle) ? -1 : hasSouth(handle) ? 1 : 0,
+});
+
+/**
+ * Geometry the overlay needs to draw the transform frame, in DOCUMENT space
+ * (the overlay projects each point through the view). `handles` is ordered to
+ * match {@link TRANSFORM_HANDLES}.
+ */
+export interface TransformOverlayGeometry {
+  /** The four rotated-rect corners (nw, ne, se, sw) for the bounds polygon. */
+  corners: Vec2[];
+  /** The eight scale-handle positions (order = {@link TRANSFORM_HANDLES}). */
+  handles: Vec2[];
+  /** The layer center (rotation pivot). */
+  center: Vec2;
+  /** The top edge midpoint (root of the rotation indicator nub). */
+  rotationAnchor: Vec2;
+}
+
+/** Document-space geometry for the transform overlay of a layer at `transform`. */
+export const transformOverlayGeometry = (transform: LayerTransform, rect: TransformRect): TransformOverlayGeometry => {
+  const m = layerTransformMatrix(transform);
+  return {
+    center: applyToPoint(m, localCenter(rect)),
+    corners: (['nw', 'ne', 'se', 'sw'] as const).map((h) => applyToPoint(m, localHandlePoint(rect, h))),
+    handles: TRANSFORM_HANDLES.map((h) => applyToPoint(m, localHandlePoint(rect, h))),
+    rotationAnchor: applyToPoint(m, localHandlePoint(rect, 'n')),
+  };
+};
+
+/** True when `pt` is inside the convex polygon `poly` (consistent-winding cross test). */
+const pointInConvexPolygon = (poly: readonly Vec2[], pt: Vec2): boolean => {
+  let pos = false;
+  let neg = false;
+  for (let i = 0; i < poly.length; i++) {
+    const a = poly[i]!;
+    const b = poly[(i + 1) % poly.length]!;
+    const cross = (b.x - a.x) * (pt.y - a.y) - (b.y - a.y) * (pt.x - a.x);
+    if (cross > 1e-9) {
+      pos = true;
+    } else if (cross < -1e-9) {
+      neg = true;
+    }
+    if (pos && neg) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/** Distance (screen px) from `p` to the segment `a`→`b`. */
+const distanceToSegment = (p: Vec2, a: Vec2, b: Vec2): number => {
+  const abx = b.x - a.x;
+  const aby = b.y - a.y;
+  const len2 = abx * abx + aby * aby;
+  const t = len2 > 0 ? Math.max(0, Math.min(1, ((p.x - a.x) * abx + (p.y - a.y) * aby) / len2)) : 0;
+  return Math.hypot(p.x - (a.x + t * abx), p.y - (a.y + t * aby));
+};
+
+/** Parameters for {@link transformTargetAt}. */
+export interface TransformHitTestParams {
+  transform: LayerTransform;
+  rect: TransformRect;
+  /** Projects a document-space point to screen space (CSS px). */
+  toScreen: (docPoint: Vec2) => Vec2;
+  /** The screen-space pointer position (CSS px). */
+  point: Vec2;
+  /** Scale-handle grab-area side length (screen px). */
+  handleHitPx?: number;
+  /** Corner rotate-zone radius (screen px). */
+  rotateZonePx?: number;
+  /** Rotation-nub grab radius (screen px). */
+  rotateNubHitPx?: number;
+}
+
+/**
+ * What a screen-space `point` targets on the transform frame: a scale handle
+ * (grab area first, corners before edges), a corner rotate zone (outside the
+ * frame, near a corner), the interior (`'move'`), or `null`.
+ */
+export const transformTargetAt = (params: TransformHitTestParams): TransformTarget | null => {
+  const { point, rect, toScreen, transform } = params;
+  const half = (params.handleHitPx ?? TRANSFORM_HANDLE_HIT_PX) / 2;
+  const m = layerTransformMatrix(transform);
+  const screenOf = (handle: TransformHandle): Vec2 => toScreen(applyToPoint(m, localHandlePoint(rect, handle)));
+
+  for (const handle of TRANSFORM_HANDLES) {
+    const s = screenOf(handle);
+    if (Math.abs(point.x - s.x) <= half && Math.abs(point.y - s.y) <= half) {
+      return { handle, kind: 'scale' };
+    }
+  }
+
+  const screenCorners = CORNER_HANDLES.map(screenOf);
+  if (pointInConvexPolygon(screenCorners, point)) {
+    return { kind: 'move' };
+  }
+
+  // Rotation nub: a capsule from the top-edge (`'n'`) midpoint outward (away
+  // from center) by `TRANSFORM_ROTATE_NUB_PX`, matching the drawn nub. Tested
+  // after the interior polygon (so an interior click stays a move) and before
+  // the corner rotate zones (disjoint regions — a top-middle nub vs corners).
+  // Without this, a click on the visible nub falls through to `null`, which the
+  // tool misreads as an off-frame press — re-opening the session (resetting its
+  // live transform) instead of starting a rotation.
+  const anchorScreen = screenOf('n');
+  const centerScreen = toScreen(applyToPoint(m, { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 }));
+  const outX = anchorScreen.x - centerScreen.x;
+  const outY = anchorScreen.y - centerScreen.y;
+  const outLen = Math.hypot(outX, outY) || 1;
+  const nubTip: Vec2 = {
+    x: anchorScreen.x + (outX / outLen) * TRANSFORM_ROTATE_NUB_PX,
+    y: anchorScreen.y + (outY / outLen) * TRANSFORM_ROTATE_NUB_PX,
+  };
+  if (distanceToSegment(point, anchorScreen, nubTip) <= (params.rotateNubHitPx ?? TRANSFORM_ROTATE_NUB_HIT_PX)) {
+    return { handle: 'n', kind: 'rotate' };
+  }
+
+  const zone = params.rotateZonePx ?? TRANSFORM_ROTATE_ZONE_PX;
+  for (let i = 0; i < CORNER_HANDLES.length; i++) {
+    const s = screenCorners[i]!;
+    if (Math.hypot(point.x - s.x, point.y - s.y) <= zone) {
+      return { handle: CORNER_HANDLES[i]!, kind: 'rotate' };
+    }
+  }
+  return null;
+};
+
+/** The four resize cursors, indexed by the quantized 45° bucket of the outward normal. */
+const RESIZE_CURSORS = ['ew-resize', 'nesw-resize', 'ns-resize', 'nwse-resize'] as const;
+
+/**
+ * The resize cursor for a scale handle, accounting for the layer's rotation:
+ * the handle's outward normal is rotated/scaled by the layer matrix, then the
+ * resulting screen-space angle is quantized to one of the four resize
+ * orientations. (The view adds only a uniform scale — no rotation/flip — so the
+ * document-space angle equals the screen-space angle.)
+ */
+export const resizeCursorForHandle = (transform: LayerTransform, handle: TransformHandle): string => {
+  const m = layerTransformMatrix(transform);
+  const dir = applyLinear(m, localOutward(handle));
+  // Screen space is y-down; negate y to get a conventional (y-up) math angle.
+  let deg = (Math.atan2(-dir.y, dir.x) * 180) / Math.PI;
+  deg = ((deg % 360) + 360) % 360;
+  deg %= 180; // opposite directions share a resize cursor
+  const bucket = Math.round(deg / 45) % 4;
+  return RESIZE_CURSORS[bucket]!;
+};
+
+/** Clamps |s| to at least {@link MIN_ABS_SCALE}, preserving sign (0 → +MIN). */
+const clampScale = (s: number): number => {
+  if (!Number.isFinite(s) || s === 0) {
+    return MIN_ABS_SCALE;
+  }
+  const sign = s < 0 ? -1 : 1;
+  return Math.abs(s) < MIN_ABS_SCALE ? sign * MIN_ABS_SCALE : s;
+};
+
+/** Applies shift axis-constraint to a document-space delta (dominant axis wins). */
+export const constrainMoveDelta = (delta: Vec2, shift: boolean): Vec2 => {
+  if (!shift) {
+    return delta;
+  }
+  return Math.abs(delta.x) >= Math.abs(delta.y) ? { x: delta.x, y: 0 } : { x: 0, y: delta.y };
+};
+
+/** Translates `start` by a document-space pointer delta (shift = axis constrain). */
+export const applyMove = (start: LayerTransform, deltaDoc: Vec2, shift: boolean): LayerTransform => {
+  const d = constrainMoveDelta(deltaDoc, shift);
+  return { ...start, x: start.x + d.x, y: start.y + d.y };
+};
+
+/** Parameters for {@link applyScale}. */
+export interface ScaleParams {
+  start: LayerTransform;
+  rect: TransformRect;
+  handle: TransformHandle;
+  /** Pointer position (document space) at gesture start. */
+  startPointerDoc: Vec2;
+  /** Current pointer position (document space). */
+  pointerDoc: Vec2;
+  /** Preserve aspect ratio (corner handles only). */
+  shift: boolean;
+  /** Scale about the layer center instead of the opposite handle. */
+  alt: boolean;
+}
+
+/**
+ * Scales `start` by dragging `handle`, anchored at the opposite handle (or the
+ * center under `alt`). The grabbed handle tracks the pointer; edge handles scale
+ * one axis, corners scale both (`shift` forces a uniform, aspect-preserving
+ * factor). Dragging past the anchor flips the axis (negative scale), which is
+ * kept correct; each axis is clamped to {@link MIN_ABS_SCALE}.
+ */
+export const applyScale = (p: ScaleParams): LayerTransform => {
+  const { alt, handle, rect, shift, start } = p;
+  const m = layerTransformMatrix(start);
+  const handleLocal = localHandlePoint(rect, handle);
+  const anchorLocal = alt ? localCenter(rect) : localHandlePoint(rect, OPPOSITE[handle]);
+  const anchorDoc = applyToPoint(m, anchorLocal);
+  const handleDoc = applyToPoint(m, handleLocal);
+  const targetDoc: Vec2 = {
+    x: handleDoc.x + (p.pointerDoc.x - p.startPointerDoc.x),
+    y: handleDoc.y + (p.pointerDoc.y - p.startPointerDoc.y),
+  };
+
+  // Un-rotate the anchor→target vector into the layer's scaled-local frame.
+  const cos = Math.cos(start.rotation);
+  const sin = Math.sin(start.rotation);
+  const dx = targetDoc.x - anchorDoc.x;
+  const dy = targetDoc.y - anchorDoc.y;
+  const vx = cos * dx + sin * dy;
+  const vy = -sin * dx + cos * dy;
+
+  const dlx = handleLocal.x - anchorLocal.x;
+  const dly = handleLocal.y - anchorLocal.y;
+  let sx = dlx !== 0 ? vx / dlx : start.scaleX;
+  let sy = dly !== 0 ? vy / dly : start.scaleY;
+
+  if (shift && isCornerHandle(handle)) {
+    const fx = start.scaleX !== 0 ? sx / start.scaleX : 1;
+    const fy = start.scaleY !== 0 ? sy / start.scaleY : 1;
+    const f = Math.abs(fx) >= Math.abs(fy) ? fx : fy;
+    sx = start.scaleX * f;
+    sy = start.scaleY * f;
+  }
+
+  sx = clampScale(sx);
+  sy = clampScale(sy);
+
+  // Keep the anchor fixed: T = anchorDoc − R·(sx·anchorLocal.x, sy·anchorLocal.y).
+  const rs = applyLinear(rotationMat(start.rotation), { x: sx * anchorLocal.x, y: sy * anchorLocal.y });
+  return {
+    rotation: start.rotation,
+    scaleX: sx,
+    scaleY: sy,
+    x: anchorDoc.x - rs.x,
+    y: anchorDoc.y - rs.y,
+  };
+};
+
+/** Snaps a radian angle to the nearest {@link ROTATE_SNAP_RAD} increment. */
+export const snapRotation = (rad: number): number => Math.round(rad / ROTATE_SNAP_RAD) * ROTATE_SNAP_RAD;
+
+/** Parameters for {@link applyRotate}. */
+export interface RotateParams {
+  start: LayerTransform;
+  rect: TransformRect;
+  startPointerDoc: Vec2;
+  pointerDoc: Vec2;
+  /** Snap the resulting absolute rotation to 15° increments. */
+  shift: boolean;
+}
+
+/**
+ * Rotates `start` about the layer center by the angle the pointer sweeps around
+ * that center since gesture start. `shift` snaps the resulting absolute rotation
+ * to 15° increments. Scale is unchanged.
+ */
+export const applyRotate = (p: RotateParams): LayerTransform => {
+  const { rect, start } = p;
+  const m = layerTransformMatrix(start);
+  const centerLocal = localCenter(rect);
+  const center = applyToPoint(m, centerLocal);
+  const a0 = Math.atan2(p.startPointerDoc.y - center.y, p.startPointerDoc.x - center.x);
+  const a1 = Math.atan2(p.pointerDoc.y - center.y, p.pointerDoc.x - center.x);
+  let rotation = start.rotation + (a1 - a0);
+  if (p.shift) {
+    rotation = snapRotation(rotation);
+  }
+  // Keep the center fixed: T = center − R(rotation)·(sx·cx, sy·cy).
+  const rs = applyLinear(rotationMat(rotation), {
+    x: start.scaleX * centerLocal.x,
+    y: start.scaleY * centerLocal.y,
+  });
+  return {
+    rotation,
+    scaleX: start.scaleX,
+    scaleY: start.scaleY,
+    x: center.x - rs.x,
+    y: center.y - rs.y,
+  };
+};
+
+/**
+ * The matrix that renders a layer's local (cache) pixels into a NEW document-space
+ * surface so that the result, drawn at identity, reproduces the layer as if drawn
+ * through `transform` — i.e. `fromTRS(transform)`. Used by the paint-layer bake:
+ * old pixels are drawn through this matrix, the layer transform is then reset to
+ * identity, and the composite is unchanged. Kept as a named helper so the bake
+ * site reads intentionally and composes with `math/mat2d`.
+ */
+export const bakeMatrix = (transform: LayerTransform): Mat2d => layerTransformMatrix(transform);
+
+/** The identity transform (a reset layer transform after a bake). */
+export const IDENTITY_TRANSFORM: LayerTransform = { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 };
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/types.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/types.ts
new file mode 100644
index 00000000000..a7678c5342c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/types.ts
@@ -0,0 +1,118 @@
+/**
+ * Core types for the canvas engine.
+ *
+ * This module is the shared vocabulary for the imperative canvas engine
+ * (`src/workbench/canvas-engine/`). It has zero React imports and zero
+ * side effects at import time — it is pure type/interface declarations (the
+ * single type-only import below is erased at compile time).
+ */
+
+import type { RasterSurface } from './render/raster';
+
+/** A 2D point or vector. */
+export interface Vec2 {
+  x: number;
+  y: number;
+}
+
+/** An axis-aligned rectangle. */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * A raster surface placed in some coordinate space: the surface holds pixels for
+ * `rect` (its bounds in that space), so surface pixel `(sx, sy)` maps to
+ * `(rect.x + sx, rect.y + sy)`. Used for content-sized layer caches (layer-local
+ * space) and the bounded selection mask (document space).
+ */
+export interface PlacedSurface {
+  surface: RasterSurface;
+  rect: Rect;
+}
+
+/**
+ * A 2D affine transform matrix, using the canvas transform convention:
+ *
+ * ```
+ * x' = a*x + c*y + e
+ * y' = b*x + d*y + f
+ * ```
+ *
+ * This matches `CanvasRenderingContext2D.setTransform(a, b, c, d, e, f)` and
+ * the DOMMatrix 2D constructor argument order.
+ */
+export interface Mat2d {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}
+
+/** Identifiers for the tools the engine's interaction layer can dispatch to. */
+export type ToolId =
+  | 'brush'
+  | 'eraser'
+  | 'shape'
+  | 'gradient'
+  | 'lasso'
+  | 'move'
+  | 'transform'
+  | 'bbox'
+  | 'view'
+  | 'colorPicker'
+  | 'text'
+  | 'sam';
+
+/**
+ * A pixel-selection boolean operation applied when a new lasso path commits
+ * against the existing selection mask (see `selection/selectionState.ts`):
+ * `replace` swaps it, `add` unions, `subtract` cuts out, `intersect` keeps the
+ * overlap.
+ */
+export type SelectionOp = 'replace' | 'add' | 'subtract' | 'intersect';
+
+/** Modifier key state accompanying a pointer sample. */
+export interface PointerModifiers {
+  shift: boolean;
+  alt: boolean;
+  ctrl: boolean;
+  meta: boolean;
+}
+
+/** A normalized pointer sample fed into the engine's interaction layer. */
+export interface PointerInput {
+  /** Pointer position in document space (unaffected by pan/zoom). */
+  documentPoint: Vec2;
+  /** Pointer position in screen/viewport space (CSS pixels). */
+  screenPoint: Vec2;
+  /** Pressure in [0, 1]. 0.5 is used for devices that don't report pressure. */
+  pressure: number;
+  /** Bitmask of currently-pressed buttons, matching `PointerEvent.buttons`. */
+  buttons: number;
+  modifiers: PointerModifiers;
+  pointerType: 'mouse' | 'pen' | 'touch';
+  /** High-resolution timestamp (ms), matching `PointerEvent.timeStamp`. */
+  timeStamp: number;
+}
+
+/**
+ * Describes what needs to be re-rendered on the next frame. Consumers
+ * (scheduler/compositor, added in later tasks) union flags together rather
+ * than always doing a full repaint.
+ */
+export interface RenderFlags {
+  /** The viewport transform (pan/zoom) changed. */
+  view: boolean;
+  /** Ids of layers whose pixel content or transform changed. */
+  layers: Set<string>;
+  /** Interaction overlays (selection, cursors, guides) changed. */
+  overlay: boolean;
+  /** Force a full repaint, ignoring the other flags. */
+  all: boolean;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/viewport.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/viewport.test.ts
new file mode 100644
index 00000000000..6558f61a7ff
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/viewport.test.ts
@@ -0,0 +1,114 @@
+import type { Vec2 } from '@workbench/canvas-engine/types';
+
+import { applyToPoint } from '@workbench/canvas-engine/math/mat2d';
+import { ZOOM_SNAP_CANDIDATES } from '@workbench/canvas-engine/math/snapping';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createViewport } from './viewport';
+
+const closeTo = (a: Vec2, b: Vec2, eps = 1e-6): void => {
+  expect(a.x).toBeCloseTo(b.x, 6);
+  expect(a.y).toBeCloseTo(b.y, 6);
+  void eps;
+};
+
+describe('createViewport', () => {
+  it('round-trips screen↔document with pan and zoom', () => {
+    const vp = createViewport({ pan: { x: 30, y: -12 }, zoom: 1.5 });
+    const doc: Vec2 = { x: 42, y: 17 };
+    const screen = vp.documentToScreen(doc);
+    // screen = zoom*doc + pan
+    closeTo(screen, { x: 1.5 * 42 + 30, y: 1.5 * 17 - 12 });
+    closeTo(vp.screenToDocument(screen), doc);
+  });
+
+  it('viewMatrix folds dpr into scale and translation (device = dpr * screen)', () => {
+    const vp = createViewport({ pan: { x: 10, y: 5 }, zoom: 2 });
+    const dpr = 2;
+    const m = vp.viewMatrix(dpr);
+    const doc: Vec2 = { x: 7, y: 9 };
+    const device = applyToPoint(m, doc);
+    const screen = vp.documentToScreen(doc);
+    closeTo(device, { x: screen.x * dpr, y: screen.y * dpr });
+  });
+
+  it('zoomAtPoint keeps the anchored document point fixed on screen', () => {
+    const vp = createViewport({ pan: { x: 0, y: 0 }, zoom: 1 });
+    const anchor: Vec2 = { x: 200, y: 120 };
+    const docUnderAnchorBefore = vp.screenToDocument(anchor);
+    vp.zoomAtPoint(3, anchor);
+    expect(vp.getZoom()).toBe(3);
+    // The document point under the anchor must project back to the same screen anchor.
+    closeTo(vp.documentToScreen(docUnderAnchorBefore), anchor);
+  });
+
+  it('wheelZoom snaps to a candidate when the exponential step lands near one', () => {
+    const vp = createViewport({ pan: { x: 0, y: 0 }, zoom: 1 });
+    const anchor: Vec2 = { x: 0, y: 0 };
+    // A tiny negative deltaY nudges zoom just above 1; it should snap back to 1.
+    vp.wheelZoom(-1, anchor);
+    expect(vp.getZoom()).toBe(1);
+    expect(ZOOM_SNAP_CANDIDATES).toContain(vp.getZoom());
+  });
+
+  it('wheelZoom zooms out on positive deltaY and in on negative deltaY', () => {
+    const vpOut = createViewport({ zoom: 1 });
+    vpOut.wheelZoom(400, { x: 0, y: 0 });
+    expect(vpOut.getZoom()).toBeLessThan(1);
+
+    const vpIn = createViewport({ zoom: 1 });
+    vpIn.wheelZoom(-400, { x: 0, y: 0 });
+    expect(vpIn.getZoom()).toBeGreaterThan(1);
+  });
+
+  it('fitToView centers the document and applies padding-limited zoom', () => {
+    const vp = createViewport();
+    const documentRect = { height: 100, width: 200, x: 0, y: 0 };
+    const viewportSize = { height: 400, width: 400 };
+    const padding = 50;
+    vp.fitToView(documentRect, viewportSize, padding);
+
+    // avail = 400 - 2*50 = 300; zoom = min(300/200, 300/100) = 1.5
+    expect(vp.getZoom()).toBeCloseTo(1.5, 6);
+    // Document center maps to viewport center.
+    const docCenter: Vec2 = { x: 100, y: 50 };
+    closeTo(vp.documentToScreen(docCenter), { x: 200, y: 200 });
+  });
+
+  it('fitToView is a no-op for a degenerate viewport', () => {
+    const vp = createViewport({ zoom: 2 });
+    vp.fitToView({ height: 100, width: 100, x: 0, y: 0 }, { height: 0, width: 0 });
+    expect(vp.getZoom()).toBe(2);
+  });
+
+  it('panBy translates in screen space', () => {
+    const vp = createViewport({ pan: { x: 5, y: 5 }, zoom: 2 });
+    vp.panBy({ x: 10, y: -4 });
+    expect(vp.getState().pan).toEqual({ x: 15, y: 1 });
+  });
+
+  it('setViewportSize clamps dpr to the max and notifies on change', () => {
+    const vp = createViewport();
+    const listener = vi.fn();
+    vp.subscribe(listener);
+    vp.setViewportSize(800, 600, 3);
+    expect(vp.getDpr()).toBe(2);
+    expect(vp.getViewportSize()).toEqual({ height: 600, width: 800 });
+    expect(listener).toHaveBeenCalledTimes(1);
+    // Identical call does not re-notify.
+    vp.setViewportSize(800, 600, 3);
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('notifies subscribers on zoom/pan and stops after unsubscribe', () => {
+    const vp = createViewport();
+    const listener = vi.fn();
+    const unsubscribe = vp.subscribe(listener);
+    vp.panBy({ x: 1, y: 0 });
+    vp.zoomAtPoint(2, { x: 0, y: 0 });
+    expect(listener).toHaveBeenCalledTimes(2);
+    unsubscribe();
+    vp.panBy({ x: 1, y: 0 });
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-engine/viewport.ts b/invokeai/frontend/webv2/src/workbench/canvas-engine/viewport.ts
new file mode 100644
index 00000000000..1715e8b9aa6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-engine/viewport.ts
@@ -0,0 +1,185 @@
+/**
+ * The pan/zoom viewport: the single source of truth for how document space
+ * maps to the on-screen canvas. It owns `{ pan, zoom }`, the CSS viewport
+ * size, and the device-pixel ratio, and derives the document→screen
+ * transform used by both the renderer (device pixels) and pointer routing
+ * (CSS pixels).
+ *
+ * ## Coordinate convention
+ *
+ * - **Document space**: the canvas document's own pixel grid, unaffected by
+ *   pan/zoom (a layer at document `(0,0)` is the top-left of the document).
+ * - **Screen/CSS space**: CSS pixels relative to the canvas element's
+ *   top-left. This is what `PointerEvent.clientX/Y` (minus the element rect)
+ *   gives you. `pan` is stored in CSS pixels.
+ * - **Device space**: the canvas backing store, `CSS × dpr`. The renderer
+ *   draws here.
+ *
+ * The mappings are:
+ * ```
+ * screen = zoom * doc + pan            (CSS pixels)
+ * device = dpr * screen = (zoom*dpr) * doc + dpr*pan
+ * ```
+ * so `viewMatrix(dpr)` is `scale(zoom*dpr)` followed by a `dpr*pan`
+ * translation — i.e. `a = d = zoom*dpr`, `e = dpr*pan.x`, `f = dpr*pan.y`.
+ *
+ * Zero React, zero import-time side effects; DOM-free (operates on plain
+ * numbers), so it runs unchanged in node tests.
+ */
+
+import type { Mat2d, Rect, Vec2 } from '@workbench/canvas-engine/types';
+
+import { applyToPoint, invert } from '@workbench/canvas-engine/math/mat2d';
+import { clampZoom, snapZoom } from '@workbench/canvas-engine/math/snapping';
+
+/** Maximum device-pixel ratio the engine honors; higher DPRs are clamped to bound backing-store size. */
+export const MAX_DPR = 2;
+
+/** Wheel exponential zoom sensitivity: `zoom *= exp(-deltaY * step)`. */
+export const WHEEL_ZOOM_STEP = 0.0015;
+
+/** The mutable view state. */
+export interface ViewState {
+  pan: Vec2;
+  zoom: number;
+}
+
+/** A `{ width, height }` size in CSS pixels. */
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/** The imperative viewport handle. */
+export interface Viewport {
+  /** Current `{ pan, zoom }` (a fresh copy — never mutate the return value). */
+  getState(): ViewState;
+  /** Current zoom factor. */
+  getZoom(): number;
+  /** Current CSS viewport size. */
+  getViewportSize(): Size;
+  /** Current (clamped) device-pixel ratio. */
+  getDpr(): number;
+  /** The document→device-pixel transform for the given `dpr`. */
+  viewMatrix(dpr: number): Mat2d;
+  /** Maps a CSS-pixel screen point to document space. */
+  screenToDocument(p: Vec2): Vec2;
+  /** Maps a document point to a CSS-pixel screen point. */
+  documentToScreen(p: Vec2): Vec2;
+  /** Sets zoom while keeping the document point under `screenAnchor` fixed. */
+  zoomAtPoint(newZoom: number, screenAnchor: Vec2): void;
+  /** Exponential wheel zoom about `screenAnchor`, snapping near common zoom levels. */
+  wheelZoom(deltaY: number, screenAnchor: Vec2): void;
+  /** Pans by a CSS-pixel screen delta. */
+  panBy(screenDelta: Vec2): void;
+  /** Centers and zooms to fit `documentRect` within `viewportSize` (minus `padding`). */
+  fitToView(documentRect: Rect, viewportSize: Size, padding?: number): void;
+  /** Records the CSS viewport size and device-pixel ratio (dpr clamped to {@link MAX_DPR}). */
+  setViewportSize(width: number, height: number, dpr: number): void;
+  /** Subscribes to any view change. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+}
+
+/** Default fit-to-view padding in CSS pixels. */
+const DEFAULT_FIT_PADDING = 48;
+
+/** Creates a viewport, optionally seeded with an initial view state / size. */
+export const createViewport = (initial?: Partial<ViewState>): Viewport => {
+  let pan: Vec2 = { x: initial?.pan?.x ?? 0, y: initial?.pan?.y ?? 0 };
+  let zoom = clampZoom(initial?.zoom ?? 1);
+  let size: Size = { height: 0, width: 0 };
+  let dpr = 1;
+
+  const listeners = new Set<() => void>();
+
+  const emit = (): void => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+
+  const cssMatrix = (): Mat2d => ({ a: zoom, b: 0, c: 0, d: zoom, e: pan.x, f: pan.y });
+
+  const documentToScreen = (p: Vec2): Vec2 => ({ x: zoom * p.x + pan.x, y: zoom * p.y + pan.y });
+
+  const screenToDocument = (p: Vec2): Vec2 => {
+    const inverse = invert(cssMatrix());
+    if (!inverse) {
+      return { x: 0, y: 0 };
+    }
+    return applyToPoint(inverse, p);
+  };
+
+  const zoomAtPoint = (newZoom: number, screenAnchor: Vec2): void => {
+    const clamped = clampZoom(newZoom);
+    // Keep the document point currently under the anchor fixed on screen.
+    const docAnchor = screenToDocument(screenAnchor);
+    zoom = clamped;
+    pan = { x: screenAnchor.x - clamped * docAnchor.x, y: screenAnchor.y - clamped * docAnchor.y };
+    emit();
+  };
+
+  const wheelZoom = (deltaY: number, screenAnchor: Vec2): void => {
+    const target = clampZoom(zoom * Math.exp(-deltaY * WHEEL_ZOOM_STEP));
+    zoomAtPoint(snapZoom(target), screenAnchor);
+  };
+
+  const panBy = (screenDelta: Vec2): void => {
+    pan = { x: pan.x + screenDelta.x, y: pan.y + screenDelta.y };
+    emit();
+  };
+
+  const fitToView = (documentRect: Rect, viewportSize: Size, padding: number = DEFAULT_FIT_PADDING): void => {
+    const availWidth = viewportSize.width - padding * 2;
+    const availHeight = viewportSize.height - padding * 2;
+    if (documentRect.width <= 0 || documentRect.height <= 0 || availWidth <= 0 || availHeight <= 0) {
+      return;
+    }
+    const fitZoom = clampZoom(Math.min(availWidth / documentRect.width, availHeight / documentRect.height));
+    const docCenter: Vec2 = {
+      x: documentRect.x + documentRect.width / 2,
+      y: documentRect.y + documentRect.height / 2,
+    };
+    zoom = fitZoom;
+    pan = { x: viewportSize.width / 2 - fitZoom * docCenter.x, y: viewportSize.height / 2 - fitZoom * docCenter.y };
+    emit();
+  };
+
+  const setViewportSize = (width: number, height: number, nextDpr: number): void => {
+    const clampedDpr = Math.max(1, Math.min(MAX_DPR, nextDpr));
+    if (size.width === width && size.height === height && dpr === clampedDpr) {
+      return;
+    }
+    size = { height, width };
+    dpr = clampedDpr;
+    emit();
+  };
+
+  return {
+    documentToScreen,
+    fitToView,
+    getDpr: () => dpr,
+    getState: () => ({ pan: { x: pan.x, y: pan.y }, zoom }),
+    getViewportSize: () => ({ height: size.height, width: size.width }),
+    getZoom: () => zoom,
+    panBy,
+    screenToDocument,
+    setViewportSize,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    viewMatrix: (matrixDpr) => ({
+      a: zoom * matrixDpr,
+      b: 0,
+      c: 0,
+      d: zoom * matrixDpr,
+      e: pan.x * matrixDpr,
+      f: pan.y * matrixDpr,
+    }),
+    wheelZoom,
+    zoomAtPoint,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/FilterOperationCoordinator.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/FilterOperationCoordinator.test.ts
new file mode 100644
index 00000000000..9dd828b7956
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/FilterOperationCoordinator.test.ts
@@ -0,0 +1,97 @@
+import type { FilterOperationSession } from '@workbench/canvas-operations/contracts';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createFilterOperationCoordinator } from './FilterOperationCoordinator';
+import { createCanvasOperationStores } from './operationStores';
+
+const layer = {
+  filter: null,
+  id: 'layer-1',
+  isEnabled: true,
+  isLocked: false,
+  name: 'Layer 1',
+  type: 'raster',
+} as const;
+
+const createSession = (): FilterOperationSession => ({
+  blockCommit: vi.fn(),
+  cancel: vi.fn(),
+  commit: vi.fn(() => Promise.resolve('committed' as const)),
+  dispose: vi.fn(),
+  getSnapshot: vi.fn(() => ({ layerId: layer.id, status: 'ready' }) as never),
+  interruptProcessing: vi.fn(),
+  process: vi.fn(() => Promise.resolve('published' as const)),
+  reset: vi.fn(),
+  setAutoProcess: vi.fn(),
+  subscribe: vi.fn(() => () => undefined),
+  updateDraft: vi.fn(),
+});
+
+const createHarness = () => {
+  const session = createSession();
+  const stores = createCanvasOperationStores();
+  const deps = {
+    captureGuard: vi.fn(() => ({ layer, layerId: layer.id }) as never),
+    clearOtherOperation: vi.fn(),
+    clearPreview: vi.fn(),
+    controller: {
+      getSnapshot: vi.fn(() => ({ status: 'idle' })),
+      subscribe: vi.fn(() => () => undefined),
+    },
+    createSession: vi.fn(() => session),
+    getDocument: vi.fn<() => any>(() => ({ layers: [layer], selectedLayerId: null })),
+    getInitialDraft: vi.fn(() => ({ settings: {}, type: 'canny' })),
+    getSessionDeps: vi.fn(() => ({})),
+    isInteractionLocked: vi.fn(() => false),
+    selectLayer: vi.fn(),
+    setViewTool: vi.fn(),
+    stores,
+  };
+  return { coordinator: createFilterOperationCoordinator(deps as never), deps, session, stores };
+};
+
+describe('FilterOperationCoordinator', () => {
+  it('owns session start, publication, and cancellation', () => {
+    const { coordinator, deps, session, stores } = createHarness();
+
+    expect(coordinator.start(layer.id)).toBe('started');
+    expect(deps.clearOtherOperation).toHaveBeenCalledOnce();
+    expect(deps.selectLayer).toHaveBeenCalledWith(layer.id);
+    expect(deps.setViewTool).toHaveBeenCalledOnce();
+    expect(stores.filterSession.get()).toEqual({ layerId: layer.id, status: 'ready' });
+
+    coordinator.cancel();
+    expect(session.dispose).toHaveBeenCalledOnce();
+    expect(stores.filterSession.get()).toBeNull();
+  });
+
+  it('delegates mutation, process, and commit to the owned session', async () => {
+    const { coordinator, session } = createHarness();
+    coordinator.start(layer.id);
+
+    expect(coordinator.updateDraft({ settings: { strength: 1 }, type: 'canny' })).toBe('updated');
+    expect(coordinator.setAutoProcess(true)).toBe('updated');
+    expect(await coordinator.process()).toBe('completed');
+    expect(await coordinator.commit('apply', vi.fn())).toBe('committed');
+
+    expect(session.updateDraft).toHaveBeenCalledOnce();
+    expect(session.setAutoProcess).toHaveBeenCalledWith(true);
+    expect(session.process).toHaveBeenCalledOnce();
+    expect(session.commit).toHaveBeenCalledWith('apply');
+  });
+
+  it('rejects missing, unsupported, disabled, locked, and busy starts deterministically', () => {
+    const { coordinator, deps } = createHarness();
+    deps.getDocument.mockReturnValueOnce(null);
+    expect(coordinator.start(layer.id)).toBe('missing');
+    deps.getDocument.mockReturnValueOnce({ layers: [{ ...layer, type: 'inpaint_mask' }], selectedLayerId: null });
+    expect(coordinator.start(layer.id)).toBe('unsupported');
+    deps.getDocument.mockReturnValueOnce({ layers: [{ ...layer, isEnabled: false }], selectedLayerId: null });
+    expect(coordinator.start(layer.id)).toBe('disabled');
+    deps.getDocument.mockReturnValueOnce({ layers: [{ ...layer, isLocked: true }], selectedLayerId: null });
+    expect(coordinator.start(layer.id)).toBe('locked');
+    deps.isInteractionLocked.mockReturnValueOnce(true);
+    expect(coordinator.start(layer.id)).toBe('locked');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/FilterOperationCoordinator.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/FilterOperationCoordinator.ts
new file mode 100644
index 00000000000..c0a7ca9e5f8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/FilterOperationCoordinator.ts
@@ -0,0 +1,238 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type {
+  CanvasOperationActionResult,
+  CanvasOperationMutationResult,
+  FilterCommitOperationResult,
+  StartFilterOperationResult,
+} from '@workbench/canvas-operations/api';
+import type {
+  CanvasApplicationOperationStores,
+  CanvasOperationController,
+  CanvasOperationRunResult,
+  CreateFilterSessionOptions,
+  FilterOperationSession,
+} from '@workbench/canvas-operations/contracts';
+import type { FilterCommitTarget, LayerFilterSettings } from '@workbench/canvas-operations/operationTypes';
+import type { BackendGraphContract, CanvasDocumentContractV2 } from '@workbench/types';
+
+import {
+  buildFilterDefaults,
+  DEFAULT_CONTROL_FILTER_TYPE,
+  getFilterDefinition,
+  isFilterConfigValid,
+} from '@workbench/generation/canvas/filterGraphs';
+
+import { createFilterOperationSession } from './filterOperationSession';
+import { runLayerFilter } from './layerFilterRunner';
+
+export interface FilterOperationCoordinatorDeps {
+  readonly stores: CanvasApplicationOperationStores;
+  readonly controller: CanvasOperationController;
+  isInteractionLocked(): boolean;
+  getDocument(): CanvasDocumentContractV2 | null;
+  captureGuard(layerId: string): LayerExportGuard | null;
+  selectLayer(layerId: string): void;
+  clearOtherOperation(): void;
+  clearPreview(layerId: string): void;
+  setViewTool(): void;
+  encodeSurface(surface: RasterSurface): Promise<Blob>;
+  runFilterGraph(options: {
+    graph: BackendGraphContract;
+    outputNodeId?: string;
+    signal?: AbortSignal;
+  }): Promise<{ height: number; imageName: string; width: number }>;
+  uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ imageName: string }>;
+  createSession?(options: CreateFilterSessionOptions): FilterOperationSession | null;
+  getSessionDeps(
+    layerId: string
+  ): Omit<
+    CreateFilterSessionOptions['deps'],
+    'canCommit' | 'clearPreview' | 'controller' | 'isDraftValid' | 'makeDurable' | 'runFilter'
+  >;
+}
+
+export interface FilterOperationCoordinator {
+  start(layerId: string, recommendedFilterType?: string | null): StartFilterOperationResult;
+  updateDraft(draft: LayerFilterSettings): CanvasOperationMutationResult;
+  setAutoProcess(value: boolean): CanvasOperationMutationResult;
+  process(): Promise<CanvasOperationActionResult>;
+  reset(settings: Record<string, unknown>): CanvasOperationMutationResult;
+  commit(
+    target: FilterCommitTarget,
+    makeImageDurable: (imageName: string) => Promise<void>
+  ): Promise<FilterCommitOperationResult>;
+  cancel(): void;
+  interruptAndBlock(): void;
+  isActive(): boolean;
+  dispose(): void;
+}
+
+export const createFilterOperationCoordinator = (deps: FilterOperationCoordinatorDeps): FilterOperationCoordinator => {
+  let session: FilterOperationSession | null = null;
+  let unsubscribeSession: (() => void) | null = null;
+  let unsubscribeController: (() => void) | null = null;
+  let makeDurable: (imageName: string) => Promise<void> = () =>
+    Promise.reject(new Error('The filter result cannot be preserved.'));
+
+  const syncStore = (): void => deps.stores.filterSession.set(session?.getSnapshot() ?? null);
+  const clear = (): void => {
+    const owned = session;
+    session = null;
+    unsubscribeSession?.();
+    unsubscribeSession = null;
+    unsubscribeController?.();
+    unsubscribeController = null;
+    owned?.dispose();
+    deps.stores.filterSession.set(null);
+  };
+
+  const start = (layerId: string, recommendedFilterType?: string | null): StartFilterOperationResult => {
+    if (deps.isInteractionLocked()) {
+      return 'locked';
+    }
+    if (recommendedFilterType && deps.controller.getSnapshot().status !== 'idle') {
+      return 'not-ready';
+    }
+    const document = deps.getDocument();
+    const layer = document?.layers.find((candidate) => candidate.id === layerId);
+    if (!document || !layer) {
+      return 'missing';
+    }
+    if (layer.type !== 'raster' && layer.type !== 'control') {
+      return 'unsupported';
+    }
+    if (recommendedFilterType && layer.filter) {
+      return 'not-ready';
+    }
+    if (!layer.isEnabled) {
+      return 'disabled';
+    }
+    if (layer.isLocked) {
+      return 'locked';
+    }
+    const guard = deps.captureGuard(layer.id);
+    if (!guard) {
+      return 'not-ready';
+    }
+    const initialType = layer.filter?.type ?? recommendedFilterType ?? DEFAULT_CONTROL_FILTER_TYPE;
+    const initialFilter = layer.filter ? structuredClone(layer.filter) : null;
+    const definition = getFilterDefinition(initialType);
+    const draft = initialFilter ?? {
+      settings: definition ? buildFilterDefaults(definition) : {},
+      type: definition?.type ?? DEFAULT_CONTROL_FILTER_TYPE,
+    };
+
+    deps.clearOtherOperation();
+    clear();
+    if (document.selectedLayerId !== layer.id) {
+      deps.selectLayer(layer.id);
+    }
+    const createSession = deps.createSession ?? createFilterOperationSession;
+    session = createSession({
+      deps: {
+        ...deps.getSessionDeps(layer.id),
+        canCommit: () => !deps.isInteractionLocked(),
+        clearPreview: () => deps.clearPreview(layer.id),
+        controller: deps.controller,
+        isDraftValid: (next) => isFilterConfigValid(next.type, next.settings),
+        makeDurable: (imageName) => makeDurable(imageName),
+        runFilter: (options) =>
+          runLayerFilter({
+            ...options,
+            deps: {
+              encodeSurface: deps.encodeSurface,
+              runFilterGraph: deps.runFilterGraph,
+              uploadIntermediate: deps.uploadIntermediate,
+            },
+          }),
+      },
+      guard,
+      initialDraft: draft,
+      initialFilter,
+      layerName: layer.name,
+      layerType: layer.type,
+    });
+    if (!session) {
+      return 'not-ready';
+    }
+    const installed = session;
+    unsubscribeSession = installed.subscribe(syncStore);
+    unsubscribeController = deps.controller.subscribe(() => {
+      if (session === installed && deps.controller.getSnapshot().status === 'idle') {
+        clear();
+      }
+    });
+    syncStore();
+    deps.setViewTool();
+    return 'started';
+  };
+
+  return {
+    cancel: clear,
+    commit: async (target, makeImageDurable) => {
+      if (deps.isInteractionLocked()) {
+        return 'blocked';
+      }
+      const owned = session;
+      if (!owned) {
+        return 'stale';
+      }
+      makeDurable = makeImageDurable;
+      const result = await owned.commit(target);
+      if (result === 'committed' && session === owned) {
+        clear();
+      }
+      return result;
+    },
+    dispose: clear,
+    interruptAndBlock: () => {
+      session?.interruptProcessing();
+      session?.blockCommit();
+    },
+    isActive: () => session !== null,
+    process: async () => {
+      if (deps.isInteractionLocked()) {
+        return 'blocked';
+      }
+      if (!session) {
+        return 'stale';
+      }
+      const result: CanvasOperationRunResult = await session.process();
+      return result === 'published' ? 'completed' : 'stale';
+    },
+    reset: (settings) => {
+      if (deps.isInteractionLocked()) {
+        return 'blocked';
+      }
+      if (!session) {
+        return 'stale';
+      }
+      session.reset(settings);
+      return 'updated';
+    },
+    setAutoProcess: (value) => {
+      if (deps.isInteractionLocked()) {
+        return 'blocked';
+      }
+      if (!session) {
+        return 'stale';
+      }
+      session.setAutoProcess(value);
+      return 'updated';
+    },
+    start,
+    updateDraft: (draft) => {
+      if (deps.isInteractionLocked()) {
+        return 'blocked';
+      }
+      if (!session) {
+        return 'stale';
+      }
+      session.updateDraft(draft);
+      return 'updated';
+    },
+  };
+};
+
+export type { FilterOperationSessionState } from '@workbench/canvas-operations/operationTypes';
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/SelectObjectCoordinator.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/SelectObjectCoordinator.ts
new file mode 100644
index 00000000000..fa8c23587d3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/SelectObjectCoordinator.ts
@@ -0,0 +1,437 @@
+import type { CommitGeneratedImageResult } from '@workbench/canvas-engine/api';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { SaveSelectObjectSessionResult, SelectObjectSaveTarget } from '@workbench/canvas-operations/api';
+import type {
+  CanvasSelectObjectCoordinatorDeps,
+  CanvasSelectObjectOperationCoordinator,
+  SelectObjectSession,
+  SelectObjectSessionPreview,
+} from '@workbench/canvas-operations/contracts';
+
+import { createSelectObjectSession } from './selectObjectSession';
+
+interface CommitOwner {
+  controller: AbortController;
+  inputHash: string;
+  preview: SelectObjectSessionPreview<RasterSurface>;
+  previewId: number;
+  session: SelectObjectSession<RasterSurface>;
+  token: number;
+}
+
+export const createSelectObjectOperationCoordinator = (
+  deps: CanvasSelectObjectCoordinatorDeps
+): CanvasSelectObjectOperationCoordinator => {
+  let session: SelectObjectSession<RasterSurface> | null = null;
+  let unsubscribe: (() => void) | null = null;
+  let controllerUnsubscribe: (() => void) | null = null;
+  let startContext: Extract<ReturnType<typeof deps.prepareStart>, { status: 'ready' }> | null = null;
+  let publishedGuard: SelectObjectSessionPreview<RasterSurface>['guard'] | null = null;
+  let pointLabel: 'include' | 'exclude' = 'include';
+  let commitOwner: CommitOwner | null = null;
+  let commitToken = 0;
+
+  const syncStore = (): void => {
+    if (!session || !startContext) {
+      deps.stores.samSession.set(null);
+      return;
+    }
+    const state = session.getSnapshot();
+    deps.stores.samSession.set({
+      applyPolygonRefinement: state.applyPolygonRefinement,
+      autoProcess: state.autoProcess,
+      error: state.error,
+      hasPreview: state.preview !== null,
+      layerName: startContext.layerName,
+      layerType: startContext.layerType,
+      input:
+        state.input.type === 'visual'
+          ? {
+              bbox: state.input.bbox ? { ...state.input.bbox } : null,
+              excludePoints: state.input.excludePoints.map((point) => ({ ...point })),
+              includePoints: state.input.includePoints.map((point) => ({ ...point })),
+              type: 'visual',
+            }
+          : { prompt: state.input.prompt, type: 'prompt' },
+      invert: state.invert,
+      isolatedPreview: state.isolatedPreview,
+      model: state.model,
+      pointLabel,
+      sourceRect: startContext.sourceRect,
+      status: commitOwner?.session === session ? 'committing' : state.status,
+    });
+    deps.invalidateOverlay();
+  };
+
+  const revokeCommit = (): void => {
+    commitToken += 1;
+    const owner = commitOwner;
+    commitOwner = null;
+    owner?.controller.abort();
+  };
+
+  const invalidateCommit = (): void => {
+    revokeCommit();
+    syncStore();
+  };
+
+  const isOwnerCurrent = (owner: CommitOwner): boolean => {
+    const state = owner.session.getSnapshot();
+    return (
+      commitOwner === owner &&
+      commitToken === owner.token &&
+      session === owner.session &&
+      publishedGuard === owner.preview.guard &&
+      state.preview?.previewId === owner.previewId &&
+      state.preview.inputHash === owner.inputHash &&
+      deps.isGuardCurrent(owner.preview.guard) &&
+      !owner.controller.signal.aborted
+    );
+  };
+
+  const beginCommit = (
+    currentSession: SelectObjectSession<RasterSurface>,
+    preview: SelectObjectSessionPreview<RasterSurface>
+  ): CommitOwner | null => {
+    if (commitOwner) {
+      return null;
+    }
+    const owner: CommitOwner = {
+      controller: new AbortController(),
+      inputHash: preview.inputHash,
+      preview,
+      previewId: preview.previewId,
+      session: currentSession,
+      token: ++commitToken,
+    };
+    commitOwner = owner;
+    syncStore();
+    return owner;
+  };
+
+  const finishCommit = (owner: CommitOwner): boolean => {
+    if (!isOwnerCurrent(owner)) {
+      return false;
+    }
+    commitOwner = null;
+    syncStore();
+    return true;
+  };
+
+  const clear = (expectedOwner?: CommitOwner): boolean => {
+    if (expectedOwner && (!isOwnerCurrent(expectedOwner) || session !== expectedOwner.session)) {
+      return false;
+    }
+    deps.replaceTemporaryRestoreTool();
+    const previous = session;
+    session = null;
+    unsubscribe?.();
+    unsubscribe = null;
+    controllerUnsubscribe?.();
+    controllerUnsubscribe = null;
+    startContext = null;
+    publishedGuard = null;
+    pointLabel = 'include';
+    revokeCommit();
+    deps.clearPreview();
+    deps.controller.cancel();
+    previous?.dispose();
+    deps.stores.samSession.set(null);
+    deps.invalidateOverlay();
+    return true;
+  };
+
+  const currentPreview = (): SelectObjectSessionPreview<RasterSurface> | null => {
+    const state = session?.getSnapshot();
+    const preview = state?.preview;
+    if (
+      !state ||
+      (state.status !== 'ready' && state.status !== 'error') ||
+      !preview ||
+      preview.guard !== publishedGuard
+    ) {
+      return null;
+    }
+    return deps.isGuardCurrent(preview.guard) ? preview : null;
+  };
+
+  const reportResultError = (owner: CommitOwner, result: SaveSelectObjectSessionResult): void => {
+    if (!finishCommit(owner)) {
+      return;
+    }
+    owner.session.reportError(
+      result.status === 'locked'
+        ? { code: 'locked' }
+        : {
+            code: 'unknown',
+            detail: result.status === 'failed' ? result.message : `Select Object commit is ${result.status}.`,
+          }
+    );
+  };
+
+  const makeDurable = async (
+    owner: CommitOwner,
+    callback: (imageName: string) => Promise<void>
+  ): Promise<{ status: 'ok' } | { status: 'failed'; message: string }> => {
+    try {
+      await callback(owner.preview.image.imageName);
+      return { status: 'ok' };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (finishCommit(owner)) {
+        owner.session.reportError({ code: 'unknown', detail: message });
+      }
+      return { message, status: 'failed' };
+    }
+  };
+
+  return {
+    start: (layerId) => {
+      if (deps.isInteractionLocked()) {
+        return 'locked';
+      }
+      const prepared = deps.prepareStart(layerId);
+      if (prepared.status !== 'ready') {
+        return prepared.status;
+      }
+      deps.clearOtherOperation();
+      clear();
+      startContext = prepared;
+      deps.selectLayer(layerId);
+      const operation = deps.controller.start({
+        cleanupPreview: deps.clearPreview,
+        guard: prepared.guard,
+        identity: { kind: 'select-object', layerId, projectId: deps.projectId },
+      });
+      if (!operation) {
+        startContext = null;
+        return 'not-ready';
+      }
+      const createSession = deps.createSession ?? createSelectObjectSession;
+      session = createSession({
+        deps: {
+          captureGuard: () => deps.captureGuard(layerId),
+          cleanupPreview: deps.clearPreview,
+          controller: deps.controller,
+          decodePreview: deps.decodePreview,
+          exportSource: () => deps.exportSource(layerId),
+          isGuardCurrent: deps.isGuardCurrent,
+          publishPreview: (preview) => {
+            publishedGuard = preview.guard;
+            deps.publishPreview(preview);
+            return undefined;
+          },
+          runGraph: deps.runGraph,
+          uploadIntermediate: deps.uploadIntermediate,
+        },
+        operation,
+      });
+      const installed = session;
+      unsubscribe = installed.subscribe(() => {
+        if (
+          commitOwner?.session === installed &&
+          installed.getSnapshot().preview?.previewId !== commitOwner.previewId
+        ) {
+          invalidateCommit();
+        }
+        syncStore();
+      });
+      controllerUnsubscribe = deps.controller.subscribe(() => {
+        if (session === installed && deps.controller.getSnapshot().status === 'idle') {
+          clear();
+          if (deps.isSamToolActive()) {
+            deps.setViewTool();
+          }
+        }
+      });
+      installed.update({ input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' } });
+      syncStore();
+      deps.setSamTool();
+      return 'started';
+    },
+    update: (changes) => {
+      if (deps.isInteractionLocked()) {
+        return 'blocked';
+      }
+      if (!session) {
+        return 'stale';
+      }
+      const { pointLabel: nextPointLabel, ...sessionChanges } = changes;
+      const state = session.getSnapshot();
+      const processingChanged =
+        ('input' in sessionChanges && sessionChanges.input !== state.input) ||
+        ('model' in sessionChanges && sessionChanges.model !== state.model) ||
+        ('invert' in sessionChanges && sessionChanges.invert !== state.invert) ||
+        ('applyPolygonRefinement' in sessionChanges &&
+          sessionChanges.applyPolygonRefinement !== state.applyPolygonRefinement);
+      if (processingChanged) {
+        invalidateCommit();
+      }
+      if (nextPointLabel) {
+        pointLabel = nextPointLabel;
+      }
+      session.update(sessionChanges);
+      syncStore();
+      return 'updated';
+    },
+    process: () => {
+      if (deps.isInteractionLocked()) {
+        return Promise.resolve('blocked');
+      }
+      invalidateCommit();
+      return session?.process() ?? Promise.resolve('stale');
+    },
+    apply: async (durable): Promise<CommitGeneratedImageResult> => {
+      if (deps.isInteractionLocked()) {
+        return { status: 'locked' };
+      }
+      const currentSession = session;
+      const preview = currentPreview();
+      if (!currentSession || !preview) {
+        return { status: 'stale' };
+      }
+      const owner = beginCommit(currentSession, preview);
+      if (!owner) {
+        return { status: 'busy' };
+      }
+      if (!isOwnerCurrent(owner)) {
+        invalidateCommit();
+        return { status: 'stale' };
+      }
+      const durability = await makeDurable(owner, durable);
+      if (durability.status === 'failed') {
+        return durability;
+      }
+      if (!isOwnerCurrent(owner)) {
+        return deps.isInteractionLocked() ? { status: 'locked' } : { status: 'stale' };
+      }
+      if (deps.isInteractionLocked()) {
+        invalidateCommit();
+        return { status: 'locked' };
+      }
+      let result: CommitGeneratedImageResult;
+      try {
+        result = await deps.commitGenerated(preview, { mode: 'replace', signal: owner.controller.signal });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (finishCommit(owner)) {
+          owner.session.reportError({ code: 'unknown', detail: message });
+        }
+        return { message, status: 'failed' };
+      }
+      if (!isOwnerCurrent(owner)) {
+        return result;
+      }
+      if (result.status === 'committed') {
+        clear(owner);
+        if (deps.isSamToolActive()) {
+          deps.setViewTool();
+        }
+      } else {
+        reportResultError(owner, result);
+      }
+      return result;
+    },
+    save: async (target: SelectObjectSaveTarget, durable): Promise<SaveSelectObjectSessionResult> => {
+      if (deps.isInteractionLocked()) {
+        return { status: 'locked' };
+      }
+      const currentSession = session;
+      const preview = currentPreview();
+      if (!currentSession || !preview) {
+        return { status: 'stale' };
+      }
+      const owner = beginCommit(currentSession, preview);
+      if (!owner) {
+        return { status: 'busy' };
+      }
+      if (target === 'selection') {
+        const result = await deps.replaceSelection(preview, owner.controller.signal);
+        if (!isOwnerCurrent(owner)) {
+          return result;
+        }
+        if (result.status === 'selected') {
+          clear(owner);
+          if (deps.isSamToolActive()) {
+            deps.setViewTool();
+          }
+        } else {
+          reportResultError(owner, result);
+        }
+        return result;
+      }
+      const durability = await makeDurable(owner, durable);
+      if (durability.status === 'failed') {
+        return durability;
+      }
+      if (!isOwnerCurrent(owner)) {
+        return deps.isInteractionLocked() ? { status: 'locked' } : { status: 'stale' };
+      }
+      if (deps.isInteractionLocked()) {
+        invalidateCommit();
+        return { status: 'locked' };
+      }
+      let result: SaveSelectObjectSessionResult;
+      try {
+        result =
+          target === 'raster' || target === 'control'
+            ? await deps.commitGenerated(preview, {
+                mode: target === 'raster' ? 'copy-raster' : 'copy-control',
+                signal: owner.controller.signal,
+              })
+            : await deps.commitMask(preview, target, owner.controller.signal);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (finishCommit(owner)) {
+          owner.session.reportError({ code: 'unknown', detail: message });
+        }
+        return { message, status: 'failed' };
+      }
+      if (!isOwnerCurrent(owner)) {
+        return result;
+      }
+      if (result.status === 'committed') {
+        finishCommit(owner);
+      } else {
+        reportResultError(owner, result);
+      }
+      return result;
+    },
+    reset: () => {
+      if (deps.isInteractionLocked()) {
+        return 'blocked';
+      }
+      const operation = deps.controller.getSnapshot();
+      if (
+        !session ||
+        !startContext ||
+        !deps.isGuardCurrent(startContext.guard) ||
+        operation.status !== 'active' ||
+        operation.identity.kind !== 'select-object' ||
+        operation.identity.projectId !== deps.projectId ||
+        operation.identity.layerId !== startContext.layerId
+      ) {
+        return 'stale';
+      }
+      invalidateCommit();
+      publishedGuard = null;
+      pointLabel = 'include';
+      session.reset();
+      session.update({ input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' } });
+      syncStore();
+      return 'updated';
+    },
+    cancel: () => {
+      clear();
+      if (deps.isSamToolActive()) {
+        deps.setViewTool();
+      }
+    },
+    interruptAndBlock: () => {
+      invalidateCommit();
+      session?.interruptProcessing();
+    },
+    isActive: () => session !== null,
+    dispose: () => clear(),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/api.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/api.ts
new file mode 100644
index 00000000000..44bbb4210d7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/api.ts
@@ -0,0 +1,77 @@
+import type { CommitGeneratedImageResult, ReplaceSelectionFromImageResult } from '@workbench/canvas-engine/api';
+import type { CommitRasterFilterResult } from '@workbench/canvas-engine/controllers/filterResultController';
+import type {
+  CommitMaskImageResult,
+  MaskImageResultTarget,
+} from '@workbench/canvas-engine/controllers/maskResultController';
+import type {
+  CanvasApplicationOperationStores,
+  CanvasOperationController,
+  SelectObjectSessionProcessResult,
+} from '@workbench/canvas-operations/contracts';
+import type {
+  FilterCommitTarget,
+  LayerFilterSettings,
+  SamInput,
+  SamModel,
+  SamPointLabel,
+} from '@workbench/canvas-operations/operationTypes';
+
+export type StartSelectObjectSessionResult =
+  | 'started'
+  | 'missing'
+  | 'disabled'
+  | 'locked'
+  | 'unsupported'
+  | 'not-ready';
+export type StartFilterOperationResult = 'started' | 'missing' | 'disabled' | 'locked' | 'unsupported' | 'not-ready';
+export type CanvasOperationActionResult = 'completed' | 'blocked' | 'stale';
+export type FilterCommitOperationResult = 'committed' | 'blocked' | 'stale';
+export type CanvasOperationMutationResult = 'updated' | 'blocked' | 'stale';
+export type SelectObjectSaveTarget = 'selection' | 'raster' | 'control' | MaskImageResultTarget;
+export type SaveSelectObjectSessionResult =
+  | CommitGeneratedImageResult
+  | CommitMaskImageResult
+  | ReplaceSelectionFromImageResult;
+
+export interface SelectObjectSessionUpdate {
+  input?: SamInput;
+  pointLabel?: SamPointLabel;
+  model?: SamModel;
+  invert?: boolean;
+  applyPolygonRefinement?: boolean;
+  autoProcess?: boolean;
+  isolatedPreview?: boolean;
+}
+
+export interface CanvasOperationCapability {
+  readonly controller: CanvasOperationController;
+  readonly stores: CanvasApplicationOperationStores;
+  startSelectObject(layerId: string): StartSelectObjectSessionResult;
+  startFilterOperation(layerId: string, recommendedFilterType?: string | null): StartFilterOperationResult;
+  updateFilterOperation(draft: LayerFilterSettings): CanvasOperationMutationResult;
+  setFilterOperationAutoProcess(value: boolean): CanvasOperationMutationResult;
+  processFilterOperation(): Promise<CanvasOperationActionResult>;
+  resetFilterOperation(settings: Record<string, unknown>): CanvasOperationMutationResult;
+  commitFilterOperation(
+    target: FilterCommitTarget,
+    makeImageDurable: (imageName: string) => Promise<void>
+  ): Promise<FilterCommitOperationResult>;
+  cancelFilterOperation(): void;
+  updateSelectObjectSession(changes: SelectObjectSessionUpdate): CanvasOperationMutationResult;
+  processSelectObjectSession(): Promise<SelectObjectSessionProcessResult>;
+  applySelectObjectSession(makeImageDurable: (imageName: string) => Promise<void>): Promise<CommitGeneratedImageResult>;
+  saveSelectObjectSession(
+    target: SelectObjectSaveTarget,
+    makeImageDurable: (imageName: string) => Promise<void>
+  ): Promise<SaveSelectObjectSessionResult>;
+  resetSelectObjectSession(): CanvasOperationMutationResult;
+  cancelSelectObjectSession(): void;
+}
+
+export type { CommitRasterFilterResult };
+export {
+  importGalleryImagesToCanvas,
+  type GalleryCanvasImportDestination,
+  type ImportGalleryImagesResult,
+} from './importGalleryImages';
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/applicationPort.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/applicationPort.ts
new file mode 100644
index 00000000000..35936f41235
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/applicationPort.ts
@@ -0,0 +1,26 @@
+import type { CanvasApplicationPort } from '@workbench/canvas-operations/contracts';
+
+import { socketHub } from '@workbench/backend/socketHub';
+import { uploadCanvasImage } from '@workbench/canvas-operations/backend/canvasImages';
+import { runUtilityGraph } from '@workbench/canvas-operations/backend/utilityQueue';
+import {
+  createFilterOperationCoordinator,
+  type FilterOperationCoordinatorDeps,
+} from '@workbench/canvas-operations/FilterOperationCoordinator';
+import { createCanvasOperationController } from '@workbench/canvas-operations/operationController';
+import { createCanvasOperationStores } from '@workbench/canvas-operations/operationStores';
+import { createSelectObjectOperationCoordinator } from '@workbench/canvas-operations/SelectObjectCoordinator';
+import { getSelectedModelBase } from '@workbench/widgets/layers/selectedModel';
+
+export const canvasApplicationPort: CanvasApplicationPort = {
+  createFilterCoordinator: (deps) => createFilterOperationCoordinator(deps as FilterOperationCoordinatorDeps),
+  createOperationController: (deps) => createCanvasOperationController(deps),
+  createOperationStores: createCanvasOperationStores,
+  createSelectObjectCoordinator: createSelectObjectOperationCoordinator,
+  getSelectedModelBase: (state, projectId) => {
+    const project = state.projects.find((candidate) => candidate.id === projectId);
+    return project ? getSelectedModelBase(project) : null;
+  },
+  runGraph: (options) => runUtilityGraph({ ...options, hub: socketHub }),
+  uploadImage: (blob, options) => uploadCanvasImage(blob, options),
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/canvasImages.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/canvasImages.test.ts
new file mode 100644
index 00000000000..e9c0ad8158d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/canvasImages.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { CanvasImageUploadError, uploadCanvasImage } from './canvasImages';
+
+/** A minimal `Response`-shaped fake for the injected fetch. */
+const jsonResponse = (body: unknown, init: { ok?: boolean; status?: number; statusText?: string } = {}): Response =>
+  ({
+    json: () => Promise.resolve(body),
+    ok: init.ok ?? true,
+    status: init.status ?? 200,
+    statusText: init.statusText ?? 'OK',
+    text: () => Promise.resolve(typeof body === 'string' ? body : JSON.stringify(body)),
+  }) as unknown as Response;
+
+describe('uploadCanvasImage', () => {
+  it('forwards an abort signal to fetch', async () => {
+    const controller = new AbortController();
+    const fetchImpl = vi.fn(() =>
+      Promise.resolve(jsonResponse({ height: 1, image_name: 'uploaded.png', width: 1 }))
+    ) as unknown as typeof fetch;
+
+    await uploadCanvasImage(new Blob(['pixels'], { type: 'image/png' }), {
+      fetch: fetchImpl,
+      signal: controller.signal,
+    });
+
+    expect(fetchImpl).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ signal: controller.signal }));
+  });
+
+  it('POSTs a multipart file to the upload endpoint with the persistence params', async () => {
+    const fetchImpl = vi.fn(() =>
+      Promise.resolve(jsonResponse({ height: 64, image_name: 'paint-1.png', width: 128 }, { status: 201 }))
+    );
+    const blob = new Blob(['png-bytes'], { type: 'image/png' });
+
+    const result = await uploadCanvasImage(blob, { fetch: fetchImpl });
+
+    expect(result).toEqual({ height: 64, imageName: 'paint-1.png', width: 128 });
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+
+    const [url, init] = fetchImpl.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toContain('/api/v1/images/upload');
+    expect(url).toContain('image_category=other');
+    expect(url).toContain('is_intermediate=false');
+    expect(init.method).toBe('POST');
+    expect(init.body).toBeInstanceOf(FormData);
+    const file = (init.body as FormData).get('file');
+    expect(file).toBeInstanceOf(File);
+    expect((file as File).type).toBe('image/png');
+  });
+
+  it('honors overrides for category, intermediate flag, board, metadata, and resize dimensions', async () => {
+    const fetchImpl = vi.fn(() =>
+      Promise.resolve(jsonResponse({ height: 1, image_name: 'x', width: 1 }, { status: 201 }))
+    );
+
+    await uploadCanvasImage(new Blob([''], { type: 'image/png' }), {
+      boardId: 'board-9',
+      fetch: fetchImpl,
+      imageCategory: 'user',
+      isIntermediate: true,
+      metadata: { seed: 42 },
+      resizeTo: { width: 1024, height: 768 },
+    });
+
+    const [url, init] = fetchImpl.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toContain('image_category=user');
+    expect(url).toContain('is_intermediate=true');
+    expect(url).toContain('board_id=board-9');
+    const formData = init.body as FormData;
+    expect(formData.get('metadata')).toBe(JSON.stringify({ seed: 42 }));
+    expect(formData.get('resize_to')).toBe(JSON.stringify({ width: 1024, height: 768 }));
+  });
+
+  it('throws a typed error with the status on a non-ok response', async () => {
+    const fetchImpl = vi.fn(() =>
+      Promise.resolve(jsonResponse('Not an image', { ok: false, status: 415, statusText: 'Unsupported Media Type' }))
+    );
+
+    await expect(uploadCanvasImage(new Blob([''], { type: 'image/png' }), { fetch: fetchImpl })).rejects.toMatchObject({
+      name: 'CanvasImageUploadError',
+      status: 415,
+    });
+  });
+
+  it('wraps a network failure in a CanvasImageUploadError', async () => {
+    const fetchImpl = vi.fn(() => Promise.reject(new Error('network down')));
+
+    const error = await uploadCanvasImage(new Blob([''], { type: 'image/png' }), { fetch: fetchImpl }).catch(
+      (caught: unknown) => caught
+    );
+
+    expect(error).toBeInstanceOf(CanvasImageUploadError);
+    expect((error as CanvasImageUploadError).status).toBeNull();
+    expect((error as CanvasImageUploadError).message).toContain('network down');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/canvasImages.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/canvasImages.ts
new file mode 100644
index 00000000000..a2ae692bdeb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/canvasImages.ts
@@ -0,0 +1,124 @@
+/**
+ * Uploads canvas paint bitmaps to the backend as persistent, non-gallery
+ * images. Paint layers reference their pixels by `imageName` (never by URL or
+ * inline data), so the persisted workbench document — which autosaves to
+ * localStorage (~5 MB) — stays ref-only and the pixels live server-side.
+ *
+ * `image_category='other'` + `is_intermediate=false` keeps the bitmap durable
+ * (not garbage-collected as an intermediate) while hiding it from the gallery's
+ * general/asset views.
+ *
+ * The `fetch` seam is injectable so this runs in node tests without a DOM.
+ * Auth + base-URL resolution mirror the shared HTTP client so uploads carry the
+ * same bearer token as every other authenticated request. Zero React.
+ */
+
+import type { CanvasImageUploadResult } from '@workbench/canvas-engine/document/imageUpload';
+
+import { buildApiUrl, getAuthToken } from '@workbench/backend/http';
+
+export type { CanvasImageUploadResult } from '@workbench/canvas-engine/document/imageUpload';
+
+/** The subset of the backend `ImageDTO` this module reads. */
+interface UploadImageResponseDTO {
+  image_name: string;
+  width: number;
+  height: number;
+}
+
+/** Options for {@link uploadCanvasImage}. */
+export interface UploadCanvasImageOptions {
+  /** Overrides the default `'other'` category. */
+  imageCategory?: 'other' | 'general' | 'control' | 'mask' | 'user';
+  /** Overrides the default `false` (persistent, not garbage-collected). */
+  isIntermediate?: boolean;
+  /** Adds the image to a board, if given. */
+  boardId?: string;
+  /** File name sent in the multipart part (defaults to `canvas-paint.png`). */
+  fileName?: string;
+  /** Optional image metadata sent as JSON in the multipart body. */
+  metadata?: Record<string, unknown>;
+  /** Optional backend resize dimensions sent as JSON in the multipart body. */
+  resizeTo?: { width: number; height: number };
+  /** Injectable `fetch` implementation (defaults to the global). */
+  fetch?: typeof globalThis.fetch;
+  /** Cancels the multipart request when its owning operation is superseded. */
+  signal?: AbortSignal;
+}
+
+/** Thrown when a canvas-image upload fails (non-2xx or network error). */
+export class CanvasImageUploadError extends Error {
+  readonly status: number | null;
+
+  constructor(message: string, status: number | null) {
+    super(message);
+    this.name = 'CanvasImageUploadError';
+    this.status = status;
+  }
+}
+
+/**
+ * POSTs `blob` as a PNG to `/api/v1/images/upload` (multipart `file` field) and
+ * returns the server-assigned image name and dimensions. Throws
+ * {@link CanvasImageUploadError} on any non-success response.
+ */
+export const uploadCanvasImage = async (
+  blob: Blob,
+  options: UploadCanvasImageOptions = {}
+): Promise<CanvasImageUploadResult> => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+
+  const query = new URLSearchParams({
+    image_category: options.imageCategory ?? 'other',
+    is_intermediate: String(options.isIntermediate ?? false),
+  });
+  if (options.boardId) {
+    query.set('board_id', options.boardId);
+  }
+
+  const fileName = options.fileName ?? 'canvas-paint.png';
+  const file = new File([blob], fileName, { type: blob.type || 'image/png' });
+  const body = new FormData();
+  body.append('file', file);
+  if (options.metadata) {
+    body.append('metadata', JSON.stringify(options.metadata));
+  }
+  if (options.resizeTo) {
+    body.append('resize_to', JSON.stringify(options.resizeTo));
+  }
+
+  const headers = new Headers();
+  const token = getAuthToken();
+  if (token) {
+    headers.set('Authorization', `Bearer ${token}`);
+  }
+
+  let response: Response;
+  try {
+    response = await fetchImpl(buildApiUrl(`/api/v1/images/upload?${query.toString()}`), {
+      body,
+      headers,
+      method: 'POST',
+      signal: options.signal,
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw error;
+    }
+    throw new CanvasImageUploadError(
+      `Canvas image upload failed: ${error instanceof Error ? error.message : String(error)}`,
+      null
+    );
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => '');
+    throw new CanvasImageUploadError(
+      text || `Canvas image upload failed: ${response.status} ${response.statusText}`,
+      response.status
+    );
+  }
+
+  const dto = (await response.json()) as UploadImageResponseDTO;
+  return { height: dto.height, imageName: dto.image_name, width: dto.width };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/utilityQueue.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/utilityQueue.test.ts
new file mode 100644
index 00000000000..baaaaca7994
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/utilityQueue.test.ts
@@ -0,0 +1,1120 @@
+import type { InvocationCompleteEvent, QueueItemStatusChangedEvent } from '@workbench/backend/events';
+import type { SocketHub } from '@workbench/backend/socketHub';
+
+import {
+  buildQueueItemOrigin,
+  buildUtilityQueueItemOrigin,
+  isUtilityQueueItemOrigin,
+  parseQueueItemOrigin,
+} from '@workbench/backend/events';
+import { ApiError } from '@workbench/backend/http';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { UtilityEnqueue } from './utilityQueue';
+
+import { DEFAULT_UTILITY_QUEUE_TIMEOUT_MS, runUtilityGraph, UtilityQueueError } from './utilityQueue';
+
+/** A fake socket hub that records handlers per event and can emit to them, mirroring `hub.on`. */
+const createFakeHub = () => {
+  const handlers = new Map<string, Set<(payload: unknown) => void>>();
+  let detachCount = 0;
+
+  const hub: Pick<SocketHub, 'on'> = {
+    on: (event, handler) => {
+      const set = handlers.get(event) ?? new Set();
+      set.add(handler as (payload: unknown) => void);
+      handlers.set(event, set);
+      return () => {
+        detachCount += 1;
+        set.delete(handler as (payload: unknown) => void);
+      };
+    },
+  };
+
+  const emit = (event: string, payload: unknown): void => {
+    for (const handler of handlers.get(event) ?? []) {
+      handler(payload);
+    }
+  };
+
+  return {
+    emit,
+    get detachCount() {
+      return detachCount;
+    },
+    handlerCount: (event: string): number => handlers.get(event)?.size ?? 0,
+    hub,
+  };
+};
+
+const UTIL_ID = 'fixed-util-id';
+const ORIGIN = buildUtilityQueueItemOrigin(UTIL_ID);
+
+const completeEvent = (overrides: Partial<InvocationCompleteEvent> = {}): InvocationCompleteEvent => ({
+  batch_id: 'b',
+  destination: null,
+  invocation_source_id: 'control_filter',
+  item_id: 1,
+  origin: ORIGIN,
+  queue_id: 'default',
+  result: { height: 48, image: { image_name: 'filtered.png' }, type: 'image_output', width: 64 },
+  session_id: 's',
+  ...overrides,
+});
+
+const statusEvent = (
+  status: QueueItemStatusChangedEvent['status'],
+  overrides: Partial<QueueItemStatusChangedEvent> = {}
+): QueueItemStatusChangedEvent => ({
+  batch_id: 'b',
+  completed_at: null,
+  created_at: '',
+  destination: null,
+  error_message: null,
+  error_traceback: null,
+  error_type: null,
+  item_id: 1,
+  origin: ORIGIN,
+  queue_id: 'default',
+  session_id: 's',
+  started_at: null,
+  status,
+  updated_at: '',
+  ...overrides,
+});
+
+const okEnqueue: UtilityEnqueue = () => Promise.resolve({ enqueued: 1, itemIds: [1] });
+
+const createDeferred = <T>(): { promise: Promise<T>; resolve: (value: T) => void } => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+const createReconcileScheduler = () => {
+  const pending: Array<{ callback: () => void; canceled: boolean }> = [];
+  const cancelers: ReturnType<typeof vi.fn>[] = [];
+  const schedule = vi.fn((callback: () => void, _delayMs: number) => {
+    const entry = { callback, canceled: false };
+    pending.push(entry);
+    const cancel = vi.fn(() => {
+      entry.canceled = true;
+    });
+    cancelers.push(cancel);
+    return cancel;
+  });
+  return {
+    cancelers,
+    pending,
+    runNext() {
+      const entry = pending.shift();
+      if (!entry) {
+        throw new Error('No reconciliation retry is scheduled.');
+      }
+      if (!entry.canceled) {
+        entry.callback();
+      }
+    },
+    schedule,
+  };
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('runUtilityGraph — await + settle', () => {
+  it('resolves with the captured image name and the isolated origin on completion', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      outputNodeId: 'control_filter',
+    });
+
+    // Listeners are attached before enqueue resolves (fast-finish race closed).
+    expect(fake.handlerCount('invocation_complete')).toBe(1);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(1);
+
+    fake.emit('invocation_complete', completeEvent());
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).resolves.toEqual({ height: 48, imageName: 'filtered.png', origin: ORIGIN, width: 64 });
+    // Both listeners detached on settle.
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+    expect(fake.detachCount).toBe(2);
+  });
+
+  it('ignores completions from other output nodes when outputNodeId is set', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      outputNodeId: 'control_filter',
+    });
+
+    // A different node's completion is ignored; the target node's is captured.
+    fake.emit(
+      'invocation_complete',
+      completeEvent({
+        invocation_source_id: 'other',
+        result: { image: { image_name: 'wrong.png' }, type: 'image_output' },
+      })
+    );
+    fake.emit('invocation_complete', completeEvent());
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+  });
+
+  it('allows delayed socket output to win after a successful null reconciliation', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => Promise.resolve(null),
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+
+    fake.emit('invocation_complete', completeEvent());
+
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+    expect(scheduler.cancelers[0]).toHaveBeenCalledOnce();
+  });
+
+  it('reconciles the target output when completed status arrives before invocation_complete', async () => {
+    const fake = createFakeHub();
+    const reconcileCompletedOutput = vi.fn(() =>
+      Promise.resolve({ height: 48, imageName: 'reconciled.png', width: 64 })
+    );
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      outputNodeId: 'control_filter',
+      reconcileCompletedOutput,
+    });
+
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).resolves.toEqual({
+      height: 48,
+      imageName: 'reconciled.png',
+      origin: ORIGIN,
+      width: 64,
+    });
+    expect(reconcileCompletedOutput).toHaveBeenCalledExactlyOnceWith([1], 'control_filter');
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+  });
+
+  it('resolves when a later reconciliation finds output after an initial successful null', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const reconcileCompletedOutput = vi
+      .fn()
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce({ height: 48, imageName: 'later.png', width: 64 });
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      outputNodeId: 'control_filter',
+      reconcileCompletedOutput,
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+    scheduler.runNext();
+
+    await expect(promise).resolves.toMatchObject({ imageName: 'later.png' });
+    expect(reconcileCompletedOutput).toHaveBeenCalledTimes(2);
+  });
+
+  it('rejects no-output only after exhausting successful null reconciliations', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const reconcileCompletedOutput = vi.fn(() => Promise.resolve(null));
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput,
+      reconcileRetryPolicy: { delayMs: 10, maxAttempts: 3 },
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledTimes(1));
+    scheduler.runNext();
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledTimes(2));
+    scheduler.runNext();
+
+    await expect(promise).rejects.toMatchObject({ reason: 'no-output' });
+    expect(reconcileCompletedOutput).toHaveBeenCalledTimes(3);
+  });
+
+  it('aborts and fully cleans up while completed-output reconciliation is pending', async () => {
+    const fake = createFakeHub();
+    const reconciliation = createDeferred<{ height: number; imageName: string; width: number } | null>();
+    const controller = new AbortController();
+    const cancel = vi.fn(() => Promise.resolve());
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      outputNodeId: 'control_filter',
+      reconcileCompletedOutput: () => reconciliation.promise,
+      signal: controller.signal,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    controller.abort();
+
+    await expect(promise).rejects.toMatchObject({ reason: 'aborted' });
+    await vi.waitFor(() => expect(cancel).toHaveBeenCalledExactlyOnceWith([1]));
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+    reconciliation.resolve({ height: 48, imageName: 'late.png', width: 64 });
+    await Promise.resolve();
+    expect(fake.detachCount).toBe(2);
+  });
+
+  it('allows delayed socket output to win after a transient reconciliation failure', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const reconcileCompletedOutput = vi.fn(() => Promise.reject(new TypeError('gateway unavailable')));
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      outputNodeId: 'control_filter',
+      reconcileCompletedOutput,
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+
+    fake.emit('invocation_complete', completeEvent());
+
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+    expect(reconcileCompletedOutput).toHaveBeenCalledOnce();
+    expect(scheduler.cancelers[0]).toHaveBeenCalledOnce();
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+  });
+
+  it('retries bounded reconciliation failures and resolves from a later successful attempt', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const reconcileCompletedOutput = vi
+      .fn()
+      .mockRejectedValueOnce(new TypeError('first failure'))
+      .mockRejectedValueOnce(new TypeError('second failure'))
+      .mockResolvedValueOnce({ height: 48, imageName: 'reconciled.png', width: 64 });
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      outputNodeId: 'control_filter',
+      reconcileCompletedOutput,
+      reconcileRetryPolicy: { delayMs: 25, maxAttempts: 3 },
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledTimes(1));
+    scheduler.runNext();
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledTimes(2));
+    scheduler.runNext();
+
+    await expect(promise).resolves.toMatchObject({ imageName: 'reconciled.png' });
+    expect(reconcileCompletedOutput).toHaveBeenCalledTimes(3);
+    expect(scheduler.schedule).toHaveBeenNthCalledWith(1, expect.any(Function), 25);
+  });
+
+  it('rejects with reconcile reason and preserves the final failure after bounded attempts are exhausted', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const finalCause = new TypeError('connection failed');
+    const reconcileCompletedOutput = vi
+      .fn()
+      .mockRejectedValueOnce(new TypeError('temporary failure'))
+      .mockRejectedValueOnce(finalCause);
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput,
+      reconcileRetryPolicy: { delayMs: 10, maxAttempts: 2 },
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+    scheduler.runNext();
+
+    await expect(promise).rejects.toMatchObject({
+      cause: finalCause,
+      message: 'Failed to reconcile utility graph output after 2 attempts: connection failed',
+      reason: 'reconcile',
+    });
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+  });
+
+  it('aborts during a scheduled reconciliation retry and cancels the retry timer', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const controller = new AbortController();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => Promise.reject(new TypeError('offline')),
+      scheduleReconcileRetry: scheduler.schedule,
+      signal: controller.signal,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+
+    controller.abort();
+
+    await expect(promise).rejects.toMatchObject({ reason: 'aborted' });
+    expect(scheduler.cancelers[0]).toHaveBeenCalledOnce();
+    scheduler.runNext();
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+  });
+
+  it('cancels a scheduled reconciliation retry when terminal failure wins', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => Promise.reject(new TypeError('offline')),
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+
+    fake.emit('queue_item_status_changed', statusEvent('failed', { error_message: 'backend failed' }));
+
+    await expect(promise).rejects.toMatchObject({ message: 'backend failed', reason: 'failed' });
+    expect(scheduler.cancelers[0]).toHaveBeenCalledOnce();
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+  });
+
+  it('fails an authentication reconciliation error immediately without retrying', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const cause = new ApiError('unauthorized', 401);
+    const reconcileCompletedOutput = vi.fn(() => Promise.reject(cause));
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput,
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'reconcile' });
+    expect(reconcileCompletedOutput).toHaveBeenCalledOnce();
+    expect(scheduler.schedule).not.toHaveBeenCalled();
+  });
+
+  it('retries a transient 503 reconciliation error', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const reconcileCompletedOutput = vi
+      .fn()
+      .mockRejectedValueOnce(new ApiError('unavailable', 503))
+      .mockResolvedValueOnce({ height: 48, imageName: 'recovered.png', width: 64 });
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput,
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+    scheduler.runNext();
+
+    await expect(promise).resolves.toMatchObject({ imageName: 'recovered.png' });
+    expect(reconcileCompletedOutput).toHaveBeenCalledTimes(2);
+  });
+
+  it('fails malformed protocol data immediately without retrying', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const cause = new Error('Queue item 1 returned malformed reconciliation data.');
+    const reconcileCompletedOutput = vi.fn(() => Promise.reject(cause));
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput,
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'reconcile' });
+    expect(reconcileCompletedOutput).toHaveBeenCalledOnce();
+    expect(scheduler.schedule).not.toHaveBeenCalled();
+  });
+
+  it('captures a synchronous reconciler throw triggered after enqueue completion', async () => {
+    const fake = createFakeHub();
+    const enqueue = createDeferred<{ enqueued: number; itemIds: number[] }>();
+    const cause = new Error('sync after enqueue');
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: () => enqueue.promise,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => {
+        throw cause;
+      },
+    });
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    enqueue.resolve({ enqueued: 1, itemIds: [1] });
+
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'reconcile' });
+  });
+
+  it('captures a synchronous reconciler throw triggered from the socket callback', async () => {
+    const fake = createFakeHub();
+    const cause = new Error('sync from socket');
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => {
+        throw cause;
+      },
+    });
+    await Promise.resolve();
+
+    expect(() => fake.emit('queue_item_status_changed', statusEvent('completed'))).not.toThrow();
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'reconcile' });
+  });
+
+  it('captures a synchronous reconciler throw triggered from the retry timer', async () => {
+    const fake = createFakeHub();
+    const scheduler = createReconcileScheduler();
+    const cause = new Error('sync from retry');
+    const reconcileCompletedOutput = vi
+      .fn()
+      .mockRejectedValueOnce(new TypeError('offline'))
+      .mockImplementationOnce(() => {
+        throw cause;
+      });
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput,
+      scheduleReconcileRetry: scheduler.schedule,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduler.schedule).toHaveBeenCalledOnce());
+
+    expect(() => scheduler.runNext()).not.toThrow();
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'reconcile' });
+  });
+
+  it('rejects with the failure reason + message on a failed item', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+    fake.emit('queue_item_status_changed', statusEvent('failed', { error_message: 'boom' }));
+    await expect(promise).rejects.toMatchObject({ message: 'boom', reason: 'failed' });
+  });
+
+  it.each(['', '   '])('uses a trimmed backend error type when the message is %j', async (error_message) => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+
+    fake.emit(
+      'queue_item_status_changed',
+      statusEvent('failed', { error_message, error_traceback: 'giant traceback', error_type: '  AttributeError  ' })
+    );
+
+    await expect(promise).rejects.toMatchObject({ message: 'AttributeError', reason: 'failed' });
+  });
+
+  it('prefers and trims a nonempty backend message over its error type', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+
+    fake.emit(
+      'queue_item_status_changed',
+      statusEvent('failed', { error_message: '  useful detail  ', error_type: 'AttributeError' })
+    );
+
+    await expect(promise).rejects.toMatchObject({ message: 'useful detail', reason: 'failed' });
+  });
+
+  it('uses the generic backend-failed fallback when message and type are missing', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+
+    fake.emit('queue_item_status_changed', statusEvent('failed'));
+
+    await expect(promise).rejects.toMatchObject({ message: 'The utility graph failed.', reason: 'failed' });
+  });
+
+  it('ignores malformed non-string backend failure fields', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+
+    fake.emit(
+      'queue_item_status_changed',
+      statusEvent('failed', { error_message: 42, error_type: { name: 'AttributeError' } } as never)
+    );
+
+    await expect(promise).rejects.toMatchObject({ message: 'The utility graph failed.', reason: 'failed' });
+  });
+
+  it('rejects canceled on a canceled item', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+    fake.emit('queue_item_status_changed', statusEvent('canceled'));
+    await expect(promise).rejects.toMatchObject({ reason: 'canceled' });
+  });
+});
+
+describe('runUtilityGraph — timeout + cancellation', () => {
+  it('rejects with timeout and cancels every accepted backend item', async () => {
+    vi.useFakeTimers();
+    const fake = createFakeHub();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.resolve());
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: () => Promise.resolve({ enqueued: 3, itemIds: [11, 12, 13] }),
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      timeoutMs: 1000,
+    });
+    const assertion = expect(promise).rejects.toMatchObject({ reason: 'timeout' });
+    await vi.advanceTimersByTimeAsync(1000);
+    await assertion;
+    expect(cancel).toHaveBeenCalledExactlyOnceWith([11, 12, 13]);
+    // Listeners cleaned up after timeout.
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+  });
+
+  it('rejects immediately without enqueueing or canceling when the signal is already aborted', async () => {
+    const fake = createFakeHub();
+    const controller = new AbortController();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.resolve());
+    const enqueue = vi.fn(okEnqueue);
+    controller.abort();
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      signal: controller.signal,
+    });
+    await expect(promise).rejects.toMatchObject({ reason: 'aborted' });
+    expect(enqueue).not.toHaveBeenCalled();
+    expect(cancel).not.toHaveBeenCalled();
+  });
+
+  it('rejects aborted, cancels accepted backend items, and detaches listeners', async () => {
+    const fake = createFakeHub();
+    const controller = new AbortController();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.resolve());
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: () => Promise.resolve({ enqueued: 2, itemIds: [21, 22] }),
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      signal: controller.signal,
+    });
+    await Promise.resolve();
+    controller.abort();
+    await expect(promise).rejects.toMatchObject({ reason: 'aborted' });
+    await vi.waitFor(() => expect(cancel).toHaveBeenCalledExactlyOnceWith([21, 22]));
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+  });
+
+  it('rejects promptly, then cancels accepted items when a pending enqueue resolves', async () => {
+    const fake = createFakeHub();
+    const controller = new AbortController();
+    const enqueue = createDeferred<{ enqueued: number; itemIds: number[] }>();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.resolve());
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: () => enqueue.promise,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      signal: controller.signal,
+    });
+    const assertion = expect(promise).rejects.toMatchObject({ reason: 'aborted' });
+
+    controller.abort();
+    await assertion;
+    expect(cancel).not.toHaveBeenCalled();
+
+    enqueue.resolve({ enqueued: 2, itemIds: [31, 32] });
+    await vi.waitFor(() => expect(cancel).toHaveBeenCalledExactlyOnceWith([31, 32]));
+  });
+
+  it('cancels at most once across abort, timeout, terminal, and cancellation-failure races', async () => {
+    vi.useFakeTimers();
+    const fake = createFakeHub();
+    const controller = new AbortController();
+    const enqueue = createDeferred<{ enqueued: number; itemIds: number[] }>();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.reject(new Error('cancel failed')));
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: () => enqueue.promise,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      signal: controller.signal,
+      timeoutMs: 1000,
+    });
+    const assertion = expect(promise).rejects.toMatchObject({ reason: 'aborted' });
+
+    controller.abort();
+    await vi.advanceTimersByTimeAsync(1000);
+    fake.emit('queue_item_status_changed', statusEvent('failed'));
+    enqueue.resolve({ enqueued: 2, itemIds: [41, 42] });
+
+    await assertion;
+    await vi.runAllTimersAsync();
+    expect(cancel).toHaveBeenCalledExactlyOnceWith([41, 42]);
+  });
+
+  it('does not cancel when a terminal success wins before a later abort', async () => {
+    const fake = createFakeHub();
+    const controller = new AbortController();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.resolve());
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: () => Promise.resolve({ enqueued: 2, itemIds: [51, 52] }),
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      signal: controller.signal,
+    });
+    await Promise.resolve();
+
+    fake.emit('invocation_complete', completeEvent());
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+    controller.abort();
+    await Promise.resolve();
+
+    expect(cancel).not.toHaveBeenCalled();
+  });
+
+  it('does not cancel when an aborted pending enqueue later accepts zero items', async () => {
+    const fake = createFakeHub();
+    const controller = new AbortController();
+    const enqueue = createDeferred<{ enqueued: number; itemIds: number[] }>();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.resolve());
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: () => enqueue.promise,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      signal: controller.signal,
+    });
+    const assertion = expect(promise).rejects.toMatchObject({ reason: 'aborted' });
+
+    controller.abort();
+    enqueue.resolve({ enqueued: 0, itemIds: [] });
+
+    await assertion;
+    await Promise.resolve();
+    expect(cancel).not.toHaveBeenCalled();
+  });
+
+  it('does not use a timeout when timeoutMs is 0', async () => {
+    vi.useFakeTimers();
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      timeoutMs: 0,
+    });
+    await vi.advanceTimersByTimeAsync(DEFAULT_UTILITY_QUEUE_TIMEOUT_MS * 2);
+    // Still pending — settle it so the promise doesn't leak.
+    fake.emit('invocation_complete', completeEvent());
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+  });
+});
+
+describe('runUtilityGraph — enqueue failures', () => {
+  it.each([
+    { enqueued: 1, itemIds: [], label: 'accepted count without ids', canceled: [] },
+    { enqueued: 1, itemIds: [Number.NaN], label: 'non-finite id', canceled: [] },
+    { enqueued: 1, itemIds: [0], label: 'non-positive id', canceled: [] },
+    { enqueued: Number.NaN, itemIds: [11], label: 'non-finite accepted count', canceled: [11] },
+    { enqueued: 1.5, itemIds: [11], label: 'fractional accepted count', canceled: [11] },
+    { enqueued: -1, itemIds: [11], label: 'negative accepted count', canceled: [11] },
+    { enqueued: 2, itemIds: [11, 11], label: 'duplicate ids', canceled: [11] },
+    { enqueued: 2, itemIds: [11], label: 'count mismatch', canceled: [11] },
+  ])('immediately rejects $label and fully cleans up', async ({ canceled, enqueued, itemIds }) => {
+    vi.useFakeTimers();
+    const fake = createFakeHub();
+    const cancel = vi.fn((_itemIds: number[]) => Promise.resolve());
+    const promise = runUtilityGraph({
+      cancel,
+      createId: () => UTIL_ID,
+      enqueue: () => Promise.resolve({ enqueued, itemIds }),
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+
+    await expect(promise).rejects.toMatchObject({ reason: 'enqueue' });
+    await Promise.resolve();
+
+    expect(cancel).toHaveBeenCalledTimes(canceled.length > 0 ? 1 : 0);
+    if (canceled.length > 0) {
+      expect(cancel).toHaveBeenCalledWith(canceled);
+    }
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('accepts a valid multi-item enqueue response', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: () => Promise.resolve({ enqueued: 2, itemIds: [11, 12] }),
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+    await Promise.resolve();
+
+    fake.emit('invocation_complete', completeEvent());
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+  });
+
+  it('contains a synchronous enqueue throw and cleans listeners with timeout disabled', async () => {
+    vi.useFakeTimers();
+    const fake = createFakeHub();
+    const cause = new Error('synchronous enqueue failure');
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: () => {
+        throw cause;
+      },
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      timeoutMs: 0,
+    });
+
+    await expect(promise).rejects.toMatchObject({ cause, message: cause.message, reason: 'enqueue' });
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('contains a synchronous reconciliation scheduler throw and fully settles with timeout disabled', async () => {
+    vi.useFakeTimers();
+    const fake = createFakeHub();
+    const cause = new Error('scheduler unavailable');
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => Promise.resolve(null),
+      scheduleReconcileRetry: () => {
+        throw cause;
+      },
+      timeoutMs: 0,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).rejects.toMatchObject({
+      cause,
+      message: 'Failed to schedule utility graph output reconciliation: scheduler unavailable',
+      reason: 'reconcile',
+    });
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('contains a throwing reconciliation retry cancellation seam during socket success', async () => {
+    const fake = createFakeHub();
+    const cancelRetry = vi.fn(() => {
+      throw new Error('cancel retry failed');
+    });
+    const scheduleReconcileRetry = vi.fn(() => cancelRetry);
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => Promise.resolve(null),
+      scheduleReconcileRetry,
+      timeoutMs: 0,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await vi.waitFor(() => expect(scheduleReconcileRetry).toHaveBeenCalledOnce());
+
+    expect(() => fake.emit('invocation_complete', completeEvent())).not.toThrow();
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+    expect(cancelRetry).toHaveBeenCalledOnce();
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+  });
+
+  it('contains a synchronous id-source throw as a setup error', async () => {
+    const cause = new Error('id source failed');
+    const promise = runUtilityGraph({
+      createId: () => {
+        throw cause;
+      },
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: createFakeHub().hub,
+      timeoutMs: 0,
+    });
+
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'setup' });
+  });
+
+  it('cleans a partially attached listener when the second socket subscription throws', async () => {
+    const fake = createFakeHub();
+    const cause = new Error('subscription failed');
+    let calls = 0;
+    const hub: Pick<SocketHub, 'on'> = {
+      on: (event, handler) => {
+        calls += 1;
+        if (calls === 2) {
+          throw cause;
+        }
+        return fake.hub.on(event, handler);
+      },
+    };
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub,
+      timeoutMs: 0,
+    });
+
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'setup' });
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+  });
+
+  it('contains a synchronous injected reconciliation classifier throw', async () => {
+    const fake = createFakeHub();
+    const cause = new Error('classifier failed');
+    const promise = runUtilityGraph({
+      classifyReconcileError: () => {
+        throw cause;
+      },
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      reconcileCompletedOutput: () => Promise.reject(new TypeError('network failed')),
+      timeoutMs: 0,
+    });
+    await Promise.resolve();
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'reconcile' });
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+  });
+
+  it('cleans listeners when abort-signal subscription throws synchronously', async () => {
+    const fake = createFakeHub();
+    const cause = new Error('abort subscription failed');
+    const signal = {
+      aborted: false,
+      addEventListener: () => {
+        throw cause;
+      },
+      removeEventListener: vi.fn(),
+    } as unknown as AbortSignal;
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      signal,
+      timeoutMs: 0,
+    });
+
+    await expect(promise).rejects.toMatchObject({ cause, reason: 'setup' });
+    expect(fake.handlerCount('invocation_complete')).toBe(0);
+    expect(fake.handlerCount('queue_item_status_changed')).toBe(0);
+  });
+
+  it('rejects enqueue when the backend accepts zero items', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: () => Promise.resolve({ enqueued: 0, itemIds: [] }),
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+    await expect(promise).rejects.toMatchObject({ reason: 'enqueue' });
+  });
+
+  it('rejects enqueue when the enqueue call throws', async () => {
+    const fake = createFakeHub();
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: () => Promise.reject(new Error('network down')),
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+    });
+    await expect(promise).rejects.toMatchObject({ message: 'network down', reason: 'enqueue' });
+  });
+});
+
+describe('runUtilityGraph — origin isolation (Risk 4)', () => {
+  it('mints a webv2:util: origin that project routing provably ignores', () => {
+    // The utility origin resolves to NO local queue item, so `queueCoordinator`
+    // (which keys backend items by `parseQueueItemOrigin`) and `routeQueueItemResults`
+    // never adopt a utility item into project staging / gallery routing.
+    expect(isUtilityQueueItemOrigin(ORIGIN)).toBe(true);
+    expect(parseQueueItemOrigin(ORIGIN)).toBeNull();
+
+    // A real project origin, by contrast, DOES parse to its local queue item id —
+    // demonstrating the coordinator adopts those but not utility items.
+    const projectOrigin = buildQueueItemOrigin('local-1', 'project-1');
+    expect(isUtilityQueueItemOrigin(projectOrigin)).toBe(false);
+    expect(parseQueueItemOrigin(projectOrigin)).toBe('local-1');
+  });
+
+  it('ignores socket events whose origin is not this utility run', async () => {
+    const fake = createFakeHub();
+    let settled = false;
+    const promise = runUtilityGraph({
+      createId: () => UTIL_ID,
+      enqueue: okEnqueue,
+      graph: { edges: [], id: 'g', nodes: {} },
+      hub: fake.hub,
+      timeoutMs: 0,
+    }).then((result) => {
+      settled = true;
+      return result;
+    });
+
+    // Events for a DIFFERENT origin (another util run or a project item) must not settle us.
+    const otherOrigin = buildUtilityQueueItemOrigin('other-util');
+    fake.emit(
+      'invocation_complete',
+      completeEvent({ origin: otherOrigin, result: { image: { image_name: 'other.png' }, type: 'image_output' } })
+    );
+    fake.emit(
+      'queue_item_status_changed',
+      statusEvent('completed', { origin: buildQueueItemOrigin('local-1', 'project-1') })
+    );
+    await Promise.resolve();
+    expect(settled).toBe(false);
+
+    // Our origin's events do settle us.
+    fake.emit('invocation_complete', completeEvent());
+    fake.emit('queue_item_status_changed', statusEvent('completed'));
+    await expect(promise).resolves.toMatchObject({ imageName: 'filtered.png' });
+  });
+});
+
+describe('UtilityQueueError', () => {
+  it('carries a reason and a name', () => {
+    const error = new UtilityQueueError('timeout', 'nope');
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('UtilityQueueError');
+    expect(error.reason).toBe('timeout');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/utilityQueue.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/utilityQueue.ts
new file mode 100644
index 00000000000..2619d947038
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/backend/utilityQueue.ts
@@ -0,0 +1,525 @@
+/**
+ * The utility queue: fire-and-await small graphs OUTSIDE any project's queue.
+ *
+ * Filter previews and (later) Segment-Anything need to run a one-shot graph and
+ * read back its single output image WITHOUT the result ever touching project
+ * staging or the gallery. {@link runUtilityGraph} does exactly that:
+ *
+ * 1. Mints a fresh `webv2:util:<uuid>` origin (see `backend/events.ts`). That
+ *    origin is deliberately invisible to project routing — `parseQueueItemOrigin`
+ *    returns `null` for it, so `queueCoordinator.reconcile` /
+ *    `isQueueServerItemInProject` never adopt it and `routeQueueItemResults`
+ *    (only invoked for coordinator-tracked project runs, which a utility item is
+ *    never registered as) never sees it. This is the plan's Risk-4 guard.
+ * 2. Attaches raw `socketHub.on` listeners (they survive socket recreation) for
+ *    `invocation_complete` (to capture the output image name and dimensions) and
+ *    `queue_item_status_changed` (to settle on the terminal status), matching
+ *    events by our unique origin.
+ * 3. Enqueues the graph (listeners are attached first, closing the fast-finish
+ *    race), then resolves with the output image metadata on completion, or rejects
+ *    on failure/cancellation/timeout/abort. Abort and timeout also best-effort
+ *    cancel every backend item accepted for this run, including when enqueue
+ *    resolves after the local await has already rejected.
+ *
+ * Zero React, zero DOM: `hub` and `enqueue` are injected, so this runs in node
+ * tests against fakes. Every side-effecting dependency is a parameter.
+ */
+
+import type { InvocationCompleteEvent, QueueItemStatusChangedEvent } from '@workbench/backend/events';
+import type { SocketHub } from '@workbench/backend/socketHub';
+import type { BackendGraphContract } from '@workbench/types';
+
+import { buildUtilityQueueItemOrigin } from '@workbench/backend/events';
+import { ApiError } from '@workbench/backend/http';
+import { cancelQueueItems, enqueueUtilityGraph, getQueueItem } from '@workbench/generation/api';
+
+/** The default time a utility graph may run before it is abandoned. */
+export const DEFAULT_UTILITY_QUEUE_TIMEOUT_MS = 120_000;
+
+/** Bounded retries for transient completed-item reconciliation failures. */
+export const DEFAULT_UTILITY_RECONCILE_RETRY_POLICY = { delayMs: 100, maxAttempts: 3 } as const;
+
+/** Thrown when a utility graph fails, is canceled, times out, or is aborted. */
+export class UtilityQueueError extends Error {
+  readonly reason: 'failed' | 'canceled' | 'timeout' | 'aborted' | 'no-output' | 'enqueue' | 'reconcile' | 'setup';
+
+  constructor(reason: UtilityQueueError['reason'], message: string, cause?: unknown) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'UtilityQueueError';
+    this.reason = reason;
+  }
+}
+
+/** The enqueue seam: posts the graph under `origin`, resolving to its backend item ids. */
+export type UtilityEnqueue = (request: {
+  graph: BackendGraphContract;
+  origin: string;
+}) => Promise<{ itemIds: number[]; enqueued: number }>;
+
+/** The cancellation seam: best-effort cancels accepted backend item ids. */
+export type UtilityCancel = (itemIds: number[]) => Promise<void>;
+
+type UtilityImageOutput = { height: number; imageName: string; width: number };
+
+const inspectUtilityEnqueueResult = (result: unknown) => {
+  const response = result as { itemIds?: unknown; enqueued?: unknown } | null;
+  const rawItemIds = Array.isArray(response?.itemIds) ? response.itemIds : [];
+  const itemIds = [
+    ...new Set(
+      rawItemIds.filter(
+        (id): id is number => typeof id === 'number' && Number.isFinite(id) && Number.isInteger(id) && id > 0
+      )
+    ),
+  ];
+  const enqueued = response?.enqueued;
+  const valid =
+    Number.isInteger(enqueued) &&
+    (enqueued as number) > 0 &&
+    itemIds.length === rawItemIds.length &&
+    itemIds.length === enqueued;
+  return { itemIds, result: valid ? { enqueued: enqueued as number, itemIds } : null };
+};
+
+/** Deterministically reads a completed queue item's target output. */
+export type UtilityCompletedOutputReconciler = (
+  itemIds: number[],
+  outputNodeId?: string
+) => Promise<UtilityImageOutput | null>;
+
+export interface UtilityReconcileRetryPolicy {
+  delayMs: number;
+  maxAttempts: number;
+}
+
+/** Returns a cancellation function for one scheduled reconciliation retry. */
+export type UtilityReconcileRetryScheduler = (callback: () => void, delayMs: number) => () => void;
+
+export type UtilityReconcileErrorClassifier = (cause: unknown) => 'retry' | 'fail';
+
+export const classifyUtilityReconcileError: UtilityReconcileErrorClassifier = (cause) => {
+  if (cause instanceof TypeError) {
+    return 'retry';
+  }
+  if (cause instanceof ApiError) {
+    return cause.status === 408 || cause.status === 429 || (cause.status >= 500 && cause.status <= 599)
+      ? 'retry'
+      : 'fail';
+  }
+  return 'fail';
+};
+
+const scheduleUtilityReconcileRetry: UtilityReconcileRetryScheduler = (callback, delayMs) => {
+  const timer = setTimeout(callback, delayMs);
+  return () => clearTimeout(timer);
+};
+
+/** Dependencies for {@link runUtilityGraph} (all injectable for tests). */
+export interface RunUtilityGraphOptions {
+  /** The graph to enqueue and await. */
+  graph: BackendGraphContract;
+  /**
+   * The source node id whose `invocation_complete` output image is the result.
+   * When omitted, the first image-bearing completion for our origin is used.
+   */
+  outputNodeId?: string;
+  /** The socket hub (only `on` is used). Raw listeners survive socket recreation. */
+  hub: Pick<SocketHub, 'on'>;
+  /** Enqueue seam (defaults to the real utility enqueue API). */
+  enqueue?: UtilityEnqueue;
+  /** Cancellation seam (defaults to the real queue cancellation API). */
+  cancel?: UtilityCancel;
+  /** Abandon after this many ms (default {@link DEFAULT_UTILITY_QUEUE_TIMEOUT_MS}). `0` disables. */
+  timeoutMs?: number;
+  /** Cancels the await and best-effort cancels accepted backend items. */
+  signal?: AbortSignal;
+  /** Injectable id source (defaults to `crypto.randomUUID`). */
+  createId?: () => string;
+  /** Injectable completed-item reconciliation seam. */
+  reconcileCompletedOutput?: UtilityCompletedOutputReconciler;
+  /** Bounded reconciliation retry policy. */
+  reconcileRetryPolicy?: UtilityReconcileRetryPolicy;
+  /** Injectable reconciliation retry timer seam. */
+  scheduleReconcileRetry?: UtilityReconcileRetryScheduler;
+  /** Injectable reconciliation failure classifier. */
+  classifyReconcileError?: UtilityReconcileErrorClassifier;
+}
+
+/** The resolved result of a utility graph: its single output image. */
+export interface UtilityGraphResult {
+  height: number;
+  imageName: string;
+  /** The origin used, for diagnostics/tests. */
+  origin: string;
+  width: number;
+}
+
+/** Extracts the current backend ImageOutput fields from a completion payload. */
+const extractImageOutput = (result: InvocationCompleteEvent['result'] | undefined): UtilityImageOutput | null => {
+  const output = result as { height?: unknown; image?: { image_name?: unknown }; width?: unknown } | undefined;
+  if (
+    typeof output?.image?.image_name !== 'string' ||
+    typeof output.width !== 'number' ||
+    !Number.isFinite(output.width) ||
+    !Number.isInteger(output.width) ||
+    output.width <= 0 ||
+    typeof output.height !== 'number' ||
+    !Number.isFinite(output.height) ||
+    !Number.isInteger(output.height) ||
+    output.height <= 0
+  ) {
+    return null;
+  }
+  return { height: output.height, imageName: output.image.image_name, width: output.width };
+};
+
+export const reconcileUtilityCompletedOutput: UtilityCompletedOutputReconciler = async (itemIds, outputNodeId) => {
+  for (const itemId of itemIds) {
+    const item = await getQueueItem(itemId);
+    if (
+      !item ||
+      typeof item !== 'object' ||
+      item.item_id !== itemId ||
+      !item.session ||
+      typeof item.session !== 'object' ||
+      !item.session.results ||
+      typeof item.session.results !== 'object' ||
+      Array.isArray(item.session.results) ||
+      (item.session.prepared_source_mapping !== undefined &&
+        (typeof item.session.prepared_source_mapping !== 'object' ||
+          item.session.prepared_source_mapping === null ||
+          Array.isArray(item.session.prepared_source_mapping)))
+    ) {
+      throw new Error(`Queue item ${itemId} returned malformed reconciliation data.`);
+    }
+    const results = item.session?.results ?? {};
+    const preparedSourceMapping = item.session?.prepared_source_mapping ?? {};
+    for (const [preparedNodeId, result] of Object.entries(results)) {
+      if (outputNodeId && (preparedSourceMapping[preparedNodeId] ?? preparedNodeId) !== outputNodeId) {
+        continue;
+      }
+      const output = extractImageOutput(result as InvocationCompleteEvent['result']);
+      if (output) {
+        return output;
+      }
+      if (outputNodeId) {
+        throw new Error(`Queue item ${itemId} returned malformed output for node ${outputNodeId}.`);
+      }
+    }
+  }
+  return null;
+};
+
+/**
+ * Runs `graph` on the utility queue and resolves with its output image metadata.
+ * Never routes into project state (isolated origin). Rejects with a
+ * {@link UtilityQueueError} on failure/cancel/timeout/abort/enqueue error.
+ */
+export const runUtilityGraph = (options: RunUtilityGraphOptions): Promise<UtilityGraphResult> => {
+  const { graph, hub, outputNodeId, signal } = options;
+  const enqueue = options.enqueue ?? enqueueUtilityGraph;
+  const cancel = options.cancel ?? cancelQueueItems;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_UTILITY_QUEUE_TIMEOUT_MS;
+  const reconcileCompletedOutput = options.reconcileCompletedOutput ?? reconcileUtilityCompletedOutput;
+  const reconcileRetryPolicy = options.reconcileRetryPolicy ?? DEFAULT_UTILITY_RECONCILE_RETRY_POLICY;
+  const scheduleReconcileRetry = options.scheduleReconcileRetry ?? scheduleUtilityReconcileRetry;
+  const classifyReconcileError = options.classifyReconcileError ?? classifyUtilityReconcileError;
+  const reconcileMaxAttempts = Number.isFinite(reconcileRetryPolicy.maxAttempts)
+    ? Math.max(1, Math.floor(reconcileRetryPolicy.maxAttempts))
+    : DEFAULT_UTILITY_RECONCILE_RETRY_POLICY.maxAttempts;
+  const reconcileDelayMs = Number.isFinite(reconcileRetryPolicy.delayMs)
+    ? Math.max(0, reconcileRetryPolicy.delayMs)
+    : DEFAULT_UTILITY_RECONCILE_RETRY_POLICY.delayMs;
+  let origin: string;
+  try {
+    const utilityId = (options.createId ?? (() => crypto.randomUUID()))();
+    origin = buildUtilityQueueItemOrigin(utilityId);
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return Promise.reject(new UtilityQueueError('setup', `Failed to initialize utility graph run: ${detail}`, cause));
+  }
+
+  return new Promise<UtilityGraphResult>((resolve, reject) => {
+    let settled = false;
+    let capturedOutput: { height: number; imageName: string; width: number } | null = null;
+    let cancellationRequested = false;
+    let cancellationStarted = false;
+    let enqueueResult: { itemIds: number[]; enqueued: number } | null = null;
+    let completionReceived = false;
+    let reconciliationAttempts = 0;
+    let reconciliationInFlight = false;
+    let cancelReconciliationRetry: (() => void) | null = null;
+    const detachers: Array<() => void> = [];
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const cancelAcceptedItems = (): void => {
+      if (
+        !cancellationRequested ||
+        cancellationStarted ||
+        enqueueResult === null ||
+        enqueueResult.enqueued === 0 ||
+        enqueueResult.itemIds.length === 0
+      ) {
+        return;
+      }
+
+      cancellationStarted = true;
+      const itemIds = [...enqueueResult.itemIds];
+      void Promise.resolve()
+        .then(() => cancel(itemIds))
+        .catch(() => {
+          // Cancellation is best-effort and must never mask the original settle reason.
+        });
+    };
+
+    const requestBackendCancellation = (): void => {
+      cancellationRequested = true;
+      cancelAcceptedItems();
+    };
+
+    const cleanup = (): void => {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      const cancelRetry = cancelReconciliationRetry;
+      cancelReconciliationRetry = null;
+      if (cancelRetry) {
+        try {
+          cancelRetry();
+        } catch {
+          // Cleanup is best-effort and must not interrupt settlement.
+        }
+      }
+      for (const detach of detachers) {
+        try {
+          detach();
+        } catch {
+          // Continue detaching the remaining listeners.
+        }
+      }
+      detachers.length = 0;
+      if (signal) {
+        try {
+          signal.removeEventListener('abort', onAbort);
+        } catch {
+          // Cleanup must not interrupt settlement.
+        }
+      }
+    };
+
+    const settleResolve = (output: { height: number; imageName: string; width: number }): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve({ ...output, origin });
+    };
+
+    const settleReject = (error: UtilityQueueError): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+
+    const reconcileCompletion = (): void => {
+      if (
+        settled ||
+        !completionReceived ||
+        reconciliationInFlight ||
+        cancelReconciliationRetry !== null ||
+        enqueueResult === null
+      ) {
+        return;
+      }
+      if (capturedOutput) {
+        settleResolve(capturedOutput);
+        return;
+      }
+      reconciliationAttempts += 1;
+      reconciliationInFlight = true;
+      const reconciliationItemIds = [...enqueueResult.itemIds];
+      const scheduleNextReconciliation = (): void => {
+        try {
+          const cancelRetry = scheduleReconcileRetry(() => {
+            cancelReconciliationRetry = null;
+            reconcileCompletion();
+          }, reconcileDelayMs);
+          cancelReconciliationRetry = typeof cancelRetry === 'function' ? cancelRetry : null;
+        } catch (cause) {
+          const detail = cause instanceof Error ? cause.message : String(cause);
+          settleReject(
+            new UtilityQueueError(
+              'reconcile',
+              `Failed to schedule utility graph output reconciliation: ${detail}`,
+              cause
+            )
+          );
+        }
+      };
+      void Promise.resolve()
+        .then(() => reconcileCompletedOutput(reconciliationItemIds, outputNodeId))
+        .then((output) => {
+          reconciliationInFlight = false;
+          if (settled) {
+            return;
+          }
+          if (capturedOutput) {
+            settleResolve(capturedOutput);
+          } else if (output) {
+            settleResolve(output);
+          } else if (reconciliationAttempts >= reconcileMaxAttempts) {
+            settleReject(new UtilityQueueError('no-output', 'The utility graph produced no output image.'));
+          } else {
+            scheduleNextReconciliation();
+          }
+        })
+        .catch((cause: unknown) => {
+          reconciliationInFlight = false;
+          if (settled || capturedOutput) {
+            if (capturedOutput) {
+              settleResolve(capturedOutput);
+            }
+            return;
+          }
+          let classification: ReturnType<UtilityReconcileErrorClassifier>;
+          try {
+            classification = classifyReconcileError(cause);
+          } catch (classifierCause) {
+            const detail = classifierCause instanceof Error ? classifierCause.message : String(classifierCause);
+            settleReject(
+              new UtilityQueueError(
+                'reconcile',
+                `Failed to classify utility reconciliation error: ${detail}`,
+                classifierCause
+              )
+            );
+            return;
+          }
+          if (classification === 'fail' || reconciliationAttempts >= reconcileMaxAttempts) {
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            settleReject(
+              new UtilityQueueError(
+                'reconcile',
+                `Failed to reconcile utility graph output after ${reconciliationAttempts} attempts: ${detail}`,
+                cause
+              )
+            );
+            return;
+          }
+          scheduleNextReconciliation();
+        });
+    };
+
+    function onAbort(): void {
+      if (settled) {
+        return;
+      }
+      requestBackendCancellation();
+      settleReject(new UtilityQueueError('aborted', 'The utility graph was aborted.'));
+    }
+
+    // Attach listeners BEFORE enqueue so a very fast completion is not missed.
+    try {
+      detachers.push(
+        hub.on('invocation_complete', (event: InvocationCompleteEvent) => {
+          if (event.origin !== origin) {
+            return;
+          }
+          // Only take the target node's output (or, when unspecified, any image).
+          if (outputNodeId && event.invocation_source_id !== outputNodeId) {
+            return;
+          }
+          const output = extractImageOutput(event.result);
+          if (output) {
+            capturedOutput = output;
+            if (completionReceived) {
+              settleResolve(output);
+            }
+          }
+        })
+      );
+
+      detachers.push(
+        hub.on('queue_item_status_changed', (event: QueueItemStatusChangedEvent) => {
+          if (event.origin !== origin) {
+            return;
+          }
+          if (event.status === 'completed') {
+            completionReceived = true;
+            reconcileCompletion();
+          } else if (event.status === 'failed') {
+            const errorMessage = typeof event.error_message === 'string' ? event.error_message.trim() : '';
+            const errorType = typeof event.error_type === 'string' ? event.error_type.trim() : '';
+            settleReject(new UtilityQueueError('failed', errorMessage || errorType || 'The utility graph failed.'));
+          } else if (event.status === 'canceled') {
+            settleReject(new UtilityQueueError('canceled', 'The utility graph was canceled.'));
+          }
+        })
+      );
+    } catch (cause) {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      settleReject(new UtilityQueueError('setup', `Failed to attach utility graph listeners: ${detail}`, cause));
+      return;
+    }
+
+    try {
+      if (signal) {
+        if (signal.aborted) {
+          onAbort();
+          return;
+        }
+        signal.addEventListener('abort', onAbort);
+      }
+    } catch (cause) {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      settleReject(new UtilityQueueError('setup', `Failed to attach utility graph abort listener: ${detail}`, cause));
+      return;
+    }
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        requestBackendCancellation();
+        settleReject(new UtilityQueueError('timeout', `The utility graph timed out after ${timeoutMs}ms.`));
+      }, timeoutMs);
+    }
+
+    // Enqueue last. A synchronous listener callback could already have fired by
+    // the time this resolves; `settled` guards against a late enqueue result.
+    void Promise.resolve()
+      .then(() => enqueue({ graph, origin }))
+      .then((result) => {
+        const inspected = inspectUtilityEnqueueResult(result);
+        const validResult = inspected.result;
+        if (!validResult) {
+          const knownItemIds = inspected.itemIds;
+          enqueueResult = { enqueued: knownItemIds.length, itemIds: knownItemIds };
+          requestBackendCancellation();
+          settleReject(
+            new UtilityQueueError('enqueue', 'The backend returned an inconsistent utility enqueue response.')
+          );
+          return;
+        }
+        enqueueResult = validResult;
+        cancelAcceptedItems();
+        if (!settled) {
+          reconcileCompletion();
+        }
+      })
+      .catch((error: unknown) => {
+        settleReject(
+          new UtilityQueueError(
+            'enqueue',
+            error instanceof Error ? error.message : 'Failed to enqueue utility graph.',
+            error
+          )
+        );
+      });
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/canvasImportNotice.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/canvasImportNotice.test.ts
new file mode 100644
index 00000000000..e7951b20c3c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/canvasImportNotice.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+
+import { getCanvasImportNotice } from './canvasImportNotice';
+
+describe('getCanvasImportNotice', () => {
+  it('maps a complete import to a localized success notice', () => {
+    expect(
+      getCanvasImportNotice({ failedImageNames: [], layerIds: ['layer-1', 'layer-2'], status: 'imported' })
+    ).toEqual({
+      kind: 'success',
+      options: { count: 2 },
+      titleKey: 'widgets.canvas.import.success',
+    });
+  });
+
+  it('maps one successful partial import with the exact pluralization interpolation', () => {
+    expect(
+      getCanvasImportNotice({
+        failedImageNames: ['failed-1.png', 'failed-2.png'],
+        layerIds: ['layer-1'],
+        status: 'imported',
+      })
+    ).toEqual({
+      kind: 'info',
+      options: { count: 1, failedCount: 2, successCount: 1 },
+      titleKey: 'widgets.canvas.import.partial',
+    });
+  });
+
+  it('maps multiple successful partial imports with the exact pluralization interpolation', () => {
+    expect(
+      getCanvasImportNotice({
+        failedImageNames: ['failed.png'],
+        layerIds: ['layer-1', 'layer-2'],
+        status: 'imported',
+      })
+    ).toEqual({
+      kind: 'info',
+      options: { count: 2, failedCount: 1, successCount: 2 },
+      titleKey: 'widgets.canvas.import.partial',
+    });
+  });
+
+  it.each([
+    ['blocked', 'info', 'widgets.canvas.import.blocked'],
+    ['empty', 'info', 'widgets.canvas.import.empty'],
+    ['stale-document', 'error', 'widgets.canvas.import.staleDocument'],
+    ['stale-project', 'error', 'widgets.canvas.import.staleProject'],
+  ] as const)('maps %s to the expected localized notice', (status, kind, titleKey) => {
+    expect(getCanvasImportNotice({ status })).toEqual({ kind, titleKey });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/canvasImportNotice.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/canvasImportNotice.ts
new file mode 100644
index 00000000000..81b7cff3726
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/canvasImportNotice.ts
@@ -0,0 +1,49 @@
+import type { ImportGalleryImagesResult } from './importGalleryImages';
+
+export interface CanvasImportNotice {
+  kind: 'error' | 'info' | 'success';
+  titleKey:
+    | 'widgets.canvas.import.blocked'
+    | 'widgets.canvas.import.empty'
+    | 'widgets.canvas.import.partial'
+    | 'widgets.canvas.import.staleDocument'
+    | 'widgets.canvas.import.staleProject'
+    | 'widgets.canvas.import.success';
+  options?: { count: number } | { count: number; failedCount: number; successCount: number };
+}
+
+const assertNever = (value: never): never => {
+  throw new Error(`Unhandled canvas import result: ${JSON.stringify(value)}`);
+};
+
+export const getCanvasImportNotice = (result: ImportGalleryImagesResult): CanvasImportNotice => {
+  switch (result.status) {
+    case 'imported':
+      if (result.failedImageNames.length > 0) {
+        return {
+          kind: 'info',
+          options: {
+            count: result.layerIds.length,
+            failedCount: result.failedImageNames.length,
+            successCount: result.layerIds.length,
+          },
+          titleKey: 'widgets.canvas.import.partial',
+        };
+      }
+      return {
+        kind: 'success',
+        options: { count: result.layerIds.length },
+        titleKey: 'widgets.canvas.import.success',
+      };
+    case 'blocked':
+      return { kind: 'info', titleKey: 'widgets.canvas.import.blocked' };
+    case 'empty':
+      return { kind: 'info', titleKey: 'widgets.canvas.import.empty' };
+    case 'stale-document':
+      return { kind: 'error', titleKey: 'widgets.canvas.import.staleDocument' };
+    case 'stale-project':
+      return { kind: 'error', titleKey: 'widgets.canvas.import.staleProject' };
+    default:
+      return assertNever(result);
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/compositeForGeneration.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/compositeForGeneration.test.ts
new file mode 100644
index 00000000000..6a87283a5c9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/compositeForGeneration.test.ts
@@ -0,0 +1,403 @@
+import type { CanvasImageUploadResult } from '@workbench/canvas-engine/document/imageUpload';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { StubRasterSurface } from '@workbench/canvas-engine/render/raster.testStub';
+import type { Rect } from '@workbench/generation/canvas/types';
+import type {
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { planComposites } from '@workbench/generation/canvas/compositePlan';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ExecuteCompositePlanDeps } from './compositeForGeneration';
+
+import {
+  createCompositeDedupeCache,
+  executeCompositePlan,
+  executeMaskComposite,
+  toGrayscaleMaskPixels,
+} from './compositeForGeneration';
+
+const imageRef = (imageName: string, width = 64, height = 48): CanvasImageRef => ({ height, imageName, width });
+
+const rasterLayer = (
+  id: string,
+  overrides: Partial<CanvasRasterLayerContractV2> = {}
+): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: imageRef(id), type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+  ...overrides,
+});
+
+const makeDoc = (layers: CanvasLayerContract[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 100, width: 100, x: 0, y: 0 },
+  height: 100,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 100,
+});
+
+const BBOX: Rect = { height: 100, width: 100, x: 0, y: 0 };
+
+/** Builds an ImageData-like object with a uniform alpha (255 = opaque). */
+const uniformImageData = (width: number, height: number, alpha: number): ImageData => {
+  const data = new Uint8ClampedArray(width * height * 4);
+  for (let i = 3; i < data.length; i += 4) {
+    data[i] = alpha;
+  }
+  return { colorSpace: 'srgb', data, height, width } as unknown as ImageData;
+};
+
+/** An opaque scan except a single transparent pixel (a hole). */
+const holeImageData = (width: number, height: number): ImageData => {
+  const image = uniformImageData(width, height, 255);
+  image.data[3] = 0;
+  return image;
+};
+
+interface Harness {
+  deps: ExecuteCompositePlanDeps;
+  createdTargets: StubRasterSurface[];
+  layerSurfaces: Map<string, StubRasterSurface>;
+  uploadImage: ReturnType<typeof vi.fn>;
+  encodeSurface: ReturnType<typeof vi.fn>;
+}
+
+const makeHarness = (readImageData?: (surface: RasterSurface, rect: Rect) => ImageData): Harness => {
+  const stub = createTestStubRasterBackend();
+  const createdTargets: StubRasterSurface[] = [];
+  const layerSurfaces = new Map<string, StubRasterSurface>();
+
+  const encodeSurface = vi.fn((surface: RasterSurface) => stub.encodeSurface(surface));
+  const backend = {
+    createSurface: (w: number, h: number): StubRasterSurface => {
+      const surface = stub.createSurface(w, h);
+      createdTargets.push(surface);
+      return surface;
+    },
+    encodeSurface,
+  };
+
+  const getLayerSurface = (layerId: string): Promise<{ surface: RasterSurface; rect: Rect }> => {
+    let surface = layerSurfaces.get(layerId);
+    if (!surface) {
+      // Layer caches are content-sized; created off the raw stub so they don't
+      // pollute the composite-target capture. Origin-anchored (0,0) here.
+      surface = stub.createSurface(64, 48);
+      layerSurfaces.set(layerId, surface);
+    }
+    return Promise.resolve({ rect: { height: 48, width: 64, x: 0, y: 0 }, surface });
+  };
+
+  let counter = 0;
+  const uploadImage = vi.fn((blob: Blob): Promise<CanvasImageUploadResult> => {
+    void blob;
+    counter += 1;
+    return Promise.resolve({ height: 100, imageName: `uploaded-${counter}`, width: 100 });
+  });
+
+  const deps: ExecuteCompositePlanDeps = {
+    backend,
+    dedupe: createCompositeDedupeCache(),
+    getLayerSurface,
+    // Content-addressed hash: identical blob bytes → identical hash.
+    hashBlob: (blob: Blob) => blob.text(),
+    readImageData,
+    uploadImage,
+  };
+
+  return { createdTargets, deps, encodeSurface, layerSurfaces, uploadImage };
+};
+
+describe('executeCompositePlan — compositing', () => {
+  it('composites enabled raster layers bottom→top into a bbox-sized surface', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    const doc = makeDoc([rasterLayer('top', { opacity: 0.4 }), rasterLayer('bottom', { opacity: 0.9 })]);
+    const plan = planComposites(doc, BBOX);
+
+    await executeCompositePlan(plan, harness.deps);
+
+    expect(harness.createdTargets).toHaveLength(1);
+    const target = harness.createdTargets[0]!;
+    expect(target.width).toBe(100);
+    expect(target.height).toBe(100);
+
+    const drawImages = target.callLog.filter((e) => e.op === 'drawImage');
+    expect(drawImages).toHaveLength(2);
+    // Bottom layer (array index 1) is drawn first.
+    expect(drawImages[0]!.args[0]).toBe(harness.layerSurfaces.get('bottom')!.canvas);
+    expect(drawImages[1]!.args[0]).toBe(harness.layerSurfaces.get('top')!.canvas);
+
+    // Per-layer opacity is applied.
+    const alphas = target.callLog.filter((e) => e.op === 'set' && e.args[0] === 'globalAlpha').map((e) => e.args[1]);
+    expect(alphas).toContain(0.4);
+    expect(alphas).toContain(0.9);
+  });
+
+  it('translates the composite by the bbox origin (crops to the bbox)', async () => {
+    const harness = makeHarness(() => uniformImageData(50, 50, 255));
+    const doc = makeDoc([rasterLayer('a')]);
+    const bbox: Rect = { height: 50, width: 50, x: 20, y: 10 };
+    const plan = planComposites(doc, bbox);
+
+    await executeCompositePlan(plan, harness.deps);
+
+    const target = harness.createdTargets[0]!;
+    // The layer sits at document origin; under the bbox translate it draws at (-20, -10).
+    const setTransforms = target.callLog.filter((e) => e.op === 'setTransform');
+    expect(setTransforms.some((e) => e.args[4] === -20 && e.args[5] === -10)).toBe(true);
+  });
+});
+
+describe('executeCompositePlan — mode geometry', () => {
+  it('reports bboxFullyCovered=true for an opaque composite', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    const plan = planComposites(makeDoc([rasterLayer('a')]), BBOX);
+    const result = await executeCompositePlan(plan, harness.deps);
+    expect(result.bboxFullyCovered).toBe(true);
+  });
+
+  it('reports bboxFullyCovered=false when the composite has a transparent hole', async () => {
+    const harness = makeHarness(() => holeImageData(100, 100));
+    const plan = planComposites(makeDoc([rasterLayer('a')]), BBOX);
+    const result = await executeCompositePlan(plan, harness.deps);
+    expect(result.bboxFullyCovered).toBe(false);
+  });
+
+  it('computes contentBounds as the union of layer bounds in document space', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    const doc = makeDoc([
+      rasterLayer('a'), // 64x48 at (0,0)
+      rasterLayer('b', { transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 100, y: 100 } }), // 64x48 at (100,100)
+    ]);
+    const plan = planComposites(doc, BBOX);
+    const result = await executeCompositePlan(plan, harness.deps);
+    expect(result.contentBounds).toEqual({ height: 148, width: 164, x: 0, y: 0 });
+  });
+
+  it('returns contentBounds=null when there is no enabled raster content', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 0));
+    const plan = planComposites(makeDoc([rasterLayer('a', { isEnabled: false })]), BBOX);
+    const result = await executeCompositePlan(plan, harness.deps);
+    expect(result.contentBounds).toBeNull();
+  });
+});
+
+describe('executeCompositePlan — upload + dedupe', () => {
+  it('reserves the composite surface and coverage buffer until execution settles', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    const release = vi.fn();
+    const reserve = vi.fn(() => ({ lease: { release }, status: 'ok' as const }));
+    harness.deps.reserve = reserve;
+    const plan = planComposites(makeDoc([rasterLayer('a')]), BBOX);
+
+    await executeCompositePlan(plan, harness.deps);
+
+    expect(reserve).toHaveBeenCalledWith(80_000);
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('refuses a composite before allocating when its reservation is over budget', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    harness.deps.reserve = () => ({ availableBytes: 0, requestedBytes: 80_000, status: 'over-budget' });
+    const plan = planComposites(makeDoc([rasterLayer('a')]), BBOX);
+
+    await expect(executeCompositePlan(plan, harness.deps)).rejects.toThrow(
+      'The canvas composite exceeds the available raster memory budget'
+    );
+    expect(harness.createdTargets).toHaveLength(0);
+  });
+
+  it('encodes and uploads once, returning the uploaded image name', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    const plan = planComposites(makeDoc([rasterLayer('a')]), BBOX);
+
+    const result = await executeCompositePlan(plan, harness.deps);
+
+    expect(harness.encodeSurface).toHaveBeenCalledTimes(1);
+    expect(harness.uploadImage).toHaveBeenCalledTimes(1);
+    expect(result.base.imageName).toBe('uploaded-1');
+    expect(result.base.reusedUpload).toBe(false);
+  });
+
+  it('re-running the same plan skips compositing, encoding and upload entirely', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    const plan = planComposites(makeDoc([rasterLayer('a')]), BBOX);
+
+    await executeCompositePlan(plan, harness.deps);
+    harness.createdTargets.length = 0;
+    const second = await executeCompositePlan(plan, harness.deps);
+
+    // No new composite target, no new encode, no new upload.
+    expect(harness.createdTargets).toHaveLength(0);
+    expect(harness.encodeSurface).toHaveBeenCalledTimes(1);
+    expect(harness.uploadImage).toHaveBeenCalledTimes(1);
+    expect(second.base.reusedUpload).toBe(true);
+    expect(second.base.imageName).toBe('uploaded-1');
+  });
+
+  it('a changed plan with identical pixels re-composites but reuses the upload by content hash', async () => {
+    const harness = makeHarness(() => uniformImageData(100, 100, 255));
+    const planA = planComposites(makeDoc([rasterLayer('a', { opacity: 1 })]), BBOX);
+    const planB = planComposites(makeDoc([rasterLayer('a', { opacity: 0.5 })]), BBOX);
+    expect(planA.entries[0]!.key).not.toBe(planB.entries[0]!.key);
+
+    await executeCompositePlan(planA, harness.deps);
+    const resultB = await executeCompositePlan(planB, harness.deps);
+
+    // The changed plan re-composites + re-encodes (same-size stub blob → same hash)...
+    expect(harness.encodeSurface).toHaveBeenCalledTimes(2);
+    // ...but the identical pixel hash means no second upload.
+    expect(harness.uploadImage).toHaveBeenCalledTimes(1);
+    expect(resultB.base.reusedUpload).toBe(true);
+    expect(resultB.base.imageName).toBe('uploaded-1');
+  });
+});
+
+// ---- Grayscale mask composite ---------------------------------------------
+
+const inpaintMask = (
+  id: string,
+  overrides: Partial<{ denoiseLimit: number; noiseLevel: number }> = {}
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  denoiseLimit: overrides.denoiseLimit,
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: imageRef(`${id}-bmp`, 64, 48), fill: { color: '#ff0000', style: 'solid' } },
+  name: id,
+  noiseLevel: overrides.noiseLevel,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+const maskEntryOf = (doc: CanvasDocumentContractV2) =>
+  planComposites(doc, BBOX).entries.find((e) => e.kind === 'inpaint-mask')!;
+
+/** A grayscale ImageData that is uniformly white or has a single dark pixel. */
+const grayImageData = (width: number, height: number, hasDark: boolean): ImageData => {
+  const data = new Uint8ClampedArray(width * height * 4);
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = 255;
+    data[i + 1] = 255;
+    data[i + 2] = 255;
+    data[i + 3] = 255;
+  }
+  if (hasDark) {
+    data[0] = 0;
+  }
+  return { colorSpace: 'srgb', data, height, width } as unknown as ImageData;
+};
+
+describe('toGrayscaleMaskPixels', () => {
+  const pixel = (alpha: number): ImageData => {
+    const data = new Uint8ClampedArray([120, 130, 140, alpha]);
+    return { colorSpace: 'srgb', data, height: 1, width: 1 } as unknown as ImageData;
+  };
+
+  it('turns a masked pixel dark by the attribute value (1.0 → black)', () => {
+    const img = pixel(255);
+    toGrayscaleMaskPixels(img, 1);
+    expect(Array.from(img.data)).toEqual([0, 0, 0, 255]);
+  });
+
+  it('turns a masked pixel mid-gray at partial strength', () => {
+    const img = pixel(255);
+    toGrayscaleMaskPixels(img, 0.5);
+    // 255 - round(255 * 0.5) = 255 - 128 = 127
+    expect(Array.from(img.data)).toEqual([127, 127, 127, 255]);
+  });
+
+  it('leaves an unmasked (transparent) pixel white', () => {
+    const img = pixel(0);
+    toGrayscaleMaskPixels(img, 1);
+    expect(Array.from(img.data)).toEqual([255, 255, 255, 255]);
+  });
+});
+
+describe('executeMaskComposite', () => {
+  it('composites mask layers onto a white bbox surface and uploads the result', async () => {
+    const harness = makeHarness(() => grayImageData(100, 100, true));
+    const entry = maskEntryOf(makeDoc([inpaintMask('m1')]));
+
+    const result = await executeMaskComposite(entry, harness.deps);
+
+    // White background fill + one mask draw.
+    const target = harness.createdTargets[0]!;
+    const fills = target.callLog.filter((e) => e.op === 'set' && e.args[0] === 'fillStyle');
+    expect(fills.map((e) => e.args[1])).toContain('white');
+    expect(harness.uploadImage).toHaveBeenCalledTimes(1);
+    expect(result.imageName).toBe('uploaded-1');
+    expect(result.hasContent).toBe(true);
+  });
+
+  it('reports no content when the composite is fully white', async () => {
+    const harness = makeHarness(() => grayImageData(100, 100, false));
+    const entry = maskEntryOf(makeDoc([inpaintMask('m1')]));
+    const result = await executeMaskComposite(entry, harness.deps);
+    expect(result.hasContent).toBe(false);
+  });
+
+  it('dedupes a repeated mask plan key with no second upload', async () => {
+    const harness = makeHarness(() => grayImageData(100, 100, true));
+    const doc = makeDoc([inpaintMask('m1', { denoiseLimit: 0.5 })]);
+
+    const first = await executeMaskComposite(maskEntryOf(doc), harness.deps);
+    const second = await executeMaskComposite(maskEntryOf(doc), harness.deps);
+
+    expect(harness.uploadImage).toHaveBeenCalledTimes(1);
+    expect(second.reusedUpload).toBe(true);
+    expect(second.imageName).toBe(first.imageName);
+    expect(second.hasContent).toBe(true);
+  });
+
+  it('darken-composites multiple mask layers', async () => {
+    const harness = makeHarness(() => grayImageData(100, 100, true));
+    const entry = maskEntryOf(makeDoc([inpaintMask('a'), inpaintMask('b')]));
+
+    await executeMaskComposite(entry, harness.deps);
+
+    const target = harness.createdTargets[0]!;
+    const composites = target.callLog
+      .filter((e) => e.op === 'set' && e.args[0] === 'globalCompositeOperation')
+      .map((e) => e.args[1]);
+    expect(composites).toContain('darken');
+  });
+});
+
+describe('executeCompositePlan — raster adjustments baked into generation pixels', () => {
+  it('reads + writes the adjusted layer pixels (bake) and NOT for a plain layer', async () => {
+    const writeImageData = vi.fn();
+    const readImageData = vi.fn((_surface: RasterSurface, rect: Rect) =>
+      uniformImageData(rect.width, rect.height, 255)
+    );
+    const harness = makeHarness(readImageData);
+    harness.deps.writeImageData = writeImageData;
+
+    // Plain layer: no adjustments → no bake write beyond the coverage scan writes (none here).
+    const plainDoc = makeDoc([rasterLayer('a')]);
+    await executeCompositePlan(planComposites(plainDoc, BBOX), harness.deps);
+    expect(writeImageData).not.toHaveBeenCalled();
+
+    // Adjusted layer: brightness bake → the executor reads the temp, applies the
+    // LUT, and writes the adjusted pixels back before compositing.
+    const adjustedDoc = makeDoc([rasterLayer('b', { adjustments: { brightness: 0.5, contrast: 0, saturation: 0 } })]);
+    await executeCompositePlan(planComposites(adjustedDoc, BBOX), harness.deps);
+    expect(writeImageData).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/compositeForGeneration.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/compositeForGeneration.ts
new file mode 100644
index 00000000000..ac31136540c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/compositeForGeneration.ts
@@ -0,0 +1,491 @@
+/**
+ * The composite-plan executor: turns a {@link CompositePlan} into an uploaded,
+ * bbox-sized base image plus the geometry the mode detector needs.
+ *
+ * This is the impure half of the canvas → generation pipeline (the planner in
+ * `generation/canvas/compositePlan.ts` is pure). It lives under `canvas-engine`
+ * and has zero React: every side-effecting dependency (surface allocation,
+ * layer rasterization, encode, hash, upload) is injected, so it runs in node
+ * tests against `render/raster.testStub.ts` + a mock uploader — no fetch, no DOM.
+ *
+ * For each `base-raster` entry it:
+ * 1. Composites the entry's enabled raster layers, in z-order, through each
+ *    layer's transform / opacity / blend mode, cropped to the bbox onto a
+ *    bbox-sized surface (following `render/compositor.ts`'s draw model, where
+ *    the "view" is a bbox translate). Layers are rasterized on demand via the
+ *    injected {@link ExecuteCompositePlanDeps.getLayerSurface}.
+ * 2. Computes `contentBounds` (union of the entry's layer bounds in document
+ *    space) and `bboxFullyCovered` (an alpha scan of the composited surface).
+ * 3. Encodes → PNG blob → SHA-256, then dedupes: an unchanged plan key reuses
+ *    the previous upload with zero new work, and a changed plan whose pixels
+ *    hash identically reuses the previous upload via the content hash.
+ *
+ * Dedupe state lives in a caller-owned {@link CompositeDedupeCache} passed
+ * through `deps`, so it persists across invokes while the function stays a plain
+ * `(plan, deps) → result`.
+ */
+
+import type { CanvasImageUploadResult } from '@workbench/canvas-engine/document/imageUpload';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Mat2d, Rect } from '@workbench/canvas-engine/types';
+import type { CompositeEntry, CompositeMaskLayerRef, CompositePlan } from '@workbench/generation/canvas/types';
+
+import { fromTRS, multiply } from '@workbench/canvas-engine/math/mat2d';
+import { renderRasterComposite } from '@workbench/canvas-engine/render/rasterComposite';
+import { getCompositeLayerBounds } from '@workbench/generation/canvas/compositePlan';
+
+type Ctx = RasterSurface['ctx'];
+
+/** SHA-256 hex of a blob's bytes, via the Web Crypto API (matches `bitmapStore`). */
+const defaultHashBlob = async (blob: Blob): Promise<string> => {
+  const buffer = await blob.arrayBuffer();
+  const digest = await crypto.subtle.digest('SHA-256', buffer);
+  const bytes = new Uint8Array(digest);
+  let hex = '';
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, '0');
+  }
+  return hex;
+};
+
+/** Reads a surface's pixels via its 2D context (real DOM path; injectable for tests). */
+const defaultReadImageData = (surface: RasterSurface, rect: Rect): ImageData =>
+  surface.ctx.getImageData(rect.x, rect.y, rect.width, rect.height);
+
+/** Writes pixels back to a surface's 2D context (real DOM path; injectable for tests). */
+const defaultWriteImageData = (surface: RasterSurface, imageData: ImageData, x: number, y: number): void =>
+  surface.ctx.putImageData(imageData, x, y);
+
+/**
+ * A caller-owned dedupe cache, persisted across executor calls:
+ * - `byKey`: plan key → its last result, so an unchanged plan skips all work.
+ * - `byHash`: pixel hash → uploaded image, so a changed plan with identical
+ *   pixels reuses the upload.
+ */
+export interface CompositeDedupeCache {
+  byKey: Map<string, CompositeCacheEntry>;
+  byHash: Map<string, CanvasImageUploadResult>;
+}
+
+/** A cached executor result for one plan key. */
+export interface CompositeCacheEntry {
+  imageName: string;
+  width: number;
+  height: number;
+  pixelHash: string;
+  bboxFullyCovered: boolean;
+}
+
+/** Creates an empty {@link CompositeDedupeCache}. */
+export const createCompositeDedupeCache = (): CompositeDedupeCache => ({
+  byHash: new Map(),
+  byKey: new Map(),
+});
+
+/** Injected dependencies for {@link executeCompositePlan}. */
+export interface ExecuteCompositePlanDeps {
+  /** Surface factory + encoder seam (usually the engine's `RasterBackend`). */
+  backend: {
+    createSurface(width: number, height: number): RasterSurface;
+    encodeSurface(surface: RasterSurface, type?: string): Promise<Blob>;
+  };
+  /**
+   * Ensures a layer's cache is rasterized and returns its surface plus the
+   * content `rect` (layer-local origin/size) those pixels occupy. The executor
+   * draws the surface at `rect.origin` (then through the layer transform). The
+   * engine wires this to its rasterize path; tests return a stub.
+   */
+  getLayerSurface(layerId: string): Promise<{ surface: RasterSurface; rect: Rect }>;
+  /**
+   * Uploads a composited blob and resolves to its server image name + dims. The
+   * engine wires this to `uploadCanvasImage(blob, { isIntermediate: true })`.
+   */
+  uploadImage(blob: Blob): Promise<CanvasImageUploadResult>;
+  /** Persistent dedupe state (see {@link CompositeDedupeCache}). */
+  dedupe: CompositeDedupeCache;
+  /** Content-hashes a blob (default SHA-256 hex via `crypto.subtle`). */
+  hashBlob?(blob: Blob): Promise<string>;
+  /** Reads a surface region's pixels for the coverage scan (default `getImageData`). */
+  readImageData?(surface: RasterSurface, rect: Rect): ImageData;
+  /** Reserves transient raster bytes for the complete composite operation. */
+  reserve?(
+    bytes: number
+  ):
+    | { status: 'ok'; lease: { release(): void } }
+    | { status: 'over-budget'; requestedBytes: number; availableBytes: number };
+  /** Writes pixels back to a surface (default `putImageData`; injectable for tests). */
+  writeImageData?(surface: RasterSurface, imageData: ImageData, x: number, y: number): void;
+}
+
+export class CompositeOverBudgetError extends Error {
+  constructor() {
+    super('The canvas composite exceeds the available raster memory budget.');
+    this.name = 'CompositeOverBudgetError';
+  }
+}
+
+const reserveComposite = (
+  entry: CompositeEntry,
+  deps: ExecuteCompositePlanDeps,
+  layerCount: number
+): { release(): void } => {
+  const pixels = Math.max(0, entry.bbox.width) * Math.max(0, entry.bbox.height);
+  // Final/accumulator surface + final scan ImageData, plus one temporary
+  // surface and one ImageData buffer for every adjusted/mask layer.
+  const reservation = deps.reserve?.(pixels * 4 * (2 + layerCount * 2));
+  if (reservation?.status === 'over-budget') {
+    throw new CompositeOverBudgetError();
+  }
+  return reservation?.status === 'ok' ? reservation.lease : { release: () => undefined };
+};
+
+/** The base composite's upload identity + hash. */
+export interface CompositeEntryResult {
+  /** The entry's stable plan key. */
+  key: string;
+  /** The uploaded (or reused) image name. */
+  imageName: string;
+  width: number;
+  height: number;
+  /** SHA-256 of the composited PNG bytes. */
+  pixelHash: string;
+  /** True when this result came from cache/dedupe (no upload happened this call). */
+  reusedUpload: boolean;
+}
+
+/** The full result of executing a plan: the base image + mode-detection geometry. */
+export interface CompositeResult {
+  base: CompositeEntryResult;
+  /** Union of enabled raster content bounds in document space, or `null`. */
+  contentBounds: Rect | null;
+  /** Whether the composited bbox surface is fully opaque (no transparent holes). */
+  bboxFullyCovered: boolean;
+}
+
+/** Document→bbox translate matrix (the "view" the entry is composited under). */
+const bboxView = (bbox: Rect): Mat2d => ({ a: 1, b: 0, c: 0, d: 1, e: -bbox.x, f: -bbox.y });
+
+/** Applies a matrix to a 2D context's transform. */
+const setTransform = (ctx: Ctx, m: Mat2d): void => {
+  ctx.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
+};
+
+/**
+ * Union of a plan's base-raster content bounds in document space, or `null`
+ * when the plan has no enabled raster content. Pure geometry (no pixels, no
+ * upload), so the invoke orchestrator can run it as a bounds-only pre-pass to
+ * decide txt2img (no bbox overlap) *before* paying for a composite/encode/upload.
+ */
+export const computeCompositeContentBounds = (plan: CompositePlan): Rect | null => {
+  const entry = plan.entries.find((e) => e.kind === 'base-raster');
+  return entry ? getCompositeLayerBounds(entry.layers) : null;
+};
+
+/** True when every pixel of `imageData` is fully opaque (alpha === 255). Empty → false. */
+const isFullyOpaque = (imageData: ImageData): boolean => {
+  const { data, height, width } = imageData;
+  if (width <= 0 || height <= 0) {
+    return false;
+  }
+  for (let i = 3; i < data.length; i += 4) {
+    if (data[i] < 255) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Composites, scans coverage, encodes, hashes, dedupes, and (when needed)
+ * uploads a single raster-style entry (`base-raster` or `control-layer`).
+ * Shared by {@link executeCompositePlan} and {@link executeControlComposite} so
+ * both go through the identical plan-key + content-hash dedupe path.
+ */
+const executeRasterEntry = async (
+  entry: CompositeEntry,
+  deps: ExecuteCompositePlanDeps
+): Promise<CompositeEntryResult & { bboxFullyCovered: boolean }> => {
+  const hashBlob = deps.hashBlob ?? defaultHashBlob;
+  const readImageData = deps.readImageData ?? defaultReadImageData;
+
+  // Plan-key hit: nothing that affects these pixels changed — reuse everything,
+  // no composite, no encode, no upload.
+  const cached = deps.dedupe.byKey.get(entry.key);
+  if (cached) {
+    return {
+      bboxFullyCovered: cached.bboxFullyCovered,
+      height: cached.height,
+      imageName: cached.imageName,
+      key: entry.key,
+      pixelHash: cached.pixelHash,
+      reusedUpload: true,
+      width: cached.width,
+    };
+  }
+
+  const reservation = reserveComposite(
+    entry,
+    deps,
+    entry.layers.filter((layer) => layer.adjustments !== undefined).length
+  );
+  try {
+    const surface = await renderRasterComposite(entry, deps);
+    const bboxFullyCovered = isFullyOpaque(
+      readImageData(surface, { height: surface.height, width: surface.width, x: 0, y: 0 })
+    );
+
+    const blob = await deps.backend.encodeSurface(surface);
+    const pixelHash = await hashBlob(blob);
+
+    // Content-hash dedupe: identical pixels (even under a different key) reuse the
+    // already-uploaded image — no second upload.
+    let upload = deps.dedupe.byHash.get(pixelHash);
+    let reusedUpload = true;
+    if (!upload) {
+      upload = await deps.uploadImage(blob);
+      deps.dedupe.byHash.set(pixelHash, upload);
+      reusedUpload = false;
+    }
+
+    deps.dedupe.byKey.set(entry.key, {
+      bboxFullyCovered,
+      height: upload.height,
+      imageName: upload.imageName,
+      pixelHash,
+      width: upload.width,
+    });
+
+    return {
+      bboxFullyCovered,
+      height: upload.height,
+      imageName: upload.imageName,
+      key: entry.key,
+      pixelHash,
+      reusedUpload,
+      width: upload.width,
+    };
+  } finally {
+    reservation.release();
+  }
+};
+
+/**
+ * Executes `plan`'s base-raster composite: composites, scans coverage, encodes,
+ * dedupes, and (when needed) uploads. Returns the base image identity plus the
+ * `contentBounds` / `bboxFullyCovered` facts the mode detector consumes.
+ */
+export const executeCompositePlan = async (
+  plan: CompositePlan,
+  deps: ExecuteCompositePlanDeps
+): Promise<CompositeResult> => {
+  const entry = plan.entries.find((e) => e.kind === 'base-raster');
+  if (!entry) {
+    throw new Error('executeCompositePlan: plan has no base-raster entry');
+  }
+
+  const contentBounds = getCompositeLayerBounds(entry.layers);
+  const { bboxFullyCovered, ...base } = await executeRasterEntry(entry, deps);
+
+  return { base, bboxFullyCovered, contentBounds };
+};
+
+/**
+ * Executes a single `control-layer` composite entry (one enabled control layer,
+ * composited alone over the bbox). Reuses the same dedupe cache as the base
+ * composite, so an unchanged control layer skips re-upload across invokes.
+ */
+export const executeControlComposite = async (
+  entry: CompositeEntry,
+  deps: ExecuteCompositePlanDeps
+): Promise<CompositeEntryResult> => {
+  const { bboxFullyCovered: _bboxFullyCovered, ...result } = await executeRasterEntry(entry, deps);
+  return result;
+};
+
+/**
+ * Executes a single `regional-mask` composite entry (one enabled regional-guidance
+ * layer's mask, composited alone over the bbox with its alpha preserved). The
+ * uploaded image's alpha channel is the region coverage, consumed by
+ * `alpha_mask_to_tensor`. Reuses the same dedupe cache + raster path as the base
+ * / control composites, so an unchanged region mask skips re-upload.
+ */
+export const executeRegionalMaskComposite = async (
+  entry: CompositeEntry,
+  deps: ExecuteCompositePlanDeps
+): Promise<CompositeEntryResult> => {
+  const { bboxFullyCovered: _bboxFullyCovered, ...result } = await executeRasterEntry(entry, deps);
+  return result;
+};
+
+// ---- Grayscale mask composite (inpaint/outpaint) ---------------------------
+
+/**
+ * Converts a mask layer's alpha into legacy grayscale, in place: a masked pixel
+ * (alpha > 127) becomes `255 - round(255 * attributeValue)` (black at full
+ * strength), an unmasked pixel becomes white (255); alpha is forced opaque. This
+ * mirrors `getGrayscaleMaskCompositeImageDTO`'s per-pixel step so multiple masks
+ * can be darken-composited over a white background (dark = inpaint, white = keep).
+ */
+export const toGrayscaleMaskPixels = (imageData: ImageData, attributeValue: number): void => {
+  const { data } = imageData;
+  const masked = Math.max(0, Math.min(255, 255 - Math.round(255 * attributeValue)));
+  for (let i = 0; i + 3 < data.length; i += 4) {
+    const gray = (data[i + 3] ?? 0) > 127 ? masked : 255;
+    data[i] = gray;
+    data[i + 1] = gray;
+    data[i + 2] = gray;
+    data[i + 3] = 255;
+  }
+};
+
+/** The local→document transform matrix for a mask layer ref. */
+const maskLayerMatrix = (ref: CompositeMaskLayerRef): Mat2d =>
+  fromTRS(
+    { x: ref.transform.x, y: ref.transform.y },
+    ref.transform.rotation,
+    ref.transform.scaleX,
+    ref.transform.scaleY
+  );
+
+/** True when any pixel is non-white (a masked region exists). Empty → false. */
+const hasNonWhitePixel = (imageData: ImageData): boolean => {
+  const { data, height, width } = imageData;
+  if (width <= 0 || height <= 0) {
+    return false;
+  }
+  for (let i = 0; i + 3 < data.length; i += 4) {
+    if ((data[i] ?? 255) < 255) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/** The result of a grayscale mask composite: its upload identity + whether it has any masked pixels. */
+export interface MaskCompositeResult {
+  key: string;
+  imageName: string;
+  width: number;
+  height: number;
+  pixelHash: string;
+  reusedUpload: boolean;
+  /** True when the composite contains a masked (non-white) region within the bbox. */
+  hasContent: boolean;
+}
+
+/** Composites one mask entry's layers into a grayscale bbox surface (white bg, darken combine). */
+const compositeMaskEntry = async (
+  entry: CompositeEntry,
+  deps: ExecuteCompositePlanDeps,
+  writeImageData: (surface: RasterSurface, imageData: ImageData, x: number, y: number) => void,
+  readImageData: (surface: RasterSurface, rect: Rect) => ImageData
+): Promise<RasterSurface> => {
+  const { bbox } = entry;
+  const maskLayers = entry.maskLayers ?? [];
+  const width = Math.max(0, bbox.width);
+  const height = Math.max(0, bbox.height);
+  const accumulator = deps.backend.createSurface(width, height);
+  const accCtx = accumulator.ctx;
+
+  // White background: unmasked area stays white ("keep").
+  setTransform(accCtx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+  accCtx.fillStyle = 'white';
+  accCtx.fillRect(0, 0, width, height);
+
+  const view = bboxView(bbox);
+  const fullRect: Rect = { height, width, x: 0, y: 0 };
+
+  for (const ref of maskLayers) {
+    // Render the mask alpha into a temp bbox surface through its transform.
+    const temp = deps.backend.createSurface(width, height);
+    const tempCtx = temp.ctx;
+    setTransform(tempCtx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+    tempCtx.clearRect(0, 0, width, height);
+    const layerSurface = await deps.getLayerSurface(ref.id);
+    setTransform(tempCtx, multiply(view, maskLayerMatrix(ref)));
+    tempCtx.drawImage(layerSurface.surface.canvas, layerSurface.rect.x, layerSurface.rect.y);
+
+    // Convert its alpha to grayscale by the layer's attribute value.
+    const pixels = readImageData(temp, fullRect);
+    toGrayscaleMaskPixels(pixels, ref.attributeValue);
+    writeImageData(temp, pixels, 0, 0);
+
+    // Darken-combine onto the accumulator (min per channel), matching legacy.
+    setTransform(accCtx, { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+    accCtx.globalAlpha = 1;
+    accCtx.globalCompositeOperation = 'darken';
+    accCtx.drawImage(temp.canvas, 0, 0);
+  }
+
+  accCtx.globalCompositeOperation = 'source-over';
+  return accumulator;
+};
+
+/**
+ * Executes a grayscale mask composite entry (`inpaint-mask` / `noise-mask`):
+ * composites the mask layers into a white-backed grayscale image, scans whether
+ * any masked region exists, then encodes / dedupes / uploads exactly like the
+ * base composite. Content-hash + plan-key dedupe reuse the same caller-owned
+ * cache so an unchanged mask skips re-upload.
+ */
+export const executeMaskComposite = async (
+  entry: CompositeEntry,
+  deps: ExecuteCompositePlanDeps
+): Promise<MaskCompositeResult> => {
+  const hashBlob = deps.hashBlob ?? defaultHashBlob;
+  const readImageData = deps.readImageData ?? defaultReadImageData;
+  const writeImageData = deps.writeImageData ?? defaultWriteImageData;
+
+  const cached = deps.dedupe.byKey.get(entry.key);
+  if (cached) {
+    return {
+      hasContent: cached.bboxFullyCovered,
+      height: cached.height,
+      imageName: cached.imageName,
+      key: entry.key,
+      pixelHash: cached.pixelHash,
+      reusedUpload: true,
+      width: cached.width,
+    };
+  }
+
+  const reservation = reserveComposite(entry, deps, entry.maskLayers?.length ?? 0);
+  try {
+    const surface = await compositeMaskEntry(entry, deps, writeImageData, readImageData);
+    const hasContent = hasNonWhitePixel(
+      readImageData(surface, { height: surface.height, width: surface.width, x: 0, y: 0 })
+    );
+
+    const blob = await deps.backend.encodeSurface(surface);
+    const pixelHash = await hashBlob(blob);
+
+    let upload = deps.dedupe.byHash.get(pixelHash);
+    let reusedUpload = true;
+    if (!upload) {
+      upload = await deps.uploadImage(blob);
+      deps.dedupe.byHash.set(pixelHash, upload);
+      reusedUpload = false;
+    }
+
+    // Reuse the `bboxFullyCovered` slot to persist `hasContent` for this key.
+    deps.dedupe.byKey.set(entry.key, {
+      bboxFullyCovered: hasContent,
+      height: upload.height,
+      imageName: upload.imageName,
+      pixelHash,
+      width: upload.width,
+    });
+
+    return {
+      hasContent,
+      height: upload.height,
+      imageName: upload.imageName,
+      key: entry.key,
+      pixelHash,
+      reusedUpload,
+      width: upload.width,
+    };
+  } finally {
+    reservation.release();
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/contracts.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/contracts.ts
new file mode 100644
index 00000000000..34ba5a4ad64
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/contracts.ts
@@ -0,0 +1,364 @@
+import type {
+  CommitGeneratedImageResult,
+  LayerExportGuard,
+  ReplaceSelectionFromImageResult,
+} from '@workbench/canvas-engine/api';
+import type { CommitRasterFilterResult } from '@workbench/canvas-engine/controllers/filterResultController';
+import type {
+  CommitMaskImageResult,
+  MaskImageResultTarget,
+} from '@workbench/canvas-engine/controllers/maskResultController';
+import type { CanvasEditGate } from '@workbench/canvas-engine/editGate';
+export type { CanvasCompositeExecutorDeps } from '@workbench/canvas-engine/api';
+import type { ExportBakedLayerBlobResult, ExportLayerPixelsResult } from '@workbench/canvas-engine/engine';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type {
+  FilterCommitTarget,
+  FilterOperationSessionState,
+  LayerFilterSettings,
+  SamInput,
+  SamModel,
+  SamSessionError,
+  SamSessionSnapshot,
+} from '@workbench/canvas-operations/operationTypes';
+import type { BackendGraphContract, CanvasDocumentContractV2, CanvasImageRef, WorkbenchState } from '@workbench/types';
+
+export type StartSelectObjectSessionResult =
+  | 'started'
+  | 'missing'
+  | 'disabled'
+  | 'locked'
+  | 'unsupported'
+  | 'not-ready';
+export type StartFilterOperationResult = 'started' | 'missing' | 'disabled' | 'locked' | 'unsupported' | 'not-ready';
+export type CanvasOperationActionResult = 'completed' | 'blocked' | 'stale';
+export type FilterCommitOperationResult = 'committed' | 'blocked' | 'stale';
+export type CanvasOperationMutationResult = 'updated' | 'blocked' | 'stale';
+export type SelectObjectSaveTarget = 'selection' | 'raster' | 'control' | MaskImageResultTarget;
+export type SaveSelectObjectSessionResult =
+  | CommitGeneratedImageResult
+  | CommitMaskImageResult
+  | ReplaceSelectionFromImageResult;
+export interface SelectObjectSessionUpdate {
+  input?: SamInput;
+  pointLabel?: 'include' | 'exclude';
+  model?: SamModel;
+  invert?: boolean;
+  applyPolygonRefinement?: boolean;
+  autoProcess?: boolean;
+  isolatedPreview?: boolean;
+}
+
+export type CanvasOperationIdentity =
+  | { kind: 'select-object'; projectId: string; layerId: string }
+  | { kind: 'filter'; projectId: string; layerId: string };
+export type CanvasOperationState =
+  | { status: 'idle' }
+  | { status: 'active'; identity: CanvasOperationIdentity; phase: 'ready' | 'running' | 'error'; error: string | null };
+export type CanvasOperationRunResult = 'published' | 'stale' | 'error';
+export interface CanvasOperationSession {
+  run<T>(
+    work: (signal: AbortSignal) => Promise<T>,
+    commitPreview: (result: T) => undefined
+  ): Promise<CanvasOperationRunResult>;
+  reset(): void;
+  interruptProcessing(): void;
+  cancel(): void;
+}
+export interface CanvasOperationController {
+  getSnapshot(): CanvasOperationState;
+  subscribe(listener: () => void): () => void;
+  start(options: {
+    identity: CanvasOperationIdentity;
+    guard: LayerExportGuard;
+    cleanupPreview(): void;
+  }): CanvasOperationSession | null;
+  reset(): void;
+  cancel(): void;
+  invalidateSource(projectId: string, layerId: string): void;
+  invalidateLayer(projectId: string, layerId: string): void;
+  invalidateProject(projectId: string): void;
+  invalidateDocument(projectId: string): void;
+  dispose(): void;
+}
+
+export interface CanvasApplicationScalarStore<T> {
+  get(): T;
+  set(value: T): void;
+  subscribe(listener: () => void): () => void;
+}
+
+export interface CanvasApplicationOperationStores {
+  readonly filterSession: CanvasApplicationScalarStore<FilterOperationSessionState | null>;
+  readonly samSession: CanvasApplicationScalarStore<SamSessionSnapshot | null>;
+}
+
+export interface CanvasFilterCoordinatorDeps {
+  readonly stores: CanvasApplicationOperationStores;
+  readonly controller: CanvasOperationController;
+  isInteractionLocked(): boolean;
+  getDocument(): CanvasDocumentContractV2 | null;
+  captureGuard(layerId: string): LayerExportGuard | null;
+  selectLayer(layerId: string): void;
+  clearOtherOperation(): void;
+  clearPreview(layerId: string): void;
+  setViewTool(): void;
+  encodeSurface(surface: RasterSurface): Promise<Blob>;
+  runFilterGraph(options: {
+    graph: BackendGraphContract;
+    outputNodeId?: string;
+    signal?: AbortSignal;
+  }): Promise<{ height: number; imageName: string; width: number }>;
+  uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ imageName: string }>;
+  createSession?(options: CreateFilterSessionOptions): FilterOperationSession | null;
+  getSessionDeps(
+    layerId: string
+  ): Omit<
+    CreateFilterSessionOptions['deps'],
+    'canCommit' | 'clearPreview' | 'controller' | 'isDraftValid' | 'makeDurable' | 'runFilter'
+  >;
+}
+
+export interface CanvasFilterOperationCoordinator {
+  start(layerId: string, recommendedFilterType?: string | null): StartFilterOperationResult;
+  updateDraft(draft: LayerFilterSettings): CanvasOperationMutationResult;
+  setAutoProcess(value: boolean): CanvasOperationMutationResult;
+  process(): Promise<CanvasOperationActionResult>;
+  reset(settings: Record<string, unknown>): CanvasOperationMutationResult;
+  commit(
+    target: FilterCommitTarget,
+    makeImageDurable: (imageName: string) => Promise<void>
+  ): Promise<FilterCommitOperationResult>;
+  cancel(): void;
+  interruptAndBlock(): void;
+  isActive(): boolean;
+  dispose(): void;
+}
+
+export type SelectObjectStartContext =
+  | { status: Exclude<StartSelectObjectSessionResult, 'started'> }
+  | {
+      status: 'ready';
+      guard: LayerExportGuard;
+      layerId: string;
+      layerName: string;
+      layerType: 'raster' | 'control';
+      sourceRect: Rect;
+    };
+
+export interface CanvasSelectObjectCoordinatorDeps {
+  readonly stores: CanvasApplicationOperationStores;
+  readonly controller: CanvasOperationController;
+  readonly projectId: string;
+  isInteractionLocked(): boolean;
+  prepareStart(layerId: string): SelectObjectStartContext;
+  selectLayer(layerId: string): void;
+  clearOtherOperation(): void;
+  setSamTool(): void;
+  setViewTool(): void;
+  replaceTemporaryRestoreTool(): void;
+  isSamToolActive(): boolean;
+  captureGuard(layerId: string): LayerExportGuard | null;
+  isGuardCurrent(guard: LayerExportGuard): boolean;
+  exportSource(layerId: string): Promise<ExportBakedLayerBlobResult>;
+  uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ height: number; imageName: string; width: number }>;
+  runGraph(options: {
+    graph: BackendGraphContract;
+    outputNodeId?: string;
+    signal?: AbortSignal;
+  }): Promise<CanvasUtilityGraphResult>;
+  decodePreview(result: SelectObjectReadyResult, signal: AbortSignal): Promise<RasterSurface>;
+  publishPreview(preview: SelectObjectSessionPreview<RasterSurface>): void;
+  clearPreview(): void;
+  invalidateOverlay(): void;
+  commitGenerated(
+    preview: SelectObjectSessionPreview<RasterSurface>,
+    options: { mode: 'replace' | 'copy-raster' | 'copy-control'; signal: AbortSignal }
+  ): Promise<CommitGeneratedImageResult>;
+  commitMask(
+    preview: SelectObjectSessionPreview<RasterSurface>,
+    target: MaskImageResultTarget,
+    signal: AbortSignal
+  ): Promise<CommitMaskImageResult>;
+  replaceSelection(
+    preview: SelectObjectSessionPreview<RasterSurface>,
+    signal: AbortSignal
+  ): Promise<ReplaceSelectionFromImageResult>;
+  createSession?(options: CreateSelectObjectSessionOptions<RasterSurface>): SelectObjectSession<RasterSurface>;
+}
+
+export interface CanvasSelectObjectOperationCoordinator {
+  start(layerId: string): StartSelectObjectSessionResult;
+  update(changes: SelectObjectSessionUpdate): CanvasOperationMutationResult;
+  process(): Promise<SelectObjectSessionProcessResult>;
+  apply(makeImageDurable: (imageName: string) => Promise<void>): Promise<CommitGeneratedImageResult>;
+  save(
+    target: SelectObjectSaveTarget,
+    makeImageDurable: (imageName: string) => Promise<void>
+  ): Promise<SaveSelectObjectSessionResult>;
+  reset(): CanvasOperationMutationResult;
+  cancel(): void;
+  interruptAndBlock(): void;
+  isActive(): boolean;
+  dispose(): void;
+}
+
+export interface FilterOperationSession {
+  getSnapshot(): FilterOperationSessionState;
+  subscribe(listener: () => void): () => void;
+  updateDraft(draft: LayerFilterSettings): void;
+  setAutoProcess(value: boolean): void;
+  process(): Promise<CanvasOperationRunResult>;
+  interruptProcessing(): void;
+  reset(settings: Record<string, unknown>): void;
+  commit(target: FilterCommitTarget): Promise<'committed' | 'blocked' | 'stale'>;
+  blockCommit(): void;
+  cancel(): void;
+  dispose(): void;
+}
+
+export type SelectObjectSessionStatus =
+  | 'ready'
+  | 'scheduled'
+  | 'preparing-source'
+  | 'uploading'
+  | 'processing-sam'
+  | 'rendering-preview'
+  | 'error';
+export interface SelectObjectSessionPreview<T> {
+  data: T;
+  guard: LayerExportGuard;
+  image: CanvasImageRef;
+  inputHash: string;
+  previewId: number;
+  isolated: boolean;
+  rect: Rect;
+  sourceImageName: string;
+}
+export interface SelectObjectSessionState<T> {
+  input: SamInput;
+  model: SamModel;
+  invert: boolean;
+  applyPolygonRefinement: boolean;
+  autoProcess: boolean;
+  isolatedPreview: boolean;
+  status: SelectObjectSessionStatus;
+  error: SamSessionError | null;
+  preview: SelectObjectSessionPreview<T> | null;
+  sourceGuard: LayerExportGuard | null;
+}
+export type SelectObjectSessionProcessResult = CanvasOperationRunResult | 'blocked' | 'deduped' | 'invalid';
+export interface SelectObjectSession<T> {
+  getSnapshot(): SelectObjectSessionState<T>;
+  subscribe(listener: () => void): () => void;
+  update(
+    changes: Partial<
+      Pick<
+        SelectObjectSessionState<T>,
+        'applyPolygonRefinement' | 'autoProcess' | 'input' | 'invert' | 'isolatedPreview' | 'model'
+      >
+    >
+  ): void;
+  process(): Promise<SelectObjectSessionProcessResult>;
+  interruptProcessing(): void;
+  reportError(error: SamSessionError | string): void;
+  reset(): void;
+  cancel(): void;
+  dispose(): void;
+}
+
+export interface CanvasUtilityGraphResult {
+  imageName: string;
+  width: number;
+  height: number;
+}
+export interface LayerFilterResult {
+  imageName: string;
+  width: number;
+  height: number;
+  origin: { x: number; y: number };
+}
+
+export interface CreateFilterSessionOptions {
+  deps: {
+    controller: CanvasOperationController;
+    exportPixels(): Promise<ExportLayerPixelsResult>;
+    runFilter(options: {
+      filterType: string;
+      input: { surface: RasterSurface; rect: Rect };
+      settings: Record<string, unknown>;
+      signal: AbortSignal;
+    }): Promise<LayerFilterResult>;
+    publishPreview(
+      imageName: string,
+      rect: Rect,
+      guard: LayerExportGuard,
+      filterType: string
+    ): Promise<'shown' | 'missing' | 'stale'>;
+    clearPreview(): void;
+    isGuardCurrent(guard: LayerExportGuard): boolean;
+    isDraftValid(draft: LayerFilterSettings): boolean;
+    makeDurable(imageName: string): Promise<void>;
+    canCommit(): boolean;
+    commit(options: {
+      draft: LayerFilterSettings;
+      guard: LayerExportGuard;
+      image: { imageName: string; width: number; height: number };
+      origin: { x: number; y: number };
+      rect: Rect;
+      signal: AbortSignal;
+      target: FilterCommitTarget;
+    }): Promise<CommitRasterFilterResult>;
+  };
+  guard: LayerExportGuard;
+  initialFilter: LayerFilterSettings | null;
+  initialDraft?: LayerFilterSettings;
+  layerName?: string;
+  layerType: 'raster' | 'control';
+}
+
+export interface SelectObjectReadyResult {
+  status: 'ready';
+  image: CanvasImageRef;
+  rect: Rect;
+  guard: LayerExportGuard;
+}
+export interface CreateSelectObjectSessionOptions<T> {
+  deps: {
+    captureGuard(): LayerExportGuard | null;
+    controller: CanvasOperationController;
+    exportSource(): Promise<ExportBakedLayerBlobResult>;
+    uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ height: number; imageName: string; width: number }>;
+    runGraph(options: {
+      graph: BackendGraphContract;
+      outputNodeId?: string;
+      signal?: AbortSignal;
+    }): Promise<CanvasUtilityGraphResult>;
+    decodePreview(result: SelectObjectReadyResult, signal: AbortSignal): Promise<T>;
+    publishPreview(preview: SelectObjectSessionPreview<T>): undefined;
+    cleanupPreview(): void;
+    isGuardCurrent(guard: LayerExportGuard): boolean;
+  };
+  operation: CanvasOperationSession;
+}
+
+export interface CanvasApplicationPort {
+  createFilterCoordinator(deps: CanvasFilterCoordinatorDeps): CanvasFilterOperationCoordinator;
+  createSelectObjectCoordinator(deps: CanvasSelectObjectCoordinatorDeps): CanvasSelectObjectOperationCoordinator;
+  createOperationStores(): CanvasApplicationOperationStores;
+  createOperationController(deps: {
+    edits: CanvasEditGate;
+    isGuardCurrent(guard: LayerExportGuard): boolean;
+  }): CanvasOperationController;
+  runGraph(options: {
+    graph: BackendGraphContract;
+    outputNodeId?: string;
+    signal?: AbortSignal;
+  }): Promise<CanvasUtilityGraphResult>;
+  uploadImage(
+    blob: Blob,
+    options?: { isIntermediate?: boolean; signal?: AbortSignal }
+  ): Promise<{ height: number; imageName: string; width: number }>;
+  getSelectedModelBase(state: WorkbenchState, projectId: string): string | null;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/createCanvasEngine.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/createCanvasEngine.ts
new file mode 100644
index 00000000000..205e71e4b96
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/createCanvasEngine.ts
@@ -0,0 +1,282 @@
+import type {
+  CanvasEngine as CoreCanvasEngine,
+  CanvasEngineOptions as CoreCanvasEngineOptions,
+} from '@workbench/canvas-engine/engine';
+import type { CanvasUtilityGraphResult } from '@workbench/canvas-operations/contracts';
+import type { BackendGraphContract } from '@workbench/types';
+
+import { createCanvasEngine as createCanvasEngineCore } from '@workbench/canvas-engine/engine';
+import { canvasApplicationPort } from '@workbench/canvas-operations/applicationPort';
+
+import type { CanvasOperationCapability } from './api';
+
+export interface CanvasEngineOptions extends Omit<CoreCanvasEngineOptions, 'uploadImage' | 'getMainModelBase'> {
+  getMainModelBase?: () => string | null;
+  selectObjectDeps?: {
+    uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ height: number; imageName: string; width: number }>;
+    runGraph(options: {
+      graph: BackendGraphContract;
+      outputNodeId?: string;
+      signal?: AbortSignal;
+    }): Promise<CanvasUtilityGraphResult>;
+  };
+  filterDeps?: {
+    uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ imageName: string }>;
+    runGraph(options: {
+      graph: BackendGraphContract;
+      outputNodeId?: string;
+      signal?: AbortSignal;
+    }): Promise<CanvasUtilityGraphResult>;
+  };
+}
+
+export type CanvasOperationsCapability = CanvasOperationCapability;
+export type CanvasEngine = CoreCanvasEngine;
+
+const operationsByEngine = new WeakMap<object, CanvasOperationCapability>();
+
+export const getCanvasOperations = (engine: object): CanvasOperationCapability => {
+  const operations = operationsByEngine.get(engine);
+  if (!operations) {
+    throw new Error('Canvas application operations are unavailable for this engine.');
+  }
+  return operations;
+};
+
+/** Application composition root: owns SAM/filter sessions, queues, uploads, and their core capability adapters. */
+export const createCanvasEngine = (options: CanvasEngineOptions): CanvasEngine => {
+  const { filterDeps, selectObjectDeps, ...coreOptions } = options;
+  const composition = createCanvasEngineCore({
+    ...coreOptions,
+    getMainModelBase: options.getMainModelBase,
+    uploadImage: (blob) => canvasApplicationPort.uploadImage(blob),
+  });
+  const { applicationHost: host } = composition;
+  const core = composition.engine;
+  const stores = canvasApplicationPort.createOperationStores();
+  const controller = canvasApplicationPort.createOperationController({
+    edits: core.edits,
+    isGuardCurrent: host.isGuardCurrent,
+  });
+
+  let filterCoordinator!: ReturnType<typeof canvasApplicationPort.createFilterCoordinator>;
+  const selectObjectCoordinator = canvasApplicationPort.createSelectObjectCoordinator({
+    captureGuard: host.captureGuard,
+    clearOtherOperation: () => filterCoordinator.cancel(),
+    clearPreview: host.clearSamPreview,
+    commitGenerated: (preview, commitOptions) =>
+      host.commitGenerated({
+        copyLayerName:
+          commitOptions.mode === 'copy-raster'
+            ? 'Segmented Object'
+            : commitOptions.mode === 'copy-control'
+              ? 'Segmented Object Control'
+              : undefined,
+        guard: preview.guard,
+        historyLabel: commitOptions.mode === 'replace' ? 'Replace layer with selected object' : undefined,
+        image: preview.image,
+        origin: { x: preview.rect.x, y: preview.rect.y },
+        signal: commitOptions.signal,
+        target:
+          commitOptions.mode === 'replace'
+            ? 'replace'
+            : commitOptions.mode === 'copy-raster'
+              ? 'copy-raster'
+              : 'copy-control',
+      }),
+    commitMask: (preview, target, signal) =>
+      host.commitMask({ guard: preview.guard, image: preview.image, rect: preview.rect, signal, target }),
+    controller,
+    decodePreview: host.decodeSelectObjectPreview,
+    exportSource: host.exportBakedLayerBlob,
+    invalidateOverlay: () => {
+      const session = stores.samSession.get();
+      host.setSamInteraction(
+        session?.input.type === 'visual'
+          ? { input: session.input, pointLabel: session.pointLabel, sourceRect: session.sourceRect }
+          : null
+      );
+    },
+    isGuardCurrent: host.isGuardCurrent,
+    isInteractionLocked: host.isInteractionLocked,
+    isSamToolActive: host.isSamToolActive,
+    prepareStart: host.prepareSelectObjectStart,
+    projectId: options.projectId,
+    publishPreview: (preview) => host.publishSamPreview(preview),
+    replaceSelection: (preview, signal) => host.replaceSelection(preview.guard, preview.image, preview.rect, signal),
+    replaceTemporaryRestoreTool: host.replaceTemporaryRestoreTool,
+    runGraph: (runOptions) => selectObjectDeps?.runGraph(runOptions) ?? canvasApplicationPort.runGraph(runOptions),
+    selectLayer: host.selectLayer,
+    setSamTool: host.setSamTool,
+    setViewTool: host.setViewTool,
+    stores,
+    uploadIntermediate: async (blob, signal) => {
+      if (selectObjectDeps) {
+        return selectObjectDeps.uploadIntermediate(blob, signal);
+      }
+      if (signal?.aborted) {
+        throw new DOMException('Select Object upload was aborted.', 'AbortError');
+      }
+      const uploaded = await canvasApplicationPort.uploadImage(blob, { isIntermediate: true, signal });
+      if (signal?.aborted) {
+        throw new DOMException('Select Object upload was aborted.', 'AbortError');
+      }
+      return uploaded;
+    },
+  });
+
+  filterCoordinator = canvasApplicationPort.createFilterCoordinator({
+    captureGuard: host.captureGuard,
+    clearOtherOperation: () => selectObjectCoordinator.cancel(),
+    clearPreview: host.clearFilterPreview,
+    controller,
+    encodeSurface: host.encodeSurface,
+    getDocument: host.getDocument,
+    getSessionDeps: (layerId) => ({
+      commit: ({ draft, guard, image, rect, signal, target }) => {
+        if (host.isInteractionLocked()) {
+          return Promise.resolve({ status: 'locked' });
+        }
+        return host.commitFilter({
+          filter: draft,
+          guard,
+          image,
+          mode: target === 'apply' ? 'replace' : 'copy',
+          rect,
+          requireExactImageDimensions: true,
+          signal,
+          target,
+        });
+      },
+      exportPixels: () => host.exportLayerPixels(layerId, { applyAdjustments: true, includeDisabled: true }),
+      isGuardCurrent: host.isGuardCurrent,
+      publishPreview: (imageName, rect, guard, filterType) =>
+        host.publishFilterPreview(guard.layerId, imageName, rect, guard, filterType),
+    }),
+    isInteractionLocked: host.isInteractionLocked,
+    runFilterGraph: async (runOptions) => {
+      const output = await (filterDeps?.runGraph(runOptions) ?? canvasApplicationPort.runGraph(runOptions));
+      return { height: output.height, imageName: output.imageName, width: output.width };
+    },
+    selectLayer: host.selectLayer,
+    setViewTool: host.setViewTool,
+    stores,
+    uploadIntermediate: async (blob, signal) => {
+      const uploaded = await (filterDeps?.uploadIntermediate(blob, signal) ??
+        canvasApplicationPort.uploadImage(blob, { isIntermediate: true, signal }));
+      return { imageName: uploaded.imageName };
+    },
+  });
+
+  const syncEditingLock = (): void =>
+    core.stores.documentEditingLocked.set(controller.getSnapshot().status === 'active');
+  const unsubscribeEditingLock = controller.subscribe(syncEditingLock);
+  const syncSamInteraction = (): void => {
+    const session = stores.samSession.get();
+    host.setSamInteraction(
+      session?.input.type === 'visual'
+        ? { input: session.input, pointLabel: session.pointLabel, sourceRect: session.sourceRect }
+        : null
+    );
+  };
+  const unsubscribeSamInteraction = stores.samSession.subscribe(syncSamInteraction);
+  const unsubscribeToolChanges = host.subscribeToolChanges(({ from, temporary, to }) => {
+    if (from === 'sam' && to !== 'sam' && !temporary && selectObjectCoordinator.isActive()) {
+      selectObjectCoordinator.cancel();
+    }
+  });
+  host.setSamInputHandler((input) => selectObjectCoordinator.update({ input }));
+  host.setEscapeHandler((gestureWasActive) => {
+    if (gestureWasActive) {
+      return false;
+    }
+    if (filterCoordinator.isActive()) {
+      filterCoordinator.cancel();
+      return true;
+    }
+    if (selectObjectCoordinator.isActive()) {
+      selectObjectCoordinator.cancel();
+      return true;
+    }
+    return false;
+  });
+  syncEditingLock();
+  syncSamInteraction();
+
+  const operations: CanvasOperationCapability = {
+    applySelectObjectSession: selectObjectCoordinator.apply,
+    cancelFilterOperation: filterCoordinator.cancel,
+    cancelSelectObjectSession: selectObjectCoordinator.cancel,
+    commitFilterOperation: filterCoordinator.commit,
+    controller,
+    processFilterOperation: filterCoordinator.process,
+    processSelectObjectSession: selectObjectCoordinator.process,
+    resetFilterOperation: filterCoordinator.reset,
+    resetSelectObjectSession: selectObjectCoordinator.reset,
+    saveSelectObjectSession: selectObjectCoordinator.save,
+    setFilterOperationAutoProcess: filterCoordinator.setAutoProcess,
+    startFilterOperation: filterCoordinator.start,
+    startSelectObject: selectObjectCoordinator.start,
+    stores,
+    updateFilterOperation: filterCoordinator.updateDraft,
+    updateSelectObjectSession: selectObjectCoordinator.update,
+  };
+
+  const coreSetInteractionLocked = core.tools.setInteractionLocked;
+  const tools = {
+    ...core.tools,
+    setInteractionLocked: (locked: boolean) => {
+      if (locked) {
+        selectObjectCoordinator.interruptAndBlock();
+        filterCoordinator.interruptAndBlock();
+      }
+      coreSetInteractionLocked(locked);
+      if (!locked && selectObjectCoordinator.isActive()) {
+        host.setSamTool();
+      }
+    },
+  };
+
+  let disposed = false;
+  const disposeOperations = (): void => {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    host.setSamInputHandler(null);
+    host.setEscapeHandler(null);
+    unsubscribeToolChanges();
+    unsubscribeSamInteraction();
+    unsubscribeEditingLock();
+    filterCoordinator.dispose();
+    selectObjectCoordinator.dispose();
+    controller.dispose();
+    core.stores.documentEditingLocked.set(false);
+    host.setSamInteraction(null);
+  };
+  const lifecycle = {
+    ...core.lifecycle,
+    beginCooldown: () => {
+      filterCoordinator.cancel();
+      selectObjectCoordinator.cancel();
+      controller.invalidateDocument(options.projectId);
+      return core.lifecycle.beginCooldown();
+    },
+    dispose: () => {
+      disposeOperations();
+      core.lifecycle.dispose();
+    },
+  };
+  const diagnostics = {
+    ...core.diagnostics,
+    clearCaches: async () => {
+      filterCoordinator.cancel();
+      selectObjectCoordinator.cancel();
+      await core.diagnostics.clearCaches();
+    },
+  };
+
+  const engine: CanvasEngine = { ...core, diagnostics, lifecycle, tools };
+  operationsByEngine.set(engine, operations);
+  return engine;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/engineRegistry.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/engineRegistry.test.ts
new file mode 100644
index 00000000000..acffc3885fe
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/engineRegistry.test.ts
@@ -0,0 +1,387 @@
+import type {
+  CanvasControlLayerContract,
+  CanvasDocumentContractV2,
+  CanvasRegionalGuidanceLayerContract,
+} from '@workbench/types';
+
+import { createBitmapStore } from '@workbench/canvas-engine/document/bitmapStore';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import {
+  createCompositeDedupeCache,
+  executeControlComposite,
+  executeRegionalMaskComposite,
+} from '@workbench/canvas-operations/compositeForGeneration';
+import { createEmptyCanvasDocumentV2 } from '@workbench/canvasMigration';
+import { applyCanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import { planControlComposites, planRegionalMaskComposites } from '@workbench/generation/canvas/compositePlan';
+import { createInitialWorkbenchState } from '@workbench/workbenchState';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { EngineDeps, RegistryTimers } from './engineRegistry';
+
+import { createEngineRegistry } from './engineRegistry';
+
+const createDeferred = <T>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+const drainUntil = async (predicate: () => boolean, maxTicks = 50): Promise<void> => {
+  for (let tick = 0; tick < maxTicks && !predicate(); tick += 1) {
+    await Promise.resolve();
+  }
+};
+
+const createFakeDeps = (): EngineDeps => {
+  let project = createInitialWorkbenchState().projects[0]!;
+  const listeners = new Set<() => void>();
+  return {
+    backend: createTestStubRasterBackend(),
+    imageResolver: () => Promise.resolve(new Blob()),
+    mutationPort: {
+      dispatch: (mutation) => {
+        const before = project.canvas;
+        project = applyCanvasProjectMutation(project, mutation);
+        for (const listener of listeners) {
+          listener();
+        }
+        return project.canvas !== before;
+      },
+      getCanvasState: () => project.canvas,
+      subscribe: (listener) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    },
+    reportError: vi.fn(),
+  };
+};
+
+const controlLayer = (id: string): CanvasControlLayerContract => ({
+  adapter: {
+    beginEndStepPct: [0, 1],
+    controlMode: 'balanced',
+    kind: 'controlnet',
+    model: null,
+    weight: 0.75,
+  },
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: 64, imageName: `${id}.png`, width: 64 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: true,
+});
+
+const regionalLayer = (id: string): CanvasRegionalGuidanceLayerContract => ({
+  autoNegative: false,
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: {
+    bitmap: { height: 64, imageName: `${id}-mask.png`, width: 64 },
+    fill: { color: '#ff0000', style: 'solid' },
+  },
+  name: id,
+  negativePrompt: null,
+  opacity: 1,
+  positivePrompt: 'regional prompt',
+  referenceImages: [],
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'regional_guidance',
+});
+
+const invocationDocument = (): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 64, width: 64, x: 0, y: 0 },
+  height: 64,
+  layers: [controlLayer('control-a'), regionalLayer('regional-a')],
+  selectedLayerId: 'control-a',
+  version: 2,
+  width: 64,
+});
+
+const createFakeTimers = (): { timers: RegistryTimers; flush: () => void; pending: () => number } => {
+  let nextHandle = 0;
+  const scheduled = new Map<number, () => void>();
+  return {
+    flush: () => {
+      const callbacks = [...scheduled.values()];
+      scheduled.clear();
+      for (const callback of callbacks) {
+        callback();
+      }
+    },
+    pending: () => scheduled.size,
+    timers: {
+      clearTimeout: (handle) => {
+        scheduled.delete(handle);
+      },
+      setTimeout: (handler) => {
+        nextHandle += 1;
+        scheduled.set(nextHandle, handler);
+        return nextHandle;
+      },
+    },
+  };
+};
+
+describe('createEngineRegistry', () => {
+  it('returns the same instance per project id and distinct instances across ids', () => {
+    const registry = createEngineRegistry();
+    const deps = createFakeDeps();
+
+    const first = registry.getOrCreateEngine('p1', deps);
+    const again = registry.getOrCreateEngine('p1', deps);
+    const other = registry.getOrCreateEngine('p2', deps);
+
+    expect(again).toBe(first);
+    expect(other).not.toBe(first);
+    expect(registry.getEngine('p1')).toBe(first);
+
+    first.lifecycle.dispose();
+    other.lifecycle.dispose();
+  });
+
+  it('disposes after the grace period once the last reference is released', async () => {
+    const fakeTimers = createFakeTimers();
+    const registry = createEngineRegistry({ gracePeriodMs: 30_000, timers: fakeTimers.timers });
+    const engine = registry.getOrCreateEngine('p1', createFakeDeps());
+    const disposeSpy = vi.spyOn(engine.lifecycle, 'dispose');
+    const cooldownSpy = vi.spyOn(engine.lifecycle, 'beginCooldown');
+
+    registry.releaseEngine('p1');
+    expect(fakeTimers.pending()).toBe(1);
+    expect(cooldownSpy).toHaveBeenCalledOnce();
+    expect(disposeSpy).not.toHaveBeenCalled();
+
+    fakeTimers.flush();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(disposeSpy).toHaveBeenCalledTimes(1);
+    expect(registry.getEngine('p1')).toBeUndefined();
+  });
+
+  it('retains a dirty engine and retries cooldown before disposing it', async () => {
+    const fakeTimers = createFakeTimers();
+    const registry = createEngineRegistry({ gracePeriodMs: 30_000, timers: fakeTimers.timers });
+    const engine = registry.getOrCreateEngine('p1', createFakeDeps());
+    const disposeSpy = vi.spyOn(engine.lifecycle, 'dispose');
+    const cooldownSpy = vi
+      .spyOn(engine.lifecycle, 'beginCooldown')
+      .mockResolvedValueOnce('dirty')
+      .mockResolvedValueOnce('cooled');
+
+    registry.releaseEngine('p1');
+    fakeTimers.flush();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(registry.getEngine('p1')).toBe(engine);
+    expect(disposeSpy).not.toHaveBeenCalled();
+    expect(cooldownSpy).toHaveBeenCalledTimes(2);
+    expect(fakeTimers.pending()).toBe(1);
+
+    fakeTimers.flush();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(registry.getEngine('p1')).toBeUndefined();
+    expect(disposeSpy).toHaveBeenCalledOnce();
+  });
+
+  it('cancels the pending disposal when the engine is re-acquired', () => {
+    const fakeTimers = createFakeTimers();
+    const registry = createEngineRegistry({ timers: fakeTimers.timers });
+    const engine = registry.getOrCreateEngine('p1', createFakeDeps());
+    const disposeSpy = vi.spyOn(engine.lifecycle, 'dispose');
+    const activateSpy = vi.spyOn(engine.lifecycle, 'activate');
+
+    registry.releaseEngine('p1');
+    expect(fakeTimers.pending()).toBe(1);
+
+    const reacquired = registry.getOrCreateEngine('p1', createFakeDeps());
+    expect(reacquired).toBe(engine);
+    expect(fakeTimers.pending()).toBe(0);
+    expect(activateSpy).toHaveBeenCalledOnce();
+
+    fakeTimers.flush();
+    expect(disposeSpy).not.toHaveBeenCalled();
+
+    engine.lifecycle.dispose();
+  });
+
+  it('continues control and regional composites from a detached snapshot after a project switch', async () => {
+    const fakeTimers = createFakeTimers();
+    const registry = createEngineRegistry({ timers: fakeTimers.timers });
+    const projectADeps = createFakeDeps();
+    projectADeps.mutationPort.dispatch({ document: invocationDocument(), type: 'replaceCanvasDocument' });
+    const projectAEngine = registry.getOrCreateEngine('project-a', projectADeps);
+    const documentSnapshot = projectAEngine.document.captureSnapshot();
+    expect(documentSnapshot).not.toBeNull();
+
+    const capture = await projectAEngine.exports.captureRasterSnapshot(documentSnapshot!, ['control-a', 'regional-a']);
+    expect(capture.status).toBe('ok');
+    if (capture.status !== 'ok') {
+      throw new Error('Expected a detached raster snapshot');
+    }
+
+    registry.releaseEngine('project-a');
+    const projectBEngine = registry.getOrCreateEngine('project-b', createFakeDeps());
+    await drainUntil(() => projectAEngine.lifecycle.getLifecycleState() === 'cool');
+
+    expect(projectAEngine.lifecycle.getLifecycleState()).toBe('cool');
+    expect(registry.getEngine('project-a')).toBe(projectAEngine);
+    expect(registry.getEngine('project-b')).toBe(projectBEngine);
+    expect(capture.snapshot.layerSurfaces.size).toBe(2);
+
+    const frozenDocument = capture.snapshot.canvas.document;
+    const controlPlan = planControlComposites(frozenDocument, frozenDocument.bbox)[0];
+    const regionalPlan = planRegionalMaskComposites(frozenDocument, frozenDocument.bbox)[0];
+    expect(controlPlan).toBeDefined();
+    expect(regionalPlan).toBeDefined();
+
+    const surfaceRequests: string[] = [];
+    const uploadImage = vi.fn((blob: Blob) => {
+      void blob;
+      return Promise.resolve({ height: 64, imageName: `snapshot-${surfaceRequests.length}.png`, width: 64 });
+    });
+    const executorDeps = {
+      ...projectAEngine.exports.getCompositeExecutorDeps(),
+      dedupe: createCompositeDedupeCache(),
+      getLayerSurface: (layerId: string) => {
+        surfaceRequests.push(layerId);
+        const detached = capture.snapshot.layerSurfaces.get(layerId);
+        if (!detached) {
+          throw new Error(`Detached snapshot is missing ${layerId}`);
+        }
+        return Promise.resolve(detached);
+      },
+      hashBlob: (blob: Blob) => blob.text(),
+      uploadImage,
+    };
+
+    await executeControlComposite(controlPlan!.entry, executorDeps);
+    await executeRegionalMaskComposite(regionalPlan!.entry, executorDeps);
+
+    expect(surfaceRequests).toEqual(['control-a', 'regional-a']);
+    expect(uploadImage).toHaveBeenCalledTimes(1);
+    expect(capture.snapshot.layerSurfaces.size).toBe(2);
+
+    capture.snapshot.release();
+    registry.releaseEngine('project-b');
+    fakeTimers.flush();
+    await drainUntil(
+      () => registry.getEngine('project-a') === undefined && registry.getEngine('project-b') === undefined
+    );
+  });
+
+  it('keeps a pending bitmap upload alive when the engine reaches zero references and is reacquired', async () => {
+    const fakeTimers = createFakeTimers();
+    const registry = createEngineRegistry({ timers: fakeTimers.timers });
+    let project = createInitialWorkbenchState().projects[0]!;
+    project = applyCanvasProjectMutation(project, {
+      document: createEmptyCanvasDocumentV2(),
+      type: 'replaceCanvasDocument',
+    });
+    project = applyCanvasProjectMutation(project, {
+      layer: {
+        blendMode: 'normal',
+        id: 'pending-layer',
+        isEnabled: true,
+        isLocked: false,
+        name: 'Pending layer',
+        opacity: 1,
+        source: { bitmap: null, type: 'paint' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+        type: 'raster',
+      },
+      type: 'addCanvasLayer',
+    });
+    const listeners = new Set<() => void>();
+    const mutationPort = {
+      dispatch: (mutation: Parameters<typeof applyCanvasProjectMutation>[1]) => {
+        const before = project.canvas;
+        project = applyCanvasProjectMutation(project, mutation);
+        for (const listener of listeners) {
+          listener();
+        }
+        return project.canvas !== before;
+      },
+      getCanvasState: () => project.canvas,
+      subscribe: (listener: () => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    };
+    const uploaded = createDeferred<{ height: number; imageName: string; width: number }>();
+    const uploadImage = vi.fn(() => uploaded.promise);
+    const surface = createTestStubRasterBackend().createSurface(8, 8);
+    const bitmapStore = createBitmapStore({
+      debounceMs: 60_000,
+      dispatch: mutationPort.dispatch,
+      encodeSurface: () => Promise.resolve(new Blob(['pending-pixels'], { type: 'image/png' })),
+      getLayerSource: () => {
+        const layer = project.canvas.document.layers.find((candidate) => candidate.id === 'pending-layer');
+        return layer?.type === 'raster' && layer.source.type === 'paint' ? layer.source : null;
+      },
+      getLayerSurface: () => ({ offset: { x: 0, y: 0 }, surface }),
+      hashBlob: () => Promise.resolve('pending-pixels'),
+      uploadImage,
+    });
+    const deps: EngineDeps = {
+      backend: createTestStubRasterBackend(),
+      bitmapStore,
+      imageResolver: () => Promise.resolve(new Blob()),
+      mutationPort,
+      reportError: vi.fn(),
+    };
+    const engine = registry.getOrCreateEngine(project.id, deps);
+    bitmapStore.markLayerDirty('pending-layer');
+
+    registry.releaseEngine(project.id);
+    await drainUntil(() => uploadImage.mock.calls.length === 1);
+    expect(fakeTimers.pending()).toBe(1);
+
+    const reacquired = registry.getOrCreateEngine(project.id, deps);
+    expect(reacquired).toBe(engine);
+    expect(fakeTimers.pending()).toBe(0);
+
+    uploaded.resolve({ height: 8, imageName: 'persisted-after-reacquire.png', width: 8 });
+    await bitmapStore.flushPendingUploads();
+
+    const layer = project.canvas.document.layers.find((candidate) => candidate.id === 'pending-layer');
+    expect(layer?.type === 'raster' && layer.source.type === 'paint' ? layer.source.bitmap?.imageName : null).toBe(
+      'persisted-after-reacquire.png'
+    );
+    engine.lifecycle.dispose();
+  });
+
+  it('only schedules disposal when the last reference is released', async () => {
+    const fakeTimers = createFakeTimers();
+    const registry = createEngineRegistry({ timers: fakeTimers.timers });
+    const deps = createFakeDeps();
+
+    registry.getOrCreateEngine('p1', deps);
+    registry.getOrCreateEngine('p1', deps);
+
+    registry.releaseEngine('p1');
+    expect(fakeTimers.pending()).toBe(0);
+
+    registry.releaseEngine('p1');
+    expect(fakeTimers.pending()).toBe(1);
+
+    fakeTimers.flush();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(registry.getEngine('p1')).toBeUndefined();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/engineRegistry.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/engineRegistry.ts
new file mode 100644
index 00000000000..1e714fc0c0c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/engineRegistry.ts
@@ -0,0 +1,132 @@
+/**
+ * The engine registry: one {@link CanvasEngine} per project, shared by the
+ * canvas and layers widgets (and any other surface that needs the same live
+ * document/pixels).
+ *
+ * Acquisition is reference-counted: `getOrCreateEngine` hands out (or creates)
+ * the instance and bumps the count; `releaseEngine` drops it. When the count
+ * reaches zero the engine is not disposed immediately — a grace-period timer
+ * runs first, so a quick unmount/remount (route change, widget re-layout)
+ * re-acquires the same warm instance instead of paying to rebuild it. A
+ * re-acquire cancels the pending disposal. The timer is injectable so tests can
+ * drive it deterministically.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import {
+  createCanvasEngine,
+  type CanvasEngine,
+  type CanvasEngineOptions,
+} from '@workbench/canvas-operations/createCanvasEngine';
+
+/** Engine creation dependencies, minus the project id the registry supplies. */
+export type EngineDeps = Omit<CanvasEngineOptions, 'projectId'>;
+
+/** Default grace period before a released engine is disposed (30s). */
+export const DEFAULT_GRACE_PERIOD_MS = 30_000;
+
+/** Injectable timer seam (defaults to the global timers). */
+export interface RegistryTimers {
+  setTimeout(handler: () => void, ms: number): number;
+  clearTimeout(handle: number): void;
+}
+
+/** The registry handle. */
+export interface EngineRegistry {
+  /** Returns the engine for `projectId`, creating it if needed, and adds a reference. */
+  getOrCreateEngine(projectId: string, deps: EngineDeps): CanvasEngine;
+  /** Returns the engine for `projectId` without changing its reference count. */
+  getEngine(projectId: string): CanvasEngine | undefined;
+  /** Drops a reference; schedules grace-period disposal when the last reference is released. */
+  releaseEngine(projectId: string): void;
+}
+
+interface RegistryEntry {
+  engine: CanvasEngine;
+  refCount: number;
+  disposeHandle: number | null;
+  generation: number;
+  cooldown: Promise<'cooled' | 'dirty'> | null;
+}
+
+const defaultTimers: RegistryTimers = {
+  clearTimeout: (handle) => globalThis.clearTimeout(handle),
+  setTimeout: (handler, ms) => globalThis.setTimeout(handler, ms),
+};
+
+/** Creates an engine registry with an optional grace period and injectable timers. */
+export const createEngineRegistry = (
+  options: {
+    gracePeriodMs?: number;
+    timers?: RegistryTimers;
+  } = {}
+): EngineRegistry => {
+  const gracePeriodMs = options.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS;
+  const timers = options.timers ?? defaultTimers;
+  const entries = new Map<string, RegistryEntry>();
+
+  const cancelDisposal = (entry: RegistryEntry): void => {
+    if (entry.disposeHandle !== null) {
+      timers.clearTimeout(entry.disposeHandle);
+      entry.disposeHandle = null;
+    }
+  };
+
+  const scheduleDisposal = (projectId: string, entry: RegistryEntry, generation: number): void => {
+    entry.disposeHandle = timers.setTimeout(() => {
+      entry.disposeHandle = null;
+      void entry.cooldown?.then((result) => {
+        if (entry.refCount !== 0 || entry.generation !== generation || entries.get(projectId) !== entry) {
+          return;
+        }
+        if (result === 'dirty') {
+          entry.cooldown = entry.engine.lifecycle.beginCooldown();
+          scheduleDisposal(projectId, entry, generation);
+          return;
+        }
+        entries.delete(projectId);
+        entry.engine.lifecycle.dispose();
+      });
+    }, gracePeriodMs);
+  };
+
+  return {
+    getEngine: (projectId) => entries.get(projectId)?.engine,
+    getOrCreateEngine: (projectId, deps) => {
+      const existing = entries.get(projectId);
+      if (existing) {
+        cancelDisposal(existing);
+        existing.generation += 1;
+        existing.refCount += 1;
+        existing.engine.lifecycle.activate();
+        existing.cooldown = null;
+        return existing.engine;
+      }
+      const engine = createCanvasEngine({ projectId, ...deps });
+      entries.set(projectId, { cooldown: null, disposeHandle: null, engine, generation: 0, refCount: 1 });
+      return engine;
+    },
+    releaseEngine: (projectId) => {
+      const entry = entries.get(projectId);
+      if (!entry) {
+        return;
+      }
+      entry.refCount = Math.max(0, entry.refCount - 1);
+      if (entry.refCount > 0 || entry.disposeHandle !== null) {
+        return;
+      }
+      entry.generation += 1;
+      const generation = entry.generation;
+      entry.cooldown = entry.engine.lifecycle.beginCooldown();
+      scheduleDisposal(projectId, entry, generation);
+    },
+  };
+};
+
+/** The process-wide default registry shared by all widget surfaces. */
+const defaultRegistry = createEngineRegistry();
+
+export const getOrCreateEngine = defaultRegistry.getOrCreateEngine;
+export const getEngine = defaultRegistry.getEngine;
+export const releaseEngine = defaultRegistry.releaseEngine;
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/filterOperationSession.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/filterOperationSession.test.ts
new file mode 100644
index 00000000000..0286869867a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/filterOperationSession.test.ts
@@ -0,0 +1,419 @@
+import type { ExportLayerPixelsResult, LayerExportGuard } from '@workbench/canvas-engine/engine';
+import type { CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { createCanvasOperationController } from '@workbench/canvas-operations/operationController';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { FilterOperationSessionDeps } from './filterOperationSession';
+
+import { createFilterOperationSession, FILTER_AUTO_PROCESS_DEBOUNCE_MS } from './filterOperationSession';
+
+const layer: CanvasRasterLayerContractV2 = {
+  blendMode: 'normal',
+  filter: { settings: { radius: 2 }, type: 'canny_edge_detection' },
+  id: 'layer-1',
+  isEnabled: true,
+  isLocked: false,
+  name: 'Layer',
+  opacity: 1,
+  source: { image: { height: 10, imageName: 'source', width: 10 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+};
+const guard: LayerExportGuard = {
+  cacheVersion: 1,
+  documentGeneration: 1,
+  layer,
+  layerId: layer.id,
+  projectId: 'project-1',
+};
+const surface = createTestStubRasterBackend().createSurface(10, 10);
+const exported: ExportLayerPixelsResult = {
+  guard,
+  release: vi.fn(),
+  rect: { height: 10, width: 10, x: 3, y: 4 },
+  status: 'ok',
+  surface,
+};
+
+const deferred = <T>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+const createDeps = (overrides: Partial<FilterOperationSessionDeps> = {}): FilterOperationSessionDeps => ({
+  canCommit: vi.fn(() => true),
+  clearPreview: vi.fn(),
+  commit: vi.fn(() => Promise.resolve({ layerId: layer.id, status: 'committed' as const })),
+  controller: createCanvasOperationController({ isGuardCurrent: () => true }),
+  exportPixels: vi.fn(() => Promise.resolve(exported)),
+  isDraftValid: vi.fn(() => true),
+  isGuardCurrent: vi.fn(() => true),
+  makeDurable: vi.fn(() => Promise.resolve()),
+  publishPreview: vi.fn(() => Promise.resolve('shown' as const)),
+  runFilter: vi.fn(() => Promise.resolve({ height: 10, imageName: 'filtered', origin: { x: 3, y: 4 }, width: 10 })),
+  ...overrides,
+});
+
+describe('createFilterOperationSession', () => {
+  it('starts with a cloned persisted settings snapshot and an independent local draft', () => {
+    const deps = createDeps();
+    const session = createFilterOperationSession({
+      deps,
+      guard,
+      initialFilter: layer.filter!,
+      layerName: 'Portrait',
+      layerType: 'raster',
+    });
+
+    expect(session).not.toBeNull();
+    expect(session!.getSnapshot()).toMatchObject({
+      autoProcess: true,
+      draft: { settings: { radius: 2 }, type: 'canny_edge_detection' },
+      initialFilter: { settings: { radius: 2 }, type: 'canny_edge_detection' },
+      layerId: layer.id,
+      layerName: 'Portrait',
+      layerType: 'raster',
+      status: 'ready',
+    });
+
+    session!.updateDraft({ settings: { radius: 9 }, type: 'content_shuffle' });
+    expect(session!.getSnapshot().draft).toEqual({ settings: { radius: 9 }, type: 'content_shuffle' });
+    expect(session!.getSnapshot().initialFilter).toEqual(layer.filter);
+    expect(session!.getSnapshot().layerName).toBe('Portrait');
+    session!.dispose();
+  });
+
+  it('publishes only the newest guarded process result', async () => {
+    const older = deferred<{ height: number; imageName: string; origin: { x: number; y: number }; width: number }>();
+    const newer = deferred<{ height: number; imageName: string; origin: { x: number; y: number }; width: number }>();
+    const runs = [older, newer];
+    const deps = createDeps({ runFilter: vi.fn(() => runs.shift()!.promise) });
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    const first = session.process();
+    await vi.waitFor(() => expect(deps.runFilter).toHaveBeenCalledTimes(1));
+    const second = session.process();
+    await vi.waitFor(() => expect(deps.runFilter).toHaveBeenCalledTimes(2));
+    newer.resolve({ height: 10, imageName: 'newer', origin: { x: 3, y: 4 }, width: 10 });
+    await second;
+    older.resolve({ height: 10, imageName: 'older', origin: { x: 3, y: 4 }, width: 10 });
+    await first;
+
+    expect(deps.publishPreview).toHaveBeenCalledOnce();
+    expect(deps.publishPreview).toHaveBeenCalledWith(
+      'newer',
+      { height: 10, width: 10, x: 3, y: 4 },
+      guard,
+      'canny_edge_detection'
+    );
+    expect(session.getSnapshot().preview?.imageName).toBe('newer');
+  });
+
+  it('publishes and commits the filter output rect instead of the exported source rect', async () => {
+    const deps = createDeps({
+      runFilter: vi.fn(() =>
+        Promise.resolve({ height: 22, imageName: 'blurred', origin: { x: -3, y: -2 }, width: 24 })
+      ),
+    });
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    await session.process();
+    expect(session.getSnapshot().preview?.rect).toEqual({ height: 22, width: 24, x: -3, y: -2 });
+    await session.commit('apply');
+
+    expect(deps.commit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        image: { height: 22, imageName: 'blurred', width: 24 },
+        rect: { height: 22, width: 24, x: -3, y: -2 },
+      })
+    );
+  });
+
+  it('reset selects current filter defaults, clears preview, and keeps the operation active', async () => {
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+    await session.process();
+
+    session.reset({ high_threshold: 200, low_threshold: 100 });
+
+    expect(session.getSnapshot()).toMatchObject({
+      draft: { settings: { high_threshold: 200, low_threshold: 100 }, type: 'canny_edge_detection' },
+      error: null,
+      preview: null,
+      status: 'ready',
+    });
+    expect(deps.clearPreview).toHaveBeenCalled();
+    expect(deps.controller.getSnapshot()).toMatchObject({ identity: { kind: 'filter' }, status: 'active' });
+  });
+
+  it('keeps the preview and session retryable when durability fails', async () => {
+    const deps = createDeps({ makeDurable: vi.fn(() => Promise.reject(new Error('promotion failed'))) });
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+    await session.process();
+
+    await session.commit('apply');
+
+    expect(deps.commit).not.toHaveBeenCalled();
+    expect(session.getSnapshot()).toMatchObject({
+      error: 'promotion failed',
+      preview: { imageName: 'filtered' },
+      status: 'error',
+    });
+    expect(deps.controller.getSnapshot()).toMatchObject({ identity: { kind: 'filter' }, status: 'active' });
+  });
+
+  it.each(['apply', 'raster', 'control'] as const)(
+    'promotes, commits to %s, and leaves the operation for its owner to end',
+    async (target) => {
+      const calls: string[] = [];
+      const deps = createDeps({
+        commit: vi.fn((options) => {
+          calls.push(`commit:${options.target}`);
+          return Promise.resolve({ layerId: layer.id, status: 'committed' as const });
+        }),
+        makeDurable: vi.fn(() => {
+          calls.push('durable');
+          return Promise.resolve();
+        }),
+      });
+      const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+      await session.process();
+
+      await session.commit(target);
+
+      expect(calls).toEqual(['durable', `commit:${target}`]);
+      expect(deps.commit).toHaveBeenCalledWith(
+        expect.objectContaining({
+          draft: layer.filter,
+          guard,
+          target,
+        })
+      );
+      expect(session.getSnapshot()).toMatchObject({ error: null, preview: null, status: 'ready' });
+      expect(deps.controller.getSnapshot()).toMatchObject({ identity: { kind: 'filter' }, status: 'active' });
+      session.dispose();
+      expect(deps.controller.getSnapshot()).toEqual({ status: 'idle' });
+    }
+  );
+
+  it('retains the guarded preview after a failed commit so Apply can retry', async () => {
+    const deps = createDeps({
+      commit: vi.fn(() => Promise.resolve({ message: 'cache failed', status: 'failed' as const })),
+    });
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+    await session.process();
+
+    await session.commit('apply');
+
+    expect(session.getSnapshot()).toMatchObject({
+      error: 'cache failed',
+      preview: { imageName: 'filtered' },
+      status: 'error',
+    });
+    expect(deps.controller.getSnapshot()).toMatchObject({ identity: { kind: 'filter' }, status: 'active' });
+  });
+
+  it('cancel aborts work, clears preview, and closes the operation independently of subscribers', async () => {
+    const result = deferred<{ height: number; imageName: string; origin: { x: number; y: number }; width: number }>();
+    let signal: AbortSignal | undefined;
+    const deps = createDeps({
+      runFilter: vi.fn((options) => {
+        signal = options.signal;
+        return result.promise;
+      }),
+    });
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+    const unsubscribe = session.subscribe(vi.fn());
+    unsubscribe();
+    const pending = session.process();
+    await vi.waitFor(() => expect(signal).toBeDefined());
+
+    session.cancel();
+    result.resolve({ height: 10, imageName: 'late', origin: { x: 3, y: 4 }, width: 10 });
+    await pending;
+
+    expect(signal?.aborted).toBe(true);
+    expect(deps.publishPreview).not.toHaveBeenCalled();
+    expect(deps.controller.getSnapshot()).toEqual({ status: 'idle' });
+  });
+
+  it.each(['export', 'graph'] as const)(
+    'interrupts processing at the %s boundary while preserving the draft and active operation',
+    async (boundary) => {
+      const wait = deferred<unknown>();
+      const deps = createDeps({
+        exportPixels:
+          boundary === 'export'
+            ? vi.fn(() => wait.promise as Promise<ExportLayerPixelsResult>)
+            : vi.fn(() => Promise.resolve(exported)),
+        runFilter:
+          boundary === 'graph'
+            ? vi.fn(() => wait.promise as ReturnType<FilterOperationSessionDeps['runFilter']>)
+            : vi.fn(() => Promise.resolve({ height: 10, imageName: 'filtered', origin: { x: 3, y: 4 }, width: 10 })),
+      });
+      const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+      session.updateDraft({ settings: { radius: 17 }, type: 'img_blur' });
+      const pending = session.process();
+      await vi.waitFor(() => expect(boundary === 'export' ? deps.exportPixels : deps.runFilter).toHaveBeenCalledOnce());
+
+      session.interruptProcessing();
+      if (boundary === 'export') {
+        wait.resolve(exported);
+      } else {
+        wait.resolve({ height: 10, imageName: 'late', origin: { x: 3, y: 4 }, width: 10 });
+      }
+      await pending;
+
+      expect(deps.publishPreview).not.toHaveBeenCalled();
+      expect(session.getSnapshot()).toMatchObject({
+        draft: { settings: { radius: 17 }, type: 'img_blur' },
+        preview: null,
+        status: 'ready',
+      });
+      expect(deps.controller.getSnapshot()).toMatchObject({ phase: 'ready', status: 'active' });
+    }
+  );
+});
+
+describe('auto-process', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const flushScheduledRun = async (deps: FilterOperationSessionDeps, times: number) => {
+    vi.useRealTimers();
+    await vi.waitFor(() => expect(deps.runFilter).toHaveBeenCalledTimes(times));
+  };
+
+  it('debounces draft updates into a single process run with the latest settings', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.updateDraft({ settings: { radius: 4 }, type: 'img_blur' });
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS - 100);
+    expect(deps.runFilter).not.toHaveBeenCalled();
+    session.updateDraft({ settings: { radius: 6 }, type: 'img_blur' });
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS);
+    await flushScheduledRun(deps, 1);
+    expect(deps.runFilter).toHaveBeenCalledWith(
+      expect.objectContaining({ filterType: 'img_blur', settings: { radius: 6 } })
+    );
+    await vi.waitFor(() => expect(session.getSnapshot().preview?.imageName).toBe('filtered'));
+    session.dispose();
+  });
+
+  it('never schedules for an invalid draft', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps({ isDraftValid: vi.fn(() => false) });
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.updateDraft({ settings: { model: null }, type: 'spandrel_filter' });
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS * 3);
+    expect(deps.runFilter).not.toHaveBeenCalled();
+    session.dispose();
+  });
+
+  it('setAutoProcess(false) cancels the pending run and blocks future scheduling', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.updateDraft({ settings: { radius: 4 }, type: 'img_blur' });
+    session.setAutoProcess(false);
+    expect(session.getSnapshot().autoProcess).toBe(false);
+    session.updateDraft({ settings: { radius: 6 }, type: 'img_blur' });
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS * 3);
+    expect(deps.runFilter).not.toHaveBeenCalled();
+    session.dispose();
+  });
+
+  it('setAutoProcess(true) schedules a run when no preview exists yet', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.setAutoProcess(false);
+    session.setAutoProcess(true);
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS);
+    await flushScheduledRun(deps, 1);
+    session.dispose();
+  });
+
+  it('cancel clears the pending auto-run', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.updateDraft({ settings: { radius: 4 }, type: 'img_blur' });
+    session.cancel();
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS * 3);
+    expect(deps.runFilter).not.toHaveBeenCalled();
+    session.dispose();
+  });
+
+  it('a manual process supersedes the pending debounced run', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.updateDraft({ settings: { radius: 4 }, type: 'img_blur' });
+    await session.process();
+    expect(deps.runFilter).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS * 3);
+    expect(deps.runFilter).toHaveBeenCalledTimes(1);
+    session.dispose();
+  });
+
+  it('interruptProcessing clears the pending auto-run', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.updateDraft({ settings: { radius: 4 }, type: 'img_blur' });
+    expect(session.getSnapshot().status).toBe('ready');
+    session.interruptProcessing();
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS * 3);
+    expect(deps.runFilter).not.toHaveBeenCalled();
+    session.dispose();
+  });
+
+  it('setAutoProcess(true) does not reschedule when a preview exists', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    session.updateDraft({ settings: { radius: 4 }, type: 'img_blur' });
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS);
+    await flushScheduledRun(deps, 1);
+    await vi.waitFor(() => expect(session.getSnapshot().preview?.imageName).toBe('filtered'));
+
+    session.setAutoProcess(false);
+    session.setAutoProcess(true);
+    await new Promise((resolve) => {
+      setTimeout(resolve, FILTER_AUTO_PROCESS_DEBOUNCE_MS * 3);
+    });
+    expect(deps.runFilter).toHaveBeenCalledTimes(1);
+    session.dispose();
+  });
+
+  it('setAutoProcess(true) does not schedule while a run is in flight', async () => {
+    vi.useFakeTimers();
+    const deps = createDeps();
+    const session = createFilterOperationSession({ deps, guard, initialFilter: layer.filter!, layerType: 'raster' })!;
+
+    const inFlight = session.process();
+    session.setAutoProcess(false);
+    session.setAutoProcess(true);
+    await vi.advanceTimersByTimeAsync(FILTER_AUTO_PROCESS_DEBOUNCE_MS * 3);
+    vi.useRealTimers();
+    await inFlight;
+    expect(deps.runFilter).toHaveBeenCalledTimes(1);
+    session.dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/filterOperationSession.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/filterOperationSession.ts
new file mode 100644
index 00000000000..b948aec6d2a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/filterOperationSession.ts
@@ -0,0 +1,385 @@
+import type {
+  CommitRasterFilterResult,
+  ExportLayerPixelsResult,
+  LayerExportGuard,
+} from '@workbench/canvas-engine/engine';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type {
+  FilterCommitTarget,
+  FilterOperationPreview,
+  FilterOperationSessionState,
+  LayerFilterSettings,
+} from '@workbench/canvas-operations/operationTypes';
+export type {
+  FilterCommitTarget,
+  FilterOperationPreview,
+  FilterOperationSessionState,
+  LayerFilterSettings,
+} from '@workbench/canvas-operations/operationTypes';
+import type {
+  CanvasOperationController,
+  CanvasOperationRunResult,
+  CanvasOperationSession,
+} from '@workbench/canvas-operations/operationController';
+
+import type { LayerFilterResult } from './layerFilterRunner';
+
+/** Delay between the last draft edit and the automatic preview run. */
+export const FILTER_AUTO_PROCESS_DEBOUNCE_MS = 400;
+
+export interface FilterOperationSessionDeps {
+  controller: CanvasOperationController;
+  exportPixels(): Promise<ExportLayerPixelsResult>;
+  runFilter(options: {
+    filterType: string;
+    input: { surface: RasterSurface; rect: Rect };
+    settings: Record<string, unknown>;
+    signal: AbortSignal;
+  }): Promise<LayerFilterResult>;
+  publishPreview(
+    imageName: string,
+    rect: Rect,
+    guard: LayerExportGuard,
+    filterType: string
+  ): Promise<'shown' | 'missing' | 'stale'>;
+  clearPreview(): void;
+  isGuardCurrent(guard: LayerExportGuard): boolean;
+  isDraftValid(draft: LayerFilterSettings): boolean;
+  makeDurable(imageName: string): Promise<void>;
+  canCommit(): boolean;
+  commit(options: {
+    draft: LayerFilterSettings;
+    guard: LayerExportGuard;
+    image: { imageName: string; width: number; height: number };
+    origin: { x: number; y: number };
+    rect: Rect;
+    signal: AbortSignal;
+    target: FilterCommitTarget;
+  }): Promise<CommitRasterFilterResult>;
+}
+
+export interface FilterOperationSession {
+  getSnapshot(): FilterOperationSessionState;
+  subscribe(listener: () => void): () => void;
+  updateDraft(draft: LayerFilterSettings): void;
+  setAutoProcess(value: boolean): void;
+  process(): Promise<CanvasOperationRunResult>;
+  interruptProcessing(): void;
+  reset(settings: Record<string, unknown>): void;
+  /** On 'committed' the canvas operation stays active; the owner must dispose the session to end it. */
+  commit(target: FilterCommitTarget): Promise<'committed' | 'blocked' | 'stale'>;
+  blockCommit(): void;
+  cancel(): void;
+  dispose(): void;
+}
+
+export interface CreateFilterOperationSessionOptions {
+  deps: FilterOperationSessionDeps;
+  guard: LayerExportGuard;
+  initialFilter: LayerFilterSettings | null;
+  initialDraft?: LayerFilterSettings;
+  layerName?: string;
+  layerType: 'raster' | 'control';
+}
+
+const cloneFilter = (filter: LayerFilterSettings | null): LayerFilterSettings | null =>
+  filter ? structuredClone(filter) : null;
+
+const sameGuard = (left: LayerExportGuard, right: LayerExportGuard): boolean =>
+  left.projectId === right.projectId &&
+  left.layerId === right.layerId &&
+  left.layer === right.layer &&
+  left.cacheVersion === right.cacheVersion &&
+  left.documentGeneration === right.documentGeneration;
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+export const createFilterOperationSession = (
+  options: CreateFilterOperationSessionOptions
+): FilterOperationSession | null => {
+  const { deps, guard, layerType } = options;
+  const initialFilter = cloneFilter(options.initialFilter);
+  const fallback = options.initialDraft ?? { settings: {}, type: 'canny_edge_detection' };
+  let state: FilterOperationSessionState = {
+    autoProcess: true,
+    draft: cloneFilter(initialFilter) ?? fallback,
+    error: null,
+    initialFilter,
+    layerId: guard.layerId,
+    layerName: options.layerName ?? guard.layer.name,
+    layerType,
+    preview: null,
+    status: 'ready',
+  };
+  let disposed = false;
+  let commitController: AbortController | null = null;
+  let commitToken = 0;
+  const listeners = new Set<() => void>();
+  let autoProcessTimer: ReturnType<typeof setTimeout> | null = null;
+  const clearAutoProcess = (): void => {
+    if (autoProcessTimer !== null) {
+      clearTimeout(autoProcessTimer);
+      autoProcessTimer = null;
+    }
+  };
+  const scheduleAutoProcess = (): void => {
+    clearAutoProcess();
+    if (!state.autoProcess || !deps.isDraftValid(state.draft)) {
+      return;
+    }
+    autoProcessTimer = setTimeout(() => {
+      autoProcessTimer = null;
+      void process();
+    }, FILTER_AUTO_PROCESS_DEBOUNCE_MS);
+  };
+
+  const publish = (next: FilterOperationSessionState): void => {
+    if (disposed) {
+      return;
+    }
+    state = next;
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+        // Session transitions must not be interrupted by a faulty view subscriber.
+      }
+    }
+  };
+  const cleanupPreview = (): void => {
+    deps.clearPreview();
+    if (state.preview) {
+      publish({ ...state, preview: null });
+    }
+  };
+  const operation: CanvasOperationSession | null = deps.controller.start({
+    cleanupPreview,
+    guard,
+    identity: { kind: 'filter', layerId: guard.layerId, projectId: guard.projectId },
+  });
+  if (!operation) {
+    return null;
+  }
+
+  const process = async (): Promise<CanvasOperationRunResult> => {
+    if (disposed) {
+      return 'stale';
+    }
+    clearAutoProcess();
+    const requestDraft = structuredClone(state.draft);
+    publish({ ...state, error: null, preview: null, status: 'processing' });
+    const result = await operation.run(
+      async (signal) => {
+        const exported = await deps.exportPixels();
+        if (exported.status !== 'ok') {
+          throw new Error(`The filter source is ${exported.status}.`);
+        }
+        try {
+          if (!sameGuard(exported.guard, guard) || !deps.isGuardCurrent(guard)) {
+            throw new DOMException('The filter source became stale.', 'AbortError');
+          }
+          const filtered = await deps.runFilter({
+            filterType: requestDraft.type,
+            input: { rect: exported.rect, surface: exported.surface },
+            settings: requestDraft.settings,
+            signal,
+          });
+          if (signal.aborted || !deps.isGuardCurrent(guard)) {
+            throw new DOMException('The filter request was superseded.', 'AbortError');
+          }
+          const rect = { height: filtered.height, width: filtered.width, ...filtered.origin };
+          const shown = await deps.publishPreview(filtered.imageName, rect, guard, requestDraft.type);
+          if (signal.aborted || !deps.isGuardCurrent(guard)) {
+            throw new DOMException('The filter request was superseded.', 'AbortError');
+          }
+          if (shown !== 'shown') {
+            throw new DOMException('The filter source became stale.', 'AbortError');
+          }
+          return {
+            guard,
+            height: filtered.height,
+            imageName: filtered.imageName,
+            origin: filtered.origin,
+            rect,
+            width: filtered.width,
+          } satisfies FilterOperationPreview;
+        } finally {
+          exported.release();
+        }
+      },
+      (preview) => {
+        publish({ ...state, error: null, preview, status: 'ready' });
+        return undefined;
+      }
+    );
+    if (result === 'error') {
+      const operationState = deps.controller.getSnapshot();
+      publish({
+        ...state,
+        error: operationState.status === 'active' ? operationState.error : 'The filter failed.',
+        preview: null,
+        status: 'error',
+      });
+    }
+    return result;
+  };
+
+  const cancelCommit = (): void => {
+    commitToken += 1;
+    commitController?.abort();
+    commitController = null;
+  };
+
+  const commit = async (target: FilterCommitTarget): Promise<'committed' | 'blocked' | 'stale'> => {
+    const preview = state.preview;
+    if (disposed || !preview || state.status === 'processing' || state.status === 'committing') {
+      return 'stale';
+    }
+    if (!deps.canCommit()) {
+      return 'blocked';
+    }
+    clearAutoProcess();
+    cancelCommit();
+    const token = commitToken;
+    const controller = new AbortController();
+    commitController = controller;
+    publish({ ...state, error: null, status: 'committing' });
+    try {
+      if (!deps.canCommit()) {
+        publish({ ...state, error: null, status: 'ready' });
+        return 'blocked';
+      }
+      await deps.makeDurable(preview.imageName);
+      if (!deps.canCommit()) {
+        if (!disposed && token === commitToken) {
+          publish({ ...state, error: null, status: 'ready' });
+        }
+        return 'blocked';
+      }
+      if (disposed || token !== commitToken || controller.signal.aborted || !deps.isGuardCurrent(guard)) {
+        return 'stale';
+      }
+      const result = await deps.commit({
+        draft: structuredClone(state.draft),
+        guard,
+        image: { height: preview.height, imageName: preview.imageName, width: preview.width },
+        origin: preview.origin,
+        rect: preview.rect,
+        signal: controller.signal,
+        target,
+      });
+      if (result.status === 'committed') {
+        // The operation stays active: the owner ends it by disposing the
+        // session, keeping teardown out of this call stack.
+        publish({ ...state, error: null, preview: null, status: 'ready' });
+        return 'committed';
+      }
+      if (disposed || token !== commitToken || controller.signal.aborted) {
+        return 'stale';
+      }
+      publish({
+        ...state,
+        error: result.status === 'failed' ? result.message : `Filter commit is ${result.status}.`,
+        status: 'error',
+      });
+      return result.status === 'locked' ? 'blocked' : 'stale';
+    } catch (error) {
+      if (!disposed && token === commitToken && !controller.signal.aborted) {
+        publish({ ...state, error: message(error), status: 'error' });
+      }
+      return 'stale';
+    } finally {
+      if (token === commitToken) {
+        commitController = null;
+      }
+    }
+  };
+
+  const cancel = (): void => {
+    if (disposed) {
+      return;
+    }
+    clearAutoProcess();
+    cancelCommit();
+    operation.cancel();
+    publish({ ...state, error: null, preview: null, status: 'ready' });
+  };
+
+  return {
+    blockCommit: () => {
+      if (commitController) {
+        cancelCommit();
+        publish({ ...state, error: null, status: 'ready' });
+      }
+    },
+    cancel,
+    commit,
+    dispose: () => {
+      if (disposed) {
+        return;
+      }
+      clearAutoProcess();
+      cancelCommit();
+      operation.cancel();
+      disposed = true;
+      listeners.clear();
+    },
+    getSnapshot: () => state,
+    interruptProcessing: () => {
+      if (disposed) {
+        return;
+      }
+      clearAutoProcess();
+      if (state.status !== 'processing') {
+        return;
+      }
+      operation.interruptProcessing();
+      publish({ ...state, error: null, preview: null, status: 'ready' });
+    },
+    process,
+    reset: (settings) => {
+      if (disposed) {
+        return;
+      }
+      cancelCommit();
+      operation.reset();
+      publish({
+        ...state,
+        draft: { settings: structuredClone(settings), type: state.draft.type },
+        error: null,
+        preview: null,
+        status: 'ready',
+      });
+      scheduleAutoProcess();
+    },
+    setAutoProcess: (value) => {
+      if (disposed || state.autoProcess === value) {
+        return;
+      }
+      publish({ ...state, autoProcess: value });
+      if (!value) {
+        clearAutoProcess();
+        return;
+      }
+      if (!state.preview && state.status !== 'processing' && state.status !== 'committing') {
+        scheduleAutoProcess();
+      }
+    },
+    subscribe: (listener) => {
+      if (!disposed) {
+        listeners.add(listener);
+      }
+      return () => listeners.delete(listener);
+    },
+    updateDraft: (draft) => {
+      if (disposed) {
+        return;
+      }
+      cancelCommit();
+      operation.reset();
+      publish({ ...state, draft: structuredClone(draft), error: null, preview: null, status: 'ready' });
+      scheduleAutoProcess();
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/fullEngineImportAudit.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/fullEngineImportAudit.ts
new file mode 100644
index 00000000000..47e438d7e86
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/fullEngineImportAudit.ts
@@ -0,0 +1,37 @@
+const FULL_ENGINE_MODULE_PATTERN = String.raw`(?:@workbench/canvas-engine/engine|@workbench/canvas-operations/createCanvasEngine)`;
+const FULL_ENGINE_MODULE = new RegExp(String.raw`['"]${FULL_ENGINE_MODULE_PATTERN}['"]`);
+
+/** Detects every supported syntax that exposes or references the full CanvasEngine type. */
+export const referencesFullCanvasEngine = (source: string): boolean => {
+  const namedReference = new RegExp(
+    String.raw`(?:import|export)(?:\s+type)?\s*\{[^}]*\bCanvasEngine\b[^}]*\}\s*from\s*['"]${FULL_ENGINE_MODULE_PATTERN}['"]`,
+    's'
+  );
+  if (namedReference.test(source)) {
+    return true;
+  }
+
+  const starReExport = new RegExp(
+    String.raw`export\s*\*\s*(?:as\s+[A-Za-z_$][\w$]*\s*)?from\s*['"]${FULL_ENGINE_MODULE_PATTERN}['"]`
+  );
+  if (starReExport.test(source)) {
+    return true;
+  }
+
+  const inlineReference = new RegExp(
+    String.raw`import\s*\(\s*['"]${FULL_ENGINE_MODULE_PATTERN}['"]\s*\)\s*\.\s*CanvasEngine\b`
+  );
+  if (inlineReference.test(source)) {
+    return true;
+  }
+
+  const namespaceImport = /import(?:\s+type)?\s*\*\s*as\s*[A-Za-z_$][\w$]*\s*from\s*([^;\n]+)/g;
+  for (const match of source.matchAll(namespaceImport)) {
+    const moduleSource = match[1];
+    if (moduleSource && FULL_ENGINE_MODULE.test(moduleSource)) {
+      return true;
+    }
+  }
+
+  return false;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/fullEngineImports.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/fullEngineImports.test.ts
new file mode 100644
index 00000000000..ae4741a4fef
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/fullEngineImports.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { referencesFullCanvasEngine } from './fullEngineImportAudit';
+
+const modules = import.meta.glob('../**/*.{ts,tsx}', { eager: true, import: 'default', query: '?raw' });
+
+const ALLOWED = new Set(['./createCanvasEngine.ts', './engineRegistry.ts']);
+const fullEngineImports = (): string[] => {
+  const result: string[] = [];
+  for (const [file, source] of Object.entries(modules)) {
+    const relative = file.replace('../', '');
+    if (
+      relative.endsWith('.test.ts') ||
+      relative.endsWith('.test.tsx') ||
+      ALLOWED.has(relative) ||
+      typeof source !== 'string'
+    ) {
+      continue;
+    }
+    if (referencesFullCanvasEngine(source)) {
+      result.push(relative);
+    }
+  }
+  return result.sort();
+};
+
+describe('full CanvasEngine consumer boundary', () => {
+  it.each([
+    [`export type { CanvasEngine } from '@workbench/canvas-engine/engine';`, 'named type re-export'],
+    [`export { CanvasEngine as PublicEngine } from '@workbench/canvas-engine/engine';`, 'aliased re-export'],
+    [`export * from '@workbench/canvas-engine/engine';`, 'star re-export'],
+    [`export * as Core from '@workbench/canvas-engine/engine';`, 'namespace re-export'],
+    [
+      `import type * as Core from '@workbench/canvas-engine/engine'; type Consumer = Core.CanvasEngine;`,
+      'qualified namespace reference',
+    ],
+    [`import * as Core from '@workbench/canvas-engine/engine'; void Core;`, 'namespace import'],
+    [`type Consumer = import('@workbench/canvas-operations/createCanvasEngine').CanvasEngine;`, 'inline imported type'],
+  ])('detects $1', (source) => {
+    expect(referencesFullCanvasEngine(source)).toBe(true);
+  });
+
+  it('does not reject a named import of a narrow capability', () => {
+    expect(
+      referencesFullCanvasEngine(
+        `import type { CanvasCoreStores } from '@workbench/canvas-engine/engine'; type Stores = CanvasCoreStores;`
+      )
+    ).toBe(false);
+  });
+
+  it('limits the full engine type to registry and composition roots', () => {
+    expect(fullEngineImports()).toEqual([]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/importGalleryImages.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/importGalleryImages.test.ts
new file mode 100644
index 00000000000..123c79dfc02
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/importGalleryImages.test.ts
@@ -0,0 +1,598 @@
+import type { CanvasEngine } from '@workbench/canvas-engine/engine';
+import type { uploadCanvasImage } from '@workbench/canvas-operations/backend/canvasImages';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { GenerateWidgetValues } from '@workbench/generation/types';
+import type { CanvasLayerContract, Project, WorkbenchState } from '@workbench/types';
+
+import {
+  createControlLayer,
+  createEmptyPaintLayer,
+  createInpaintMaskFromImage,
+  createRegionalGuidanceFromImage,
+  createRegionalGuidanceLayerWithRefImage,
+  DEFAULT_INPAINT_MASK_FILL,
+  nextRegionalGuidanceFillColor,
+} from '@workbench/widgets/layers/layerOps';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { createInitialWorkbenchState, type WorkbenchAction } from '@workbench/workbenchState';
+import { describe, expect, it, vi } from 'vitest';
+
+import { importGalleryImagesToCanvas, type GalleryCanvasImportDestination } from './importGalleryImages';
+
+const image = (imageName: string, width = 320, height = 160): GalleryImage => ({
+  boardId: 'none',
+  height,
+  imageCategory: 'general',
+  imageName,
+  imageUrl: `https://images.example/${imageName}`,
+  queuedAt: '2026-01-01T00:00:00.000Z',
+  sourceQueueItemId: 'queue-1',
+  starred: false,
+  thumbnailUrl: `https://images.example/thumb/${imageName}`,
+  width,
+});
+
+const withProject = (mutate?: (project: Project) => Project): { project: Project; state: WorkbenchState } => {
+  const state = createInitialWorkbenchState();
+  const current = state.projects.find((candidate) => candidate.id === state.activeProjectId)!;
+  const document = {
+    ...current.canvas.document,
+    bbox: { height: 512, width: 768, x: 31, y: 47 },
+    layers: [createEmptyPaintLayer('Existing', 'previous')],
+    selectedLayerId: 'previous',
+  };
+  const base = { ...current, canvas: { ...current.canvas, document } };
+  const project = mutate ? mutate(base) : base;
+  return { project, state: { ...state, projects: [project] } };
+};
+
+const setModel = (project: Project, base: GenerateWidgetValues['model']['base']): Project => {
+  const generate = project.widgetInstances.generate;
+  if (!generate) {
+    throw new Error('Expected generate widget');
+  }
+  const previous = getProjectWidgetValues(project, 'generate');
+  const model = { base, key: 'test-model', name: 'Test Model', type: 'main' } as GenerateWidgetValues['model'];
+  const values: GenerateWidgetValues = {
+    aspectRatioId: '1:1',
+    aspectRatioIsLocked: false,
+    aspectRatioValue: 1,
+    batchCount: 1,
+    cfgRescaleMultiplier: 0,
+    cfgScale: 7,
+    clipEmbedModel: null,
+    clipGEmbedModel: null,
+    clipLEmbedModel: null,
+    clipSkip: 0,
+    colorCompensation: false,
+    componentSourceModel: null,
+    height: 1024,
+    loras: [],
+    negativePrompt: '',
+    negativePromptEnabled: true,
+    negativePromptHeightPx: 56,
+    positivePrompt: '',
+    positivePromptHeightPx: 96,
+    qwen3EncoderModel: null,
+    qwenVLEncoderModel: null,
+    referenceImages: [],
+    scheduler: 'euler_a',
+    seamlessXAxis: false,
+    seamlessYAxis: false,
+    seed: 1,
+    shouldRandomizeSeed: true,
+    steps: 30,
+    t5EncoderModel: null,
+    vae: null,
+    vaePrecision: 'fp32',
+    width: 1024,
+    ...previous,
+    model,
+    modelKey: model.key,
+  };
+  return {
+    ...project,
+    widgetInstances: {
+      ...project.widgetInstances,
+      generate: {
+        ...generate,
+        state: { ...generate.state, values: values as unknown as Record<string, unknown> },
+      },
+    },
+  };
+};
+
+const engine = (
+  projectId: string,
+  canCommitStructural: CanvasEngine['layers']['canCommitStructural'] = vi.fn(() => true),
+  commitStructural: CanvasEngine['layers']['commitStructural'] = vi.fn(() => true)
+): CanvasEngine => ({ layers: { canCommitStructural, commitStructural }, projectId }) as unknown as CanvasEngine;
+
+const getForwardLayers = (action: WorkbenchAction | CanvasProjectMutation): readonly CanvasLayerContract[] => {
+  const mutation = action.type === 'applyCanvasProjectMutation' ? action.mutation : action;
+  if (mutation.type !== 'applyCanvasLayerStackMutation' || !mutation.add) {
+    throw new Error('Expected add stack mutation');
+  }
+  return mutation.add.layers;
+};
+
+const expectedLayer = (
+  destination: Exclude<GalleryCanvasImportDestination, 'control-resized'>,
+  source: GalleryImage,
+  index: number,
+  bbox: Project['canvas']['document']['bbox'],
+  base: string | null
+): CanvasLayerContract => {
+  const ref = { height: source.height, imageName: source.imageName, width: source.width };
+  switch (destination) {
+    case 'raster':
+      return {
+        blendMode: 'normal',
+        id: expect.any(String) as string,
+        isEnabled: true,
+        isLocked: false,
+        name: `Layer ${index + 1}`,
+        opacity: 1,
+        source: { image: ref, type: 'image' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: bbox.x, y: bbox.y },
+        type: 'raster',
+      };
+    case 'control':
+      return {
+        ...createControlLayer(`Control Layer ${index + 1}`, 'expected', base),
+        id: expect.any(String) as string,
+        source: { image: ref, type: 'image' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: bbox.x, y: bbox.y },
+      };
+    case 'inpaint-mask':
+      return createInpaintMaskFromImage({
+        fill: DEFAULT_INPAINT_MASK_FILL,
+        id: expect.any(String) as string,
+        image: ref,
+        name: `Inpaint Mask ${index + 1}`,
+        rect: bbox,
+      });
+    case 'regional-guidance':
+      return createRegionalGuidanceFromImage({
+        fill: { color: nextRegionalGuidanceFillColor(index), style: 'solid' },
+        id: expect.any(String) as string,
+        image: ref,
+        name: `Regional Guidance ${index + 1}`,
+        rect: bbox,
+      });
+    case 'regional-reference': {
+      const layer = createRegionalGuidanceLayerWithRefImage(`Regional Guidance ${index + 1}`, index, base);
+      const reference = layer.referenceImages[0]!;
+      return {
+        ...layer,
+        id: expect.any(String) as string,
+        referenceImages: [
+          { ...reference, config: { ...reference.config, image: source }, id: expect.any(String) as string },
+        ],
+      };
+    }
+  }
+};
+
+describe('importGalleryImagesToCanvas', () => {
+  it.each<Exclude<GalleryCanvasImportDestination, 'control-resized'>>([
+    'raster',
+    'control',
+    'inpaint-mask',
+    'regional-guidance',
+    'regional-reference',
+  ])('builds the %s destination contract in input order and commits one history entry', async (destination) => {
+    const { project, state } = withProject((value) => setModel(value, 'z-image'));
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const canvasEngine = engine(project.id);
+    const images = [image('first.png'), image('second.png', 640, 480)];
+
+    const result = await importGalleryImagesToCanvas({
+      destination,
+      dispatch,
+      engine: canvasEngine,
+      getState: () => state,
+      images,
+      project,
+    });
+
+    expect(result.status).toBe('imported');
+    if (result.status !== 'imported') {
+      return;
+    }
+    expect(result.failedImageNames).toEqual([]);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(canvasEngine.layers.commitStructural).toHaveBeenCalledOnce();
+    const [, forward, inverse] = vi.mocked(canvasEngine.layers.commitStructural).mock.calls[0]!;
+    const layers = getForwardLayers(forward);
+    expect(layers).toEqual(
+      images.map((source, index) => expectedLayer(destination, source, index, project.canvas.document.bbox, 'z-image'))
+    );
+    expect(result.layerIds).toEqual(layers.map((layer) => layer.id));
+    expect(forward).toMatchObject({
+      add: { index: 0 },
+      enabledUpdates: [],
+      selectedLayerId: layers[1]!.id,
+      type: 'applyCanvasLayerStackMutation',
+    });
+    expect(inverse).toEqual({
+      enabledUpdates: [],
+      removeIds: layers.map((layer) => layer.id),
+      selectedLayerId: 'previous',
+      type: 'applyCanvasLayerStackMutation',
+    });
+  });
+
+  it('fetches and uploads each resized control once with optimal model dimensions and durable hidden policy', async () => {
+    const { project, state } = withProject((value) => setModel(value, 'flux2'));
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const fetchImage = vi.fn<typeof fetch>(() => Promise.resolve(new Response(new Blob(['pixels']), { status: 200 })));
+    const uploadImage = vi.fn<typeof uploadCanvasImage>((_blob, options) =>
+      Promise.resolve({
+        height: options!.resizeTo!.height,
+        imageName: `resized-${options!.fileName}`,
+        width: options!.resizeTo!.width,
+      })
+    );
+
+    const result = await importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch,
+      engine: null,
+      fetchImage,
+      getState: () => state,
+      images: [image('wide.png', 1600, 900), image('square.png', 400, 400)],
+      project,
+      uploadImage,
+    });
+
+    expect(result.status).toBe('imported');
+    expect(fetchImage.mock.calls.map(([url]) => url)).toEqual([
+      'https://images.example/wide.png',
+      'https://images.example/square.png',
+    ]);
+    expect(uploadImage).toHaveBeenCalledTimes(2);
+    expect(uploadImage.mock.calls.map(([, options]) => options)).toEqual([
+      expect.objectContaining({
+        fileName: 'wide.png',
+        imageCategory: 'other',
+        isIntermediate: false,
+        resizeTo: { height: 768, width: 1360 },
+      }),
+      expect.objectContaining({
+        fileName: 'square.png',
+        imageCategory: 'other',
+        isIntermediate: false,
+        resizeTo: { height: 1024, width: 1024 },
+      }),
+    ]);
+    expect(dispatch).toHaveBeenCalledOnce();
+    const forward = dispatch.mock.calls[0]![0];
+    const layers = getForwardLayers(forward);
+    expect(layers).toEqual([
+      {
+        ...createControlLayer('Control Layer 1', 'expected', 'flux2'),
+        id: expect.any(String),
+        source: { image: { height: 768, imageName: 'resized-wide.png', width: 1360 }, type: 'image' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 31, y: 47 },
+      },
+      {
+        ...createControlLayer('Control Layer 2', 'expected', 'flux2'),
+        id: expect.any(String),
+        source: { image: { height: 1024, imageName: 'resized-square.png', width: 1024 }, type: 'image' },
+        transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 31, y: 47 },
+      },
+    ]);
+    expect(
+      layers.map((layer) => (layer.type === 'control' && layer.source.type === 'image' ? layer.source.image : null))
+    ).toEqual([
+      { height: 768, imageName: 'resized-wide.png', width: 1360 },
+      { height: 1024, imageName: 'resized-square.png', width: 1024 },
+    ]);
+    expect(forward).toMatchObject({
+      mutation: {
+        selectedLayerId: layers[1]!.id,
+        type: 'applyCanvasLayerStackMutation',
+      },
+      projectId: project.id,
+      type: 'applyCanvasProjectMutation',
+    });
+  });
+
+  it('returns empty without committing', async () => {
+    const { project, state } = withProject();
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const result = await importGalleryImagesToCanvas({
+      destination: 'raster',
+      dispatch,
+      engine: null,
+      getState: () => state,
+      images: [],
+      project,
+    });
+    expect(result).toEqual({ status: 'empty' });
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+
+  it('blocks a locked matching engine before resized preprocessing', async () => {
+    const { project, state } = withProject();
+    const fetchImage = vi.fn<typeof fetch>();
+    const uploadImage = vi.fn<typeof uploadCanvasImage>();
+    const result = await importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch: vi.fn(),
+      engine: engine(
+        project.id,
+        vi.fn(() => false)
+      ),
+      fetchImage,
+      getState: () => state,
+      images: [image('a.png')],
+      project,
+      uploadImage,
+    });
+    expect(result).toEqual({ status: 'blocked' });
+    expect(fetchImage).not.toHaveBeenCalled();
+    expect(uploadImage).not.toHaveBeenCalled();
+  });
+
+  it('returns blocked when the matching engine locks during preprocessing', async () => {
+    const { project, state } = withProject();
+    const fetchImage = vi.fn<typeof fetch>(() => Promise.resolve(new Response(new Blob(['pixels']), { status: 200 })));
+    const uploadImage = vi.fn<typeof uploadCanvasImage>(() =>
+      Promise.resolve({ height: 512, imageName: 'resized', width: 512 })
+    );
+    const commitStructural = vi.fn<
+      (_label: string, _forward: CanvasProjectMutation, _inverse: CanvasProjectMutation) => boolean
+    >(() => false);
+    const result = await importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch: vi.fn(),
+      engine: engine(
+        project.id,
+        vi.fn(() => true),
+        commitStructural
+      ),
+      fetchImage,
+      getState: () => state,
+      images: [image('a.png')],
+      project,
+      uploadImage,
+    });
+    expect(result).toEqual({ status: 'blocked' });
+    expect(commitStructural).toHaveBeenCalledOnce();
+    const [, forward, inverse] = commitStructural.mock.calls[0]!;
+    const layers = getForwardLayers(forward);
+    expect(inverse).toEqual({
+      enabledUpdates: [],
+      removeIds: layers.map((layer) => layer.id),
+      selectedLayerId: 'previous',
+      type: 'applyCanvasLayerStackMutation',
+    });
+  });
+
+  it('returns stale-project when the target is deleted during preprocessing', async () => {
+    const { project, state } = withProject();
+    let current = state;
+    const uploadImage = vi.fn<typeof uploadCanvasImage>(() => {
+      current = { ...current, projects: [] };
+      return Promise.resolve({ height: 512, imageName: 'resized', width: 512 });
+    });
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const result = await importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch,
+      engine: null,
+      fetchImage: () => Promise.resolve(new Response(new Blob(['pixels']), { status: 200 })),
+      getState: () => current,
+      images: [image('a.png')],
+      project,
+      uploadImage,
+    });
+    expect(result).toEqual({ status: 'stale-project' });
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+
+  it('dispatches to the captured project when the active project changes during preprocessing', async () => {
+    const { project, state } = withProject();
+    const other = { ...project, id: 'other-project' };
+    let current = { ...state, projects: [project, other] };
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const matchingEngine = engine(project.id);
+    const uploadImage = vi.fn<typeof uploadCanvasImage>(() => {
+      current = { ...current, activeProjectId: other.id };
+      return Promise.resolve({ height: 512, imageName: 'resized', width: 512 });
+    });
+    const result = await importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch,
+      engine: matchingEngine,
+      fetchImage: () => Promise.resolve(new Response(new Blob(['pixels']), { status: 200 })),
+      getState: () => current,
+      images: [image('a.png')],
+      project,
+      uploadImage,
+    });
+    expect(result.status).toBe('imported');
+    expect(matchingEngine.layers.commitStructural).not.toHaveBeenCalled();
+    expect(dispatch).toHaveBeenCalledOnce();
+    expect(dispatch.mock.calls[0]![0]).toMatchObject({ projectId: project.id });
+  });
+
+  it('uses the matching engine final guard when the target project becomes active during preprocessing', async () => {
+    const { project, state } = withProject();
+    const other = { ...project, id: 'other-project' };
+    let current = { ...state, activeProjectId: other.id, projects: [project, other] };
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const commitStructural = vi.fn(() => false);
+    const matchingEngine = engine(
+      project.id,
+      vi.fn(() => true),
+      commitStructural
+    );
+    const uploadImage = vi.fn<typeof uploadCanvasImage>(() => {
+      current = { ...current, activeProjectId: project.id };
+      return Promise.resolve({ height: 512, imageName: 'resized', width: 512 });
+    });
+
+    const result = await importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch,
+      engine: matchingEngine,
+      fetchImage: () => Promise.resolve(new Response(new Blob(['pixels']), { status: 200 })),
+      getState: () => current,
+      images: [image('a.png')],
+      project,
+      uploadImage,
+    });
+
+    expect(result).toEqual({ status: 'blocked' });
+    expect(commitStructural).toHaveBeenCalledOnce();
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+
+  it('returns stale-document when the captured target document identity changes', async () => {
+    const { project, state } = withProject();
+    let current = state;
+    const uploadImage = vi.fn<typeof uploadCanvasImage>(() => {
+      current = {
+        ...current,
+        projects: current.projects.map((candidate) =>
+          candidate.id === project.id
+            ? { ...candidate, canvas: { ...candidate.canvas, document: { ...candidate.canvas.document } } }
+            : candidate
+        ),
+      };
+      return Promise.resolve({ height: 512, imageName: 'resized', width: 512 });
+    });
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const result = await importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch,
+      engine: null,
+      fetchImage: () => Promise.resolve(new Response(new Blob(['pixels']), { status: 200 })),
+      getState: () => current,
+      images: [image('a.png')],
+      project,
+      uploadImage,
+    });
+    expect(result).toEqual({ status: 'stale-document' });
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+
+  it('single-flights imports per project while allowing other projects', async () => {
+    const first = withProject();
+    const secondProject = { ...first.project, id: 'second-project' };
+    const secondState = { ...first.state, activeProjectId: secondProject.id, projects: [secondProject] };
+    let release!: () => void;
+    const pending = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const fetchImage = vi.fn<typeof fetch>(async () => {
+      await pending;
+      return new Response(new Blob(['pixels']), { status: 200 });
+    });
+    const uploadImage = vi.fn<typeof uploadCanvasImage>(() =>
+      Promise.resolve({ height: 512, imageName: 'resized', width: 512 })
+    );
+    const firstImport = importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch: vi.fn(),
+      engine: null,
+      fetchImage,
+      getState: () => first.state,
+      images: [image('a.png')],
+      project: first.project,
+      uploadImage,
+    });
+    const overlap = await importGalleryImagesToCanvas({
+      destination: 'raster',
+      dispatch: vi.fn(),
+      engine: null,
+      getState: () => first.state,
+      images: [image('b.png')],
+      project: first.project,
+    });
+    const independent = await importGalleryImagesToCanvas({
+      destination: 'raster',
+      dispatch: vi.fn(),
+      engine: null,
+      getState: () => secondState,
+      images: [image('c.png')],
+      project: secondProject,
+    });
+    expect(overlap).toEqual({ status: 'blocked' });
+    expect(independent.status).toBe('imported');
+    release();
+    await firstImport;
+  });
+
+  it('bounds resized work at four, preserves successful order, and reports partial failures once', async () => {
+    const { project, state } = withProject();
+    let active = 0;
+    let maximum = 0;
+    const releases: Array<() => void> = [];
+    const fetchImage = vi.fn<typeof fetch>(async (_input) => {
+      active += 1;
+      maximum = Math.max(maximum, active);
+      await new Promise<void>((resolve) => {
+        releases.push(resolve);
+      });
+      active -= 1;
+      return new Response(new Blob(['pixels']), { status: 200 });
+    });
+    const uploadImage = vi.fn<typeof uploadCanvasImage>((_blob, options) => {
+      if (options!.fileName === '2.png' || options!.fileName === '5.png') {
+        return Promise.reject(new Error('resize failed'));
+      }
+      return Promise.resolve({ height: 512, imageName: `ok-${options!.fileName}`, width: 512 });
+    });
+    const dispatch = vi.fn<(action: WorkbenchAction) => void>();
+    const importing = importGalleryImagesToCanvas({
+      destination: 'control-resized',
+      dispatch,
+      engine: null,
+      fetchImage,
+      getState: () => state,
+      images: Array.from({ length: 7 }, (_, index) => image(`${index}.png`)),
+      project,
+      uploadImage,
+    });
+    await vi.waitFor(() => expect(fetchImage).toHaveBeenCalledTimes(4));
+    expect(maximum).toBe(4);
+    releases.splice(0).forEach((resolve) => resolve());
+    await vi.waitFor(() => expect(fetchImage).toHaveBeenCalledTimes(7));
+    releases.splice(0).forEach((resolve) => resolve());
+    const result = await importing;
+    expect(result.status).toBe('imported');
+    if (result.status !== 'imported') {
+      return;
+    }
+    expect(result.failedImageNames).toEqual(['2.png', '5.png']);
+    expect(dispatch).toHaveBeenCalledOnce();
+    expect(
+      getForwardLayers(dispatch.mock.calls[0]![0]).map((layer) =>
+        layer.type === 'control' && layer.source.type === 'image' ? layer.source.image.imageName : null
+      )
+    ).toEqual(['ok-0.png', 'ok-1.png', 'ok-3.png', 'ok-4.png', 'ok-6.png']);
+  });
+
+  it('throws one AggregateError when every resized image fails and releases the project flight', async () => {
+    const { project, state } = withProject();
+    const options = {
+      destination: 'control-resized' as const,
+      dispatch: vi.fn(),
+      engine: null,
+      fetchImage: () => Promise.resolve(new Response(new Blob(['pixels']), { status: 200 })),
+      getState: () => state,
+      images: [image('a.png'), image('b.png')],
+      project,
+      uploadImage: vi.fn<typeof uploadCanvasImage>(() => Promise.reject(new Error('failed'))),
+    };
+    await expect(importGalleryImagesToCanvas(options)).rejects.toBeInstanceOf(AggregateError);
+    await expect(importGalleryImagesToCanvas({ ...options, destination: 'raster' })).resolves.toMatchObject({
+      status: 'imported',
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/importGalleryImages.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/importGalleryImages.ts
new file mode 100644
index 00000000000..302eda495ba
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/importGalleryImages.ts
@@ -0,0 +1,300 @@
+import type { CanvasLayerCapability } from '@workbench/canvas-engine/api';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { CanvasImageRef, CanvasLayerContract, Project, WorkbenchState } from '@workbench/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+import type { Dispatch } from 'react';
+
+import { getGenerationDimensions } from '@workbench/generation/baseGenerationPolicies';
+import { calculateNewSize, normalizeGenerateWidgetValues } from '@workbench/generation/settings';
+import {
+  createControlLayer,
+  createEmptyPaintLayer,
+  createInpaintMaskFromImage,
+  createLayerId,
+  createRegionalGuidanceFromImage,
+  createRegionalGuidanceLayerWithRefImage,
+  DEFAULT_INPAINT_MASK_FILL,
+  nextControlLayerName,
+  nextInpaintMaskName,
+  nextRegionalGuidanceFillColor,
+  nextRegionalGuidanceName,
+} from '@workbench/widgets/layers/layerOps';
+import { getSelectedModelBase } from '@workbench/widgets/layers/selectedModel';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { nextLayerName } from '@workbench/workbenchState';
+
+import { uploadCanvasImage } from './backend/canvasImages';
+
+export type GalleryCanvasImportDestination =
+  | 'raster'
+  | 'control'
+  | 'inpaint-mask'
+  | 'regional-guidance'
+  | 'regional-reference'
+  | 'control-resized';
+
+export type ImportGalleryImagesResult =
+  | { status: 'imported'; layerIds: string[]; failedImageNames: string[] }
+  | { status: 'blocked' | 'empty' | 'stale-document' | 'stale-project' };
+
+interface BuildLayerContext {
+  bbox: Project['canvas']['document']['bbox'];
+  existingLayers: readonly CanvasLayerContract[];
+  modelBase: string | null;
+}
+
+type LayerImage = CanvasImageRef | GalleryImage;
+
+const activeImports = new Set<string>();
+
+const imageRef = (image: LayerImage): CanvasImageRef => ({
+  height: image.height,
+  imageName: image.imageName,
+  width: image.width,
+});
+
+const isGeneratedImage = (image: LayerImage): image is GalleryImage => 'imageUrl' in image;
+
+const withBboxOrigin = <T extends CanvasLayerContract>(layer: T, bbox: BuildLayerContext['bbox']): T => ({
+  ...layer,
+  transform: { ...layer.transform, x: bbox.x, y: bbox.y },
+});
+
+const buildLayer = (
+  image: LayerImage,
+  destination: GalleryCanvasImportDestination,
+  context: BuildLayerContext
+): CanvasLayerContract => {
+  const id = createLayerId();
+  const names = context.existingLayers.map((layer) => layer.name);
+  const ref = imageRef(image);
+
+  switch (destination) {
+    case 'raster':
+      return withBboxOrigin(
+        { ...createEmptyPaintLayer(nextLayerName(names), id), source: { image: ref, type: 'image' } },
+        context.bbox
+      );
+    case 'control':
+    case 'control-resized':
+      return withBboxOrigin(
+        {
+          ...createControlLayer(nextControlLayerName(names), id, context.modelBase),
+          source: { image: ref, type: 'image' },
+        },
+        context.bbox
+      );
+    case 'inpaint-mask':
+      return createInpaintMaskFromImage({
+        fill: DEFAULT_INPAINT_MASK_FILL,
+        id,
+        image: ref,
+        name: nextInpaintMaskName(names),
+        rect: context.bbox,
+      });
+    case 'regional-guidance': {
+      const regionalGuidanceCount = context.existingLayers.filter((layer) => layer.type === 'regional_guidance').length;
+      return createRegionalGuidanceFromImage({
+        fill: { color: nextRegionalGuidanceFillColor(regionalGuidanceCount), style: 'solid' },
+        id,
+        image: ref,
+        name: nextRegionalGuidanceName(names),
+        rect: context.bbox,
+      });
+    }
+    case 'regional-reference': {
+      const regionalGuidanceCount = context.existingLayers.filter((layer) => layer.type === 'regional_guidance').length;
+      const layer = createRegionalGuidanceLayerWithRefImage(
+        nextRegionalGuidanceName(names),
+        regionalGuidanceCount,
+        context.modelBase,
+        id
+      );
+      const referenceImage = layer.referenceImages[0];
+      if (!referenceImage) {
+        throw new Error('Regional reference factory did not create a reference image');
+      }
+      if (!isGeneratedImage(image)) {
+        throw new Error('Regional reference imports require a gallery image');
+      }
+      return {
+        ...layer,
+        referenceImages: [{ ...referenceImage, config: { ...referenceImage.config, image } }],
+      };
+    }
+  }
+};
+
+const buildLayers = (
+  images: readonly LayerImage[],
+  destination: GalleryCanvasImportDestination,
+  project: Project
+): CanvasLayerContract[] => {
+  const layers: CanvasLayerContract[] = [];
+  const modelBase = getSelectedModelBase(project);
+  for (const image of images) {
+    layers.push(
+      buildLayer(image, destination, {
+        bbox: project.canvas.document.bbox,
+        existingLayers: [...project.canvas.document.layers, ...layers],
+        modelBase,
+      })
+    );
+  }
+  return layers;
+};
+
+const mapWithConcurrency = async <T, R>(
+  items: readonly T[],
+  concurrency: number,
+  mapper: (item: T, index: number) => Promise<R>
+): Promise<R[]> => {
+  const results: R[] = [];
+  let nextIndex = 0;
+  const worker = async (): Promise<void> => {
+    while (nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await mapper(items[index]!, index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+  return results;
+};
+
+type ResizeResult =
+  | { status: 'fulfilled'; image: LayerImage }
+  | { status: 'rejected'; imageName: string; reason: unknown };
+
+const resizeImages = async (
+  images: readonly GalleryImage[],
+  project: Project,
+  fetchImage: typeof fetch,
+  uploadImage: typeof uploadCanvasImage
+): Promise<{ images: LayerImage[]; failedImageNames: string[] }> => {
+  const generateValues = normalizeGenerateWidgetValues(getProjectWidgetValues(project, 'generate'));
+  const dimensions = getGenerationDimensions(generateValues?.model);
+  const results = await mapWithConcurrency(images, 4, async (image): Promise<ResizeResult> => {
+    try {
+      const response = await fetchImage(image.imageUrl);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${image.imageName}: ${response.status} ${response.statusText}`);
+      }
+      const blob = await response.blob();
+      const resizeTo = calculateNewSize(image.width / image.height, dimensions.optimal ** 2, dimensions.grid);
+      const uploaded = await uploadImage(blob, {
+        fileName: image.imageName,
+        imageCategory: 'other',
+        isIntermediate: false,
+        resizeTo,
+      });
+      return { image: uploaded, status: 'fulfilled' };
+    } catch (reason) {
+      return { imageName: image.imageName, reason, status: 'rejected' };
+    }
+  });
+  const successful = results.filter(
+    (result): result is Extract<ResizeResult, { status: 'fulfilled' }> => result.status === 'fulfilled'
+  );
+  const failed = results.filter(
+    (result): result is Extract<ResizeResult, { status: 'rejected' }> => result.status === 'rejected'
+  );
+  if (successful.length === 0 && failed.length > 0) {
+    throw new AggregateError(
+      failed.map((result) => result.reason),
+      `Failed to resize ${String(failed.length)} gallery image${failed.length === 1 ? '' : 's'}`
+    );
+  }
+  return {
+    failedImageNames: failed.map((result) => result.imageName),
+    images: successful.map((result) => result.image),
+  };
+};
+
+type GalleryImportEngine = { readonly projectId: string; readonly layers: CanvasLayerCapability };
+
+export const importGalleryImagesToCanvas = async (options: {
+  destination: GalleryCanvasImportDestination;
+  dispatch: Dispatch<WorkbenchAction>;
+  engine: GalleryImportEngine | null;
+  getState: () => WorkbenchState;
+  images: readonly GalleryImage[];
+  project: Project;
+  fetchImage?: typeof fetch;
+  uploadImage?: typeof uploadCanvasImage;
+}): Promise<ImportGalleryImagesResult> => {
+  const {
+    destination,
+    dispatch,
+    engine,
+    fetchImage = globalThis.fetch,
+    getState,
+    images,
+    project,
+    uploadImage = uploadCanvasImage,
+  } = options;
+  if (images.length === 0) {
+    return { status: 'empty' };
+  }
+  if (activeImports.has(project.id)) {
+    return { status: 'blocked' };
+  }
+  activeImports.add(project.id);
+
+  try {
+    const capturedDocument = project.canvas.document;
+    const initialState = getState();
+    const matchingProjectEngine = engine !== null && engine.projectId === project.id ? engine : null;
+    if (
+      matchingProjectEngine &&
+      initialState.activeProjectId === project.id &&
+      !matchingProjectEngine.layers.canCommitStructural()
+    ) {
+      return { status: 'blocked' };
+    }
+
+    let layerImages: readonly LayerImage[] = images;
+    let failedImageNames: string[] = [];
+    if (destination === 'control-resized') {
+      const resized = await resizeImages(images, project, fetchImage, uploadImage);
+      layerImages = resized.images;
+      failedImageNames = resized.failedImageNames;
+    }
+
+    const layers = buildLayers(layerImages, destination, project);
+    const previousSelectedLayerId = capturedDocument.selectedLayerId;
+    const forward: CanvasProjectMutation = {
+      add: { index: 0, layers },
+      enabledUpdates: [],
+      selectedLayerId: layers.at(-1)?.id ?? previousSelectedLayerId,
+      type: 'applyCanvasLayerStackMutation',
+    };
+    const inverse: CanvasProjectMutation = {
+      enabledUpdates: [],
+      removeIds: layers.map((layer) => layer.id),
+      selectedLayerId: previousSelectedLayerId,
+      type: 'applyCanvasLayerStackMutation',
+    };
+
+    const latestState = getState();
+    const latestProject = latestState.projects.find((candidate) => candidate.id === project.id);
+    if (!latestProject) {
+      return { status: 'stale-project' };
+    }
+    if (latestProject.canvas.document !== capturedDocument) {
+      return { status: 'stale-document' };
+    }
+
+    if (matchingProjectEngine && latestState.activeProjectId === project.id) {
+      if (!matchingProjectEngine.layers.commitStructural('Import gallery images', forward, inverse)) {
+        return { status: 'blocked' };
+      }
+    } else {
+      dispatch({ mutation: forward, projectId: project.id, type: 'applyCanvasProjectMutation' });
+    }
+    return { failedImageNames, layerIds: layers.map((layer) => layer.id), status: 'imported' };
+  } finally {
+    activeImports.delete(project.id);
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/layerFilterRunner.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerFilterRunner.test.ts
new file mode 100644
index 00000000000..1f3708a09c9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerFilterRunner.test.ts
@@ -0,0 +1,255 @@
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it } from 'vitest';
+
+import { LayerFilterOutputDimensionError, resolveFilterOutputRect, runLayerFilter } from './layerFilterRunner';
+
+describe('resolveFilterOutputRect', () => {
+  const source = { height: 60, width: 80, x: 12, y: 24 };
+
+  it.each([
+    ['gaussian', 2.1, { height: 74, width: 94, x: 5, y: 17 }],
+    ['box', 2.1, { height: 66, width: 86, x: 9, y: 21 }],
+  ] as const)('uses exact legacy %s blur padding and actual output dimensions', (blurType, radius, expected) => {
+    expect(
+      resolveFilterOutputRect({
+        filterType: 'img_blur',
+        output: { height: expected.height, width: expected.width },
+        settings: { blur_type: blurType, radius },
+        source,
+      })
+    ).toEqual(expected);
+  });
+
+  it('keeps the legacy Spandrel origin while adopting actual upscale dimensions', () => {
+    expect(
+      resolveFilterOutputRect({
+        filterType: 'spandrel_filter',
+        output: { height: 240, width: 320 },
+        settings: { scale: 4 },
+        source,
+      })
+    ).toEqual({ height: 240, width: 320, x: 12, y: 24 });
+  });
+
+  it.each([
+    [Number.NaN, 4],
+    [5_000, 12 - 4_096],
+  ])('uses the graph-resolved blur radius for malformed or oversized input %s', (radius, expectedX) => {
+    expect(
+      resolveFilterOutputRect({
+        filterType: 'img_blur',
+        output: { height: 60, width: 80 },
+        settings: { blur_type: 'box', radius },
+        source,
+      }).x
+    ).toBe(expectedX);
+  });
+
+  it('rejects wrong metadata dimensions for dimension-preserving filters', () => {
+    expect(() =>
+      resolveFilterOutputRect({
+        filterType: 'canny_edge_detection',
+        output: { height: 999, width: 999 },
+        source,
+      })
+    ).toThrow(LayerFilterOutputDimensionError);
+  });
+
+  it('retains the source rect for exact dimension-preserving output', () => {
+    expect(
+      resolveFilterOutputRect({ filterType: 'canny_edge_detection', output: { height: 60, width: 80 }, source })
+    ).toEqual(source);
+  });
+});
+
+describe('runLayerFilter', () => {
+  it('returns an actionable typed error for wrong dimension-preserving output metadata', async () => {
+    const surface = createTestStubRasterBackend().createSurface(80, 60);
+
+    await expect(
+      runLayerFilter({
+        deps: {
+          encodeSurface: () => Promise.resolve(new Blob()),
+          runFilterGraph: () => Promise.resolve({ height: 60, imageName: 'wrong', width: 79 }),
+          uploadIntermediate: () => Promise.resolve({ imageName: 'input' }),
+        },
+        filterType: 'canny_edge_detection',
+        input: { rect: { height: 60, width: 80, x: 12, y: 24 }, surface },
+      })
+    ).rejects.toMatchObject({
+      code: 'output-dimension',
+      message: 'Canny Edge Detection output dimensions 79x60 do not match source dimensions 80x60.',
+    });
+  });
+
+  it('encodes, uploads, builds, and runs a filter in order', async () => {
+    const surface = createTestStubRasterBackend().createSurface(80, 60);
+    const blob = new Blob(['pixels'], { type: 'image/png' });
+    const calls: string[] = [];
+    const signal = new AbortController().signal;
+
+    const result = await runLayerFilter({
+      deps: {
+        encodeSurface: (receivedSurface) => {
+          expect(receivedSurface).toBe(surface);
+          calls.push('encode');
+          return Promise.resolve(blob);
+        },
+        runFilterGraph: ({ graph, outputNodeId, signal: receivedSignal }) => {
+          calls.push('run');
+          expect(graph.nodes.control_filter).toMatchObject({
+            high_threshold: 200,
+            image: { image_name: 'input' },
+            low_threshold: 100,
+            type: 'canny_edge_detection',
+          });
+          expect(outputNodeId).toBe('control_filter');
+          expect(receivedSignal).toBe(signal);
+          return Promise.resolve({ height: 60, imageName: 'output', width: 80 });
+        },
+        uploadIntermediate: (receivedBlob, receivedSignal) => {
+          expect(receivedBlob).toBe(blob);
+          expect(receivedSignal).toBe(signal);
+          calls.push('upload');
+          return Promise.resolve({ imageName: 'input' });
+        },
+      },
+      filterType: 'canny_edge_detection',
+      input: { rect: { height: 60, width: 80, x: 12, y: 24 }, surface },
+      settings: { high_threshold: 200, low_threshold: 100 },
+      signal,
+    });
+
+    expect(calls).toEqual(['encode', 'upload', 'run']);
+    expect(result).toEqual({ height: 60, imageName: 'output', origin: { x: 12, y: 24 }, width: 80 });
+  });
+
+  it('rejects a pre-aborted request without invoking dependencies', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const calls: string[] = [];
+
+    await expect(
+      runLayerFilter({
+        deps: {
+          encodeSurface: () => {
+            calls.push('encode');
+            return Promise.resolve(new Blob());
+          },
+          runFilterGraph: () => {
+            calls.push('run');
+            return Promise.resolve({ height: 1, imageName: 'output', width: 1 });
+          },
+          uploadIntermediate: () => {
+            calls.push('upload');
+            return Promise.resolve({ imageName: 'input' });
+          },
+        },
+        filterType: 'canny_edge_detection',
+        input: {
+          rect: { height: 1, width: 1, x: 0, y: 0 },
+          surface: createTestStubRasterBackend().createSurface(1, 1),
+        },
+        signal: controller.signal,
+      })
+    ).rejects.toMatchObject({ name: 'AbortError' });
+    expect(calls).toEqual([]);
+  });
+
+  it('does not build or run the graph after upload aborts the request', async () => {
+    const controller = new AbortController();
+    const calls: string[] = [];
+
+    await expect(
+      runLayerFilter({
+        deps: {
+          encodeSurface: () => {
+            calls.push('encode');
+            return Promise.resolve(new Blob());
+          },
+          runFilterGraph: () => {
+            calls.push('run');
+            return Promise.resolve({ height: 1, imageName: 'output', width: 1 });
+          },
+          uploadIntermediate: () => {
+            calls.push('upload');
+            controller.abort();
+            return Promise.resolve({ imageName: 'input' });
+          },
+        },
+        filterType: 'canny_edge_detection',
+        input: {
+          rect: { height: 1, width: 1, x: 0, y: 0 },
+          surface: createTestStubRasterBackend().createSurface(1, 1),
+        },
+        signal: controller.signal,
+      })
+    ).rejects.toMatchObject({ name: 'AbortError' });
+    expect(calls).toEqual(['encode', 'upload']);
+  });
+
+  it('forwards cancellation into an in-flight upload', async () => {
+    const controller = new AbortController();
+    let uploadSignal: AbortSignal | undefined;
+
+    const pending = runLayerFilter({
+      deps: {
+        encodeSurface: () => Promise.resolve(new Blob()),
+        runFilterGraph: () => Promise.resolve({ height: 1, imageName: 'output', width: 1 }),
+        uploadIntermediate: (_blob, signal) => {
+          uploadSignal = signal;
+          return new Promise((_resolve, reject) => {
+            signal?.addEventListener('abort', () => reject(new DOMException('aborted', 'AbortError')), { once: true });
+          });
+        },
+      },
+      filterType: 'canny_edge_detection',
+      input: {
+        rect: { height: 1, width: 1, x: 0, y: 0 },
+        surface: createTestStubRasterBackend().createSurface(1, 1),
+      },
+      signal: controller.signal,
+    });
+    await Promise.resolve();
+    controller.abort();
+
+    await expect(pending).rejects.toMatchObject({ name: 'AbortError' });
+    expect(uploadSignal).toBe(controller.signal);
+  });
+
+  it('propagates a filter graph failure', async () => {
+    const graphError = new Error('graph failed');
+
+    await expect(
+      runLayerFilter({
+        deps: {
+          encodeSurface: () => Promise.resolve(new Blob()),
+          runFilterGraph: () => Promise.reject(graphError),
+          uploadIntermediate: () => Promise.resolve({ imageName: 'input' }),
+        },
+        filterType: 'canny_edge_detection',
+        input: {
+          rect: { height: 1, width: 1, x: 0, y: 0 },
+          surface: createTestStubRasterBackend().createSurface(1, 1),
+        },
+      })
+    ).rejects.toBe(graphError);
+  });
+
+  it('preserves a negative layer-local origin', async () => {
+    const result = await runLayerFilter({
+      deps: {
+        encodeSurface: () => Promise.resolve(new Blob()),
+        runFilterGraph: () => Promise.resolve({ height: 20, imageName: 'output', width: 30 }),
+        uploadIntermediate: () => Promise.resolve({ imageName: 'input' }),
+      },
+      filterType: 'canny_edge_detection',
+      input: {
+        rect: { height: 20, width: 30, x: -12, y: -24 },
+        surface: createTestStubRasterBackend().createSurface(30, 20),
+      },
+    });
+
+    expect(result.origin).toEqual({ x: -12, y: -24 });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/layerFilterRunner.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerFilterRunner.ts
new file mode 100644
index 00000000000..ce3b0e72848
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerFilterRunner.ts
@@ -0,0 +1,92 @@
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { BackendGraphContract } from '@workbench/types';
+
+import { LayerFilterOutputDimensionError } from '@workbench/canvas-engine/filterError';
+import { buildFilterGraph } from '@workbench/generation/canvas/filterGraphs';
+export { LayerFilterOutputDimensionError } from '@workbench/canvas-engine/filterError';
+
+export interface LayerFilterResult {
+  imageName: string;
+  width: number;
+  height: number;
+  origin: { x: number; y: number };
+}
+
+export interface RunLayerFilterOptions {
+  input: { surface: RasterSurface; rect: Rect };
+  filterType: string;
+  settings?: Record<string, unknown>;
+  signal?: AbortSignal;
+  deps: {
+    encodeSurface(surface: RasterSurface): Promise<Blob>;
+    uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ imageName: string }>;
+    runFilterGraph(options: {
+      graph: BackendGraphContract;
+      outputNodeId: string;
+      signal?: AbortSignal;
+    }): Promise<{ height: number; imageName: string; width: number }>;
+  };
+}
+
+export const resolveFilterOutputRect = (options: {
+  filterType: string;
+  output: { width: number; height: number };
+  settings?: Record<string, unknown>;
+  source: Rect;
+}): Rect => {
+  if (options.filterType === 'img_blur') {
+    const configuredRadius = options.settings?.radius;
+    const radius =
+      typeof configuredRadius === 'number' && Number.isFinite(configuredRadius)
+        ? Math.min(4_096, Math.max(0, configuredRadius))
+        : 8;
+    const padding = Math.max(0, Math.ceil(radius * (options.settings?.blur_type === 'box' ? 1 : 3)));
+    return {
+      height: options.output.height,
+      width: options.output.width,
+      x: options.source.x - padding,
+      y: options.source.y - padding,
+    };
+  }
+  if (options.filterType === 'spandrel_filter') {
+    return { ...options.output, x: options.source.x, y: options.source.y };
+  }
+  if (options.output.width !== options.source.width || options.output.height !== options.source.height) {
+    throw new LayerFilterOutputDimensionError(options.filterType, options.output, options.source);
+  }
+  return { ...options.source };
+};
+
+const throwIfAborted = (signal: AbortSignal | undefined): void => {
+  if (signal?.aborted) {
+    throw new DOMException('The layer-filter request was aborted.', 'AbortError');
+  }
+};
+
+export const runLayerFilter = async (options: RunLayerFilterOptions): Promise<LayerFilterResult> => {
+  throwIfAborted(options.signal);
+  const blob = await options.deps.encodeSurface(options.input.surface);
+  throwIfAborted(options.signal);
+  const uploaded = await options.deps.uploadIntermediate(blob, options.signal);
+  throwIfAborted(options.signal);
+  const built = buildFilterGraph(options.filterType, uploaded.imageName, options.settings);
+  const output = await options.deps.runFilterGraph({
+    graph: built.graph,
+    outputNodeId: built.outputNodeId,
+    signal: options.signal,
+  });
+  throwIfAborted(options.signal);
+  const rect = resolveFilterOutputRect({
+    filterType: options.filterType,
+    output,
+    settings: options.settings,
+    source: options.input.rect,
+  });
+  return {
+    height: rect.height,
+    imageName: output.imageName,
+    origin: { x: rect.x, y: rect.y },
+    width: rect.width,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/layerImageResult.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerImageResult.test.ts
new file mode 100644
index 00000000000..3ab9ceb8aa3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerImageResult.test.ts
@@ -0,0 +1,106 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/engine';
+import type { CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { prepareSelectObjectSource, processSelectObjectSource } from './layerImageResult';
+
+const rect = { height: 12, width: 16, x: -5, y: 7 };
+const layer: CanvasRasterLayerContractV2 = {
+  blendMode: 'normal',
+  id: 'source',
+  isEnabled: true,
+  isLocked: false,
+  name: 'Source',
+  opacity: 1,
+  source: { fill: '#fff', height: 12, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 16 },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: -5, y: 7 },
+  type: 'raster',
+};
+const guard = {
+  cacheVersion: 1,
+  documentGeneration: 1,
+  layer,
+  layerId: layer.id,
+  projectId: 'p1',
+} satisfies LayerExportGuard;
+
+describe('Select Object image processing', () => {
+  it('carries exact upload dimensions into the prepared source', async () => {
+    await expect(
+      prepareSelectObjectSource({
+        exportSource: () => Promise.resolve({ blob: new Blob(), guard, rect, status: 'ok' }),
+        uploadIntermediate: () => Promise.resolve({ height: 12, imageName: 'source.png', width: 16 }),
+      })
+    ).resolves.toEqual({
+      source: { guard, height: 12, imageName: 'source.png', rect, width: 16 },
+      status: 'ready',
+    });
+  });
+
+  it.each([
+    { height: 12, width: 15 },
+    { height: 12.5, width: 16 },
+    { height: 0, width: 16 },
+    { height: Number.NaN, width: 16 },
+  ])('rejects upload dimensions that do not exactly match the bbox: $width x $height', async (dimensions) => {
+    await expect(
+      prepareSelectObjectSource({
+        exportSource: () => Promise.resolve({ blob: new Blob(), guard, rect, status: 'ok' }),
+        uploadIntermediate: () => Promise.resolve({ ...dimensions, imageName: 'source.png' }),
+      })
+    ).resolves.toMatchObject({ status: 'dimension-mismatch' });
+  });
+
+  it('rejects a visual input made empty by export-local conversion before enqueue', async () => {
+    const runGraph = vi.fn();
+    await expect(
+      processSelectObjectSource({
+        applyPolygonRefinement: false,
+        input: {
+          bbox: null,
+          excludePoints: [],
+          includePoints: [{ x: 100, y: 100 }],
+          type: 'visual',
+        },
+        invert: false,
+        model: 'segment-anything-2-large',
+        runGraph,
+        source: { guard, height: 12, imageName: 'source.png', rect, width: 16 },
+      })
+    ).resolves.toEqual({ status: 'invalid-input' });
+    expect(runGraph).not.toHaveBeenCalled();
+  });
+
+  it('rejects a prepared source whose threaded upload dimensions no longer match its bbox', async () => {
+    const runGraph = vi.fn();
+    await expect(
+      processSelectObjectSource({
+        applyPolygonRefinement: false,
+        input: { prompt: 'cat', type: 'prompt' },
+        invert: false,
+        model: 'segment-anything-2-large',
+        runGraph,
+        source: { guard, height: 12, imageName: 'source.png', rect, width: 15 },
+      })
+    ).resolves.toMatchObject({ status: 'dimension-mismatch' });
+    expect(runGraph).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    { height: 12, width: 15 },
+    { height: 11.5, width: 16 },
+    { height: Number.POSITIVE_INFINITY, width: 16 },
+  ])('rejects mismatched SAM ImageOutput metadata without returning a stretchable preview', async (dimensions) => {
+    await expect(
+      processSelectObjectSource({
+        applyPolygonRefinement: false,
+        input: { prompt: 'cat', type: 'prompt' },
+        invert: false,
+        model: 'segment-anything-2-large',
+        runGraph: () => Promise.resolve({ ...dimensions, imageName: 'mask.png', origin: 'test' }),
+        source: { guard, height: 12, imageName: 'source.png', rect, width: 16 },
+      })
+    ).resolves.toMatchObject({ status: 'dimension-mismatch' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/layerImageResult.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerImageResult.ts
new file mode 100644
index 00000000000..9a10e27ac80
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/layerImageResult.ts
@@ -0,0 +1,187 @@
+import type { ExportBakedLayerBlobResult, LayerExportGuard } from '@workbench/canvas-engine/engine';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { RunUtilityGraphOptions, UtilityGraphResult } from '@workbench/canvas-operations/backend/utilityQueue';
+import type { SamSessionErrorCode } from '@workbench/canvas-operations/operationTypes';
+import type { SamInput, SamModel } from '@workbench/generation/canvas/samGraph';
+import type { CanvasImageRef } from '@workbench/types';
+
+import { UtilityQueueError } from '@workbench/canvas-operations/backend/utilityQueue';
+import { buildSamGraph, documentToExportLocalSamInput, isSamInputValid } from '@workbench/generation/canvas/samGraph';
+
+export interface SelectObjectReadyResult {
+  status: 'ready';
+  image: CanvasImageRef;
+  rect: Rect;
+  guard: LayerExportGuard;
+}
+
+export type SelectObjectRunResult =
+  | SelectObjectReadyResult
+  | { status: 'aborted' | 'missing' | 'disabled' | 'unsupported' | 'empty' | 'not-ready' | 'over-budget' }
+  | { status: 'invalid-input' }
+  | { status: 'dimension-mismatch'; message: string }
+  | { status: 'failed'; message: string; code: SamSessionErrorCode };
+
+export interface SelectObjectRunnerDeps {
+  exportSource(): Promise<ExportBakedLayerBlobResult>;
+  uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ height: number; imageName: string; width: number }>;
+  runGraph(options: Pick<RunUtilityGraphOptions, 'graph' | 'outputNodeId' | 'signal'>): Promise<UtilityGraphResult>;
+}
+
+const isAbortError = (error: unknown): boolean => error instanceof Error && error.name === 'AbortError';
+const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+export interface SelectObjectPreparedSource {
+  guard: LayerExportGuard;
+  imageName: string;
+  height: number;
+  rect: Rect;
+  width: number;
+}
+
+export type PrepareSelectObjectSourceResult =
+  | { status: 'ready'; source: SelectObjectPreparedSource }
+  | Exclude<SelectObjectRunResult, SelectObjectReadyResult>;
+
+export const prepareSelectObjectSource = async (
+  deps: Pick<SelectObjectRunnerDeps, 'exportSource' | 'uploadIntermediate'>,
+  signal?: AbortSignal,
+  onPhase?: (phase: 'uploading') => void
+): Promise<PrepareSelectObjectSourceResult> => {
+  if (signal?.aborted) {
+    return { status: 'aborted' };
+  }
+  let exported: ExportBakedLayerBlobResult;
+  try {
+    exported = await deps.exportSource();
+    if (signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    if (exported.status !== 'ok') {
+      return exported;
+    }
+  } catch (error) {
+    if (signal?.aborted || isAbortError(error)) {
+      return { status: 'aborted' };
+    }
+    return { code: 'unknown', message: errorMessage(error), status: 'failed' };
+  }
+
+  try {
+    onPhase?.('uploading');
+    const uploaded = await deps.uploadIntermediate(exported.blob, signal);
+    if (signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    if (!hasExactDimensions(uploaded, exported.rect)) {
+      return {
+        message: `Uploaded Select Object source dimensions ${String(uploaded.width)}x${String(uploaded.height)} do not match ${exported.rect.width}x${exported.rect.height}.`,
+        status: 'dimension-mismatch',
+      };
+    }
+    return {
+      source: {
+        guard: exported.guard,
+        height: uploaded.height,
+        imageName: uploaded.imageName,
+        rect: exported.rect,
+        width: uploaded.width,
+      },
+      status: 'ready',
+    };
+  } catch (error) {
+    if (signal?.aborted || isAbortError(error)) {
+      return { status: 'aborted' };
+    }
+    return { code: 'upload', message: errorMessage(error), status: 'failed' };
+  }
+};
+
+export interface ProcessSelectObjectSourceOptions {
+  source: SelectObjectPreparedSource;
+  input: SamInput;
+  model: SamModel;
+  invert: boolean;
+  applyPolygonRefinement: boolean;
+  signal?: AbortSignal;
+  runGraph: SelectObjectRunnerDeps['runGraph'];
+  onPhase?: (phase: 'processing-sam') => void;
+}
+
+const hasExactDimensions = (
+  value: { height: number; width: number },
+  expected: { height: number; width: number }
+): boolean =>
+  Number.isFinite(value.width) &&
+  Number.isInteger(value.width) &&
+  value.width > 0 &&
+  Number.isFinite(value.height) &&
+  Number.isInteger(value.height) &&
+  value.height > 0 &&
+  value.width === expected.width &&
+  value.height === expected.height;
+
+export const processSelectObjectSource = async (
+  options: ProcessSelectObjectSourceOptions
+): Promise<SelectObjectRunResult> => {
+  if (options.signal?.aborted) {
+    return { status: 'aborted' };
+  }
+  try {
+    if (!hasExactDimensions(options.source, options.source.rect)) {
+      return {
+        message: `Uploaded Select Object source dimensions ${String(options.source.width)}x${String(options.source.height)} do not match ${options.source.rect.width}x${options.source.rect.height}.`,
+        status: 'dimension-mismatch',
+      };
+    }
+    const input = documentToExportLocalSamInput(options.input, options.source.rect);
+    if (!isSamInputValid(input)) {
+      return { status: 'invalid-input' };
+    }
+    const built = buildSamGraph({
+      applyPolygonRefinement: options.applyPolygonRefinement,
+      imageName: options.source.imageName,
+      input,
+      invert: options.invert,
+      model: options.model,
+    });
+    options.onPhase?.('processing-sam');
+    const output = await options.runGraph({
+      graph: built.graph,
+      outputNodeId: built.outputNodeId,
+      signal: options.signal,
+    });
+    if (options.signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    if (!hasExactDimensions(output, options.source.rect)) {
+      return {
+        message: `SAM output dimensions ${String(output.width)}x${String(output.height)} do not match ${options.source.rect.width}x${options.source.rect.height}.`,
+        status: 'dimension-mismatch',
+      };
+    }
+    return {
+      guard: options.source.guard,
+      image: {
+        height: output.height,
+        imageName: output.imageName,
+        width: output.width,
+      },
+      rect: options.source.rect,
+      status: 'ready',
+    };
+  } catch (error) {
+    if (options.signal?.aborted || isAbortError(error)) {
+      return { status: 'aborted' };
+    }
+    const code: SamSessionErrorCode =
+      error instanceof UtilityQueueError
+        ? error.reason === 'no-output'
+          ? 'no-output'
+          : error.reason === 'reconcile'
+            ? 'reconcile'
+            : 'queue'
+        : 'queue';
+    return { code, message: errorMessage(error), status: 'failed' };
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/operationController.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationController.test.ts
new file mode 100644
index 00000000000..1327aac1f0f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationController.test.ts
@@ -0,0 +1,513 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { createCanvasEditGate } from '@workbench/canvas-engine/editGate';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createCanvasOperationController } from './operationController';
+
+const layer: CanvasRasterLayerContractV2 = {
+  blendMode: 'normal',
+  id: 'layer-1',
+  isEnabled: true,
+  isLocked: false,
+  name: 'Layer',
+  opacity: 1,
+  source: { fill: '#fff', height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+};
+
+const guard: LayerExportGuard = {
+  cacheVersion: 1,
+  documentGeneration: 1,
+  layer,
+  layerId: layer.id,
+  projectId: 'project-1',
+};
+
+const createDeferred = <T>() => {
+  let resolve!: (value: T) => void;
+  let reject!: (cause: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, reject, resolve };
+};
+
+const filterIdentity = { kind: 'filter' as const, layerId: layer.id, projectId: 'project-1' };
+const selectObjectIdentity = { kind: 'select-object' as const, layerId: layer.id, projectId: 'project-1' };
+
+describe('createCanvasOperationController', () => {
+  it('holds an exclusive edit lease and closes when the engine invalidates it', () => {
+    const edits = createCanvasEditGate();
+    const controller = createCanvasOperationController({ edits, isGuardCurrent: () => true });
+    const session = controller.start({
+      cleanupPreview: vi.fn(),
+      guard,
+      identity: { kind: 'filter', layerId: guard.layerId, projectId: guard.projectId },
+    });
+
+    expect(session).not.toBeNull();
+    expect(edits.tryAcquire({ kind: 'other' })).toBeNull();
+    edits.invalidateDocument();
+    expect(controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(edits.tryAcquire({ kind: 'other' })?.isCurrent()).toBe(true);
+  });
+  it('requires the identity to name the guarded layer for both operation kinds', () => {
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+
+    const session = controller.start({
+      cleanupPreview: vi.fn(),
+      guard,
+      identity: selectObjectIdentity,
+    });
+
+    expect(session).not.toBeNull();
+    expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+    expect(
+      controller.start({ cleanupPreview: vi.fn(), guard, identity: { ...selectObjectIdentity, layerId: 'other' } })
+    ).toBeNull();
+    expect(
+      controller.start({ cleanupPreview: vi.fn(), guard, identity: { ...filterIdentity, layerId: 'other' } })
+    ).toBeNull();
+    expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+  });
+  it('replaces the active operation and prevents its stale session from affecting the replacement', async () => {
+    const firstWork = createDeferred<string>();
+    const firstCleanup = vi.fn();
+    const secondCleanup = vi.fn();
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const first = controller.start({ cleanupPreview: firstCleanup, guard, identity: filterIdentity })!;
+    const publishFirst = vi.fn((_result: string): undefined => undefined);
+    const pending = first.run(() => firstWork.promise, publishFirst);
+    firstCleanup.mockClear();
+
+    const second = controller.start({
+      cleanupPreview: secondCleanup,
+      guard,
+      identity: selectObjectIdentity,
+    })!;
+
+    expect(firstCleanup).toHaveBeenCalledOnce();
+    expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+    first.cancel();
+    firstWork.resolve('old');
+    await expect(pending).resolves.toBe('stale');
+    expect(publishFirst).not.toHaveBeenCalled();
+    expect(secondCleanup).not.toHaveBeenCalled();
+    expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+    second.cancel();
+  });
+
+  it('reset aborts work and clears the preview while keeping the operation active', async () => {
+    const work = createDeferred<string>();
+    const cleanupPreview = vi.fn();
+    let signal: AbortSignal | undefined;
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+    const pending = session.run(
+      (requestSignal) => {
+        signal = requestSignal;
+        return work.promise;
+      },
+      vi.fn((): undefined => undefined)
+    );
+    cleanupPreview.mockClear();
+
+    session.reset();
+
+    expect(signal?.aborted).toBe(true);
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(controller.getSnapshot()).toEqual({
+      error: null,
+      identity: filterIdentity,
+      phase: 'ready',
+      status: 'active',
+    });
+    work.resolve('late');
+    await expect(pending).resolves.toBe('stale');
+  });
+
+  it('cancel aborts work, clears the preview, and closes the operation', async () => {
+    const work = createDeferred<string>();
+    const cleanupPreview = vi.fn();
+    let signal: AbortSignal | undefined;
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+    const pending = session.run(
+      (requestSignal) => {
+        signal = requestSignal;
+        return work.promise;
+      },
+      vi.fn((): undefined => undefined)
+    );
+    cleanupPreview.mockClear();
+
+    session.cancel();
+
+    expect(signal?.aborted).toBe(true);
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(controller.getSnapshot()).toEqual({ status: 'idle' });
+    work.resolve('late');
+    await expect(pending).resolves.toBe('stale');
+  });
+
+  it('dispose aborts work, clears the preview, and stops notifications', async () => {
+    const work = createDeferred<string>();
+    const cleanupPreview = vi.fn();
+    let signal: AbortSignal | undefined;
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+    const pending = session.run(
+      (requestSignal) => {
+        signal = requestSignal;
+        return work.promise;
+      },
+      vi.fn((): undefined => undefined)
+    );
+    const listener = vi.fn();
+    controller.subscribe(listener);
+    cleanupPreview.mockClear();
+    listener.mockClear();
+
+    controller.dispose();
+
+    expect(signal?.aborted).toBe(true);
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(controller.getSnapshot()).toEqual({ status: 'idle' });
+    expect(listener).not.toHaveBeenCalled();
+    expect(controller.start({ cleanupPreview, guard, identity: filterIdentity })).toBeNull();
+    work.resolve('late');
+    await expect(pending).resolves.toBe('stale');
+  });
+
+  it('publishes only the latest request when completions arrive out of order', async () => {
+    const older = createDeferred<string>();
+    const newer = createDeferred<string>();
+    const publishOlder = vi.fn((_result: string): undefined => undefined);
+    const publishNewer = vi.fn((_result: string): undefined => undefined);
+    const signals: AbortSignal[] = [];
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview: vi.fn(), guard, identity: filterIdentity })!;
+
+    const olderPending = session.run((signal) => {
+      signals.push(signal);
+      return older.promise;
+    }, publishOlder);
+    const newerPending = session.run((signal) => {
+      signals.push(signal);
+      return newer.promise;
+    }, publishNewer);
+    newer.resolve('newer');
+    await expect(newerPending).resolves.toBe('published');
+    older.resolve('older');
+    await expect(olderPending).resolves.toBe('stale');
+
+    expect(signals[0]?.aborted).toBe(true);
+    expect(publishOlder).not.toHaveBeenCalled();
+    expect(publishNewer).toHaveBeenCalledWith('newer');
+  });
+
+  it('rechecks freshness after synchronous preview commit', async () => {
+    const replacementCleanup = vi.fn();
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview: vi.fn(), guard, identity: filterIdentity })!;
+
+    const result = await session.run(
+      () => Promise.resolve('prepared'),
+      () => {
+        controller.start({
+          cleanupPreview: replacementCleanup,
+          guard,
+          identity: selectObjectIdentity,
+        });
+        return undefined;
+      }
+    );
+
+    expect(result).toBe('stale');
+    expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+    expect(replacementCleanup).not.toHaveBeenCalled();
+  });
+
+  it('requires preview commit callbacks to be synchronous', () => {
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview: vi.fn(), guard, identity: filterIdentity })!;
+
+    if (Date.now() < 0) {
+      const asyncCommit = (): Promise<void> => Promise.resolve();
+      const voidCommit = (): void => undefined;
+      const maybeAsyncCommit = (): void | Promise<void> => Promise.resolve();
+      // @ts-expect-error Preview commit must not yield after the final freshness check.
+      void session.run(() => Promise.resolve('prepared'), asyncCommit);
+      // @ts-expect-error Preview commit must explicitly return undefined.
+      void session.run(() => Promise.resolve('prepared'), voidCommit);
+      // @ts-expect-error Preview commit cannot have an async branch.
+      void session.run(() => Promise.resolve('prepared'), maybeAsyncCommit);
+    }
+  });
+
+  it('treats AbortError from a superseded request as stale without publishing an error', async () => {
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview: vi.fn(), guard, identity: filterIdentity })!;
+    const commitOlder = vi.fn((_result: string): undefined => undefined);
+    const older = session.run(
+      (signal) =>
+        new Promise<string>((_resolve, reject) => {
+          signal.addEventListener('abort', () => reject(new DOMException('superseded', 'AbortError')), { once: true });
+        }),
+      commitOlder
+    );
+
+    const commitNewer = vi.fn((_result: string): undefined => undefined);
+    const newer = session.run(() => Promise.resolve('newer'), commitNewer);
+
+    await expect(older).resolves.toBe('stale');
+    await expect(newer).resolves.toBe('published');
+    expect(commitOlder).not.toHaveBeenCalled();
+    expect(commitNewer).toHaveBeenCalledWith('newer');
+    expect(controller.getSnapshot()).toMatchObject({ error: null, phase: 'ready', status: 'active' });
+  });
+
+  it.each(['replacement', 'reset', 'cancel'] as const)(
+    'preserves an operation started reentrantly during %s cleanup',
+    (lifecycle) => {
+      const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+      const replacementCleanup = vi.fn();
+      const cleanupPreview = vi.fn(() => {
+        controller.start({
+          cleanupPreview: replacementCleanup,
+          guard,
+          identity: selectObjectIdentity,
+        });
+      });
+      const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+
+      if (lifecycle === 'replacement') {
+        controller.start({ cleanupPreview: vi.fn(), guard, identity: filterIdentity });
+      } else if (lifecycle === 'reset') {
+        session.reset();
+      } else {
+        session.cancel();
+      }
+
+      expect(cleanupPreview).toHaveBeenCalledOnce();
+      expect(replacementCleanup).not.toHaveBeenCalled();
+      expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+    }
+  );
+
+  it('preserves an operation started reentrantly during request cleanup', async () => {
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const replacementCleanup = vi.fn();
+    const cleanupPreview = vi.fn(() => {
+      controller.start({
+        cleanupPreview: replacementCleanup,
+        guard,
+        identity: selectObjectIdentity,
+      });
+    });
+    const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+    const work = vi.fn(() => Promise.resolve('prepared'));
+
+    await expect(
+      session.run(
+        work,
+        vi.fn((): undefined => undefined)
+      )
+    ).resolves.toBe('stale');
+
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(work).not.toHaveBeenCalled();
+    expect(replacementCleanup).not.toHaveBeenCalled();
+    expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+  });
+
+  it('contains subscriber exceptions during start and request state transitions', async () => {
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const healthyListener = vi.fn();
+    controller.subscribe(() => {
+      throw new Error('listener failed');
+    });
+    controller.subscribe(healthyListener);
+
+    const session = controller.start({ cleanupPreview: vi.fn(), guard, identity: filterIdentity });
+
+    expect(session).not.toBeNull();
+    await expect(
+      session!.run(
+        () => Promise.resolve('ready'),
+        vi.fn((): undefined => undefined)
+      )
+    ).resolves.toBe('published');
+    expect(healthyListener).toHaveBeenCalledTimes(3);
+    expect(controller.getSnapshot()).toMatchObject({ phase: 'ready', status: 'active' });
+  });
+
+  it('rejects an invalid or mismatched export guard without replacing the active operation', () => {
+    const isGuardCurrent = vi.fn((candidate: LayerExportGuard) => candidate === guard);
+    const controller = createCanvasOperationController({ isGuardCurrent });
+    const session = controller.start({ cleanupPreview: vi.fn(), guard, identity: filterIdentity });
+    const staleGuard = { ...guard, cacheVersion: 2 };
+
+    expect(session).not.toBeNull();
+    expect(controller.start({ cleanupPreview: vi.fn(), guard: staleGuard, identity: filterIdentity })).toBeNull();
+    expect(
+      controller.start({ cleanupPreview: vi.fn(), guard, identity: { ...filterIdentity, layerId: 'other' } })
+    ).toBeNull();
+    expect(
+      controller.start({ cleanupPreview: vi.fn(), guard, identity: { ...filterIdentity, projectId: 'other' } })
+    ).toBeNull();
+    expect(controller.getSnapshot()).toMatchObject({ identity: filterIdentity, status: 'active' });
+  });
+
+  it('suppresses a result when its guard becomes invalid during work', async () => {
+    let current = true;
+    const work = createDeferred<string>();
+    const publish = vi.fn((_result: string): undefined => undefined);
+    const cleanupPreview = vi.fn();
+    const controller = createCanvasOperationController({ isGuardCurrent: () => current });
+    const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+    const pending = session.run(() => work.promise, publish);
+    cleanupPreview.mockClear();
+
+    current = false;
+    work.resolve('stale');
+
+    await expect(pending).resolves.toBe('stale');
+    expect(publish).not.toHaveBeenCalled();
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(controller.getSnapshot()).toEqual({ status: 'idle' });
+  });
+
+  it.each([
+    [
+      'source',
+      (controller: ReturnType<typeof createCanvasOperationController>) =>
+        controller.invalidateSource('project-1', layer.id),
+    ],
+    [
+      'layer',
+      (controller: ReturnType<typeof createCanvasOperationController>) =>
+        controller.invalidateLayer('project-1', layer.id),
+    ],
+    [
+      'project',
+      (controller: ReturnType<typeof createCanvasOperationController>) => controller.invalidateProject('project-1'),
+    ],
+    [
+      'document',
+      (controller: ReturnType<typeof createCanvasOperationController>) => controller.invalidateDocument('project-1'),
+    ],
+  ])('%s invalidation aborts and cleans the matching operation', async (_reason, invalidate) => {
+    const work = createDeferred<string>();
+    const cleanupPreview = vi.fn();
+    let signal: AbortSignal | undefined;
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+    const pending = session.run(
+      (requestSignal) => {
+        signal = requestSignal;
+        return work.promise;
+      },
+      vi.fn((): undefined => undefined)
+    );
+    cleanupPreview.mockClear();
+
+    invalidate(controller);
+
+    expect(signal?.aborted).toBe(true);
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(controller.getSnapshot()).toEqual({ status: 'idle' });
+    work.resolve('late');
+    await expect(pending).resolves.toBe('stale');
+  });
+
+  it('ignores invalidation for a different target', () => {
+    const cleanupPreview = vi.fn();
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    controller.start({ cleanupPreview, guard, identity: filterIdentity });
+
+    controller.invalidateSource('project-1', 'other-layer');
+    controller.invalidateLayer('other-project', layer.id);
+    controller.invalidateProject('other-project');
+    controller.invalidateDocument('other-project');
+
+    expect(cleanupPreview).not.toHaveBeenCalled();
+    expect(controller.getSnapshot()).toMatchObject({ identity: filterIdentity, status: 'active' });
+  });
+
+  it('keeps Select Object open across other-layer invalidation but closes it for its own source layer', () => {
+    const cleanupPreview = vi.fn();
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    controller.start({
+      cleanupPreview,
+      guard,
+      identity: selectObjectIdentity,
+    });
+
+    controller.invalidateSource('project-1', 'other-layer');
+    controller.invalidateLayer('project-1', 'other-layer');
+
+    expect(cleanupPreview).not.toHaveBeenCalled();
+    expect(controller.getSnapshot()).toMatchObject({ identity: selectObjectIdentity, status: 'active' });
+
+    controller.invalidateSource('project-1', layer.id);
+    expect(cleanupPreview).toHaveBeenCalledOnce();
+    expect(controller.getSnapshot()).toEqual({ status: 'idle' });
+  });
+
+  it('suppresses a late result after the operation closes', async () => {
+    const work = createDeferred<string>();
+    const publish = vi.fn((_result: string): undefined => undefined);
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({
+      cleanupPreview: vi.fn(),
+      guard,
+      identity: selectObjectIdentity,
+    })!;
+    const pending = session.run(() => work.promise, publish);
+
+    controller.cancel();
+    work.resolve('late');
+
+    await expect(pending).resolves.toBe('stale');
+    expect(publish).not.toHaveBeenCalled();
+    expect(controller.getSnapshot()).toEqual({ status: 'idle' });
+  });
+
+  it('publishes an error and allows the same operation to retry', async () => {
+    const cleanupPreview = vi.fn();
+    const listener = vi.fn();
+    const controller = createCanvasOperationController({ isGuardCurrent: () => true });
+    const session = controller.start({ cleanupPreview, guard, identity: filterIdentity })!;
+    controller.subscribe(listener);
+
+    await expect(
+      session.run(
+        () => Promise.reject(new Error('graph failed')),
+        vi.fn((): undefined => undefined)
+      )
+    ).resolves.toBe('error');
+
+    expect(controller.getSnapshot()).toEqual({
+      error: 'graph failed',
+      identity: filterIdentity,
+      phase: 'error',
+      status: 'active',
+    });
+
+    const publish = vi.fn((_result: string): undefined => undefined);
+    await expect(session.run(() => Promise.resolve('recovered'), publish)).resolves.toBe('published');
+    expect(publish).toHaveBeenCalledWith('recovered');
+    expect(controller.getSnapshot()).toEqual({
+      error: null,
+      identity: filterIdentity,
+      phase: 'ready',
+      status: 'active',
+    });
+    expect(listener).toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/operationController.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationController.ts
new file mode 100644
index 00000000000..75a4fa3d60e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationController.ts
@@ -0,0 +1,330 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type { CanvasEditGate, CanvasEditLease } from '@workbench/canvas-engine/editGate';
+
+import { createCanvasEditGate } from '@workbench/canvas-engine/editGate';
+
+export type CanvasOperationIdentity =
+  | { kind: 'select-object'; projectId: string; layerId: string }
+  | { kind: 'filter'; projectId: string; layerId: string };
+
+export type CanvasOperationGuard = LayerExportGuard;
+
+export type CanvasOperationState =
+  | { status: 'idle' }
+  | {
+      status: 'active';
+      identity: CanvasOperationIdentity;
+      phase: 'ready' | 'running' | 'error';
+      error: string | null;
+    };
+
+export type CanvasOperationRunResult = 'published' | 'stale' | 'error';
+
+export interface CanvasOperationSession {
+  /**
+   * Prepares a preview asynchronously, then commits it synchronously only while
+   * this request and its export guard are still current. `commitPreview` must
+   * explicitly return `undefined`; do not cast or erase an async callback to
+   * `() => void`, which TypeScript cannot distinguish from a synchronous one.
+   */
+  run<T>(
+    work: (signal: AbortSignal) => Promise<T>,
+    commitPreview: (result: T) => undefined
+  ): Promise<CanvasOperationRunResult>;
+  reset(): void;
+  /** Aborts only the active request and keeps this operation ready for retry or Cancel. */
+  interruptProcessing(): void;
+  cancel(): void;
+}
+
+export interface StartCanvasOperationOptions {
+  identity: CanvasOperationIdentity;
+  guard: LayerExportGuard;
+  cleanupPreview(): void;
+}
+
+export interface CanvasOperationController {
+  getSnapshot(): CanvasOperationState;
+  subscribe(listener: () => void): () => void;
+  start(options: StartCanvasOperationOptions): CanvasOperationSession | null;
+  reset(): void;
+  cancel(): void;
+  invalidateSource(projectId: string, layerId: string): void;
+  invalidateLayer(projectId: string, layerId: string): void;
+  invalidateProject(projectId: string): void;
+  invalidateDocument(projectId: string): void;
+  dispose(): void;
+}
+
+export interface CanvasOperationControllerDeps {
+  isGuardCurrent(guard: CanvasOperationGuard): boolean;
+  edits?: CanvasEditGate;
+}
+
+type ActiveOperation = StartCanvasOperationOptions & {
+  lease: CanvasEditLease;
+  onLeaseAbort: () => void;
+  requestController: AbortController | null;
+  requestToken: number;
+};
+
+const errorMessage = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
+
+export const createCanvasOperationController = (deps: CanvasOperationControllerDeps): CanvasOperationController => {
+  const ownedEditGate = deps.edits ? null : createCanvasEditGate();
+  const edits: CanvasEditGate = deps.edits ?? ownedEditGate!;
+  let state: CanvasOperationState = { status: 'idle' };
+  let active: ActiveOperation | null = null;
+  let disposed = false;
+  const listeners = new Set<() => void>();
+
+  const publishState = (next: CanvasOperationState): void => {
+    state = next;
+    if (disposed) {
+      return;
+    }
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+        // One faulty subscriber must not strand the controller mid-transition.
+      }
+    }
+  };
+
+  const cleanupPreview = (operation: ActiveOperation): void => {
+    try {
+      operation.cleanupPreview();
+    } catch {
+      // Cleanup is best-effort and must not prevent cancellation or invalidation.
+    }
+  };
+
+  const close = (operation: ActiveOperation): void => {
+    if (active !== operation) {
+      return;
+    }
+    operation.requestToken += 1;
+    const requestController = operation.requestController;
+    operation.requestController = null;
+    active = null;
+    const idleState: CanvasOperationState = { status: 'idle' };
+    state = idleState;
+    requestController?.abort();
+    operation.lease.signal.removeEventListener('abort', operation.onLeaseAbort);
+    operation.lease.release();
+    cleanupPreview(operation);
+    if (active === null && state === idleState) {
+      publishState(idleState);
+    }
+  };
+
+  const interruptProcessing = (operation: ActiveOperation): void => {
+    if (active !== operation || disposed) {
+      return;
+    }
+    operation.requestToken += 1;
+    const requestController = operation.requestController;
+    operation.requestController = null;
+    active = null;
+    const idleState: CanvasOperationState = { status: 'idle' };
+    state = idleState;
+    requestController?.abort();
+    operation.lease.signal.removeEventListener('abort', operation.onLeaseAbort);
+    operation.lease.release();
+    cleanupPreview(operation);
+    if (!disposed && active === null && state === idleState) {
+      const lease = edits.tryAcquire({ kind: operation.identity.kind, layerId: operation.identity.layerId });
+      if (lease) {
+        operation.lease = lease;
+        lease.signal.addEventListener('abort', operation.onLeaseAbort, { once: true });
+        active = operation;
+        publishState({ error: null, identity: operation.identity, phase: 'ready', status: 'active' });
+      } else {
+        publishState(idleState);
+      }
+    }
+  };
+
+  const isGuardCurrent = (operation: ActiveOperation): boolean => {
+    try {
+      return deps.isGuardCurrent(operation.guard);
+    } catch {
+      return false;
+    }
+  };
+
+  const isCurrentRequest = (operation: ActiveOperation, token: number, controller: AbortController): boolean =>
+    !disposed &&
+    active === operation &&
+    operation.requestToken === token &&
+    operation.requestController === controller &&
+    !controller.signal.aborted;
+
+  const run = async <T>(
+    operation: ActiveOperation,
+    work: (signal: AbortSignal) => Promise<T>,
+    commitPreview: (result: T) => undefined
+  ): Promise<CanvasOperationRunResult> => {
+    if (disposed || active !== operation) {
+      return 'stale';
+    }
+    if (!isGuardCurrent(operation)) {
+      close(operation);
+      return 'stale';
+    }
+
+    operation.requestToken += 1;
+    const token = operation.requestToken;
+    const previousController = operation.requestController;
+    operation.requestController = null;
+    active = null;
+    const idleState: CanvasOperationState = { status: 'idle' };
+    state = idleState;
+    previousController?.abort();
+    operation.lease.signal.removeEventListener('abort', operation.onLeaseAbort);
+    operation.lease.release();
+    cleanupPreview(operation);
+    if (disposed || active !== null || state !== idleState) {
+      return 'stale';
+    }
+    const lease = edits.tryAcquire({ kind: operation.identity.kind, layerId: operation.identity.layerId });
+    if (!lease) {
+      publishState(idleState);
+      return 'stale';
+    }
+    operation.lease = lease;
+    lease.signal.addEventListener('abort', operation.onLeaseAbort, { once: true });
+
+    const controller = new AbortController();
+    operation.requestController = controller;
+    active = operation;
+    publishState({ error: null, identity: operation.identity, phase: 'running', status: 'active' });
+    if (!isCurrentRequest(operation, token, controller)) {
+      return 'stale';
+    }
+
+    try {
+      const result = await work(controller.signal);
+      if (!isCurrentRequest(operation, token, controller)) {
+        return 'stale';
+      }
+      if (!isGuardCurrent(operation)) {
+        close(operation);
+        return 'stale';
+      }
+
+      commitPreview(result);
+      if (!isCurrentRequest(operation, token, controller)) {
+        return 'stale';
+      }
+      if (!isGuardCurrent(operation)) {
+        close(operation);
+        return 'stale';
+      }
+
+      operation.requestController = null;
+      publishState({ error: null, identity: operation.identity, phase: 'ready', status: 'active' });
+      return 'published';
+    } catch (cause) {
+      if (!isCurrentRequest(operation, token, controller)) {
+        return 'stale';
+      }
+      operation.requestController = null;
+      publishState({ error: errorMessage(cause), identity: operation.identity, phase: 'error', status: 'active' });
+      return 'error';
+    }
+  };
+
+  const start = (options: StartCanvasOperationOptions): CanvasOperationSession | null => {
+    if (
+      disposed ||
+      options.identity.projectId !== options.guard.projectId ||
+      options.identity.layerId !== options.guard.layerId
+    ) {
+      return null;
+    }
+    try {
+      if (!deps.isGuardCurrent(options.guard)) {
+        return null;
+      }
+    } catch {
+      return null;
+    }
+
+    if (active) {
+      close(active);
+      if (active) {
+        return null;
+      }
+    }
+    const lease = edits.tryAcquire({ kind: options.identity.kind, layerId: options.identity.layerId });
+    if (!lease) {
+      return null;
+    }
+    let operation!: ActiveOperation;
+    const onLeaseAbort = (): void => close(operation);
+    operation = {
+      ...options,
+      lease,
+      onLeaseAbort,
+      requestController: null,
+      requestToken: 0,
+    };
+    lease.signal.addEventListener('abort', onLeaseAbort, { once: true });
+    active = operation;
+    publishState({ error: null, identity: operation.identity, phase: 'ready', status: 'active' });
+
+    return {
+      cancel: () => close(operation),
+      interruptProcessing: () => interruptProcessing(operation),
+      reset: () => interruptProcessing(operation),
+      run: <T>(work: (signal: AbortSignal) => Promise<T>, commitPreview: (result: T) => undefined) =>
+        run(operation, work, commitPreview),
+    };
+  };
+
+  const invalidateTarget = (projectId: string, layerId?: string): void => {
+    if (active?.identity.projectId === projectId && (layerId === undefined || active.identity.layerId === layerId)) {
+      close(active);
+    }
+  };
+
+  return {
+    cancel: () => {
+      if (active) {
+        close(active);
+      }
+    },
+    dispose: () => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      if (active) {
+        close(active);
+      } else {
+        state = { status: 'idle' };
+      }
+      listeners.clear();
+      ownedEditGate?.dispose();
+    },
+    getSnapshot: () => state,
+    invalidateDocument: (projectId) => invalidateTarget(projectId),
+    invalidateLayer: (projectId, layerId) => invalidateTarget(projectId, layerId),
+    invalidateProject: (projectId) => invalidateTarget(projectId),
+    invalidateSource: (projectId, layerId) => invalidateTarget(projectId, layerId),
+    reset: () => {
+      if (active) {
+        interruptProcessing(active);
+      }
+    },
+    start,
+    subscribe: (listener) => {
+      if (!disposed) {
+        listeners.add(listener);
+      }
+      return () => listeners.delete(listener);
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/operationStores.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationStores.test.ts
new file mode 100644
index 00000000000..97ab9c47be1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationStores.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createCanvasOperationStores } from './operationStores';
+
+describe('createCanvasOperationStores', () => {
+  it('publishes filter and Select Object session snapshots independently', () => {
+    const stores = createCanvasOperationStores();
+    const onFilter = vi.fn();
+    const onSam = vi.fn();
+    stores.filterSession.subscribe(onFilter);
+    stores.samSession.subscribe(onSam);
+
+    stores.filterSession.set({ status: 'ready' } as never);
+    expect(onFilter).toHaveBeenCalledOnce();
+    expect(onSam).not.toHaveBeenCalled();
+
+    stores.samSession.set({ status: 'ready' } as never);
+    expect(onSam).toHaveBeenCalledOnce();
+  });
+
+  it('does not notify for an identical snapshot reference', () => {
+    const stores = createCanvasOperationStores();
+    const listener = vi.fn();
+    const snapshot = { status: 'ready' } as never;
+    stores.filterSession.subscribe(listener);
+    stores.filterSession.set(snapshot);
+    stores.filterSession.set(snapshot);
+    expect(listener).toHaveBeenCalledOnce();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/operationStores.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationStores.ts
new file mode 100644
index 00000000000..9a5800d46c2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationStores.ts
@@ -0,0 +1,33 @@
+import type {
+  CanvasApplicationOperationStores,
+  CanvasApplicationScalarStore,
+} from '@workbench/canvas-operations/contracts';
+
+export type CanvasOperationScalarStore<T> = CanvasApplicationScalarStore<T>;
+export type CanvasOperationStores = CanvasApplicationOperationStores;
+
+const createScalarStore = <T>(initial: T): CanvasOperationScalarStore<T> => {
+  let value = initial;
+  const listeners = new Set<() => void>();
+  return {
+    get: () => value,
+    set: (next) => {
+      if (Object.is(value, next)) {
+        return;
+      }
+      value = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+};
+
+export const createCanvasOperationStores = (): CanvasOperationStores => ({
+  filterSession: createScalarStore(null),
+  samSession: createScalarStore(null),
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/operationTypes.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationTypes.ts
new file mode 100644
index 00000000000..44867e71d3b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/operationTypes.ts
@@ -0,0 +1,77 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/api';
+import type {
+  RasterFilterCommitTarget,
+  RasterFilterSettings,
+} from '@workbench/canvas-engine/controllers/filterResultController';
+import type { SamVisualInput } from '@workbench/canvas-engine/samInteraction';
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+export type { SamVisualInput } from '@workbench/canvas-engine/samInteraction';
+
+export type SamModel = 'segment-anything-2-large' | 'segment-anything-huge';
+export type SamPointLabel = 'include' | 'exclude';
+export type SamSessionErrorCode =
+  | 'invalid'
+  | 'not-ready'
+  | 'empty'
+  | 'upload'
+  | 'queue'
+  | 'no-output'
+  | 'reconcile'
+  | 'output-dimension'
+  | 'decode'
+  | 'locked'
+  | 'unknown';
+export interface SamSessionError {
+  code: SamSessionErrorCode;
+  detail?: string;
+}
+export type SamInput =
+  | { type: 'prompt'; prompt: string }
+  | { type: 'visual'; includePoints: readonly Vec2[]; excludePoints: readonly Vec2[]; bbox?: Rect | null };
+export type SamSessionInput =
+  | SamVisualInput
+  | { type: 'prompt'; prompt: string; includePoints?: never; excludePoints?: never; bbox?: never };
+export interface SamSessionSnapshot {
+  sourceRect: Rect;
+  layerName: string;
+  layerType: 'raster' | 'control';
+  input: SamSessionInput;
+  pointLabel: SamPointLabel;
+  model: SamModel;
+  invert: boolean;
+  applyPolygonRefinement: boolean;
+  autoProcess: boolean;
+  isolatedPreview: boolean;
+  status:
+    | 'ready'
+    | 'scheduled'
+    | 'preparing-source'
+    | 'uploading'
+    | 'processing-sam'
+    | 'rendering-preview'
+    | 'committing'
+    | 'error';
+  error: SamSessionError | null;
+  hasPreview: boolean;
+}
+export type LayerFilterSettings = RasterFilterSettings;
+export interface FilterOperationPreview {
+  guard: LayerExportGuard;
+  imageName: string;
+  rect: Rect;
+  width: number;
+  height: number;
+  origin: { x: number; y: number };
+}
+export interface FilterOperationSessionState {
+  autoProcess: boolean;
+  draft: LayerFilterSettings;
+  error: string | null;
+  initialFilter: LayerFilterSettings | null;
+  layerId: string;
+  layerName: string;
+  layerType: 'raster' | 'control';
+  preview: FilterOperationPreview | null;
+  status: 'ready' | 'processing' | 'committing' | 'error';
+}
+export type FilterCommitTarget = RasterFilterCommitTarget;
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/saveCanvasToGallery.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/saveCanvasToGallery.test.ts
new file mode 100644
index 00000000000..d7b33aa709f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/saveCanvasToGallery.test.ts
@@ -0,0 +1,253 @@
+import type { CanvasEngine } from '@workbench/canvas-engine/engine';
+import type { RasterCompositeExportResult } from '@workbench/canvas-engine/exportRasterComposite';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { GenerateModelConfig, GenerateWidgetValues, MainModelConfig } from '@workbench/generation/types';
+import type { CanvasDocumentContractV2, Project } from '@workbench/types';
+
+import { getDefaultGenerateSettings } from '@workbench/generation/baseGenerationPolicies';
+import { getProjectWidgetInstance } from '@workbench/widgetState';
+import { createInitialWorkbenchState } from '@workbench/workbenchState';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { uploadCanvasImage } from './backend/canvasImages';
+
+import { saveCanvasToGallery } from './saveCanvasToGallery';
+
+const model: MainModelConfig = {
+  base: 'sd-1',
+  hash: 'model-hash',
+  key: 'model-key',
+  name: 'Test Model',
+  type: 'main',
+};
+
+const defaultRect: Rect = { height: 456, width: 123, x: -4, y: 8 };
+const defaultBlob = new Blob(['pixels'], { type: 'image/png' });
+
+const createProject = (boardId = 'board-1', generateOverrides: Partial<GenerateWidgetValues> = {}): Project => {
+  const project = createInitialWorkbenchState().projects[0]!;
+  const generate = getProjectWidgetInstance(project, 'generate');
+  const gallery = getProjectWidgetInstance(project, 'gallery');
+
+  if (!generate || !gallery) {
+    throw new Error('Expected initial project to contain generate and gallery widgets');
+  }
+
+  generate.state.values = {
+    ...getDefaultGenerateSettings(model),
+    model,
+    modelKey: model.key,
+    negativePromptEnabled: true,
+    negativePrompt: 'avoid blur',
+    positivePrompt: 'a canvas prompt',
+    seed: 123,
+    ...generateOverrides,
+  };
+  gallery.state.values = { ...gallery.state.values, selectedBoardId: boardId };
+
+  return project;
+};
+
+const createDocument = (bbox: Rect): CanvasDocumentContractV2 => ({ bbox }) as unknown as CanvasDocumentContractV2;
+
+const createHarness = (
+  options: {
+    document?: CanvasDocumentContractV2 | null;
+    exportResult?: RasterCompositeExportResult;
+    onFlush?: () => void;
+  } = {}
+) => {
+  const order: string[] = [];
+  let document = options.document === undefined ? createDocument(defaultRect) : options.document;
+  const exportResult = options.exportResult ?? { blob: defaultBlob, rect: defaultRect, status: 'ok' };
+  const flushPendingUploads = vi.fn(() => {
+    order.push('flush');
+    options.onFlush?.();
+    return Promise.resolve();
+  });
+  const getDocument = vi.fn(() => {
+    order.push('document');
+    return document;
+  });
+  const exportRasterComposite = vi.fn<CanvasEngine['exports']['exportRasterComposite']>(() => {
+    order.push('export');
+    return Promise.resolve(exportResult);
+  });
+  const uploadImage = vi.fn<typeof uploadCanvasImage>(() => {
+    order.push('upload');
+    return Promise.resolve({ height: defaultRect.height, imageName: 'saved.png', width: defaultRect.width });
+  });
+  const engine = {
+    document: { getDocument },
+    exports: { exportRasterComposite },
+    lifecycle: { flushPendingUploads },
+  } as unknown as CanvasEngine;
+
+  return {
+    engine,
+    exportRasterComposite,
+    flushPendingUploads,
+    getDocument,
+    order,
+    setDocument: (next: CanvasDocumentContractV2 | null) => {
+      document = next;
+    },
+    uploadImage,
+  };
+};
+
+describe('saveCanvasToGallery', () => {
+  it('flushes before exporting canvas content and uploads with gallery metadata', async () => {
+    const harness = createHarness();
+
+    await expect(
+      saveCanvasToGallery({
+        engine: harness.engine,
+        project: createProject(),
+        region: 'canvas',
+        uploadImage: harness.uploadImage,
+      })
+    ).resolves.toEqual({ imageName: 'saved.png', status: 'saved' });
+
+    expect(harness.order).toEqual(['flush', 'document', 'export', 'upload']);
+    expect(harness.exportRasterComposite).toHaveBeenCalledWith({ bounds: 'content' });
+    expect(harness.uploadImage).toHaveBeenCalledWith(defaultBlob, {
+      boardId: 'board-1',
+      fileName: 'canvas.png',
+      imageCategory: 'general',
+      isIntermediate: false,
+      metadata: {
+        height: 456,
+        model: { base: 'sd-1', hash: 'model-hash', key: 'model-key', name: 'Test Model', type: 'main' },
+        negative_prompt: 'avoid blur',
+        positive_prompt: 'a canvas prompt',
+        seed: 123,
+        width: 123,
+      },
+    });
+  });
+
+  it('exports the post-flush document bbox and uses the bbox filename', async () => {
+    const preFlushRect: Rect = { height: 20, width: 10, x: 0, y: 0 };
+    const postFlushRect: Rect = { height: 40, width: 30, x: 5, y: 6 };
+    let harness: ReturnType<typeof createHarness>;
+    harness = createHarness({
+      document: createDocument(preFlushRect),
+      onFlush: () => harness.setDocument(createDocument(postFlushRect)),
+    });
+
+    await saveCanvasToGallery({
+      engine: harness.engine,
+      project: createProject(),
+      region: 'bbox',
+      uploadImage: harness.uploadImage,
+    });
+
+    expect(harness.exportRasterComposite).toHaveBeenCalledWith({ bounds: 'rect', rect: postFlushRect });
+    expect(harness.uploadImage).toHaveBeenCalledWith(defaultBlob, expect.objectContaining({ fileName: 'bbox.png' }));
+  });
+
+  it.each([
+    ['board-physical', 'board-physical'],
+    ['none', undefined],
+    ['by_date:2026-07-15', undefined],
+  ])('normalizes selected board %s to upload board %s', async (selectedBoardId, expectedBoardId) => {
+    const harness = createHarness();
+
+    await saveCanvasToGallery({
+      engine: harness.engine,
+      project: createProject(selectedBoardId),
+      region: 'canvas',
+      uploadImage: harness.uploadImage,
+    });
+
+    expect(harness.uploadImage.mock.calls[0]?.[1]?.boardId).toBe(expectedBoardId);
+  });
+
+  it('omits disabled negative prompts and unsupported models from metadata', async () => {
+    const unsupportedModel: GenerateModelConfig = {
+      base: 'unsupported',
+      key: 'unsupported-model',
+      name: 'Unsupported Model',
+      type: 'main',
+    };
+    const harness = createHarness();
+
+    await saveCanvasToGallery({
+      engine: harness.engine,
+      project: createProject('none', {
+        model: unsupportedModel,
+        modelKey: unsupportedModel.key,
+        negativePromptEnabled: false,
+      }),
+      region: 'canvas',
+      uploadImage: harness.uploadImage,
+    });
+
+    const metadata = harness.uploadImage.mock.calls[0]?.[1]?.metadata;
+    expect(metadata).not.toHaveProperty('model');
+    expect(metadata).not.toHaveProperty('negative_prompt');
+    expect(metadata).toMatchObject({ height: 456, positive_prompt: 'a canvas prompt', seed: 123, width: 123 });
+  });
+
+  it.each(['empty', 'stale', 'not-ready'] as const)('returns %s without uploading', async (status) => {
+    const harness = createHarness({ exportResult: { status } });
+
+    await expect(
+      saveCanvasToGallery({
+        engine: harness.engine,
+        project: createProject(),
+        region: 'canvas',
+        uploadImage: harness.uploadImage,
+      })
+    ).resolves.toEqual({ status });
+
+    expect(harness.uploadImage).not.toHaveBeenCalled();
+  });
+
+  it('returns not-ready without exporting when there is no post-flush document', async () => {
+    const harness = createHarness({ document: null });
+
+    await expect(
+      saveCanvasToGallery({
+        engine: harness.engine,
+        project: createProject(),
+        region: 'bbox',
+        uploadImage: harness.uploadImage,
+      })
+    ).resolves.toEqual({ status: 'not-ready' });
+
+    expect(harness.exportRasterComposite).not.toHaveBeenCalled();
+    expect(harness.uploadImage).not.toHaveBeenCalled();
+  });
+
+  it('propagates export rejection without uploading', async () => {
+    const harness = createHarness();
+    harness.exportRasterComposite.mockRejectedValueOnce(new Error('export failed'));
+
+    await expect(
+      saveCanvasToGallery({
+        engine: harness.engine,
+        project: createProject(),
+        region: 'canvas',
+        uploadImage: harness.uploadImage,
+      })
+    ).rejects.toThrow('export failed');
+
+    expect(harness.uploadImage).not.toHaveBeenCalled();
+  });
+
+  it('propagates upload rejection', async () => {
+    const harness = createHarness();
+    harness.uploadImage.mockRejectedValueOnce(new Error('upload failed'));
+
+    await expect(
+      saveCanvasToGallery({
+        engine: harness.engine,
+        project: createProject(),
+        region: 'canvas',
+        uploadImage: harness.uploadImage,
+      })
+    ).rejects.toThrow('upload failed');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/saveCanvasToGallery.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/saveCanvasToGallery.ts
new file mode 100644
index 00000000000..3cc872c6bb9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/saveCanvasToGallery.ts
@@ -0,0 +1,85 @@
+import type {
+  CanvasDocumentCapability,
+  CanvasExportCapability,
+  CanvasLifecycleCapability,
+} from '@workbench/canvas-engine/api';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { Project } from '@workbench/types';
+
+import { isDateBoardId } from '@workbench/gallery/api';
+import { isSupportedGenerateModel } from '@workbench/generation/baseGenerationPolicies';
+import { toModelIdentifier } from '@workbench/generation/graphBuilder';
+import { normalizeGenerateWidgetValues } from '@workbench/generation/settings';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+
+import { uploadCanvasImage } from './backend/canvasImages';
+
+export type CanvasGallerySaveRegion = 'canvas' | 'bbox';
+
+export type SaveCanvasToGalleryResult =
+  | { status: 'saved'; imageName: string }
+  | { status: 'empty' | 'stale' | 'not-ready' | 'over-budget' };
+
+type CanvasGallerySaveEngine = {
+  readonly document: CanvasDocumentCapability;
+  readonly exports: Pick<CanvasExportCapability, 'exportRasterComposite'>;
+  readonly lifecycle: Pick<CanvasLifecycleCapability, 'flushPendingUploads'>;
+};
+
+const buildCanvasSaveMetadata = (project: Project, rect: Rect): Record<string, unknown> => {
+  const generateValues = normalizeGenerateWidgetValues(getProjectWidgetValues(project, 'generate'));
+  const dimensions = { height: rect.height, width: rect.width };
+
+  if (!generateValues) {
+    return dimensions;
+  }
+
+  return {
+    ...dimensions,
+    ...(isSupportedGenerateModel(generateValues.model) ? { model: toModelIdentifier(generateValues.model) } : {}),
+    ...(generateValues.negativePromptEnabled ? { negative_prompt: generateValues.negativePrompt } : {}),
+    positive_prompt: generateValues.positivePrompt,
+    seed: generateValues.seed,
+  };
+};
+
+const getCanvasSaveBoardId = (project: Project): string | undefined => {
+  const selectedBoardId = getProjectWidgetValues(project, 'gallery').selectedBoardId;
+
+  return typeof selectedBoardId === 'string' && selectedBoardId !== 'none' && !isDateBoardId(selectedBoardId)
+    ? selectedBoardId
+    : undefined;
+};
+
+export const saveCanvasToGallery = async (options: {
+  engine: CanvasGallerySaveEngine;
+  region: CanvasGallerySaveRegion;
+  project: Project;
+  uploadImage?: typeof uploadCanvasImage;
+}): Promise<SaveCanvasToGalleryResult> => {
+  const { engine, project, region, uploadImage = uploadCanvasImage } = options;
+  const boardId = getCanvasSaveBoardId(project);
+
+  await engine.lifecycle.flushPendingUploads();
+  const document = engine.document.getDocument();
+  if (!document) {
+    return { status: 'not-ready' };
+  }
+
+  const exported = await engine.exports.exportRasterComposite(
+    region === 'canvas' ? { bounds: 'content' } : { bounds: 'rect', rect: document.bbox }
+  );
+  if (exported.status !== 'ok') {
+    return exported;
+  }
+
+  const uploaded = await uploadImage(exported.blob, {
+    boardId,
+    fileName: region === 'canvas' ? 'canvas.png' : 'bbox.png',
+    imageCategory: 'general',
+    isIntermediate: false,
+    metadata: buildCanvasSaveMetadata(project, exported.rect),
+  });
+
+  return { imageName: uploaded.imageName, status: 'saved' };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/selectObjectSession.test.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/selectObjectSession.test.ts
new file mode 100644
index 00000000000..83cc88af1d1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/selectObjectSession.test.ts
@@ -0,0 +1,947 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/engine';
+import type { SamSessionError } from '@workbench/canvas-operations/operationTypes';
+import type { CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { UtilityQueueError } from '@workbench/canvas-operations/backend/utilityQueue';
+import { createCanvasOperationController } from '@workbench/canvas-operations/operationController';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { SelectObjectSessionDeps } from './selectObjectSession';
+
+import { createSelectObjectSession } from './selectObjectSession';
+
+const layer: CanvasRasterLayerContractV2 = {
+  blendMode: 'normal',
+  id: 'source',
+  isEnabled: true,
+  isLocked: false,
+  name: 'Source',
+  opacity: 1,
+  source: { fill: '#fff', height: 12, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 16 },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: -5, y: 7 },
+  type: 'raster',
+};
+const guard: LayerExportGuard = {
+  cacheVersion: 3,
+  documentGeneration: 4,
+  layer,
+  layerId: layer.id,
+  projectId: 'p1',
+};
+const replacementGuard: LayerExportGuard = {
+  ...guard,
+  cacheVersion: 4,
+};
+const cloneGuard = (source: LayerExportGuard = guard): LayerExportGuard => ({ ...source });
+const rect = { height: 12, width: 16, x: -5, y: 7 };
+const blob = new Blob(['source'], { type: 'image/png' });
+
+const deferred = <T>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+const createHarness = (overrides: Partial<SelectObjectSessionDeps<string>> = {}) => {
+  let currentGuard: LayerExportGuard | null = guard;
+  let controllerSubscriber: (() => void) | null = null;
+  const unsubscribe = vi.fn();
+  const baseController = createCanvasOperationController({
+    isGuardCurrent: (candidate) => candidate === guard,
+  });
+  const controller = {
+    ...baseController,
+    subscribe: vi.fn((listener: () => void) => {
+      controllerSubscriber = listener;
+      const detach = baseController.subscribe(listener);
+      return () => {
+        unsubscribe();
+        detach();
+      };
+    }),
+  };
+  const deps: SelectObjectSessionDeps<string> = {
+    captureGuard: vi.fn(() => currentGuard),
+    controller,
+    decodePreview: vi.fn(({ image }) => Promise.resolve(`decoded:${image.imageName}`)),
+    exportSource: vi.fn(() => Promise.resolve({ blob, guard: currentGuard ?? guard, rect, status: 'ok' as const })),
+    isGuardCurrent: (candidate) => candidate === currentGuard,
+    publishPreview: vi.fn((): undefined => undefined),
+    cleanupPreview: vi.fn(),
+    runGraph: vi.fn(() =>
+      Promise.resolve({ height: 12, imageName: 'result.png', origin: 'webv2:util:test', width: 16 })
+    ),
+    uploadIntermediate: vi.fn(() => Promise.resolve({ height: 12, imageName: 'input.png', width: 16 })),
+    ...overrides,
+  };
+  const operation = controller.start({
+    cleanupPreview: deps.cleanupPreview,
+    guard,
+    identity: { kind: 'select-object', layerId: layer.id, projectId: 'p1' },
+  });
+  if (!operation) {
+    throw new Error('expected Select Object operation');
+  }
+  const session = createSelectObjectSession({ deps, operation });
+  session.update({ input: { prompt: 'cat', type: 'prompt' } });
+  return {
+    controller,
+    deps,
+    fireControllerSubscriber() {
+      controllerSubscriber?.();
+    },
+    session,
+    setCurrentGuard(next: LayerExportGuard | null) {
+      currentGuard = next;
+    },
+    unsubscribe,
+  };
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('createSelectObjectSession', () => {
+  it('exposes the complete default processing state', () => {
+    const { session } = createHarness();
+
+    expect(session.getSnapshot()).toMatchObject({
+      applyPolygonRefinement: false,
+      autoProcess: false,
+      error: null,
+      input: { prompt: 'cat', type: 'prompt' },
+      invert: false,
+      isolatedPreview: true,
+      model: 'segment-anything-2-large',
+      preview: null,
+      sourceGuard: null,
+      status: 'ready',
+    });
+  });
+
+  it('reports phases from the source export, upload, SAM, render, and ready boundaries', async () => {
+    const harness = createHarness();
+    const phases: string[] = [];
+    harness.session.subscribe(() => phases.push(harness.session.getSnapshot().status));
+
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    expect(phases).toEqual(['preparing-source', 'uploading', 'processing-sam', 'rendering-preview', 'ready']);
+  });
+
+  it('does not publish a stale request phase after a replacement retry starts', async () => {
+    const oldUpload = deferred<{ height: number; imageName: string; width: number }>();
+    const harness = createHarness({
+      uploadIntermediate: vi
+        .fn()
+        .mockImplementationOnce(() => oldUpload.promise)
+        .mockResolvedValueOnce({ height: 12, imageName: 'new-source.png', width: 16 }),
+    });
+    const phases: string[] = [];
+    harness.session.subscribe(() => phases.push(harness.session.getSnapshot().status));
+    const oldPending = harness.session.process();
+    await vi.waitFor(() => expect(harness.session.getSnapshot().status).toBe('uploading'));
+
+    harness.setCurrentGuard(replacementGuard);
+    vi.mocked(harness.deps.exportSource).mockResolvedValue({ blob, guard: replacementGuard, rect, status: 'ok' });
+    const newPending = harness.session.process();
+    await expect(newPending).resolves.toBe('published');
+    const readyIndex = phases.lastIndexOf('ready');
+    oldUpload.resolve({ height: 12, imageName: 'old-source.png', width: 16 });
+    await expect(oldPending).resolves.toBe('stale');
+
+    expect(phases.slice(readyIndex + 1)).toEqual([]);
+    expect(harness.session.getSnapshot()).toMatchObject({ status: 'ready' });
+  });
+
+  it('contains subscriber exceptions so healthy subscribers and processing continue', async () => {
+    const harness = createHarness();
+    const throwing = vi.fn(() => {
+      throw new Error('subscriber failed');
+    });
+    const healthy = vi.fn();
+    harness.session.subscribe(throwing);
+    harness.session.subscribe(healthy);
+
+    expect(() => harness.session.update({ model: 'segment-anything-huge' })).not.toThrow();
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    expect(throwing).toHaveBeenCalled();
+    expect(healthy).toHaveBeenCalled();
+    expect(harness.session.getSnapshot()).toMatchObject({ error: null, status: 'ready' });
+  });
+
+  it('never publishes error status without an error and returns to ready when update clears it', async () => {
+    const harness = createHarness();
+    const snapshots: Array<{ error: SamSessionError | null; status: string }> = [];
+    harness.session.subscribe(() => {
+      const { error, status } = harness.session.getSnapshot();
+      snapshots.push({ error, status });
+    });
+    harness.session.update({ input: { prompt: '   ', type: 'prompt' } });
+
+    await expect(harness.session.process()).resolves.toBe('invalid');
+    expect(harness.session.getSnapshot()).toMatchObject({
+      error: { code: 'invalid' },
+      status: 'error',
+    });
+
+    harness.session.update({ autoProcess: false });
+
+    expect(harness.session.getSnapshot()).toMatchObject({ error: null, status: 'ready' });
+    expect(snapshots.every(({ error, status }) => (status === 'error') === (error !== null))).toBe(true);
+  });
+
+  it('keeps a non-null error whenever processing fails', async () => {
+    const harness = createHarness({ runGraph: vi.fn(() => Promise.reject(new Error('graph failed'))) });
+
+    await expect(harness.session.process()).resolves.toBe('error');
+
+    expect(harness.session.getSnapshot()).toEqual(
+      expect.objectContaining({ error: { code: 'queue', detail: 'graph failed' }, status: 'error' })
+    );
+  });
+
+  it('retries the same input after a dimension mismatch and publishes the corrected output', async () => {
+    const runGraph = vi
+      .fn()
+      .mockResolvedValueOnce({ height: 12, imageName: 'bad.png', origin: 'test', width: 15 })
+      .mockResolvedValueOnce({ height: 12, imageName: 'good.png', origin: 'test', width: 16 });
+    const harness = createHarness({ runGraph });
+
+    await expect(harness.session.process()).resolves.toBe('error');
+    expect(harness.session.getSnapshot()).toMatchObject({ preview: null, status: 'error' });
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    expect(runGraph).toHaveBeenCalledTimes(2);
+    expect(harness.session.getSnapshot()).toMatchObject({ error: null, status: 'ready' });
+    expect(harness.session.getSnapshot().preview?.image.imageName).toBe('good.png');
+  });
+
+  it('reports routing failures without discarding the preview and Reset clears the error', async () => {
+    const harness = createHarness();
+    await harness.session.process();
+    const preview = harness.session.getSnapshot().preview;
+
+    harness.session.reportError('commit failed');
+
+    expect(harness.session.getSnapshot()).toMatchObject({
+      error: { code: 'unknown', detail: 'commit failed' },
+      preview,
+      status: 'error',
+    });
+    harness.session.reset();
+    expect(harness.session.getSnapshot()).toMatchObject({ error: null, preview: null, status: 'ready' });
+  });
+
+  it.each([
+    ['no-output', new UtilityQueueError('no-output', 'No output image.')],
+    ['reconcile', new UtilityQueueError('reconcile', 'Queue lookup failed.')],
+    ['queue', new UtilityQueueError('failed', 'SAM backend failed.')],
+  ] as const)('maps utility queue failures to %s session errors', async (code, cause) => {
+    const harness = createHarness({ runGraph: vi.fn(() => Promise.reject(cause)) });
+
+    await expect(harness.session.process()).resolves.toBe('error');
+
+    expect(harness.session.getSnapshot()).toMatchObject({ error: { code, detail: cause.message }, status: 'error' });
+  });
+
+  it('preserves a backend exception type as queue diagnostics', async () => {
+    const harness = createHarness({
+      runGraph: vi.fn(() => Promise.reject(new UtilityQueueError('failed', 'AttributeError'))),
+    });
+
+    await expect(harness.session.process()).resolves.toBe('error');
+
+    expect(harness.session.getSnapshot()).toMatchObject({
+      error: { code: 'queue', detail: 'AttributeError' },
+      status: 'error',
+    });
+  });
+
+  it('maps upload failures to a typed upload error', async () => {
+    const harness = createHarness({
+      uploadIntermediate: vi.fn(() => Promise.reject(new Error('upload service unavailable'))),
+    });
+
+    await expect(harness.session.process()).resolves.toBe('error');
+
+    expect(harness.session.getSnapshot()).toMatchObject({
+      error: { code: 'upload', detail: 'upload service unavailable' },
+      status: 'error',
+    });
+  });
+
+  it('maps empty and not-ready sources to typed errors', async () => {
+    const empty = createHarness({ exportSource: vi.fn(() => Promise.resolve({ status: 'empty' as const })) });
+    await expect(empty.session.process()).resolves.toBe('error');
+    expect(empty.session.getSnapshot().error).toEqual({ code: 'empty' });
+
+    const notReady = createHarness();
+    notReady.setCurrentGuard(null);
+    await expect(notReady.session.process()).resolves.toBe('error');
+    expect(notReady.session.getSnapshot().error).toEqual({ code: 'not-ready' });
+  });
+
+  it('maps output dimensions and decode failures to typed errors', async () => {
+    const uploadDimensions = createHarness({
+      uploadIntermediate: vi.fn(() => Promise.resolve({ height: 12, imageName: 'bad-source.png', width: 15 })),
+    });
+    await expect(uploadDimensions.session.process()).resolves.toBe('error');
+    expect(uploadDimensions.session.getSnapshot().error).toMatchObject({ code: 'output-dimension' });
+
+    const dimensions = createHarness({
+      runGraph: vi.fn(() => Promise.resolve({ height: 12, imageName: 'bad.png', origin: 'test', width: 15 })),
+    });
+    await expect(dimensions.session.process()).resolves.toBe('error');
+    expect(dimensions.session.getSnapshot().error).toMatchObject({ code: 'output-dimension' });
+
+    const decode = createHarness({ decodePreview: vi.fn(() => Promise.reject(new Error('corrupt PNG'))) });
+    await expect(decode.session.process()).resolves.toBe('error');
+    expect(decode.session.getSnapshot().error).toEqual({ code: 'decode', detail: 'corrupt PNG' });
+  });
+
+  it('accepts typed locked errors while preserving string compatibility as unknown diagnostics', () => {
+    const harness = createHarness();
+
+    harness.session.reportError({ code: 'locked' });
+    expect(harness.session.getSnapshot().error).toEqual({ code: 'locked' });
+
+    harness.session.reportError('legacy failure detail');
+    expect(harness.session.getSnapshot().error).toEqual({ code: 'unknown', detail: 'legacy failure detail' });
+  });
+
+  it('survives source invalidation of other layers but closes when its own layer is invalidated', async () => {
+    const harness = createHarness({ runGraph: vi.fn(() => Promise.reject(new Error('graph failed'))) });
+    await expect(harness.session.process()).resolves.toBe('error');
+
+    harness.controller.invalidateSource('p1', 'other-layer');
+
+    expect(harness.session.getSnapshot()).toMatchObject({ error: { code: 'queue' }, status: 'error' });
+    expect(harness.controller.getSnapshot()).toMatchObject({ status: 'active' });
+
+    harness.controller.invalidateSource('p1', layer.id);
+
+    expect(harness.controller.getSnapshot()).toMatchObject({ status: 'idle' });
+    expect(harness.session.getSnapshot()).toMatchObject({ preview: null, sourceGuard: null, status: 'ready' });
+  });
+
+  it('reuses an uploaded export only while its exact guard remains current', async () => {
+    const harness = createHarness();
+
+    await expect(harness.session.process()).resolves.toBe('published');
+    harness.session.update({ input: { prompt: 'dog', type: 'prompt' } });
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    expect(harness.deps.exportSource).toHaveBeenCalledTimes(1);
+    expect(harness.deps.uploadIntermediate).toHaveBeenCalledTimes(1);
+    expect(harness.deps.runGraph).toHaveBeenCalledTimes(2);
+    expect(harness.session.getSnapshot().sourceGuard).toBe(guard);
+
+    harness.setCurrentGuard(replacementGuard);
+    vi.mocked(harness.deps.exportSource).mockResolvedValue({
+      blob,
+      guard: replacementGuard,
+      rect,
+      status: 'ok',
+    });
+    harness.session.update({ input: { prompt: 'bird', type: 'prompt' } });
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    expect(harness.deps.exportSource).toHaveBeenCalledTimes(2);
+    expect(harness.deps.uploadIntermediate).toHaveBeenCalledTimes(2);
+    expect(harness.session.getSnapshot().sourceGuard).toBe(replacementGuard);
+  });
+
+  it('rebinds a prepared source across fresh structurally equal guards without another export or upload', async () => {
+    let currentGuard = cloneGuard();
+    const harness = createHarness({
+      captureGuard: () => currentGuard,
+      exportSource: vi.fn(() => Promise.resolve({ blob, guard: currentGuard, rect, status: 'ok' as const })),
+      isGuardCurrent: (candidate) =>
+        candidate.cacheVersion === currentGuard.cacheVersion &&
+        candidate.documentGeneration === currentGuard.documentGeneration,
+    });
+    harness.session.update({
+      input: { bbox: null, excludePoints: [], includePoints: [{ x: -4, y: 8 }], type: 'visual' },
+    });
+
+    await expect(harness.session.process()).resolves.toBe('published');
+    for (const update of [
+      { input: { bbox: null, excludePoints: [], includePoints: [{ x: -3, y: 9 }], type: 'visual' as const } },
+      { invert: true },
+      { applyPolygonRefinement: true },
+    ]) {
+      currentGuard = cloneGuard();
+      harness.session.update(update);
+      await expect(harness.session.process()).resolves.toBe('published');
+      expect(harness.session.getSnapshot().sourceGuard).toBe(currentGuard);
+    }
+
+    expect(harness.deps.exportSource).toHaveBeenCalledOnce();
+    expect(harness.deps.uploadIntermediate).toHaveBeenCalledOnce();
+    expect(harness.deps.runGraph).toHaveBeenCalledTimes(4);
+  });
+
+  it.each([
+    ['layer reference', { ...cloneGuard(), layer: { ...layer } }],
+    ['cache version', cloneGuard(replacementGuard)],
+    [
+      'document generation',
+      {
+        ...cloneGuard(),
+        documentGeneration: guard.documentGeneration + 1,
+      },
+    ],
+  ] as const)('does not reuse the prepared source after a changed %s guard', async (_label, nextGuard) => {
+    let currentGuard: LayerExportGuard = guard;
+    const harness = createHarness({
+      captureGuard: () => currentGuard,
+      exportSource: vi.fn(() => Promise.resolve({ blob, guard: currentGuard, rect, status: 'ok' as const })),
+      isGuardCurrent: (candidate) => candidate === currentGuard,
+    });
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    currentGuard = nextGuard;
+    harness.session.update({ input: { prompt: 'dog', type: 'prompt' } });
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    expect(harness.deps.exportSource).toHaveBeenCalledTimes(2);
+    expect(harness.deps.uploadIntermediate).toHaveBeenCalledTimes(2);
+  });
+
+  it.each(['layer', 'project', 'document'] as const)(
+    'invalidates the cached export and preview on %s invalidation',
+    async (kind) => {
+      const harness = createHarness();
+      await harness.session.process();
+      vi.mocked(harness.deps.cleanupPreview).mockClear();
+
+      if (kind === 'layer') {
+        harness.controller.invalidateLayer('p1', layer.id);
+      } else if (kind === 'project') {
+        harness.controller.invalidateProject('p1');
+      } else {
+        harness.controller.invalidateDocument('p1');
+      }
+
+      expect(harness.session.getSnapshot()).toMatchObject({ preview: null, sourceGuard: null, status: 'ready' });
+      expect(harness.deps.cleanupPreview).toHaveBeenCalledOnce();
+    }
+  );
+
+  it('starts an immediate same-input retry after invalidation when old work ignores abort', async () => {
+    const older = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const newer = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const harness = createHarness({
+      runGraph: vi
+        .fn()
+        .mockImplementationOnce(() => older.promise)
+        .mockImplementationOnce(() => newer.promise),
+    });
+    const oldPending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.setCurrentGuard(replacementGuard);
+    vi.mocked(harness.deps.exportSource).mockResolvedValue({ blob, guard: replacementGuard, rect, status: 'ok' });
+    const newPending = harness.session.process();
+
+    expect(newPending).not.toBe(oldPending);
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledTimes(2));
+    expect(harness.deps.exportSource).toHaveBeenCalledTimes(2);
+    older.resolve({ height: 12, imageName: 'old.png', origin: 'old', width: 16 });
+    await expect(oldPending).resolves.toBe('stale');
+    expect(harness.session.process()).toBe(newPending);
+
+    newer.resolve({ height: 12, imageName: 'new.png', origin: 'new', width: 16 });
+    await expect(newPending).resolves.toBe('published');
+    expect(harness.session.getSnapshot().preview?.image.imageName).toBe('new.png');
+    await expect(harness.session.process()).resolves.toBe('deduped');
+    expect(harness.deps.runGraph).toHaveBeenCalledTimes(2);
+  });
+
+  it('starts an immediate same-input retry when invalidation aborts an export that ignores its signal', async () => {
+    const oldExport = deferred<Awaited<ReturnType<SelectObjectSessionDeps<string>['exportSource']>>>();
+    const harness = createHarness({
+      exportSource: vi
+        .fn()
+        .mockImplementationOnce(() => oldExport.promise)
+        .mockImplementationOnce(() => Promise.resolve({ blob, guard: replacementGuard, rect, status: 'ok' as const })),
+    });
+    const oldPending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.exportSource).toHaveBeenCalledOnce());
+
+    harness.setCurrentGuard(replacementGuard);
+    vi.mocked(harness.deps.exportSource).mockResolvedValue({ blob, guard: replacementGuard, rect, status: 'ok' });
+    const newPending = harness.session.process();
+
+    expect(newPending).not.toBe(oldPending);
+    await expect(newPending).resolves.toBe('published');
+    expect(harness.deps.exportSource).toHaveBeenCalledTimes(2);
+    expect(harness.deps.uploadIntermediate).toHaveBeenCalledOnce();
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+    oldExport.resolve({ blob, guard, rect, status: 'ok' });
+    await expect(oldPending).resolves.toBe('stale');
+    expect(harness.session.getSnapshot().preview?.image.imageName).toBe('result.png');
+    await expect(harness.session.process()).resolves.toBe('deduped');
+  });
+
+  it('starts an immediate same-input retry when invalidation aborts an upload that ignores its signal', async () => {
+    const oldUpload = deferred<{ height: number; imageName: string; width: number }>();
+    const harness = createHarness({
+      uploadIntermediate: vi
+        .fn()
+        .mockImplementationOnce(() => oldUpload.promise)
+        .mockImplementationOnce(() => Promise.resolve({ height: 12, imageName: 'new-input.png', width: 16 })),
+    });
+    const oldPending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.uploadIntermediate).toHaveBeenCalledOnce());
+
+    harness.setCurrentGuard(replacementGuard);
+    vi.mocked(harness.deps.exportSource).mockResolvedValue({ blob, guard: replacementGuard, rect, status: 'ok' });
+    const newPending = harness.session.process();
+
+    expect(newPending).not.toBe(oldPending);
+    await expect(newPending).resolves.toBe('published');
+    expect(harness.deps.exportSource).toHaveBeenCalledTimes(2);
+    expect(harness.deps.uploadIntermediate).toHaveBeenCalledTimes(2);
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+    oldUpload.resolve({ height: 12, imageName: 'old-input.png', width: 16 });
+    await expect(oldPending).resolves.toBe('stale');
+    expect(harness.session.getSnapshot().preview?.sourceImageName).toBe('new-input.png');
+    await expect(harness.session.process()).resolves.toBe('deduped');
+  });
+
+  it('deduplicates an identical stable input hash after publication', async () => {
+    const harness = createHarness();
+
+    await expect(harness.session.process()).resolves.toBe('published');
+    await expect(harness.session.process()).resolves.toBe('deduped');
+
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+  });
+
+  it('transitions an identical scheduled auto-run back to ready and preserves its preview', async () => {
+    vi.useFakeTimers();
+    const harness = createHarness();
+    await harness.session.process();
+    const preview = harness.session.getSnapshot().preview;
+    const listener = vi.fn();
+    harness.session.subscribe(listener);
+
+    harness.session.update({ autoProcess: true });
+    expect(harness.session.getSnapshot().status).toBe('scheduled');
+    listener.mockClear();
+    await vi.advanceTimersByTimeAsync(1_000);
+
+    expect(harness.session.getSnapshot()).toMatchObject({ error: null, preview, status: 'ready' });
+    expect(listener).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+  });
+
+  it('transitions an identical scheduled auto-run back to processing when work is already in flight', async () => {
+    vi.useFakeTimers();
+    const graph = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const harness = createHarness({ runGraph: vi.fn(() => graph.promise) });
+    const pending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.session.update({ autoProcess: true });
+    expect(harness.session.getSnapshot().status).toBe('scheduled');
+    await vi.advanceTimersByTimeAsync(1_000);
+
+    expect(harness.session.getSnapshot()).toMatchObject({ error: null, status: 'processing-sam' });
+    expect(vi.getTimerCount()).toBe(0);
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+    graph.resolve({ height: 12, imageName: 'result.png', origin: 'test', width: 16 });
+    await expect(pending).resolves.toBe('published');
+  });
+
+  it('does not deduplicate the same hash after its exact source guard is replaced', async () => {
+    const harness = createHarness();
+    await expect(harness.session.process()).resolves.toBe('published');
+
+    harness.setCurrentGuard(replacementGuard);
+    vi.mocked(harness.deps.exportSource).mockResolvedValue({ blob, guard: replacementGuard, rect, status: 'ok' });
+
+    await expect(harness.session.process()).resolves.toBe('published');
+    expect(harness.deps.exportSource).toHaveBeenCalledTimes(2);
+    expect(harness.deps.uploadIntermediate).toHaveBeenCalledTimes(2);
+    expect(harness.deps.runGraph).toHaveBeenCalledTimes(2);
+    expect(harness.session.getSnapshot().sourceGuard).toBe(replacementGuard);
+  });
+
+  it('debounces auto-processing for one second and manual processing runs immediately', async () => {
+    vi.useFakeTimers();
+    const harness = createHarness();
+    harness.session.update({ autoProcess: true });
+    harness.session.update({ input: { prompt: 'first', type: 'prompt' } });
+    await vi.advanceTimersByTimeAsync(500);
+    harness.session.update({ input: { prompt: 'second', type: 'prompt' } });
+    await vi.advanceTimersByTimeAsync(999);
+    expect(harness.deps.exportSource).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.session.update({ input: { prompt: 'manual', type: 'prompt' } });
+    await expect(harness.session.process()).resolves.toBe('published');
+    expect(harness.deps.runGraph).toHaveBeenCalledTimes(2);
+  });
+
+  it('immediately stales a delayed auto-run when input changes before the replacement debounce', async () => {
+    vi.useFakeTimers();
+    const oldGraph = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const harness = createHarness({ runGraph: vi.fn(() => oldGraph.promise) });
+    harness.session.update({ autoProcess: true });
+    await vi.advanceTimersByTimeAsync(1_000);
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.session.update({ input: { prompt: 'dog', type: 'prompt' } });
+    expect(harness.session.getSnapshot()).toMatchObject({ preview: null, status: 'scheduled' });
+    oldGraph.resolve({ height: 12, imageName: 'old.png', origin: 'old', width: 16 });
+    await vi.advanceTimersByTimeAsync(999);
+
+    expect(harness.deps.publishPreview).not.toHaveBeenCalled();
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    ['input', { input: { prompt: 'dog', type: 'prompt' as const } }],
+    ['model', { model: 'segment-anything-huge' as const }],
+    ['invert', { invert: true }],
+    ['refinement', { applyPolygonRefinement: true }],
+  ] as const)('immediately aborts in-flight work and clears preview for a %s update', async (_label, update) => {
+    const signals: AbortSignal[] = [];
+    const graph = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const harness = createHarness({
+      runGraph: vi.fn((options) => {
+        if (options.signal) {
+          signals.push(options.signal);
+        }
+        return graph.promise;
+      }),
+    });
+    const pending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.session.update(update);
+
+    expect(signals[0]?.aborted).toBe(true);
+    expect(harness.session.getSnapshot().preview).toBeNull();
+    graph.resolve({ height: 12, imageName: 'stale.png', origin: 'stale', width: 16 });
+    await expect(pending).resolves.toBe('stale');
+    expect(harness.deps.publishPreview).not.toHaveBeenCalled();
+  });
+
+  it('changes ready preview isolation without clearing or reprocessing it', async () => {
+    const harness = createHarness();
+    await harness.session.process();
+    const preview = harness.session.getSnapshot().preview;
+    vi.mocked(harness.deps.publishPreview).mockClear();
+    vi.mocked(harness.deps.runGraph).mockClear();
+    vi.mocked(harness.deps.cleanupPreview).mockClear();
+
+    harness.session.update({ isolatedPreview: false });
+
+    expect(harness.session.getSnapshot()).toMatchObject({ isolatedPreview: false });
+    expect(harness.session.getSnapshot().preview).toMatchObject({ data: preview?.data, isolated: false });
+    expect(harness.deps.publishPreview).toHaveBeenCalledOnce();
+    expect(harness.deps.cleanupPreview).not.toHaveBeenCalled();
+    expect(harness.deps.runGraph).not.toHaveBeenCalled();
+  });
+
+  it('changes isolation during processing without aborting or rerunning the request', async () => {
+    const graph = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const signals: AbortSignal[] = [];
+    const harness = createHarness({
+      runGraph: vi.fn((options) => {
+        if (options.signal) {
+          signals.push(options.signal);
+        }
+        return graph.promise;
+      }),
+    });
+    const pending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.session.update({ isolatedPreview: false });
+    graph.resolve({ height: 12, imageName: 'result.png', origin: 'test', width: 16 });
+
+    await expect(pending).resolves.toBe('published');
+    expect(signals[0]?.aborted).toBe(false);
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+    expect(harness.session.getSnapshot().preview).toMatchObject({ isolated: false });
+  });
+
+  it('clears an already-published preview as soon as processing input changes', async () => {
+    const harness = createHarness();
+    await harness.session.process();
+    vi.mocked(harness.deps.cleanupPreview).mockClear();
+
+    harness.session.update({ model: 'segment-anything-huge' });
+
+    expect(harness.session.getSnapshot()).toMatchObject({ preview: null, status: 'ready' });
+    expect(harness.deps.cleanupPreview).toHaveBeenCalledOnce();
+  });
+
+  it('rejects non-finite document input before hashing or scheduling work', async () => {
+    vi.useFakeTimers();
+    const harness = createHarness();
+    harness.session.update({ autoProcess: true });
+    harness.session.update({
+      input: {
+        bbox: null,
+        excludePoints: [],
+        includePoints: [{ x: Number.NaN, y: 1 }],
+        type: 'visual',
+      },
+    });
+
+    await expect(harness.session.process()).resolves.toBe('invalid');
+    await vi.runAllTimersAsync();
+    expect(harness.deps.exportSource).not.toHaveBeenCalled();
+    expect(harness.deps.runGraph).not.toHaveBeenCalled();
+  });
+
+  it('publishes only the latest request when graph completions arrive out of order', async () => {
+    const older = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const newer = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const harness = createHarness({
+      runGraph: vi
+        .fn()
+        .mockImplementationOnce(() => older.promise)
+        .mockImplementationOnce(() => newer.promise),
+    });
+    const oldPending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+    harness.session.update({ input: { prompt: 'dog', type: 'prompt' } });
+    const newPending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledTimes(2));
+
+    newer.resolve({ height: 12, imageName: 'new.png', origin: 'new', width: 16 });
+    await expect(newPending).resolves.toBe('published');
+    older.resolve({ height: 12, imageName: 'old.png', origin: 'old', width: 16 });
+    await expect(oldPending).resolves.toBe('stale');
+
+    expect(harness.deps.publishPreview).toHaveBeenCalledOnce();
+    expect(harness.session.getSnapshot().preview?.image.imageName).toBe('new.png');
+  });
+
+  it.each(['export', 'upload', 'queue', 'decode'] as const)(
+    'cancels safely at the %s boundary without starting later work',
+    async (boundary) => {
+      const wait = deferred<unknown>();
+      const harness = createHarness({
+        decodePreview:
+          boundary === 'decode'
+            ? vi.fn(() => wait.promise as Promise<string>)
+            : vi.fn(({ image }) => Promise.resolve(`decoded:${image.imageName}`)),
+        exportSource:
+          boundary === 'export'
+            ? vi.fn(() => wait.promise as ReturnType<SelectObjectSessionDeps<string>['exportSource']>)
+            : vi.fn(() => Promise.resolve({ blob, guard, rect, status: 'ok' as const })),
+        runGraph:
+          boundary === 'queue'
+            ? vi.fn(() => wait.promise as ReturnType<SelectObjectSessionDeps<string>['runGraph']>)
+            : vi.fn(() => Promise.resolve({ height: 12, imageName: 'result.png', origin: 'test', width: 16 })),
+        uploadIntermediate:
+          boundary === 'upload'
+            ? vi.fn(() => wait.promise as ReturnType<SelectObjectSessionDeps<string>['uploadIntermediate']>)
+            : vi.fn(() => Promise.resolve({ height: 12, imageName: 'input.png', width: 16 })),
+      });
+      const pending = harness.session.process();
+      await vi.waitFor(() => {
+        const fn =
+          boundary === 'export'
+            ? harness.deps.exportSource
+            : boundary === 'upload'
+              ? harness.deps.uploadIntermediate
+              : boundary === 'queue'
+                ? harness.deps.runGraph
+                : harness.deps.decodePreview;
+        expect(fn).toHaveBeenCalledOnce();
+      });
+
+      harness.session.cancel();
+      if (boundary === 'export') {
+        wait.resolve({ blob, guard, rect, status: 'ok' });
+      } else if (boundary === 'upload') {
+        wait.resolve({ height: 12, imageName: 'input.png', width: 16 });
+      } else if (boundary === 'queue') {
+        wait.resolve({ height: 12, imageName: 'result.png', origin: 'test', width: 16 });
+      } else {
+        wait.resolve('decoded');
+      }
+
+      await expect(pending).resolves.toBe('stale');
+      expect(harness.deps.publishPreview).not.toHaveBeenCalled();
+      expect(harness.deps.uploadIntermediate).toHaveBeenCalledTimes(boundary === 'export' ? 0 : 1);
+      expect(harness.deps.runGraph).toHaveBeenCalledTimes(boundary === 'export' || boundary === 'upload' ? 0 : 1);
+      expect(harness.deps.decodePreview).toHaveBeenCalledTimes(
+        boundary === 'export' || boundary === 'upload' || boundary === 'queue' ? 0 : 1
+      );
+    }
+  );
+
+  it.each(['export', 'upload', 'queue', 'decode'] as const)(
+    'interrupts processing at the %s boundary while preserving inputs and the active operation',
+    async (boundary) => {
+      const wait = deferred<unknown>();
+      const harness = createHarness({
+        decodePreview:
+          boundary === 'decode'
+            ? vi.fn(() => wait.promise as Promise<string>)
+            : vi.fn(({ image }) => Promise.resolve(`decoded:${image.imageName}`)),
+        exportSource:
+          boundary === 'export'
+            ? vi.fn(() => wait.promise as ReturnType<SelectObjectSessionDeps<string>['exportSource']>)
+            : vi.fn(() => Promise.resolve({ blob, guard, rect, status: 'ok' as const })),
+        runGraph:
+          boundary === 'queue'
+            ? vi.fn(() => wait.promise as ReturnType<SelectObjectSessionDeps<string>['runGraph']>)
+            : vi.fn(() => Promise.resolve({ height: 12, imageName: 'result.png', origin: 'test', width: 16 })),
+        uploadIntermediate:
+          boundary === 'upload'
+            ? vi.fn(() => wait.promise as ReturnType<SelectObjectSessionDeps<string>['uploadIntermediate']>)
+            : vi.fn(() => Promise.resolve({ height: 12, imageName: 'input.png', width: 16 })),
+      });
+      harness.session.update({ input: { prompt: 'keep me', type: 'prompt' }, invert: true });
+      const pending = harness.session.process();
+      await vi.waitFor(() => {
+        const fn =
+          boundary === 'export'
+            ? harness.deps.exportSource
+            : boundary === 'upload'
+              ? harness.deps.uploadIntermediate
+              : boundary === 'queue'
+                ? harness.deps.runGraph
+                : harness.deps.decodePreview;
+        expect(fn).toHaveBeenCalledOnce();
+      });
+
+      harness.session.interruptProcessing();
+      if (boundary === 'export') {
+        wait.resolve({ blob, guard, rect, status: 'ok' });
+      } else if (boundary === 'upload') {
+        wait.resolve({ height: 12, imageName: 'input.png', width: 16 });
+      } else if (boundary === 'queue') {
+        wait.resolve({ height: 12, imageName: 'result.png', origin: 'test', width: 16 });
+      } else {
+        wait.resolve('decoded');
+      }
+
+      await expect(pending).resolves.toBe('stale');
+      expect(harness.deps.publishPreview).not.toHaveBeenCalled();
+      expect(harness.session.getSnapshot()).toMatchObject({
+        input: { prompt: 'keep me', type: 'prompt' },
+        invert: true,
+        preview: null,
+        status: 'ready',
+      });
+      expect(harness.controller.getSnapshot()).toMatchObject({ phase: 'ready', status: 'active' });
+    }
+  );
+
+  it('suppresses a decoded preview when the source guard becomes stale', async () => {
+    const decode = deferred<string>();
+    const harness = createHarness({ decodePreview: vi.fn(() => decode.promise) });
+    const pending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.decodePreview).toHaveBeenCalledOnce());
+
+    harness.setCurrentGuard(null);
+    decode.resolve('decoded');
+
+    await expect(pending).resolves.toBe('stale');
+    expect(harness.deps.publishPreview).not.toHaveBeenCalled();
+    expect(harness.session.getSnapshot()).toMatchObject({ preview: null, sourceGuard: null, status: 'ready' });
+  });
+
+  it('reset cancels work and scheduling, clears preview/cache, and restores defaults', async () => {
+    vi.useFakeTimers();
+    const graph = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const harness = createHarness({ runGraph: vi.fn(() => graph.promise) });
+    harness.session.update({ autoProcess: true, invert: true, model: 'segment-anything-huge' });
+    const pending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.session.reset();
+    graph.resolve({ height: 12, imageName: 'late.png', origin: 'test', width: 16 });
+
+    await expect(pending).resolves.toBe('stale');
+    expect(harness.session.getSnapshot()).toEqual({
+      applyPolygonRefinement: false,
+      autoProcess: false,
+      error: null,
+      input: { prompt: '', type: 'prompt' },
+      invert: false,
+      isolatedPreview: true,
+      model: 'segment-anything-2-large',
+      preview: null,
+      sourceGuard: null,
+      status: 'ready',
+    });
+    await vi.runAllTimersAsync();
+    expect(harness.deps.runGraph).toHaveBeenCalledOnce();
+  });
+
+  it('dispose clears scheduling and preview, unsubscribes exactly once, and makes methods inert', async () => {
+    vi.useFakeTimers();
+    const harness = createHarness();
+    await harness.session.process();
+    harness.session.update({ autoProcess: true });
+    const listener = vi.fn();
+    harness.session.subscribe(listener);
+    vi.mocked(harness.deps.cleanupPreview).mockClear();
+    listener.mockClear();
+
+    harness.session.dispose();
+    const disposedState = harness.session.getSnapshot();
+
+    expect(disposedState).toMatchObject({ preview: null, sourceGuard: null, status: 'ready' });
+    expect(harness.deps.cleanupPreview).toHaveBeenCalledOnce();
+    expect(harness.unsubscribe).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+    listener.mockClear();
+
+    harness.fireControllerSubscriber();
+    harness.session.update({ model: 'segment-anything-huge' });
+    harness.session.reset();
+    harness.session.cancel();
+    harness.session.dispose();
+    const lateListener = vi.fn();
+    harness.session.subscribe(lateListener);
+
+    await expect(harness.session.process()).resolves.toBe('stale');
+    expect(harness.session.getSnapshot()).toBe(disposedState);
+    expect(listener).not.toHaveBeenCalled();
+    expect(lateListener).not.toHaveBeenCalled();
+    expect(harness.unsubscribe).toHaveBeenCalledOnce();
+  });
+
+  it('dispose aborts in-flight processing and suppresses its completion', async () => {
+    const graph = deferred<{ height: number; imageName: string; origin: string; width: number }>();
+    const signals: AbortSignal[] = [];
+    const harness = createHarness({
+      runGraph: vi.fn((options) => {
+        if (options.signal) {
+          signals.push(options.signal);
+        }
+        return graph.promise;
+      }),
+    });
+    const pending = harness.session.process();
+    await vi.waitFor(() => expect(harness.deps.runGraph).toHaveBeenCalledOnce());
+
+    harness.session.dispose();
+
+    expect(signals[0]?.aborted).toBe(true);
+    graph.resolve({ height: 12, imageName: 'late.png', origin: 'late', width: 16 });
+    await expect(pending).resolves.toBe('stale');
+    expect(harness.deps.publishPreview).not.toHaveBeenCalled();
+    expect(harness.unsubscribe).toHaveBeenCalledOnce();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvas-operations/selectObjectSession.ts b/invokeai/frontend/webv2/src/workbench/canvas-operations/selectObjectSession.ts
new file mode 100644
index 00000000000..7fcbb379855
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvas-operations/selectObjectSession.ts
@@ -0,0 +1,573 @@
+import type { ExportBakedLayerBlobResult, LayerExportGuard } from '@workbench/canvas-engine/engine';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { RunUtilityGraphOptions, UtilityGraphResult } from '@workbench/canvas-operations/backend/utilityQueue';
+import type {
+  CanvasOperationController,
+  CanvasOperationRunResult,
+  CanvasOperationSession,
+} from '@workbench/canvas-operations/operationController';
+import type { SamSessionError, SamSessionErrorCode } from '@workbench/canvas-operations/operationTypes';
+import type { SamInput, SamModel } from '@workbench/generation/canvas/samGraph';
+
+import { isSamDocumentInputValid } from '@workbench/generation/canvas/samGraph';
+
+import type { SelectObjectPreparedSource, SelectObjectReadyResult } from './layerImageResult';
+
+import { prepareSelectObjectSource, processSelectObjectSource } from './layerImageResult';
+
+export type SelectObjectSessionStatus =
+  | 'ready'
+  | 'scheduled'
+  | 'preparing-source'
+  | 'uploading'
+  | 'processing-sam'
+  | 'rendering-preview'
+  | 'error';
+
+export interface SelectObjectSessionPreview<T> {
+  data: T;
+  guard: LayerExportGuard;
+  image: SelectObjectReadyResult['image'];
+  inputHash: string;
+  previewId: number;
+  isolated: boolean;
+  rect: Rect;
+  sourceImageName: string;
+}
+
+export interface SelectObjectSessionState<T> {
+  input: SamInput;
+  model: SamModel;
+  invert: boolean;
+  applyPolygonRefinement: boolean;
+  autoProcess: boolean;
+  isolatedPreview: boolean;
+  status: SelectObjectSessionStatus;
+  error: SamSessionError | null;
+  preview: SelectObjectSessionPreview<T> | null;
+  sourceGuard: LayerExportGuard | null;
+}
+
+export interface SelectObjectSessionDeps<T> {
+  captureGuard(): LayerExportGuard | null;
+  controller: CanvasOperationController;
+  exportSource(): Promise<ExportBakedLayerBlobResult>;
+  uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ height: number; imageName: string; width: number }>;
+  runGraph(options: Pick<RunUtilityGraphOptions, 'graph' | 'outputNodeId' | 'signal'>): Promise<UtilityGraphResult>;
+  decodePreview(result: SelectObjectReadyResult, signal: AbortSignal): Promise<T>;
+  publishPreview(preview: SelectObjectSessionPreview<T>): undefined;
+  cleanupPreview(): void;
+  isGuardCurrent(guard: LayerExportGuard): boolean;
+}
+
+export interface CreateSelectObjectSessionOptions<T> {
+  deps: SelectObjectSessionDeps<T>;
+  operation: CanvasOperationSession;
+}
+
+export type SelectObjectSessionProcessResult = CanvasOperationRunResult | 'blocked' | 'deduped' | 'invalid';
+
+export interface SelectObjectSession<T> {
+  getSnapshot(): SelectObjectSessionState<T>;
+  subscribe(listener: () => void): () => void;
+  update(
+    changes: Partial<
+      Pick<
+        SelectObjectSessionState<T>,
+        'applyPolygonRefinement' | 'autoProcess' | 'input' | 'invert' | 'isolatedPreview' | 'model'
+      >
+    >
+  ): void;
+  process(): Promise<SelectObjectSessionProcessResult>;
+  interruptProcessing(): void;
+  reportError(error: SamSessionError | string): void;
+  reset(): void;
+  cancel(): void;
+  dispose(): void;
+}
+
+const defaultState = <T>(): SelectObjectSessionState<T> => ({
+  applyPolygonRefinement: false,
+  autoProcess: false,
+  error: null,
+  input: { prompt: '', type: 'prompt' },
+  invert: false,
+  isolatedPreview: true,
+  model: 'segment-anything-2-large',
+  preview: null,
+  sourceGuard: null,
+  status: 'ready',
+});
+
+const stableInputHash = <T>(state: SelectObjectSessionState<T>): string => {
+  const input =
+    state.input.type === 'prompt'
+      ? ['prompt', state.input.prompt.trim()]
+      : [
+          'visual',
+          state.input.includePoints.map(({ x, y }) => [x, y]),
+          state.input.excludePoints.map(({ x, y }) => [x, y]),
+          state.input.bbox
+            ? [state.input.bbox.x, state.input.bbox.y, state.input.bbox.width, state.input.bbox.height]
+            : null,
+        ];
+  return JSON.stringify([input, state.model, state.invert, state.applyPolygonRefinement]);
+};
+
+const errorDetail = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
+
+const withDetail = (code: SamSessionErrorCode, detail?: string): SamSessionError =>
+  detail ? { code, detail } : { code };
+
+const getPreparedSourceError = (
+  result: Exclude<Awaited<ReturnType<typeof prepareSelectObjectSource>>, { status: 'ready' }>
+): SamSessionError => {
+  if (result.status === 'failed') {
+    return withDetail(result.code, result.message);
+  }
+  if (result.status === 'empty') {
+    return { code: 'empty' };
+  }
+  if (result.status === 'dimension-mismatch') {
+    return withDetail('output-dimension', result.message);
+  }
+  return { code: 'not-ready' };
+};
+
+const getProcessedSourceError = (
+  result: Exclude<Awaited<ReturnType<typeof processSelectObjectSource>>, { status: 'ready' | 'aborted' }>
+): SamSessionError => {
+  if (result.status === 'invalid-input') {
+    return { code: 'invalid' };
+  }
+  if (result.status === 'dimension-mismatch') {
+    return withDetail('output-dimension', result.message);
+  }
+  if (result.status === 'failed') {
+    return withDetail(result.code, result.message);
+  }
+  return { code: 'unknown' };
+};
+
+class SamSessionFailure extends Error {
+  readonly error: SamSessionError;
+
+  constructor(error: SamSessionError) {
+    super(error.detail ?? error.code);
+    this.name = 'SamSessionFailure';
+    this.error = error;
+  }
+}
+
+export const createSelectObjectSession = <T>(options: CreateSelectObjectSessionOptions<T>): SelectObjectSession<T> => {
+  const { deps, operation } = options;
+  let state = defaultState<T>();
+  let source: SelectObjectPreparedSource | null = null;
+  let requestToken = 0;
+  let lastPublishedHash: string | null = null;
+  let pendingHash: string | null = null;
+  let pendingPhase: SelectObjectSessionStatus | null = null;
+  let pendingProcess: Promise<SelectObjectSessionProcessResult> | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+  let unsubscribeController: (() => void) | null = null;
+  const listeners = new Set<() => void>();
+
+  const publishState = (next: SelectObjectSessionState<T>): void => {
+    if (next.status === 'error') {
+      state = next.error === null ? { ...next, status: 'ready' } : next;
+    } else {
+      state = next.error === null ? next : { ...next, error: null };
+    }
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+        // One faulty subscriber must not interrupt session state transitions.
+      }
+    }
+  };
+
+  const clearTimer = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+
+  const publishPhase = (token: number, status: SelectObjectSessionStatus): void => {
+    if (!disposed && token === requestToken) {
+      pendingPhase = status;
+      publishState({ ...state, error: null, status });
+    }
+  };
+
+  const clearSource = (): void => {
+    requestToken += 1;
+    pendingHash = null;
+    pendingPhase = null;
+    pendingProcess = null;
+    source = null;
+    lastPublishedHash = null;
+    publishState({ ...state, preview: null, sourceGuard: null, status: 'ready' });
+  };
+
+  const isGuardCurrent = (guard: LayerExportGuard): boolean => {
+    try {
+      return deps.isGuardCurrent(guard);
+    } catch {
+      return false;
+    }
+  };
+
+  const isSameGuard = (left: LayerExportGuard, right: LayerExportGuard): boolean =>
+    left.projectId === right.projectId &&
+    left.layerId === right.layerId &&
+    left.layer === right.layer &&
+    left.cacheVersion === right.cacheVersion &&
+    left.documentGeneration === right.documentGeneration;
+
+  unsubscribeController = deps.controller.subscribe(() => {
+    if (!disposed && deps.controller.getSnapshot().status === 'idle') {
+      clearSource();
+    }
+  });
+
+  const schedule = (): void => {
+    clearTimer();
+    if (disposed) {
+      return;
+    }
+    if (!state.autoProcess || !isSamDocumentInputValid(state.input)) {
+      if (state.status === 'scheduled') {
+        publishState({ ...state, status: 'ready' });
+      }
+      return;
+    }
+    publishState({ ...state, error: null, status: 'scheduled' });
+    timer = setTimeout(() => {
+      timer = null;
+      void process();
+    }, 1_000);
+  };
+
+  const ensureSource = async (
+    guard: LayerExportGuard,
+    signal: AbortSignal,
+    token: number
+  ): Promise<SelectObjectPreparedSource> => {
+    if (source && isSameGuard(source.guard, guard) && isGuardCurrent(source.guard) && isGuardCurrent(guard)) {
+      source = { ...source, guard };
+      return source;
+    }
+    source = null;
+    const prepared = await prepareSelectObjectSource(deps, signal, (phase) => publishPhase(token, phase));
+    if (prepared.status !== 'ready') {
+      throw new SamSessionFailure(getPreparedSourceError(prepared));
+    }
+    if (signal.aborted || !isGuardCurrent(guard) || !isSameGuard(prepared.source.guard, guard)) {
+      throw new DOMException('Select Object source became stale.', 'AbortError');
+    }
+    source = { ...prepared.source, guard };
+    return source;
+  };
+
+  const runRequest = async (
+    token: number,
+    hash: string,
+    requestState: SelectObjectSessionState<T>,
+    guard: LayerExportGuard
+  ): Promise<SelectObjectSessionProcessResult> => {
+    let requestError: SamSessionError | null = null;
+    try {
+      pendingPhase = 'preparing-source';
+      publishState({ ...state, sourceGuard: guard, status: 'preparing-source' });
+      const result = await operation.run(
+        async (signal) => {
+          try {
+            const preparedSource = await ensureSource(guard, signal, token);
+            if (signal.aborted || token !== requestToken) {
+              throw new DOMException('Select Object source preparation was aborted.', 'AbortError');
+            }
+            const processed = await processSelectObjectSource({
+              applyPolygonRefinement: requestState.applyPolygonRefinement,
+              input: requestState.input,
+              invert: requestState.invert,
+              model: requestState.model,
+              runGraph: deps.runGraph,
+              onPhase: (phase) => publishPhase(token, phase),
+              signal,
+              source: preparedSource,
+            });
+            if (processed.status !== 'ready') {
+              if (processed.status === 'aborted') {
+                throw new DOMException('Select Object processing was aborted.', 'AbortError');
+              }
+              throw new SamSessionFailure(getProcessedSourceError(processed));
+            }
+            if (!isGuardCurrent(guard) || !isSameGuard(processed.guard, guard)) {
+              throw new DOMException('Select Object layer source became stale.', 'AbortError');
+            }
+            publishPhase(token, 'rendering-preview');
+            let data: T;
+            try {
+              data = await deps.decodePreview(processed, signal);
+            } catch (cause) {
+              if (signal.aborted || (cause instanceof Error && cause.name === 'AbortError')) {
+                throw cause;
+              }
+              const code =
+                cause &&
+                typeof cause === 'object' &&
+                'samErrorCode' in cause &&
+                cause.samErrorCode === 'output-dimension'
+                  ? 'output-dimension'
+                  : 'decode';
+              throw new SamSessionFailure(withDetail(code, errorDetail(cause)));
+            }
+            if (signal.aborted || !isGuardCurrent(guard)) {
+              throw new DOMException('Select Object preview decode was aborted.', 'AbortError');
+            }
+            return {
+              data,
+              guard: processed.guard,
+              image: processed.image,
+              inputHash: hash,
+              previewId: token,
+              isolated: requestState.isolatedPreview,
+              rect: processed.rect,
+              sourceImageName: preparedSource.imageName,
+            } satisfies SelectObjectSessionPreview<T>;
+          } catch (cause) {
+            if (cause instanceof SamSessionFailure) {
+              requestError = cause.error;
+            }
+            throw cause;
+          }
+        },
+        (preview) => {
+          if (!isGuardCurrent(preview.guard)) {
+            throw new DOMException('Select Object preview became stale.', 'AbortError');
+          }
+          const publishedPreview =
+            preview.isolated === state.isolatedPreview ? preview : { ...preview, isolated: state.isolatedPreview };
+          deps.publishPreview(publishedPreview);
+          lastPublishedHash = hash;
+          publishState({
+            ...state,
+            error: null,
+            preview: publishedPreview,
+            sourceGuard: preview.guard,
+            status: 'ready',
+          });
+          return undefined;
+        }
+      );
+      if (token !== requestToken) {
+        return 'stale';
+      }
+      if (result === 'error' && requestError === null && !isGuardCurrent(guard)) {
+        clearSource();
+        return 'stale';
+      }
+      if (result === 'error') {
+        publishState({
+          ...state,
+          error: requestError ?? withDetail('unknown', 'Select Object processing failed.'),
+          status: 'error',
+        });
+      } else if (result === 'stale' && !isGuardCurrent(guard)) {
+        clearSource();
+      }
+      return result;
+    } catch (cause) {
+      if (token !== requestToken || (cause instanceof Error && cause.name === 'AbortError')) {
+        return 'stale';
+      }
+      publishState({
+        ...state,
+        error: cause instanceof SamSessionFailure ? cause.error : withDetail('unknown', errorDetail(cause)),
+        status: 'error',
+      });
+      return 'error';
+    }
+  };
+
+  const process = (): Promise<SelectObjectSessionProcessResult> => {
+    clearTimer();
+    if (disposed) {
+      return Promise.resolve('stale');
+    }
+    if (!isSamDocumentInputValid(state.input)) {
+      publishState({ ...state, error: { code: 'invalid' }, status: 'error' });
+      return Promise.resolve('invalid');
+    }
+    if (state.sourceGuard && !isGuardCurrent(state.sourceGuard)) {
+      requestToken += 1;
+      operation.interruptProcessing();
+      source = null;
+      pendingHash = null;
+      pendingProcess = null;
+      lastPublishedHash = null;
+      publishState({ ...state, preview: null, sourceGuard: null, status: 'ready' });
+    }
+    const hash = stableInputHash(state);
+    if (hash === pendingHash && pendingProcess) {
+      publishState({ ...state, error: null, status: pendingPhase ?? 'preparing-source' });
+      return pendingProcess;
+    }
+    if (
+      hash === lastPublishedHash &&
+      state.preview !== null &&
+      state.sourceGuard === state.preview.guard &&
+      source?.guard === state.preview.guard &&
+      isGuardCurrent(state.preview.guard)
+    ) {
+      publishState({ ...state, error: null, status: 'ready' });
+      return Promise.resolve('deduped');
+    }
+
+    requestToken += 1;
+    const token = requestToken;
+    const guard = deps.captureGuard();
+    if (!guard || !isGuardCurrent(guard)) {
+      publishState({ ...state, error: { code: 'not-ready' }, status: 'error' });
+      return Promise.resolve('error');
+    }
+    pendingHash = hash;
+    const requestState = state;
+    const promise = runRequest(token, hash, requestState, guard).finally(() => {
+      if (token === requestToken) {
+        pendingHash = null;
+        pendingPhase = null;
+        pendingProcess = null;
+      }
+    });
+    pendingProcess = promise;
+    return promise;
+  };
+
+  const cancelCurrent = (): void => {
+    clearTimer();
+    requestToken += 1;
+    pendingHash = null;
+    pendingPhase = null;
+    pendingProcess = null;
+    operation.cancel();
+    source = null;
+    lastPublishedHash = null;
+  };
+
+  const invalidateProcessingState = (): void => {
+    requestToken += 1;
+    pendingHash = null;
+    pendingPhase = null;
+    pendingProcess = null;
+    lastPublishedHash = null;
+    operation.reset();
+  };
+
+  return {
+    cancel: () => {
+      if (disposed) {
+        return;
+      }
+      cancelCurrent();
+      publishState({ ...state, error: null, preview: null, sourceGuard: null, status: 'ready' });
+    },
+    dispose: () => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      clearTimer();
+      requestToken += 1;
+      pendingHash = null;
+      pendingPhase = null;
+      pendingProcess = null;
+      lastPublishedHash = null;
+      unsubscribeController?.();
+      unsubscribeController = null;
+      operation.cancel();
+      source = null;
+      publishState({ ...state, error: null, preview: null, sourceGuard: null, status: 'ready' });
+      listeners.clear();
+    },
+    getSnapshot: () => state,
+    interruptProcessing: () => {
+      clearTimer();
+      if (disposed || state.status === 'ready' || state.status === 'error') {
+        return;
+      }
+      requestToken += 1;
+      pendingHash = null;
+      pendingPhase = null;
+      pendingProcess = null;
+      lastPublishedHash = null;
+      operation.interruptProcessing();
+      publishState({ ...state, error: null, preview: null, status: 'ready' });
+    },
+    process,
+    reportError: (error) => {
+      if (!disposed) {
+        publishState({
+          ...state,
+          error: typeof error === 'string' ? withDetail('unknown', error) : error,
+          status: 'error',
+        });
+      }
+    },
+    reset: () => {
+      if (disposed) {
+        return;
+      }
+      clearTimer();
+      requestToken += 1;
+      pendingHash = null;
+      pendingPhase = null;
+      pendingProcess = null;
+      operation.reset();
+      source = null;
+      lastPublishedHash = null;
+      publishState(defaultState<T>());
+    },
+    subscribe: (listener) => {
+      if (disposed) {
+        return () => undefined;
+      }
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    update: (changes) => {
+      if (disposed) {
+        return;
+      }
+      const processingChanged =
+        ('input' in changes && changes.input !== state.input) ||
+        ('model' in changes && changes.model !== state.model) ||
+        ('invert' in changes && changes.invert !== state.invert) ||
+        ('applyPolygonRefinement' in changes && changes.applyPolygonRefinement !== state.applyPolygonRefinement);
+      const isolationChanged = 'isolatedPreview' in changes && changes.isolatedPreview !== state.isolatedPreview;
+      if (processingChanged) {
+        invalidateProcessingState();
+      }
+      const preview =
+        isolationChanged && state.preview
+          ? { ...state.preview, isolated: changes.isolatedPreview ?? state.isolatedPreview }
+          : state.preview;
+      if (preview && preview !== state.preview) {
+        deps.publishPreview(preview);
+      }
+      publishState({
+        ...state,
+        ...changes,
+        error: null,
+        preview: processingChanged ? null : preview,
+        status: processingChanged ? 'ready' : state.status,
+      });
+      if (processingChanged || 'autoProcess' in changes) {
+        schedule();
+      }
+    },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvasDimsSync.test.ts b/invokeai/frontend/webv2/src/workbench/canvasDimsSync.test.ts
new file mode 100644
index 00000000000..6f1fbb871af
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasDimsSync.test.ts
@@ -0,0 +1,379 @@
+import { describe, expect, it } from 'vitest';
+
+import type { CanvasProjectMutation } from './canvasProjectMutations';
+import type { MainModelConfig } from './generation/types';
+import type { WorkbenchState } from './types';
+import type { WorkbenchAction } from './workbenchState';
+
+import { type CanvasDimsSnapshot, createCanvasDimsSync, reconcileCanvasDims } from './canvasDimsSync';
+import { getProjectWidgetValues } from './widgetState';
+import { createWorkbenchStore } from './workbenchStore';
+
+const bbox = (width: number, height: number, x = 0, y = 0) => ({ height, width, x, y });
+
+const dispatchCanvas = (store: ReturnType<typeof createWorkbenchStore>, mutation: CanvasProjectMutation): void => {
+  store.dispatch({ mutation, projectId: store.getState().activeProjectId, type: 'applyCanvasProjectMutation' });
+};
+
+const snapshot = (bboxW: number, bboxH: number, dimsW: number, dimsH: number): CanvasDimsSnapshot => ({
+  bboxHeight: bboxH,
+  bboxWidth: bboxW,
+  dimsHeight: dimsH,
+  dimsWidth: dimsW,
+});
+
+describe('reconcileCanvasDims (pure)', () => {
+  it('no-ops when there is no canvas frame (not in canvas mode)', () => {
+    expect(reconcileCanvasDims({ bbox: null, dims: { height: 512, width: 512 }, grid: 8, prev: null })).toEqual({
+      kind: 'none',
+    });
+  });
+
+  it('no-ops when the bbox and dims already agree', () => {
+    expect(
+      reconcileCanvasDims({
+        bbox: bbox(1024, 1024),
+        dims: { height: 1024, width: 1024 },
+        grid: 8,
+        prev: snapshot(1024, 1024, 1024, 1024),
+      })
+    ).toEqual({ kind: 'none' });
+  });
+
+  it('maps a bbox size change onto the generate dims and re-derives the aspect id', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(512, 768),
+      dims: { height: 1024, width: 1024 },
+      grid: 8,
+      prev: snapshot(1024, 1024, 1024, 1024),
+    });
+
+    expect(result).toEqual({
+      aspectRatioId: '2:3',
+      aspectRatioValue: 512 / 768,
+      height: 768,
+      kind: 'patch-dims',
+      width: 512,
+    });
+  });
+
+  it('emits the bbox ratio as aspectRatioValue for a non-square bbox (not just the preset id)', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(1024, 768),
+      dims: { height: 1024, width: 1024 },
+      grid: 8,
+      prev: snapshot(1024, 1024, 1024, 1024),
+    });
+
+    // 4:3 as an id, but the numeric ratio must agree so downstream constraint
+    // math (GenerateDimensionFields' getActiveRatio) uses the fresh ratio
+    // instead of a stale 1.0 left over from the previous (square) dims.
+    expect(result).toMatchObject({ aspectRatioId: '4:3', aspectRatioValue: 1024 / 768, kind: 'patch-dims' });
+  });
+
+  it('re-derives a preset aspect id for a matching bbox ratio', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(1024, 768),
+      dims: { height: 1024, width: 1024 },
+      grid: 8,
+      prev: snapshot(1024, 1024, 1024, 1024),
+    });
+
+    expect(result).toMatchObject({ aspectRatioId: '4:3', kind: 'patch-dims' });
+  });
+
+  it('re-derives Free for a non-preset bbox ratio', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(1000, 512),
+      dims: { height: 1024, width: 1024 },
+      grid: 8,
+      prev: snapshot(1024, 1024, 1024, 1024),
+    });
+
+    expect(result).toMatchObject({ aspectRatioId: 'Free', kind: 'patch-dims' });
+  });
+
+  it('ignores a position-only bbox move (same width/height)', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(1024, 1024, 128, 64),
+      dims: { height: 1024, width: 1024 },
+      grid: 8,
+      prev: snapshot(1024, 1024, 1024, 1024),
+    });
+
+    expect(result).toEqual({ kind: 'none' });
+  });
+
+  it('resizes the bbox to changed dims, keeping the top-left position', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(512, 768, 40, 24),
+      dims: { height: 768, width: 768 },
+      grid: 8,
+      prev: snapshot(512, 768, 512, 768),
+    });
+
+    expect(result).toEqual({ bbox: { height: 768, width: 768, x: 40, y: 24 }, kind: 'set-bbox' });
+  });
+
+  it('snaps dims to the grid when resizing the bbox', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(512, 512),
+      dims: { height: 100, width: 100 },
+      grid: 16,
+      prev: snapshot(512, 512, 512, 512),
+    });
+
+    expect(result).toEqual({ bbox: { height: 96, width: 96, x: 0, y: 0 }, kind: 'set-bbox' });
+  });
+
+  it('clamps a sub-grid dimension up to the grid minimum', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(512, 512),
+      dims: { height: 1, width: 1 },
+      grid: 16,
+      prev: snapshot(512, 512, 512, 512),
+    });
+
+    expect(result).toEqual({ bbox: { height: 16, width: 16, x: 0, y: 0 }, kind: 'set-bbox' });
+  });
+
+  it('no-ops the dims->bbox direction when the snapped size already matches the bbox', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(96, 96),
+      dims: { height: 100, width: 100 },
+      grid: 16,
+      prev: snapshot(96, 96, 96, 96),
+    });
+
+    expect(result).toEqual({ kind: 'none' });
+  });
+
+  it('lets the bbox win on first run (no prior snapshot)', () => {
+    const result = reconcileCanvasDims({
+      bbox: bbox(512, 512),
+      dims: { height: 256, width: 256 },
+      grid: 8,
+      prev: null,
+    });
+
+    expect(result).toEqual({ aspectRatioId: '1:1', aspectRatioValue: 1, height: 512, kind: 'patch-dims', width: 512 });
+  });
+
+  it('converges: applying each direction twice is a fixed point', () => {
+    // bbox -> dims, then re-reconcile the resulting agreed state.
+    const first = reconcileCanvasDims({
+      bbox: bbox(640, 512),
+      dims: { height: 1024, width: 1024 },
+      grid: 8,
+      prev: snapshot(1024, 1024, 1024, 1024),
+    });
+    expect(first.kind).toBe('patch-dims');
+    const afterPatch = reconcileCanvasDims({
+      bbox: bbox(640, 512),
+      dims: { height: 512, width: 640 },
+      grid: 8,
+      prev: snapshot(640, 512, 640, 512),
+    });
+    expect(afterPatch).toEqual({ kind: 'none' });
+
+    // dims -> bbox, then re-reconcile the resulting agreed state.
+    const second = reconcileCanvasDims({
+      bbox: bbox(512, 512, 10, 20),
+      dims: { height: 512, width: 768 },
+      grid: 8,
+      prev: snapshot(512, 512, 512, 512),
+    });
+    expect(second.kind).toBe('set-bbox');
+    const afterResize = reconcileCanvasDims({
+      bbox: bbox(768, 512, 10, 20),
+      dims: { height: 512, width: 768 },
+      grid: 8,
+      prev: snapshot(768, 512, 768, 512),
+    });
+    expect(afterResize).toEqual({ kind: 'none' });
+  });
+});
+
+const model: MainModelConfig = { base: 'sdxl', key: 'test-model', name: 'Test Model', type: 'main' };
+
+const getActiveGenerate = (state: WorkbenchState) => {
+  const project = state.projects.find((candidate) => candidate.id === state.activeProjectId);
+  if (!project) {
+    throw new Error('no active project');
+  }
+  return { bbox: project.canvas.document.bbox, values: getProjectWidgetValues(project, 'generate') };
+};
+
+/** A store that counts only the dispatches the sync itself issues. */
+const setupCanvasStore = () => {
+  const store = createWorkbenchStore();
+
+  // Put the active project into canvas mode with concrete generate dims/model.
+  store.dispatch({ type: 'setInvocationSource', sourceId: 'canvas' });
+  store.dispatch({
+    type: 'patchGenerateSettings',
+    values: { height: 1024, model, modelKey: model.key, width: 1024 },
+  });
+
+  let syncDispatches = 0;
+  const countingStore = {
+    dispatch: (action: WorkbenchAction) => {
+      syncDispatches += 1;
+      store.dispatch(action);
+    },
+    getState: store.getState,
+    subscribe: store.subscribe,
+  };
+
+  const sync = createCanvasDimsSync(countingStore);
+
+  return { getSyncDispatches: () => syncDispatches, store, sync };
+};
+
+describe('createCanvasDimsSync (wiring)', () => {
+  it('does not dispatch on mount when bbox and dims already agree', () => {
+    const { getSyncDispatches, sync } = setupCanvasStore();
+
+    expect(getSyncDispatches()).toBe(0);
+    sync.dispose();
+  });
+
+  it('patches the generate dims when the bbox changes, without looping', () => {
+    const { getSyncDispatches, store, sync } = setupCanvasStore();
+
+    dispatchCanvas(store, { bbox: { height: 768, width: 512, x: 0, y: 0 }, type: 'setCanvasBbox' });
+
+    const { values } = getActiveGenerate(store.getState());
+    expect(values.width).toBe(512);
+    expect(values.height).toBe(768);
+    expect(values.aspectRatioId).toBe('2:3');
+    // The numeric ratio must be re-derived alongside the id, or downstream
+    // constraint math (GenerateDimensionFields' getActiveRatio, which prefers
+    // aspectRatioValue whenever it is > 0) keeps constraining edits to the
+    // stale ratio from before the bbox drag.
+    expect(values.aspectRatioValue).toBeCloseTo(512 / 768);
+    // Exactly one sync dispatch (the echo is a no-op, so no unbounded loop).
+    expect(getSyncDispatches()).toBe(1);
+    sync.dispose();
+  });
+
+  it('a bbox-driven ratio is what a subsequent constrained width edit uses (not the pre-drag ratio)', () => {
+    const { store, sync } = setupCanvasStore();
+
+    // Drag the bbox to a non-square 4:3 frame; dims should follow.
+    dispatchCanvas(store, { bbox: { height: 768, width: 1024, x: 0, y: 0 }, type: 'setCanvasBbox' });
+    const { values } = getActiveGenerate(store.getState());
+    expect(values.aspectRatioId).toBe('4:3');
+    expect(values.aspectRatioValue).toBeCloseTo(1024 / 768);
+
+    const aspectRatioValue = values.aspectRatioValue as number;
+    const width = values.width as number;
+    const height = values.height as number;
+
+    // Mirror GenerateDimensionFields' getActiveRatio: prefer aspectRatioValue
+    // when positive, else fall back to the live width/height.
+    const activeRatio = aspectRatioValue > 0 ? aspectRatioValue : width / height;
+    const nextWidth = 800;
+    const constrainedHeight = nextWidth / activeRatio;
+
+    // Before the fix this would divide by the stale ratio (1.0, from the
+    // original 1024x1024 dims) and yield the wrong height (800 instead of 600).
+    expect(constrainedHeight).toBeCloseTo(600);
+    sync.dispose();
+  });
+
+  it('resizes the bbox when the generate dims change, without looping', () => {
+    const { getSyncDispatches, store, sync } = setupCanvasStore();
+
+    // Move the frame first so the resize must preserve the top-left position.
+    dispatchCanvas(store, { bbox: { height: 1024, width: 1024, x: 32, y: 48 }, type: 'setCanvasBbox' });
+    const before = getSyncDispatches();
+
+    store.dispatch({ type: 'patchGenerateSettings', values: { width: 512 } });
+
+    const { bbox: nextBbox } = getActiveGenerate(store.getState());
+    expect(nextBbox).toEqual({ height: 1024, width: 512, x: 32, y: 48 });
+    expect(getSyncDispatches() - before).toBe(1);
+    sync.dispose();
+  });
+
+  it('driving the dims off-grid still keeps the dispatch count bounded (no snap/reconcile loop)', () => {
+    const { getSyncDispatches, store, sync } = setupCanvasStore();
+
+    // Move the frame first so the resize must preserve the top-left position.
+    dispatchCanvas(store, { bbox: { height: 1024, width: 1024, x: 32, y: 48 }, type: 'setCanvasBbox' });
+    const before = getSyncDispatches();
+
+    // 501 is not a multiple of the sdxl grid (8): dims -> bbox must snap it,
+    // and the bbox -> dims echo from that snapped bbox must not re-trigger
+    // another round of reconciliation (the snapped bbox and the still-501-wide
+    // dims disagree by construction, but the sync's re-entrancy guard must
+    // still hold the total dispatch count for this one external change to 1).
+    store.dispatch({ type: 'patchGenerateSettings', values: { width: 501 } });
+
+    const { bbox: nextBbox } = getActiveGenerate(store.getState());
+    expect(nextBbox.width).toBe(504); // snapped up to the nearest multiple of 8
+    expect(getSyncDispatches() - before).toBe(1);
+    sync.dispose();
+  });
+
+  it('ignores a position-only bbox move', () => {
+    const { getSyncDispatches, store, sync } = setupCanvasStore();
+
+    dispatchCanvas(store, { bbox: { height: 1024, width: 1024, x: 100, y: 200 }, type: 'setCanvasBbox' });
+
+    const { values } = getActiveGenerate(store.getState());
+    expect(values.width).toBe(1024);
+    expect(values.height).toBe(1024);
+    expect(getSyncDispatches()).toBe(0);
+    sync.dispose();
+  });
+
+  it('stays inert when the project is not invoking into the canvas', () => {
+    const store = createWorkbenchStore();
+    store.dispatch({ type: 'setInvocationSource', sourceId: 'generate' });
+    store.dispatch({
+      type: 'patchGenerateSettings',
+      values: { height: 1024, model, modelKey: model.key, width: 1024 },
+    });
+
+    let syncDispatches = 0;
+    const countingStore = {
+      dispatch: (action: WorkbenchAction) => {
+        syncDispatches += 1;
+        store.dispatch(action);
+      },
+      getState: store.getState,
+      subscribe: store.subscribe,
+    };
+    const sync = createCanvasDimsSync(countingStore);
+
+    dispatchCanvas(store, { bbox: { height: 512, width: 512, x: 0, y: 0 }, type: 'setCanvasBbox' });
+
+    const { values } = getActiveGenerate(store.getState());
+    // Generate dims untouched: non-canvas behavior is exactly as today.
+    expect(values.width).toBe(1024);
+    expect(values.height).toBe(1024);
+    expect(syncDispatches).toBe(0);
+    sync.dispose();
+  });
+
+  it('aligns dims to the bbox when a project enters canvas mode', () => {
+    const store = createWorkbenchStore();
+    // Diverge the frame from the dims while still in generate mode.
+    store.dispatch({
+      type: 'patchGenerateSettings',
+      values: { height: 1024, model, modelKey: model.key, width: 1024 },
+    });
+    dispatchCanvas(store, { bbox: { height: 640, width: 896, x: 0, y: 0 }, type: 'setCanvasBbox' });
+
+    const sync = createCanvasDimsSync(store);
+    // Switching into canvas mode should let the bbox win and drive the dims.
+    store.dispatch({ type: 'setInvocationSource', sourceId: 'canvas' });
+
+    const { values } = getActiveGenerate(store.getState());
+    expect(values.width).toBe(896);
+    expect(values.height).toBe(640);
+    sync.dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvasDimsSync.ts b/invokeai/frontend/webv2/src/workbench/canvasDimsSync.ts
new file mode 100644
index 00000000000..3841e93dedc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasDimsSync.ts
@@ -0,0 +1,261 @@
+/**
+ * Two-way sync between a project's canvas generation frame (`canvas.document.bbox`)
+ * and its generate-widget dimensions (`width` / `height` / `aspectRatioId`).
+ *
+ * Legacy parity: while a project is invoking into the canvas, the generation
+ * frame IS the generation size. Resizing the bbox (tool gesture, BboxOptions,
+ * undo/redo) drives the generate width/height; editing the generate dimensions
+ * (or picking an aspect preset) resizes the bbox in place (top-left anchored).
+ * Position-only bbox moves never touch the dimensions.
+ *
+ * The module is two parts:
+ * - {@link reconcileCanvasDims}: a pure, unit-tested reconcile that decides which
+ *   side (if any) to write, given the current bbox, the current committed
+ *   generate dims, the snapping grid, and the last-synced snapshot.
+ * - {@link createCanvasDimsSync}: a thin `store.subscribe` wiring that feeds the
+ *   reconcile from workbench state and dispatches the resulting action.
+ *
+ * Loop safety: the reconcile short-circuits to `none` whenever the bbox and dims
+ * already agree, so applying either direction is a fixed point. The wiring also
+ * updates its last-synced snapshot *before* dispatching and hard-guards against
+ * re-entrant notifications, keeping the dispatch count per external change
+ * bounded (at most one echo, which is itself a no-op).
+ *
+ * Only active while `project.invocation.sourceId === 'canvas'`; for every other
+ * source the sync is inert and generate-dimension editing behaves exactly as it
+ * does today. Zero React.
+ */
+
+import type { AspectRatioId } from './generation/types';
+import type { CanvasDocumentContractV2, WorkbenchState } from './types';
+import type { WorkbenchAction } from './workbenchState';
+
+import { deriveAspectRatioId } from './generation/settings';
+import { gridSizeForModelBase } from './widgets/canvas/bboxGrid';
+import { getProjectWidgetValues } from './widgetState';
+
+type Bbox = CanvasDocumentContractV2['bbox'];
+
+/** The last-synced width/height on both sides, used to detect which side changed. */
+export interface CanvasDimsSnapshot {
+  bboxWidth: number;
+  bboxHeight: number;
+  dimsWidth: number;
+  dimsHeight: number;
+}
+
+export interface CanvasDimsReconcileInput {
+  /** The current generation frame, or `null` when the sync should stay inert (no canvas mode). */
+  bbox: Bbox | null;
+  /** The current committed generate width/height. */
+  dims: { width: number; height: number };
+  /** The bbox/generate snapping grid (model-derived; identical on both sides). */
+  grid: number;
+  /** The last snapshot this sync wrote/observed, or `null` on first run / after a reset. */
+  prev: CanvasDimsSnapshot | null;
+}
+
+export type CanvasDimsReconcileResult =
+  | { kind: 'none' }
+  /**
+   * Write the bbox size onto the generate dims (bbox wins), re-deriving the
+   * aspect id *and* the numeric aspect ratio. Both are re-derived from the bbox
+   * unconditionally (even when the form's ratio is locked to a preset) so the
+   * id, the numeric ratio, and the dims stay mutually consistent after the
+   * patch — a locked preset does not veto the bbox, which remains authoritative.
+   */
+  | { kind: 'patch-dims'; width: number; height: number; aspectRatioId: AspectRatioId; aspectRatioValue: number }
+  /** Resize the bbox to the (grid-snapped) generate dims, keeping its top-left position. */
+  | { kind: 'set-bbox'; bbox: Bbox };
+
+const snapToGrid = (value: number, grid: number): number => {
+  const step = grid > 0 ? grid : 1;
+  return Math.max(step, Math.round(value / step) * step);
+};
+
+/**
+ * Decide which direction of the bbox <-> dims sync to apply.
+ *
+ * - No bbox (not in canvas mode) -> `none`.
+ * - Bbox and dims already agree -> `none` (the primary loop guard).
+ * - Otherwise the side that changed since `prev` wins; the bbox is authoritative
+ *   when both (or neither, on first run) changed, matching "the frame is the
+ *   generation size". Bbox -> dims writes the exact bbox size and re-derives the
+ *   aspect id. Dims -> bbox snaps to the grid and only emits when the snapped
+ *   size actually differs from the live bbox.
+ */
+export const reconcileCanvasDims = ({
+  bbox,
+  dims,
+  grid,
+  prev,
+}: CanvasDimsReconcileInput): CanvasDimsReconcileResult => {
+  if (!bbox) {
+    return { kind: 'none' };
+  }
+
+  if (bbox.width === dims.width && bbox.height === dims.height) {
+    return { kind: 'none' };
+  }
+
+  const bboxChanged = !prev || prev.bboxWidth !== bbox.width || prev.bboxHeight !== bbox.height;
+
+  if (bboxChanged) {
+    return {
+      aspectRatioId: deriveAspectRatioId(bbox.width, bbox.height),
+      aspectRatioValue: bbox.height > 0 ? bbox.width / bbox.height : 1,
+      height: bbox.height,
+      kind: 'patch-dims',
+      width: bbox.width,
+    };
+  }
+
+  const dimsChanged = !prev || prev.dimsWidth !== dims.width || prev.dimsHeight !== dims.height;
+
+  if (dimsChanged) {
+    const width = snapToGrid(dims.width, grid);
+    const height = snapToGrid(dims.height, grid);
+
+    if (width === bbox.width && height === bbox.height) {
+      return { kind: 'none' };
+    }
+
+    return { bbox: { height, width, x: bbox.x, y: bbox.y }, kind: 'set-bbox' };
+  }
+
+  return { kind: 'none' };
+};
+
+/** The minimal workbench store surface the sync depends on. */
+export interface CanvasDimsSyncStore {
+  getState(): WorkbenchState;
+  subscribe(listener: () => void): () => void;
+  dispatch(action: WorkbenchAction): void;
+}
+
+export interface CanvasDimsSync {
+  dispose(): void;
+}
+
+const readFiniteDimension = (values: Record<string, unknown>, key: 'width' | 'height'): number | null => {
+  const raw = values[key];
+  return typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? raw : null;
+};
+
+const readModelBase = (values: Record<string, unknown>): string | null => {
+  const model = values.model;
+  return model && typeof model === 'object' && typeof (model as { base?: unknown }).base === 'string'
+    ? (model as { base: string }).base
+    : null;
+};
+
+/**
+ * Wire the bbox <-> generate-dims reconcile onto a workbench store. Subscribes
+ * immediately; dispatches `patchGenerateSettings` / `setCanvasBbox` as the
+ * reconcile directs. Returns a handle whose `dispose` removes the subscription.
+ */
+export const createCanvasDimsSync = (store: CanvasDimsSyncStore): CanvasDimsSync => {
+  let prev: CanvasDimsSnapshot | null = null;
+  let lastProjectId: string | null = null;
+  let isSyncing = false;
+
+  const handleChange = (): void => {
+    // A dispatch below re-enters this listener synchronously; the snapshot is
+    // already updated to the post-dispatch expectation, so the nested pass would
+    // be a no-op — skip it to keep the dispatch count strictly bounded.
+    if (isSyncing) {
+      return;
+    }
+
+    const state = store.getState();
+    const project = state.projects.find((candidate) => candidate.id === state.activeProjectId);
+
+    if (!project) {
+      prev = null;
+      lastProjectId = null;
+      return;
+    }
+
+    if (project.id !== lastProjectId) {
+      lastProjectId = project.id;
+      prev = null;
+    }
+
+    // Inert unless the project is invoking into the canvas: for every other
+    // source the generate dimensions behave exactly as they do today.
+    if (project.invocation.sourceId !== 'canvas') {
+      prev = null;
+      return;
+    }
+
+    const generateValues = getProjectWidgetValues(project, 'generate');
+    const width = readFiniteDimension(generateValues, 'width');
+    const height = readFiniteDimension(generateValues, 'height');
+
+    if (width === null || height === null) {
+      prev = null;
+      return;
+    }
+
+    const bbox = project.canvas.document.bbox;
+    const grid = gridSizeForModelBase(readModelBase(generateValues));
+    const result = reconcileCanvasDims({ bbox, dims: { height, width }, grid, prev });
+
+    switch (result.kind) {
+      case 'none': {
+        prev = { bboxHeight: bbox.height, bboxWidth: bbox.width, dimsHeight: height, dimsWidth: width };
+        return;
+      }
+      case 'patch-dims': {
+        prev = {
+          bboxHeight: bbox.height,
+          bboxWidth: bbox.width,
+          dimsHeight: result.height,
+          dimsWidth: result.width,
+        };
+        isSyncing = true;
+        try {
+          store.dispatch({
+            projectId: project.id,
+            type: 'patchGenerateSettings',
+            values: {
+              aspectRatioId: result.aspectRatioId,
+              aspectRatioValue: result.aspectRatioValue,
+              height: result.height,
+              width: result.width,
+            },
+          });
+        } finally {
+          isSyncing = false;
+        }
+        return;
+      }
+      case 'set-bbox': {
+        prev = {
+          bboxHeight: result.bbox.height,
+          bboxWidth: result.bbox.width,
+          dimsHeight: height,
+          dimsWidth: width,
+        };
+        isSyncing = true;
+        try {
+          store.dispatch({
+            mutation: { bbox: result.bbox, type: 'setCanvasBbox' },
+            projectId: project.id,
+            type: 'applyCanvasProjectMutation',
+          });
+        } finally {
+          isSyncing = false;
+        }
+        return;
+      }
+    }
+  };
+
+  const unsubscribe = store.subscribe(handleChange);
+
+  // Seed from the current state so an already-canvas project reconciles on mount.
+  handleChange();
+
+  return { dispose: unsubscribe };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvasLayerOps.test.ts b/invokeai/frontend/webv2/src/workbench/canvasLayerOps.test.ts
new file mode 100644
index 00000000000..3f3f69da9ec
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasLayerOps.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import type { CanvasLayerContract } from './types';
+
+import {
+  deleteLayerActions,
+  duplicateLayerActions,
+  reorderIdsForHotkey,
+  reorderLayerActions,
+  reorderTargetIndex,
+} from './canvasLayerOps';
+
+const layer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+describe('duplicateLayerActions', () => {
+  it('duplicates forward and removes the duplicate on undo', () => {
+    expect(duplicateLayerActions('a', 'a-copy')).toEqual({
+      forward: { newId: 'a-copy', sourceId: 'a', type: 'duplicateCanvasLayer' },
+      inverse: { ids: ['a-copy'], type: 'removeCanvasLayers' },
+    });
+  });
+});
+
+describe('deleteLayerActions', () => {
+  it('removes forward and re-adds at the original index on undo', () => {
+    const l = layer('a');
+    expect(deleteLayerActions(l, 2)).toEqual({
+      forward: { ids: ['a'], type: 'removeCanvasLayers' },
+      inverse: { index: 2, layer: l, type: 'addCanvasLayer' },
+    });
+  });
+});
+
+describe('reorderLayerActions', () => {
+  it('reorders forward and restores the prior order on undo (copies arrays)', () => {
+    const current = ['a', 'b', 'c'];
+    const next = ['b', 'a', 'c'];
+    const actions = reorderLayerActions(current, next);
+    expect(actions).toEqual({
+      forward: { orderedIds: ['b', 'a', 'c'], type: 'reorderCanvasLayers' },
+      inverse: { orderedIds: ['a', 'b', 'c'], type: 'reorderCanvasLayers' },
+    });
+    // Snapshotted, not aliased.
+    if (actions.forward.type === 'reorderCanvasLayers') {
+      expect(actions.forward.orderedIds).not.toBe(next);
+    }
+  });
+});
+
+describe('reorderTargetIndex (index 0 = top-most)', () => {
+  it('moves toward/away and clamps at boundaries', () => {
+    expect(reorderTargetIndex(2, 5, 'forward')).toBe(1);
+    expect(reorderTargetIndex(0, 5, 'forward')).toBe(0);
+    expect(reorderTargetIndex(2, 5, 'backward')).toBe(3);
+    expect(reorderTargetIndex(4, 5, 'backward')).toBe(4);
+    expect(reorderTargetIndex(3, 5, 'front')).toBe(0);
+    expect(reorderTargetIndex(1, 5, 'back')).toBe(4);
+  });
+});
+
+describe('reorderIdsForHotkey', () => {
+  it('moves one step toward the front', () => {
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 2, 'forward')).toEqual(['a', 'c', 'b']);
+  });
+
+  it('moves one step toward the back', () => {
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 0, 'backward')).toEqual(['b', 'a', 'c']);
+  });
+
+  it('moves to front and to back', () => {
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 2, 'front')).toEqual(['c', 'a', 'b']);
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 0, 'back')).toEqual(['b', 'c', 'a']);
+  });
+
+  it('returns null when nothing would move (already at the boundary)', () => {
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 0, 'forward')).toBeNull();
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 2, 'backward')).toBeNull();
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 0, 'front')).toBeNull();
+    expect(reorderIdsForHotkey(['a', 'b', 'c'], 2, 'back')).toBeNull();
+  });
+
+  it('returns null for an out-of-range index', () => {
+    expect(reorderIdsForHotkey(['a', 'b'], 5, 'forward')).toBeNull();
+    expect(reorderIdsForHotkey(['a', 'b'], -1, 'forward')).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvasLayerOps.ts b/invokeai/frontend/webv2/src/workbench/canvasLayerOps.ts
new file mode 100644
index 00000000000..8306ec8bc0a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasLayerOps.ts
@@ -0,0 +1,88 @@
+/**
+ * Pure builders for the structural document edits shared by the layers panel and
+ * the canvas widget's layer hotkeys: each returns the forward + inverse reducer
+ * action pair for `engine.layers.commitStructural` / `applyStructural`, so the
+ * inverse-construction logic lives in exactly one place.
+ *
+ * Index convention matches the contract and the layers panel: index 0 is the
+ * top-most layer, so "up"/"forward" moves toward index 0.
+ *
+ * Zero React, zero import-time side effects.
+ */
+
+import type { CanvasProjectMutation } from './canvasProjectMutations';
+import type { CanvasLayerContract } from './types';
+
+/** A forward/inverse reducer-action pair for one reversible structural edit. */
+export interface StructuralActions {
+  forward: CanvasProjectMutation;
+  inverse: CanvasProjectMutation;
+}
+
+/** Mints a fresh layer id (matches the engine's / layers panel's id shape). */
+export const createLayerId = (): string => `layer-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+/** Duplicate a layer (forward), removing the duplicate on undo (inverse). */
+export const duplicateLayerActions = (sourceId: string, newId: string): StructuralActions => ({
+  forward: { newId, sourceId, type: 'duplicateCanvasLayer' },
+  inverse: { ids: [newId], type: 'removeCanvasLayers' },
+});
+
+/** Delete a layer (forward), re-adding it at its original index on undo (inverse). */
+export const deleteLayerActions = (layer: CanvasLayerContract, index: number): StructuralActions => ({
+  forward: { ids: [layer.id], type: 'removeCanvasLayers' },
+  inverse: { index, layer, type: 'addCanvasLayer' },
+});
+
+/** Reorder to `nextIds` (forward), restoring `currentIds` on undo (inverse). */
+export const reorderLayerActions = (currentIds: readonly string[], nextIds: readonly string[]): StructuralActions => ({
+  forward: { orderedIds: [...nextIds], type: 'reorderCanvasLayers' },
+  inverse: { orderedIds: [...currentIds], type: 'reorderCanvasLayers' },
+});
+
+/** A z-reorder direction for the layer hotkeys. */
+export type LayerReorderKind = 'forward' | 'backward' | 'front' | 'back';
+
+/** The destination index for a z-reorder of the layer at `index` in a stack of `count`. */
+export const reorderTargetIndex = (index: number, count: number, kind: LayerReorderKind): number => {
+  switch (kind) {
+    case 'forward':
+      return Math.max(0, index - 1);
+    case 'backward':
+      return Math.min(count - 1, index + 1);
+    case 'front':
+      return 0;
+    case 'back':
+      return count - 1;
+  }
+};
+
+/** Moves `items[from]` to `to`, shifting the rest. Returns a new array. */
+const moveItem = <T>(items: readonly T[], from: number, to: number): T[] => {
+  const next = [...items];
+  const [moved] = next.splice(from, 1);
+  if (moved === undefined) {
+    return next;
+  }
+  next.splice(to, 0, moved);
+  return next;
+};
+
+/**
+ * The reordered id list for a z-reorder hotkey, or `null` when nothing would move
+ * (already at the boundary, or the index is out of range) so callers can no-op.
+ */
+export const reorderIdsForHotkey = (
+  currentIds: readonly string[],
+  index: number,
+  kind: LayerReorderKind
+): string[] | null => {
+  if (index < 0 || index >= currentIds.length) {
+    return null;
+  }
+  const target = reorderTargetIndex(index, currentIds.length, kind);
+  if (target === index) {
+    return null;
+  }
+  return moveItem(currentIds, index, target);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvasMigration.test.ts b/invokeai/frontend/webv2/src/workbench/canvasMigration.test.ts
new file mode 100644
index 00000000000..74f455fbf7b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasMigration.test.ts
@@ -0,0 +1,661 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createEmptyCanvasStateV2,
+  createNewCanvasStateV2,
+  DEFAULT_CANVAS_DOCUMENT_HEIGHT,
+  DEFAULT_CANVAS_DOCUMENT_WIDTH,
+  migrateCanvasStateToV2,
+  placementToTransform,
+} from './canvasMigration';
+import {
+  createControlLayer,
+  createEmptyPaintLayer,
+  createInpaintMaskLayer,
+  createRegionalGuidanceLayer,
+  nextInpaintMaskName,
+} from './widgets/layers/layerOps';
+
+describe('placementToTransform', () => {
+  it('maps a placement rect to a scale-based transform relative to the source image size', () => {
+    expect(placementToTransform({ height: 200, width: 400, x: 10, y: 20 }, 200, 100)).toEqual({
+      rotation: 0,
+      scaleX: 2,
+      scaleY: 2,
+      x: 10,
+      y: 20,
+    });
+  });
+
+  it('falls back to a 1:1 scale when the source image has no dimensions', () => {
+    expect(placementToTransform({ height: 200, width: 400, x: 0, y: 0 }, 0, 0)).toEqual({
+      rotation: 0,
+      scaleX: 1,
+      scaleY: 1,
+      x: 0,
+      y: 0,
+    });
+  });
+});
+
+describe('migrateCanvasStateToV2', () => {
+  it('round-trips z-image controls without rewriting persisted adapter kinds', () => {
+    const adapters = [
+      { beginEndStepPct: [0, 0.75], controlMode: 'balanced', kind: 'controlnet', model: 'sd-control', weight: 0.75 },
+      { beginEndStepPct: [0, 1], controlMode: null, kind: 't2i_adapter', model: 't2i', weight: 1 },
+      { beginEndStepPct: [0, 1], controlMode: null, kind: 'control_lora', model: 'flux-control', weight: 0.75 },
+      { beginEndStepPct: [0.2, 0.9], controlMode: null, kind: 'z_image_control', model: 'z-control', weight: 0.7 },
+    ] as const;
+    const layers = adapters.map((adapter, index) => ({
+      adapter,
+      blendMode: 'normal',
+      id: `control-${index}`,
+      isEnabled: true,
+      isLocked: false,
+      name: `Control ${index}`,
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'control',
+      withTransparencyEffect: true,
+    }));
+    const state = {
+      ...createEmptyCanvasStateV2(),
+      document: { ...createEmptyCanvasStateV2().document, layers },
+    };
+
+    const migrated = migrateCanvasStateToV2(state);
+
+    expect(migrated.document.layers.map((layer) => (layer.type === 'control' ? layer.adapter : null))).toEqual(
+      adapters
+    );
+  });
+
+  it('normalizes an incomplete persisted Z-Image control with backend defaults', () => {
+    const state = createEmptyCanvasStateV2();
+    const migrated = migrateCanvasStateToV2({
+      ...state,
+      document: {
+        ...state.document,
+        layers: [
+          {
+            adapter: { kind: 'z_image_control', model: 'z-control' },
+            blendMode: 'normal',
+            id: 'z-control',
+            isEnabled: true,
+            isLocked: false,
+            name: 'Z Control',
+            opacity: 1,
+            source: { bitmap: null, type: 'paint' },
+            transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+            type: 'control',
+            withTransparencyEffect: true,
+          },
+        ],
+      },
+    });
+    const layer = migrated.document.layers[0];
+
+    expect(layer?.type).toBe('control');
+    expect(layer?.type === 'control' ? layer.adapter : null).toEqual({
+      beginEndStepPct: [0, 1],
+      controlMode: null,
+      kind: 'z_image_control',
+      model: 'z-control',
+      weight: 0.75,
+    });
+  });
+
+  it('normalizes control adapters in both the live document and saved snapshots', () => {
+    const state = createEmptyCanvasStateV2();
+    const invalidLayer = {
+      adapter: { beginEndStepPct: [0.8, 0.2], controlMode: null, kind: 'z_image_control', model: null, weight: -1 },
+      blendMode: 'normal',
+      id: 'z-control',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Z Control',
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'control',
+      withTransparencyEffect: true,
+    };
+    const document = { ...state.document, layers: [invalidLayer] };
+    const migrated = migrateCanvasStateToV2({
+      ...state,
+      document,
+      snapshots: [{ createdAt: 'now', document, id: 'snapshot', name: 'Snapshot' }],
+    });
+
+    const getAdapter = (doc: (typeof migrated)['document']) => {
+      const layer = doc.layers[0];
+      return layer?.type === 'control' ? layer.adapter : null;
+    };
+    expect(getAdapter(migrated.document)).toMatchObject({ beginEndStepPct: [0, 1], weight: 0.75 });
+    expect(getAdapter(migrated.snapshots[0]!.document)).toMatchObject({ beginEndStepPct: [0, 1], weight: 0.75 });
+  });
+
+  it('keeps valid snapshots and discards malformed snapshot entries without blocking the live canvas', () => {
+    const state = createEmptyCanvasStateV2();
+    const liveLayer = {
+      blendMode: 'normal',
+      id: 'live',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Live',
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    };
+    const snapshotLayer = {
+      adapter: { kind: 'z_image_control', model: 'z-control' },
+      ...liveLayer,
+      id: 'snapshot-control',
+      name: 'Snapshot Control',
+      type: 'control',
+      withTransparencyEffect: true,
+    };
+    const validDocument = { ...state.document, layers: [snapshotLayer] };
+
+    const migrated = migrateCanvasStateToV2({
+      ...state,
+      document: { ...state.document, layers: [liveLayer] },
+      snapshots: [
+        { createdAt: 'now', document: validDocument, id: 'valid', name: 'Valid' },
+        null,
+        'malformed',
+        {},
+        { createdAt: 'now', id: 'missing-document', name: 'Missing document' },
+        { createdAt: 'now', document: null, id: 'null-document', name: 'Null document' },
+        {
+          createdAt: 'now',
+          document: { ...state.document, layers: { bad: true } },
+          id: 'malformed-layers',
+          name: 'Malformed layers',
+        },
+      ],
+    });
+
+    expect(migrated.document.layers.map((layer) => layer.id)).toEqual(['live']);
+    expect(migrated.snapshots).toHaveLength(1);
+    expect(migrated.snapshots[0]).toMatchObject({ createdAt: 'now', id: 'valid', name: 'Valid' });
+    const validLayer = migrated.snapshots[0]!.document.layers[0];
+    expect(validLayer?.type === 'control' ? validLayer.adapter : null).toEqual({
+      beginEndStepPct: [0, 1],
+      controlMode: null,
+      kind: 'z_image_control',
+      model: 'z-control',
+      weight: 0.75,
+    });
+  });
+
+  it.each([
+    ['missing discriminant and base fields', { id: 'broken' }],
+    ['raster with invalid source', { ...createEmptyPaintLayer('Raster', 'raster'), source: null }],
+    ['control with invalid adapter', { ...createControlLayer('Control', 'control'), adapter: null }],
+    [
+      'regional guidance with invalid mask',
+      { ...createRegionalGuidanceLayer('Region', 0, 'region'), mask: { bitmap: null, fill: null } },
+    ],
+    ['inpaint mask with invalid mask', { ...createInpaintMaskLayer('Mask', 'mask'), mask: null }],
+  ])('discards a snapshot containing a malformed layer: %s', (_label, malformedLayer) => {
+    const state = createEmptyCanvasStateV2();
+    const migrated = migrateCanvasStateToV2({
+      ...state,
+      snapshots: [
+        {
+          createdAt: 'now',
+          document: { ...state.document, layers: [malformedLayer] },
+          id: 'malformed',
+          name: 'Malformed',
+        },
+      ],
+    });
+
+    expect(migrated.snapshots).toEqual([]);
+    expect(migrated.document.layers).toEqual([]);
+  });
+
+  it('round-trips valid snapshots containing every layer type', () => {
+    const state = createEmptyCanvasStateV2();
+    const layers = [
+      createEmptyPaintLayer('Raster', 'raster'),
+      createControlLayer('Control', 'control'),
+      createRegionalGuidanceLayer('Region', 0, 'region'),
+      createInpaintMaskLayer('Mask', 'mask'),
+    ];
+    const snapshot = {
+      createdAt: 'now',
+      document: { ...state.document, layers, selectedLayerId: 'control' },
+      id: 'valid-layers',
+      name: 'Valid layers',
+    };
+
+    const migrated = migrateCanvasStateToV2({ ...state, snapshots: [snapshot] });
+
+    expect(migrated.snapshots).toEqual([snapshot]);
+  });
+
+  it('filters malformed live layers without discarding valid live layers', () => {
+    const state = createEmptyCanvasStateV2();
+    const valid = createEmptyPaintLayer('Valid', 'valid');
+    const migrated = migrateCanvasStateToV2({
+      ...state,
+      document: { ...state.document, layers: [{ id: 'broken' }, valid] },
+    });
+
+    expect(migrated.document.layers).toEqual([valid]);
+  });
+
+  it('maps a v1 raster layer to a v2 raster layer positioned by transform', () => {
+    const v1Canvas = {
+      document: {
+        height: 768,
+        layers: [
+          {
+            acceptedAt: '2026-06-09T00:00:00.000Z',
+            height: 512,
+            id: 'layer-1',
+            imageName: 'candidate.png',
+            imageUrl: '/api/v1/images/i/candidate.png/full',
+            label: 'Layer 1',
+            placement: { height: 300, opacity: 0.8, width: 600, x: 12, y: 24 },
+            queuedAt: '2026-06-09T00:00:00.000Z',
+            sourceQueueItemId: 'queue-1',
+            thumbnailUrl: '/api/v1/images/i/candidate.png/thumbnail',
+            width: 1024,
+          },
+        ],
+        version: 1,
+        width: 1024,
+      },
+      stagingArea: {
+        areThumbnailsVisible: true,
+        isVisible: false,
+        pendingImageIds: [],
+        pendingImages: [],
+        selectedImageIndex: 0,
+      },
+      version: 1,
+    };
+
+    const migrated = migrateCanvasStateToV2(v1Canvas);
+
+    expect(migrated.version).toBe(2);
+    expect(migrated.document.layers).toHaveLength(1);
+
+    const layer = migrated.document.layers[0];
+
+    expect(layer).toEqual({
+      blendMode: 'normal',
+      id: 'layer-1',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Layer 1',
+      opacity: 0.8,
+      source: { image: { height: 512, imageName: 'candidate.png', width: 1024 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 600 / 1024, scaleY: 300 / 512, x: 12, y: 24 },
+      type: 'raster',
+    });
+  });
+
+  it('generates an id and positional name for a layer missing them, and defaults a missing placement', () => {
+    const migrated = migrateCanvasStateToV2({
+      document: {
+        height: 512,
+        layers: [{ height: 256, imageName: 'no-id.png', width: 256 }],
+        width: 512,
+      },
+      version: 1,
+    });
+
+    const layer = migrated.document.layers[0];
+
+    expect(layer?.id).toBeTruthy();
+    expect(layer?.name).toBe('Layer 1');
+    expect(layer?.type).toBe('raster');
+
+    if (layer?.type === 'raster' && layer.source.type === 'image') {
+      expect(layer.source.image).toEqual({ height: 256, imageName: 'no-id.png', width: 256 });
+      expect(layer.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 });
+      expect(layer.opacity).toBe(1);
+    }
+  });
+
+  it('migrates a bare imageName-string legacy layer', () => {
+    const migrated = migrateCanvasStateToV2({
+      document: { height: 512, layers: ['legacy-image.png'], width: 512 },
+      version: 1,
+    });
+
+    const layer = migrated.document.layers[0];
+
+    expect(layer?.name).toBe('legacy-image.png');
+
+    if (layer?.type === 'raster' && layer.source.type === 'image') {
+      expect(layer.source.image.imageName).toBe('legacy-image.png');
+    }
+  });
+
+  it('supports the pre-`document` legacy shape with layers directly on the canvas', () => {
+    const migrated = migrateCanvasStateToV2({
+      layers: ['ancient.png'],
+      version: 1,
+    });
+
+    expect(migrated.document.width).toBe(DEFAULT_CANVAS_DOCUMENT_WIDTH);
+    expect(migrated.document.height).toBe(DEFAULT_CANVAS_DOCUMENT_HEIGHT);
+    expect(migrated.document.layers).toHaveLength(1);
+  });
+
+  it('defaults bbox to the full document rect', () => {
+    const migrated = migrateCanvasStateToV2({ document: { height: 600, layers: [], width: 800 }, version: 1 });
+
+    expect(migrated.document.bbox).toEqual({ height: 600, width: 800, x: 0, y: 0 });
+  });
+
+  it('defaults selectedLayerId to null (v1 had no selection concept)', () => {
+    const migrated = migrateCanvasStateToV2({ document: { height: 512, layers: [], width: 512 }, version: 1 });
+
+    expect(migrated.document.selectedLayerId).toBeNull();
+  });
+
+  it('carries the staging area through unchanged and defaults autoSwitchMode to off', () => {
+    const pendingImages = [
+      {
+        height: 512,
+        imageName: 'staged.png',
+        imageUrl: '/api/v1/images/i/staged.png/full',
+        placement: { height: 512, opacity: 1, width: 512, x: 0, y: 0 },
+        queuedAt: '2026-06-09T00:00:00.000Z',
+        sourceQueueItemId: 'queue-1',
+        thumbnailUrl: '/api/v1/images/i/staged.png/thumbnail',
+        width: 512,
+      },
+    ];
+
+    const migrated = migrateCanvasStateToV2({
+      document: { height: 512, layers: [], width: 512 },
+      stagingArea: {
+        areThumbnailsVisible: false,
+        isVisible: true,
+        pendingImageIds: ['staged.png'],
+        pendingImages,
+        selectedImageIndex: 0,
+        selectedLayerId: 'layer-x',
+        sourceQueueItemId: 'queue-1',
+      },
+      version: 1,
+    });
+
+    expect(migrated.stagingArea).toEqual({
+      areThumbnailsVisible: false,
+      autoSwitchMode: 'off',
+      isVisible: true,
+      pendingImageIds: ['staged.png'],
+      pendingImages,
+      selectedImageIndex: 0,
+      selectedLayerId: 'layer-x',
+      sourceQueueItemId: 'queue-1',
+    });
+    // The candidate objects themselves are carried through by reference, not reshaped.
+    expect(migrated.stagingArea.pendingImages[0]).toBe(pendingImages[0]);
+  });
+
+  it('starts with no snapshots', () => {
+    const migrated = migrateCanvasStateToV2({ document: { height: 512, layers: [], width: 512 }, version: 1 });
+
+    expect(migrated.snapshots).toEqual([]);
+  });
+
+  it('passes already-v2 input through normalized rather than re-migrating it', () => {
+    const v2Canvas = {
+      document: {
+        background: 'transparent',
+        bbox: { height: 512, width: 512, x: 0, y: 0 },
+        height: 512,
+        layers: [
+          {
+            blendMode: 'multiply',
+            id: 'layer-1',
+            isEnabled: true,
+            isLocked: false,
+            name: 'Layer 1',
+            opacity: 0.5,
+            source: { image: { height: 100, imageName: 'v2.png', width: 100 }, type: 'image' },
+            transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+            type: 'raster',
+          },
+        ],
+        selectedLayerId: 'layer-1',
+        version: 2,
+        width: 512,
+      },
+      documentRevision: 0,
+      snapshots: [],
+      stagingArea: {
+        areThumbnailsVisible: true,
+        autoSwitchMode: 'latest',
+        isVisible: false,
+        pendingImageIds: [],
+        pendingImages: [],
+        selectedImageIndex: 0,
+      },
+      version: 2,
+    };
+
+    const migrated = migrateCanvasStateToV2(v2Canvas);
+
+    expect(migrated).toEqual(v2Canvas);
+    // Not double-migrated: blendMode/opacity/selectedLayerId survive untouched, which a v1->v2
+    // re-derivation from a (nonexistent) placement would not preserve.
+    expect(migrated.document.layers[0]).toEqual(v2Canvas.document.layers[0]);
+    expect(migrated.stagingArea.autoSwitchMode).toBe('latest');
+  });
+
+  it('preserves the progress canvas staging auto-switch mode', () => {
+    const migrated = migrateCanvasStateToV2({
+      document: { height: 512, layers: [], width: 512 },
+      stagingArea: { autoSwitchMode: 'progress' },
+      version: 2,
+    });
+
+    expect(migrated.stagingArea.autoSwitchMode).toBe('progress');
+  });
+
+  it('normalizes the removed oldest canvas staging auto-switch mode to off', () => {
+    const migrated = migrateCanvasStateToV2({
+      document: { height: 512, layers: [], width: 512 },
+      stagingArea: { autoSwitchMode: 'oldest' },
+      version: 2,
+    });
+
+    expect(migrated.stagingArea.autoSwitchMode).toBe('off');
+  });
+
+  it('round-trips content-sized fields (paint offset, gradient width/height) on an already-v2 doc unchanged', () => {
+    const paintOffset = { x: -30, y: 45 };
+    const gradientExtent = { height: 220, width: 180 };
+    const v2Canvas = {
+      document: {
+        background: 'transparent',
+        bbox: { height: 512, width: 512, x: 0, y: 0 },
+        height: 512,
+        layers: [
+          {
+            blendMode: 'normal',
+            id: 'paint-1',
+            isEnabled: true,
+            isLocked: false,
+            name: 'Paint 1',
+            opacity: 1,
+            // Content-sized paint bitmap placed off-origin.
+            source: { bitmap: { height: 40, imageName: 'paint.png', width: 40 }, offset: paintOffset, type: 'paint' },
+            transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+            type: 'raster',
+          },
+          {
+            blendMode: 'normal',
+            id: 'gradient-1',
+            isEnabled: true,
+            isLocked: false,
+            name: 'Gradient 1',
+            opacity: 1,
+            // Gradient carrying an explicit content extent (not document-sized).
+            source: {
+              angle: 45,
+              height: gradientExtent.height,
+              kind: 'linear',
+              stops: [
+                { color: '#000000', offset: 0 },
+                { color: '#ffffff', offset: 1 },
+              ],
+              type: 'gradient',
+              width: gradientExtent.width,
+            },
+            transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+            type: 'raster',
+          },
+        ],
+        selectedLayerId: 'paint-1',
+        version: 2,
+        width: 512,
+      },
+      documentRevision: 3,
+      snapshots: [],
+      stagingArea: {
+        areThumbnailsVisible: true,
+        autoSwitchMode: 'off',
+        isVisible: false,
+        pendingImageIds: [],
+        pendingImages: [],
+        selectedImageIndex: 0,
+      },
+      version: 2,
+    };
+
+    const migrated = migrateCanvasStateToV2(v2Canvas);
+
+    // Whole-state round-trip: normalization must not drop or rewrite the
+    // content-sizing fields the current schema carries.
+    expect(migrated).toEqual(v2Canvas);
+    const paintLayer = migrated.document.layers[0];
+    const gradientLayer = migrated.document.layers[1];
+    if (paintLayer?.type !== 'raster' || gradientLayer?.type !== 'raster') {
+      throw new Error('expected two raster layers to survive normalization');
+    }
+    expect(paintLayer.source).toEqual({
+      bitmap: { height: 40, imageName: 'paint.png', width: 40 },
+      offset: paintOffset,
+      type: 'paint',
+    });
+    expect(gradientLayer.source).toMatchObject({
+      height: gradientExtent.height,
+      type: 'gradient',
+      width: gradientExtent.width,
+    });
+  });
+
+  it.each([undefined, null, 'garbage', 42, [], {}])(
+    'falls back to a fresh empty v2 state for garbage input (%j)',
+    (garbage) => {
+      const migrated = migrateCanvasStateToV2(garbage);
+
+      expect(migrated).toEqual(createEmptyCanvasStateV2());
+      expect(migrated.document.width).toBe(DEFAULT_CANVAS_DOCUMENT_WIDTH);
+      expect(migrated.document.height).toBe(DEFAULT_CANVAS_DOCUMENT_HEIGHT);
+      expect(migrated.document.layers).toEqual([]);
+      expect(migrated.stagingArea.autoSwitchMode).toBe('off');
+    }
+  );
+});
+
+describe('createEmptyCanvasStateV2', () => {
+  it('creates a well-formed empty v2 canvas at the default document size', () => {
+    const state = createEmptyCanvasStateV2();
+
+    expect(state).toEqual({
+      document: {
+        background: 'transparent',
+        bbox: { height: DEFAULT_CANVAS_DOCUMENT_HEIGHT, width: DEFAULT_CANVAS_DOCUMENT_WIDTH, x: 0, y: 0 },
+        height: DEFAULT_CANVAS_DOCUMENT_HEIGHT,
+        layers: [],
+        selectedLayerId: null,
+        version: 2,
+        width: DEFAULT_CANVAS_DOCUMENT_WIDTH,
+      },
+      documentRevision: 0,
+      snapshots: [],
+      stagingArea: {
+        areThumbnailsVisible: true,
+        autoSwitchMode: 'off',
+        isVisible: false,
+        pendingImageIds: [],
+        pendingImages: [],
+        selectedImageIndex: 0,
+      },
+      version: 2,
+    });
+  });
+
+  it('honors a custom document size', () => {
+    const state = createEmptyCanvasStateV2(800, 600);
+
+    expect(state.document.width).toBe(800);
+    expect(state.document.height).toBe(600);
+    expect(state.document.bbox).toEqual({ height: 600, width: 800, x: 0, y: 0 });
+  });
+});
+
+describe('createNewCanvasStateV2', () => {
+  it('seeds exactly one empty inpaint mask, selected, with legacy-default fill', () => {
+    const state = createNewCanvasStateV2();
+    const { layers, selectedLayerId } = state.document;
+
+    expect(layers).toHaveLength(1);
+    const mask = layers[0];
+    expect(mask?.type).toBe('inpaint_mask');
+    expect(mask?.name).toBe('Inpaint Mask 1');
+    expect(mask?.isEnabled).toBe(true);
+    expect(mask?.isLocked).toBe(false);
+    expect(mask?.opacity).toBe(1);
+    // Empty = no bitmap (no strokes); the diagonal-hatch fill is the legacy default.
+    expect(mask && 'mask' in mask ? mask.mask : null).toEqual({
+      bitmap: null,
+      fill: { color: '#e07575', style: 'diagonal' },
+    });
+    // The seeded mask is the initially selected layer.
+    expect(selectedLayerId).toBe(mask?.id);
+  });
+
+  it('matches the layers-panel inpaint-mask factory shape (kept in lockstep)', () => {
+    const state = createNewCanvasStateV2();
+    const mask = state.document.layers[0];
+    // Rebuild the expected layer via the canonical factory, pinning the minted id
+    // and name so only the contract shape is compared.
+    const expected = createInpaintMaskLayer(nextInpaintMaskName([]), mask?.id ?? '');
+
+    expect(mask).toEqual(expected);
+  });
+
+  it('honors a custom document size while staying otherwise identical to an empty canvas', () => {
+    const state = createNewCanvasStateV2(800, 600);
+
+    expect(state.document.width).toBe(800);
+    expect(state.document.height).toBe(600);
+    expect(state.document.bbox).toEqual({ height: 600, width: 800, x: 0, y: 0 });
+    // Only the document's layers/selection differ from the empty canvas.
+    expect({ ...state, document: { ...state.document, layers: [], selectedLayerId: null } }).toEqual(
+      createEmptyCanvasStateV2(800, 600)
+    );
+  });
+
+  it('does not disturb the migration/empty path (garbage still migrates to an empty, mask-free canvas)', () => {
+    // The new-canvas seed is scoped to fresh projects only; migrating unknown
+    // input keeps producing an empty, mask-free document.
+    expect(migrateCanvasStateToV2('garbage').document.layers).toEqual([]);
+    expect(createEmptyCanvasStateV2().document.layers).toEqual([]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvasMigration.ts b/invokeai/frontend/webv2/src/workbench/canvasMigration.ts
new file mode 100644
index 00000000000..a55332cf374
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasMigration.ts
@@ -0,0 +1,534 @@
+import { z } from 'zod';
+
+/**
+ * Canvas v1 -> v2 document migration.
+ *
+ * `CanvasStateContract` (v1) only ever produced a flat stack of single-image
+ * raster layers positioned by an absolute `placement` rect. `CanvasStateContractV2`
+ * (see `types.ts`) generalizes the document into a typed layer union (raster,
+ * control, regional guidance, inpaint mask) positioned by a `transform`, with
+ * bitmaps referenced by `imageName` rather than by resolved URL.
+ *
+ * `migrateCanvasStateToV2` accepts genuinely unknown input (as read from
+ * localStorage) so it doubles as both the v1->v2 converter and the
+ * garbage/undefined-input fallback used when normalizing a loaded project.
+ * Already-v2 input passes through normalized, not double-migrated.
+ */
+import type {
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerBaseContract,
+  CanvasRasterLayerContractV2,
+  CanvasStagingAreaContractV2,
+  CanvasStateContractV2,
+} from './types';
+
+import { normalizeControlAdapter } from './controlAdapters';
+
+export const DEFAULT_CANVAS_DOCUMENT_WIDTH = 1024;
+export const DEFAULT_CANVAS_DOCUMENT_HEIGHT = 1024;
+
+const createMigrationId = (prefix: string): string =>
+  `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+const zFiniteNumber = z.number().finite();
+const zCoordinate = z.object({ x: zFiniteNumber, y: zFiniteNumber });
+const zImageRef = z.object({
+  contentHash: z.string().optional(),
+  height: zFiniteNumber.nonnegative(),
+  imageName: z.string(),
+  width: zFiniteNumber.nonnegative(),
+});
+const zPaintSource = z.object({
+  bitmap: zImageRef.nullable(),
+  offset: zCoordinate.optional(),
+  type: z.literal('paint'),
+});
+const zLayerSource = z.discriminatedUnion('type', [
+  zPaintSource,
+  z.object({ image: zImageRef, type: z.literal('image') }),
+  z.object({
+    align: z.enum(['left', 'center', 'right']),
+    color: z.string(),
+    content: z.string(),
+    fontFamily: z.string(),
+    fontSize: zFiniteNumber,
+    fontWeight: zFiniteNumber,
+    lineHeight: zFiniteNumber,
+    type: z.literal('text'),
+  }),
+  z.object({
+    fill: z.string().nullable(),
+    height: zFiniteNumber,
+    kind: z.enum(['rect', 'ellipse', 'polygon']),
+    points: z.array(zCoordinate).optional(),
+    stroke: z.string().nullable(),
+    strokeWidth: zFiniteNumber,
+    type: z.literal('shape'),
+    width: zFiniteNumber,
+  }),
+  z.object({
+    angle: zFiniteNumber,
+    height: zFiniteNumber.positive().optional(),
+    kind: z.enum(['linear', 'radial']),
+    stops: z.array(z.object({ color: z.string(), offset: zFiniteNumber })),
+    type: z.literal('gradient'),
+    width: zFiniteNumber.positive().optional(),
+  }),
+]);
+const zTransform = z.object({
+  rotation: zFiniteNumber,
+  scaleX: zFiniteNumber,
+  scaleY: zFiniteNumber,
+  x: zFiniteNumber,
+  y: zFiniteNumber,
+});
+const zFilter = z.object({ settings: z.record(z.string(), z.unknown()), type: z.string() });
+const zCurve = z.array(z.tuple([zFiniteNumber, zFiniteNumber]));
+const zAdjustments = z.object({
+  brightness: zFiniteNumber,
+  contrast: zFiniteNumber,
+  curves: z.object({ b: zCurve, g: zCurve, r: zCurve }).optional(),
+  saturation: zFiniteNumber,
+});
+const zControlAdapter = z
+  .object({
+    beginEndStepPct: z.tuple([zFiniteNumber, zFiniteNumber]),
+    controlMode: z.enum(['balanced', 'more_prompt', 'more_control', 'unbalanced']).nullable(),
+    kind: z.enum(['controlnet', 't2i_adapter', 'control_lora', 'z_image_control']),
+    model: z.string().nullable(),
+    weight: zFiniteNumber,
+  })
+  .refine(({ beginEndStepPct }) => {
+    const [begin, end] = beginEndStepPct;
+    return begin >= 0 && end <= 1 && begin < end;
+  })
+  .refine(({ kind, weight }) => weight >= (kind === 'z_image_control' ? 0 : -1) && weight <= 2);
+const zMask = z.object({
+  bitmap: zImageRef.nullable(),
+  fill: z.object({
+    color: z.string(),
+    style: z.enum(['solid', 'grid', 'crosshatch', 'diagonal', 'horizontal', 'vertical']),
+  }),
+  offset: zCoordinate.optional(),
+});
+const zGeneratedImage = z.object({
+  height: zFiniteNumber.nonnegative(),
+  imageName: z.string(),
+  imageUrl: z.string(),
+  queuedAt: z.string(),
+  sourceQueueItemId: z.string(),
+  thumbnailUrl: z.string(),
+  width: zFiniteNumber.nonnegative(),
+});
+const zModelIdentifier = z.object({ base: z.string(), key: z.string(), name: z.string(), type: z.string() });
+const zReferenceImage = z.object({
+  config: z.discriminatedUnion('type', [
+    z.object({
+      beginEndStepPct: z.tuple([zFiniteNumber, zFiniteNumber]),
+      clipVisionModel: z.enum(['ViT-H', 'ViT-G', 'ViT-L']),
+      image: zGeneratedImage.nullable(),
+      method: z.enum(['full', 'style', 'composition', 'style_strong', 'style_precise']),
+      model: zModelIdentifier.nullable(),
+      type: z.literal('ip_adapter'),
+      weight: zFiniteNumber,
+    }),
+    z.object({
+      image: zGeneratedImage.nullable(),
+      imageInfluence: z.enum(['lowest', 'low', 'medium', 'high', 'highest']),
+      model: zModelIdentifier.nullable(),
+      type: z.literal('flux_redux'),
+    }),
+    z.object({
+      image: zGeneratedImage.nullable(),
+      model: zModelIdentifier.nullable(),
+      type: z.literal('flux_kontext_reference_image'),
+    }),
+    z.object({ image: zGeneratedImage.nullable(), type: z.literal('flux2_reference_image') }),
+    z.object({ image: zGeneratedImage.nullable(), type: z.literal('qwen_image_reference_image') }),
+    z.object({ image: zGeneratedImage.nullable(), type: z.literal('external_reference_image') }),
+  ]),
+  id: z.string(),
+  isEnabled: z.boolean(),
+});
+const zLayerBase = z.object({
+  blendMode: z.enum([
+    'normal',
+    'multiply',
+    'screen',
+    'overlay',
+    'darken',
+    'lighten',
+    'color-dodge',
+    'color-burn',
+    'hard-light',
+    'soft-light',
+    'difference',
+    'exclusion',
+    'hue',
+    'saturation',
+    'color',
+    'luminosity',
+  ]),
+  id: z.string(),
+  isEnabled: z.boolean(),
+  isLocked: z.boolean(),
+  name: z.string(),
+  opacity: zFiniteNumber.min(0).max(1),
+  transform: zTransform,
+});
+const zCanvasLayer = z.discriminatedUnion('type', [
+  zLayerBase.extend({
+    adjustments: zAdjustments.optional(),
+    filter: zFilter.optional(),
+    isTransparencyLocked: z.boolean().optional(),
+    source: zLayerSource,
+    type: z.literal('raster'),
+  }),
+  zLayerBase.extend({
+    adapter: zControlAdapter,
+    filter: zFilter.optional(),
+    source: zLayerSource,
+    type: z.literal('control'),
+    withTransparencyEffect: z.boolean(),
+  }),
+  zLayerBase.extend({
+    autoNegative: z.boolean(),
+    mask: zMask,
+    negativePrompt: z.string().nullable(),
+    positivePrompt: z.string().nullable(),
+    referenceImages: z.array(zReferenceImage),
+    type: z.literal('regional_guidance'),
+  }),
+  zLayerBase.extend({
+    denoiseLimit: zFiniteNumber.optional(),
+    mask: zMask,
+    noiseLevel: zFiniteNumber.optional(),
+    type: z.literal('inpaint_mask'),
+  }),
+]);
+
+const asNumber = (value: unknown, fallback: number): number => (typeof value === 'number' ? value : fallback);
+
+const asString = (value: unknown, fallback: string): string => (typeof value === 'string' ? value : fallback);
+
+const asPositiveNumber = (value: unknown, fallback: number): number => {
+  const numeric = asNumber(value, fallback);
+
+  return numeric > 0 ? numeric : fallback;
+};
+
+export const createEmptyCanvasStateV2 = (
+  width = DEFAULT_CANVAS_DOCUMENT_WIDTH,
+  height = DEFAULT_CANVAS_DOCUMENT_HEIGHT
+): CanvasStateContractV2 => ({
+  document: createEmptyCanvasDocumentV2(width, height),
+  documentRevision: 0,
+  snapshots: [],
+  stagingArea: createDefaultStagingAreaV2(),
+  version: 2,
+});
+
+export const createEmptyCanvasDocumentV2 = (
+  width = DEFAULT_CANVAS_DOCUMENT_WIDTH,
+  height = DEFAULT_CANVAS_DOCUMENT_HEIGHT
+): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height, width, x: 0, y: 0 },
+  height,
+  layers: [],
+  selectedLayerId: null,
+  version: 2,
+  width,
+});
+
+/**
+ * A brand-new project's default inpaint mask: one empty mask (no bitmap/strokes)
+ * with the legacy-default diagonal-hatch fill in the first cycled mask colour
+ * (legacy `rgb(224,117,117)`). Mirrors `createInpaintMaskLayer` /
+ * `DEFAULT_INPAINT_MASK_FILL` in `widgets/layers/layerOps` — duplicated here so
+ * the pure reducer/migration module doesn't pull in the layers-panel/engine
+ * module graph; `canvasMigration.test.ts` locks the shape against that factory.
+ */
+const createInitialInpaintMaskLayer = (): CanvasInpaintMaskLayerContract => ({
+  blendMode: 'normal',
+  id: createMigrationId('layer'),
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+  name: 'Inpaint Mask 1',
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+/**
+ * A fresh canvas state for a newly created project: an empty document that
+ * already carries one empty inpaint mask (selected), matching legacy, which seeds
+ * a canvas session with an inpaint mask present. The mask has no content, so it
+ * does NOT flip generation-mode detection to inpaint (see `detectCanvasMode`).
+ *
+ * This is the NEW-canvas path only. The migration / garbage-fallback path
+ * (`migrateCanvasStateToV2`) and `createEmptyCanvasStateV2` stay empty, so
+ * existing and migrated documents are left untouched.
+ */
+export const createNewCanvasStateV2 = (
+  width = DEFAULT_CANVAS_DOCUMENT_WIDTH,
+  height = DEFAULT_CANVAS_DOCUMENT_HEIGHT
+): CanvasStateContractV2 => {
+  const base = createEmptyCanvasStateV2(width, height);
+  const mask = createInitialInpaintMaskLayer();
+
+  return {
+    ...base,
+    document: { ...base.document, layers: [mask], selectedLayerId: mask.id },
+  };
+};
+
+const createDefaultStagingAreaV2 = (): CanvasStagingAreaContractV2 => ({
+  areThumbnailsVisible: true,
+  autoSwitchMode: 'off',
+  isVisible: false,
+  pendingImageIds: [],
+  pendingImages: [],
+  selectedImageIndex: 0,
+});
+
+/**
+ * Converts a v1 `{x,y,width,height}` placement rect, plus the native size of the image it
+ * places, into a v2 `transform`. Shared by the migration path and the live "accept staged
+ * image into a raster layer" reducer, which still works from a v1-shaped placement.
+ */
+export const placementToTransform = (
+  placement: { x: number; y: number; width: number; height: number },
+  imageWidth: number,
+  imageHeight: number
+): CanvasLayerBaseContract['transform'] => ({
+  rotation: 0,
+  scaleX: imageWidth > 0 ? placement.width / imageWidth : 1,
+  scaleY: imageHeight > 0 ? placement.height / imageHeight : 1,
+  x: placement.x,
+  y: placement.y,
+});
+
+/** Migrates a single v1 `CanvasRasterLayerContract` (or bare imageName string) into a v2 raster layer. */
+const migrateLayerToV2 = (rawLayer: unknown, index: number): CanvasRasterLayerContractV2 => {
+  if (typeof rawLayer === 'string') {
+    return {
+      blendMode: 'normal',
+      id: rawLayer || createMigrationId('layer'),
+      isEnabled: true,
+      isLocked: false,
+      name: rawLayer || `Layer ${index + 1}`,
+      opacity: 1,
+      source: { image: { height: 0, imageName: rawLayer, width: 0 }, type: 'image' },
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'raster',
+    };
+  }
+
+  const layer = isRecord(rawLayer) ? rawLayer : {};
+  const image: CanvasImageRef = {
+    height: asNumber(layer.height, 0),
+    imageName: asString(layer.imageName, ''),
+    width: asNumber(layer.width, 0),
+  };
+  const placement = isRecord(layer.placement) ? layer.placement : {};
+  const placementX = asNumber(placement.x, 0);
+  const placementY = asNumber(placement.y, 0);
+  const placementWidth = asNumber(placement.width, image.width);
+  const placementHeight = asNumber(placement.height, image.height);
+  const placementOpacity = typeof placement.opacity === 'number' ? placement.opacity : 1;
+
+  return {
+    blendMode: 'normal',
+    id: asString(layer.id, createMigrationId('layer')),
+    isEnabled: true,
+    isLocked: false,
+    name: asString(layer.label, `Layer ${index + 1}`),
+    opacity: placementOpacity,
+    source: { image, type: 'image' },
+    transform: placementToTransform(
+      { height: placementHeight, width: placementWidth, x: placementX, y: placementY },
+      image.width,
+      image.height
+    ),
+    type: 'raster',
+  };
+};
+
+const migrateDocumentToV2 = (rawCanvas: Record<string, unknown>): CanvasDocumentContractV2 => {
+  const rawDocument = isRecord(rawCanvas.document) ? rawCanvas.document : rawCanvas;
+  const width = asPositiveNumber(rawDocument.width, DEFAULT_CANVAS_DOCUMENT_WIDTH);
+  const height = asPositiveNumber(rawDocument.height, DEFAULT_CANVAS_DOCUMENT_HEIGHT);
+  const rawLayers = Array.isArray(rawDocument.layers) ? rawDocument.layers : [];
+
+  return {
+    background: 'transparent',
+    bbox: { height, width, x: 0, y: 0 },
+    height,
+    layers: rawLayers.map((rawLayer, index) => migrateLayerToV2(rawLayer, index)),
+    selectedLayerId: null,
+    version: 2,
+    width,
+  };
+};
+
+const AUTO_SWITCH_MODES: CanvasStagingAreaContractV2['autoSwitchMode'][] = ['off', 'latest', 'progress'];
+
+const asAutoSwitchMode = (value: unknown): CanvasStagingAreaContractV2['autoSwitchMode'] =>
+  AUTO_SWITCH_MODES.includes(value as CanvasStagingAreaContractV2['autoSwitchMode'])
+    ? (value as CanvasStagingAreaContractV2['autoSwitchMode'])
+    : 'off';
+
+/**
+ * Normalizes a v1 or v2 staging area. v1 never had `autoSwitchMode`, so it's absent from raw
+ * input and defaults to `'off'`; already-v2 input keeps its existing value.
+ */
+const migrateStagingAreaToV2 = (rawCanvas: Record<string, unknown>): CanvasStagingAreaContractV2 => {
+  const rawStagingArea = isRecord(rawCanvas.stagingArea) ? rawCanvas.stagingArea : {};
+  const defaults = createDefaultStagingAreaV2();
+
+  return {
+    areThumbnailsVisible:
+      typeof rawStagingArea.areThumbnailsVisible === 'boolean'
+        ? rawStagingArea.areThumbnailsVisible
+        : defaults.areThumbnailsVisible,
+    autoSwitchMode: asAutoSwitchMode(rawStagingArea.autoSwitchMode),
+    isVisible: typeof rawStagingArea.isVisible === 'boolean' ? rawStagingArea.isVisible : defaults.isVisible,
+    pendingImageIds: Array.isArray(rawStagingArea.pendingImageIds)
+      ? (rawStagingArea.pendingImageIds as CanvasStagingAreaContractV2['pendingImageIds'])
+      : defaults.pendingImageIds,
+    pendingImages: Array.isArray(rawStagingArea.pendingImages)
+      ? (rawStagingArea.pendingImages as CanvasStagingAreaContractV2['pendingImages'])
+      : defaults.pendingImages,
+    selectedImageIndex: asNumber(rawStagingArea.selectedImageIndex, defaults.selectedImageIndex),
+    ...(typeof rawStagingArea.selectedLayerId === 'string' ? { selectedLayerId: rawStagingArea.selectedLayerId } : {}),
+    ...(typeof rawStagingArea.sourceQueueItemId === 'string'
+      ? { sourceQueueItemId: rawStagingArea.sourceQueueItemId }
+      : {}),
+  };
+};
+
+const isCanvasStateV2 = (canvas: unknown): canvas is Record<string, unknown> & { version: 2 } =>
+  isRecord(canvas) && canvas.version === 2;
+
+const normalizeCanvasLayer = (value: unknown): CanvasDocumentContractV2['layers'][number] | null => {
+  if (!isRecord(value)) {
+    return null;
+  }
+  let candidate: Record<string, unknown> = value;
+  if (value.type === 'control') {
+    candidate = {
+      ...value,
+      adapter: normalizeControlAdapter(value.adapter),
+      withTransparencyEffect: value.withTransparencyEffect === undefined ? true : value.withTransparencyEffect,
+    };
+  } else if (value.type === 'regional_guidance') {
+    candidate = {
+      ...value,
+      autoNegative: value.autoNegative === undefined ? false : value.autoNegative,
+      negativePrompt: value.negativePrompt === undefined ? null : value.negativePrompt,
+      positivePrompt: value.positivePrompt === undefined ? null : value.positivePrompt,
+      referenceImages: value.referenceImages === undefined ? [] : value.referenceImages,
+    };
+  }
+  const parsed = zCanvasLayer.safeParse(candidate);
+  return parsed.success ? (candidate as unknown as CanvasDocumentContractV2['layers'][number]) : null;
+};
+
+export const normalizeCanvasDocumentControlAdapters = (
+  document: CanvasDocumentContractV2
+): CanvasDocumentContractV2 => ({
+  ...document,
+  layers: document.layers.flatMap((layer) => {
+    const normalized = normalizeCanvasLayer(layer);
+    return normalized ? [normalized] : [];
+  }),
+});
+
+const normalizeCanvasDocumentV2 = (value: unknown, requireValidLayers: boolean): CanvasDocumentContractV2 | null => {
+  const rawDocument = isRecord(value) ? value : {};
+  const rawLayers = Array.isArray(rawDocument.layers) ? rawDocument.layers : [];
+  const layers = rawLayers.flatMap((layer) => {
+    const normalized = normalizeCanvasLayer(layer);
+    return normalized ? [normalized] : [];
+  });
+  if (requireValidLayers && (!Array.isArray(rawDocument.layers) || layers.length !== rawLayers.length)) {
+    return null;
+  }
+  const width = asPositiveNumber(rawDocument.width, DEFAULT_CANVAS_DOCUMENT_WIDTH);
+  const height = asPositiveNumber(rawDocument.height, DEFAULT_CANVAS_DOCUMENT_HEIGHT);
+  const bbox = isRecord(rawDocument.bbox) ? rawDocument.bbox : {};
+  return {
+    background:
+      rawDocument.background === 'transparent' || isRecord(rawDocument.background)
+        ? (rawDocument.background as CanvasDocumentContractV2['background'])
+        : 'transparent',
+    bbox: {
+      height: asPositiveNumber(bbox.height, height),
+      width: asPositiveNumber(bbox.width, width),
+      x: asNumber(bbox.x, 0),
+      y: asNumber(bbox.y, 0),
+    },
+    height,
+    layers,
+    selectedLayerId: typeof rawDocument.selectedLayerId === 'string' ? rawDocument.selectedLayerId : null,
+    version: 2,
+    width,
+  };
+};
+
+const normalizeCanvasSnapshot = (value: unknown): CanvasStateContractV2['snapshots'][number] | null => {
+  if (
+    !isRecord(value) ||
+    typeof value.id !== 'string' ||
+    typeof value.name !== 'string' ||
+    typeof value.createdAt !== 'string'
+  ) {
+    return null;
+  }
+  const document = normalizeCanvasDocumentV2(value.document, true);
+  return document ? ({ ...value, document } as CanvasStateContractV2['snapshots'][number]) : null;
+};
+
+/** Defensively re-normalizes an already-v2 canvas state (fills in anything missing without re-deriving layers). */
+const normalizeCanvasStateV2 = (canvas: Record<string, unknown>): CanvasStateContractV2 => {
+  const document = normalizeCanvasDocumentV2(canvas.document, false) ?? createEmptyCanvasDocumentV2();
+
+  return {
+    document,
+    documentRevision: asNumber(canvas.documentRevision, 0),
+    snapshots: Array.isArray(canvas.snapshots)
+      ? canvas.snapshots.flatMap((snapshot) => {
+          const normalized = normalizeCanvasSnapshot(snapshot);
+          return normalized ? [normalized] : [];
+        })
+      : [],
+    stagingArea: migrateStagingAreaToV2(canvas),
+    version: 2,
+  };
+};
+
+/**
+ * Converts unknown persisted canvas state (v1, v2, or garbage) into `CanvasStateContractV2`.
+ * Already-v2 input is normalized (defaults filled in) but not re-derived from placements.
+ */
+export const migrateCanvasStateToV2 = (canvas: unknown): CanvasStateContractV2 => {
+  if (isCanvasStateV2(canvas)) {
+    return normalizeCanvasStateV2(canvas);
+  }
+
+  const rawCanvas = isRecord(canvas) ? canvas : {};
+
+  return {
+    document: migrateDocumentToV2(rawCanvas),
+    documentRevision: 0,
+    snapshots: [],
+    stagingArea: migrateStagingAreaToV2(rawCanvas),
+    version: 2,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvasProjectMutationPort.test.ts b/invokeai/frontend/webv2/src/workbench/canvasProjectMutationPort.test.ts
new file mode 100644
index 00000000000..dfb4887392b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasProjectMutationPort.test.ts
@@ -0,0 +1,255 @@
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type {
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { createBitmapStore } from '@workbench/canvas-engine/document/bitmapStore';
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createEmptyCanvasDocumentV2 } from './canvasMigration';
+import { createCanvasProjectMutationPort } from './canvasProjectMutationPort';
+import { createWorkbenchStore } from './workbenchStore';
+
+const createDeferred = <T>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+const drainUntil = async (predicate: () => boolean, maxTicks = 50): Promise<void> => {
+  for (let tick = 0; tick < maxTicks && !predicate(); tick += 1) {
+    await Promise.resolve();
+  }
+};
+
+const layerBase = (id: string) => ({
+  blendMode: 'normal' as const,
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+});
+
+const createPaintLayer = (id: string): CanvasRasterLayerContractV2 => ({
+  ...layerBase(id),
+  source: { bitmap: null, type: 'paint' },
+  type: 'raster',
+});
+
+const createMaskLayer = (id: string): CanvasInpaintMaskLayerContract => ({
+  ...layerBase(id),
+  mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+  type: 'inpaint_mask',
+});
+
+const getLayer = (
+  store: ReturnType<typeof createWorkbenchStore>,
+  projectId: string,
+  layerId: string
+): CanvasLayerContract | undefined =>
+  store
+    .getState()
+    .projects.find((project) => project.id === projectId)
+    ?.canvas.document.layers.find((layer) => layer.id === layerId);
+
+const getPaintSource = (
+  layer: CanvasLayerContract | undefined
+): Extract<CanvasLayerSourceContract, { type: 'paint' }> | null => {
+  if (!layer) {
+    return null;
+  }
+  if (layer.type === 'raster' || layer.type === 'control') {
+    return layer.source.type === 'paint' ? layer.source : null;
+  }
+  return { bitmap: layer.mask.bitmap, offset: layer.mask.offset, type: 'paint' };
+};
+
+const setupProjects = (originLayer: CanvasLayerContract, otherLayer: CanvasLayerContract) => {
+  const store = createWorkbenchStore();
+  const originProjectId = store.getState().activeProjectId;
+  store.dispatch({
+    mutation: { document: createEmptyCanvasDocumentV2(), type: 'replaceCanvasDocument' },
+    projectId: originProjectId,
+    type: 'applyCanvasProjectMutation',
+  });
+  store.dispatch({
+    mutation: { layer: originLayer, type: 'addCanvasLayer' },
+    projectId: originProjectId,
+    type: 'applyCanvasProjectMutation',
+  });
+  store.dispatch({ type: 'createProject' });
+  const otherProjectId = store.getState().activeProjectId;
+  store.dispatch({
+    mutation: { document: createEmptyCanvasDocumentV2(), type: 'replaceCanvasDocument' },
+    projectId: otherProjectId,
+    type: 'applyCanvasProjectMutation',
+  });
+  store.dispatch({
+    mutation: { layer: otherLayer, type: 'addCanvasLayer' },
+    projectId: otherProjectId,
+    type: 'applyCanvasProjectMutation',
+  });
+  store.dispatch({ projectId: originProjectId, type: 'switchProject' });
+  return { originProjectId, otherProjectId, store };
+};
+
+const beginUpload = (
+  store: ReturnType<typeof createWorkbenchStore>,
+  projectId: string,
+  layerId: string,
+  isMask = false,
+  sourceReaders?: {
+    authoritative?: (id: string) => CanvasLayerSourceContract | null;
+    mirrored?: (id: string) => CanvasLayerSourceContract | null;
+  }
+) => {
+  const uploaded = createDeferred<{ height: number; imageName: string; width: number }>();
+  const uploadImage = vi.fn(() => uploaded.promise);
+  const surface: RasterSurface = createTestStubRasterBackend().createSurface(8, 8);
+  const port = createCanvasProjectMutationPort(store, projectId);
+  const onError = vi.fn();
+  const bitmapStore = createBitmapStore({
+    debounceMs: 60_000,
+    dispatch: port.dispatch,
+    dispatchBitmap: isMask
+      ? (id, bitmap, offset) =>
+          port.dispatch({
+            config: { layerType: 'inpaint_mask', mask: { bitmap, offset } },
+            id,
+            type: 'updateCanvasLayerConfig',
+          })
+      : undefined,
+    encodeSurface: () => Promise.resolve(new Blob(['pixels'], { type: 'image/png' })),
+    getAuthoritativeLayerSource: sourceReaders?.authoritative,
+    getLayerSource: sourceReaders?.mirrored ?? ((id) => getPaintSource(getLayer(store, projectId, id))),
+    getLayerSurface: () => ({ offset: { x: 3, y: 4 }, surface }),
+    hashBlob: () => Promise.resolve('pixels-hash'),
+    onError,
+    uploadImage,
+  });
+  bitmapStore.markLayerDirty(layerId);
+  const flush = bitmapStore.flushPendingUploads();
+  return { bitmapStore, flush, onError, uploadImage, uploaded };
+};
+
+describe('project-bound bitmap persistence', () => {
+  it('finishes an upload in its origin project after switching to a project with a different layer id', async () => {
+    const h = setupProjects(createPaintLayer('origin-layer'), createPaintLayer('other-layer'));
+    const upload = beginUpload(h.store, h.originProjectId, 'origin-layer');
+    await drainUntil(() => upload.uploadImage.mock.calls.length === 1);
+
+    h.store.dispatch({ projectId: h.otherProjectId, type: 'switchProject' });
+    upload.uploaded.resolve({ height: 8, imageName: 'origin-upload.png', width: 8 });
+    await upload.flush;
+
+    expect(getPaintSource(getLayer(h.store, h.originProjectId, 'origin-layer'))?.bitmap?.imageName).toBe(
+      'origin-upload.png'
+    );
+    expect(getPaintSource(getLayer(h.store, h.otherProjectId, 'other-layer'))?.bitmap).toBeNull();
+    upload.bitmapStore.dispose();
+  });
+
+  it('does not mutate a colliding layer id in the newly active project', async () => {
+    const h = setupProjects(createPaintLayer('shared-layer'), createPaintLayer('shared-layer'));
+    const upload = beginUpload(h.store, h.originProjectId, 'shared-layer');
+    await drainUntil(() => upload.uploadImage.mock.calls.length === 1);
+
+    h.store.dispatch({ projectId: h.otherProjectId, type: 'switchProject' });
+    upload.uploaded.resolve({ height: 8, imageName: 'origin-shared.png', width: 8 });
+    await upload.flush;
+
+    expect(getPaintSource(getLayer(h.store, h.originProjectId, 'shared-layer'))?.bitmap?.imageName).toBe(
+      'origin-shared.png'
+    );
+    expect(getPaintSource(getLayer(h.store, h.otherProjectId, 'shared-layer'))?.bitmap).toBeNull();
+    upload.bitmapStore.dispose();
+  });
+
+  it('routes a mask upload back to the origin project after switching projects', async () => {
+    const h = setupProjects(createMaskLayer('shared-mask'), createMaskLayer('shared-mask'));
+    const upload = beginUpload(h.store, h.originProjectId, 'shared-mask', true);
+    await drainUntil(() => upload.uploadImage.mock.calls.length === 1);
+
+    h.store.dispatch({ projectId: h.otherProjectId, type: 'switchProject' });
+    upload.uploaded.resolve({ height: 8, imageName: 'origin-mask.png', width: 8 });
+    await upload.flush;
+
+    expect(getPaintSource(getLayer(h.store, h.originProjectId, 'shared-mask'))?.bitmap?.imageName).toBe(
+      'origin-mask.png'
+    );
+    expect(getPaintSource(getLayer(h.store, h.otherProjectId, 'shared-mask'))?.bitmap).toBeNull();
+    upload.bitmapStore.dispose();
+  });
+
+  it('accepts the pending upload after switching away from and reacquiring the origin project', async () => {
+    const h = setupProjects(createPaintLayer('reacquired'), createPaintLayer('other'));
+    const upload = beginUpload(h.store, h.originProjectId, 'reacquired');
+    await drainUntil(() => upload.uploadImage.mock.calls.length === 1);
+
+    h.store.dispatch({ projectId: h.otherProjectId, type: 'switchProject' });
+    h.store.dispatch({ projectId: h.originProjectId, type: 'switchProject' });
+    upload.uploaded.resolve({ height: 8, imageName: 'reacquired.png', width: 8 });
+    await upload.flush;
+
+    expect(getPaintSource(getLayer(h.store, h.originProjectId, 'reacquired'))?.bitmap?.imageName).toBe(
+      'reacquired.png'
+    );
+    upload.bitmapStore.dispose();
+  });
+
+  it('treats a project-bound bitmap commit as accepted when a subscriber throws after the reducer lands it', async () => {
+    const h = setupProjects(createPaintLayer('subscriber-throw'), createPaintLayer('other'));
+    let mirroredSource = getPaintSource(getLayer(h.store, h.originProjectId, 'subscriber-throw'));
+    const unsubscribe = h.store.subscribe(() => {
+      throw new Error('subscriber failed after commit');
+    });
+    const unsubscribeMirror = h.store.subscribe(() => {
+      mirroredSource = getPaintSource(getLayer(h.store, h.originProjectId, 'subscriber-throw'));
+    });
+    const upload = beginUpload(h.store, h.originProjectId, 'subscriber-throw', false, {
+      authoritative: (id) => getPaintSource(getLayer(h.store, h.originProjectId, id)),
+      mirrored: () => mirroredSource,
+    });
+    await drainUntil(() => upload.uploadImage.mock.calls.length === 1);
+
+    upload.uploaded.resolve({ height: 8, imageName: 'landed-before-subscriber-throw.png', width: 8 });
+    await expect(upload.flush).resolves.toBeUndefined();
+    await expect(upload.bitmapStore.flushPendingUploads()).resolves.toBeUndefined();
+
+    expect(getPaintSource(getLayer(h.store, h.originProjectId, 'subscriber-throw'))).toMatchObject({
+      bitmap: { imageName: 'landed-before-subscriber-throw.png' },
+      offset: { x: 3, y: 4 },
+    });
+    expect(upload.uploadImage).toHaveBeenCalledOnce();
+    expect(upload.onError).not.toHaveBeenCalled();
+    expect(mirroredSource?.bitmap).toBeNull();
+    unsubscribeMirror();
+    unsubscribe();
+    upload.bitmapStore.dispose();
+  });
+
+  it('treats project deletion during upload as terminal removal', async () => {
+    const h = setupProjects(createPaintLayer('deleted-project-layer'), createPaintLayer('survivor'));
+    const upload = beginUpload(h.store, h.originProjectId, 'deleted-project-layer');
+    await drainUntil(() => upload.uploadImage.mock.calls.length === 1);
+
+    h.store.dispatch({ projectId: h.otherProjectId, type: 'switchProject' });
+    h.store.dispatch({ projectId: h.originProjectId, type: 'closeProject' });
+    upload.uploaded.resolve({ height: 8, imageName: 'orphaned.png', width: 8 });
+    await upload.flush;
+    await upload.bitmapStore.flushPendingUploads();
+
+    expect(h.store.getState().projects.some((project) => project.id === h.originProjectId)).toBe(false);
+    expect(getPaintSource(getLayer(h.store, h.otherProjectId, 'survivor'))?.bitmap).toBeNull();
+    expect(upload.uploadImage).toHaveBeenCalledOnce();
+    upload.bitmapStore.dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvasProjectMutationPort.ts b/invokeai/frontend/webv2/src/workbench/canvasProjectMutationPort.ts
new file mode 100644
index 00000000000..bcab928703f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasProjectMutationPort.ts
@@ -0,0 +1,30 @@
+import type { CanvasProjectMutation } from './canvasProjectMutations';
+import type { CanvasStateContractV2 } from './types';
+import type { WorkbenchStore } from './workbenchStore';
+
+export interface CanvasProjectMutationPort {
+  getCanvasState(): CanvasStateContractV2 | null;
+  subscribe(listener: () => void): () => void;
+  dispatch(mutation: CanvasProjectMutation): boolean;
+}
+
+export const createCanvasProjectMutationPort = (
+  store: Pick<WorkbenchStore, 'dispatch' | 'getState' | 'subscribe'>,
+  projectId: string
+): CanvasProjectMutationPort => {
+  const getCanvasState = (): CanvasStateContractV2 | null =>
+    store.getState().projects.find((project) => project.id === projectId)?.canvas ?? null;
+
+  return {
+    dispatch: (mutation) => {
+      const before = getCanvasState();
+      if (!before) {
+        return false;
+      }
+      store.dispatch({ mutation, projectId, type: 'applyCanvasProjectMutation' });
+      return getCanvasState() !== before;
+    },
+    getCanvasState,
+    subscribe: store.subscribe,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvasProjectMutations.ts b/invokeai/frontend/webv2/src/workbench/canvasProjectMutations.ts
new file mode 100644
index 00000000000..c8b54b290b0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasProjectMutations.ts
@@ -0,0 +1,727 @@
+import type {
+  CanvasAdjustmentsContract,
+  CanvasControlAdapterContract,
+  CanvasControlLayerContract,
+  CanvasDocumentContractV2,
+  CanvasLayerBaseContract,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+  CanvasMaskContract,
+  CanvasRasterLayerContractV2,
+  CanvasRegionalGuidanceLayerContract,
+  ProjectEvent,
+  CanvasStagingAreaContractV2,
+  CanvasStateContractV2,
+  Project,
+} from './types';
+
+import { normalizeCanvasDocumentControlAdapters } from './canvasMigration';
+import {
+  getCanvasStagingCandidateFingerprint,
+  getCanvasStagingSlotCount,
+  getCanvasStagingSlots,
+} from './canvasStagingView';
+
+export type CanvasLayerBasePatch = Partial<
+  Pick<CanvasLayerBaseContract, 'name' | 'isEnabled' | 'isLocked' | 'opacity' | 'blendMode'>
+> & { transform?: Partial<CanvasLayerBaseContract['transform']> };
+
+export type CanvasLayerConfigPatch =
+  | {
+      layerType: 'raster';
+      adjustments?: CanvasAdjustmentsContract;
+      isTransparencyLocked?: boolean;
+      filter?: CanvasRasterLayerContractV2['filter'];
+    }
+  | {
+      layerType: 'control';
+      adapter?: Partial<CanvasControlAdapterContract>;
+      withTransparencyEffect?: boolean;
+      filter?: CanvasControlLayerContract['filter'];
+    }
+  | {
+      layerType: 'regional_guidance';
+      mask?: Partial<CanvasMaskContract>;
+      positivePrompt?: string | null;
+      negativePrompt?: string | null;
+      autoNegative?: boolean;
+      referenceImages?: CanvasRegionalGuidanceLayerContract['referenceImages'];
+    }
+  | { layerType: 'inpaint_mask'; mask?: Partial<CanvasMaskContract>; noiseLevel?: number; denoiseLimit?: number };
+
+export type CanvasProjectMutation =
+  | {
+      type: 'commitStagedImage';
+      candidateFingerprint: string;
+      event: ProjectEvent;
+      layer: CanvasRasterLayerContractV2;
+      selectedImageIndex: number;
+    }
+  | {
+      type: 'rollbackStagedImageCommit';
+      event: ProjectEvent;
+      layer: CanvasRasterLayerContractV2;
+      selectedLayerId: string | null;
+      stagingArea: CanvasStagingAreaContractV2;
+    }
+  | { type: 'setStagedImageIndex'; imageIndex: number }
+  | { type: 'cycleStagedImage'; direction: -1 | 1 }
+  | { type: 'discardSelectedStagedImage' }
+  | { type: 'discardAllStagedImages' }
+  | { type: 'toggleCanvasStagingVisibility' }
+  | { type: 'toggleCanvasStagingThumbnailsVisibility' }
+  | { type: 'clearCanvasStaging' }
+  | { type: 'addCanvasLayer'; layer: CanvasLayerContract; index?: number }
+  | {
+      type: 'applyCanvasLayerStackMutation';
+      add?: { index: number; layers: readonly CanvasLayerContract[] };
+      removeIds?: readonly string[];
+      enabledUpdates: readonly { id: string; isEnabled: boolean }[];
+      selectedLayerId: string | null;
+    }
+  | { type: 'removeCanvasLayers'; ids: string[] }
+  | { type: 'duplicateCanvasLayer'; sourceId: string; newId: string }
+  | { type: 'reorderCanvasLayers'; orderedIds: string[] }
+  | { type: 'updateCanvasLayer'; id: string; patch: CanvasLayerBasePatch }
+  | { type: 'replaceCanvasLayer'; layerId: string; layer: CanvasLayerContract }
+  | { type: 'setCanvasLayersEnabled'; updates: readonly { id: string; isEnabled: boolean }[] }
+  | { type: 'updateCanvasLayerSource'; id: string; source: CanvasLayerSourceContract }
+  | { type: 'updateCanvasLayerConfig'; id: string; config: CanvasLayerConfigPatch }
+  | { type: 'convertCanvasLayer'; id: string; targetType: CanvasLayerContract['type']; layer: CanvasLayerContract }
+  | {
+      type: 'mergeCanvasLayersDown';
+      upperLayerId: string;
+      source: Extract<CanvasLayerSourceContract, { type: 'paint' }>;
+    }
+  | { type: 'setCanvasBbox'; bbox: CanvasDocumentContractV2['bbox'] }
+  | { type: 'setCanvasSelectedLayer'; id: string | null }
+  | { type: 'resizeCanvasDocument'; width: number; height: number; offsetX?: number; offsetY?: number }
+  | { type: 'replaceCanvasDocument'; document: CanvasDocumentContractV2 }
+  | { type: 'saveCanvasSnapshot'; id: string; name: string; createdAt: string }
+  | { type: 'restoreCanvasSnapshot'; snapshotId: string }
+  | { type: 'deleteCanvasSnapshot'; snapshotId: string }
+  | { type: 'setCanvasStagingAutoSwitch'; mode: CanvasStagingAreaContractV2['autoSwitchMode'] };
+
+const CANVAS_PROJECT_MUTATION_TYPES: ReadonlySet<string> = new Set<CanvasProjectMutation['type']>([
+  'commitStagedImage',
+  'rollbackStagedImageCommit',
+  'addCanvasLayer',
+  'applyCanvasLayerStackMutation',
+  'clearCanvasStaging',
+  'convertCanvasLayer',
+  'cycleStagedImage',
+  'deleteCanvasSnapshot',
+  'discardAllStagedImages',
+  'discardSelectedStagedImage',
+  'duplicateCanvasLayer',
+  'mergeCanvasLayersDown',
+  'removeCanvasLayers',
+  'reorderCanvasLayers',
+  'replaceCanvasDocument',
+  'replaceCanvasLayer',
+  'resizeCanvasDocument',
+  'restoreCanvasSnapshot',
+  'saveCanvasSnapshot',
+  'setCanvasBbox',
+  'setCanvasLayersEnabled',
+  'setCanvasSelectedLayer',
+  'setCanvasStagingAutoSwitch',
+  'setStagedImageIndex',
+  'toggleCanvasStagingThumbnailsVisibility',
+  'toggleCanvasStagingVisibility',
+  'updateCanvasLayer',
+  'updateCanvasLayerConfig',
+  'updateCanvasLayerSource',
+]);
+
+export const isCanvasProjectMutation = (value: { type: string }): value is CanvasProjectMutation =>
+  CANVAS_PROJECT_MUTATION_TYPES.has(value.type);
+
+type CanvasLayers = CanvasDocumentContractV2['layers'];
+
+const layerExists = (layers: CanvasLayers, id: string): boolean => layers.some((layer) => layer.id === id);
+
+const AUTO_LAYER_NAME_PATTERN = /^Layer (\d+)$/;
+
+export const nextLayerName = (existingNames: readonly string[]): string => {
+  const used = new Set<number>();
+  for (const name of existingNames) {
+    const match = AUTO_LAYER_NAME_PATTERN.exec(name.trim());
+    if (match) {
+      const n = Number(match[1]);
+      if (Number.isInteger(n) && n > 0) {
+        used.add(n);
+      }
+    }
+  }
+  let n = 1;
+  while (used.has(n)) {
+    n += 1;
+  }
+  return `Layer ${n}`;
+};
+
+const repairSelectedLayerId = (document: CanvasDocumentContractV2): CanvasDocumentContractV2 =>
+  document.selectedLayerId === null || layerExists(document.layers, document.selectedLayerId)
+    ? document
+    : { ...document, selectedLayerId: document.layers[0]?.id ?? null };
+
+const setCanvasDocument = (project: Project, document: CanvasDocumentContractV2): Project =>
+  document === project.canvas.document ? project : { ...project, canvas: { ...project.canvas, document } };
+
+const updateCanvasDocument = (
+  project: Project,
+  update: (document: CanvasDocumentContractV2) => CanvasDocumentContractV2
+): Project => setCanvasDocument(project, update(project.canvas.document));
+
+const setCanvasState = (project: Project, canvas: CanvasStateContractV2): Project =>
+  canvas === project.canvas ? project : { ...project, canvas };
+
+const mapCanvasLayer = (
+  document: CanvasDocumentContractV2,
+  id: string,
+  update: (layer: CanvasLayerContract) => CanvasLayerContract
+): CanvasDocumentContractV2 => {
+  let changed = false;
+  const layers = document.layers.map((layer) => {
+    if (layer.id !== id) {
+      return layer;
+    }
+    const next = update(layer);
+    changed ||= next !== layer;
+    return next;
+  });
+  return changed ? { ...document, layers } : document;
+};
+
+const setCanvasLayersEnabled = (
+  document: CanvasDocumentContractV2,
+  updates: readonly { id: string; isEnabled: boolean }[]
+): CanvasDocumentContractV2 => {
+  const targets = new Map(updates.map((update) => [update.id, update.isEnabled]));
+  let changed = false;
+  const layers = document.layers.map((layer) => {
+    const isEnabled = targets.get(layer.id);
+    if (isEnabled === undefined || isEnabled === layer.isEnabled) {
+      return layer;
+    }
+    changed = true;
+    return { ...layer, isEnabled };
+  });
+  return changed ? { ...document, layers } : document;
+};
+
+const applyLayerStackMutation = (
+  document: CanvasDocumentContractV2,
+  mutation: Extract<CanvasProjectMutation, { type: 'applyCanvasLayerStackMutation' }>
+): CanvasDocumentContractV2 => {
+  const currentIds = new Set(document.layers.map((layer) => layer.id));
+  if (mutation.add && (mutation.removeIds?.length ?? 0) > 0) {
+    return document;
+  }
+  const removeIds = new Set(mutation.removeIds ?? []);
+  if ([...removeIds].some((id) => !currentIds.has(id))) {
+    return document;
+  }
+  const projectedIds = new Set(currentIds);
+  for (const id of removeIds) {
+    projectedIds.delete(id);
+  }
+  if (mutation.add) {
+    for (const layer of mutation.add.layers) {
+      if (projectedIds.has(layer.id)) {
+        return document;
+      }
+      projectedIds.add(layer.id);
+    }
+  }
+  if (
+    mutation.enabledUpdates.some((update) => !projectedIds.has(update.id)) ||
+    (mutation.selectedLayerId !== null && !projectedIds.has(mutation.selectedLayerId))
+  ) {
+    return document;
+  }
+  let layers = document.layers;
+  let changed = false;
+  if (mutation.add?.layers.length) {
+    const index = Math.min(Math.max(0, Math.round(mutation.add.index)), layers.length);
+    layers = [...layers.slice(0, index), ...mutation.add.layers, ...layers.slice(index)];
+    changed = true;
+  }
+  if (removeIds.size > 0) {
+    layers = layers.filter((layer) => !removeIds.has(layer.id));
+    changed = true;
+  }
+  const enabledById = new Map(mutation.enabledUpdates.map((update) => [update.id, update.isEnabled]));
+  let enabledChanged = false;
+  const nextLayers = layers.map((layer) => {
+    const isEnabled = enabledById.get(layer.id);
+    if (isEnabled === undefined || isEnabled === layer.isEnabled) {
+      return layer;
+    }
+    enabledChanged = true;
+    changed = true;
+    return { ...layer, isEnabled };
+  });
+  if (enabledChanged) {
+    layers = nextLayers;
+  }
+  changed ||= document.selectedLayerId !== mutation.selectedLayerId;
+  return changed ? { ...document, layers, selectedLayerId: mutation.selectedLayerId } : document;
+};
+
+const addLayer = (document: CanvasDocumentContractV2, layer: CanvasLayerContract, index = 0) => {
+  const insertIndex = Math.min(Math.max(0, Math.round(index)), document.layers.length);
+  return {
+    ...document,
+    layers: [...document.layers.slice(0, insertIndex), layer, ...document.layers.slice(insertIndex)],
+    selectedLayerId: layer.id,
+  };
+};
+
+const removeLayers = (document: CanvasDocumentContractV2, ids: readonly string[]): CanvasDocumentContractV2 => {
+  const removed = new Set(ids);
+  const layers = document.layers.filter((layer) => !removed.has(layer.id));
+  if (layers.length === document.layers.length) {
+    return document;
+  }
+  let selectedLayerId = document.selectedLayerId;
+  if (selectedLayerId !== null && removed.has(selectedLayerId)) {
+    const removedIndex = document.layers.findIndex((layer) => layer.id === selectedLayerId);
+    const remainingIds = new Set(layers.map((layer) => layer.id));
+    selectedLayerId = null;
+    for (let index = removedIndex + 1; index < document.layers.length; index += 1) {
+      const id = document.layers[index]?.id;
+      if (id && remainingIds.has(id)) {
+        selectedLayerId = id;
+        break;
+      }
+    }
+    if (selectedLayerId === null) {
+      for (let index = removedIndex - 1; index >= 0; index -= 1) {
+        const id = document.layers[index]?.id;
+        if (id && remainingIds.has(id)) {
+          selectedLayerId = id;
+          break;
+        }
+      }
+    }
+  }
+  return { ...document, layers, selectedLayerId };
+};
+
+const duplicateLayer = (document: CanvasDocumentContractV2, sourceId: string, newId: string) => {
+  const index = document.layers.findIndex((layer) => layer.id === sourceId);
+  if (index === -1) {
+    return document;
+  }
+  const source = document.layers[index] as CanvasLayerContract;
+  const duplicate = structuredClone(source);
+  duplicate.id = newId;
+  duplicate.name = `${source.name} copy`;
+  return {
+    ...document,
+    layers: [...document.layers.slice(0, index), duplicate, ...document.layers.slice(index)],
+    selectedLayerId: newId,
+  };
+};
+
+const reorderLayers = (document: CanvasDocumentContractV2, orderedIds: readonly string[]) => {
+  if (orderedIds.length !== document.layers.length || new Set(orderedIds).size !== orderedIds.length) {
+    return document;
+  }
+  const byId = new Map(document.layers.map((layer) => [layer.id, layer]));
+  const layers: CanvasLayers = [];
+  for (const id of orderedIds) {
+    const layer = byId.get(id);
+    if (!layer) {
+      return document;
+    }
+    layers.push(layer);
+  }
+  return { ...document, layers };
+};
+
+const patchLayer = (layer: CanvasLayerContract, patch: CanvasLayerBasePatch): CanvasLayerContract => {
+  const { transform, ...rest } = patch;
+  return { ...layer, ...rest, transform: transform ? { ...layer.transform, ...transform } : layer.transform };
+};
+
+const patchLayerConfig = (layer: CanvasLayerContract, config: CanvasLayerConfigPatch): CanvasLayerContract => {
+  if (layer.type !== config.layerType) {
+    return layer;
+  }
+  if (layer.type === 'raster' && config.layerType === 'raster') {
+    return {
+      ...layer,
+      ...(Object.hasOwn(config, 'adjustments') ? { adjustments: config.adjustments } : {}),
+      ...(Object.hasOwn(config, 'isTransparencyLocked') ? { isTransparencyLocked: config.isTransparencyLocked } : {}),
+      ...(Object.hasOwn(config, 'filter') ? { filter: config.filter } : {}),
+    };
+  }
+  if (layer.type === 'control' && config.layerType === 'control') {
+    return {
+      ...layer,
+      ...(config.adapter ? { adapter: { ...layer.adapter, ...config.adapter } } : {}),
+      ...(Object.hasOwn(config, 'withTransparencyEffect')
+        ? { withTransparencyEffect: config.withTransparencyEffect }
+        : {}),
+      ...(Object.hasOwn(config, 'filter') ? { filter: config.filter } : {}),
+    };
+  }
+  if (layer.type === 'regional_guidance' && config.layerType === 'regional_guidance') {
+    return {
+      ...layer,
+      ...(config.mask ? { mask: { ...layer.mask, ...config.mask } } : {}),
+      ...(Object.hasOwn(config, 'positivePrompt') ? { positivePrompt: config.positivePrompt } : {}),
+      ...(Object.hasOwn(config, 'negativePrompt') ? { negativePrompt: config.negativePrompt } : {}),
+      ...(Object.hasOwn(config, 'autoNegative') ? { autoNegative: config.autoNegative } : {}),
+      ...(Object.hasOwn(config, 'referenceImages') ? { referenceImages: config.referenceImages } : {}),
+    };
+  }
+  if (layer.type === 'inpaint_mask' && config.layerType === 'inpaint_mask') {
+    return {
+      ...layer,
+      ...(config.mask ? { mask: { ...layer.mask, ...config.mask } } : {}),
+      ...(Object.hasOwn(config, 'noiseLevel') ? { noiseLevel: config.noiseLevel } : {}),
+      ...(Object.hasOwn(config, 'denoiseLimit') ? { denoiseLimit: config.denoiseLimit } : {}),
+    };
+  }
+  return layer;
+};
+
+const clampBbox = (bbox: CanvasDocumentContractV2['bbox'], width: number, height: number) => {
+  const clampedWidth = Math.min(Math.max(1, Math.round(bbox.width)), width);
+  const clampedHeight = Math.min(Math.max(1, Math.round(bbox.height)), height);
+  return {
+    height: clampedHeight,
+    width: clampedWidth,
+    x: Math.min(Math.max(0, Math.round(bbox.x)), width - clampedWidth),
+    y: Math.min(Math.max(0, Math.round(bbox.y)), height - clampedHeight),
+  };
+};
+
+const clearStagingArea = (stagingArea: CanvasStateContractV2['stagingArea']) => ({
+  ...stagingArea,
+  isVisible: false,
+  pendingImageIds: [],
+  pendingImages: [],
+  selectedImageIndex: 0,
+  sourceQueueItemId: undefined,
+});
+
+const clampStagedImageIndex = (imageIndex: number, slotCount: number): number =>
+  Math.min(Math.max(0, slotCount - 1), Math.max(0, imageIndex));
+
+const selectedCandidate = (project: Project) => {
+  const slot = getCanvasStagingSlots(project.canvas, project.queue.items)[
+    project.canvas.stagingArea.selectedImageIndex
+  ];
+  return slot?.kind === 'candidate' ? slot.candidate : undefined;
+};
+
+export const applyCanvasProjectMutation = (project: Project, mutation: CanvasProjectMutation): Project => {
+  switch (mutation.type) {
+    case 'commitStagedImage': {
+      const stagedImage = selectedCandidate(project);
+      if (
+        project.canvas.stagingArea.selectedImageIndex !== mutation.selectedImageIndex ||
+        !stagedImage ||
+        getCanvasStagingCandidateFingerprint(stagedImage) !== mutation.candidateFingerprint
+      ) {
+        return project;
+      }
+      const { layer } = mutation;
+      if (project.canvas.document.layers.some((candidate) => candidate.id === layer.id)) {
+        return project;
+      }
+      return {
+        ...project,
+        canvas: {
+          ...project.canvas,
+          document: {
+            ...project.canvas.document,
+            layers: [layer, ...project.canvas.document.layers],
+            selectedLayerId: layer.id,
+          },
+          stagingArea: clearStagingArea(project.canvas.stagingArea),
+        },
+        events: [mutation.event, ...project.events],
+      };
+    }
+    case 'rollbackStagedImageCommit': {
+      if (
+        project.canvas.document.selectedLayerId !== mutation.layer.id ||
+        project.canvas.document.layers[0] !== mutation.layer ||
+        project.events[0] !== mutation.event ||
+        project.canvas.stagingArea.pendingImages.length !== 0
+      ) {
+        return project;
+      }
+      return {
+        ...project,
+        canvas: {
+          ...project.canvas,
+          document: {
+            ...project.canvas.document,
+            layers: project.canvas.document.layers.slice(1),
+            selectedLayerId: mutation.selectedLayerId,
+          },
+          stagingArea: mutation.stagingArea,
+        },
+        events: project.events.slice(1),
+      };
+    }
+    case 'setStagedImageIndex': {
+      const selectedImageIndex = clampStagedImageIndex(
+        mutation.imageIndex,
+        getCanvasStagingSlotCount(project.canvas, project.queue.items)
+      );
+      return selectedImageIndex === project.canvas.stagingArea.selectedImageIndex
+        ? project
+        : {
+            ...project,
+            canvas: {
+              ...project.canvas,
+              stagingArea: { ...project.canvas.stagingArea, selectedImageIndex },
+            },
+          };
+    }
+    case 'cycleStagedImage': {
+      const count = getCanvasStagingSlotCount(project.canvas, project.queue.items);
+      const current = project.canvas.stagingArea.selectedImageIndex;
+      const selectedImageIndex = count < 2 ? 0 : (current + mutation.direction + count) % count;
+      return selectedImageIndex === current
+        ? project
+        : {
+            ...project,
+            canvas: {
+              ...project.canvas,
+              stagingArea: { ...project.canvas.stagingArea, selectedImageIndex },
+            },
+          };
+    }
+    case 'discardSelectedStagedImage': {
+      const selected = selectedCandidate(project);
+      if (!selected) {
+        return project;
+      }
+      const pendingImages = project.canvas.stagingArea.pendingImages.filter(
+        (image) => image.sourceQueueItemId !== selected.sourceQueueItemId || image.imageName !== selected.imageName
+      );
+      const canvas = {
+        ...project.canvas,
+        stagingArea: {
+          ...project.canvas.stagingArea,
+          pendingImageIds: pendingImages.map((image) => image.imageName),
+          pendingImages,
+        },
+      };
+      const slotCount = getCanvasStagingSlotCount(canvas, project.queue.items);
+      return {
+        ...project,
+        canvas: {
+          ...canvas,
+          stagingArea: {
+            ...canvas.stagingArea,
+            isVisible: slotCount > 0 && canvas.stagingArea.isVisible,
+            selectedImageIndex: clampStagedImageIndex(canvas.stagingArea.selectedImageIndex, slotCount),
+            sourceQueueItemId: pendingImages.length > 0 ? canvas.stagingArea.sourceQueueItemId : undefined,
+          },
+        },
+      };
+    }
+    case 'discardAllStagedImages': {
+      const canvas = { ...project.canvas, stagingArea: clearStagingArea(project.canvas.stagingArea) };
+      return {
+        ...project,
+        canvas: {
+          ...canvas,
+          stagingArea: {
+            ...canvas.stagingArea,
+            isVisible: getCanvasStagingSlotCount(canvas, project.queue.items) > 0,
+          },
+        },
+      };
+    }
+    case 'toggleCanvasStagingVisibility':
+      return getCanvasStagingSlotCount(project.canvas, project.queue.items) === 0
+        ? project
+        : {
+            ...project,
+            canvas: {
+              ...project.canvas,
+              stagingArea: {
+                ...project.canvas.stagingArea,
+                isVisible: !project.canvas.stagingArea.isVisible,
+              },
+            },
+          };
+    case 'toggleCanvasStagingThumbnailsVisibility':
+      return getCanvasStagingSlotCount(project.canvas, project.queue.items) === 0
+        ? project
+        : {
+            ...project,
+            canvas: {
+              ...project.canvas,
+              stagingArea: {
+                ...project.canvas.stagingArea,
+                areThumbnailsVisible: !project.canvas.stagingArea.areThumbnailsVisible,
+              },
+            },
+          };
+    case 'clearCanvasStaging':
+      return { ...project, canvas: { ...project.canvas, stagingArea: clearStagingArea(project.canvas.stagingArea) } };
+    case 'addCanvasLayer':
+      return updateCanvasDocument(project, (document) => addLayer(document, mutation.layer, mutation.index));
+    case 'applyCanvasLayerStackMutation':
+      return updateCanvasDocument(project, (document) => applyLayerStackMutation(document, mutation));
+    case 'removeCanvasLayers':
+      return updateCanvasDocument(project, (document) => removeLayers(document, mutation.ids));
+    case 'duplicateCanvasLayer':
+      return updateCanvasDocument(project, (document) => duplicateLayer(document, mutation.sourceId, mutation.newId));
+    case 'reorderCanvasLayers':
+      return updateCanvasDocument(project, (document) => reorderLayers(document, mutation.orderedIds));
+    case 'updateCanvasLayer':
+      return updateCanvasDocument(project, (document) =>
+        mapCanvasLayer(document, mutation.id, (layer) => patchLayer(layer, mutation.patch))
+      );
+    case 'replaceCanvasLayer':
+      return updateCanvasDocument(project, (document) =>
+        mapCanvasLayer(document, mutation.layerId, () => mutation.layer)
+      );
+    case 'setCanvasLayersEnabled':
+      return updateCanvasDocument(project, (document) => setCanvasLayersEnabled(document, mutation.updates));
+    case 'updateCanvasLayerSource':
+      return updateCanvasDocument(project, (document) =>
+        mapCanvasLayer(document, mutation.id, (layer) =>
+          layer.type === 'raster' || layer.type === 'control' ? { ...layer, source: mutation.source } : layer
+        )
+      );
+    case 'updateCanvasLayerConfig':
+      return updateCanvasDocument(project, (document) =>
+        mapCanvasLayer(document, mutation.id, (layer) => patchLayerConfig(layer, mutation.config))
+      );
+    case 'convertCanvasLayer': {
+      if (mutation.layer.type !== mutation.targetType || !layerExists(project.canvas.document.layers, mutation.id)) {
+        return project;
+      }
+      const converted = structuredClone(mutation.layer);
+      converted.id = mutation.id;
+      return updateCanvasDocument(project, (document) => mapCanvasLayer(document, mutation.id, () => converted));
+    }
+    case 'mergeCanvasLayersDown': {
+      const document = project.canvas.document;
+      const upperIndex = document.layers.findIndex((layer) => layer.id === mutation.upperLayerId);
+      const below = upperIndex === -1 ? undefined : document.layers[upperIndex + 1];
+      if (!below) {
+        return project;
+      }
+      const merged: CanvasRasterLayerContractV2 = {
+        blendMode: below.blendMode,
+        id: below.id,
+        isEnabled: below.isEnabled,
+        isLocked: below.isLocked,
+        name: below.name,
+        opacity: below.opacity,
+        source: mutation.source,
+        transform: below.transform,
+        type: 'raster',
+      };
+      return setCanvasDocument(project, {
+        ...document,
+        layers: document.layers
+          .filter((_, index) => index !== upperIndex)
+          .map((layer) => (layer.id === below.id ? merged : layer)),
+        selectedLayerId: document.selectedLayerId === mutation.upperLayerId ? below.id : document.selectedLayerId,
+      });
+    }
+    case 'setCanvasBbox':
+      return updateCanvasDocument(project, (document) => ({
+        ...document,
+        bbox: {
+          height: Math.max(1, Math.round(mutation.bbox.height)),
+          width: Math.max(1, Math.round(mutation.bbox.width)),
+          x: Math.round(mutation.bbox.x),
+          y: Math.round(mutation.bbox.y),
+        },
+      }));
+    case 'setCanvasSelectedLayer':
+      return updateCanvasDocument(project, (document) =>
+        mutation.id !== null && !layerExists(document.layers, mutation.id)
+          ? document
+          : document.selectedLayerId === mutation.id
+            ? document
+            : { ...document, selectedLayerId: mutation.id }
+      );
+    case 'resizeCanvasDocument': {
+      const width = Math.max(1, Math.round(mutation.width));
+      const height = Math.max(1, Math.round(mutation.height));
+      const offsetX = mutation.offsetX ?? 0;
+      const offsetY = mutation.offsetY ?? 0;
+      return updateCanvasDocument(project, (document) => ({
+        ...document,
+        bbox: clampBbox(
+          { ...document.bbox, x: document.bbox.x + offsetX, y: document.bbox.y + offsetY },
+          width,
+          height
+        ),
+        height,
+        layers:
+          offsetX === 0 && offsetY === 0
+            ? document.layers
+            : document.layers.map((layer) => ({
+                ...layer,
+                transform: { ...layer.transform, x: layer.transform.x + offsetX, y: layer.transform.y + offsetY },
+              })),
+        width,
+      }));
+    }
+    case 'replaceCanvasDocument':
+      return setCanvasState(project, {
+        ...project.canvas,
+        document: repairSelectedLayerId(normalizeCanvasDocumentControlAdapters(structuredClone(mutation.document))),
+        documentRevision: project.canvas.documentRevision + 1,
+        stagingArea: clearStagingArea(project.canvas.stagingArea),
+      });
+    case 'saveCanvasSnapshot':
+      return setCanvasState(project, {
+        ...project.canvas,
+        snapshots: [
+          ...project.canvas.snapshots,
+          {
+            createdAt: mutation.createdAt,
+            document: normalizeCanvasDocumentControlAdapters(structuredClone(project.canvas.document)),
+            id: mutation.id,
+            name: mutation.name,
+          },
+        ],
+      });
+    case 'restoreCanvasSnapshot': {
+      const snapshot = project.canvas.snapshots.find((entry) => entry.id === mutation.snapshotId);
+      return snapshot
+        ? setCanvasState(project, {
+            ...project.canvas,
+            document: repairSelectedLayerId(normalizeCanvasDocumentControlAdapters(structuredClone(snapshot.document))),
+            documentRevision: project.canvas.documentRevision + 1,
+          })
+        : project;
+    }
+    case 'deleteCanvasSnapshot': {
+      const snapshots = project.canvas.snapshots.filter((entry) => entry.id !== mutation.snapshotId);
+      return snapshots.length === project.canvas.snapshots.length
+        ? project
+        : setCanvasState(project, { ...project.canvas, snapshots });
+    }
+    case 'setCanvasStagingAutoSwitch':
+      return project.canvas.stagingArea.autoSwitchMode === mutation.mode
+        ? project
+        : {
+            ...project,
+            canvas: {
+              ...project.canvas,
+              stagingArea: { ...project.canvas.stagingArea, autoSwitchMode: mutation.mode },
+            },
+          };
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/canvasStagingView.test.ts b/invokeai/frontend/webv2/src/workbench/canvasStagingView.test.ts
new file mode 100644
index 00000000000..ff75681d120
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasStagingView.test.ts
@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'vitest';
+
+import type { CanvasStagingCandidateContract, GeneratedImageContract, QueueItem, QueueItemStatus } from './types';
+
+import { createEmptyCanvasStateV2 } from './canvasMigration';
+import {
+  getCancelableCanvasStagingQueueItemId,
+  getCanvasQueuePlaceholderSlots,
+  getCanvasStagingCandidateFingerprint,
+  getCanvasStagingSlots,
+} from './canvasStagingView';
+
+const createImage = (imageName: string, sourceQueueItemId: string): GeneratedImageContract => ({
+  height: 768,
+  imageName,
+  imageUrl: `/api/v1/images/i/${imageName}/full`,
+  queuedAt: '2026-06-09T00:00:00.000Z',
+  sourceQueueItemId,
+  thumbnailUrl: `/api/v1/images/i/${imageName}/thumbnail`,
+  width: 512,
+});
+
+const createCandidate = (imageName: string, sourceQueueItemId: string): CanvasStagingCandidateContract => ({
+  ...createImage(imageName, sourceQueueItemId),
+  placement: { height: 256, opacity: 1, width: 256, x: 16, y: 24 },
+});
+
+const createBackendCandidate = (
+  imageName: string,
+  sourceQueueItemId: string,
+  sourceBackendItemId: number
+): CanvasStagingCandidateContract => ({
+  ...createCandidate(imageName, sourceQueueItemId),
+  sourceBackendItemId,
+});
+
+const createCanvas = ({
+  bbox = { height: 512, width: 512, x: 0, y: 0 },
+  revision = 0,
+  stagedImages = [],
+}: {
+  bbox?: { height: number; width: number; x: number; y: number };
+  revision?: number;
+  stagedImages?: CanvasStagingCandidateContract[];
+} = {}) => {
+  const canvas = createEmptyCanvasStateV2(1024, 1024);
+
+  return {
+    ...canvas,
+    document: { ...canvas.document, bbox },
+    documentRevision: revision,
+    stagingArea: {
+      ...canvas.stagingArea,
+      isVisible: stagedImages.length > 0,
+      pendingImageIds: stagedImages.map((image) => image.imageName),
+      pendingImages: stagedImages,
+    },
+  };
+};
+
+const createQueueItem = ({
+  backendItemIds,
+  batchCount = 1,
+  bbox = { height: 320, width: 640, x: 10, y: 12 },
+  cancelledBackendItemIds,
+  completedBackendItemIds,
+  destination = 'canvas',
+  id,
+  revision = 0,
+  status = 'pending',
+  submittedAt = '2026-06-09T00:00:00.000Z',
+}: {
+  backendItemIds?: number[];
+  batchCount?: number;
+  bbox?: { height: number; width: number; x: number; y: number };
+  cancelledBackendItemIds?: number[];
+  completedBackendItemIds?: number[];
+  destination?: 'canvas' | 'gallery';
+  id: string;
+  revision?: number;
+  status?: QueueItemStatus;
+  submittedAt?: string;
+}): QueueItem =>
+  ({
+    backendItemIds,
+    cancellable: true,
+    cancelledBackendItemIds,
+    completedBackendItemIds,
+    id,
+    snapshot: {
+      canvas: createCanvas({ bbox, revision }),
+      destination,
+      graph: { edges: [], id: 'graph', label: 'Graph', nodes: [], updatedAt: '2026-06-09T00:00:00.000Z', version: 1 },
+      sourceId: 'canvas',
+      submittedAt,
+      widgetInstances: {},
+      widgetStates: {
+        generate: { id: 'generate', label: 'Generate', values: { batchCount, height: 999, width: 999 }, version: 1 },
+      },
+    },
+    status,
+  }) as QueueItem;
+
+describe('canvas staging view', () => {
+  it('derives in-flight canvas placeholders from the submitted bbox without persisting fake images', () => {
+    const canvas = createCanvas({ revision: 2 });
+    const queueItems = [
+      createQueueItem({
+        batchCount: 2,
+        bbox: { height: 384, width: 640, x: 8, y: 9 },
+        id: 'q-pending',
+        revision: 2,
+        submittedAt: '2026-06-09T00:00:01.000Z',
+      }),
+      createQueueItem({
+        backendItemIds: [11, 12, 13],
+        bbox: { height: 256, width: 512, x: 1, y: 2 },
+        cancelledBackendItemIds: [12],
+        completedBackendItemIds: [11],
+        id: 'q-running',
+        revision: 2,
+        status: 'running',
+        submittedAt: '2026-06-09T00:00:02.000Z',
+      }),
+    ];
+
+    expect(getCanvasQueuePlaceholderSlots(canvas, queueItems)).toEqual([
+      { height: 384, id: 'q-pending:0', itemIndex: 1, kind: 'placeholder', queueItemId: 'q-pending', width: 640 },
+      { height: 384, id: 'q-pending:1', itemIndex: 2, kind: 'placeholder', queueItemId: 'q-pending', width: 640 },
+      { height: 256, id: 'q-running:2', itemIndex: 3, kind: 'placeholder', queueItemId: 'q-running', width: 512 },
+    ]);
+    expect(canvas.stagingArea.pendingImages).toEqual([]);
+  });
+
+  it('skips gallery, stale, terminal, completed, and cancelled canvas slots', () => {
+    const canvas = createCanvas({ revision: 2 });
+    const queueItems = [
+      createQueueItem({ destination: 'gallery', id: 'q-gallery', revision: 2 }),
+      createQueueItem({ id: 'q-stale', revision: 1 }),
+      createQueueItem({ id: 'q-completed', revision: 2, status: 'completed' }),
+      createQueueItem({ id: 'q-cancelled', revision: 2, status: 'cancelled' }),
+      createQueueItem({
+        backendItemIds: [11, 12],
+        cancelledBackendItemIds: [12],
+        completedBackendItemIds: [11],
+        id: 'q-no-open-slots',
+        revision: 2,
+        status: 'running',
+      }),
+    ];
+
+    expect(getCanvasQueuePlaceholderSlots(canvas, queueItems)).toEqual([]);
+  });
+
+  it('combines ready staged candidates with ephemeral placeholders in one selected slot list', () => {
+    const staged = createCandidate('ready.png', 'q-ready');
+    const canvas = createCanvas({ revision: 2, stagedImages: [staged] });
+    const queueItems = [createQueueItem({ id: 'q-pending', revision: 2 })];
+
+    expect(getCanvasStagingSlots(canvas, queueItems)).toEqual([
+      {
+        candidate: staged,
+        height: 768,
+        id: `candidate:${getCanvasStagingCandidateFingerprint(staged)}`,
+        imageName: 'ready.png',
+        kind: 'candidate',
+        queueItemId: 'q-ready',
+        width: 512,
+      },
+      { height: 320, id: 'q-pending:0', itemIndex: 1, kind: 'placeholder', queueItemId: 'q-pending', width: 640 },
+    ]);
+  });
+
+  it('orders placeholders by execution order even when local queue items are newest-first', () => {
+    const canvas = createCanvas({ revision: 2 });
+    const queueItems = [
+      createQueueItem({ id: 'q-third', revision: 2, submittedAt: '2026-06-09T00:00:03.000Z' }),
+      createQueueItem({ id: 'q-second', revision: 2, submittedAt: '2026-06-09T00:00:02.000Z' }),
+      createQueueItem({ id: 'q-first', revision: 2, submittedAt: '2026-06-09T00:00:01.000Z' }),
+    ];
+
+    expect(getCanvasQueuePlaceholderSlots(canvas, queueItems).map((slot) => slot.queueItemId)).toEqual([
+      'q-first',
+      'q-second',
+      'q-third',
+    ]);
+  });
+
+  it('interleaves completed candidates and placeholders per queue item in execution order', () => {
+    const firstCandidate = createBackendCandidate('first-result.png', 'q-first', 11);
+    const canvas = createCanvas({ revision: 2, stagedImages: [firstCandidate] });
+    const queueItems = [
+      createQueueItem({ id: 'q-second', revision: 2, submittedAt: '2026-06-09T00:00:02.000Z' }),
+      createQueueItem({
+        backendItemIds: [11, 12],
+        completedBackendItemIds: [11],
+        id: 'q-first',
+        revision: 2,
+        status: 'running',
+        submittedAt: '2026-06-09T00:00:01.000Z',
+      }),
+    ];
+
+    expect(
+      getCanvasStagingSlots(canvas, queueItems).map((slot) =>
+        slot.kind === 'candidate'
+          ? `candidate:${slot.queueItemId}:${slot.itemIndex}`
+          : `placeholder:${slot.queueItemId}:${slot.itemIndex}`
+      )
+    ).toEqual(['candidate:q-first:1', 'placeholder:q-first:2', 'placeholder:q-second:1']);
+  });
+
+  it('resolves a cancelable queue item only for placeholder slots', () => {
+    const candidate = createCandidate('ready.png', 'q-ready');
+
+    expect(
+      getCancelableCanvasStagingQueueItemId({
+        candidate,
+        height: 768,
+        id: 'candidate:q-ready:ready.png',
+        imageName: 'ready.png',
+        kind: 'candidate',
+        queueItemId: 'q-ready',
+        width: 512,
+      })
+    ).toBeNull();
+    expect(
+      getCancelableCanvasStagingQueueItemId({
+        height: 320,
+        id: 'q-pending:0',
+        itemIndex: 1,
+        kind: 'placeholder',
+        queueItemId: 'q-pending',
+        width: 640,
+      })
+    ).toBe('q-pending');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/canvasStagingView.ts b/invokeai/frontend/webv2/src/workbench/canvasStagingView.ts
new file mode 100644
index 00000000000..c9c264c7ac0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/canvasStagingView.ts
@@ -0,0 +1,261 @@
+import type { CanvasStagingCandidateContract, CanvasStateContractV2, QueueItem } from './types';
+
+import { sanitizeBatchCount } from './generation/batch';
+
+export interface CanvasQueuePlaceholderSlot {
+  height: number;
+  id: string;
+  itemIndex: number;
+  kind: 'placeholder';
+  queueItemId: string;
+  width: number;
+}
+
+export interface CanvasCandidateSlot {
+  candidate: CanvasStagingCandidateContract;
+  height: number;
+  id: string;
+  imageName: string;
+  itemIndex?: number;
+  kind: 'candidate';
+  queueItemId: string;
+  width: number;
+}
+
+export type CanvasStagingSlot = CanvasCandidateSlot | CanvasQueuePlaceholderSlot;
+
+const isActiveCanvasQueueItemForDocument = (canvas: CanvasStateContractV2, item: QueueItem): boolean =>
+  item.snapshot.destination === 'canvas' &&
+  (item.status === 'pending' || item.status === 'running') &&
+  item.snapshot.canvas.documentRevision === canvas.documentRevision;
+
+const getFiniteNumber = (value: unknown, fallback: number): number =>
+  typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+
+const getSubmittedBboxSize = (item: QueueItem): { height: number; width: number } => {
+  const { bbox } = item.snapshot.canvas.document;
+
+  return {
+    height: Math.max(1, Math.round(getFiniteNumber(bbox.height, item.snapshot.canvas.document.height))),
+    width: Math.max(1, Math.round(getFiniteNumber(bbox.width, item.snapshot.canvas.document.width))),
+  };
+};
+
+const getExpectedImageCount = (item: QueueItem): number => {
+  if (item.backendItemIds?.length) {
+    return item.backendItemIds.length;
+  }
+
+  return sanitizeBatchCount(
+    item.snapshot.generate?.values.batchCount ?? item.snapshot.widgetStates.generate?.values.batchCount
+  );
+};
+
+/** Collision-safe candidate value identity used with the selected slot index for guarded acceptance. */
+export const getCanvasStagingCandidateFingerprint = (candidate: CanvasStagingCandidateContract): string =>
+  JSON.stringify([
+    candidate.sourceQueueItemId,
+    candidate.sourceBackendItemId ?? null,
+    candidate.imageName,
+    candidate.width,
+    candidate.height,
+    candidate.placement.x,
+    candidate.placement.y,
+    candidate.placement.width,
+    candidate.placement.height,
+    candidate.placement.opacity,
+  ]);
+
+const compareQueueItemsByExecutionOrder = (left: QueueItem, right: QueueItem): number => {
+  const leftBackendItemId = left.backendItemIds?.[0];
+  const rightBackendItemId = right.backendItemIds?.[0];
+
+  if (leftBackendItemId !== undefined && rightBackendItemId !== undefined && leftBackendItemId !== rightBackendItemId) {
+    return leftBackendItemId - rightBackendItemId;
+  }
+
+  const leftSubmittedAt = Date.parse(left.snapshot.submittedAt);
+  const rightSubmittedAt = Date.parse(right.snapshot.submittedAt);
+
+  if (Number.isFinite(leftSubmittedAt) && Number.isFinite(rightSubmittedAt) && leftSubmittedAt !== rightSubmittedAt) {
+    return leftSubmittedAt - rightSubmittedAt;
+  }
+
+  return 0;
+};
+
+const getQueueItemsInExecutionOrder = (queueItems: readonly QueueItem[]): QueueItem[] =>
+  queueItems
+    .map((item, index) => ({ index, item }))
+    .sort((left, right) => compareQueueItemsByExecutionOrder(left.item, right.item) || right.index - left.index)
+    .map(({ item }) => item);
+
+const createCandidateSlot = (candidate: CanvasStagingCandidateContract, itemIndex?: number): CanvasCandidateSlot => ({
+  candidate,
+  height: candidate.height,
+  id: `candidate:${getCanvasStagingCandidateFingerprint(candidate)}`,
+  imageName: candidate.imageName,
+  ...(itemIndex === undefined ? {} : { itemIndex }),
+  kind: 'candidate',
+  queueItemId: candidate.sourceQueueItemId,
+  width: candidate.width,
+});
+
+const createPlaceholderSlot = (item: QueueItem, itemIndex: number): CanvasQueuePlaceholderSlot => {
+  const { height, width } = getSubmittedBboxSize(item);
+
+  return {
+    height,
+    id: `${item.id}:${itemIndex - 1}`,
+    itemIndex,
+    kind: 'placeholder',
+    queueItemId: item.id,
+    width,
+  };
+};
+
+export const getCanvasQueuePlaceholderSlots = (
+  canvas: CanvasStateContractV2,
+  queueItems: readonly QueueItem[]
+): CanvasQueuePlaceholderSlot[] => {
+  const placeholders: CanvasQueuePlaceholderSlot[] = [];
+
+  for (const item of getQueueItemsInExecutionOrder(queueItems)) {
+    if (!isActiveCanvasQueueItemForDocument(canvas, item)) {
+      continue;
+    }
+
+    const completedBackendItemIds = new Set(item.completedBackendItemIds ?? []);
+    const cancelledBackendItemIds = new Set(item.cancelledBackendItemIds ?? []);
+
+    if (item.backendItemIds?.length) {
+      for (let index = 0; index < item.backendItemIds.length; index += 1) {
+        const backendItemId = item.backendItemIds[index];
+
+        if (
+          backendItemId === undefined ||
+          completedBackendItemIds.has(backendItemId) ||
+          cancelledBackendItemIds.has(backendItemId)
+        ) {
+          continue;
+        }
+
+        placeholders.push(createPlaceholderSlot(item, index + 1));
+      }
+
+      continue;
+    }
+
+    for (let index = 0; index < getExpectedImageCount(item); index += 1) {
+      placeholders.push(createPlaceholderSlot(item, index + 1));
+    }
+  }
+
+  return placeholders;
+};
+
+const getCandidatesByQueueItemId = (
+  candidates: readonly CanvasStagingCandidateContract[]
+): Map<string, CanvasStagingCandidateContract[]> => {
+  const candidatesByQueueItemId = new Map<string, CanvasStagingCandidateContract[]>();
+
+  for (const candidate of candidates) {
+    const candidatesForQueueItem = candidatesByQueueItemId.get(candidate.sourceQueueItemId) ?? [];
+
+    candidatesForQueueItem.push(candidate);
+    candidatesByQueueItemId.set(candidate.sourceQueueItemId, candidatesForQueueItem);
+  }
+
+  return candidatesByQueueItemId;
+};
+
+const getCanvasStagingSlotsForQueueItem = (
+  canvas: CanvasStateContractV2,
+  item: QueueItem,
+  candidates: readonly CanvasStagingCandidateContract[]
+): CanvasStagingSlot[] => {
+  const slots: CanvasStagingSlot[] = [];
+  const remainingCandidates = [...candidates];
+  const isActive = isActiveCanvasQueueItemForDocument(canvas, item);
+  const completedBackendItemIds = new Set(item.completedBackendItemIds ?? []);
+  const cancelledBackendItemIds = new Set(item.cancelledBackendItemIds ?? []);
+
+  if (item.backendItemIds?.length) {
+    for (let index = 0; index < item.backendItemIds.length; index += 1) {
+      const backendItemId = item.backendItemIds[index];
+      const itemIndex = index + 1;
+
+      if (backendItemId === undefined) {
+        continue;
+      }
+
+      const candidateIndex = remainingCandidates.findIndex(
+        (candidate) => candidate.sourceBackendItemId === backendItemId
+      );
+
+      if (candidateIndex !== -1) {
+        const [candidate] = remainingCandidates.splice(candidateIndex, 1);
+
+        if (candidate) {
+          slots.push(createCandidateSlot(candidate, itemIndex));
+        }
+
+        continue;
+      }
+
+      if (isActive && !completedBackendItemIds.has(backendItemId) && !cancelledBackendItemIds.has(backendItemId)) {
+        slots.push(createPlaceholderSlot(item, itemIndex));
+      }
+    }
+
+    return [...slots, ...remainingCandidates.map((candidate) => createCandidateSlot(candidate))];
+  }
+
+  slots.push(...remainingCandidates.map((candidate, index) => createCandidateSlot(candidate, index + 1)));
+
+  if (!isActive) {
+    return slots;
+  }
+
+  for (let index = remainingCandidates.length; index < getExpectedImageCount(item); index += 1) {
+    slots.push(createPlaceholderSlot(item, index + 1));
+  }
+
+  return slots;
+};
+
+export const getCanvasStagingSlots = (
+  canvas: CanvasStateContractV2,
+  queueItems: readonly QueueItem[]
+): CanvasStagingSlot[] => {
+  const candidatesByQueueItemId = getCandidatesByQueueItemId(canvas.stagingArea.pendingImages);
+  const slots: CanvasStagingSlot[] = [];
+
+  for (const item of getQueueItemsInExecutionOrder(queueItems)) {
+    const candidates = candidatesByQueueItemId.get(item.id) ?? [];
+
+    if (!isActiveCanvasQueueItemForDocument(canvas, item) && candidates.length === 0) {
+      continue;
+    }
+
+    slots.push(...getCanvasStagingSlotsForQueueItem(canvas, item, candidates));
+    candidatesByQueueItemId.delete(item.id);
+  }
+
+  const orphanCandidateSlots = [...candidatesByQueueItemId.values()].flatMap((candidates) =>
+    candidates.map((candidate) => createCandidateSlot(candidate))
+  );
+
+  return [...orphanCandidateSlots, ...slots];
+};
+
+export const getCanvasStagingSlotCount = (canvas: CanvasStateContractV2, queueItems: readonly QueueItem[]): number =>
+  getCanvasStagingSlots(canvas, queueItems).length;
+
+export const getFirstCanvasPlaceholderSlotIndex = (
+  canvas: CanvasStateContractV2,
+  queueItems: readonly QueueItem[]
+): number => getCanvasStagingSlots(canvas, queueItems).findIndex((slot) => slot.kind === 'placeholder');
+
+export const getCancelableCanvasStagingQueueItemId = (slot: CanvasStagingSlot | undefined): string | null =>
+  slot?.kind === 'placeholder' ? slot.queueItemId : null;
diff --git a/invokeai/frontend/webv2/src/workbench/components/InvokeMark.tsx b/invokeai/frontend/webv2/src/workbench/components/InvokeMark.tsx
new file mode 100644
index 00000000000..d77971e5ac4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/InvokeMark.tsx
@@ -0,0 +1,14 @@
+import { Box } from '@chakra-ui/react';
+
+/** The Invoke logomark, drawn in the theme brand color. */
+export const InvokeMark = ({ size = 36 }: { size?: number }) => (
+  <Box color="brand.fg">
+    <svg aria-hidden="true" fill="none" height={size} viewBox="0 0 44 44" width={size}>
+      <path
+        d="M29.1951 10.6667H42V2H2V10.6667H14.8049L29.1951 33.3333H42V42H2V33.3333H14.8049"
+        stroke="currentColor"
+        strokeWidth="2.8"
+      />
+    </svg>
+  </Box>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/components/QueueProgressIndicator.tsx b/invokeai/frontend/webv2/src/workbench/components/QueueProgressIndicator.tsx
new file mode 100644
index 00000000000..8e1278eabdf
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/QueueProgressIndicator.tsx
@@ -0,0 +1,65 @@
+import type { QueueProgressBarState } from '@workbench/queueSummary';
+import type { ComponentProps } from 'react';
+
+import { Progress, ProgressCircle } from '@chakra-ui/react';
+
+const getProgressValuePercent = (state: QueueProgressBarState): number | null =>
+  state.kind === 'determinate' ? state.value * 100 : state.value;
+
+type ProgressCircleRootProps = ComponentProps<typeof ProgressCircle.Root>;
+type QueueCircularProgressSize = NonNullable<ProgressCircleRootProps['size']> | '2xs';
+
+export const QueueCircularProgress = ({
+  size = '2xs',
+  state,
+  ...props
+}: Omit<ProgressCircleRootProps, 'size' | 'value'> & {
+  size?: QueueCircularProgressSize;
+  state: QueueProgressBarState;
+}) => {
+  if (state.kind === 'idle') {
+    return null;
+  }
+
+  return (
+    <ProgressCircle.Root
+      aria-label="Project queue progress"
+      colorPalette="accent"
+      flexShrink="0"
+      size={size as ProgressCircleRootProps['size']}
+      value={getProgressValuePercent(state)}
+      {...props}
+    >
+      <ProgressCircle.Circle>
+        <ProgressCircle.Track stroke="{colors.border.subtle}" />
+        <ProgressCircle.Range stroke="{colors.accent.solid}" />
+      </ProgressCircle.Circle>
+    </ProgressCircle.Root>
+  );
+};
+
+export const QueueTabBackgroundProgress = ({
+  state,
+  ...props
+}: Omit<ComponentProps<typeof Progress.Root>, 'value'> & { state: QueueProgressBarState }) => {
+  if (state.kind === 'idle') {
+    return null;
+  }
+
+  return (
+    <Progress.Root
+      aria-label="Widget queue progress"
+      h="full"
+      inset="0"
+      max={1}
+      pointerEvents="none"
+      position="absolute"
+      value={state.value}
+      {...props}
+    >
+      <Progress.Track bg="transparent" h="full" boxShadow="none">
+        <Progress.Range bg="accent.subtle" />
+      </Progress.Track>
+    </Progress.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/WorkbenchSplashScreen.tsx b/invokeai/frontend/webv2/src/workbench/components/WorkbenchSplashScreen.tsx
new file mode 100644
index 00000000000..a247000b525
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/WorkbenchSplashScreen.tsx
@@ -0,0 +1,46 @@
+import splashImageUrl from '@assets/SplashImage.webp';
+import { Box, Flex, Heading, HStack, Spinner, Text, VStack } from '@chakra-ui/react';
+import { InvokeMark } from '@workbench/components/InvokeMark';
+import { useTranslation } from 'react-i18next';
+
+import { APP_VERSION } from '@/appMetadata';
+
+const splashImageStyle = { backgroundPosition: 'center', backgroundSize: 'cover' } as const;
+
+export const WorkbenchSplashScreen = ({ messageKey = 'splash.loadingWorkspace' }: { messageKey?: string }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Flex align="center" aria-busy="true" bg="bg" color="fg" h="100vh" justify="center" role="status" w="100vw">
+      <Box
+        position="relative"
+        borderColor="border.subtle"
+        borderRadius="3xl"
+        borderWidth="1px"
+        maxW="2xl"
+        p="6"
+        shadow="sm"
+      >
+        <HStack align="stretch" gap="8">
+          <Box aspectRatio="1/1" p="14" bgImage={`url(${splashImageUrl})`} rounded="xl" style={splashImageStyle}>
+            <InvokeMark size={164} />
+          </Box>
+          <VStack align="start" flex="1" minH="full" minW="80" textAlign="start" py="2">
+            <Heading size="2xl">{t('app.nameWithVersion', { name: t('app.name'), version: APP_VERSION })}</Heading>
+            <Text fontSize="md">{t('splash.tagline')}</Text>
+            <Text fontSize="xs">{t('splash.artworkBy', { artist: 'John Smith' })}</Text>
+            <Flex alignItems="center" gap="2" mt="auto">
+              <Spinner size="xs" />
+              <Text fontSize="xs" flex="1">
+                {t(messageKey)}
+              </Text>
+            </Flex>
+            <Text fontSize="2xs" mt="auto" fontFamily="mono">
+              {t('splash.copyright', { year: new Date().getFullYear() })}
+            </Text>
+          </VStack>
+        </HStack>
+      </Box>
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Button.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Button.tsx
new file mode 100644
index 00000000000..29d6140be1f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Button.tsx
@@ -0,0 +1,30 @@
+import type { ComponentProps } from 'react';
+
+import {
+  Button as ChakraButton,
+  CloseButton as ChakraCloseButton,
+  IconButton as ChakraIconButton,
+} from '@chakra-ui/react';
+
+type ButtonProps = ComponentProps<typeof ChakraButton>;
+type IconButtonProps = ComponentProps<typeof ChakraIconButton>;
+type CloseButtonProps = ComponentProps<typeof ChakraCloseButton>;
+
+/**
+ * Workbench buttons. Solid buttons default to the blue `accent` palette; every
+ * other variant stays on the neutral, theme-aware `gray` palette. Pass
+ * `colorPalette` explicitly to override (e.g. `brand` for the global Invoke
+ * action, `red` for destructive actions).
+ */
+const defaultPalette = (variant: ButtonProps['variant']): ButtonProps['colorPalette'] =>
+  variant === undefined || variant === 'solid' ? 'accent' : 'gray';
+
+export const Button = ({ colorPalette, ...props }: ButtonProps) => (
+  <ChakraButton colorPalette={colorPalette ?? defaultPalette(props.variant)} {...props} />
+);
+
+export const IconButton = ({ colorPalette, ...props }: IconButtonProps) => (
+  <ChakraIconButton colorPalette={colorPalette ?? defaultPalette(props.variant)} {...props} />
+);
+
+export const CloseButton = (props: CloseButtonProps) => <ChakraCloseButton {...props} />;
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/ColorPicker.test.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/ColorPicker.test.tsx
new file mode 100644
index 00000000000..4b12c8b3f6c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/ColorPicker.test.tsx
@@ -0,0 +1,18 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ColorPicker } from './ColorPicker';
+
+describe('ColorPicker', () => {
+  it('does not mount its overlay until it is opened', () => {
+    const markup = renderToStaticMarkup(
+      <ChakraProvider value={system}>
+        <ColorPicker aria-label="Fill color" value="#ff0000" onValueChange={vi.fn()} />
+      </ChakraProvider>
+    );
+
+    expect(markup).not.toContain('data-part="content"');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/ColorPicker.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/ColorPicker.tsx
new file mode 100644
index 00000000000..e9b0b39d426
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/ColorPicker.tsx
@@ -0,0 +1,108 @@
+import type { Color, ColorPickerValueChangeDetails } from '@chakra-ui/react';
+import type { ComponentProps } from 'react';
+
+import { ColorPicker as ChakraColorPicker, parseColor, Portal } from '@chakra-ui/react';
+import { useCallback, useState } from 'react';
+
+import { shouldSyncExternalColor } from './colorPickerSync';
+
+export type ColorPickerSize = NonNullable<ComponentProps<typeof ChakraColorPicker.Root>['size']>;
+
+export interface ColorPickerProps {
+  /** The current color, as a `#rrggbb` (or any CSS-parseable) string. */
+  value: string;
+  /** Called with the new `#rrggbb` hex string as the user drags the area/slider or edits the hex input. */
+  onValueChange: (hex: string) => void;
+  /**
+   * Called with the final `#rrggbb` hex when an interaction ends (pointer up on
+   * the area/slider, or the hex input committing). Consumers that record undo
+   * history use this to collapse a whole drag into one entry, mirroring the
+   * `Slider` `onValueChangeEnd` pattern.
+   */
+  onValueChangeEnd?: (hex: string) => void;
+  /** Accessible label for the swatch trigger button. */
+  'aria-label': string;
+  size?: ColorPickerSize;
+}
+
+/**
+ * Workbench color picker: a compact swatch trigger that opens a popover with a
+ * saturation/hue area and a hex input. Wraps Chakra v3's composed
+ * `ColorPicker.*` parts (chrome comes from the built-in `colorPicker` slot
+ * recipe, which already reads workbench semantic tokens) — this is the single
+ * import point, kept to exactly what `BrushOptions` needs.
+ *
+ * Internally, the picker's controlled value is kept as a full Chakra/Zag
+ * `Color` (which preserves hue/saturation independent of RGB), not a hex
+ * string — see `shouldSyncExternalColor` for why. The external API stays
+ * hex-string based; hex is only produced at the `onValueChange` emit boundary.
+ */
+export const ColorPicker = ({
+  'aria-label': ariaLabel,
+  onValueChange,
+  onValueChangeEnd,
+  size = 'xs',
+  value,
+}: ColorPickerProps) => {
+  const [previousExternalValue, setPreviousExternalValue] = useState(value);
+  const [color, setColor] = useState<Color>(() => parseColor(value));
+  const [lastEmittedHex, setLastEmittedHex] = useState(() => color.toString('hex'));
+
+  // Sync external -> internal only when the prop genuinely changed to
+  // something other than what we last emitted (see `shouldSyncExternalColor`).
+  if (value !== previousExternalValue) {
+    setPreviousExternalValue(value);
+    if (shouldSyncExternalColor(value, previousExternalValue, lastEmittedHex)) {
+      setColor(parseColor(value));
+    }
+  }
+
+  const handleValueChange = useCallback(
+    (details: ColorPickerValueChangeDetails) => {
+      setColor(details.value);
+      const hex = details.value.toString('hex');
+      setLastEmittedHex(hex);
+      onValueChange(hex);
+    },
+    [onValueChange]
+  );
+
+  const handleValueChangeEnd = useCallback(
+    (details: ColorPickerValueChangeDetails) => {
+      onValueChangeEnd?.(details.value.toString('hex'));
+    },
+    [onValueChangeEnd]
+  );
+
+  return (
+    <ChakraColorPicker.Root
+      lazyMount
+      size={size}
+      unmountOnExit
+      value={color}
+      onValueChange={handleValueChange}
+      onValueChangeEnd={handleValueChangeEnd}
+    >
+      <ChakraColorPicker.Control>
+        <ChakraColorPicker.Trigger aria-label={ariaLabel} data-fit-content>
+          <ChakraColorPicker.ValueSwatch />
+        </ChakraColorPicker.Trigger>
+      </ChakraColorPicker.Control>
+      <Portal>
+        <ChakraColorPicker.Positioner>
+          <ChakraColorPicker.Content>
+            <ChakraColorPicker.Area>
+              <ChakraColorPicker.AreaBackground />
+              <ChakraColorPicker.AreaThumb />
+            </ChakraColorPicker.Area>
+            <ChakraColorPicker.ChannelSlider channel="hue">
+              <ChakraColorPicker.ChannelSliderTrack />
+              <ChakraColorPicker.ChannelSliderThumb />
+            </ChakraColorPicker.ChannelSlider>
+            <ChakraColorPicker.Input />
+          </ChakraColorPicker.Content>
+        </ChakraColorPicker.Positioner>
+      </Portal>
+    </ChakraColorPicker.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/ConfirmDialog.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/ConfirmDialog.tsx
new file mode 100644
index 00000000000..cc6766b68aa
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/ConfirmDialog.tsx
@@ -0,0 +1,91 @@
+/* eslint-disable react/react-compiler */
+import { Dialog, Portal, Stack, Text } from '@chakra-ui/react';
+import { useCallback, useState, type ReactNode } from 'react';
+
+import { Button, CloseButton } from './Button';
+
+/**
+ * Controlled confirmation dialog for consequential actions. The confirm
+ * button shows a pending state while `onConfirm` runs; errors are left to the
+ * caller (usually surfaced as a notification) and the dialog closes either way.
+ */
+export const ConfirmDialog = ({
+  body,
+  confirmLabel,
+  isDestructive = true,
+  isOpen,
+  onClose,
+  onConfirm,
+  title,
+}: {
+  body: ReactNode;
+  confirmLabel: string;
+  isDestructive?: boolean;
+  isOpen: boolean;
+  onClose: () => void;
+  onConfirm: () => Promise<void> | void;
+  title: string;
+}) => {
+  const [isPending, setIsPending] = useState(false);
+
+  const handleConfirm = useCallback(async () => {
+    setIsPending(true);
+
+    try {
+      await onConfirm();
+    } finally {
+      setIsPending(false);
+      onClose();
+    }
+  }, [onClose, onConfirm]);
+
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  const handleConfirmClick = useCallback(() => {
+    void handleConfirm();
+  }, [handleConfirm]);
+
+  return (
+    <Dialog.Root open={isOpen} placement="center" role="alertdialog" size="sm" onOpenChange={handleOpenChange}>
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" color="fg">
+            <Dialog.Header>
+              <Dialog.Title fontSize="sm" fontWeight="700">
+                {title}
+              </Dialog.Title>
+            </Dialog.Header>
+            <Dialog.Body>
+              <Stack gap="2">{typeof body === 'string' ? <Text fontSize="xs">{body}</Text> : body}</Stack>
+            </Dialog.Body>
+            <Dialog.Footer gap="2">
+              <Button disabled={isPending} size="xs" variant="ghost" onClick={onClose}>
+                Cancel
+              </Button>
+              <Button
+                colorPalette={isDestructive ? 'red' : 'accent'}
+                loading={isPending}
+                size="xs"
+                variant="solid"
+                onClick={handleConfirmClick}
+              >
+                {confirmLabel}
+              </Button>
+            </Dialog.Footer>
+            <Dialog.CloseTrigger asChild>
+              <CloseButton color="fg.muted" size="sm" />
+            </Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/EmptyState.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/EmptyState.tsx
new file mode 100644
index 00000000000..fb37633fbb4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/EmptyState.tsx
@@ -0,0 +1,30 @@
+import { EmptyState as ChakraEmptyState, VStack } from '@chakra-ui/react';
+import * as React from 'react';
+
+export interface EmptyStateProps extends ChakraEmptyState.RootProps {
+  title: string;
+  description?: string | null;
+  icon?: React.ReactNode;
+  danger?: boolean;
+}
+
+export const EmptyState = React.forwardRef<HTMLDivElement, EmptyStateProps>(function EmptyState(props, ref) {
+  const { title, description, icon, children, danger, ...rest } = props;
+  const fgColor = danger ? 'fg.error' : undefined;
+  return (
+    <ChakraEmptyState.Root ref={ref} {...rest} size={props.size ?? 'sm'}>
+      <ChakraEmptyState.Content>
+        {icon && <ChakraEmptyState.Indicator color={fgColor}>{icon}</ChakraEmptyState.Indicator>}
+        {description ? (
+          <VStack textAlign="center" color={fgColor}>
+            <ChakraEmptyState.Title>{title}</ChakraEmptyState.Title>
+            <ChakraEmptyState.Description>{description}</ChakraEmptyState.Description>
+          </VStack>
+        ) : (
+          <ChakraEmptyState.Title color={fgColor}>{title}</ChakraEmptyState.Title>
+        )}
+        {children}
+      </ChakraEmptyState.Content>
+    </ChakraEmptyState.Root>
+  );
+});
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Field.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Field.tsx
new file mode 100644
index 00000000000..32fa33e702d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Field.tsx
@@ -0,0 +1,124 @@
+import type { ReactNode } from 'react';
+
+import { Field as ChakraField, HStack, Stack, Text, useRecipe, type StackProps } from '@chakra-ui/react';
+import { fieldLabelRecipe } from '@theme/recipes';
+import { useMemo } from 'react';
+
+/**
+ * The shared, theme-aware uppercase field label. Backed by `fieldLabelRecipe` so
+ * every form across the workbench renders an identical label without repeating
+ * the same five style props inline.
+ */
+export const FieldLabel = ({ children }: { children: ReactNode }) => {
+  const recipe = useRecipe({ recipe: fieldLabelRecipe });
+
+  return (
+    <Text as="span" css={recipe()}>
+      {children}
+    </Text>
+  );
+};
+
+export interface FieldProps extends Omit<StackProps, 'disabled' | 'id' | 'readOnly' | 'required' | 'title'> {
+  id?: string;
+  label: string;
+  labelEnd?: ReactNode;
+  disabled?: boolean;
+  orientation?: 'horizontal' | 'vertical';
+  invalid?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  /** Validation error, shown in place of `helpText`; also marks the field invalid by default. */
+  error?: string | null;
+  helpText?: string;
+  children: ReactNode;
+}
+
+/** A labelled form field: an uppercase label stacked above its control, with an optional help/error line below. */
+export const Field = ({
+  children,
+  disabled,
+  error,
+  helpText,
+  id,
+  invalid,
+  label,
+  labelEnd,
+  orientation = 'vertical',
+  readOnly,
+  required,
+  ...rest
+}: FieldProps) => {
+  const recipe = useRecipe({ recipe: fieldLabelRecipe });
+  const isHorizontal = orientation === 'horizontal';
+  const isInvalid = invalid ?? Boolean(error);
+  const ids = useMemo(
+    () =>
+      id
+        ? {
+            errorText: `${id}-error`,
+            helperText: `${id}-help`,
+            label: `${id}-label`,
+          }
+        : undefined,
+    [id]
+  );
+  const labelContent = <ChakraField.Label css={recipe()}>{label}</ChakraField.Label>;
+  const message = error ? (
+    <ChakraField.ErrorText color="fg.error" fontSize="2xs" role="alert">
+      {error}
+    </ChakraField.ErrorText>
+  ) : helpText ? (
+    <ChakraField.HelperText color="fg.subtle" fontSize="2xs">
+      {helpText}
+    </ChakraField.HelperText>
+  ) : null;
+
+  if (!isHorizontal) {
+    return (
+      <ChakraField.Root
+        asChild
+        disabled={disabled}
+        id={id}
+        ids={ids}
+        invalid={isInvalid}
+        readOnly={readOnly}
+        required={required}
+        unstyled
+      >
+        <Stack flex="1" gap="1.5" minW="0" {...rest}>
+          <HStack align="center" justify="space-between" minW="0">
+            {labelContent}
+            {labelEnd}
+          </HStack>
+          {children}
+          {message}
+        </Stack>
+      </ChakraField.Root>
+    );
+  }
+
+  return (
+    <ChakraField.Root
+      asChild
+      disabled={disabled}
+      id={id}
+      ids={ids}
+      invalid={isInvalid}
+      readOnly={readOnly}
+      required={required}
+      unstyled
+    >
+      <Stack align="flex-start" direction="row" flex="1" gap="1.5" minW="0" {...rest}>
+        <HStack align="center" flexShrink="0" justify="space-between" minH="8" minW="0">
+          {labelContent}
+          {labelEnd}
+        </HStack>
+        <Stack flex="1" gap="1.5" minW="0" w="full">
+          {children}
+          {message}
+        </Stack>
+      </Stack>
+    </ChakraField.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/JsonPreview.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/JsonPreview.tsx
new file mode 100644
index 00000000000..5d4f34131b8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/JsonPreview.tsx
@@ -0,0 +1,112 @@
+import { Box, Code, Icon, ScrollArea } from '@chakra-ui/react';
+import { CheckIcon, CopyIcon } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { IconButton } from './Button';
+import { toaster } from './toaster';
+
+/**
+ * The workbench's standard JSON preview: a monospace block with a copy button
+ * that owns its scrolling in both axes — long strings scroll horizontally
+ * instead of stretching the surrounding layout. Pass `value` to serialize, or
+ * `text` when the JSON string already exists (an export payload that must be
+ * copied byte-for-byte). Defaults to a bounded height; pass `maxH` (or wrap in
+ * a flex parent and pass `maxH="100%"`) to control it.
+ */
+export const JsonPreview = ({
+  h,
+  label = 'JSON preview',
+  maxH = '24rem',
+  text,
+  value,
+}: {
+  h?: string;
+  /** Accessible name for the scroll viewport. */
+  label?: string;
+  maxH?: string;
+  text?: string;
+  value?: unknown;
+}) => {
+  const [hasCopied, setHasCopied] = useState(false);
+  const copyResetTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const json = useMemo(() => text ?? JSON.stringify(value, null, 2) ?? 'null', [text, value]);
+
+  useEffect(
+    () => () => {
+      if (copyResetTimerRef.current !== null) {
+        clearTimeout(copyResetTimerRef.current);
+      }
+    },
+    []
+  );
+
+  const copy = useCallback(() => {
+    navigator.clipboard
+      .writeText(json)
+      .then(() => {
+        setHasCopied(true);
+
+        if (copyResetTimerRef.current !== null) {
+          clearTimeout(copyResetTimerRef.current);
+        }
+
+        copyResetTimerRef.current = setTimeout(() => setHasCopied(false), 1500);
+      })
+      .catch(() => toaster.create({ title: 'Failed to copy JSON', type: 'error' }));
+  }, [json]);
+
+  return (
+    <Box
+      bg="bg.inset"
+      display="flex"
+      flexDirection="column"
+      h={h}
+      maxH={maxH}
+      maxW="full"
+      minH="0"
+      minW="0"
+      overflow="hidden"
+      position="relative"
+      w="full"
+    >
+      <IconButton
+        aria-label="Copy JSON"
+        bg="bg.muted"
+        position="absolute"
+        right="1.5"
+        size="2xs"
+        title="Copy JSON"
+        top="1.5"
+        variant="ghost"
+        zIndex="1"
+        onClick={copy}
+      >
+        <Icon as={hasCopied ? CheckIcon : CopyIcon} boxSize="3" color={hasCopied ? 'green.solid' : undefined} />
+      </IconButton>
+      <ScrollArea.Root flex="1" maxW="full" minH="0" minW="0" size="xs" variant="hover" w="full">
+        <ScrollArea.Viewport aria-label={label} h="full" maxH={maxH} minW="0" w="full">
+          <ScrollArea.Content w="full">
+            <Code
+              bg="transparent"
+              display="block"
+              fontSize="2xs"
+              minW="max-content"
+              p="2"
+              whiteSpace="pre"
+              wordBreak="normal"
+            >
+              {json}
+            </Code>
+          </ScrollArea.Content>
+        </ScrollArea.Viewport>
+        <ScrollArea.Scrollbar>
+          <ScrollArea.Thumb />
+        </ScrollArea.Scrollbar>
+        <ScrollArea.Scrollbar orientation="horizontal">
+          <ScrollArea.Thumb />
+        </ScrollArea.Scrollbar>
+        <ScrollArea.Corner />
+      </ScrollArea.Root>
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Menu.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Menu.tsx
new file mode 100644
index 00000000000..4d295159567
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Menu.tsx
@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react';
+
+import { Menu } from '@chakra-ui/react';
+
+type MenuContentProps = ComponentProps<typeof Menu.Content>;
+
+/**
+ * Menu.Content passthrough. The workbench popover chrome (surface, stroke,
+ * radius, shadow) is applied globally by the `menu` slot-recipe override in
+ * `theme/recipes.ts`; this wrapper only exists as the single import point
+ * for future menu-wide behavior.
+ */
+export const MenuContent = (props: MenuContentProps) => <Menu.Content {...props} />;
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Panel.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Panel.tsx
new file mode 100644
index 00000000000..9f92013a96b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Panel.tsx
@@ -0,0 +1,19 @@
+import { Box, type BoxProps, type RecipeVariantProps, useRecipe } from '@chakra-ui/react';
+import { panelRecipe } from '@theme/recipes';
+import { useMemo } from 'react';
+
+export type PanelProps = BoxProps & RecipeVariantProps<typeof panelRecipe>;
+
+/**
+ * Bordered surface container backed by `panelRecipe` — the one styling
+ * contract for panels, cards, and wells across the workbench.
+ *
+ * - `tone`: `surface` (default) | `raised` | `inset` | `control`
+ * - `density`: `none` (default) | `sm` | `md` — padding + gap presets
+ */
+export const Panel = ({ css, density, tone, ...rest }: PanelProps) => {
+  const recipe = useRecipe({ recipe: panelRecipe });
+  const panelCss = useMemo(() => [recipe({ density, tone }), css], [css, density, recipe, tone]);
+
+  return <Box css={panelCss} {...rest} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/RenameDialog.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/RenameDialog.tsx
new file mode 100644
index 00000000000..eaf0fc42ab3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/RenameDialog.tsx
@@ -0,0 +1,112 @@
+import { chakra, Dialog, Input, Portal, Stack } from '@chakra-ui/react';
+import { useCallback, useState, type FormEvent } from 'react';
+
+import { Button, CloseButton } from './Button';
+import { Field } from './Field';
+
+/**
+ * Controlled single-field rename dialog. `onSubmit` only fires for a
+ * non-empty name that actually changed; it may be async, in which case the
+ * submit button shows a pending state and errors keep the dialog open so the
+ * caller's message (usually a toast) can be acted on.
+ */
+export const RenameDialog = ({
+  initialName,
+  isOpen,
+  label = 'Project name',
+  onClose,
+  onSubmit,
+  submitLabel = 'Rename',
+  submitUnchanged = false,
+  title = 'Rename project',
+}: {
+  initialName: string;
+  isOpen: boolean;
+  label?: string;
+  onClose: () => void;
+  onSubmit: (name: string) => Promise<void> | void;
+  submitLabel?: string;
+  submitUnchanged?: boolean;
+  title?: string;
+}) => {
+  const [isPending, setIsPending] = useState(false);
+
+  const commit = useCallback(
+    async (value: string) => {
+      const name = value.trim();
+
+      if (!name || (!submitUnchanged && name === initialName.trim())) {
+        onClose();
+
+        return;
+      }
+
+      setIsPending(true);
+
+      try {
+        await onSubmit(name);
+        onClose();
+      } catch {
+        // The caller surfaced the failure (toast/notification); stay open so
+        // the name is not lost.
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [initialName, onClose, onSubmit, submitUnchanged]
+  );
+
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  const handleSubmit = useCallback(
+    (event: FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      void commit(new FormData(event.currentTarget).get('renameValue')?.toString() ?? '');
+    },
+    [commit]
+  );
+
+  return (
+    <Dialog.Root lazyMount open={isOpen} placement="center" size="xs" unmountOnExit onOpenChange={handleOpenChange}>
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" color="fg">
+            <chakra.form onSubmit={handleSubmit}>
+              <Dialog.Header>
+                <Dialog.Title fontSize="sm" fontWeight="700">
+                  {title}
+                </Dialog.Title>
+              </Dialog.Header>
+              <Dialog.Body>
+                <Stack gap="2">
+                  <Field label={label}>
+                    <Input autoFocus defaultValue={initialName} name="renameValue" size="sm" />
+                  </Field>
+                </Stack>
+              </Dialog.Body>
+              <Dialog.Footer gap="2">
+                <Button disabled={isPending} size="xs" type="button" variant="ghost" onClick={onClose}>
+                  Cancel
+                </Button>
+                <Button loading={isPending} size="xs" type="submit" variant="solid">
+                  {submitLabel}
+                </Button>
+              </Dialog.Footer>
+            </chakra.form>
+            <Dialog.CloseTrigger asChild>
+              <CloseButton color="fg.muted" size="sm" />
+            </Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/ResizableTextarea.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/ResizableTextarea.tsx
new file mode 100644
index 00000000000..9fede592834
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/ResizableTextarea.tsx
@@ -0,0 +1,164 @@
+/* eslint-disable react/react-compiler */
+import type {
+  ComponentProps,
+  KeyboardEvent as ReactKeyboardEvent,
+  PointerEvent as ReactPointerEvent,
+  Ref,
+  ReactNode,
+} from 'react';
+
+import { Box, Textarea } from '@chakra-ui/react';
+import { useCallback, useState } from 'react';
+
+type TextareaProps = ComponentProps<typeof Textarea>;
+
+const DEFAULT_STEP_PX = 12;
+const DEFAULT_LARGE_STEP_PX = 48;
+
+const clamp = (value: number, min: number, max: number): number => Math.min(Math.max(value, min), max);
+
+const resizeHandleAfter = {
+  bg: 'border.emphasized',
+  borderRadius: 'full',
+  bottom: '1px',
+  content: '""',
+  h: '1px',
+  left: '25%',
+  opacity: 0.55,
+  position: 'absolute',
+  right: '25%',
+} as const;
+
+const resizeHandleFocusVisible = { bg: 'accent.solid/20', outline: '2px solid {colors.accent.solid}' } as const;
+const resizeHandleHover = { bg: 'accent.solid/12' } as const;
+
+export interface ResizableTextareaProps extends Omit<
+  TextareaProps,
+  'h' | 'height' | 'maxH' | 'maxHeight' | 'minH' | 'minHeight' | 'resize'
+> {
+  defaultHeightPx: number;
+  maxHeightPx?: number;
+  minHeightPx: number;
+  resizeHandleAriaLabel: string;
+  largeStepPx?: number;
+  stepPx?: number;
+  textareaRef?: Ref<HTMLTextAreaElement>;
+  underlay?: ReactNode;
+  onResizeEnd?: (heightPx: number) => void;
+}
+
+export const ResizableTextarea = ({
+  defaultHeightPx,
+  largeStepPx = DEFAULT_LARGE_STEP_PX,
+  maxHeightPx = 420,
+  minHeightPx,
+  onResizeEnd,
+  resizeHandleAriaLabel,
+  stepPx = DEFAULT_STEP_PX,
+  textareaRef,
+  underlay,
+  ...textareaProps
+}: ResizableTextareaProps) => {
+  const initialHeightPx = clamp(defaultHeightPx, minHeightPx, maxHeightPx);
+  const [heightPx, setHeightPx] = useState(initialHeightPx);
+  const [dragHeightPx, setDragHeightPx] = useState<number | null>(null);
+  const displayHeightPx = dragHeightPx ?? heightPx;
+
+  const commitHeight = useCallback(
+    (nextHeightPx: number) => {
+      const clampedHeightPx = clamp(nextHeightPx, minHeightPx, maxHeightPx);
+
+      setHeightPx(clampedHeightPx);
+      onResizeEnd?.(clampedHeightPx);
+    },
+    [maxHeightPx, minHeightPx, onResizeEnd]
+  );
+
+  const handlePointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      event.preventDefault();
+
+      const startY = event.clientY;
+      const startHeightPx = displayHeightPx;
+      let nextHeightPx = startHeightPx;
+
+      const handlePointerMove = (moveEvent: PointerEvent) => {
+        nextHeightPx = clamp(startHeightPx + moveEvent.clientY - startY, minHeightPx, maxHeightPx);
+        setDragHeightPx(nextHeightPx);
+      };
+
+      const handlePointerUp = () => {
+        window.removeEventListener('pointermove', handlePointerMove);
+        window.removeEventListener('pointerup', handlePointerUp);
+        window.removeEventListener('pointercancel', handlePointerUp);
+        setDragHeightPx(null);
+        commitHeight(nextHeightPx);
+      };
+
+      window.addEventListener('pointermove', handlePointerMove);
+      window.addEventListener('pointerup', handlePointerUp);
+      window.addEventListener('pointercancel', handlePointerUp);
+    },
+    [commitHeight, displayHeightPx, maxHeightPx, minHeightPx]
+  );
+
+  const handleKeyDown = useCallback(
+    (event: ReactKeyboardEvent<HTMLDivElement>) => {
+      const step = event.shiftKey ? largeStepPx : stepPx;
+      const heightChange =
+        event.key === 'ArrowDown'
+          ? step
+          : event.key === 'ArrowUp'
+            ? -step
+            : event.key === 'End'
+              ? maxHeightPx - displayHeightPx
+              : event.key === 'Home'
+                ? minHeightPx - displayHeightPx
+                : undefined;
+
+      if (heightChange === undefined) {
+        return;
+      }
+
+      event.preventDefault();
+      commitHeight(displayHeightPx + heightChange);
+    },
+    [commitHeight, displayHeightPx, largeStepPx, maxHeightPx, minHeightPx, stepPx]
+  );
+
+  return (
+    <Box position="relative">
+      {underlay}
+      <Textarea
+        ref={textareaRef}
+        h={`${displayHeightPx}px`}
+        position={underlay ? 'relative' : textareaProps.position}
+        resize="none"
+        zIndex={underlay ? 1 : textareaProps.zIndex}
+        {...textareaProps}
+      />
+      <Box
+        aria-label={resizeHandleAriaLabel}
+        aria-orientation="horizontal"
+        aria-valuemax={maxHeightPx}
+        aria-valuemin={minHeightPx}
+        aria-valuenow={displayHeightPx}
+        bottom="0"
+        cursor="ns-resize"
+        h="2"
+        left="0"
+        position="absolute"
+        right="0"
+        role="separator"
+        tabIndex={0}
+        transition="background var(--wb-motion-duration-fast) ease, opacity var(--wb-motion-duration-fast) ease"
+        zIndex={2}
+        _after={resizeHandleAfter}
+        _focusVisible={resizeHandleFocusVisible}
+        _hover={resizeHandleHover}
+        onKeyDown={handleKeyDown}
+        onPointerDown={handlePointerDown}
+      />
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Row.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Row.tsx
new file mode 100644
index 00000000000..ce2179f3888
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Row.tsx
@@ -0,0 +1,22 @@
+import { Box, type BoxProps, type RecipeVariantProps, useRecipe } from '@chakra-ui/react';
+import { rowRecipe } from '@theme/recipes';
+import { useMemo } from 'react';
+
+export type RowProps = BoxProps & RecipeVariantProps<typeof rowRecipe>;
+
+/**
+ * Interactive list / table row backed by `rowRecipe`: hover and focus fills
+ * come from the recipe, and the previously ad-hoc `isSelected ? … : …`
+ * ternaries collapse into the `active` variant.
+ *
+ * - `active`: `none` (default) | `muted` (selected) | `brand` (identity) |
+ *   `accent` (active item / selection highlight)
+ *
+ * Render as a real `<button>` (`as="button"`) when the row is clickable.
+ */
+export const Row = ({ active, css, ...rest }: RowProps) => {
+  const recipe = useRecipe({ recipe: rowRecipe });
+  const rowCss = useMemo(() => [recipe({ active }), css], [active, css, recipe]);
+
+  return <Box css={rowCss} {...rest} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Scrollable.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Scrollable.tsx
new file mode 100644
index 00000000000..a1c0fe7befd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Scrollable.tsx
@@ -0,0 +1,29 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { ScrollArea } from '@chakra-ui/react';
+
+type ScrollAreaRootProps = ComponentProps<typeof ScrollArea.Root>;
+
+/**
+ * The workbench's standard scroll container: ScrollArea with hover-revealed
+ * scrollbars and the content wrapper zag needs for correct thumb sizing.
+ * Layout props (h, maxH, flex, ...) go to the root.
+ */
+export const Scrollable = ({
+  children,
+  label,
+  ...rootProps
+}: ScrollAreaRootProps & {
+  children: ReactNode;
+  /** Accessible name for the scroll viewport. */
+  label?: string;
+}) => (
+  <ScrollArea.Root size="xs" variant="hover" {...rootProps}>
+    <ScrollArea.Viewport aria-label={label} h="full" w="full">
+      <ScrollArea.Content w="full">{children}</ScrollArea.Content>
+    </ScrollArea.Viewport>
+    <ScrollArea.Scrollbar>
+      <ScrollArea.Thumb />
+    </ScrollArea.Scrollbar>
+  </ScrollArea.Root>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Select.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Select.tsx
new file mode 100644
index 00000000000..1c917eca753
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Select.tsx
@@ -0,0 +1,77 @@
+import type {
+  CollectionItem,
+  SelectContentProps,
+  SelectIndicatorGroupProps,
+  SelectPositionerProps,
+  SelectRootProps,
+  SelectTriggerProps,
+  SelectValueTextProps,
+} from '@chakra-ui/react';
+import type { Key, ReactNode } from 'react';
+
+import { Portal, Select as ChakraSelect } from '@chakra-ui/react';
+
+const getDefaultItemKey = <T extends CollectionItem>(item: T, index: number): Key => {
+  const keyedItem = item as { id?: Key; value?: Key };
+
+  return keyedItem.value ?? keyedItem.id ?? index;
+};
+
+const renderDefaultItem = <T extends CollectionItem>(item: T): ReactNode => {
+  const labelledItem = item as { label?: ReactNode; value?: ReactNode };
+
+  return labelledItem.label ?? labelledItem.value;
+};
+
+export interface SelectProps<T extends CollectionItem> extends Omit<SelectRootProps<T>, 'children'> {
+  contentProps?: SelectContentProps;
+  getItemKey?: (item: T, index: number) => Key;
+  indicatorGroupProps?: SelectIndicatorGroupProps;
+  itemIndicator?: boolean;
+  portalled?: boolean;
+  positionerProps?: SelectPositionerProps;
+  renderItem?: (item: T) => ReactNode;
+  triggerProps?: SelectTriggerProps;
+  valueText?: ReactNode;
+  valueTextProps?: SelectValueTextProps;
+}
+
+/** Workbench Select: Chakra's custom Select with the standard trigger, portal, and item markup pre-wired. */
+export const Select = <T extends CollectionItem>({
+  collection,
+  contentProps,
+  getItemKey = getDefaultItemKey,
+  indicatorGroupProps,
+  itemIndicator = true,
+  portalled = true,
+  positionerProps,
+  renderItem = renderDefaultItem,
+  triggerProps,
+  valueText,
+  valueTextProps,
+  ...rootProps
+}: SelectProps<T>) => (
+  <ChakraSelect.Root collection={collection} {...rootProps}>
+    <ChakraSelect.HiddenSelect />
+    <ChakraSelect.Control>
+      <ChakraSelect.Trigger {...triggerProps}>
+        <ChakraSelect.ValueText {...valueTextProps}>{valueText}</ChakraSelect.ValueText>
+      </ChakraSelect.Trigger>
+      <ChakraSelect.IndicatorGroup {...indicatorGroupProps}>
+        <ChakraSelect.Indicator />
+      </ChakraSelect.IndicatorGroup>
+    </ChakraSelect.Control>
+    <Portal disabled={!portalled}>
+      <ChakraSelect.Positioner {...positionerProps}>
+        <ChakraSelect.Content {...contentProps}>
+          {collection.items.map((item, index) => (
+            <ChakraSelect.Item key={getItemKey(item, index)} item={item}>
+              <ChakraSelect.ItemText>{renderItem(item)}</ChakraSelect.ItemText>
+              {itemIndicator ? <ChakraSelect.ItemIndicator /> : null}
+            </ChakraSelect.Item>
+          ))}
+        </ChakraSelect.Content>
+      </ChakraSelect.Positioner>
+    </Portal>
+  </ChakraSelect.Root>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Slider.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Slider.tsx
new file mode 100644
index 00000000000..97de382b885
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Slider.tsx
@@ -0,0 +1,172 @@
+import type { ReactNode } from 'react';
+
+import { Portal, Slider as ChakraSlider, Tooltip as ChakraTooltip } from '@chakra-ui/react';
+import { useCallback, useMemo, useState } from 'react';
+
+export type SliderMark = number | { label: ReactNode; value: number };
+
+export interface SliderProps extends Omit<ChakraSlider.RootProps, 'children'> {
+  /** Formats a thumb's value for its tooltip. */
+  formatValue?: (value: number, index: number) => string;
+  /** Marks under the track, revealed while the slider is hovered or dragged. */
+  marks?: SliderMark[];
+  /** Show the formatted value above each thumb while the slider is hovered or a thumb is dragged. */
+  withThumbTooltip?: boolean;
+}
+
+// Marks stay mounted so the slider keeps a stable height, but only fade in
+// while the slider is hovered or dragged. This is driven by the primitives' own
+// DOM state: the root carries `data-dragging` for the whole gesture.
+const INTERACTION_REVEAL_CSS = {
+  '& [data-part="marker-group"]': {
+    opacity: 0,
+    transition: 'opacity var(--wb-motion-duration-fast)',
+  },
+  '&:hover [data-part="marker-group"], &[data-dragging] [data-part="marker-group"]': {
+    opacity: 1,
+  },
+};
+
+const RANGE_MARKER_CSS = {
+  '& [data-part="marker"][data-state="under-value"], & [data-part="marker"][data-state="over-value"]': {
+    '--marker-bg': 'white',
+  },
+  '& [data-part="marker"][data-state="at-value"]': {
+    '--marker-bg': 'colors.bg',
+  },
+};
+
+const TOOLTIP_POSITIONING = {
+  gutter: 4,
+  placement: 'top',
+  strategy: 'fixed',
+} as const;
+
+const formatValueDefault = (value: number): string => String(value);
+
+const SliderThumb = ({ index, isTooltipOpen, label }: { index: number; isTooltipOpen: boolean; label: string }) => (
+  <ChakraTooltip.Root closeDelay={0} open={isTooltipOpen} openDelay={0} positioning={TOOLTIP_POSITIONING}>
+    <ChakraTooltip.Trigger asChild>
+      <ChakraSlider.Thumb index={index}>
+        <ChakraSlider.HiddenInput />
+      </ChakraSlider.Thumb>
+    </ChakraTooltip.Trigger>
+    <Portal>
+      <ChakraTooltip.Positioner>
+        <ChakraTooltip.Content pointerEvents="none">{label}</ChakraTooltip.Content>
+      </ChakraTooltip.Positioner>
+    </Portal>
+  </ChakraTooltip.Root>
+);
+
+/**
+ * Workbench slider. Wraps the Chakra slider primitives with the conveniences
+ * the legacy (Chakra v2) slider had: a formatted value tooltip on each thumb
+ * that shows while the slider is hovered and stays up through drags, and track
+ * marks that reveal on hover so dense forms stay quiet until the slider is
+ * being used. Renders one thumb per entry in `value`/`defaultValue`, so it
+ * covers single and range sliders.
+ */
+export const Slider = ({
+  formatValue = formatValueDefault,
+  marks,
+  withThumbTooltip = true,
+  ...rootProps
+}: SliderProps) => {
+  const {
+    css,
+    onBlurCapture,
+    onFocusCapture,
+    onPointerDown,
+    onPointerEnter,
+    onPointerLeave,
+    onPointerUp,
+    onValueChangeEnd,
+    ...rest
+  } = rootProps;
+  const values = rest.value ?? rest.defaultValue ?? [];
+  const [isHovering, setIsHovering] = useState(false);
+  const [isFocused, setIsFocused] = useState(false);
+  const [isDragging, setIsDragging] = useState(false);
+
+  const rootCss = useMemo(() => {
+    const baseCss = values.length > 1 ? [INTERACTION_REVEAL_CSS, RANGE_MARKER_CSS] : [INTERACTION_REVEAL_CSS];
+
+    return css ? [...baseCss, css] : baseCss;
+  }, [css, values.length]);
+  const isTooltipOpen = withThumbTooltip && (isHovering || isFocused || isDragging);
+  const handleBlurCapture: NonNullable<ChakraSlider.RootProps['onBlurCapture']> = useCallback(
+    (event) => {
+      setIsFocused(false);
+      onBlurCapture?.(event);
+    },
+    [onBlurCapture]
+  );
+  const handleFocusCapture: NonNullable<ChakraSlider.RootProps['onFocusCapture']> = useCallback(
+    (event) => {
+      setIsFocused(true);
+      onFocusCapture?.(event);
+    },
+    [onFocusCapture]
+  );
+  const handlePointerDown: NonNullable<ChakraSlider.RootProps['onPointerDown']> = useCallback(
+    (event) => {
+      setIsDragging(true);
+      onPointerDown?.(event);
+    },
+    [onPointerDown]
+  );
+  const handlePointerEnter: NonNullable<ChakraSlider.RootProps['onPointerEnter']> = useCallback(
+    (event) => {
+      setIsHovering(true);
+      onPointerEnter?.(event);
+    },
+    [onPointerEnter]
+  );
+  const handlePointerLeave: NonNullable<ChakraSlider.RootProps['onPointerLeave']> = useCallback(
+    (event) => {
+      setIsHovering(false);
+      onPointerLeave?.(event);
+    },
+    [onPointerLeave]
+  );
+  const handlePointerUp: NonNullable<ChakraSlider.RootProps['onPointerUp']> = useCallback(
+    (event) => {
+      setIsDragging(false);
+      onPointerUp?.(event);
+    },
+    [onPointerUp]
+  );
+  const handleValueChangeEnd: NonNullable<ChakraSlider.RootProps['onValueChangeEnd']> = useCallback(
+    (details) => {
+      setIsDragging(false);
+      onValueChangeEnd?.(details);
+    },
+    [onValueChangeEnd]
+  );
+
+  return (
+    <ChakraSlider.Root
+      css={rootCss}
+      {...rest}
+      onBlurCapture={handleBlurCapture}
+      onFocusCapture={handleFocusCapture}
+      onPointerDown={handlePointerDown}
+      onPointerEnter={handlePointerEnter}
+      onPointerLeave={handlePointerLeave}
+      onPointerUp={handlePointerUp}
+      onValueChangeEnd={handleValueChangeEnd}
+      thumbCollisionBehavior="push"
+    >
+      <ChakraSlider.Control>
+        <ChakraSlider.Track>
+          <ChakraSlider.Range />
+        </ChakraSlider.Track>
+        {values.map((value, index) => (
+          <SliderThumb key={index} index={index} isTooltipOpen={isTooltipOpen} label={formatValue(value, index)} />
+        ))}
+      </ChakraSlider.Control>
+      {marks?.length ? <ChakraSlider.Marks marks={marks} /> : null}
+    </ChakraSlider.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Tabs.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Tabs.tsx
new file mode 100644
index 00000000000..a7585ee883f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Tabs.tsx
@@ -0,0 +1,12 @@
+import type { ComponentProps } from 'react';
+
+import { Tabs as ChakraTabs } from '@chakra-ui/react';
+
+type TabsRootProps = ComponentProps<typeof ChakraTabs.Root>;
+
+const Root = (props: TabsRootProps) => <ChakraTabs.Root colorPalette="accent" {...props} />;
+
+export const Tabs = {
+  ...ChakraTabs,
+  Root,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/ToggleDot.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/ToggleDot.tsx
new file mode 100644
index 00000000000..f014609bd6e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/ToggleDot.tsx
@@ -0,0 +1,54 @@
+import type { BoxProps } from '@chakra-ui/react';
+import type { ReactNode } from 'react';
+
+import { Box } from '@chakra-ui/react';
+import { useCallback } from 'react';
+
+import { Tooltip } from './Tooltip';
+
+const TOGGLE_DOT_HOVER_STYLES = { borderColor: 'fg.muted' };
+const TOGGLE_DOT_CHECKED_HOVER_STYLES = { bg: 'accent.emphasized', borderColor: 'accent.emphasized' };
+
+export interface ToggleDotProps extends Omit<BoxProps, 'aria-label' | 'as' | 'children' | 'onChange' | 'onClick'> {
+  checked: boolean;
+  disabled?: boolean;
+  label: string;
+  tooltip?: ReactNode;
+  onCheckedChange: (checked: boolean) => void;
+}
+
+/** Small pressable dot for compact enabled/disabled state toggles. */
+export const ToggleDot = ({
+  checked,
+  disabled = false,
+  label,
+  onCheckedChange,
+  tooltip = label,
+  ...rest
+}: ToggleDotProps) => {
+  const handleClick = useCallback(() => onCheckedChange(!checked), [checked, onCheckedChange]);
+  const nativeDisabled = disabled ? { disabled: true } : {};
+  const dot = (
+    <Box
+      as="button"
+      {...nativeDisabled}
+      aria-disabled={disabled || undefined}
+      aria-label={label}
+      aria-pressed={checked}
+      bg={checked ? 'accent.solid' : 'transparent'}
+      borderColor={checked ? 'accent.solid' : 'border.emphasized'}
+      borderWidth="1px"
+      cursor={disabled ? 'not-allowed' : 'pointer'}
+      flexShrink="0"
+      h="3"
+      rounded="full"
+      transition="background var(--wb-motion-duration-fast), border-color var(--wb-motion-duration-fast)"
+      w="3"
+      _hover={checked ? TOGGLE_DOT_CHECKED_HOVER_STYLES : TOGGLE_DOT_HOVER_STYLES}
+      onClick={disabled ? undefined : handleClick}
+      {...rest}
+    />
+  );
+
+  return tooltip ? <Tooltip content={tooltip}>{dot}</Tooltip> : dot;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Toolbar.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Toolbar.tsx
new file mode 100644
index 00000000000..e81d4959c99
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Toolbar.tsx
@@ -0,0 +1,60 @@
+import type { ComponentProps } from 'react';
+
+import { Icon, Separator, Stack, type StackProps } from '@chakra-ui/react';
+
+import { IconButton } from './Button';
+import { Tooltip } from './Tooltip';
+
+const toolbarButtonTooltipPositioning = { placement: 'right-start' } as const;
+
+/**
+ * The workbench's floating tool strip, shared by canvas-like surfaces (the
+ * workflow editor today, the canvas later). Vertical by default — designed to
+ * dock against a surface edge. Compose from `ToolbarButton`s (sticky tools via
+ * `isActive`, one-shot actions without) and `ToolbarSeparator`s between
+ * groups.
+ */
+
+export const Toolbar = ({ children, direction = 'column', ...stackProps }: StackProps) => (
+  <Stack
+    bg="bg.subtle"
+    borderColor="border.subtle"
+    borderWidth="1px"
+    direction={direction}
+    gap="0.5"
+    p="1"
+    rounded="lg"
+    shadow="sm"
+    {...stackProps}
+  >
+    {children}
+  </Stack>
+);
+
+export const ToolbarButton = ({
+  icon,
+  isActive,
+  label,
+  ...buttonProps
+}: {
+  icon: React.ElementType;
+  /** Sticky-tool styling; omit for one-shot action buttons. */
+  isActive?: boolean;
+  label: string;
+} & Omit<ComponentProps<typeof IconButton>, 'aria-label'>) => (
+  <Tooltip content={label} positioning={toolbarButtonTooltipPositioning}>
+    <IconButton
+      aria-label={label}
+      aria-pressed={isActive}
+      size="sm"
+      variant={isActive ? 'solid' : 'ghost'}
+      {...buttonProps}
+    >
+      <Icon as={icon} boxSize="3.5" />
+    </IconButton>
+  </Tooltip>
+);
+
+export const ToolbarSeparator = ({ direction = 'column' }: { direction?: 'column' | 'row' }) => (
+  <Separator borderColor="border.subtle" orientation={direction === 'column' ? 'horizontal' : 'vertical'} />
+);
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/Tooltip.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/Tooltip.tsx
new file mode 100644
index 00000000000..02bf2fa4df7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/Tooltip.tsx
@@ -0,0 +1,134 @@
+/* eslint-disable react/react-compiler */
+import { Tooltip as ChakraTooltip, Portal } from '@chakra-ui/react';
+import {
+  cloneElement,
+  isValidElement,
+  type ComponentProps,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+} from 'react';
+
+type TooltipTriggerProps = Omit<ComponentProps<typeof ChakraTooltip.Trigger>, 'children'>;
+
+const ROOT_PROP_NAMES = new Set([
+  'closeDelay',
+  'closeOnClick',
+  'closeOnEscape',
+  'closeOnPointerDown',
+  'closeOnScroll',
+  'defaultOpen',
+  'disabled',
+  'ids',
+  'immediate',
+  'interactive',
+  'lazyMount',
+  'onOpenChange',
+  'open',
+  'openDelay',
+  'positioning',
+  'present',
+  'unmountOnExit',
+]);
+
+const splitTooltipProps = (props: Record<string, unknown>) => {
+  const rootProps: Record<string, unknown> = {};
+  const triggerProps: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(props)) {
+    if (ROOT_PROP_NAMES.has(key)) {
+      rootProps[key] = value;
+    } else {
+      triggerProps[key] = value;
+    }
+  }
+
+  return { rootProps, triggerProps };
+};
+
+const setRef = <T,>(ref: Ref<T> | undefined, value: T | null): void => {
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+
+  if (ref) {
+    ref.current = value;
+  }
+};
+
+const composeRefs =
+  <T,>(...refs: (Ref<T> | undefined)[]): Ref<T> =>
+  (value) => {
+    for (const ref of refs) {
+      setRef(ref, value);
+    }
+  };
+
+type TooltipChildProps = Record<string, unknown> & { ref?: Ref<HTMLButtonElement> };
+
+export interface TooltipProps extends ChakraTooltip.RootProps {
+  showArrow?: boolean;
+  portalled?: boolean;
+  portalRef?: RefObject<HTMLElement | null>;
+  content: ReactNode;
+  contentRef?: Ref<HTMLDivElement>;
+  contentProps?: ChakraTooltip.ContentProps;
+  ref?: Ref<HTMLButtonElement>;
+  triggerProps?: TooltipTriggerProps;
+}
+
+/**
+ * Workbench tooltip. Chrome comes from the `tooltip` slot-recipe override in
+ * `theme/recipes.ts`, so this wrapper only provides the trigger/portal
+ * structure and the `content` convenience API.
+ */
+export const Tooltip = (props: TooltipProps) => {
+  const {
+    showArrow = true,
+    children,
+    disabled,
+    portalled = true,
+    content,
+    contentProps,
+    contentRef,
+    portalRef,
+    ref,
+    triggerProps,
+    ...rest
+  } = props;
+  const { rootProps, triggerProps: triggerPassthroughProps } = splitTooltipProps(rest);
+  const { ref: explicitTriggerRef, ...explicitTriggerProps } = triggerProps ?? {};
+  const mergedTriggerProps = { ...triggerPassthroughProps, ...explicitTriggerProps };
+  const hasTriggerPassthrough = ref || explicitTriggerRef || Object.keys(mergedTriggerProps).length > 0;
+  const triggerChild =
+    hasTriggerPassthrough && isValidElement<TooltipChildProps>(children)
+      ? cloneElement(children as ReactElement<TooltipChildProps>, {
+          ...mergedTriggerProps,
+          ref: composeRefs(children.props.ref, explicitTriggerRef, ref),
+        })
+      : children;
+
+  if (disabled) {
+    return triggerChild;
+  }
+
+  return (
+    <ChakraTooltip.Root {...(rootProps as ChakraTooltip.RootProps)}>
+      <ChakraTooltip.Trigger asChild>{triggerChild}</ChakraTooltip.Trigger>
+      <Portal disabled={!portalled} container={portalRef}>
+        <ChakraTooltip.Positioner>
+          <ChakraTooltip.Content ref={contentRef} {...contentProps}>
+            {showArrow && (
+              <ChakraTooltip.Arrow>
+                <ChakraTooltip.ArrowTip />
+              </ChakraTooltip.Arrow>
+            )}
+            {content}
+          </ChakraTooltip.Content>
+        </ChakraTooltip.Positioner>
+      </Portal>
+    </ChakraTooltip.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/colorPickerSync.test.ts b/invokeai/frontend/webv2/src/workbench/components/ui/colorPickerSync.test.ts
new file mode 100644
index 00000000000..013b8bfb20d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/colorPickerSync.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { shouldSyncExternalColor } from './colorPickerSync';
+
+describe('shouldSyncExternalColor', () => {
+  it('does not sync when the external value is unchanged', () => {
+    expect(shouldSyncExternalColor('#808080', '#808080', '#808080')).toBe(false);
+  });
+
+  it('does not sync when the external value changed to exactly what we last emitted (our own round trip)', () => {
+    // This is the grey-hue-loss scenario: the user drags the hue slider at
+    // S=0, we emit "#808080", the consumer stores it and passes it back as
+    // the new `value` prop -- that must not force a re-parse that would
+    // collapse the hue we're holding onto internally.
+    expect(shouldSyncExternalColor('#808080', '#7f7f7f', '#808080')).toBe(false);
+  });
+
+  it('syncs when the external value changed to something other than what we last emitted', () => {
+    // A genuine external change (e.g. a programmatic reset, or a different
+    // control writing to the same underlying value) should still win.
+    expect(shouldSyncExternalColor('#ff0000', '#808080', '#808080')).toBe(true);
+  });
+
+  it('syncs on the very first divergence even if nothing has been emitted yet', () => {
+    expect(shouldSyncExternalColor('#ff0000', '#000000', '#000000')).toBe(true);
+  });
+
+  it('does not sync when the previous and external values are identical, regardless of last emitted', () => {
+    expect(shouldSyncExternalColor('#123456', '#123456', '#abcdef')).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/colorPickerSync.ts b/invokeai/frontend/webv2/src/workbench/components/ui/colorPickerSync.ts
new file mode 100644
index 00000000000..784eed98ffe
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/colorPickerSync.ts
@@ -0,0 +1,18 @@
+/**
+ * True when `externalValue` (the latest `value` prop given to `ColorPicker`)
+ * should be re-parsed into the picker's internal `Color`, versus kept as-is.
+ *
+ * We only want to re-sync from the external hex string when it reflects a
+ * change the consumer made independently of the picker (e.g. a programmatic
+ * reset) — not the round trip of the hex the picker *just emitted itself* via
+ * `onValueChange`. That round trip loses hue information for any grey/black/
+ * white color (saturation or value = 0, where hex/RGB is hue-agnostic), so
+ * re-parsing it on every render would snap the hue thumb back to whatever
+ * `parseColor` yields for an indeterminate hue — the picker would only ever
+ * be able to *emit* a new hue at S=0, never actually keep it.
+ */
+export const shouldSyncExternalColor = (
+  externalValue: string,
+  previousExternalValue: string,
+  lastEmittedHex: string
+): boolean => externalValue !== previousExternalValue && externalValue !== lastEmittedHex;
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/index.ts b/invokeai/frontend/webv2/src/workbench/components/ui/index.ts
new file mode 100644
index 00000000000..1e10a8129f2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/index.ts
@@ -0,0 +1,18 @@
+export * from './Button';
+export * from './ColorPicker';
+export * from './ConfirmDialog';
+export * from './Field';
+export * from './JsonPreview';
+export * from './Menu';
+export * from './Panel';
+export * from './RenameDialog';
+export * from './ResizableTextarea';
+export * from './Row';
+export * from './Scrollable';
+export * from './Select';
+export * from './Slider';
+export * from './Tabs';
+export * from './toaster';
+export * from './Toolbar';
+export * from './ToggleDot';
+export * from './Tooltip';
diff --git a/invokeai/frontend/webv2/src/workbench/components/ui/toaster.tsx b/invokeai/frontend/webv2/src/workbench/components/ui/toaster.tsx
new file mode 100644
index 00000000000..292a14d9235
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/components/ui/toaster.tsx
@@ -0,0 +1,39 @@
+import {
+  Box,
+  HStack,
+  Portal,
+  Stack,
+  ToastCloseTrigger,
+  ToastDescription,
+  Toaster as ChakraToaster,
+  ToastIndicator,
+  ToastRoot,
+  ToastTitle,
+  createToaster,
+} from '@chakra-ui/react';
+
+export const toaster = createToaster({
+  offsets: { bottom: '1rem', left: '1rem', right: '1rem', top: '1rem' },
+  placement: 'bottom-end',
+  pauseOnPageIdle: true,
+});
+
+export const AppToaster = () => (
+  <Portal>
+    <ChakraToaster toaster={toaster}>
+      {(toast) => (
+        <ToastRoot maxW="calc(100vw - 2rem)" overflowWrap="anywhere" w="24rem">
+          <HStack align="start" gap="3">
+            <ToastIndicator />
+            <Stack gap="1" flex="1">
+              {toast.title ? <ToastTitle>{toast.title}</ToastTitle> : null}
+              {toast.description ? <ToastDescription>{toast.description}</ToastDescription> : null}
+            </Stack>
+            <ToastCloseTrigger />
+          </HStack>
+          <Box display="none" />
+        </ToastRoot>
+      )}
+    </ChakraToaster>
+  </Portal>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/controlAdapters.test.ts b/invokeai/frontend/webv2/src/workbench/controlAdapters.test.ts
new file mode 100644
index 00000000000..6bb3865900f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/controlAdapters.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { CONTROL_ADAPTER_DEFAULTS, normalizeControlAdapter } from './controlAdapters';
+
+describe('normalizeControlAdapter', () => {
+  it.each([
+    ['controlnet', -1, [0, 0.75]],
+    ['t2i_adapter', 2, [0.2, 0.8]],
+    ['control_lora', -1, [0, 1]],
+    ['z_image_control', 0, [0.1, 0.9]],
+  ] as const)('preserves valid %s numeric values', (kind, weight, beginEndStepPct) => {
+    const adapter = { ...CONTROL_ADAPTER_DEFAULTS[kind], beginEndStepPct, weight };
+    expect(normalizeControlAdapter(adapter)).toEqual(adapter);
+  });
+
+  it.each([
+    ['controlnet', Number.NaN],
+    ['controlnet', Number.POSITIVE_INFINITY],
+    ['controlnet', -1.01],
+    ['controlnet', 2.01],
+    ['z_image_control', -0.01],
+    ['z_image_control', 2.01],
+  ] as const)('repairs invalid %s weight %s with its default', (kind, weight) => {
+    const adapter = { ...CONTROL_ADAPTER_DEFAULTS[kind], weight };
+    expect(normalizeControlAdapter(adapter)).toMatchObject({ kind, weight: CONTROL_ADAPTER_DEFAULTS[kind].weight });
+  });
+
+  it.each([
+    [Number.NaN, 1],
+    [0, Number.POSITIVE_INFINITY],
+    [-0.01, 1],
+    [0, 1.01],
+    [0.5, 0.5],
+    [0.8, 0.2],
+  ])('repairs invalid step range [%s, %s] with adapter defaults', (begin, end) => {
+    const adapter = { ...CONTROL_ADAPTER_DEFAULTS.z_image_control, beginEndStepPct: [begin, end] };
+    expect(normalizeControlAdapter(adapter)).toMatchObject({ beginEndStepPct: [0, 1] });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/controlAdapters.ts b/invokeai/frontend/webv2/src/workbench/controlAdapters.ts
new file mode 100644
index 00000000000..415c1905a5f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/controlAdapters.ts
@@ -0,0 +1,92 @@
+import type { CanvasControlAdapterContract } from './types';
+
+export const CONTROL_ADAPTER_DEFAULTS: Readonly<
+  Record<CanvasControlAdapterContract['kind'], CanvasControlAdapterContract>
+> = {
+  control_lora: {
+    beginEndStepPct: [0, 1],
+    controlMode: null,
+    kind: 'control_lora',
+    model: null,
+    weight: 0.75,
+  },
+  controlnet: {
+    beginEndStepPct: [0, 0.75],
+    controlMode: 'balanced',
+    kind: 'controlnet',
+    model: null,
+    weight: 0.75,
+  },
+  t2i_adapter: {
+    beginEndStepPct: [0, 1],
+    controlMode: null,
+    kind: 't2i_adapter',
+    model: null,
+    weight: 1,
+  },
+  z_image_control: {
+    beginEndStepPct: [0, 1],
+    controlMode: null,
+    kind: 'z_image_control',
+    model: null,
+    weight: 0.75,
+  },
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+const isControlAdapterKind = (value: unknown): value is CanvasControlAdapterContract['kind'] =>
+  typeof value === 'string' && Object.hasOwn(CONTROL_ADAPTER_DEFAULTS, value);
+
+export const areControlAdapterValuesValid = (
+  kind: CanvasControlAdapterContract['kind'],
+  weight: unknown,
+  beginEndStepPct: unknown
+): beginEndStepPct is [number, number] => {
+  const minWeight = kind === 'z_image_control' ? 0 : -1;
+  if (typeof weight !== 'number' || !Number.isFinite(weight) || weight < minWeight || weight > 2) {
+    return false;
+  }
+  if (!Array.isArray(beginEndStepPct) || beginEndStepPct.length !== 2) {
+    return false;
+  }
+  const [begin, end] = beginEndStepPct;
+  return (
+    typeof begin === 'number' &&
+    Number.isFinite(begin) &&
+    begin >= 0 &&
+    begin <= 1 &&
+    typeof end === 'number' &&
+    Number.isFinite(end) &&
+    end >= 0 &&
+    end <= 1 &&
+    begin < end
+  );
+};
+
+/** Repairs persisted numeric fields while preserving valid values and adapter kinds. */
+export const normalizeControlAdapter = (value: unknown): unknown => {
+  if (!isRecord(value) || !isControlAdapterKind(value.kind)) {
+    return value;
+  }
+  const defaults = CONTROL_ADAPTER_DEFAULTS[value.kind];
+  const minWeight = value.kind === 'z_image_control' ? 0 : -1;
+  const weight =
+    typeof value.weight === 'number' && Number.isFinite(value.weight) && value.weight >= minWeight && value.weight <= 2
+      ? value.weight
+      : defaults.weight;
+  const beginEndStepPct: [number, number] = areControlAdapterValuesValid(value.kind, weight, value.beginEndStepPct)
+    ? [value.beginEndStepPct[0], value.beginEndStepPct[1]]
+    : [defaults.beginEndStepPct[0], defaults.beginEndStepPct[1]];
+
+  if (value.kind !== 'z_image_control') {
+    return { ...defaults, ...value, beginEndStepPct, weight } satisfies CanvasControlAdapterContract;
+  }
+  return {
+    beginEndStepPct,
+    controlMode: null,
+    kind: 'z_image_control',
+    model: typeof value.model === 'string' ? value.model : null,
+    weight,
+  } satisfies CanvasControlAdapterContract;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/customNodes/api.ts b/invokeai/frontend/webv2/src/workbench/customNodes/api.ts
new file mode 100644
index 00000000000..eec33c2f4a6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/customNodes/api.ts
@@ -0,0 +1,48 @@
+import { apiFetch, apiFetchJson } from '@workbench/backend/http';
+
+/** REST client for the custom nodes manager (`/api/v2/custom_nodes`). */
+
+const CUSTOM_NODES_BASE = '/api/v2/custom_nodes';
+
+export interface NodePackInfo {
+  name: string;
+  path: string;
+  node_count: number;
+  node_types: string[];
+}
+
+export interface NodePackListResponse {
+  node_packs: NodePackInfo[];
+  custom_nodes_path: string;
+}
+
+export interface InstallNodePackResponse {
+  name: string;
+  success: boolean;
+  message: string;
+  workflows_imported: number;
+  requires_dependencies: boolean;
+  dependency_file: string | null;
+}
+
+export interface UninstallNodePackResponse {
+  name: string;
+  success: boolean;
+  message: string;
+}
+
+export const listCustomNodePacks = (): Promise<NodePackListResponse> =>
+  apiFetchJson<NodePackListResponse>(`${CUSTOM_NODES_BASE}/`);
+
+export const installCustomNodePack = (source: string): Promise<InstallNodePackResponse> =>
+  apiFetchJson<InstallNodePackResponse>(`${CUSTOM_NODES_BASE}/install`, {
+    body: JSON.stringify({ source }),
+    method: 'POST',
+  });
+
+export const uninstallCustomNodePack = (packName: string): Promise<UninstallNodePackResponse> =>
+  apiFetchJson<UninstallNodePackResponse>(`${CUSTOM_NODES_BASE}/${encodeURIComponent(packName)}`, { method: 'DELETE' });
+
+export const reloadCustomNodes = async (): Promise<void> => {
+  await apiFetch(`${CUSTOM_NODES_BASE}/reload`, { method: 'POST' });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/customNodes/installLogStore.ts b/invokeai/frontend/webv2/src/workbench/customNodes/installLogStore.ts
new file mode 100644
index 00000000000..9acd002ff55
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/customNodes/installLogStore.ts
@@ -0,0 +1,36 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+export interface CustomNodeInstallLogEntry {
+  id: number;
+  name: string;
+  status: 'installing' | 'completed' | 'error' | 'uninstalled';
+  message?: string;
+  timestamp: number;
+}
+
+const LOG_LIMIT = 50;
+
+const store = createExternalStore<{ log: CustomNodeInstallLogEntry[] }>({ log: [] });
+
+let nextId = 1;
+
+export const addCustomNodeInstallLogEntry = (
+  entry: Omit<CustomNodeInstallLogEntry, 'id' | 'timestamp'>
+): CustomNodeInstallLogEntry => {
+  const nextEntry: CustomNodeInstallLogEntry = {
+    ...entry,
+    id: nextId,
+    timestamp: Date.now(),
+  };
+
+  nextId += 1;
+  store.patchSnapshot({ log: [nextEntry, ...store.getSnapshot().log].slice(0, LOG_LIMIT) });
+
+  return nextEntry;
+};
+
+export const clearCustomNodeInstallLog = (): void => {
+  store.patchSnapshot({ log: [] });
+};
+
+export const useCustomNodeInstallLog = (): CustomNodeInstallLogEntry[] => store.useSelector((snapshot) => snapshot.log);
diff --git a/invokeai/frontend/webv2/src/workbench/customNodes/nodesStore.ts b/invokeai/frontend/webv2/src/workbench/customNodes/nodesStore.ts
new file mode 100644
index 00000000000..da7474a6030
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/customNodes/nodesStore.ts
@@ -0,0 +1,65 @@
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { createExternalStore } from '@workbench/externalStore';
+
+import type { NodePackInfo } from './api';
+
+import { listCustomNodePacks } from './api';
+
+export interface CustomNodesSnapshot {
+  nodePacks: NodePackInfo[];
+  customNodesPath: string | null;
+  status: 'idle' | 'loading' | 'loaded' | 'error';
+  error: string | null;
+}
+
+const store = createExternalStore<CustomNodesSnapshot>({
+  customNodesPath: null,
+  error: null,
+  nodePacks: [],
+  status: 'idle',
+});
+
+let inflightRefresh: Promise<void> | null = null;
+
+export const refreshCustomNodePacks = (): Promise<void> => {
+  if (inflightRefresh) {
+    return inflightRefresh;
+  }
+
+  store.patchSnapshot({ status: store.getSnapshot().status === 'loaded' ? 'loaded' : 'loading' });
+
+  inflightRefresh = listCustomNodePacks()
+    .then((response) => {
+      store.patchSnapshot({
+        customNodesPath: response.custom_nodes_path,
+        error: null,
+        nodePacks: response.node_packs,
+        status: 'loaded',
+      });
+    })
+    .catch((error: unknown) => {
+      store.patchSnapshot({
+        error: getApiErrorMessage(error, 'Failed to load custom node packs.'),
+        status: store.getSnapshot().nodePacks.length > 0 ? 'loaded' : 'error',
+      });
+    })
+    .finally(() => {
+      inflightRefresh = null;
+    });
+
+  return inflightRefresh;
+};
+
+export const ensureCustomNodePacksLoaded = (): void => {
+  if (store.getSnapshot().status === 'idle') {
+    void refreshCustomNodePacks();
+  }
+};
+
+export const removeCustomNodePackFromStore = (packName: string): void => {
+  store.patchSnapshot({ nodePacks: store.getSnapshot().nodePacks.filter((pack) => pack.name !== packName) });
+};
+
+export const useCustomNodesSelector = store.useSelector;
+
+export const useCustomNodesSnapshot = (): CustomNodesSnapshot => store.useSnapshot();
diff --git a/invokeai/frontend/webv2/src/workbench/customNodes/nodesUiStore.ts b/invokeai/frontend/webv2/src/workbench/customNodes/nodesUiStore.ts
new file mode 100644
index 00000000000..c2b6fc02711
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/customNodes/nodesUiStore.ts
@@ -0,0 +1,45 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+/**
+ * Session-lived UI state for the Launchpad nodes manager. Keeping the active
+ * detail tab, selected pack, search term, and add-node form tab in an external
+ * store (the same pattern as the models UI store) means nothing resets while
+ * the user navigates within the manager.
+ */
+
+export type NodesManagerTab = 'details' | 'add';
+export type AddNodesTab = 'git' | 'scan';
+
+export interface NodesUiSnapshot {
+  activeTab: NodesManagerTab;
+  addTab: AddNodesTab;
+  activePackName: string | null;
+  activityExpanded: boolean;
+  searchTerm: string;
+}
+
+const store = createExternalStore<NodesUiSnapshot>({
+  activeTab: 'details',
+  activePackName: null,
+  activityExpanded: false,
+  addTab: 'git',
+  searchTerm: '',
+});
+
+export const updateNodesUi = (next: Partial<NodesUiSnapshot>): void => store.patchSnapshot(next);
+
+export const openNodePackDetail = (activePackName: string): void => {
+  updateNodesUi({ activePackName, activeTab: 'details' });
+};
+
+export const openNodesManagerTab = (activeTab: NodesManagerTab): void => {
+  updateNodesUi({ activeTab });
+};
+
+export const setNodeActivityExpanded = (activityExpanded: boolean): void => {
+  updateNodesUi({ activityExpanded });
+};
+
+export const useNodesUiSelector = store.useSelector;
+
+export const useNodesUi = (): NodesUiSnapshot => store.useSnapshot();
diff --git a/invokeai/frontend/webv2/src/workbench/diagnostics/logger.test.ts b/invokeai/frontend/webv2/src/workbench/diagnostics/logger.test.ts
new file mode 100644
index 00000000000..a2adad10d75
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/diagnostics/logger.test.ts
@@ -0,0 +1,129 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  clearProjectDiagnostics,
+  configureDiagnostics,
+  createProjectLogger,
+  getProjectDiagnostics,
+  recordDiagnosticTiming,
+} from './logger';
+
+beforeEach(() => {
+  clearProjectDiagnostics('project-a');
+  clearProjectDiagnostics('project-b');
+  configureDiagnostics({
+    enabled: true,
+    level: 'trace',
+    namespaces: ['workflows', 'system', 'queue'],
+    performanceTimingsEnabled: true,
+  });
+  vi.setSystemTime(new Date('2026-06-29T00:00:00.000Z'));
+});
+
+describe('diagnostics logger', () => {
+  it('records entries scoped to the source project', () => {
+    const logger = createProjectLogger('workflows', {
+      instanceId: 'workflow:center',
+      kind: 'widget',
+      projectId: 'project-a',
+      region: 'center',
+      typeId: 'workflow',
+    });
+
+    logger.info({ nodes: 120 }, 'Workflow loaded');
+
+    expect(getProjectDiagnostics('project-a')).toMatchObject([
+      {
+        context: { nodes: 120 },
+        createdAt: '2026-06-29T00:00:00.000Z',
+        level: 'info',
+        message: 'Workflow loaded',
+        namespace: 'workflows',
+        source: {
+          instanceId: 'workflow:center',
+          kind: 'widget',
+          projectId: 'project-a',
+          region: 'center',
+          typeId: 'workflow',
+        },
+      },
+    ]);
+    expect(getProjectDiagnostics('project-b')).toEqual([]);
+  });
+
+  it('records timing entries as normal diagnostics', () => {
+    recordDiagnosticTiming({ area: 'persistence', kind: 'workbench', projectId: 'project-a' }, 'workbench:save', 12.34);
+
+    expect(getProjectDiagnostics('project-a')).toMatchObject([
+      {
+        durationMs: 12.34,
+        level: 'debug',
+        message: 'workbench:save completed in 12.3ms',
+        namespace: 'performance',
+        source: { area: 'persistence', kind: 'workbench', projectId: 'project-a' },
+      },
+    ]);
+  });
+
+  it('clears a single project without clearing other projects', () => {
+    createProjectLogger('system', { area: 'runtime', kind: 'workbench', projectId: 'project-a' }).error('A failed');
+    createProjectLogger('system', { area: 'runtime', kind: 'workbench', projectId: 'project-b' }).warn('B warned');
+
+    clearProjectDiagnostics('project-a');
+
+    expect(getProjectDiagnostics('project-a')).toEqual([]);
+    expect(getProjectDiagnostics('project-b')).toHaveLength(1);
+  });
+
+  it('filters entries by project logging settings', () => {
+    configureDiagnostics({
+      enabled: true,
+      level: 'warn',
+      namespaces: ['system'],
+      performanceTimingsEnabled: true,
+    });
+
+    createProjectLogger('workflows', { area: 'runtime', kind: 'workbench', projectId: 'project-a' }).error(
+      'Wrong namespace'
+    );
+    createProjectLogger('system', { area: 'runtime', kind: 'workbench', projectId: 'project-a' }).debug('Too quiet');
+    createProjectLogger('system', { area: 'runtime', kind: 'workbench', projectId: 'project-a' }).warn('Recorded');
+
+    expect(getProjectDiagnostics('project-a')).toMatchObject([{ level: 'warn', message: 'Recorded' }]);
+  });
+
+  it('can disable project diagnostics and performance timings independently', () => {
+    configureDiagnostics({
+      enabled: false,
+      level: 'trace',
+      namespaces: ['system'],
+      performanceTimingsEnabled: true,
+    });
+
+    createProjectLogger('system', { area: 'runtime', kind: 'workbench', projectId: 'project-a' }).error('Skipped');
+
+    configureDiagnostics({
+      enabled: true,
+      level: 'trace',
+      namespaces: ['system'],
+      performanceTimingsEnabled: false,
+    });
+
+    recordDiagnosticTiming({ area: 'runtime', kind: 'workbench', projectId: 'project-a' }, 'workbench:test', 1.2);
+
+    expect(getProjectDiagnostics('project-a')).toEqual([]);
+  });
+
+  it('applies the current diagnostics config to every project', () => {
+    configureDiagnostics({
+      enabled: true,
+      level: 'warn',
+      namespaces: ['queue'],
+      performanceTimingsEnabled: true,
+    });
+
+    createProjectLogger('queue', { area: 'autosave', kind: 'workbench', projectId: 'project-b' }).error('Recorded');
+
+    expect(getProjectDiagnostics('project-b')).toMatchObject([{ level: 'error', message: 'Recorded' }]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/diagnostics/logger.ts b/invokeai/frontend/webv2/src/workbench/diagnostics/logger.ts
new file mode 100644
index 00000000000..e920d613c22
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/diagnostics/logger.ts
@@ -0,0 +1,193 @@
+import type { DeveloperLogLevel, DeveloperLogNamespace, WidgetContributionSource } from '@workbench/types';
+
+import { useSyncExternalStore } from 'react';
+
+const MAX_PROJECT_DIAGNOSTIC_ENTRIES = 500;
+const EMPTY_DIAGNOSTIC_ENTRIES: DiagnosticEntry[] = [];
+
+const LOG_LEVEL_ORDER: Record<DeveloperLogLevel, number> = {
+  debug: 20,
+  error: 50,
+  fatal: 60,
+  info: 30,
+  trace: 10,
+  warn: 40,
+};
+
+export type DiagnosticSource =
+  | ({ kind: 'widget' } & WidgetContributionSource)
+  | { area: string; kind: 'workbench'; projectId?: string };
+
+export interface DiagnosticEntry {
+  context?: Record<string, unknown>;
+  createdAt: string;
+  durationMs?: number;
+  id: string;
+  level: DeveloperLogLevel;
+  message: string;
+  namespace: DeveloperLogNamespace | 'performance';
+  source: DiagnosticSource;
+}
+
+export interface DiagnosticsConfig {
+  enabled: boolean;
+  level: DeveloperLogLevel;
+  namespaces: DeveloperLogNamespace[];
+  performanceTimingsEnabled: boolean;
+}
+
+type DiagnosticListener = () => void;
+
+type LogArgument = string | Record<string, unknown>;
+
+const entriesByProjectId = new Map<string, DiagnosticEntry[]>();
+const listenersByProjectId = new Map<string, Set<DiagnosticListener>>();
+
+let diagnosticsConfig: DiagnosticsConfig = {
+  enabled: true,
+  level: 'warn',
+  namespaces: ['system', 'queue', 'workflows'],
+  performanceTimingsEnabled: false,
+};
+
+let nextDiagnosticEntryId = 0;
+
+const getProjectIdFromSource = (source: DiagnosticSource): string | null => source.projectId ?? null;
+
+const shouldRecordEntry = (entry: Omit<DiagnosticEntry, 'createdAt' | 'id'>): boolean => {
+  if (entry.namespace === 'performance') {
+    return diagnosticsConfig.performanceTimingsEnabled;
+  }
+
+  return (
+    diagnosticsConfig.enabled &&
+    LOG_LEVEL_ORDER[entry.level] >= LOG_LEVEL_ORDER[diagnosticsConfig.level] &&
+    diagnosticsConfig.namespaces.includes(entry.namespace)
+  );
+};
+
+const getProjectEntries = (projectId: string): DiagnosticEntry[] => {
+  const entries = entriesByProjectId.get(projectId) ?? [];
+
+  if (!entriesByProjectId.has(projectId)) {
+    entriesByProjectId.set(projectId, entries);
+  }
+
+  return entries;
+};
+
+const getProjectEntriesSnapshot = (projectId: string): DiagnosticEntry[] =>
+  entriesByProjectId.get(projectId) ?? EMPTY_DIAGNOSTIC_ENTRIES;
+
+const notifyProjectDiagnostics = (projectId: string): void => {
+  for (const listener of listenersByProjectId.get(projectId) ?? []) {
+    listener();
+  }
+};
+
+const normalizeLogArgs = (
+  first: LogArgument,
+  second?: string
+): { context?: Record<string, unknown>; message: string } => {
+  if (typeof first === 'string') {
+    return { message: first };
+  }
+
+  return { context: first, message: second ?? '' };
+};
+
+export const recordDiagnosticEntry = (entry: Omit<DiagnosticEntry, 'createdAt' | 'id'>): DiagnosticEntry | null => {
+  const projectId = getProjectIdFromSource(entry.source);
+
+  if (!projectId) {
+    return null;
+  }
+
+  if (!shouldRecordEntry(entry)) {
+    return null;
+  }
+
+  const nextEntry: DiagnosticEntry = {
+    ...entry,
+    createdAt: new Date().toISOString(),
+    id: `diagnostic-${nextDiagnosticEntryId++}`,
+  };
+  const entries = [nextEntry, ...getProjectEntries(projectId)].slice(0, MAX_PROJECT_DIAGNOSTIC_ENTRIES);
+
+  entriesByProjectId.set(projectId, entries);
+
+  notifyProjectDiagnostics(projectId);
+
+  return nextEntry;
+};
+
+export const createProjectLogger = (namespace: DeveloperLogNamespace, source: DiagnosticSource) => {
+  const log = (level: DeveloperLogLevel, first: LogArgument, second?: string): void => {
+    const { context, message } = normalizeLogArgs(first, second);
+
+    recordDiagnosticEntry({ context, level, message, namespace, source });
+  };
+
+  return {
+    debug: (first: LogArgument, second?: string) => log('debug', first, second),
+    error: (first: LogArgument, second?: string) => log('error', first, second),
+    fatal: (first: LogArgument, second?: string) => log('fatal', first, second),
+    info: (first: LogArgument, second?: string) => log('info', first, second),
+    trace: (first: LogArgument, second?: string) => log('trace', first, second),
+    warn: (first: LogArgument, second?: string) => log('warn', first, second),
+  };
+};
+
+export const configureDiagnostics = (config: DiagnosticsConfig): void => {
+  diagnosticsConfig = { ...config, namespaces: [...config.namespaces] };
+};
+
+export const canRecordDiagnosticTiming = (source?: DiagnosticSource): source is DiagnosticSource => {
+  if (!source?.projectId) {
+    return false;
+  }
+
+  return diagnosticsConfig.performanceTimingsEnabled;
+};
+
+export const recordDiagnosticTiming = (
+  source: DiagnosticSource,
+  name: string,
+  durationMs: number
+): DiagnosticEntry | null =>
+  recordDiagnosticEntry({
+    durationMs,
+    level: 'debug',
+    message: `${name} completed in ${durationMs.toFixed(1)}ms`,
+    namespace: 'performance',
+    source,
+  });
+
+export const getProjectDiagnostics = (projectId: string): DiagnosticEntry[] => [...getProjectEntries(projectId)];
+
+export const useProjectDiagnostics = (projectId: string): DiagnosticEntry[] =>
+  useSyncExternalStore(
+    (listener) => subscribeProjectDiagnostics(projectId, listener),
+    () => getProjectEntriesSnapshot(projectId),
+    () => EMPTY_DIAGNOSTIC_ENTRIES
+  );
+
+export const clearProjectDiagnostics = (projectId: string): void => {
+  entriesByProjectId.delete(projectId);
+  notifyProjectDiagnostics(projectId);
+};
+
+export const subscribeProjectDiagnostics = (projectId: string, listener: DiagnosticListener): (() => void) => {
+  const listeners = listenersByProjectId.get(projectId) ?? new Set<DiagnosticListener>();
+
+  listeners.add(listener);
+  listenersByProjectId.set(projectId, listeners);
+
+  return () => {
+    listeners.delete(listener);
+
+    if (listeners.size === 0) {
+      listenersByProjectId.delete(projectId);
+    }
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/extensions/README.md b/invokeai/frontend/webv2/src/workbench/extensions/README.md
new file mode 100644
index 00000000000..3864f04f13d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/extensions/README.md
@@ -0,0 +1,64 @@
+# Workbench Widget Extensions
+
+The workbench shell is now structured around widget types and widget instances.
+
+- A widget manifest registers a widget type.
+- A project layout stores widget instances in ordered region lists.
+- A widget instance owns persisted project state.
+- The shell owns placement, drag/drop, resizing, failure containment, and contribution APIs.
+
+## Manifest Shape
+
+Widgets should provide component icons, not icon IDs or import strings:
+
+```tsx
+import { LayersIcon } from 'lucide-react';
+
+export const manifest = {
+  id: 'invoke.layers',
+  version: 1,
+  label: 'Layers',
+  labelText: 'Layers',
+  icon: LayersIcon,
+  allowedRegions: ['right'],
+  allowMultiple: false,
+  state: {
+    version: 1,
+    persistence: 'project',
+    createInitial: () => ({}),
+  },
+  view: LayersWidgetView,
+};
+```
+
+Third-party widgets should ship icons as JSX/SVG components in their compiled widget bundle.
+
+## Discovery Options
+
+Custom nodes today are server-discovered. The backend scans `custom_nodes_path`, skips hidden/underscore directories, requires `__init__.py`, and imports each pack with Python `importlib`. The management API can clone a git repo into that directory, reload nodes, and list installed packs.
+
+Widgets should not mirror Python import execution directly in the browser. The safer server-first shape is:
+
+- Add a configured `widgets_path` beside `custom_nodes_path`.
+- Require each widget pack directory to include a manifest file, for example `invokeai-widget.json`.
+- Let the server list widget packs and expose static compiled assets from each pack.
+- The browser fetches a signed/validated widget catalog from the server.
+- The shell dynamically imports approved widget entrypoints by URL only after the server has validated the pack manifest.
+
+This avoids symlink assumptions and lets multi-user/admin rules follow the existing custom-node management pattern.
+
+## Missing Core Systems
+
+The extension API stubs exist in `extensionApi.ts`, but these systems still need real shell features:
+
+- Command registry UI and lifecycle ownership.
+- Command palette UI.
+- Hotkey manager with context-aware `when` clauses.
+- Global search UI and ranked result aggregation.
+- Menu contribution rendering beyond widget header menus.
+- Toolbar contribution rendering for locations like `center.tabs.trailing` and status bar slots.
+- Extension install/uninstall/reload API for widget packs.
+- Widget pack trust, signing, permission prompts, and admin policy.
+- Extension asset serving and cache invalidation.
+
+Undo/redo history controls were removed from normal widget registration because they render buttons and do not belong inside another button-like widget tab/slot. They should return as command and toolbar contributions when the command/toolbar systems exist.
diff --git a/invokeai/frontend/webv2/src/workbench/extensions/contributionSource.test.ts b/invokeai/frontend/webv2/src/workbench/extensions/contributionSource.test.ts
new file mode 100644
index 00000000000..5fb22c84729
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/extensions/contributionSource.test.ts
@@ -0,0 +1,44 @@
+import type { WidgetContributionSource } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  areWidgetContributionSourcesEqual,
+  getWidgetContributionRegistrationKey,
+  getWidgetContributionSourceKey,
+} from './contributionSource';
+
+const source = (overrides: Partial<WidgetContributionSource> = {}): WidgetContributionSource => ({
+  instanceId: 'generate',
+  projectId: 'project-1',
+  region: 'left',
+  typeId: 'generate',
+  ...overrides,
+});
+
+describe('areWidgetContributionSourcesEqual', () => {
+  it('matches widget contribution sources by project, region, type, and instance', () => {
+    expect(areWidgetContributionSourcesEqual(source(), source())).toBe(true);
+    expect(areWidgetContributionSourcesEqual(source(), source({ projectId: 'project-2' }))).toBe(false);
+    expect(areWidgetContributionSourcesEqual(source(), source({ instanceId: 'generate:2' }))).toBe(false);
+    expect(areWidgetContributionSourcesEqual(source(), null)).toBe(false);
+  });
+});
+
+describe('getWidgetContributionRegistrationKey', () => {
+  it('creates stable replacement keys per command id and source', () => {
+    expect(getWidgetContributionRegistrationKey('generate.run', source())).toBe(
+      getWidgetContributionRegistrationKey('generate.run', source())
+    );
+    expect(getWidgetContributionRegistrationKey('generate.run', source())).not.toBe(
+      getWidgetContributionRegistrationKey('generate.run', source({ projectId: 'project-2' }))
+    );
+    expect(getWidgetContributionRegistrationKey('generate.run', undefined)).not.toBe(
+      getWidgetContributionRegistrationKey('generate.run', source())
+    );
+  });
+
+  it('keeps source keys stable without depending on object identity', () => {
+    expect(getWidgetContributionSourceKey(source())).toBe(getWidgetContributionSourceKey({ ...source() }));
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/extensions/contributionSource.ts b/invokeai/frontend/webv2/src/workbench/extensions/contributionSource.ts
new file mode 100644
index 00000000000..b454643f2a5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/extensions/contributionSource.ts
@@ -0,0 +1,29 @@
+import type { WidgetContributionSource } from '@workbench/types';
+
+const GLOBAL_SOURCE_KEY = 'global';
+
+export const areWidgetContributionSourcesEqual = (
+  left: WidgetContributionSource | null | undefined,
+  right: WidgetContributionSource | null | undefined
+): boolean => {
+  if (!left || !right) {
+    return false;
+  }
+
+  return (
+    left.projectId === right.projectId &&
+    left.region === right.region &&
+    left.typeId === right.typeId &&
+    left.instanceId === right.instanceId
+  );
+};
+
+export const getWidgetContributionSourceKey = (source: WidgetContributionSource | null | undefined): string =>
+  source
+    ? JSON.stringify(['widget', source.projectId, source.region, source.typeId, source.instanceId])
+    : GLOBAL_SOURCE_KEY;
+
+export const getWidgetContributionRegistrationKey = (
+  id: string,
+  source: WidgetContributionSource | null | undefined
+): string => JSON.stringify([id, getWidgetContributionSourceKey(source)]);
diff --git a/invokeai/frontend/webv2/src/workbench/extensions/extensionApi.test.ts b/invokeai/frontend/webv2/src/workbench/extensions/extensionApi.test.ts
new file mode 100644
index 00000000000..fa47c45b2f1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/extensions/extensionApi.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { commandApi } from './extensionApi';
+
+describe('commandApi', () => {
+  it('registers, executes, and disposes commands by id', async () => {
+    const handler = vi.fn(() => 'ok');
+    const dispose = commandApi.register({ handler, id: 'test.command', title: 'Test command' });
+
+    await expect(commandApi.execute('test.command', 'arg')).resolves.toBe('ok');
+    expect(handler).toHaveBeenCalledWith('arg');
+
+    dispose();
+
+    await expect(commandApi.execute('test.command')).resolves.toBeUndefined();
+  });
+
+  it('replaces duplicate global command registrations', async () => {
+    const firstHandler = vi.fn(() => 'first');
+    const secondHandler = vi.fn(() => 'second');
+    const disposeFirst = commandApi.register({ handler: firstHandler, id: 'test.duplicate-command', title: 'First' });
+    const disposeSecond = commandApi.register({
+      handler: secondHandler,
+      id: 'test.duplicate-command',
+      title: 'Second',
+    });
+
+    await expect(commandApi.execute('test.duplicate-command')).resolves.toBe('second');
+
+    disposeFirst();
+
+    await expect(commandApi.execute('test.duplicate-command')).resolves.toBe('second');
+
+    disposeSecond();
+
+    await expect(commandApi.execute('test.duplicate-command')).resolves.toBeUndefined();
+  });
+
+  it('replaces duplicate command registrations from the same source', async () => {
+    const firstHandler = vi.fn(() => 'first');
+    const secondHandler = vi.fn(() => 'second');
+    const source = { instanceId: 'alpha', projectId: 'project-1', region: 'right', typeId: 'test-widget' } as const;
+    const disposeFirst = commandApi.register({
+      handler: firstHandler,
+      id: 'test.replace-command',
+      source,
+      title: 'First',
+    });
+    const disposeSecond = commandApi.register({
+      handler: secondHandler,
+      id: 'test.replace-command',
+      source,
+      title: 'Second',
+    });
+
+    await expect(commandApi.executeForSource('test.replace-command', source)).resolves.toBe('second');
+
+    disposeFirst();
+
+    await expect(commandApi.executeForSource('test.replace-command', source)).resolves.toBe('second');
+
+    disposeSecond();
+
+    await expect(commandApi.executeForSource('test.replace-command', source)).resolves.toBeUndefined();
+  });
+
+  it('does not execute a command registered by the same widget source in another project', async () => {
+    const handler = vi.fn(() => 'project-1');
+    const dispose = commandApi.register({
+      handler,
+      id: 'test.project-command',
+      source: { instanceId: 'alpha', projectId: 'project-1', region: 'right', typeId: 'test-widget' },
+      title: 'Project command',
+    });
+
+    await expect(
+      commandApi.executeForSource('test.project-command', {
+        instanceId: 'alpha',
+        projectId: 'project-2',
+        region: 'right',
+        typeId: 'test-widget',
+      })
+    ).resolves.toBeUndefined();
+    expect(handler).not.toHaveBeenCalled();
+
+    dispose();
+  });
+
+  it('does not fall back to another widget instance when executing for a source', async () => {
+    const handler = vi.fn(() => 'beta');
+    const dispose = commandApi.register({
+      handler,
+      id: 'test.scoped-command',
+      source: { instanceId: 'beta', projectId: 'project-1', region: 'right', typeId: 'test-widget' },
+      title: 'Scoped command',
+    });
+
+    await expect(
+      commandApi.executeForSource('test.scoped-command', {
+        instanceId: 'alpha',
+        projectId: 'project-1',
+        region: 'right',
+        typeId: 'test-widget',
+      })
+    ).resolves.toBeUndefined();
+    expect(handler).not.toHaveBeenCalled();
+
+    dispose();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/extensions/extensionApi.ts b/invokeai/frontend/webv2/src/workbench/extensions/extensionApi.ts
new file mode 100644
index 00000000000..fbc7e3e0f09
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/extensions/extensionApi.ts
@@ -0,0 +1,95 @@
+import type {
+  WidgetCommandApi,
+  WidgetCommandContribution,
+  WidgetCommandPaletteApi,
+  WidgetCommandPaletteContribution,
+  WidgetContributionSource,
+  WidgetHotkeyApi,
+  WidgetHotkeyContribution,
+  WidgetMenuApi,
+  WidgetMenuContribution,
+  WidgetSearchApi,
+  WidgetSearchProvider,
+  WidgetToolbarApi,
+  WidgetToolbarContribution,
+} from '@workbench/types';
+
+import { createCollectionStore } from '@workbench/externalStore';
+
+import { areWidgetContributionSourcesEqual, getWidgetContributionRegistrationKey } from './contributionSource';
+
+const noopDispose = (): void => {};
+
+const commandStore = createCollectionStore<WidgetCommandContribution>();
+const hotkeyStore = createCollectionStore<WidgetHotkeyContribution>();
+const menuStore = createCollectionStore<WidgetMenuContribution>();
+const paletteStore = createCollectionStore<WidgetCommandPaletteContribution>();
+const searchStore = createCollectionStore<WidgetSearchProvider>();
+const toolbarStore = createCollectionStore<WidgetToolbarContribution>();
+
+const findCommand = (
+  commandId: string,
+  source: WidgetContributionSource | null = null
+): WidgetCommandContribution | undefined =>
+  source
+    ? (commandStore.findLatest(
+        (candidate) => candidate.id === commandId && areWidgetContributionSourcesEqual(candidate.source, source)
+      ) ?? commandStore.findLatest((candidate) => candidate.id === commandId && !candidate.source))
+    : commandStore.findLatest((candidate) => candidate.id === commandId && !candidate.source);
+
+export const commandApi: WidgetCommandApi = {
+  execute(commandId, ...args) {
+    const command = findCommand(commandId);
+
+    return Promise.resolve(command ? command.handler(...args) : undefined);
+  },
+  executeForSource(commandId, source, ...args) {
+    const command = findCommand(commandId, source);
+
+    return Promise.resolve(command ? command.handler(...args) : undefined);
+  },
+  register(command) {
+    return commandStore.register(command, getWidgetContributionRegistrationKey(command.id, command.source));
+  },
+};
+
+export const hotkeyApi: WidgetHotkeyApi = {
+  register(hotkey) {
+    return hotkeyStore.register(hotkey, getWidgetContributionRegistrationKey(hotkey.id, hotkey.source));
+  },
+};
+
+export const menuApi: WidgetMenuApi = {
+  register(menu) {
+    return menuStore.register(menu, getWidgetContributionRegistrationKey(menu.id, menu.source));
+  },
+};
+
+export const commandPaletteApi: WidgetCommandPaletteApi = {
+  register(entry) {
+    return paletteStore.register(entry, entry.commandId);
+  },
+};
+
+export const searchApi: WidgetSearchApi = {
+  registerProvider(provider) {
+    return searchStore.register(provider, provider.id);
+  },
+};
+
+export const toolbarApi: WidgetToolbarApi = {
+  register(toolbar) {
+    return toolbarStore.register(toolbar, toolbar.id);
+  },
+};
+
+export const extensionContributionStores = {
+  commands: commandStore,
+  hotkeys: hotkeyStore,
+  menus: menuStore,
+  palette: paletteStore,
+  search: searchStore,
+  toolbars: toolbarStore,
+};
+
+export const disposeExtensionContribution = noopDispose;
diff --git a/invokeai/frontend/webv2/src/workbench/externalStore.test.ts b/invokeai/frontend/webv2/src/workbench/externalStore.test.ts
new file mode 100644
index 00000000000..7a39c7acac4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/externalStore.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createCollectionStore, createExternalStore, createKeyedTransientStore } from './externalStore';
+
+describe('createExternalStore', () => {
+  it('does not notify listeners for identical snapshots or empty patches', () => {
+    const initial = { count: 0, label: 'idle' };
+    const store = createExternalStore(initial);
+    const listener = vi.fn();
+
+    store.subscribe(listener);
+
+    store.setSnapshot(initial);
+    store.setSnapshot({ count: 0, label: 'idle' });
+    store.patchSnapshot({});
+    store.patchSnapshot({ count: 0 });
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('notifies when a patch adds an undefined optional key', () => {
+    const store = createExternalStore<{ count: number; label?: string }>({ count: 0 });
+    const listener = vi.fn();
+
+    store.subscribe(listener);
+    store.patchSnapshot({ label: undefined });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(Object.prototype.hasOwnProperty.call(store.getSnapshot(), 'label')).toBe(true);
+  });
+});
+
+describe('createKeyedTransientStore', () => {
+  it('notifies only listeners for the changed key and global listeners', () => {
+    const store = createKeyedTransientStore<string, number>();
+    const keyListener = vi.fn();
+    const otherKeyListener = vi.fn();
+    const globalListener = vi.fn();
+
+    store.subscribeKey('a', keyListener);
+    store.subscribeKey('b', otherKeyListener);
+    store.subscribe(globalListener);
+
+    store.set('a', 1);
+
+    expect(keyListener).toHaveBeenCalledTimes(1);
+    expect(otherKeyListener).not.toHaveBeenCalled();
+    expect(globalListener).toHaveBeenCalledTimes(1);
+    expect(store.get('a')).toBe(1);
+  });
+
+  it('does not notify when setting an identical value', () => {
+    const store = createKeyedTransientStore<string, number>();
+    const listener = vi.fn();
+
+    store.set('a', 1);
+    store.subscribeKey('a', listener);
+    store.set('a', 1);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
+
+describe('createCollectionStore', () => {
+  it('returns a stable list snapshot until registrations change', () => {
+    const store = createCollectionStore<{ id: string }>();
+
+    const empty = store.list();
+
+    expect(store.list()).toBe(empty);
+
+    const dispose = store.register({ id: 'first' }, 'first');
+    const populated = store.list();
+
+    expect(populated).not.toBe(empty);
+    expect(store.list()).toBe(populated);
+
+    dispose();
+
+    expect(store.list()).not.toBe(populated);
+    expect(store.list()).toEqual([]);
+  });
+
+  it('replaces duplicate logical registrations and only the active disposer can clear them', () => {
+    const store = createCollectionStore<{ id: string; value: string }>();
+    const disposeFirst = store.register({ id: 'duplicate', value: 'first' }, 'duplicate');
+    const disposeSecond = store.register({ id: 'duplicate', value: 'second' }, 'duplicate');
+
+    expect(store.list()).toEqual([{ id: 'duplicate', value: 'second' }]);
+    expect(store.findLatest((item) => item.id === 'duplicate')?.value).toBe('second');
+
+    disposeFirst();
+
+    expect(store.findLatest((item) => item.id === 'duplicate')?.value).toBe('second');
+
+    disposeSecond();
+
+    expect(store.findLatest((item) => item.id === 'duplicate')).toBeUndefined();
+  });
+
+  it('keeps registrations with different logical keys side by side', () => {
+    const store = createCollectionStore<{ id: string; value: string }>();
+    const disposeFirst = store.register({ id: 'duplicate', value: 'first' }, 'duplicate:first');
+    const disposeSecond = store.register({ id: 'duplicate', value: 'second' }, 'duplicate:second');
+
+    expect(store.list()).toEqual([
+      { id: 'duplicate', value: 'first' },
+      { id: 'duplicate', value: 'second' },
+    ]);
+
+    disposeFirst();
+
+    expect(store.list()).toEqual([{ id: 'duplicate', value: 'second' }]);
+
+    disposeSecond();
+
+    expect(store.findLatest((item) => item.id === 'duplicate')).toBeUndefined();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/externalStore.ts b/invokeai/frontend/webv2/src/workbench/externalStore.ts
new file mode 100644
index 00000000000..d0a26ae455c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/externalStore.ts
@@ -0,0 +1,238 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { shallowEqual, useExternalStoreSelector, type EqualityFn } from './workbenchSelectors';
+
+/**
+ * Minimal factory for module-level stores backed by `useSyncExternalStore`.
+ * For backend-owned or session-lived state shared across widget surfaces
+ * (model library, install jobs, starter catalog) where the workbench reducer
+ * is the wrong home. See `models/modelsStore.ts` for the canonical usage.
+ */
+
+/** A bare listener channel, for auxiliary data living beside a snapshot. */
+export interface ListenerChannel {
+  subscribe: (listener: () => void) => () => void;
+  notify: () => void;
+}
+
+export const createListenerChannel = (): ListenerChannel => {
+  const listeners = new Set<() => void>();
+
+  return {
+    notify: () => {
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+};
+
+export interface ExternalStore<Snapshot extends object> extends ListenerChannel {
+  getSnapshot: () => Snapshot;
+  /** Replace the snapshot and notify subscribers. */
+  setSnapshot: (next: Snapshot) => void;
+  /** Merge a partial snapshot and notify subscribers. */
+  patchSnapshot: (next: Partial<Snapshot>) => void;
+  /** Replace without notifying — for data read imperatively, never rendered. */
+  setSnapshotSilently: (next: Snapshot) => void;
+  /** Subscribe the calling component to the snapshot. */
+  useSnapshot: () => Snapshot;
+  /** Subscribe the calling component to a selected snapshot value. */
+  useSelector: <Selected>(
+    selector: (snapshot: Snapshot) => Selected,
+    isEqual?: (left: Selected, right: Selected) => boolean
+  ) => Selected;
+}
+
+const hasPatchChanges = <Snapshot extends object>(snapshot: Snapshot, patch: Partial<Snapshot>): boolean =>
+  Object.entries(patch).some(
+    ([key, value]) =>
+      !Object.prototype.hasOwnProperty.call(snapshot, key) || !Object.is(snapshot[key as keyof Snapshot], value)
+  );
+
+export const createExternalStore = <Snapshot extends object>(initialSnapshot: Snapshot): ExternalStore<Snapshot> => {
+  let snapshot = initialSnapshot;
+  const channel = createListenerChannel();
+
+  const getSnapshot = (): Snapshot => snapshot;
+
+  const setSnapshot = (next: Snapshot): void => {
+    if (shallowEqual(next, snapshot)) {
+      return;
+    }
+
+    snapshot = next;
+    channel.notify();
+  };
+
+  const useSnapshot = (): Snapshot => useSyncExternalStore(channel.subscribe, getSnapshot);
+
+  const useSelector = <Selected>(
+    selector: (snapshot: Snapshot) => Selected,
+    isEqual: EqualityFn<Selected> = shallowEqual
+  ): Selected => useExternalStoreSelector(channel.subscribe, getSnapshot, selector, isEqual);
+
+  return {
+    ...channel,
+    getSnapshot,
+    patchSnapshot: (next) => {
+      if (!hasPatchChanges(snapshot, next)) {
+        return;
+      }
+
+      setSnapshot({ ...snapshot, ...next });
+    },
+    setSnapshot,
+    setSnapshotSilently: (next) => {
+      snapshot = next;
+    },
+    useSelector,
+    useSnapshot,
+  };
+};
+
+export interface KeyedTransientStore<Key, Value> extends ListenerChannel {
+  clear: () => void;
+  delete: (key: Key) => void;
+  entries: () => Array<[Key, Value]>;
+  get: (key: Key) => Value | undefined;
+  set: (key: Key, value: Value) => void;
+  subscribeKey: (key: Key, listener: () => void) => () => void;
+  useValue: (key: Key) => Value | undefined;
+}
+
+export const createKeyedTransientStore = <Key, Value>(
+  isEqual: EqualityFn<Value | undefined> = Object.is
+): KeyedTransientStore<Key, Value> => {
+  const values = new Map<Key, Value>();
+  const channel = createListenerChannel();
+  const keyedListeners = new Map<Key, Set<() => void>>();
+
+  const notifyKey = (key: Key): void => {
+    for (const listener of keyedListeners.get(key) ?? []) {
+      listener();
+    }
+
+    channel.notify();
+  };
+
+  const subscribeKey = (key: Key, listener: () => void): (() => void) => {
+    const listeners = keyedListeners.get(key) ?? new Set<() => void>();
+
+    listeners.add(listener);
+    keyedListeners.set(key, listeners);
+
+    return () => {
+      listeners.delete(listener);
+
+      if (listeners.size === 0) {
+        keyedListeners.delete(key);
+      }
+    };
+  };
+
+  const get = (key: Key): Value | undefined => values.get(key);
+
+  return {
+    ...channel,
+    clear: () => {
+      if (values.size === 0) {
+        return;
+      }
+
+      const keys = Array.from(values.keys());
+      values.clear();
+
+      for (const key of keys) {
+        for (const listener of keyedListeners.get(key) ?? []) {
+          listener();
+        }
+      }
+
+      channel.notify();
+    },
+    delete: (key) => {
+      if (values.delete(key)) {
+        notifyKey(key);
+      }
+    },
+    entries: () => [...values.entries()],
+    get,
+    set: (key, value) => {
+      if (values.has(key) && isEqual(values.get(key), value)) {
+        return;
+      }
+
+      values.set(key, value);
+      notifyKey(key);
+    },
+    subscribeKey,
+    useValue: (key) => {
+      const subscribe = useCallback((listener: () => void) => subscribeKey(key, listener), [key]);
+      const getKeySnapshot = useCallback(() => get(key), [key]);
+
+      return useSyncExternalStore(subscribe, getKeySnapshot);
+    },
+  };
+};
+
+export interface CollectionStore<Contribution> extends ListenerChannel {
+  findLatest: (predicate: (contribution: Contribution) => boolean) => Contribution | undefined;
+  list: () => Contribution[];
+  register: (contribution: Contribution, registrationKey: string) => () => void;
+  useList: () => Contribution[];
+}
+
+export const createCollectionStore = <Contribution>(): CollectionStore<Contribution> => {
+  let nextRegistrationId = 0;
+  const contributions = new Map<string, { contribution: Contribution; token: number }>();
+  const channel = createListenerChannel();
+  let listSnapshot: Contribution[] = [];
+  const refreshListSnapshot = (): void => {
+    listSnapshot = [...contributions.values()].map((entry) => entry.contribution);
+  };
+  const list = (): Contribution[] => listSnapshot;
+
+  return {
+    ...channel,
+    findLatest: (predicate) => {
+      const items = list();
+
+      for (let index = items.length - 1; index >= 0; index -= 1) {
+        const contribution = items[index];
+
+        if (contribution !== undefined && predicate(contribution)) {
+          return contribution;
+        }
+      }
+
+      return undefined;
+    },
+    list,
+    register: (contribution, registrationKey) => {
+      const id = registrationKey;
+      const token = nextRegistrationId;
+
+      nextRegistrationId += 1;
+      contributions.delete(id);
+      contributions.set(id, { contribution, token });
+      refreshListSnapshot();
+      channel.notify();
+
+      return () => {
+        if (contributions.get(id)?.token === token && contributions.delete(id)) {
+          refreshListSnapshot();
+          channel.notify();
+        }
+      };
+    },
+    useList: () => useSyncExternalStore(channel.subscribe, list),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/focusRegions.tsx b/invokeai/frontend/webv2/src/workbench/focusRegions.tsx
new file mode 100644
index 00000000000..3af79a18bf6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/focusRegions.tsx
@@ -0,0 +1,78 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop */
+import type { FocusEvent, PointerEvent, ReactNode } from 'react';
+
+import { createContext, use, useState } from 'react';
+
+import type { WidgetRegion } from './types';
+
+import { useWorkbenchPreferenceSelector } from './settings/store';
+
+let focusedRegionSnapshot: WidgetRegion | null = null;
+
+export const getFocusedRegionSnapshot = (): WidgetRegion | null => focusedRegionSnapshot;
+
+interface FocusRegionContextValue {
+  focusedRegion: WidgetRegion | null;
+  setFocusedRegion: (region: WidgetRegion | null) => void;
+}
+
+const FocusRegionContext = createContext<FocusRegionContextValue | null>(null);
+
+const highlightStyles = {
+  '&[data-highlighted="true"]::after': {
+    borderColor: 'accent.solid',
+    opacity: 1,
+  },
+  '&::after': {
+    border: '1px solid',
+    borderColor: 'transparent',
+    borderRadius: 'md',
+    content: '""',
+    inset: '2px',
+    opacity: 0,
+    pointerEvents: 'none',
+    position: 'absolute',
+    transition: 'border-color var(--wb-motion-duration-fast) ease, opacity var(--wb-motion-duration-fast) ease',
+    zIndex: 2,
+  },
+} as const;
+
+export const FocusRegionProvider = ({ children }: { children: ReactNode }) => {
+  const [focusedRegion, setFocusedRegion] = useState<WidgetRegion | null>(null);
+  const setFocusedRegionSnapshot = (region: WidgetRegion | null) => {
+    focusedRegionSnapshot = region;
+    setFocusedRegion(region);
+  };
+
+  return (
+    <FocusRegionContext value={{ focusedRegion, setFocusedRegion: setFocusedRegionSnapshot }}>
+      {children}
+    </FocusRegionContext>
+  );
+};
+
+const useFocusRegionContext = () => {
+  const context = use(FocusRegionContext);
+
+  if (!context) {
+    throw new Error('useFocusRegionProps must be used within a FocusRegionProvider.');
+  }
+
+  return context;
+};
+
+export const useFocusRegionProps = (region: WidgetRegion) => {
+  const { focusedRegion, setFocusedRegion } = useFocusRegionContext();
+  const showFocusRegionHighlight = useWorkbenchPreferenceSelector(
+    (preferences) => preferences.showFocusRegionHighlight
+  );
+  const isHighlighted = showFocusRegionHighlight && focusedRegion === region;
+
+  return {
+    css: highlightStyles,
+    'data-highlighted': isHighlighted,
+    onFocusCapture: (_event: FocusEvent<HTMLElement>) => setFocusedRegion(region),
+    onPointerDownCapture: (_event: PointerEvent<HTMLElement>) => setFocusedRegion(region),
+    position: 'relative' as const,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/gallery/api.test.ts b/invokeai/frontend/webv2/src/workbench/gallery/api.test.ts
new file mode 100644
index 00000000000..4d11fcf874f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/gallery/api.test.ts
@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  apiFetchJson: vi.fn(),
+}));
+
+vi.mock('@workbench/backend/http', () => ({
+  absolutizeApiUrl: (url: string) => `https://api.test${url}`,
+  apiFetch: vi.fn(),
+  apiFetchJson: mocks.apiFetchJson,
+  apiFetchRaw: vi.fn(),
+  sleep: vi.fn(),
+}));
+
+import { getGalleryImageByName, imageMakeDurableChanges, imageSaveToGalleryChanges } from './api';
+
+describe('getGalleryImageByName', () => {
+  beforeEach(() => {
+    mocks.apiFetchJson.mockReset();
+  });
+
+  it('encodes the image name, forwards the abort signal, and maps the backend image', async () => {
+    const controller = new AbortController();
+    mocks.apiFetchJson.mockResolvedValue({
+      board_id: 'board-1',
+      created_at: '2026-07-09T12:00:00.000Z',
+      height: 360,
+      image_category: 'general',
+      image_name: 'folder/workflow result.png',
+      image_url: '/images/workflow-result.png',
+      is_intermediate: false,
+      starred: true,
+      thumbnail_url: '/thumbnails/workflow-result.webp',
+      width: 640,
+    });
+
+    await expect(getGalleryImageByName('folder/workflow result.png', controller.signal)).resolves.toEqual({
+      boardId: 'board-1',
+      height: 360,
+      imageCategory: 'general',
+      imageName: 'folder/workflow result.png',
+      imageUrl: 'https://api.test/images/workflow-result.png',
+      queuedAt: '2026-07-09T12:00:00.000Z',
+      sourceQueueItemId: 'backend-gallery',
+      starred: true,
+      thumbnailUrl: 'https://api.test/thumbnails/workflow-result.webp',
+      width: 640,
+    });
+    expect(mocks.apiFetchJson).toHaveBeenCalledWith('/api/v1/images/i/folder%2Fworkflow%20result.png', {
+      signal: controller.signal,
+    });
+  });
+
+  it('propagates backend lookup errors', async () => {
+    const error = new Error('404 image not found');
+    mocks.apiFetchJson.mockRejectedValue(error);
+
+    await expect(getGalleryImageByName('missing.png')).rejects.toBe(error);
+  });
+
+  it('propagates request aborts', async () => {
+    const controller = new AbortController();
+    const error = new DOMException('The operation was aborted.', 'AbortError');
+    mocks.apiFetchJson.mockRejectedValue(error);
+
+    const result = getGalleryImageByName('workflow.png', controller.signal);
+    controller.abort();
+
+    await expect(result).rejects.toBe(error);
+  });
+});
+
+describe('imageSaveToGalleryChanges', () => {
+  it('promotes an intermediate candidate to a durable, gallery-visible image', () => {
+    // The backend `ImageRecordChanges` body: clear `is_intermediate` (stop GC)
+    // and set `image_category: 'general'` (surface in the gallery images view).
+    expect(imageSaveToGalleryChanges()).toEqual({ image_category: 'general', is_intermediate: false });
+  });
+});
+
+describe('imageMakeDurableChanges', () => {
+  it('clears is_intermediate without changing the existing image category', () => {
+    // A utility result adopted by the canvas must survive GC, while its existing
+    // category continues to determine whether it appears in Images or Assets.
+    const body = imageMakeDurableChanges();
+    expect(body).toEqual({ is_intermediate: false });
+    expect('image_category' in body).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/gallery/api.ts b/invokeai/frontend/webv2/src/workbench/gallery/api.ts
new file mode 100644
index 00000000000..9db903b0842
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/gallery/api.ts
@@ -0,0 +1,512 @@
+import type { GeneratedImageContract } from '@workbench/types';
+
+import { absolutizeApiUrl, apiFetch, apiFetchJson, apiFetchRaw, sleep } from '@workbench/backend/http';
+
+export type GalleryView = 'images' | 'assets';
+
+export type GalleryOrderDir = 'ASC' | 'DESC';
+
+export type GalleryBoardOrderBy = 'created_at' | 'board_name';
+
+export interface BackendBoardDTO {
+  board_id: string;
+  board_name: string;
+  image_count: number;
+  asset_count: number;
+  archived: boolean;
+  cover_image_name?: string | null;
+  /** Board owner's display name; populated only for admins on multi-user backends. */
+  owner_username?: string | null;
+}
+
+/**
+ * 'board' is a real backend board; 'uncategorized' is the pseudo-board for
+ * unassigned images (board_id 'none'); 'date' is a read-only virtual board
+ * grouping images by creation date (id 'by_date:YYYY-MM-DD').
+ */
+export type GalleryBoardKind = 'board' | 'uncategorized' | 'date';
+
+export interface GalleryBoard {
+  id: string;
+  name: string;
+  kind: GalleryBoardKind;
+  imageCount: number;
+  assetCount: number;
+  archived: boolean;
+  coverImageName?: string | null;
+  coverThumbnailUrl?: string;
+  /** Owner display name when the backend exposes it (admins in multi-user mode). */
+  ownerName?: string | null;
+}
+
+const DATE_BOARD_ID_PREFIX = 'by_date:';
+
+export const isDateBoardId = (boardId: string): boolean => boardId.startsWith(DATE_BOARD_ID_PREFIX);
+
+const getDateFromBoardId = (boardId: string): string => boardId.slice(DATE_BOARD_ID_PREFIX.length);
+
+export interface BackendImageDTO {
+  image_name: string;
+  image_url: string;
+  thumbnail_url: string;
+  width: number;
+  height: number;
+  created_at: string;
+  image_category: 'general' | 'control' | 'mask' | 'user' | 'other';
+  is_intermediate: boolean;
+  starred?: boolean;
+  board_id?: string | null;
+}
+
+export interface GalleryImage extends GeneratedImageContract {
+  boardId: string;
+  imageCategory: BackendImageDTO['image_category'];
+  starred: boolean;
+}
+
+export type GalleryImageMetadata = Record<string, unknown>;
+
+interface ListImagesResponse {
+  items: BackendImageDTO[];
+  limit: number;
+  offset: number;
+  total: number;
+}
+
+const imageCategories = ['general'];
+const assetCategories = ['control', 'mask', 'user', 'other'];
+
+export const getImageThumbnailUrl = (imageName: string): string =>
+  absolutizeApiUrl(`/api/v1/images/i/${encodeURIComponent(imageName)}/thumbnail`);
+
+/** The full-resolution image URL for an image referenced only by name (e.g. a v2 canvas layer's `CanvasImageRef`). */
+export const getImageFullUrl = (imageName: string): string =>
+  absolutizeApiUrl(`/api/v1/images/i/${encodeURIComponent(imageName)}/full`);
+
+const toSearchParams = (entries: Record<string, boolean | number | string | string[] | undefined>): string => {
+  const params = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(entries)) {
+    if (value === undefined || value === '') {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        params.append(key, item);
+      }
+      continue;
+    }
+
+    params.set(key, String(value));
+  }
+
+  return params.toString();
+};
+
+const mapBoard = (board: BackendBoardDTO): GalleryBoard => ({
+  archived: board.archived,
+  assetCount: board.asset_count,
+  coverImageName: board.cover_image_name,
+  coverThumbnailUrl: board.cover_image_name ? getImageThumbnailUrl(board.cover_image_name) : undefined,
+  id: board.board_id,
+  imageCount: board.image_count,
+  kind: 'board',
+  name: board.board_name,
+  ownerName: board.owner_username ?? null,
+});
+
+const getGalleryTotal = async ({ boardId, categories }: { boardId: string; categories: string[] }): Promise<number> => {
+  const query = toSearchParams({
+    board_id: boardId,
+    categories,
+    is_intermediate: false,
+    limit: 0,
+    offset: 0,
+  });
+  const body = await apiFetchJson<Pick<ListImagesResponse, 'total'>>(`/api/v1/images/?${query}`);
+
+  return body.total;
+};
+
+const mapImage = (image: BackendImageDTO): GalleryImage => ({
+  boardId: image.board_id ?? 'none',
+  height: image.height,
+  imageCategory: image.image_category,
+  imageName: image.image_name,
+  imageUrl: absolutizeApiUrl(image.image_url),
+  queuedAt: image.created_at,
+  sourceQueueItemId: 'backend-gallery',
+  starred: image.starred ?? false,
+  thumbnailUrl: absolutizeApiUrl(image.thumbnail_url),
+  width: image.width,
+});
+
+const normalizeTotal = (value: unknown, fallback: number): number =>
+  typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : Math.max(0, fallback);
+
+export const listGalleryBoards = async ({
+  includeArchived = false,
+  orderBy = 'created_at',
+  orderDir = 'DESC',
+}: {
+  includeArchived?: boolean;
+  orderBy?: GalleryBoardOrderBy;
+  orderDir?: GalleryOrderDir;
+} = {}): Promise<GalleryBoard[]> => {
+  const boardsQuery = toSearchParams({
+    all: true,
+    direction: orderDir,
+    include_archived: includeArchived,
+    order_by: orderBy,
+  });
+  const boardsBodyPromise = apiFetchJson<BackendBoardDTO[] | { items?: BackendBoardDTO[] }>(
+    `/api/v1/boards/?${boardsQuery}`
+  );
+
+  const [body, uncategorizedImageCount, uncategorizedAssetCount] = await Promise.all([
+    boardsBodyPromise,
+    getGalleryTotal({ boardId: 'none', categories: imageCategories }),
+    getGalleryTotal({ boardId: 'none', categories: assetCategories }),
+  ]);
+  const boards = Array.isArray(body) ? body : (body.items ?? []);
+
+  return [
+    {
+      archived: false,
+      assetCount: uncategorizedAssetCount,
+      id: 'none',
+      imageCount: uncategorizedImageCount,
+      kind: 'uncategorized',
+      name: 'Uncategorized',
+    },
+    ...boards.filter((board) => includeArchived || !board.archived).map(mapBoard),
+  ];
+};
+
+interface VirtualDateBoardDTO {
+  virtual_board_id: string;
+  board_name: string;
+  date: string;
+  image_count: number;
+  asset_count: number;
+  cover_image_name?: string | null;
+}
+
+export const listGalleryDateBoards = async (): Promise<GalleryBoard[]> => {
+  const body = await apiFetchJson<VirtualDateBoardDTO[]>('/api/v1/virtual_boards/by_date');
+
+  return body.map((board) => ({
+    archived: false,
+    assetCount: board.asset_count,
+    coverImageName: board.cover_image_name,
+    coverThumbnailUrl: board.cover_image_name ? getImageThumbnailUrl(board.cover_image_name) : undefined,
+    id: board.virtual_board_id,
+    imageCount: board.image_count,
+    kind: 'date',
+    name: board.board_name,
+  }));
+};
+
+export interface GalleryImagesPage {
+  images: GalleryImage[];
+  total: number;
+}
+
+export const getGalleryImagesByNames = async (imageNames: string[]): Promise<GalleryImage[]> => {
+  if (imageNames.length === 0) {
+    return [];
+  }
+
+  const body = await apiFetchJson<BackendImageDTO[]>('/api/v1/images/images_by_names', {
+    body: JSON.stringify({ image_names: imageNames }),
+    method: 'POST',
+  });
+
+  return body.map(mapImage);
+};
+
+export const getGalleryImageByName = async (imageName: string, signal?: AbortSignal): Promise<GalleryImage> => {
+  const body = await apiFetchJson<BackendImageDTO>(`/api/v1/images/i/${encodeURIComponent(imageName)}`, { signal });
+
+  return mapImage(body);
+};
+
+/**
+ * Date virtual boards have no offset-paginated DTO endpoint; list the ordered
+ * names for the date, slice the requested window, then bulk-hydrate DTOs.
+ */
+const listGalleryDateBoardImages = async ({
+  boardId,
+  galleryView,
+  limit,
+  offset,
+  orderDir,
+  searchTerm,
+  starredFirst,
+}: {
+  boardId: string;
+  galleryView: GalleryView;
+  limit: number;
+  offset: number;
+  orderDir: GalleryOrderDir;
+  searchTerm: string;
+  starredFirst: boolean;
+}): Promise<GalleryImagesPage> => {
+  const query = toSearchParams({
+    categories: galleryView === 'assets' ? assetCategories : imageCategories,
+    order_dir: orderDir,
+    search_term: searchTerm.trim() || undefined,
+    starred_first: starredFirst,
+  });
+  const body = await apiFetchJson<{ image_names: string[]; total_count: number }>(
+    `/api/v1/virtual_boards/by_date/${encodeURIComponent(getDateFromBoardId(boardId))}/image_names?${query}`
+  );
+  const images = await getGalleryImagesByNames(body.image_names.slice(offset, offset + limit));
+
+  return { images, total: normalizeTotal(body.total_count, body.image_names.length) };
+};
+
+export const listGalleryImages = async ({
+  boardId,
+  galleryView,
+  limit = 100,
+  offset = 0,
+  orderDir = 'DESC',
+  searchTerm,
+  starredFirst = false,
+}: {
+  boardId: string;
+  galleryView: GalleryView;
+  limit?: number;
+  offset?: number;
+  orderDir?: GalleryOrderDir;
+  searchTerm: string;
+  starredFirst?: boolean;
+}): Promise<GalleryImagesPage> => {
+  if (isDateBoardId(boardId)) {
+    return listGalleryDateBoardImages({ boardId, galleryView, limit, offset, orderDir, searchTerm, starredFirst });
+  }
+
+  const query = toSearchParams({
+    board_id: boardId,
+    categories: galleryView === 'assets' ? assetCategories : imageCategories,
+    is_intermediate: false,
+    limit,
+    offset,
+    order_dir: orderDir,
+    search_term: searchTerm.trim() || undefined,
+    starred_first: starredFirst,
+  });
+  const body = await apiFetchJson<ListImagesResponse | BackendImageDTO[]>(`/api/v1/images/?${query}`);
+  const items = Array.isArray(body) ? body : (body.items ?? []);
+
+  return {
+    images: items.map(mapImage),
+    total: normalizeTotal(
+      Array.isArray(body) ? undefined : body.total,
+      offset + items.length + (Array.isArray(body) && items.length >= limit ? 1 : 0)
+    ),
+  };
+};
+
+/**
+ * The `ImageRecordChanges` body that promotes a staged canvas candidate (an
+ * intermediate image) into a durable, gallery-visible image: clearing
+ * `is_intermediate` stops it being garbage-collected, and `image_category:
+ * 'general'` surfaces it in the gallery's images view. Pure so the request
+ * shape can be unit-tested without a fetch.
+ */
+export const imageSaveToGalleryChanges = (): { is_intermediate: false; image_category: 'general' } => ({
+  image_category: 'general',
+  is_intermediate: false,
+});
+
+/**
+ * The `ImageRecordChanges` body that makes an intermediate image durable without
+ * changing its category. Clearing `is_intermediate` stops garbage collection;
+ * where the image appears is determined by its existing category. Used when a
+ * utility result becomes a canvas source while discarded previews remain
+ * intermediate and can be collected.
+ */
+export const imageMakeDurableChanges = (): { is_intermediate: false } => ({
+  is_intermediate: false,
+});
+
+/**
+ * Makes a single intermediate image durable (survives GC) without changing its
+ * category, via `PATCH /api/v1/images/i/{image_name}`. Resolves once the PATCH
+ * succeeds; the caller commits the layer-source swap only after this settles so a
+ * failed PATCH never strands the layer pointing at a soon-to-be-collected image.
+ */
+export const makeImageDurable = async (imageName: string): Promise<void> => {
+  await apiFetchJson<BackendImageDTO>(`/api/v1/images/i/${encodeURIComponent(imageName)}`, {
+    body: JSON.stringify(imageMakeDurableChanges()),
+    method: 'PATCH',
+  });
+};
+
+/**
+ * Promotes a single image (e.g. a staged canvas candidate) into the gallery via
+ * `PATCH /api/v1/images/i/{image_name}` and returns the updated {@link GalleryImage}.
+ */
+export const saveImageToGallery = async (imageName: string): Promise<GalleryImage> => {
+  const body = await apiFetchJson<BackendImageDTO>(`/api/v1/images/i/${encodeURIComponent(imageName)}`, {
+    body: JSON.stringify(imageSaveToGalleryChanges()),
+    method: 'PATCH',
+  });
+
+  return mapImage(body);
+};
+
+export const getGalleryImageMetadata = async (imageName: string): Promise<GalleryImageMetadata | null> => {
+  const body = await apiFetchJson<unknown>(`/api/v1/images/i/${encodeURIComponent(imageName)}/metadata`);
+
+  return body && typeof body === 'object' && !Array.isArray(body) ? (body as GalleryImageMetadata) : null;
+};
+
+export const createGalleryBoard = async (boardName: string): Promise<GalleryBoard> => {
+  const query = toSearchParams({ board_name: boardName });
+  const body = await apiFetchJson<BackendBoardDTO>(`/api/v1/boards/?${query}`, { method: 'POST' });
+
+  return mapBoard(body);
+};
+
+export const updateGalleryBoard = async (
+  boardId: string,
+  changes: { name?: string; archived?: boolean }
+): Promise<GalleryBoard> => {
+  const body = await apiFetchJson<BackendBoardDTO>(`/api/v1/boards/${encodeURIComponent(boardId)}`, {
+    body: JSON.stringify({ archived: changes.archived, board_name: changes.name }),
+    method: 'PATCH',
+  });
+
+  return mapBoard(body);
+};
+
+export const deleteGalleryBoard = async (boardId: string, includeImages: boolean): Promise<void> => {
+  const query = toSearchParams({ include_images: includeImages });
+
+  await apiFetch(`/api/v1/boards/${encodeURIComponent(boardId)}?${query}`, { method: 'DELETE' });
+};
+
+export const addImagesToGalleryBoard = async (boardId: string, imageNames: string[]): Promise<void> => {
+  if (
+    boardId === 'none' ||
+    boardId === 'generated' ||
+    boardId === 'assets' ||
+    isDateBoardId(boardId) ||
+    imageNames.length === 0
+  ) {
+    return;
+  }
+
+  await apiFetchJson('/api/v1/board_images/batch', {
+    body: JSON.stringify({ board_id: boardId, image_names: imageNames }),
+    method: 'POST',
+  });
+};
+
+export const removeImagesFromGalleryBoard = async (imageNames: string[]): Promise<void> => {
+  if (imageNames.length === 0) {
+    return;
+  }
+
+  await apiFetchJson('/api/v1/board_images/batch/delete', {
+    body: JSON.stringify({ image_names: imageNames }),
+    method: 'POST',
+  });
+};
+
+const setGalleryImagesStarred = async (imageNames: string[], starred: boolean): Promise<void> => {
+  if (imageNames.length === 0) {
+    return;
+  }
+
+  await apiFetchJson(`/api/v1/images/${starred ? 'star' : 'unstar'}`, {
+    body: JSON.stringify({ image_names: imageNames }),
+    method: 'POST',
+  });
+};
+
+export const starGalleryImages = (imageNames: string[]): Promise<void> => setGalleryImagesStarred(imageNames, true);
+
+export const unstarGalleryImages = (imageNames: string[]): Promise<void> => setGalleryImagesStarred(imageNames, false);
+
+export const deleteGalleryImages = async (imageNames: string[]): Promise<void> => {
+  if (imageNames.length === 0) {
+    return;
+  }
+
+  await apiFetchJson('/api/v1/images/delete', {
+    body: JSON.stringify({ image_names: imageNames }),
+    method: 'POST',
+  });
+};
+
+const BULK_DOWNLOAD_POLL_INTERVAL_MS = 2000;
+const BULK_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Starts a bulk download (a zip prepared in a backend background task) and
+ * polls the artifact endpoint until it exists. Returns the archive blob and
+ * its file name.
+ */
+export const downloadGalleryArchive = async ({
+  boardId,
+  imageNames,
+}: {
+  boardId?: string;
+  imageNames?: string[];
+}): Promise<{ blob: Blob; fileName: string }> => {
+  const { bulk_download_item_name: fileName } = await apiFetchJson<{ bulk_download_item_name?: string | null }>(
+    '/api/v1/images/download',
+    {
+      body: JSON.stringify({ board_id: boardId, image_names: imageNames }),
+      method: 'POST',
+    }
+  );
+
+  if (!fileName) {
+    throw new Error('The bulk download failed to start.');
+  }
+
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < BULK_DOWNLOAD_TIMEOUT_MS) {
+    const response = await apiFetchRaw(`/api/v1/images/download/${encodeURIComponent(fileName)}`);
+
+    if (response.ok) {
+      return { blob: await response.blob(), fileName };
+    }
+
+    if (response.status !== 404) {
+      throw new Error(`${response.status} ${response.statusText}`);
+    }
+
+    await sleep(BULK_DOWNLOAD_POLL_INTERVAL_MS);
+  }
+
+  throw new Error('Timed out preparing the download archive.');
+};
+
+export const uploadGalleryImage = async (
+  file: File,
+  boardId: string,
+  options: { isIntermediate?: boolean } = {}
+): Promise<GalleryImage> => {
+  const query = toSearchParams({
+    board_id: boardId === 'none' || isDateBoardId(boardId) ? undefined : boardId,
+    image_category: 'user',
+    is_intermediate: options.isIntermediate ?? false,
+  });
+  const body = new FormData();
+  body.append('file', file);
+
+  const uploadedImage = await apiFetchJson<BackendImageDTO>(`/api/v1/images/upload?${query}`, {
+    body,
+    method: 'POST',
+  });
+
+  return mapImage(uploadedImage);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/gallery/settings.ts b/invokeai/frontend/webv2/src/workbench/gallery/settings.ts
new file mode 100644
index 00000000000..c09613df29e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/gallery/settings.ts
@@ -0,0 +1,63 @@
+import type { GalleryBoardOrderBy, GalleryOrderDir } from './api';
+
+export type GalleryThumbnailFit = 'square' | 'aspect';
+
+export type GalleryPaginationMode = 'infinite' | 'paginated';
+
+/**
+ * User-tunable gallery settings. Persisted as plain entries in the gallery
+ * widget's `values` record so they survive workbench autosave/hydration.
+ */
+export interface GallerySettings {
+  boardOrderBy: GalleryBoardOrderBy;
+  boardOrderDir: GalleryOrderDir;
+  imageDensityPercent: number;
+  imageOrderDir: GalleryOrderDir;
+  paginationMode: GalleryPaginationMode;
+  showArchivedBoards: boolean;
+  showDateBoards: boolean;
+  showImageDimensions: boolean;
+  starredFirst: boolean;
+  thumbnailFit: GalleryThumbnailFit;
+}
+
+export const DEFAULT_GALLERY_SETTINGS: GallerySettings = {
+  boardOrderBy: 'created_at',
+  boardOrderDir: 'DESC',
+  imageDensityPercent: 50,
+  imageOrderDir: 'DESC',
+  paginationMode: 'infinite',
+  showArchivedBoards: false,
+  showDateBoards: false,
+  showImageDimensions: false,
+  starredFirst: true,
+  thumbnailFit: 'square',
+};
+
+const isOrderDir = (value: unknown): value is GalleryOrderDir => value === 'ASC' || value === 'DESC';
+
+const isBoardOrderBy = (value: unknown): value is GalleryBoardOrderBy =>
+  value === 'created_at' || value === 'board_name';
+
+export const getGallerySettings = (values: Record<string, unknown>): GallerySettings => ({
+  boardOrderBy: isBoardOrderBy(values.boardOrderBy) ? values.boardOrderBy : DEFAULT_GALLERY_SETTINGS.boardOrderBy,
+  boardOrderDir: isOrderDir(values.boardOrderDir) ? values.boardOrderDir : DEFAULT_GALLERY_SETTINGS.boardOrderDir,
+  imageDensityPercent:
+    typeof values.imageDensityPercent === 'number' && Number.isFinite(values.imageDensityPercent)
+      ? Math.min(100, Math.max(0, values.imageDensityPercent))
+      : DEFAULT_GALLERY_SETTINGS.imageDensityPercent,
+  imageOrderDir: isOrderDir(values.imageOrderDir) ? values.imageOrderDir : DEFAULT_GALLERY_SETTINGS.imageOrderDir,
+  paginationMode: values.paginationMode === 'paginated' ? 'paginated' : DEFAULT_GALLERY_SETTINGS.paginationMode,
+  showArchivedBoards:
+    typeof values.showArchivedBoards === 'boolean'
+      ? values.showArchivedBoards
+      : DEFAULT_GALLERY_SETTINGS.showArchivedBoards,
+  showDateBoards:
+    typeof values.showDateBoards === 'boolean' ? values.showDateBoards : DEFAULT_GALLERY_SETTINGS.showDateBoards,
+  showImageDimensions:
+    typeof values.showImageDimensions === 'boolean'
+      ? values.showImageDimensions
+      : DEFAULT_GALLERY_SETTINGS.showImageDimensions,
+  starredFirst: typeof values.starredFirst === 'boolean' ? values.starredFirst : DEFAULT_GALLERY_SETTINGS.starredFirst,
+  thumbnailFit: values.thumbnailFit === 'aspect' ? 'aspect' : DEFAULT_GALLERY_SETTINGS.thumbnailFit,
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/api.test.ts b/invokeai/frontend/webv2/src/workbench/generation/api.test.ts
new file mode 100644
index 00000000000..5872e364768
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/api.test.ts
@@ -0,0 +1,224 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { EnqueueGenerateRequest, EnqueueWorkflowRequest } from './types';
+
+const mocks = vi.hoisted(() => ({
+  apiFetchJson: vi.fn(),
+}));
+
+vi.mock('../backend/http', () => ({
+  absolutizeApiUrl: (url: string) => url,
+  ApiError: class ApiError extends Error {
+    status: number;
+
+    constructor(status: number) {
+      super('API error');
+      this.status = status;
+    }
+  },
+  apiFetchJson: mocks.apiFetchJson,
+}));
+
+const createRequest = (overrides: Partial<EnqueueGenerateRequest> = {}): EnqueueGenerateRequest => ({
+  batchCount: 3,
+  destination: 'gallery',
+  graph: { edges: [], id: 'graph-1', nodes: {} },
+  negativePrompt: 'low quality',
+  negativePromptNodeId: 'negative_prompt',
+  positivePrompt: 'a fjord at dawn',
+  positivePromptNodeId: 'positive_prompt',
+  projectId: 'project-1',
+  seed: 10,
+  seedNodeId: 'seed',
+  shouldRandomizeSeed: false,
+  sourceQueueItemId: 'local-1',
+  ...overrides,
+});
+
+const createWorkflowRequest = (overrides: Partial<EnqueueWorkflowRequest> = {}): EnqueueWorkflowRequest => ({
+  batchCount: 2,
+  destination: 'gallery',
+  graph: { edges: [], id: 'graph-1', nodes: {} },
+  projectId: 'project-1',
+  sourceQueueItemId: 'local-1',
+  ...overrides,
+});
+
+const getSubmittedBody = () => {
+  const init = mocks.apiFetchJson.mock.calls[0]?.[1] as RequestInit | undefined;
+
+  expect(init?.body).toEqual(expect.any(String));
+
+  return JSON.parse(init?.body as string) as {
+    batch: {
+      data: { field_name: string; items: unknown[]; node_path: string }[][];
+      origin: string;
+      runs: number;
+    };
+  };
+};
+
+describe('enqueueGenerateGraph', () => {
+  beforeEach(() => {
+    mocks.apiFetchJson.mockReset();
+    mocks.apiFetchJson.mockResolvedValue({
+      batch: { batch_id: 'batch-1' },
+      enqueued: 3,
+      item_ids: [1, 2, 3],
+      requested: 3,
+    });
+  });
+
+  it('keeps a fixed seed for every run when randomization is disabled', async () => {
+    const { enqueueGenerateGraph } = await import('./api');
+
+    await enqueueGenerateGraph(createRequest({ shouldRandomizeSeed: false }));
+
+    const body = getSubmittedBody();
+
+    expect(body.batch.runs).toBe(3);
+    expect(body.batch.data[0]).toEqual([
+      { field_name: 'value', items: [10], node_path: 'seed' },
+      { field_name: 'value', items: ['a fjord at dawn'], node_path: 'positive_prompt' },
+      { field_name: 'value', items: ['low quality'], node_path: 'negative_prompt' },
+    ]);
+  });
+
+  it('expands seeds per batch item only when randomization is enabled', async () => {
+    const { enqueueGenerateGraph } = await import('./api');
+
+    await enqueueGenerateGraph(createRequest({ shouldRandomizeSeed: true }));
+
+    const body = getSubmittedBody();
+
+    expect(body.batch.runs).toBe(1);
+    expect(body.batch.data[0]).toEqual([
+      { field_name: 'value', items: [10, 11, 12], node_path: 'seed' },
+      {
+        field_name: 'value',
+        items: ['a fjord at dawn', 'a fjord at dawn', 'a fjord at dawn'],
+        node_path: 'positive_prompt',
+      },
+      { field_name: 'value', items: ['low quality', 'low quality', 'low quality'], node_path: 'negative_prompt' },
+    ]);
+  });
+
+  it('includes project-aware webv2 origin metadata', async () => {
+    const { enqueueGenerateGraph } = await import('./api');
+
+    await enqueueGenerateGraph(createRequest());
+
+    expect(getSubmittedBody().batch.origin).toBe('webv2:p:project-1:q:local-1');
+  });
+});
+
+describe('enqueueWorkflowGraph', () => {
+  beforeEach(() => {
+    mocks.apiFetchJson.mockReset();
+    mocks.apiFetchJson.mockResolvedValue({
+      batch: { batch_id: 'batch-1' },
+      enqueued: 2,
+      item_ids: [1, 2],
+      requested: 2,
+    });
+  });
+
+  it('submits workflow runs for the requested batch count', async () => {
+    const { enqueueWorkflowGraph } = await import('./api');
+
+    await enqueueWorkflowGraph(createWorkflowRequest());
+
+    expect(getSubmittedBody().batch.runs).toBe(2);
+  });
+
+  it('does not cap workflow runs', async () => {
+    const { enqueueWorkflowGraph } = await import('./api');
+
+    await enqueueWorkflowGraph(createWorkflowRequest({ batchCount: 10_000 }));
+
+    expect(getSubmittedBody().batch.runs).toBe(10_000);
+  });
+});
+
+describe('getQueueItemResultImages', () => {
+  beforeEach(() => {
+    mocks.apiFetchJson.mockReset();
+  });
+
+  it('can restrict image extraction to explicit result node ids', async () => {
+    mocks.apiFetchJson.mockImplementation((url: string) => {
+      if (url === '/api/v1/queue/default/i/1') {
+        return Promise.resolve({
+          item_id: 1,
+          session: {
+            prepared_source_mapping: {
+              exec_canvas_l2i: 'canvas_l2i',
+              exec_canvas_output: 'canvas_output',
+              exec_create_gradient_mask: 'create_gradient_mask',
+              exec_expand_mask: 'expand_mask',
+            },
+            results: {
+              exec_canvas_l2i: { image: { image_name: 'decoded-patch.png' }, type: 'image_output' },
+              exec_canvas_output: { image: { image_name: 'final-composite.png' }, type: 'image_output' },
+              exec_create_gradient_mask: { image: { image_name: 'gradient-mask.png' }, type: 'image_output' },
+              exec_expand_mask: { image: { image_name: 'expanded-mask.png' }, type: 'image_output' },
+            },
+          },
+          status: 'completed',
+        });
+      }
+
+      const imageName = decodeURIComponent(url.replace('/api/v1/images/i/', ''));
+      return Promise.resolve({
+        height: 768,
+        image_name: imageName,
+        image_url: `/images/${imageName}`,
+        is_intermediate: true,
+        thumbnail_url: `/thumbs/${imageName}`,
+        width: 1024,
+      });
+    });
+
+    const { getQueueItemResultImages } = await import('./api');
+
+    const images = await getQueueItemResultImages(1, 'source-1', '2026-06-15T00:00:00.000Z', {
+      resultNodeIds: ['canvas_output'],
+    });
+
+    expect(images.map((image) => image.imageName)).toEqual(['final-composite.png']);
+  });
+
+  it('extracts image names from image collection outputs', async () => {
+    mocks.apiFetchJson.mockImplementation((url: string) => {
+      if (url === '/api/v1/queue/default/i/1') {
+        return Promise.resolve({
+          item_id: 1,
+          session: {
+            results: {
+              external: {
+                collection: [{ image_name: 'external-a.png' }, { image_name: 'external-b.png' }],
+              },
+            },
+          },
+          status: 'completed',
+        });
+      }
+
+      const imageName = decodeURIComponent(url.replace('/api/v1/images/i/', ''));
+      return Promise.resolve({
+        height: 768,
+        image_name: imageName,
+        image_url: `/images/${imageName}`,
+        is_intermediate: false,
+        thumbnail_url: `/thumbs/${imageName}`,
+        width: 1024,
+      });
+    });
+
+    const { getQueueItemResultImages } = await import('./api');
+
+    const images = await getQueueItemResultImages(1, 'source-1', '2026-06-15T00:00:00.000Z');
+
+    expect(images.map((image) => image.imageName)).toEqual(['external-a.png', 'external-b.png']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/api.ts b/invokeai/frontend/webv2/src/workbench/generation/api.ts
new file mode 100644
index 00000000000..1f7e1dc65e0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/api.ts
@@ -0,0 +1,255 @@
+import type { BackendGraphContract } from '@workbench/types';
+
+import { buildQueueItemOrigin } from '@workbench/backend/events';
+import { absolutizeApiUrl, ApiError, apiFetchJson } from '@workbench/backend/http';
+
+import type {
+  EnqueueGenerateRequest,
+  EnqueueGenerateResult,
+  EnqueueWorkflowRequest,
+  ImageDTO,
+  MainModelConfig,
+  QueueItemDTO,
+} from './types';
+
+import { sanitizeBatchCount } from './batch';
+import { generateSeedSequence } from './graph';
+
+export const listMainModels = async (): Promise<MainModelConfig[]> => {
+  const body = await apiFetchJson<{ models?: MainModelConfig[] }>('/api/v2/models/?model_type=main');
+
+  return body.models ?? [];
+};
+
+export const enqueueGenerateGraph = async (request: EnqueueGenerateRequest): Promise<EnqueueGenerateResult> => {
+  const batchCount = sanitizeBatchCount(request.batchCount);
+  const seeds = request.shouldRandomizeSeed ? generateSeedSequence(request.seed, batchCount) : [request.seed];
+  const prompts = request.shouldRandomizeSeed ? seeds.map(() => request.positivePrompt) : [request.positivePrompt];
+  const negativePrompts = request.shouldRandomizeSeed
+    ? seeds.map(() => request.negativePrompt)
+    : [request.negativePrompt];
+  const body = {
+    batch: {
+      data: [
+        [
+          { field_name: 'value', items: seeds, node_path: request.seedNodeId },
+          { field_name: 'value', items: prompts, node_path: request.positivePromptNodeId },
+          { field_name: 'value', items: negativePrompts, node_path: request.negativePromptNodeId },
+        ],
+      ],
+      destination: request.destination,
+      graph: request.graph satisfies BackendGraphContract,
+      origin: buildQueueItemOrigin(request.sourceQueueItemId, request.projectId),
+      runs: request.shouldRandomizeSeed ? 1 : batchCount,
+    },
+    prepend: false,
+  };
+  const result = await apiFetchJson<{
+    batch?: { batch_id?: string };
+    enqueued?: number;
+    item_ids?: number[];
+    requested?: number;
+  }>('/api/v1/queue/default/enqueue_batch', { body: JSON.stringify(body), method: 'POST' });
+
+  return {
+    batchId: result.batch?.batch_id,
+    enqueued: result.enqueued ?? 0,
+    itemIds: result.item_ids ?? [],
+    requested: result.requested ?? 0,
+  };
+};
+
+/** Enqueue an arbitrary compiled graph — the workflow path. */
+export const enqueueWorkflowGraph = async (request: EnqueueWorkflowRequest): Promise<EnqueueGenerateResult> => {
+  const batchCount = sanitizeBatchCount(request.batchCount);
+  const body = {
+    batch: {
+      destination: request.destination,
+      graph: request.graph satisfies BackendGraphContract,
+      origin: buildQueueItemOrigin(request.sourceQueueItemId, request.projectId),
+      runs: batchCount,
+    },
+    prepend: false,
+  };
+  const result = await apiFetchJson<{
+    batch?: { batch_id?: string };
+    enqueued?: number;
+    item_ids?: number[];
+    requested?: number;
+  }>('/api/v1/queue/default/enqueue_batch', { body: JSON.stringify(body), method: 'POST' });
+
+  return {
+    batchId: result.batch?.batch_id,
+    enqueued: result.enqueued ?? 0,
+    itemIds: result.item_ids ?? [],
+    requested: result.requested ?? 0,
+  };
+};
+
+/**
+ * Enqueues a small graph OUTSIDE any project's queue, tagged with a caller-built
+ * utility origin (`webv2:util:<id>`). Used by {@link import('@workbench/canvas-operations/backend/utilityQueue').runUtilityGraph}
+ * for filter previews / SAM: the origin is intentionally opaque to project
+ * routing (see `events.ts`), so results are never staged or added to the gallery.
+ * A single deterministic run (no seed/prompt batch data).
+ */
+export const enqueueUtilityGraph = async (request: {
+  graph: BackendGraphContract;
+  origin: string;
+}): Promise<{ itemIds: number[]; enqueued: number }> => {
+  const body = {
+    batch: {
+      graph: request.graph satisfies BackendGraphContract,
+      origin: request.origin,
+      runs: 1,
+    },
+    prepend: false,
+  };
+  const result = await apiFetchJson<{ enqueued?: number; item_ids?: number[] }>('/api/v1/queue/default/enqueue_batch', {
+    body: JSON.stringify(body),
+    method: 'POST',
+  });
+
+  return { enqueued: result.enqueued ?? 0, itemIds: result.item_ids ?? [] };
+};
+
+export const getQueueItem = (itemId: number): Promise<QueueItemDTO> =>
+  apiFetchJson<QueueItemDTO>(`/api/v1/queue/default/i/${itemId}`);
+
+export const listAllQueueItems = (): Promise<QueueItemDTO[]> =>
+  apiFetchJson<QueueItemDTO[]>('/api/v1/queue/default/list_all');
+
+export interface QueueItemResultImageOptions {
+  /** Source graph node ids whose prepared execution results should be read. */
+  resultNodeIds?: readonly string[];
+}
+
+const getImageDTO = async (
+  imageName: string,
+  queuedAt: string,
+  sourceQueueItemId: string
+): Promise<ImageDTO | null> => {
+  try {
+    const body = await apiFetchJson<{
+      image_name: string;
+      image_url: string;
+      thumbnail_url: string;
+      width: number;
+      height: number;
+      is_intermediate: boolean;
+    }>(`/api/v1/images/i/${encodeURIComponent(imageName)}`);
+
+    return {
+      height: body.height,
+      imageName: body.image_name,
+      imageUrl: absolutizeApiUrl(body.image_url),
+      isIntermediate: body.is_intermediate,
+      queuedAt,
+      sourceQueueItemId,
+      thumbnailUrl: absolutizeApiUrl(body.thumbnail_url),
+      width: body.width,
+    };
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      return null;
+    }
+
+    throw error;
+  }
+};
+
+const getResultImageNames = (queueItem: QueueItemDTO, options?: QueueItemResultImageOptions): string[] => {
+  const imageNames = new Set<string>();
+  const results = queueItem.session?.results ?? {};
+  const preparedSourceMapping = queueItem.session?.prepared_source_mapping ?? {};
+  const resultNodeIds = options?.resultNodeIds;
+  const resultValues = resultNodeIds
+    ? Object.entries(results)
+        // Backend result keys are prepared execution ids; source ids carry the graph contract.
+        .filter(([nodeId]) => resultNodeIds.includes(preparedSourceMapping[nodeId] ?? nodeId))
+        .map(([, result]) => result)
+    : Object.values(results);
+
+  for (const result of resultValues) {
+    if (!result || typeof result !== 'object') {
+      continue;
+    }
+
+    const image = (result as { image?: { image_name?: unknown } }).image;
+    if (typeof image?.image_name === 'string') {
+      imageNames.add(image.image_name);
+    }
+
+    const collection = (result as { collection?: unknown }).collection;
+    if (Array.isArray(collection)) {
+      for (const item of collection) {
+        if (!item || typeof item !== 'object') {
+          continue;
+        }
+
+        const imageName = (item as { image_name?: unknown }).image_name;
+        if (typeof imageName === 'string') {
+          imageNames.add(imageName);
+        }
+      }
+    }
+  }
+
+  return [...imageNames];
+};
+
+/** Fetch the result image DTOs of a completed queue item. */
+export const getQueueItemResultImages = async (
+  itemId: number,
+  sourceQueueItemId: string,
+  queuedAt: string,
+  options?: QueueItemResultImageOptions
+): Promise<ImageDTO[]> => {
+  const queueItem = await getQueueItem(itemId);
+
+  const images = await Promise.all(
+    getResultImageNames(queueItem, options).map((imageName) => getImageDTO(imageName, queuedAt, sourceQueueItemId))
+  );
+
+  return images.filter((image): image is ImageDTO => image !== null);
+};
+
+export const cancelQueueItemsByBatchIds = async (batchIds: string[]): Promise<void> => {
+  if (batchIds.length === 0) {
+    return;
+  }
+
+  await apiFetchJson('/api/v1/queue/default/cancel_by_batch_ids', {
+    body: JSON.stringify({ batch_ids: batchIds }),
+    method: 'PUT',
+  });
+};
+
+export const getCurrentQueueItem = (): Promise<QueueItemDTO | null> =>
+  apiFetchJson<QueueItemDTO | null>('/api/v1/queue/default/current');
+
+export const cancelQueueItem = (itemId: number): Promise<QueueItemDTO> =>
+  apiFetchJson<QueueItemDTO>(`/api/v1/queue/default/i/${itemId}/cancel`, { method: 'PUT' });
+
+export const cancelQueueItems = async (itemIds: number[]): Promise<void> => {
+  await Promise.all(itemIds.map(cancelQueueItem));
+};
+
+export const cancelCurrentQueueItem = async (): Promise<QueueItemDTO | null> => {
+  const currentQueueItem = await getCurrentQueueItem();
+
+  if (!currentQueueItem) {
+    return null;
+  }
+
+  return cancelQueueItem(currentQueueItem.item_id);
+};
+
+export const cancelAllExceptCurrentQueueItems = (): Promise<unknown> =>
+  apiFetchJson('/api/v1/queue/default/cancel_all_except_current', { method: 'PUT' });
+
+export const resumeQueueProcessor = (): Promise<unknown> =>
+  apiFetchJson('/api/v1/queue/default/processor/resume', { method: 'PUT' });
+
+export const pauseQueueProcessor = (): Promise<unknown> =>
+  apiFetchJson('/api/v1/queue/default/processor/pause', { method: 'PUT' });
diff --git a/invokeai/frontend/webv2/src/workbench/generation/baseGenerationPolicies.test.ts b/invokeai/frontend/webv2/src/workbench/generation/baseGenerationPolicies.test.ts
new file mode 100644
index 00000000000..d53f49d8e84
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/baseGenerationPolicies.test.ts
@@ -0,0 +1,764 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  ComponentModelConfig,
+  GenerateModelConfig,
+  GenerateSettings,
+  LoraModelConfig,
+  MainModelConfig,
+  VaeModelConfig,
+} from './types';
+
+import {
+  BASE_GENERATION,
+  coerceSchedulerForGraph,
+  getComponentSectionPolicy,
+  getAutoFlux2ComponentSourceModel,
+  getDefaultGenerateSettings,
+  getGenerationDimensions,
+  getGenerationModelAvailabilityReasons,
+  getGenerationModelPolicy,
+  getGenerationValidationReasons,
+  getMaxReferenceImages,
+  getPromptPolicy,
+  getSettingsWithCompatibleModelSelections,
+  getSettingsWithModelDefaults,
+  isReferenceImageSupported,
+  isSupportedGenerateModel,
+  SUPPORTED_GENERATE_BASES,
+} from './baseGenerationPolicies';
+
+const createModel = (base: string, overrides: Partial<MainModelConfig> = {}): MainModelConfig => ({
+  base,
+  key: `${base}-model`,
+  name: `${base} model`,
+  type: 'main',
+  ...overrides,
+});
+
+const createSettings = (model: GenerateModelConfig, overrides: Partial<GenerateSettings> = {}): GenerateSettings => ({
+  ...getDefaultGenerateSettings(model),
+  seed: 1,
+  shouldRandomizeSeed: false,
+  ...overrides,
+});
+
+const t5Encoder: ComponentModelConfig = { base: 'any', key: 't5', name: 'T5 Encoder', type: 't5_encoder' };
+const clipEmbed: ComponentModelConfig = { base: 'any', key: 'clip', name: 'CLIP Embed', type: 'clip_embed' };
+const qwenVlEncoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'qwen-vl',
+  name: 'Qwen VL Encoder',
+  type: 'qwen_vl_encoder',
+};
+const qwen3Encoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'qwen3',
+  name: 'Qwen3 Encoder',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_8b',
+};
+const animaQwen3Encoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'anima-qwen3',
+  name: 'Anima Qwen3 Encoder',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_06b',
+};
+const fluxVae: VaeModelConfig = { base: 'flux', key: 'flux-vae', name: 'FLUX VAE', type: 'vae' };
+const flux2Vae: VaeModelConfig = { base: 'flux2', key: 'flux2-vae', name: 'FLUX.2 VAE', type: 'vae' };
+const qwenImageVae: VaeModelConfig = { base: 'qwen-image', key: 'qwen-vae', name: 'Qwen VAE', type: 'vae' };
+const sdxlVae: VaeModelConfig = { base: 'sdxl', key: 'sdxl-vae', name: 'SDXL VAE', type: 'vae' };
+const sd1Lora: LoraModelConfig = { base: 'sd-1', key: 'sd1-lora', name: 'SD 1 LoRA', type: 'lora' };
+const sdxlLora: LoraModelConfig = { base: 'sdxl', key: 'sdxl-lora', name: 'SDXL LoRA', type: 'lora' };
+const sd1IpAdapter: ComponentModelConfig = {
+  base: 'sd-1',
+  key: 'sd1-ip-adapter',
+  name: 'SD 1 IP Adapter',
+  type: 'ip_adapter',
+};
+const sdxlIpAdapter: ComponentModelConfig = {
+  base: 'sdxl',
+  key: 'sdxl-ip-adapter',
+  name: 'SDXL IP Adapter',
+  type: 'ip_adapter',
+};
+const referenceImage = {
+  height: 768,
+  imageName: 'reference.png',
+  imageUrl: '/api/v1/images/i/reference.png/full',
+  queuedAt: '2026-01-01T00:00:00.000Z',
+  sourceQueueItemId: 'backend-gallery',
+  thumbnailUrl: '/api/v1/images/i/reference.png/thumbnail',
+  width: 512,
+};
+const externalModel: GenerateModelConfig = {
+  base: 'external',
+  capabilities: { modes: ['txt2img'], supports_negative_prompt: false, supports_seed: false },
+  format: 'external_api',
+  key: 'external-model',
+  name: 'External Model',
+  provider_id: 'openai',
+  type: 'external_image_generator',
+};
+
+describe('BASE_GENERATION', () => {
+  it('matches expected dimensions per base', () => {
+    expect(getGenerationDimensions(createModel('sd-1'))).toMatchObject({ grid: 8, optimal: 512 });
+    expect(getGenerationDimensions(createModel('sdxl'))).toMatchObject({ grid: 8, optimal: 1024 });
+    expect(getGenerationDimensions(createModel('flux2'))).toMatchObject({ grid: 16, optimal: 1024 });
+    expect(getGenerationDimensions(createModel('cogview4'))).toMatchObject({ grid: 32, optimal: 1024 });
+  });
+
+  it('matches expected defaults per base', () => {
+    expect(getDefaultGenerateSettings(createModel('sdxl'))).toMatchObject({
+      steps: 30,
+      cfgScale: 7,
+      scheduler: 'euler_a',
+      width: 1024,
+      height: 1024,
+    });
+    expect(getDefaultGenerateSettings(createModel('flux'))).toMatchObject({
+      steps: 4,
+      cfgScale: 4,
+      scheduler: 'euler',
+    });
+    expect(getDefaultGenerateSettings(createModel('flux2'))).toMatchObject({
+      steps: 4,
+      cfgScale: 1,
+      scheduler: 'euler',
+    });
+    expect(getDefaultGenerateSettings(createModel('qwen-image'))).toMatchObject({
+      steps: 40,
+      cfgScale: 4,
+      scheduler: 'euler_a',
+    });
+    expect(getDefaultGenerateSettings(createModel('z-image'))).toMatchObject({
+      steps: 8,
+      cfgScale: 1,
+      scheduler: 'euler',
+    });
+  });
+
+  it('matches expected scheduler sets per base', () => {
+    const flux = createModel('flux');
+    const zbase = createModel('z-image', { variant: 'zbase' });
+    const anima = createModel('anima');
+
+    expect(
+      getGenerationModelPolicy(createModel('sdxl'), createSettings(createModel('sdxl'))).scheduler.options.map(
+        (option) => option.value
+      )
+    ).toContain('euler_a');
+    expect(
+      getGenerationModelPolicy(flux, createSettings(flux)).scheduler.options.map((option) => option.value)
+    ).toEqual(['euler', 'heun', 'lcm']);
+    expect(
+      getGenerationModelPolicy(zbase, createSettings(zbase)).scheduler.options.map((option) => option.value)
+    ).toEqual(['euler', 'heun']);
+    expect(
+      getGenerationModelPolicy(anima, createSettings(anima)).scheduler.options.map((option) => option.value)
+    ).toEqual(['euler', 'heun', 'dpmpp_2m', 'dpmpp_2m_sde', 'er_sde', 'lcm']);
+    expect(coerceSchedulerForGraph(zbase, 'lcm')).toBe('euler');
+  });
+
+  it('matches expected prompt policy per base', () => {
+    expect(getPromptPolicy(createModel('flux'), { cfgScale: 4, negativePromptEnabled: true })).toMatchObject({
+      negativeVisible: false,
+      negativeUsedInGraph: false,
+    });
+    expect(getPromptPolicy(createModel('sdxl'), { cfgScale: 1, negativePromptEnabled: true })).toMatchObject({
+      negativeVisible: true,
+      negativeUsedInGraph: true,
+    });
+    expect(getPromptPolicy(createModel('sdxl'), { cfgScale: 1, negativePromptEnabled: false })).toMatchObject({
+      negativeVisible: true,
+      negativeUsedInGraph: false,
+    });
+    expect(getPromptPolicy(createModel('qwen-image'), { cfgScale: 1, negativePromptEnabled: true })).toMatchObject({
+      negativeVisible: true,
+      negativeUsedInGraph: false,
+    });
+    expect(getPromptPolicy(createModel('qwen-image'), { cfgScale: 2, negativePromptEnabled: true })).toMatchObject({
+      negativeVisible: true,
+      negativeUsedInGraph: true,
+      negativeHelpText: 'Used only when CFG is greater than 1.',
+    });
+    expect(getPromptPolicy(externalModel, { cfgScale: 7, negativePromptEnabled: true })).toMatchObject({
+      negativeVisible: false,
+      negativeUsedInGraph: false,
+    });
+    expect(
+      getPromptPolicy(
+        { ...externalModel, capabilities: { supports_negative_prompt: true } },
+        { cfgScale: 7, negativePromptEnabled: true }
+      )
+    ).toMatchObject({ negativeVisible: true, negativeUsedInGraph: true });
+  });
+
+  it('matches expected UI availability per base', () => {
+    expect(getGenerationModelPolicy(createModel('sd-1'), createSettings(createModel('sd-1'))).ui).toMatchObject({
+      clipSkipMax: 12,
+      cfgRescaleVisible: true,
+      schedulerVisible: true,
+    });
+    expect(getGenerationModelPolicy(createModel('sd-2'), createSettings(createModel('sd-2'))).ui).toMatchObject({
+      clipSkipMax: 24,
+      cfgRescaleVisible: true,
+    });
+    expect(getGenerationModelPolicy(createModel('flux'), createSettings(createModel('flux'))).ui).toMatchObject({
+      guidanceLabel: 'Guidance',
+      schedulerVisible: true,
+      clipSkipMax: null,
+    });
+    expect(getGenerationModelPolicy(createModel('sd-3'), createSettings(createModel('sd-3'))).ui).toMatchObject({
+      schedulerVisible: false,
+      sdVaeVisible: false,
+    });
+    expect(
+      getGenerationModelPolicy(createModel('qwen-image'), createSettings(createModel('qwen-image'))).ui.schedulerVisible
+    ).toBe(false);
+    expect(getGenerationModelPolicy(externalModel, createSettings(externalModel)).ui.seedVisible).toBe(false);
+    expect(
+      getGenerationModelPolicy(
+        { ...externalModel, capabilities: { supports_seed: true } },
+        createSettings(externalModel)
+      ).ui.seedVisible
+    ).toBe(true);
+  });
+
+  it('has generation config for every graph builder base', () => {
+    expect(SUPPORTED_GENERATE_BASES).toEqual([
+      'sd-1',
+      'sd-2',
+      'sdxl',
+      'sd-3',
+      'flux',
+      'flux2',
+      'cogview4',
+      'qwen-image',
+      'z-image',
+      'anima',
+    ]);
+  });
+
+  it('does not mark display-only bases as generatable', () => {
+    expect(isSupportedGenerateModel(createModel('sdxl-refiner'))).toBe(false);
+    expect(isSupportedGenerateModel(createModel('unknown'))).toBe(false);
+    expect(isSupportedGenerateModel(createModel('made-up'))).toBe(false);
+    expect(BASE_GENERATION).not.toHaveProperty('external');
+  });
+});
+
+describe('component policies', () => {
+  it('validates FLUX T5, CLIP embed, and VAE requirements', () => {
+    const model = createModel('flux');
+
+    expect(getGenerationValidationReasons(model, createSettings(model))).toEqual([
+      'Generate needs a T5 Encoder for FLUX models.',
+      'Generate needs a CLIP Embed model for FLUX models.',
+      'Generate needs a VAE for FLUX models.',
+    ]);
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, { clipEmbedModel: clipEmbed, t5EncoderModel: t5Encoder, vae: fluxVae })
+      )
+    ).toEqual([]);
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, {
+          clipEmbedModel: t5Encoder,
+          t5EncoderModel: clipEmbed,
+          vae: fluxVae,
+        })
+      )
+    ).toEqual(['Generate needs a T5 Encoder for FLUX models.', 'Generate needs a CLIP Embed model for FLUX models.']);
+  });
+
+  it('rejects unsupported FLUX dev_fill variant', () => {
+    const model = createModel('flux', { variant: 'dev_fill' });
+
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, { clipEmbedModel: clipEmbed, t5EncoderModel: t5Encoder, vae: fluxVae })
+      )
+    ).toEqual(['FLUX Fill models do not support text-to-image generation.']);
+  });
+
+  it('validates FLUX.2 Qwen3 and VAE requirements and allows bundled alternatives', () => {
+    const model = createModel('flux2', { format: 'gguf_quantized', variant: 'klein_9b' });
+    const source = createModel('flux2', { format: 'diffusers', variant: 'klein_9b' });
+    const incompatibleSource = createModel('flux2', {
+      format: 'diffusers',
+      key: 'flux2-4b-source',
+      variant: 'klein_4b',
+    });
+
+    expect(getGenerationValidationReasons(model, createSettings(model))).toEqual([
+      'Generate needs a Qwen3 Encoder for non-Diffusers FLUX.2 models.',
+      'Generate needs a VAE for non-Diffusers FLUX.2 models.',
+    ]);
+    expect(getGenerationValidationReasons(model, createSettings(model, { componentSourceModel: source }))).toEqual([]);
+    expect(
+      getGenerationValidationReasons(model, createSettings(model, { componentSourceModel: incompatibleSource }))
+    ).toEqual(['Generate needs a Qwen3 Encoder for non-Diffusers FLUX.2 models.']);
+    expect(
+      getGenerationValidationReasons(model, createSettings(model, { qwen3EncoderModel: qwen3Encoder, vae: flux2Vae }))
+    ).toEqual([]);
+  });
+
+  it('keeps FLUX.2 component source hidden and auto-selects installed Diffusers sources', () => {
+    const model = createModel('flux2', { format: 'gguf_quantized', variant: 'klein_9b' });
+    const source = createModel('flux2', { format: 'diffusers', variant: 'klein_9b' });
+    const incompatibleSource = createModel('flux2', {
+      format: 'diffusers',
+      key: 'flux2-4b-source',
+      variant: 'klein_4b',
+    });
+    const settings = createSettings(model);
+
+    expect(getComponentSectionPolicy(model, settings).slots.map((slot) => slot.key)).toEqual([
+      'qwen3EncoderModel',
+      'vae',
+    ]);
+    expect(getAutoFlux2ComponentSourceModel(model, settings, [incompatibleSource, source])?.key).toBe(source.key);
+    expect(
+      getAutoFlux2ComponentSourceModel(model, { ...settings, qwen3EncoderModel: qwen3Encoder }, [incompatibleSource])
+        ?.key
+    ).toBe(incompatibleSource.key);
+  });
+
+  it('validates Qwen Image Qwen-VL and VAE requirements', () => {
+    const model = createModel('qwen-image', { format: 'checkpoint' });
+
+    expect(getGenerationValidationReasons(model, createSettings(model))).toEqual([
+      'Generate needs a Qwen VL Encoder for non-Diffusers Qwen Image models.',
+      'Generate needs a VAE for non-Diffusers Qwen Image models.',
+    ]);
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, { qwenVLEncoderModel: qwenVlEncoder, vae: qwenImageVae })
+      )
+    ).toEqual([]);
+  });
+
+  it('validates Z-Image non-anima Qwen3 and flux VAE requirements', () => {
+    const model = createModel('z-image', { format: 'checkpoint' });
+
+    expect(getGenerationValidationReasons(model, createSettings(model))).toEqual([
+      'Generate needs a Qwen3 Encoder for Z-Image models.',
+      'Generate needs a VAE for Z-Image models.',
+    ]);
+    expect(
+      getGenerationValidationReasons(model, createSettings(model, { qwen3EncoderModel: qwen3Encoder, vae: fluxVae }))
+    ).toEqual([]);
+  });
+
+  it('validates Anima Qwen3 and allowed VAE bases', () => {
+    const model = createModel('anima');
+
+    expect(getGenerationValidationReasons(model, createSettings(model))).toEqual([
+      'Generate needs a Qwen3 Encoder for Anima models.',
+      'Generate needs a VAE for Anima models.',
+    ]);
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, { qwen3EncoderModel: animaQwen3Encoder, vae: qwenImageVae })
+      )
+    ).toEqual([]);
+  });
+
+  it('validates dimensions against bounds and model-family grid', () => {
+    const model = createModel('flux2');
+
+    expect(getGenerationValidationReasons(model, createSettings(model, { width: 0 }))).toContain(
+      'Generate width must be between 64 and 4096.'
+    );
+    expect(getGenerationValidationReasons(model, createSettings(model, { height: 4104 }))).toContain(
+      'Generate height must be between 64 and 4096.'
+    );
+    expect(getGenerationValidationReasons(model, createSettings(model, { height: 888 }))).toContain(
+      'Generate height must be a multiple of 16.'
+    );
+  });
+
+  it('rejects external image generators without a registered invocation node', () => {
+    const model: GenerateModelConfig = {
+      base: 'external',
+      capabilities: { modes: ['txt2img'] },
+      format: 'external_api',
+      key: 'external-unknown',
+      name: 'Unknown External Provider',
+      provider_id: 'future-provider',
+      type: 'external_image_generator',
+    };
+
+    expect(getGenerationValidationReasons(model, createSettings(model))).toContain(
+      "No invocation node registered for external provider 'future-provider'."
+    );
+  });
+
+  it('renders no component slots for bases without extra requirements', () => {
+    expect(getComponentSectionPolicy(createModel('sdxl'), createSettings(createModel('sdxl'))).slots).toEqual([]);
+    expect(getComponentSectionPolicy(createModel('cogview4'), createSettings(createModel('cogview4'))).slots).toEqual(
+      []
+    );
+  });
+
+  it('clears incompatible selections when the selected model changes', () => {
+    const model = createModel('sdxl');
+    const settings = createSettings(createModel('sd-1'), {
+      cfgRescaleMultiplier: 0.5,
+      clipSkip: 2,
+      loras: [
+        { isEnabled: true, model: sd1Lora, weight: 1 },
+        { isEnabled: true, model: sdxlLora, weight: 1 },
+      ],
+      seamlessXAxis: true,
+      t5EncoderModel: t5Encoder,
+      vae: sdxlVae,
+    });
+
+    const result = getSettingsWithCompatibleModelSelections(settings, model, []);
+
+    expect(result.settings.modelKey).toBe(model.key);
+    expect(result.settings.loras.map((lora) => lora.model.key)).toEqual(['sdxl-lora']);
+    expect(result.settings.vae).toEqual(sdxlVae);
+    expect(result.settings.t5EncoderModel).toBeNull();
+    expect(result.settings.clipSkip).toBe(0);
+    expect(result.settings.cfgRescaleMultiplier).toBe(0);
+    expect(result.settings.seamlessXAxis).toBe(true);
+    expect(result.clearedLabels).toEqual(['LoRAs', 'T5 Encoder', 'CLIP skip', 'CFG rescale']);
+  });
+
+  it('reconciles dimensions to the new model grid when the selected model changes', () => {
+    const model = createModel('cogview4');
+    const settings = createSettings(createModel('sdxl'), { height: 520, width: 520 });
+    const result = getSettingsWithCompatibleModelSelections(settings, model, []);
+
+    expect(result.settings.width).toBe(512);
+    expect(result.settings.height).toBe(512);
+    expect(result.clearedLabels).toContain('Dimensions');
+  });
+
+  it('keeps selected VAE when applying model defaults without a VAE override', () => {
+    const model = createModel('sdxl', { default_settings: { steps: 12 } });
+    const settings = createSettings(model, { vae: sdxlVae });
+    const nextSettings = getSettingsWithModelDefaults(settings, model);
+
+    expect(nextSettings.steps).toBe(12);
+    expect(nextSettings.vae).toBe(sdxlVae);
+  });
+
+  it('reports selected model records that disappeared from the backend model list', () => {
+    const model = createModel('flux');
+    const settings = createSettings(model, {
+      clipEmbedModel: clipEmbed,
+      loras: [{ isEnabled: true, model: sd1Lora, weight: 1 }],
+      t5EncoderModel: t5Encoder,
+      vae: fluxVae,
+    });
+
+    expect(getGenerationModelAvailabilityReasons(model, settings, [model as never, t5Encoder as never])).toEqual([
+      'CLIP Embed "CLIP Embed" is no longer installed.',
+      'VAE "FLUX VAE" is no longer installed.',
+      'LoRA "SD 1 LoRA" is no longer installed.',
+    ]);
+  });
+
+  it('clears same-base FLUX.2 component selections that do not match the new variant', () => {
+    const model = createModel('flux2', { format: 'gguf_quantized', variant: 'klein_9b' });
+    const incompatibleQwen3: ComponentModelConfig = {
+      base: 'any',
+      key: 'qwen3-4b',
+      name: 'Qwen3 4B Encoder',
+      type: 'qwen3_encoder',
+      variant: 'qwen3_4b',
+    };
+    const settings = createSettings(createModel('flux2', { format: 'gguf_quantized', variant: 'klein_4b' }), {
+      qwen3EncoderModel: incompatibleQwen3,
+      vae: flux2Vae,
+    });
+
+    const result = getSettingsWithCompatibleModelSelections(settings, model, []);
+
+    expect(result.settings.qwen3EncoderModel).toBeNull();
+    expect(result.settings.vae).toEqual(flux2Vae);
+    expect(result.clearedLabels).toEqual(['Qwen3 Encoder']);
+  });
+
+  it('requires enabled IP Adapter reference images to have an image and compatible adapter model', () => {
+    const model = createModel('sd-1');
+
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, {
+          referenceImages: [
+            {
+              id: 'ref-1',
+              isEnabled: true,
+              config: {
+                beginEndStepPct: [0, 1],
+                clipVisionModel: 'ViT-H',
+                image: null,
+                method: 'full',
+                model: sd1IpAdapter,
+                type: 'ip_adapter',
+                weight: 1,
+              },
+            },
+          ],
+        })
+      )
+    ).toContain('Reference Image #1 needs an image.');
+
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, {
+          referenceImages: [
+            {
+              id: 'ref-1',
+              isEnabled: true,
+              config: {
+                beginEndStepPct: [0, 1],
+                clipVisionModel: 'ViT-H',
+                image: referenceImage,
+                method: 'full',
+                model: null,
+                type: 'ip_adapter',
+                weight: 1,
+              },
+            },
+          ],
+        })
+      )
+    ).toContain('Reference Image #1 needs a compatible IP Adapter model.');
+  });
+
+  it('clears reference images when switching to a model without reference image support', () => {
+    const settings = createSettings(createModel('sdxl'), {
+      referenceImages: [
+        {
+          id: 'ref-1',
+          isEnabled: true,
+          config: {
+            beginEndStepPct: [0, 1],
+            clipVisionModel: 'ViT-H',
+            image: referenceImage,
+            method: 'full',
+            model: sdxlIpAdapter,
+            type: 'ip_adapter',
+            weight: 1,
+          },
+        },
+      ],
+    });
+
+    const result = getSettingsWithCompatibleModelSelections(settings, createModel('cogview4'), [sdxlIpAdapter]);
+
+    expect(result.settings.referenceImages).toEqual([]);
+    expect(result.clearedLabels).toContain('Reference Images');
+  });
+
+  it('re-targets reference image configs to the new model base, keeping the image and enabled state', () => {
+    const settings = createSettings(createModel('sdxl'), {
+      referenceImages: [
+        {
+          id: 'ref-1',
+          isEnabled: false,
+          config: {
+            beginEndStepPct: [0, 1],
+            clipVisionModel: 'ViT-H',
+            image: referenceImage,
+            method: 'style',
+            model: sdxlIpAdapter,
+            type: 'ip_adapter',
+            weight: 0.5,
+          },
+        },
+      ],
+    });
+
+    const result = getSettingsWithCompatibleModelSelections(settings, createModel('sd-1'), [
+      sd1IpAdapter,
+      sdxlIpAdapter,
+    ]);
+
+    expect(result.settings.referenceImages).toEqual([
+      {
+        id: 'ref-1',
+        isEnabled: false,
+        config: {
+          beginEndStepPct: [0, 1],
+          clipVisionModel: 'ViT-H',
+          image: referenceImage,
+          method: 'full',
+          model: sd1IpAdapter,
+          type: 'ip_adapter',
+          weight: 1,
+        },
+      },
+    ]);
+    expect(result.clearedLabels).toContain('Reference Images');
+  });
+
+  it('re-targets reference images across a flux2 -> sdxl -> flux2 round trip', () => {
+    const flux2Model = createModel('flux2');
+    const sdxlModel = createModel('sdxl');
+    const settings = createSettings(flux2Model, {
+      referenceImages: [
+        { id: 'ref-1', isEnabled: true, config: { image: referenceImage, type: 'flux2_reference_image' } },
+      ],
+    });
+
+    const toSdxl = getSettingsWithCompatibleModelSelections(settings, sdxlModel, [sdxlIpAdapter]);
+
+    expect(toSdxl.settings.referenceImages[0]?.config).toMatchObject({
+      image: referenceImage,
+      model: sdxlIpAdapter,
+      type: 'ip_adapter',
+    });
+
+    const backToFlux2 = getSettingsWithCompatibleModelSelections(toSdxl.settings, flux2Model, [sdxlIpAdapter]);
+
+    expect(backToFlux2.settings.referenceImages).toEqual([
+      { id: 'ref-1', isEnabled: true, config: { image: referenceImage, type: 'flux2_reference_image' } },
+    ]);
+  });
+
+  it('keeps compatible reference images untouched when the selected model changes', () => {
+    const referenceImages: GenerateSettings['referenceImages'] = [
+      {
+        id: 'ref-1',
+        isEnabled: true,
+        config: {
+          beginEndStepPct: [0, 1],
+          clipVisionModel: 'ViT-H',
+          image: referenceImage,
+          method: 'full',
+          model: sdxlIpAdapter,
+          type: 'ip_adapter',
+          weight: 1,
+        },
+      },
+    ];
+    const settings = createSettings(createModel('sdxl'), { referenceImages });
+
+    const result = getSettingsWithCompatibleModelSelections(settings, createModel('sdxl', { key: 'sdxl-other' }), [
+      sdxlIpAdapter,
+    ]);
+
+    expect(result.settings.referenceImages).toBe(referenceImages);
+    expect(result.clearedLabels).not.toContain('Reference Images');
+  });
+
+  it('reports reference image support per model', () => {
+    expect(isReferenceImageSupported(createModel('sdxl'))).toBe(true);
+    expect(isReferenceImageSupported(createModel('cogview4'))).toBe(false);
+    expect(isReferenceImageSupported(createModel('qwen-image'))).toBe(false);
+    expect(isReferenceImageSupported(createModel('qwen-image', { variant: 'edit' }))).toBe(true);
+    expect(isReferenceImageSupported(externalModel)).toBe(false);
+    expect(
+      isReferenceImageSupported({
+        ...externalModel,
+        capabilities: { ...externalModel.capabilities, supports_reference_images: true },
+      })
+    ).toBe(true);
+    expect(isReferenceImageSupported(undefined)).toBe(false);
+  });
+
+  it('derives the reference image limit from external provider capabilities', () => {
+    expect(getMaxReferenceImages(createModel('sdxl'))).toBe(5);
+    expect(getMaxReferenceImages(createModel('cogview4'))).toBe(0);
+    expect(
+      getMaxReferenceImages({
+        ...externalModel,
+        capabilities: { ...externalModel.capabilities, max_reference_images: 14, supports_reference_images: true },
+      })
+    ).toBe(14);
+    expect(
+      getMaxReferenceImages({
+        ...externalModel,
+        capabilities: { ...externalModel.capabilities, supports_reference_images: true },
+      })
+    ).toBe(5);
+  });
+
+  it('rejects unsupported reference image configs for the selected model', () => {
+    const model = createModel('sd-3');
+
+    expect(
+      getGenerationValidationReasons(
+        model,
+        createSettings(model, {
+          referenceImages: [
+            { id: 'ref-1', isEnabled: true, config: { image: referenceImage, type: 'flux2_reference_image' } },
+          ],
+        })
+      )
+    ).toContain('Reference Image #1 is not supported by sd-3 model.');
+  });
+
+  it('reports missing reference image model dependencies', () => {
+    const model = createModel('sd-1');
+
+    expect(
+      getGenerationModelAvailabilityReasons(
+        model,
+        createSettings(model, {
+          referenceImages: [
+            {
+              id: 'ref-1',
+              isEnabled: true,
+              config: {
+                beginEndStepPct: [0, 1],
+                clipVisionModel: 'ViT-H',
+                image: referenceImage,
+                method: 'full',
+                model: sd1IpAdapter,
+                type: 'ip_adapter',
+                weight: 1,
+              },
+            },
+          ],
+        }),
+        [model as never]
+      )
+    ).toContain('Reference Image model "SD 1 IP Adapter" is no longer installed.');
+  });
+
+  it('ignores missing reference image model dependencies when the reference image is disabled', () => {
+    const model = createModel('sd-1');
+
+    expect(
+      getGenerationModelAvailabilityReasons(
+        model,
+        createSettings(model, {
+          referenceImages: [
+            {
+              id: 'ref-1',
+              isEnabled: false,
+              config: {
+                beginEndStepPct: [0, 1],
+                clipVisionModel: 'ViT-H',
+                image: referenceImage,
+                method: 'full',
+                model: sd1IpAdapter,
+                type: 'ip_adapter',
+                weight: 1,
+              },
+            },
+          ],
+        }),
+        [model as never]
+      )
+    ).toEqual([]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/baseGenerationPolicies.ts b/invokeai/frontend/webv2/src/workbench/generation/baseGenerationPolicies.ts
new file mode 100644
index 00000000000..dd35d8c705f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/baseGenerationPolicies.ts
@@ -0,0 +1,1334 @@
+import type { KnownModelBase } from '@workbench/models/baseIdentity';
+import type { ModelConfig, ModelTaxonomyType } from '@workbench/models/types';
+
+import type {
+  GenerateModelConfig,
+  GenerateReferenceImage,
+  GenerateReferenceImageAsset,
+  GenerateReferenceImageConfig,
+  GenerateSettings,
+  MainModelConfig,
+  VaePrecision,
+} from './types';
+
+import {
+  getCompatibleDiffusersComponentSource,
+  isAnimaQwen3Encoder,
+  isAnimaVae,
+  isClipVariant,
+  isDiffusersMainForBase,
+  isFlux2DiffusersSourceForModel,
+  isFlux2Qwen3EncoderForModel,
+  isNonAnimaQwen3Encoder,
+  isVaeForBases,
+  type GenerateComponentFilter,
+} from './componentCompatibility';
+import {
+  clampDimension,
+  DEFAULT_REFERENCE_IMAGE_LIMIT,
+  deriveAspectRatioId,
+  isLoraCompatibleWithModel,
+  MAX_DIMENSION,
+  MIN_DIMENSION,
+  SEED_MAX,
+} from './settings';
+
+// Generation policy registry keyed by model base. Display identity stays in @workbench/models/baseIdentity;
+// graph topology stays explicit in graph.ts.
+
+export interface SchedulerOption {
+  value: string;
+  label: string;
+}
+
+export type SchedulerSetId = 'standard' | 'flow' | 'flow-no-lcm' | 'anima';
+
+export type NegativePromptUsage = 'always' | 'cfg-gated' | 'never';
+
+export type GuidanceLabel = 'CFG' | 'Guidance';
+
+export interface BaseGenerationConfig {
+  dimensions: {
+    grid: number;
+    optimalSide: number;
+  };
+  defaults: {
+    steps: number;
+    cfgScale: number;
+    scheduler: string;
+  };
+  schedulerSet: SchedulerSetId;
+  schedulerAppliesToGraph: boolean;
+  guidanceLabel: GuidanceLabel;
+  negativePrompt: {
+    visible: boolean;
+    usage: NegativePromptUsage;
+  };
+  ui: {
+    sdVaeOverride: boolean;
+    colorCompensation: boolean;
+    vaePrecision: boolean;
+    seamless: boolean;
+    cfgRescale: boolean;
+    clipSkipMax?: number;
+  };
+}
+
+type GenerateDefaultSettings =
+  | {
+      scheduler?: string | null;
+      steps?: number | null;
+      cfg_scale?: number | null;
+      guidance?: number | null;
+      cfg_rescale_multiplier?: number | null;
+      width?: number | null;
+      height?: number | null;
+      vae?: string | null;
+      vae_precision?: string | null;
+    }
+  | null
+  | undefined;
+
+export const SCHEDULER_OPTIONS: SchedulerOption[] = [
+  { label: 'DDIM', value: 'ddim' },
+  { label: 'DDPM', value: 'ddpm' },
+  { label: 'DEIS', value: 'deis' },
+  { label: 'DEIS Karras', value: 'deis_k' },
+  { label: 'DPM++ 2S', value: 'dpmpp_2s' },
+  { label: 'DPM++ 2S Karras', value: 'dpmpp_2s_k' },
+  { label: 'DPM++ 2M', value: 'dpmpp_2m' },
+  { label: 'DPM++ 2M Karras', value: 'dpmpp_2m_k' },
+  { label: 'DPM++ 2M SDE', value: 'dpmpp_2m_sde' },
+  { label: 'DPM++ 2M SDE Karras', value: 'dpmpp_2m_sde_k' },
+  { label: 'DPM++ 3M', value: 'dpmpp_3m' },
+  { label: 'DPM++ 3M Karras', value: 'dpmpp_3m_k' },
+  { label: 'DPM++ SDE', value: 'dpmpp_sde' },
+  { label: 'DPM++ SDE Karras', value: 'dpmpp_sde_k' },
+  { label: 'ER-SDE', value: 'er_sde' },
+  { label: 'Euler', value: 'euler' },
+  { label: 'Euler Karras', value: 'euler_k' },
+  { label: 'Euler Ancestral', value: 'euler_a' },
+  { label: 'Heun', value: 'heun' },
+  { label: 'Heun Karras', value: 'heun_k' },
+  { label: 'KDPM 2', value: 'kdpm_2' },
+  { label: 'KDPM 2 Karras', value: 'kdpm_2_k' },
+  { label: 'KDPM 2 Ancestral', value: 'kdpm_2_a' },
+  { label: 'KDPM 2 Ancestral Karras', value: 'kdpm_2_a_k' },
+  { label: 'LCM', value: 'lcm' },
+  { label: 'LMS', value: 'lms' },
+  { label: 'LMS Karras', value: 'lms_k' },
+  { label: 'PNDM', value: 'pndm' },
+  { label: 'TCD', value: 'tcd' },
+  { label: 'UniPC', value: 'unipc' },
+  { label: 'UniPC Karras', value: 'unipc_k' },
+];
+
+export const FLOW_SCHEDULER_OPTIONS: SchedulerOption[] = [
+  { label: 'Euler', value: 'euler' },
+  { label: 'Heun (2nd order)', value: 'heun' },
+  { label: 'LCM', value: 'lcm' },
+];
+
+export const FLOW_SCHEDULER_OPTIONS_WITHOUT_LCM: SchedulerOption[] = [
+  { label: 'Euler', value: 'euler' },
+  { label: 'Heun (2nd order)', value: 'heun' },
+];
+
+export const ANIMA_SCHEDULER_OPTIONS: SchedulerOption[] = [
+  { label: 'Euler', value: 'euler' },
+  { label: 'Heun (2nd order)', value: 'heun' },
+  { label: 'DPM++ 2M', value: 'dpmpp_2m' },
+  { label: 'DPM++ 2M SDE', value: 'dpmpp_2m_sde' },
+  { label: 'ER-SDE', value: 'er_sde' },
+  { label: 'LCM', value: 'lcm' },
+];
+
+const KNOWN_SCHEDULERS = new Set(SCHEDULER_OPTIONS.map((option) => option.value));
+const FLOW_SCHEDULERS = new Set(FLOW_SCHEDULER_OPTIONS.map((option) => option.value));
+const FLOW_SCHEDULERS_WITHOUT_LCM = new Set(FLOW_SCHEDULER_OPTIONS_WITHOUT_LCM.map((option) => option.value));
+const ANIMA_SCHEDULERS = new Set(ANIMA_SCHEDULER_OPTIONS.map((option) => option.value));
+
+export const isKnownScheduler = (value: string): boolean => KNOWN_SCHEDULERS.has(value);
+
+export const BASE_GENERATION = {
+  'sd-1': {
+    dimensions: { grid: 8, optimalSide: 512 },
+    defaults: { steps: 30, cfgScale: 7, scheduler: 'euler_a' },
+    schedulerSet: 'standard',
+    schedulerAppliesToGraph: true,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'always' },
+    ui: {
+      sdVaeOverride: true,
+      colorCompensation: false,
+      vaePrecision: true,
+      seamless: true,
+      cfgRescale: true,
+      clipSkipMax: 12,
+    },
+  },
+  'sd-2': {
+    dimensions: { grid: 8, optimalSide: 512 },
+    defaults: { steps: 30, cfgScale: 7, scheduler: 'euler_a' },
+    schedulerSet: 'standard',
+    schedulerAppliesToGraph: true,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'always' },
+    ui: {
+      sdVaeOverride: true,
+      colorCompensation: false,
+      vaePrecision: true,
+      seamless: true,
+      cfgRescale: true,
+      clipSkipMax: 24,
+    },
+  },
+  sdxl: {
+    dimensions: { grid: 8, optimalSide: 1024 },
+    defaults: { steps: 30, cfgScale: 7, scheduler: 'euler_a' },
+    schedulerSet: 'standard',
+    schedulerAppliesToGraph: true,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'always' },
+    ui: { sdVaeOverride: true, colorCompensation: true, vaePrecision: true, seamless: true, cfgRescale: false },
+  },
+  'sd-3': {
+    dimensions: { grid: 16, optimalSide: 1024 },
+    defaults: { steps: 30, cfgScale: 7, scheduler: 'euler_a' },
+    schedulerSet: 'standard',
+    schedulerAppliesToGraph: false,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'always' },
+    ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+  },
+  flux: {
+    dimensions: { grid: 16, optimalSide: 1024 },
+    defaults: { steps: 4, cfgScale: 4, scheduler: 'euler' },
+    schedulerSet: 'flow',
+    schedulerAppliesToGraph: true,
+    guidanceLabel: 'Guidance',
+    negativePrompt: { visible: false, usage: 'never' },
+    ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+  },
+  flux2: {
+    dimensions: { grid: 16, optimalSide: 1024 },
+    defaults: { steps: 4, cfgScale: 1, scheduler: 'euler' },
+    schedulerSet: 'flow',
+    schedulerAppliesToGraph: true,
+    guidanceLabel: 'Guidance',
+    negativePrompt: { visible: false, usage: 'never' },
+    ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+  },
+  cogview4: {
+    dimensions: { grid: 32, optimalSide: 1024 },
+    defaults: { steps: 30, cfgScale: 7, scheduler: 'euler_a' },
+    schedulerSet: 'standard',
+    schedulerAppliesToGraph: false,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'always' },
+    ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+  },
+  'qwen-image': {
+    dimensions: { grid: 16, optimalSide: 1024 },
+    defaults: { steps: 40, cfgScale: 4, scheduler: 'euler_a' },
+    schedulerSet: 'standard',
+    schedulerAppliesToGraph: false,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'cfg-gated' },
+    ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+  },
+  'z-image': {
+    dimensions: { grid: 16, optimalSide: 1024 },
+    defaults: { steps: 8, cfgScale: 1, scheduler: 'euler' },
+    schedulerSet: 'flow',
+    schedulerAppliesToGraph: true,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'cfg-gated' },
+    ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+  },
+  anima: {
+    dimensions: { grid: 8, optimalSide: 1024 },
+    defaults: { steps: 30, cfgScale: 4, scheduler: 'euler' },
+    schedulerSet: 'anima',
+    schedulerAppliesToGraph: true,
+    guidanceLabel: 'CFG',
+    negativePrompt: { visible: true, usage: 'cfg-gated' },
+    ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+  },
+} as const satisfies Partial<Record<KnownModelBase, BaseGenerationConfig>>;
+
+export type SupportedGenerateBase = keyof typeof BASE_GENERATION;
+
+export const SUPPORTED_GENERATE_BASES = Object.keys(BASE_GENERATION) as SupportedGenerateBase[];
+
+export interface GenerationModelPolicy {
+  isSupported: boolean;
+  dimensions: {
+    grid: number;
+    min: number;
+    max: number;
+    optimal: number;
+  };
+  defaults: {
+    steps: number;
+    cfgScale: number;
+    cfgRescaleMultiplier: number;
+    scheduler: string;
+    vaePrecision: VaePrecision;
+  };
+  scheduler: {
+    options: readonly SchedulerOption[];
+    defaultValue: string;
+    appliesToGraph: boolean;
+    coerceForGraph: (value: string) => string;
+  };
+  prompt: {
+    negativeVisible: boolean;
+    negativeUsedInGraph: boolean;
+    negativeHelpText?: string;
+  };
+  ui: {
+    guidanceLabel: GuidanceLabel;
+    schedulerVisible: boolean;
+    clipSkipMax: number | null;
+    cfgRescaleVisible: boolean;
+    colorCompensationVisible: boolean;
+    seamlessVisible: boolean;
+    sdVaeVisible: boolean;
+    vaePrecisionVisible: boolean;
+    seedVisible: boolean;
+  };
+}
+
+const FALLBACK_GENERATION_CONFIG: BaseGenerationConfig = {
+  dimensions: { grid: 8, optimalSide: 1024 },
+  defaults: { steps: 30, cfgScale: 7, scheduler: 'euler_a' },
+  schedulerSet: 'standard',
+  schedulerAppliesToGraph: false,
+  guidanceLabel: 'CFG',
+  negativePrompt: { visible: true, usage: 'never' },
+  ui: { sdVaeOverride: false, colorCompensation: false, vaePrecision: false, seamless: false, cfgRescale: false },
+};
+
+// Fallbacks keep UI selectors crash-safe; isSupportedGenerateModel() still blocks invocation.
+const getBaseGenerationConfig = (
+  model: Pick<GenerateModelConfig, 'base' | 'type'> | undefined
+): BaseGenerationConfig => {
+  if (!model || model.type === 'external_image_generator') {
+    return FALLBACK_GENERATION_CONFIG;
+  }
+
+  return (BASE_GENERATION as Partial<Record<string, BaseGenerationConfig>>)[model.base] ?? FALLBACK_GENERATION_CONFIG;
+};
+
+const getNumber = (value: number | null | undefined, fallback: number): number =>
+  Number.isFinite(value) && value !== null && value !== undefined ? value : fallback;
+
+export const getGenerationDimensions = (model: Pick<GenerateModelConfig, 'base' | 'type'> | undefined) => {
+  const config = getBaseGenerationConfig(model);
+
+  return {
+    grid: config.dimensions.grid,
+    min: MIN_DIMENSION,
+    max: MAX_DIMENSION,
+    optimal: config.dimensions.optimalSide,
+  };
+};
+
+export const getGenerationDefaults = (model: GenerateModelConfig | undefined) => {
+  const config = getBaseGenerationConfig(model);
+  const defaults = model?.default_settings as GenerateDefaultSettings;
+
+  return {
+    cfgRescaleMultiplier: getNumber(defaults?.cfg_rescale_multiplier, 0),
+    cfgScale: getNumber(defaults?.cfg_scale ?? defaults?.guidance, config.defaults.cfgScale),
+    scheduler: defaults?.scheduler ?? config.defaults.scheduler,
+    steps: Math.max(1, Math.round(getNumber(defaults?.steps, config.defaults.steps))),
+    vaePrecision: defaults?.vae_precision === 'fp16' ? ('fp16' as const) : ('fp32' as const),
+  };
+};
+
+export const getSchedulerOptions = (
+  model:
+    | (Pick<GenerateModelConfig, 'base' | 'type' | 'variant'> & Partial<Pick<MainModelConfig, 'format'>>)
+    | undefined,
+  currentValue?: string
+): readonly SchedulerOption[] => {
+  const config = getBaseGenerationConfig(model);
+  const options = (() => {
+    if (model?.base === 'z-image' && model.variant === 'zbase') {
+      return FLOW_SCHEDULER_OPTIONS_WITHOUT_LCM;
+    }
+
+    switch (config.schedulerSet) {
+      case 'flow':
+        return FLOW_SCHEDULER_OPTIONS;
+      case 'flow-no-lcm':
+        return FLOW_SCHEDULER_OPTIONS_WITHOUT_LCM;
+      case 'anima':
+        return ANIMA_SCHEDULER_OPTIONS;
+      case 'standard':
+        return SCHEDULER_OPTIONS;
+    }
+  })();
+
+  // Keep persisted/metadata scheduler values visible until the user picks a supported option.
+  return currentValue && !options.some((option) => option.value === currentValue)
+    ? [{ label: currentValue, value: currentValue }, ...options]
+    : options;
+};
+
+export const coerceSchedulerForGraph = (
+  model:
+    | (Pick<GenerateModelConfig, 'base' | 'type' | 'variant'> & Partial<Pick<MainModelConfig, 'format'>>)
+    | undefined,
+  scheduler: string
+): string => {
+  const config = getBaseGenerationConfig(model);
+
+  // Some graph builders ignore scheduler entirely; coerce to stable metadata/defaults instead of leaking stale UI state.
+  if (!config.schedulerAppliesToGraph) {
+    return config.defaults.scheduler;
+  }
+
+  if (model?.base === 'z-image' && model.variant === 'zbase') {
+    return FLOW_SCHEDULERS_WITHOUT_LCM.has(scheduler) ? scheduler : 'euler';
+  }
+
+  switch (config.schedulerSet) {
+    case 'flow':
+      return FLOW_SCHEDULERS.has(scheduler) ? scheduler : 'euler';
+    case 'flow-no-lcm':
+      return FLOW_SCHEDULERS_WITHOUT_LCM.has(scheduler) ? scheduler : 'euler';
+    case 'anima':
+      return ANIMA_SCHEDULERS.has(scheduler) ? scheduler : 'euler';
+    case 'standard':
+      return KNOWN_SCHEDULERS.has(scheduler) ? scheduler : config.defaults.scheduler;
+  }
+};
+
+export const getPromptPolicy = (
+  model: GenerateModelConfig | undefined,
+  settings: Pick<GenerateSettings, 'cfgScale' | 'negativePromptEnabled'>
+) => {
+  if (model?.type === 'external_image_generator') {
+    const supportsNegativePrompt = model.capabilities?.supports_negative_prompt === true;
+
+    return {
+      negativeVisible: supportsNegativePrompt,
+      negativeUsedInGraph: settings.negativePromptEnabled && supportsNegativePrompt,
+    };
+  }
+
+  const config = getBaseGenerationConfig(model);
+  // Visibility controls the textarea; usage controls whether the graph wires negative conditioning.
+  const negativeUsedInGraph =
+    settings.negativePromptEnabled &&
+    (config.negativePrompt.usage === 'always' ||
+      (config.negativePrompt.usage === 'cfg-gated' && settings.cfgScale > 1));
+
+  return {
+    negativeVisible: config.negativePrompt.visible,
+    negativeUsedInGraph,
+    ...(config.negativePrompt.usage === 'cfg-gated'
+      ? { negativeHelpText: 'Used only when CFG is greater than 1.' }
+      : {}),
+  };
+};
+
+export const getGenerationUiPolicy = (
+  model: GenerateModelConfig | undefined,
+  _settings: Pick<GenerateSettings, 'cfgScale'>
+) => {
+  const config = getBaseGenerationConfig(model);
+  const seedVisible = model?.type === 'external_image_generator' ? model.capabilities?.supports_seed === true : true;
+
+  return {
+    guidanceLabel: config.guidanceLabel,
+    schedulerVisible: config.schedulerAppliesToGraph,
+    clipSkipMax: config.ui.clipSkipMax ?? null,
+    cfgRescaleVisible: config.ui.cfgRescale,
+    colorCompensationVisible: config.ui.colorCompensation,
+    seamlessVisible: config.ui.seamless,
+    sdVaeVisible: config.ui.sdVaeOverride,
+    vaePrecisionVisible: config.ui.vaePrecision,
+    seedVisible,
+  };
+};
+
+export const isSupportedGenerateModel = <T extends { base: string; type: string }>(
+  model: T
+): model is T & GenerateModelConfig =>
+  (model.type === 'main' && model.base in BASE_GENERATION) ||
+  (model.type === 'external_image_generator' && model.base === 'external');
+
+export const isGenerateModelSelectable = <T extends ModelConfig>(model: T): boolean => isSupportedGenerateModel(model);
+
+export const EXTERNAL_PROVIDER_NODE_TYPES: Record<string, string> = {
+  alibabacloud: 'alibabacloud_image_generation',
+  gemini: 'gemini_image_generation',
+  openai: 'openai_image_generation',
+  seedream: 'seedream_image_generation',
+};
+
+export const getExternalProviderNodeType = (providerId: unknown): string | null =>
+  typeof providerId === 'string' ? (EXTERNAL_PROVIDER_NODE_TYPES[providerId] ?? null) : null;
+
+export const getGenerationModelPolicy = (
+  model: GenerateModelConfig | undefined,
+  settings: GenerateSettings
+): GenerationModelPolicy => {
+  const config = getBaseGenerationConfig(model);
+  const dimensions = getGenerationDimensions(model);
+  const defaults = getGenerationDefaults(model);
+
+  return {
+    isSupported: model ? isSupportedGenerateModel(model) : false,
+    dimensions,
+    defaults,
+    scheduler: {
+      options: getSchedulerOptions(model, settings.scheduler),
+      defaultValue: defaults.scheduler,
+      appliesToGraph: config.schedulerAppliesToGraph,
+      coerceForGraph: (value: string) => coerceSchedulerForGraph(model, value),
+    },
+    prompt: getPromptPolicy(model, settings),
+    ui: getGenerationUiPolicy(model, settings),
+  };
+};
+
+export const getDefaultGenerateSettings = (model?: GenerateModelConfig): GenerateSettings => {
+  const defaults = getGenerationDefaults(model);
+  const dimensions = getGenerationDimensions(model);
+  const defaultSettings = model?.default_settings as GenerateDefaultSettings;
+  const width = clampDimension(getNumber(defaultSettings?.width, dimensions.optimal), dimensions.grid);
+  const height = clampDimension(getNumber(defaultSettings?.height, dimensions.optimal), dimensions.grid);
+
+  return {
+    aspectRatioId: deriveAspectRatioId(width, height),
+    aspectRatioIsLocked: false,
+    aspectRatioValue: height > 0 ? width / height : 1,
+    batchCount: 1,
+    cfgRescaleMultiplier: defaults.cfgRescaleMultiplier,
+    cfgScale: defaults.cfgScale,
+    clipSkip: 0,
+    colorCompensation: false,
+    clipEmbedModel: null,
+    clipGEmbedModel: null,
+    clipLEmbedModel: null,
+    componentSourceModel: null,
+    height,
+    loras: [],
+    modelKey: model?.key ?? '',
+    negativePromptEnabled: true,
+    negativePrompt: '',
+    negativePromptHeightPx: 56,
+    positivePrompt: '',
+    positivePromptHeightPx: 96,
+    qwen3EncoderModel: null,
+    qwenVLEncoderModel: null,
+    referenceImages: [],
+    scheduler: defaults.scheduler,
+    seamlessXAxis: false,
+    seamlessYAxis: false,
+    seed: Math.floor(Math.random() * SEED_MAX),
+    shouldRandomizeSeed: true,
+    steps: defaults.steps,
+    t5EncoderModel: null,
+    vae: null,
+    vaePrecision: defaults.vaePrecision,
+    width,
+  };
+};
+
+export const getSettingsWithModelDefaults = (
+  settings: GenerateSettings,
+  model: GenerateModelConfig
+): GenerateSettings => {
+  const modelDefaults = getDefaultGenerateSettings(model);
+
+  return {
+    ...settings,
+    aspectRatioId: modelDefaults.aspectRatioId,
+    aspectRatioIsLocked: false,
+    aspectRatioValue: modelDefaults.aspectRatioValue,
+    cfgRescaleMultiplier: modelDefaults.cfgRescaleMultiplier,
+    cfgScale: modelDefaults.cfgScale,
+    colorCompensation: modelDefaults.colorCompensation,
+    height: modelDefaults.height,
+    loras: settings.loras.map((lora) =>
+      isLoraCompatibleWithModel(lora.model, model) ? lora : { ...lora, isEnabled: false }
+    ),
+    modelKey: model.key,
+    scheduler: modelDefaults.scheduler,
+    steps: modelDefaults.steps,
+    vaePrecision: modelDefaults.vaePrecision,
+    width: modelDefaults.width,
+  };
+};
+
+export type GenerateComponentValueKey =
+  | 't5EncoderModel'
+  | 'clipEmbedModel'
+  | 'clipLEmbedModel'
+  | 'clipGEmbedModel'
+  | 'qwen3EncoderModel'
+  | 'qwenVLEncoderModel'
+  | 'componentSourceModel'
+  | 'vae';
+
+export interface ComponentPolicyContext {
+  model: GenerateModelConfig;
+  settings: GenerateSettings;
+  selectedComponents: Pick<GenerateSettings, GenerateComponentValueKey>;
+}
+
+export interface ComponentSlotPolicy {
+  key: GenerateComponentValueKey;
+  label: string;
+  modelTypes: readonly ModelTaxonomyType[];
+  valueKind: 'component' | 'vae' | 'main';
+  helpText?: string;
+  placeholder?: string;
+  defaultOpen?: boolean;
+  filter?: (candidate: ModelConfig, ctx: ComponentPolicyContext) => boolean;
+  required?: (ctx: ComponentPolicyContext) => boolean;
+  missingMessage?: string;
+}
+
+export interface ComponentSectionPolicy {
+  defaultOpen: boolean;
+  slots: readonly ComponentSlotPolicy[];
+  validate: (ctx: ComponentPolicyContext) => string[];
+}
+
+export interface GenerateSettingsCompatibilityResult {
+  settings: GenerateSettings;
+  clearedLabels: string[];
+}
+
+const TYPE_CLIP_EMBED: ModelTaxonomyType[] = ['clip_embed'];
+const TYPE_MAIN: ModelTaxonomyType[] = ['main'];
+const TYPE_QWEN3: ModelTaxonomyType[] = ['qwen3_encoder'];
+const TYPE_QWEN_VL: ModelTaxonomyType[] = ['qwen_vl_encoder'];
+const TYPE_T5: ModelTaxonomyType[] = ['t5_encoder'];
+const TYPE_VAE: ModelTaxonomyType[] = ['vae'];
+
+const wrapFilter = (filter: GenerateComponentFilter) => (candidate: ModelConfig) => filter(candidate);
+
+const slot = (policy: ComponentSlotPolicy): ComponentSlotPolicy => policy;
+
+const componentSourceSlot = (
+  filter: (candidate: ModelConfig, ctx: ComponentPolicyContext) => boolean,
+  helpText: string
+): ComponentSlotPolicy =>
+  slot({
+    key: 'componentSourceModel',
+    label: 'Component source',
+    modelTypes: TYPE_MAIN,
+    valueKind: 'main',
+    helpText,
+    filter,
+  });
+
+const t5EncoderSlot = (helpText: string): ComponentSlotPolicy =>
+  slot({
+    key: 't5EncoderModel',
+    label: 'T5 Encoder',
+    modelTypes: TYPE_T5,
+    valueKind: 'component',
+    helpText,
+    filter: (candidate) => candidate.type === 't5_encoder',
+  });
+
+const clipEmbedSlot = (helpText: string): ComponentSlotPolicy =>
+  slot({
+    key: 'clipEmbedModel',
+    label: 'CLIP Embed',
+    modelTypes: TYPE_CLIP_EMBED,
+    valueKind: 'component',
+    helpText,
+    filter: (candidate) => candidate.type === 'clip_embed',
+  });
+
+const qwenVlEncoderSlot = (helpText: string): ComponentSlotPolicy =>
+  slot({
+    key: 'qwenVLEncoderModel',
+    label: 'Qwen VL Encoder',
+    modelTypes: TYPE_QWEN_VL,
+    valueKind: 'component',
+    helpText,
+    filter: (candidate) => candidate.type === 'qwen_vl_encoder',
+  });
+
+const qwen3EncoderSlot = (helpText: string, filter?: GenerateComponentFilter): ComponentSlotPolicy =>
+  slot({
+    key: 'qwen3EncoderModel',
+    label: 'Qwen3 Encoder',
+    modelTypes: TYPE_QWEN3,
+    valueKind: 'component',
+    helpText,
+    filter: filter
+      ? (candidate) => candidate.type === 'qwen3_encoder' && filter(candidate)
+      : (candidate) => candidate.type === 'qwen3_encoder',
+  });
+
+const clipVariantSlot = (
+  key: 'clipLEmbedModel' | 'clipGEmbedModel',
+  label: string,
+  variant: string,
+  helpText: string
+) =>
+  slot({
+    key,
+    label,
+    modelTypes: TYPE_CLIP_EMBED,
+    valueKind: 'component',
+    helpText,
+    filter: wrapFilter(isClipVariant(variant)),
+  });
+
+const vaeSlot = (helpText: string, filter: GenerateComponentFilter): ComponentSlotPolicy =>
+  slot({ key: 'vae', label: 'VAE', modelTypes: TYPE_VAE, valueKind: 'vae', helpText, filter: wrapFilter(filter) });
+
+const hasCompatibleComponentSource = (ctx: ComponentPolicyContext): boolean =>
+  ctx.model.type !== 'external_image_generator' &&
+  Boolean(getCompatibleDiffusersComponentSource(ctx.model, ctx.settings.componentSourceModel));
+
+type ComponentSourceCandidate = {
+  base: string;
+  key: string;
+  name: string;
+  type: string;
+  format?: string;
+  variant?: unknown;
+};
+
+const isFlux2DiffusersSource = (source: ComponentSourceCandidate | null | undefined): source is MainModelConfig =>
+  Boolean(source && source.type === 'main' && source.base === 'flux2' && source.format === 'diffusers');
+
+const hasFlux2DiffusersVaeSource = (ctx: ComponentPolicyContext): boolean =>
+  ctx.model.type !== 'external_image_generator' &&
+  (ctx.model.format === 'diffusers' || isFlux2DiffusersSource(ctx.settings.componentSourceModel));
+
+const hasFlux2DiffusersQwen3Source = (ctx: ComponentPolicyContext): boolean =>
+  ctx.model.type !== 'external_image_generator' &&
+  (ctx.model.format === 'diffusers' ||
+    Boolean(
+      ctx.settings.componentSourceModel && isFlux2DiffusersSourceForModel(ctx.model)(ctx.settings.componentSourceModel)
+    ));
+
+export const getFlux2DiffusersComponentSource = (
+  model: MainModelConfig,
+  settings: GenerateSettings
+): MainModelConfig | undefined => {
+  const source = settings.componentSourceModel;
+
+  if (!isFlux2DiffusersSource(source)) {
+    return undefined;
+  }
+
+  if (settings.qwen3EncoderModel) {
+    return source;
+  }
+
+  return isFlux2DiffusersSourceForModel(model)(source) ? source : undefined;
+};
+
+export const getAutoFlux2ComponentSourceModel = (
+  model: GenerateModelConfig | undefined,
+  settings: Pick<GenerateSettings, 'qwen3EncoderModel' | 'vae'>,
+  models: readonly ComponentSourceCandidate[]
+): MainModelConfig | null | undefined => {
+  if (!model || model.type === 'external_image_generator' || model.base !== 'flux2') {
+    return undefined;
+  }
+
+  if (model.format === 'diffusers' || (settings.qwen3EncoderModel && settings.vae)) {
+    return null;
+  }
+
+  const diffusersModels = models.filter(isFlux2DiffusersSource);
+  const variantMatch = diffusersModels.find(isFlux2DiffusersSourceForModel(model));
+
+  if (!settings.qwen3EncoderModel && settings.vae) {
+    return variantMatch ?? null;
+  }
+
+  return variantMatch ?? diffusersModels[0] ?? null;
+};
+
+// Split/quantized families can satisfy required encoder/VAE slots from a bundled Diffusers source.
+const isBundledOrDiffusersSourceSatisfied = (ctx: ComponentPolicyContext): boolean =>
+  ctx.model.type !== 'external_image_generator' &&
+  (ctx.model.format === 'diffusers' || hasCompatibleComponentSource(ctx));
+
+// Slot validation is shared by invocation readiness and graph preflight so picker requirements cannot drift.
+const validateSlots = (policy: Pick<ComponentSectionPolicy, 'slots'>, ctx: ComponentPolicyContext): string[] =>
+  policy.slots.flatMap((slotPolicy) => {
+    if (!slotPolicy.required?.(ctx)) {
+      return [];
+    }
+
+    const value = ctx.selectedComponents[slotPolicy.key];
+    const isValid = value && (!slotPolicy.filter || slotPolicy.filter(value as ModelConfig, ctx));
+
+    return isValid ? [] : [slotPolicy.missingMessage ?? `Generate needs a ${slotPolicy.label} for this model.`];
+  });
+
+const createPolicy = (defaultOpen: boolean, slots: readonly ComponentSlotPolicy[]): ComponentSectionPolicy => ({
+  defaultOpen,
+  slots,
+  validate: (ctx) => validateSlots({ slots }, ctx),
+});
+
+const EMPTY_COMPONENT_POLICY: ComponentSectionPolicy = createPolicy(false, []);
+
+export const getComponentSectionPolicy = (
+  model: GenerateModelConfig | undefined,
+  _settings: GenerateSettings
+): ComponentSectionPolicy => {
+  if (!model || model.type === 'external_image_generator') {
+    return EMPTY_COMPONENT_POLICY;
+  }
+
+  switch (model.base) {
+    case 'flux':
+      return {
+        ...createPolicy(false, [
+          {
+            ...t5EncoderSlot('Required for FLUX.1 models.'),
+            required: () => true,
+            missingMessage: 'Generate needs a T5 Encoder for FLUX models.',
+          },
+          {
+            ...clipEmbedSlot('Required for FLUX.1 models.'),
+            required: () => true,
+            missingMessage: 'Generate needs a CLIP Embed model for FLUX models.',
+          },
+          {
+            ...vaeSlot('Required for FLUX.1 models.', isVaeForBases(['flux'])),
+            required: () => true,
+            missingMessage: 'Generate needs a VAE for FLUX models.',
+          },
+        ]),
+        validate: (ctx) => [
+          ...(ctx.model.type !== 'external_image_generator' && ctx.model.variant === 'dev_fill'
+            ? ['FLUX Fill models do not support text-to-image generation.']
+            : []),
+          ...validateSlots(getComponentSectionPolicy(ctx.model, ctx.settings), ctx),
+        ],
+      };
+    case 'flux2':
+      return createPolicy(model.format !== 'diffusers', [
+        {
+          ...qwen3EncoderSlot('Optional override; otherwise a compatible installed FLUX.2 Diffusers model is used.'),
+          filter: (candidate, ctx) =>
+            ctx.model.type !== 'external_image_generator' && isFlux2Qwen3EncoderForModel(ctx.model)(candidate),
+          required: (ctx) => !hasFlux2DiffusersQwen3Source(ctx),
+          missingMessage: 'Generate needs a Qwen3 Encoder for non-Diffusers FLUX.2 models.',
+        },
+        {
+          ...vaeSlot(
+            'Optional override; otherwise an installed FLUX.2 Diffusers model is used.',
+            isVaeForBases(['flux2'])
+          ),
+          required: (ctx) => !hasFlux2DiffusersVaeSource(ctx),
+          missingMessage: 'Generate needs a VAE for non-Diffusers FLUX.2 models.',
+        },
+      ]);
+    case 'sd-3':
+      return createPolicy(false, [
+        t5EncoderSlot('Optional override; the main model is used when omitted.'),
+        clipVariantSlot('clipLEmbedModel', 'CLIP L', 'large', 'Optional CLIP-L override.'),
+        clipVariantSlot('clipGEmbedModel', 'CLIP G', 'gigantic', 'Optional CLIP-G override.'),
+        vaeSlot('Optional VAE override.', isVaeForBases(['sd-3'])),
+      ]);
+    case 'qwen-image':
+      return createPolicy(model.format !== 'diffusers', [
+        componentSourceSlot(
+          (candidate) => isDiffusersMainForBase('qwen-image')(candidate),
+          'For non-Diffusers Qwen Image models, select this or provide separate VAE and Qwen VL models.'
+        ),
+        {
+          ...qwenVlEncoderSlot('Optional override, or required with a non-Diffusers model and no component source.'),
+          required: (ctx) => !isBundledOrDiffusersSourceSatisfied(ctx),
+          missingMessage: 'Generate needs a Qwen VL Encoder for non-Diffusers Qwen Image models.',
+        },
+        {
+          ...vaeSlot(
+            'Optional override, or required with a non-Diffusers model and no component source.',
+            isVaeForBases(['qwen-image'])
+          ),
+          required: (ctx) => !isBundledOrDiffusersSourceSatisfied(ctx),
+          missingMessage: 'Generate needs a VAE for non-Diffusers Qwen Image models.',
+        },
+      ]);
+    case 'z-image':
+      return createPolicy(model.format !== 'diffusers', [
+        componentSourceSlot(
+          (candidate) => isDiffusersMainForBase('z-image')(candidate),
+          'Select a Diffusers Z-Image model to provide VAE and Qwen3 components.'
+        ),
+        {
+          ...qwen3EncoderSlot('Required unless a Diffusers component source is available.', isNonAnimaQwen3Encoder),
+          required: (ctx) => !isBundledOrDiffusersSourceSatisfied(ctx),
+          missingMessage: 'Generate needs a Qwen3 Encoder for Z-Image models.',
+        },
+        {
+          ...vaeSlot('Required unless a Diffusers component source is available.', isVaeForBases(['flux'])),
+          required: (ctx) => !isBundledOrDiffusersSourceSatisfied(ctx),
+          missingMessage: 'Generate needs a VAE for Z-Image models.',
+        },
+      ]);
+    case 'anima':
+      return createPolicy(true, [
+        {
+          ...qwen3EncoderSlot('Required for Anima models.', isAnimaQwen3Encoder),
+          required: () => true,
+          missingMessage: 'Generate needs a Qwen3 Encoder for Anima models.',
+        },
+        {
+          ...vaeSlot('Required for Anima models. Qwen Image and FLUX VAEs are supported.', isAnimaVae),
+          required: () => true,
+          missingMessage: 'Generate needs a VAE for Anima models.',
+        },
+      ]);
+    default:
+      return EMPTY_COMPONENT_POLICY;
+  }
+};
+
+const getComponentPolicyContext = (model: GenerateModelConfig, settings: GenerateSettings): ComponentPolicyContext => ({
+  model,
+  settings,
+  selectedComponents: {
+    clipEmbedModel: settings.clipEmbedModel,
+    clipGEmbedModel: settings.clipGEmbedModel,
+    clipLEmbedModel: settings.clipLEmbedModel,
+    componentSourceModel: settings.componentSourceModel,
+    qwen3EncoderModel: settings.qwen3EncoderModel,
+    qwenVLEncoderModel: settings.qwenVLEncoderModel,
+    t5EncoderModel: settings.t5EncoderModel,
+    vae: settings.vae,
+  },
+});
+
+const COMPONENT_SETTING_LABELS: Record<GenerateComponentValueKey, string> = {
+  clipEmbedModel: 'CLIP Embed',
+  clipGEmbedModel: 'CLIP G',
+  clipLEmbedModel: 'CLIP L',
+  qwen3EncoderModel: 'Qwen3 Encoder',
+  qwenVLEncoderModel: 'Qwen VL Encoder',
+  t5EncoderModel: 'T5 Encoder',
+  vae: 'VAE',
+  componentSourceModel: 'Component source',
+};
+
+const addClearedLabel = (labels: string[], label: string) => {
+  if (!labels.includes(label)) {
+    labels.push(label);
+  }
+};
+
+const isSelectedComponentCompatible = (
+  slotPolicy: ComponentSlotPolicy | undefined,
+  model: GenerateModelConfig,
+  settings: GenerateSettings,
+  key: GenerateComponentValueKey
+): boolean => {
+  const value = settings[key];
+
+  if (!value) {
+    return true;
+  }
+
+  if (key === 'componentSourceModel' && model.type !== 'external_image_generator' && model.base === 'flux2') {
+    return Boolean(getFlux2DiffusersComponentSource(model, settings));
+  }
+
+  if (!slotPolicy) {
+    return false;
+  }
+
+  return !slotPolicy.filter || slotPolicy.filter(value as ModelConfig, getComponentPolicyContext(model, settings));
+};
+
+type ReferenceModelCandidate = { base: string; key: string; name: string; type: string };
+
+const isFluxKontextModel = (model: GenerateModelConfig | undefined): model is MainModelConfig =>
+  Boolean(
+    model &&
+    model.type !== 'external_image_generator' &&
+    model.base === 'flux' &&
+    model.name.toLowerCase().includes('kontext')
+  );
+
+/**
+ * Whether the model can consume reference images at all. Kept strict so the UI
+ * only offers reference images where `getGenerationValidationReasons` would
+ * accept them (e.g. Qwen Image requires the `edit` variant).
+ */
+export const isReferenceImageSupported = (model: GenerateModelConfig | undefined): boolean => {
+  if (!model) {
+    return false;
+  }
+
+  if (model.type === 'external_image_generator') {
+    return model.capabilities?.supports_reference_images === true;
+  }
+
+  if (model.base === 'qwen-image') {
+    return model.variant === 'edit';
+  }
+
+  return ['flux', 'flux2', 'sd-1', 'sdxl'].includes(model.base);
+};
+
+export const getMaxReferenceImages = (model: GenerateModelConfig | undefined): number => {
+  if (!model || !isReferenceImageSupported(model)) {
+    return 0;
+  }
+
+  if (model.type === 'external_image_generator' && typeof model.capabilities?.max_reference_images === 'number') {
+    return Math.max(0, model.capabilities.max_reference_images);
+  }
+
+  return DEFAULT_REFERENCE_IMAGE_LIMIT;
+};
+
+export const createReferenceImageId = (): string =>
+  `reference_image_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+
+export const getDefaultReferenceImageConfig = (
+  model: GenerateModelConfig | undefined,
+  models: readonly ReferenceModelCandidate[],
+  image: GenerateReferenceImageAsset | null = null
+): GenerateReferenceImageConfig => {
+  const modelBase: string | undefined = model?.base;
+
+  if (model?.type === 'external_image_generator') {
+    return { image, type: 'external_reference_image' };
+  }
+
+  if (modelBase === 'flux2') {
+    return { image, type: 'flux2_reference_image' };
+  }
+
+  if (modelBase === 'qwen-image') {
+    return { image, type: 'qwen_image_reference_image' };
+  }
+
+  if (isFluxKontextModel(model)) {
+    return { image, model, type: 'flux_kontext_reference_image' };
+  }
+
+  const adapterModel =
+    models.find((candidate) => candidate.type === 'ip_adapter' && candidate.base === modelBase) ?? null;
+
+  return {
+    beginEndStepPct: [0, 1],
+    clipVisionModel: modelBase === 'flux' ? 'ViT-L' : 'ViT-H',
+    image,
+    method: 'full',
+    model: adapterModel,
+    type: 'ip_adapter',
+    weight: 1,
+  };
+};
+
+const getReferenceImageConfigSupported = (
+  model: GenerateModelConfig,
+  referenceImage: GenerateReferenceImage
+): boolean => {
+  switch (referenceImage.config.type) {
+    case 'external_reference_image':
+      return model.type === 'external_image_generator' && model.capabilities?.supports_reference_images === true;
+    case 'flux2_reference_image':
+      return model.type !== 'external_image_generator' && model.base === 'flux2';
+    case 'qwen_image_reference_image':
+      return model.type !== 'external_image_generator' && model.base === 'qwen-image' && model.variant === 'edit';
+    case 'flux_kontext_reference_image':
+      return isFluxKontextModel(model);
+    case 'flux_redux':
+      return model.type !== 'external_image_generator' && model.base === 'flux';
+    case 'ip_adapter':
+      return model.type !== 'external_image_generator' && ['sd-1', 'sdxl', 'flux'].includes(model.base);
+  }
+};
+
+export const isReferenceImageCompatibleWithModel = (
+  model: GenerateModelConfig,
+  referenceImage: GenerateReferenceImage
+): boolean => {
+  if (!getReferenceImageConfigSupported(model, referenceImage)) {
+    return false;
+  }
+
+  const config = referenceImage.config;
+
+  if ((config.type === 'ip_adapter' || config.type === 'flux_redux') && config.model) {
+    return config.model.base === model.base;
+  }
+
+  if (config.type === 'flux_kontext_reference_image' && config.model) {
+    return config.model.key === model.key;
+  }
+
+  return true;
+};
+
+/**
+ * Reference images carried over to `model`: dropped entirely when the model
+ * does not support reference images, and re-targeted to a default config for
+ * the new model (keeping the image and enabled state) when incompatible.
+ * Returns the input array untouched when nothing changes.
+ */
+export const getCompatibleReferenceImages = (
+  referenceImages: GenerateReferenceImage[],
+  model: GenerateModelConfig,
+  models: readonly ReferenceModelCandidate[]
+): GenerateReferenceImage[] => {
+  if (referenceImages.length === 0) {
+    return referenceImages;
+  }
+
+  if (!isReferenceImageSupported(model)) {
+    return [];
+  }
+
+  let didChange = false;
+  const next = referenceImages.map((referenceImage) => {
+    if (isReferenceImageCompatibleWithModel(model, referenceImage)) {
+      return referenceImage;
+    }
+
+    didChange = true;
+    return { ...referenceImage, config: getDefaultReferenceImageConfig(model, models, referenceImage.config.image) };
+  });
+
+  return didChange ? next : referenceImages;
+};
+
+export const getSettingsWithCompatibleModelSelections = (
+  settings: GenerateSettings,
+  model: GenerateModelConfig,
+  models: readonly ReferenceModelCandidate[]
+): GenerateSettingsCompatibilityResult => {
+  const nextSettings: GenerateSettings = { ...settings, modelKey: model.key };
+  const clearedLabels: string[] = [];
+  const compatibleLoras = settings.loras.filter((lora) => isLoraCompatibleWithModel(lora.model, model));
+  const dimensions = getGenerationDimensions(model);
+  const width = clampDimension(nextSettings.width, dimensions.grid);
+  const height = clampDimension(nextSettings.height, dimensions.grid);
+
+  if (width !== nextSettings.width || height !== nextSettings.height) {
+    nextSettings.width = width;
+    nextSettings.height = height;
+    nextSettings.aspectRatioId = deriveAspectRatioId(width, height);
+    nextSettings.aspectRatioValue = height > 0 ? width / height : 1;
+    addClearedLabel(clearedLabels, 'Dimensions');
+  }
+
+  if (compatibleLoras.length !== settings.loras.length) {
+    nextSettings.loras = compatibleLoras;
+    addClearedLabel(clearedLabels, 'LoRAs');
+  }
+
+  const compatibleReferenceImages = getCompatibleReferenceImages(settings.referenceImages, model, models);
+
+  if (compatibleReferenceImages !== settings.referenceImages) {
+    nextSettings.referenceImages = compatibleReferenceImages;
+    addClearedLabel(clearedLabels, 'Reference Images');
+  }
+
+  const policy = getComponentSectionPolicy(model, nextSettings);
+  const slotsByKey = new Map(policy.slots.map((slotPolicy) => [slotPolicy.key, slotPolicy]));
+  const uiPolicy = getGenerationUiPolicy(model, nextSettings);
+
+  for (const key of Object.keys(COMPONENT_SETTING_LABELS) as GenerateComponentValueKey[]) {
+    if (!nextSettings[key]) {
+      continue;
+    }
+
+    if (key === 'vae' && !slotsByKey.has(key) && uiPolicy.sdVaeVisible && nextSettings.vae?.base === model.base) {
+      continue;
+    }
+
+    if (!isSelectedComponentCompatible(slotsByKey.get(key), model, nextSettings, key)) {
+      nextSettings[key] = null;
+      addClearedLabel(clearedLabels, COMPONENT_SETTING_LABELS[key]);
+    }
+  }
+
+  if (!uiPolicy.clipSkipMax && nextSettings.clipSkip !== 0) {
+    nextSettings.clipSkip = 0;
+    addClearedLabel(clearedLabels, 'CLIP skip');
+  } else if (uiPolicy.clipSkipMax && nextSettings.clipSkip > uiPolicy.clipSkipMax) {
+    nextSettings.clipSkip = uiPolicy.clipSkipMax;
+    addClearedLabel(clearedLabels, 'CLIP skip');
+  }
+
+  if (!uiPolicy.cfgRescaleVisible && nextSettings.cfgRescaleMultiplier !== 0) {
+    nextSettings.cfgRescaleMultiplier = 0;
+    addClearedLabel(clearedLabels, 'CFG rescale');
+  }
+
+  if (!uiPolicy.colorCompensationVisible && nextSettings.colorCompensation) {
+    nextSettings.colorCompensation = false;
+    addClearedLabel(clearedLabels, 'Color compensation');
+  }
+
+  if (!uiPolicy.seamlessVisible && (nextSettings.seamlessXAxis || nextSettings.seamlessYAxis)) {
+    nextSettings.seamlessXAxis = false;
+    nextSettings.seamlessYAxis = false;
+    addClearedLabel(clearedLabels, 'Seamless tiling');
+  }
+
+  if (!uiPolicy.vaePrecisionVisible) {
+    const defaultVaePrecision = getGenerationDefaults(model).vaePrecision;
+
+    if (nextSettings.vaePrecision !== defaultVaePrecision) {
+      nextSettings.vaePrecision = defaultVaePrecision;
+      addClearedLabel(clearedLabels, 'VAE precision');
+    }
+  }
+
+  return { settings: nextSettings, clearedLabels };
+};
+
+const hasModelKey = (models: readonly ModelConfig[], key: string, type?: string): boolean =>
+  models.some((model) => model.key === key && (!type || model.type === type));
+
+export const getGenerationModelAvailabilityReasons = (
+  model: GenerateModelConfig,
+  settings: GenerateSettings,
+  models: readonly ModelConfig[]
+): string[] => {
+  const reasons: string[] = [];
+
+  if (!hasModelKey(models, model.key, model.type)) {
+    reasons.push(`Selected model "${model.name}" is no longer installed.`);
+  }
+
+  for (const key of Object.keys(COMPONENT_SETTING_LABELS) as GenerateComponentValueKey[]) {
+    const value = settings[key];
+
+    if (value && !hasModelKey(models, value.key, value.type)) {
+      reasons.push(`${COMPONENT_SETTING_LABELS[key]} "${value.name}" is no longer installed.`);
+    }
+  }
+
+  for (const lora of settings.loras) {
+    if (!hasModelKey(models, lora.model.key, 'lora')) {
+      reasons.push(`LoRA "${lora.model.name}" is no longer installed.`);
+    }
+  }
+
+  for (const referenceImage of settings.referenceImages) {
+    if (!referenceImage.isEnabled) {
+      continue;
+    }
+
+    const config = referenceImage.config;
+
+    if ('model' in config && config.model && !hasModelKey(models, config.model.key, config.model.type)) {
+      reasons.push(`Reference Image model "${config.model.name}" is no longer installed.`);
+    }
+  }
+
+  return reasons;
+};
+
+const getDimensionValidationReasons = (model: GenerateModelConfig, settings: GenerateSettings): string[] => {
+  const reasons: string[] = [];
+  const dimensions = getGenerationDimensions(model);
+
+  if (!Number.isFinite(settings.width) || settings.width < dimensions.min || settings.width > dimensions.max) {
+    reasons.push(`Generate width must be between ${dimensions.min} and ${dimensions.max}.`);
+  } else if (settings.width % dimensions.grid !== 0) {
+    reasons.push(`Generate width must be a multiple of ${dimensions.grid}.`);
+  }
+
+  if (!Number.isFinite(settings.height) || settings.height < dimensions.min || settings.height > dimensions.max) {
+    reasons.push(`Generate height must be between ${dimensions.min} and ${dimensions.max}.`);
+  } else if (settings.height % dimensions.grid !== 0) {
+    reasons.push(`Generate height must be a multiple of ${dimensions.grid}.`);
+  }
+
+  return reasons;
+};
+
+const getReferenceImageValidationReasons = (model: GenerateModelConfig, settings: GenerateSettings): string[] => {
+  const reasons: string[] = [];
+  const enabled = settings.referenceImages.filter((referenceImage) => referenceImage.isEnabled);
+  const maxReferenceImages =
+    model.type === 'external_image_generator' && typeof model.capabilities?.max_reference_images === 'number'
+      ? model.capabilities.max_reference_images
+      : DEFAULT_REFERENCE_IMAGE_LIMIT;
+
+  if (enabled.length > maxReferenceImages) {
+    reasons.push(`Generate supports at most ${maxReferenceImages} reference images for ${model.name}.`);
+  }
+
+  enabled.forEach((referenceImage, index) => {
+    const prefix = `Reference Image #${index + 1}`;
+
+    if (!getReferenceImageConfigSupported(model, referenceImage)) {
+      reasons.push(`${prefix} is not supported by ${model.base} model.`);
+      return;
+    }
+
+    if (!referenceImage.config.image) {
+      reasons.push(`${prefix} needs an image.`);
+    }
+
+    if (referenceImage.config.type === 'ip_adapter') {
+      if (!referenceImage.config.model || referenceImage.config.model.base !== model.base) {
+        reasons.push(`${prefix} needs a compatible IP Adapter model.`);
+      }
+    }
+
+    if (referenceImage.config.type === 'flux_redux') {
+      if (!referenceImage.config.model || referenceImage.config.model.base !== model.base) {
+        reasons.push(`${prefix} needs a compatible FLUX Redux model.`);
+      }
+    }
+
+    if (referenceImage.config.type === 'flux_kontext_reference_image') {
+      if (!referenceImage.config.model || referenceImage.config.model.key !== model.key) {
+        reasons.push(`${prefix} needs the selected FLUX Kontext model.`);
+      }
+    }
+  });
+
+  return reasons;
+};
+
+export const getGenerationValidationReasons = (model: GenerateModelConfig, settings: GenerateSettings): string[] => {
+  if (!isSupportedGenerateModel(model)) {
+    return ['Generate needs a supported model before it can be invoked.'];
+  }
+
+  const reasons = [
+    ...getDimensionValidationReasons(model, settings),
+    ...getReferenceImageValidationReasons(model, settings),
+  ];
+
+  if (model.type === 'external_image_generator') {
+    if (model.capabilities?.modes && !model.capabilities.modes.includes('txt2img')) {
+      reasons.push(`${model.name} does not support text-to-image generation.`);
+    }
+
+    if (!getExternalProviderNodeType(model.provider_id)) {
+      reasons.push(`No invocation node registered for external provider '${model.provider_id ?? ''}'.`);
+    }
+
+    return reasons;
+  }
+
+  const componentPolicy = getComponentSectionPolicy(model, settings);
+  reasons.push(...componentPolicy.validate(getComponentPolicyContext(model, settings)));
+
+  return reasons;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/batch.ts b/invokeai/frontend/webv2/src/workbench/generation/batch.ts
new file mode 100644
index 00000000000..c692662b790
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/batch.ts
@@ -0,0 +1,6 @@
+export const MIN_BATCH_COUNT = 1;
+
+export const sanitizeBatchCount = (batchCount: unknown): number =>
+  typeof batchCount === 'number' && Number.isFinite(batchCount)
+    ? Math.max(MIN_BATCH_COUNT, Math.round(batchCount))
+    : MIN_BATCH_COUNT;
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/addControlLayers.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/addControlLayers.test.ts
new file mode 100644
index 00000000000..5eb2df00444
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/addControlLayers.test.ts
@@ -0,0 +1,529 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  AddControlLayersOptions,
+  ControlAdapterKind,
+  ControlLayerGraphInput,
+  ControlModelIdentifier,
+} from './addControlLayers';
+
+import {
+  addControlLayers,
+  CONTROL_DENOISE_NODE_ID,
+  getControlLayerRejectionReason,
+  isControlKindSupportedForBase,
+} from './addControlLayers';
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+interface TestGraph {
+  id: string;
+  nodes: Record<string, { id: string; type: string; [key: string]: unknown }>;
+  edges: {
+    source: { node_id: string; field: string };
+    destination: { node_id: string; field: string };
+  }[];
+}
+
+/** A minimal built base graph containing only the required denoise node. */
+const baseGraph = (): TestGraph => ({
+  id: 'g',
+  nodes: {
+    denoise_latents: { id: 'denoise_latents', type: 'denoise_latents' },
+  },
+  edges: [],
+});
+
+const model = (base: string, type = 'controlnet'): ControlModelIdentifier => ({
+  key: `model-${base}`,
+  name: `Model ${base}`,
+  base,
+  type,
+});
+
+const layer = (overrides: Partial<ControlLayerGraphInput> = {}): ControlLayerGraphInput => ({
+  id: 'layer1',
+  imageName: 'image1.png',
+  kind: 'controlnet',
+  model: model('sd-1'),
+  weight: 0.75,
+  beginEndStepPct: [0.1, 0.8],
+  controlMode: 'balanced',
+  ...overrides,
+});
+
+// Convenience to run addControlLayers against a fresh graph.
+const run = (options: AddControlLayersOptions) => {
+  const graph = baseGraph();
+  // Cast: TestGraph is structurally the BackendGraphContract shape addControlLayers needs.
+  addControlLayers(graph as never, options);
+  return graph;
+};
+
+const edgesTo = (graph: TestGraph, nodeId: string, field: string) =>
+  graph.edges.filter((e) => e.destination.node_id === nodeId && e.destination.field === field);
+
+// ---------------------------------------------------------------------------
+// 1. isControlKindSupportedForBase full matrix
+// ---------------------------------------------------------------------------
+
+describe('isControlKindSupportedForBase', () => {
+  it('controlnet is supported on sd-1, sdxl, flux only', () => {
+    expect(isControlKindSupportedForBase('sd-1', 'controlnet')).toBe(true);
+    expect(isControlKindSupportedForBase('sdxl', 'controlnet')).toBe(true);
+    expect(isControlKindSupportedForBase('flux', 'controlnet')).toBe(true);
+    expect(isControlKindSupportedForBase('sd-2', 'controlnet')).toBe(false);
+    expect(isControlKindSupportedForBase('sd-3', 'controlnet')).toBe(false);
+  });
+
+  it('t2i_adapter is supported on sd-1 and sdxl only (not flux)', () => {
+    expect(isControlKindSupportedForBase('sd-1', 't2i_adapter')).toBe(true);
+    expect(isControlKindSupportedForBase('sdxl', 't2i_adapter')).toBe(true);
+    expect(isControlKindSupportedForBase('flux', 't2i_adapter')).toBe(false);
+    expect(isControlKindSupportedForBase('sd-2', 't2i_adapter')).toBe(false);
+  });
+
+  it('control_lora is supported on flux only', () => {
+    expect(isControlKindSupportedForBase('flux', 'control_lora')).toBe(true);
+    expect(isControlKindSupportedForBase('sd-1', 'control_lora')).toBe(false);
+    expect(isControlKindSupportedForBase('sdxl', 'control_lora')).toBe(false);
+    expect(isControlKindSupportedForBase('sd-2', 'control_lora')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CONTROL_DENOISE_NODE_ID sanity
+// ---------------------------------------------------------------------------
+
+describe('CONTROL_DENOISE_NODE_ID', () => {
+  it('is the deterministic denoise node id', () => {
+    expect(CONTROL_DENOISE_NODE_ID).toBe('denoise_latents');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. controlnet on sd-1
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — controlnet on sd-1', () => {
+  it('creates a controlnet node with exact fields and wires the collector to denoise.control', () => {
+    const m = model('sd-1');
+    const graph = run({
+      base: 'sd-1',
+      layers: [
+        layer({
+          id: 'L1',
+          imageName: 'ctrl.png',
+          model: m,
+          weight: 0.6,
+          beginEndStepPct: [0.2, 0.9],
+          controlMode: null,
+        }),
+      ],
+    });
+
+    const node = graph.nodes['control_net_L1'];
+    expect(node).toBeDefined();
+    expect(node.type).toBe('controlnet');
+    expect(node.begin_step_percent).toBe(0.2);
+    expect(node.end_step_percent).toBe(0.9);
+    expect(node.control_model).toBe(m);
+    expect(node.control_weight).toBe(0.6);
+    expect(node.resize_mode).toBe('just_resize');
+    // controlMode null → defaults to 'balanced'
+    expect(node.control_mode).toBe('balanced');
+    expect(node.image).toEqual({ image_name: 'ctrl.png' });
+
+    // Collector created and wired.
+    expect(graph.nodes['control_net_collector']).toBeDefined();
+    expect(graph.nodes['control_net_collector'].type).toBe('collect');
+
+    // node.control → collector.item
+    expect(
+      graph.edges.some(
+        (e) =>
+          e.source.node_id === 'control_net_L1' &&
+          e.source.field === 'control' &&
+          e.destination.node_id === 'control_net_collector' &&
+          e.destination.field === 'item'
+      )
+    ).toBe(true);
+
+    // collector.collection → denoise.control
+    expect(
+      graph.edges.some(
+        (e) =>
+          e.source.node_id === 'control_net_collector' &&
+          e.source.field === 'collection' &&
+          e.destination.node_id === 'denoise_latents' &&
+          e.destination.field === 'control'
+      )
+    ).toBe(true);
+  });
+
+  it('carries an explicit controlMode when provided', () => {
+    const graph = run({
+      base: 'sd-1',
+      layers: [layer({ id: 'L1', controlMode: 'more_control' })],
+    });
+    expect(graph.nodes['control_net_L1'].control_mode).toBe('more_control');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. controlnet on flux
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — controlnet on flux', () => {
+  it('uses flux_controlnet type and omits control_mode entirely', () => {
+    const m = model('flux');
+    const graph = run({
+      base: 'flux',
+      layers: [layer({ id: 'F1', kind: 'controlnet', model: m, controlMode: 'more_prompt' })],
+    });
+
+    const node = graph.nodes['control_net_F1'];
+    expect(node).toBeDefined();
+    expect(node.type).toBe('flux_controlnet');
+    expect(node.resize_mode).toBe('just_resize');
+    expect(node.control_model).toBe(m);
+    // No control_mode key at all, even though controlMode was set.
+    expect(node).not.toHaveProperty('control_mode');
+
+    // Collector wired same as SD family.
+    expect(
+      graph.edges.some(
+        (e) =>
+          e.source.node_id === 'control_net_collector' &&
+          e.source.field === 'collection' &&
+          e.destination.node_id === 'denoise_latents' &&
+          e.destination.field === 'control'
+      )
+    ).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. t2i_adapter on sdxl
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — t2i_adapter on sdxl', () => {
+  it('creates a t2i_adapter node with exact fields and wires collector to denoise.t2i_adapter', () => {
+    const m = model('sdxl', 't2i_adapter');
+    const graph = run({
+      base: 'sdxl',
+      layers: [
+        layer({
+          id: 'T1',
+          kind: 't2i_adapter',
+          imageName: 't2i.png',
+          model: m,
+          weight: 0.5,
+          beginEndStepPct: [0.05, 0.7],
+        }),
+      ],
+    });
+
+    const node = graph.nodes['t2i_adapter_T1'];
+    expect(node).toBeDefined();
+    expect(node.type).toBe('t2i_adapter');
+    expect(node.begin_step_percent).toBe(0.05);
+    expect(node.end_step_percent).toBe(0.7);
+    expect(node.resize_mode).toBe('just_resize');
+    expect(node.t2i_adapter_model).toBe(m);
+    expect(node.weight).toBe(0.5);
+    expect(node.image).toEqual({ image_name: 't2i.png' });
+    // t2i_adapter has no control_mode / control_model / control_weight
+    expect(node).not.toHaveProperty('control_mode');
+    expect(node).not.toHaveProperty('control_model');
+
+    expect(graph.nodes['t2i_adapter_collector']).toBeDefined();
+    expect(graph.nodes['t2i_adapter_collector'].type).toBe('collect');
+
+    // node.t2i_adapter → collector.item
+    expect(
+      graph.edges.some(
+        (e) =>
+          e.source.node_id === 't2i_adapter_T1' &&
+          e.source.field === 't2i_adapter' &&
+          e.destination.node_id === 't2i_adapter_collector' &&
+          e.destination.field === 'item'
+      )
+    ).toBe(true);
+
+    // collector.collection → denoise.t2i_adapter
+    expect(
+      graph.edges.some(
+        (e) =>
+          e.source.node_id === 't2i_adapter_collector' &&
+          e.source.field === 'collection' &&
+          e.destination.node_id === 'denoise_latents' &&
+          e.destination.field === 't2i_adapter'
+      )
+    ).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. control_lora on flux
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — control_lora on flux', () => {
+  it('creates a flux_control_lora_loader wired directly to denoise.control_lora with no collector', () => {
+    const m = model('flux', 'control_lora');
+    const graph = run({
+      base: 'flux',
+      layers: [layer({ id: 'CL1', kind: 'control_lora', imageName: 'lora.png', model: m, weight: 0.9 })],
+    });
+
+    const node = graph.nodes['control_lora_CL1'];
+    expect(node).toBeDefined();
+    expect(node.type).toBe('flux_control_lora_loader');
+    expect(node.lora).toBe(m);
+    expect(node.image).toEqual({ image_name: 'lora.png' });
+    expect(node.weight).toBe(0.9);
+
+    // Wired directly node.control_lora → denoise.control_lora
+    expect(
+      graph.edges.some(
+        (e) =>
+          e.source.node_id === 'control_lora_CL1' &&
+          e.source.field === 'control_lora' &&
+          e.destination.node_id === 'denoise_latents' &&
+          e.destination.field === 'control_lora'
+      )
+    ).toBe(true);
+
+    // No collector node of any kind created.
+    expect(graph.nodes['control_net_collector']).toBeUndefined();
+    expect(graph.nodes['t2i_adapter_collector']).toBeUndefined();
+    expect(Object.values(graph.nodes).some((n) => n.type === 'collect')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. control_lora limits: second skipped; dev_fill skips
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — control_lora limits', () => {
+  it('rejects a second control_lora with the shared reason code', () => {
+    expect(() =>
+      run({
+        base: 'flux',
+        layers: [
+          layer({ id: 'CL1', kind: 'control_lora', model: model('flux', 'control_lora') }),
+          layer({ id: 'CL2', kind: 'control_lora', model: model('flux', 'control_lora') }),
+        ],
+      })
+    ).toThrow(/control_lora_limit/);
+  });
+
+  it('rejects control_lora for a dev_fill main model variant', () => {
+    expect(() =>
+      run({
+        base: 'flux',
+        modelVariant: 'dev_fill',
+        layers: [layer({ id: 'CL1', kind: 'control_lora', model: model('flux', 'control_lora') })],
+      })
+    ).toThrow(/flux_fill_control_lora/);
+  });
+});
+
+describe('addControlLayers — Z-Image control', () => {
+  it('creates the exact backend node and connects it directly to Z-Image denoise', () => {
+    const m = model('z-image', 'controlnet');
+    const graph = run({
+      base: 'z-image',
+      layers: [
+        layer({
+          beginEndStepPct: [0.2, 0.9],
+          controlMode: null,
+          id: 'Z1',
+          imageName: 'z-control.png',
+          kind: 'z_image_control',
+          model: m,
+          weight: 0.7,
+        }),
+      ],
+    });
+
+    expect(graph.nodes.z_image_control_Z1).toEqual({
+      begin_step_percent: 0.2,
+      control_context_scale: 0.7,
+      control_model: m,
+      end_step_percent: 0.9,
+      id: 'z_image_control_Z1',
+      image: { image_name: 'z-control.png' },
+      is_intermediate: true,
+      type: 'z_image_control',
+      use_cache: true,
+    });
+    expect(graph.edges).toContainEqual({
+      destination: { field: 'control', node_id: 'denoise_latents' },
+      source: { field: 'control', node_id: 'z_image_control_Z1' },
+    });
+    expect(Object.values(graph.nodes).some((node) => node.type === 'collect')).toBe(false);
+  });
+
+  it('rejects a second Z-Image control because denoise accepts a single field', () => {
+    const m = model('z-image', 'controlnet');
+    expect(() =>
+      run({
+        base: 'z-image',
+        layers: [
+          layer({ id: 'Z1', kind: 'z_image_control', model: m }),
+          layer({ id: 'Z2', kind: 'z_image_control', model: m }),
+        ],
+      })
+    ).toThrow(/z_image_control_limit/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. Two controlnet layers → distinct nodes, one shared collector
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — per-layer separation', () => {
+  it('creates two distinct adapter nodes feeding one shared collector', () => {
+    const graph = run({
+      base: 'sd-1',
+      layers: [layer({ id: 'A', imageName: 'a.png' }), layer({ id: 'B', imageName: 'b.png' })],
+    });
+
+    expect(graph.nodes['control_net_A']).toBeDefined();
+    expect(graph.nodes['control_net_B']).toBeDefined();
+    expect(graph.nodes['control_net_A'].image).toEqual({ image_name: 'a.png' });
+    expect(graph.nodes['control_net_B'].image).toEqual({ image_name: 'b.png' });
+
+    // Exactly one collector.
+    const collectors = Object.values(graph.nodes).filter((n) => n.type === 'collect');
+    expect(collectors).toHaveLength(1);
+
+    // Two item edges into the shared collector.
+    const itemEdges = graph.edges.filter(
+      (e) => e.destination.node_id === 'control_net_collector' && e.destination.field === 'item'
+    );
+    expect(itemEdges).toHaveLength(2);
+    expect(itemEdges.map((e) => e.source.node_id).sort()).toEqual(['control_net_A', 'control_net_B']);
+
+    // Only one collection→denoise edge (collector wired once).
+    expect(edgesTo(graph, 'denoise_latents', 'control')).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 8. Unsupported kind for base is silently skipped
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — unsupported kind rejected', () => {
+  it('rejects a t2i_adapter layer on flux', () => {
+    expect(() =>
+      run({
+        base: 'flux',
+        layers: [layer({ id: 'X', kind: 't2i_adapter', model: model('flux', 't2i_adapter') })],
+      })
+    ).toThrow(/unsupported_adapter/);
+  });
+
+  it('rejects a mixed set containing an unsupported layer', () => {
+    expect(() =>
+      run({
+        base: 'flux',
+        layers: [
+          layer({ id: 'skip', kind: 't2i_adapter', model: model('flux', 't2i_adapter') }),
+          layer({ id: 'keep', kind: 'controlnet', model: model('flux') }),
+        ],
+      })
+    ).toThrow(/unsupported_adapter/);
+  });
+
+  it('rejects a graph input whose resolved model has an incompatible base', () => {
+    expect(() => run({ base: 'sd-1', layers: [layer({ model: model('sdxl') })] })).toThrow(/incompatible_base/);
+  });
+
+  it('rejects malformed numeric adapter values at the graph boundary', () => {
+    expect(() => run({ base: 'sd-1', layers: [layer({ weight: Number.NaN })] })).toThrow(/invalid_adapter_values/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 9. throws when denoise node missing
+// ---------------------------------------------------------------------------
+
+describe('addControlLayers — missing denoise node', () => {
+  it('throws when the base graph has no denoise node', () => {
+    const graph: TestGraph = { id: 'g', nodes: {}, edges: [] };
+    expect(() => addControlLayers(graph as never, { base: 'sd-1', layers: [layer()] })).toThrow(
+      /missing the denoise node/
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 10. getControlLayerRejectionReason branches
+// ---------------------------------------------------------------------------
+
+describe('getControlLayerRejectionReason', () => {
+  const validParams = {
+    layerName: 'My Layer',
+    hasContent: true,
+    kind: 'controlnet' as ControlAdapterKind,
+    adapterModel: { base: 'sd-1' },
+    beginEndStepPct: [0, 1] as [number, number],
+    mainBase: 'sd-1',
+    mainVariant: undefined as string | undefined,
+    weight: 0.75,
+  };
+
+  it('returns null for a valid controlnet on sd-1 with a matching model base', () => {
+    expect(getControlLayerRejectionReason(validParams)).toBeNull();
+  });
+
+  it('rejects when the layer has no content', () => {
+    const reason = getControlLayerRejectionReason({ ...validParams, hasContent: false });
+    expect(reason).toEqual(expect.any(String));
+    expect(reason).toContain('no control content');
+  });
+
+  it('rejects when no adapter model is selected', () => {
+    const reason = getControlLayerRejectionReason({ ...validParams, adapterModel: null });
+    expect(reason).toEqual(expect.any(String));
+    expect(reason).toContain('no control model');
+  });
+
+  it('rejects when the base+kind is unsupported', () => {
+    const reason = getControlLayerRejectionReason({
+      ...validParams,
+      mainBase: 'sd-2',
+      adapterModel: { base: 'sd-2' },
+    });
+    expect(reason).toEqual(expect.any(String));
+    expect(reason).toContain('not supported');
+  });
+
+  it('rejects when the adapter model base does not match the main base', () => {
+    const reason = getControlLayerRejectionReason({
+      ...validParams,
+      adapterModel: { base: 'sdxl' },
+    });
+    expect(reason).toEqual(expect.any(String));
+    expect(reason).toContain('incompatible base');
+  });
+
+  it('rejects FLUX Fill (dev_fill) + control_lora', () => {
+    const reason = getControlLayerRejectionReason({
+      layerName: 'My Layer',
+      hasContent: true,
+      kind: 'control_lora',
+      adapterModel: { base: 'flux' },
+      beginEndStepPct: [0, 1],
+      mainBase: 'flux',
+      mainVariant: 'dev_fill',
+      weight: 0.75,
+    });
+    expect(reason).toEqual(expect.any(String));
+    expect(reason).toContain('FLUX Fill');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/addControlLayers.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/addControlLayers.ts
new file mode 100644
index 00000000000..9a7e41c72a9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/addControlLayers.ts
@@ -0,0 +1,233 @@
+/**
+ * Pure control-layer graph grafting (legacy parity).
+ *
+ * {@link addControlLayers} wires each enabled, valid control layer's uploaded
+ * composite into a base-appropriate control adapter node, collects same-kind
+ * nodes, and connects the collector (or, for Control LoRA, the node directly) to
+ * the canvas graph's denoise node. It mutates the graph in place using the same
+ * `addNode`/`addEdge` helpers the base builders use — no fetch, no engine, no
+ * React. Node types + args mirror legacy
+ * `features/nodes/util/graph/generation/addControlAdapters.ts`.
+ *
+ * Per-base + per-kind support (legacy `getControlLayerWarnings` + the graph
+ * builders): controlnet on sd-1 / sdxl (`controlnet`) and flux (`flux_controlnet`);
+ * t2i_adapter on sd-1 / sdxl; control_lora on flux only (single layer, and never
+ * with a FLUX Fill main model); z_image_control on Z-Image only (single layer).
+ * Everything else is rejected upstream.
+ *
+ * The executor composites each control layer SEPARATELY (never blended) and
+ * passes its own uploaded image name in — so each adapter node references a
+ * distinct control image, exactly like legacy.
+ */
+
+import type { SupportedGenerateBase } from '@workbench/generation/baseGenerationPolicies';
+import type { BackendGraphContract, BackendInvocationContract } from '@workbench/types';
+
+import { addEdge, addNode } from '@workbench/generation/graphBuilder';
+
+import type { ControlAdapterKind } from './controlValidation';
+
+import { getControlValidationReason } from './controlValidation';
+
+/** The deterministic denoise node id every canvas base graph uses. */
+export const CONTROL_DENOISE_NODE_ID = 'denoise_latents';
+
+/** The control-adapter kinds a control layer can carry. */
+export type { ControlAdapterKind } from './controlValidation';
+
+/** A resolved control-adapter model identifier (the backend model field shape). */
+export interface ControlModelIdentifier {
+  key: string;
+  hash?: string;
+  name: string;
+  base: string;
+  type: string;
+}
+
+/** One control layer's fully-resolved graph contribution (invalid layers filtered out first). */
+export interface ControlLayerGraphInput {
+  /** The document layer id (used to mint deterministic node ids). */
+  id: string;
+  /** The uploaded per-layer composite image name. */
+  imageName: string;
+  kind: ControlAdapterKind;
+  /** The resolved control-adapter model identifier (never null here). */
+  model: ControlModelIdentifier;
+  weight: number;
+  beginEndStepPct: [number, number];
+  controlMode: 'balanced' | 'more_prompt' | 'more_control' | 'unbalanced' | null;
+}
+
+/**
+ * True when `base` supports control adapters of `kind` (legacy support matrix).
+ * `controlMode` and adapter-model base compatibility are validated separately.
+ */
+export { isControlKindSupportedForBase } from './controlValidation';
+
+/** Options for {@link addControlLayers}. */
+export interface AddControlLayersOptions {
+  /** The main model base — selects controlnet vs flux_controlnet and support. */
+  base: SupportedGenerateBase;
+  /** The main model variant (a FLUX `dev_fill` blocks Control LoRA). */
+  modelVariant?: string;
+  /** The valid, resolved control layers to graft (in document order). */
+  layers: readonly ControlLayerGraphInput[];
+}
+
+/** Resolves the backend node type for a controlnet layer on `base`. */
+const controlNetNodeType = (base: string): string => (base === 'flux' ? 'flux_controlnet' : 'controlnet');
+
+/**
+ * Grafts control layers onto a built canvas base graph. Revalidates support,
+ * model compatibility, the Control LoRA limit, and FLUX Fill restrictions so a
+ * caller cannot bypass the same shared validation used by invoke and UI. Wires:
+ * - controlnet → `control_net_collector` (collect) → `denoise.control`;
+ * - t2i_adapter → `t2i_adapter_collector` (collect) → `denoise.t2i_adapter`;
+ * - control_lora → `denoise.control_lora` directly (FLUX, first layer only).
+ * - z_image_control → `denoise.control` directly (Z-Image, first layer only).
+ */
+export const addControlLayers = (graph: BackendGraphContract, options: AddControlLayersOptions): void => {
+  const { base, layers, modelVariant } = options;
+  const denoise = graph.nodes[CONTROL_DENOISE_NODE_ID];
+  if (!denoise) {
+    throw new Error('addControlLayers: base graph is missing the denoise node.');
+  }
+
+  let controlNetCollector: BackendInvocationContract | null = null;
+  let t2iAdapterCollector: BackendInvocationContract | null = null;
+  let controlLoraCount = 0;
+  let zImageControlCount = 0;
+
+  const ensureControlNetCollector = (): BackendInvocationContract => {
+    if (!controlNetCollector) {
+      controlNetCollector = addNode(graph, { id: 'control_net_collector', type: 'collect' });
+      addEdge(graph, controlNetCollector, 'collection', denoise, 'control');
+    }
+    return controlNetCollector;
+  };
+
+  const ensureT2iAdapterCollector = (): BackendInvocationContract => {
+    if (!t2iAdapterCollector) {
+      t2iAdapterCollector = addNode(graph, { id: 't2i_adapter_collector', type: 'collect' });
+      addEdge(graph, t2iAdapterCollector, 'collection', denoise, 't2i_adapter');
+    }
+    return t2iAdapterCollector;
+  };
+
+  for (const layer of layers) {
+    const reason = getControlValidationReason({
+      adapterModel: layer.model,
+      beginEndStepPct: layer.beginEndStepPct,
+      controlLoraIndex: layer.kind === 'control_lora' ? controlLoraCount : 0,
+      kind: layer.kind,
+      mainBase: base,
+      mainVariant: modelVariant,
+      weight: layer.weight,
+      zImageControlIndex: layer.kind === 'z_image_control' ? zImageControlCount : 0,
+    });
+    if (reason) {
+      throw new Error(`Invalid control layer: ${reason}`);
+    }
+
+    if (layer.kind === 'controlnet') {
+      const node = addNode(graph, {
+        begin_step_percent: layer.beginEndStepPct[0],
+        control_model: layer.model,
+        control_weight: layer.weight,
+        end_step_percent: layer.beginEndStepPct[1],
+        id: `control_net_${layer.id}`,
+        image: { image_name: layer.imageName },
+        resize_mode: 'just_resize',
+        type: controlNetNodeType(base),
+        // FLUX ControlNet has no control_mode; SD-family carries it.
+        ...(base === 'flux' ? {} : { control_mode: layer.controlMode ?? 'balanced' }),
+      });
+      addEdge(graph, node, 'control', ensureControlNetCollector(), 'item');
+    } else if (layer.kind === 't2i_adapter') {
+      const node = addNode(graph, {
+        begin_step_percent: layer.beginEndStepPct[0],
+        end_step_percent: layer.beginEndStepPct[1],
+        id: `t2i_adapter_${layer.id}`,
+        image: { image_name: layer.imageName },
+        resize_mode: 'just_resize',
+        t2i_adapter_model: layer.model,
+        type: 't2i_adapter',
+        weight: layer.weight,
+      });
+      addEdge(graph, node, 't2i_adapter', ensureT2iAdapterCollector(), 'item');
+    } else if (layer.kind === 'control_lora') {
+      const node = addNode(graph, {
+        id: `control_lora_${layer.id}`,
+        image: { image_name: layer.imageName },
+        lora: layer.model,
+        type: 'flux_control_lora_loader',
+        weight: layer.weight,
+      });
+      addEdge(graph, node, 'control_lora', denoise, 'control_lora');
+      controlLoraCount += 1;
+    } else {
+      const node = addNode(graph, {
+        begin_step_percent: layer.beginEndStepPct[0],
+        control_context_scale: layer.weight,
+        control_model: layer.model,
+        end_step_percent: layer.beginEndStepPct[1],
+        id: `z_image_control_${layer.id}`,
+        image: { image_name: layer.imageName },
+        type: 'z_image_control',
+      });
+      addEdge(graph, node, 'control', denoise, 'control');
+      zImageControlCount += 1;
+    }
+  }
+};
+
+/**
+ * Returns the legacy-parity rejection reason for a control layer, or `null` when
+ * it is valid for generation. Mirrors `getControlLayerWarnings`:
+ * - no drawn/composited content → "no control";
+ * - no adapter model selected → "no model";
+ * - main base unsupported (sd-2 / sd-3 / anima / …) → "unsupported model";
+ * - adapter model base ≠ main base → "incompatible base";
+ * - FLUX Fill + Control LoRA → "incompatible".
+ */
+export const getControlLayerRejectionReason = (params: {
+  layerName: string;
+  hasContent: boolean;
+  kind: ControlAdapterKind;
+  adapterModel: { base: string; type?: string } | null;
+  beginEndStepPct: [number, number];
+  mainBase: string;
+  mainVariant?: string;
+  weight: number;
+}): string | null => {
+  const { adapterModel, beginEndStepPct, hasContent, kind, layerName, mainBase, mainVariant, weight } = params;
+
+  if (!hasContent) {
+    return `Control layer "${layerName}" has no control content.`;
+  }
+  const reason = getControlValidationReason({
+    adapterModel: adapterModel ? { base: adapterModel.base, type: adapterModel.type ?? kind } : null,
+    beginEndStepPct,
+    controlLoraIndex: 0,
+    kind,
+    mainBase,
+    mainVariant,
+    weight,
+  });
+  if (!reason) {
+    return null;
+  }
+  if (reason === 'missing_model') {
+    return `Control layer "${layerName}" has no control model selected.`;
+  }
+  if (reason === 'unsupported_adapter') {
+    return `Control layer "${layerName}" is not supported for the selected base model.`;
+  }
+  if (reason === 'incompatible_base') {
+    return `Control layer "${layerName}" uses an incompatible base model.`;
+  }
+  if (reason === 'flux_fill_control_lora') {
+    return 'Control LoRA is not compatible with FLUX Fill.';
+  }
+  return `Control layer "${layerName}" uses an incompatible control adapter.`;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/addRegionalGuidance.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/addRegionalGuidance.test.ts
new file mode 100644
index 00000000000..9819afbfc73
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/addRegionalGuidance.test.ts
@@ -0,0 +1,312 @@
+import { describe, expect, it } from 'vitest';
+
+import type { AddRegionalGuidanceOptions, RegionalGuidanceInput, RegionalReferenceModel } from './addRegionalGuidance';
+
+import {
+  addRegionalGuidance,
+  getRegionalGuidanceRejectionReason,
+  isRegionalGuidanceSupportedForBase,
+} from './addRegionalGuidance';
+
+interface TestGraph {
+  id: string;
+  nodes: Record<string, { id: string; type: string; [key: string]: unknown }>;
+  edges: { source: { node_id: string; field: string }; destination: { node_id: string; field: string } }[];
+}
+
+/** A minimal SD-family base graph: pos/neg cond + collectors wired to denoise, with clip edges. */
+const sdBaseGraph = (opts: { sdxl?: boolean } = {}): TestGraph => {
+  const clip2Edges = opts.sdxl
+    ? [
+        { destination: { field: 'clip2', node_id: 'pos_cond' }, source: { field: 'clip2', node_id: 'model_loader' } },
+        { destination: { field: 'clip2', node_id: 'neg_cond' }, source: { field: 'clip2', node_id: 'model_loader' } },
+      ]
+    : [];
+  return {
+    edges: [
+      { destination: { field: 'clip', node_id: 'pos_cond' }, source: { field: 'clip', node_id: 'clip_skip' } },
+      { destination: { field: 'clip', node_id: 'neg_cond' }, source: { field: 'clip', node_id: 'clip_skip' } },
+      ...clip2Edges,
+      {
+        destination: { field: 'positive_conditioning', node_id: 'denoise_latents' },
+        source: { field: 'collection', node_id: 'pos_cond_collect' },
+      },
+      {
+        destination: { field: 'negative_conditioning', node_id: 'denoise_latents' },
+        source: { field: 'collection', node_id: 'neg_cond_collect' },
+      },
+    ],
+    id: 'g',
+    nodes: {
+      denoise_latents: { id: 'denoise_latents', type: 'denoise_latents' },
+      neg_cond: { id: 'neg_cond', type: opts.sdxl ? 'sdxl_compel_prompt' : 'compel' },
+      neg_cond_collect: { id: 'neg_cond_collect', type: 'collect' },
+      pos_cond: { id: 'pos_cond', type: opts.sdxl ? 'sdxl_compel_prompt' : 'compel' },
+      pos_cond_collect: { id: 'pos_cond_collect', type: 'collect' },
+    },
+  };
+};
+
+/** A minimal FLUX base graph: pos cond + collector, no negative. */
+const fluxBaseGraph = (): TestGraph => ({
+  edges: [
+    { destination: { field: 'clip', node_id: 'pos_cond' }, source: { field: 'clip', node_id: 'model_loader' } },
+    {
+      destination: { field: 't5_encoder', node_id: 'pos_cond' },
+      source: { field: 't5_encoder', node_id: 'model_loader' },
+    },
+    {
+      destination: { field: 'positive_text_conditioning', node_id: 'denoise_latents' },
+      source: { field: 'collection', node_id: 'pos_cond_collect' },
+    },
+  ],
+  id: 'g',
+  nodes: {
+    denoise_latents: { id: 'denoise_latents', type: 'flux_denoise' },
+    pos_cond: { id: 'pos_cond', type: 'flux_text_encoder' },
+    pos_cond_collect: { id: 'pos_cond_collect', type: 'collect' },
+  },
+});
+
+const ipModel = (base: string): RegionalReferenceModel => ({
+  base,
+  key: `ip-${base}`,
+  name: `IP ${base}`,
+  type: 'ip_adapter',
+});
+
+const region = (overrides: Partial<RegionalGuidanceInput> = {}): RegionalGuidanceInput => ({
+  autoNegative: false,
+  id: 'r1',
+  maskImageName: 'mask1.png',
+  negativePrompt: null,
+  positivePrompt: 'a cat',
+  referenceImages: [],
+  ...overrides,
+});
+
+const run = (graph: TestGraph, options: AddRegionalGuidanceOptions): TestGraph => {
+  addRegionalGuidance(graph as never, options);
+  return graph;
+};
+
+const nodesOfType = (graph: TestGraph, type: string) => Object.values(graph.nodes).filter((n) => n.type === type);
+const hasEdge = (graph: TestGraph, s: string, sf: string, d: string, df: string): boolean =>
+  graph.edges.some(
+    (e) => e.source.node_id === s && e.source.field === sf && e.destination.node_id === d && e.destination.field === df
+  );
+
+describe('isRegionalGuidanceSupportedForBase', () => {
+  it('supports sd-1 / sdxl / flux and nothing else', () => {
+    expect(isRegionalGuidanceSupportedForBase('sd-1')).toBe(true);
+    expect(isRegionalGuidanceSupportedForBase('sdxl')).toBe(true);
+    expect(isRegionalGuidanceSupportedForBase('flux')).toBe(true);
+    expect(isRegionalGuidanceSupportedForBase('sd-3')).toBe(false);
+    expect(isRegionalGuidanceSupportedForBase('cogview4')).toBe(false);
+  });
+});
+
+describe('addRegionalGuidance — SD1', () => {
+  it('wires a mask tensor + positive conditioning into the positive collector, copying clip', () => {
+    const g = run(sdBaseGraph(), { base: 'sd-1', regions: [region()] });
+    const mask = nodesOfType(g, 'alpha_mask_to_tensor');
+    expect(mask).toHaveLength(1);
+    expect(mask[0].image).toEqual({ image_name: 'mask1.png' });
+    expect(mask[0].id).toBe('rg_mask_to_tensor_r1');
+
+    const posCond = g.nodes.rg_pos_cond_r1;
+    expect(posCond).toBeDefined();
+    expect(posCond.type).toBe('compel');
+    expect(posCond.prompt).toBe('a cat');
+    // mask edge + conditioning into the collector.
+    expect(hasEdge(g, 'rg_mask_to_tensor_r1', 'mask', 'rg_pos_cond_r1', 'mask')).toBe(true);
+    expect(hasEdge(g, 'rg_pos_cond_r1', 'conditioning', 'pos_cond_collect', 'item')).toBe(true);
+    // Copied the global posCond clip edge.
+    expect(hasEdge(g, 'clip_skip', 'clip', 'rg_pos_cond_r1', 'clip')).toBe(true);
+  });
+
+  it('wires a negative prompt into the negative collector', () => {
+    const g = run(sdBaseGraph(), { base: 'sd-1', regions: [region({ negativePrompt: 'blurry' })] });
+    expect(g.nodes.rg_neg_cond_r1.prompt).toBe('blurry');
+    expect(hasEdge(g, 'rg_mask_to_tensor_r1', 'mask', 'rg_neg_cond_r1', 'mask')).toBe(true);
+    expect(hasEdge(g, 'rg_neg_cond_r1', 'conditioning', 'neg_cond_collect', 'item')).toBe(true);
+    expect(hasEdge(g, 'clip_skip', 'clip', 'rg_neg_cond_r1', 'clip')).toBe(true);
+  });
+
+  it('autoNegative inverts the mask and re-encodes the positive prompt into the negative collector', () => {
+    const g = run(sdBaseGraph(), { base: 'sd-1', regions: [region({ autoNegative: true })] });
+    const invert = nodesOfType(g, 'invert_tensor_mask');
+    expect(invert).toHaveLength(1);
+    expect(invert[0].id).toBe('rg_invert_mask_r1');
+    expect(hasEdge(g, 'rg_mask_to_tensor_r1', 'mask', 'rg_invert_mask_r1', 'mask')).toBe(true);
+    // The inverted-cond node uses the POSITIVE prompt but feeds the NEGATIVE collector.
+    expect(g.nodes.rg_pos_cond_inverted_r1.prompt).toBe('a cat');
+    expect(hasEdge(g, 'rg_invert_mask_r1', 'mask', 'rg_pos_cond_inverted_r1', 'mask')).toBe(true);
+    expect(hasEdge(g, 'rg_pos_cond_inverted_r1', 'conditioning', 'neg_cond_collect', 'item')).toBe(true);
+  });
+
+  it('does not autoNegative when there is no positive prompt', () => {
+    const g = run(sdBaseGraph(), {
+      base: 'sd-1',
+      regions: [region({ autoNegative: true, negativePrompt: 'x', positivePrompt: null })],
+    });
+    expect(nodesOfType(g, 'invert_tensor_mask')).toHaveLength(0);
+  });
+
+  it('wires a regional ip_adapter reference image mask-scoped into a collector → denoise.ip_adapter', () => {
+    const g = run(sdBaseGraph(), {
+      base: 'sd-1',
+      regions: [
+        region({
+          referenceImages: [
+            {
+              beginEndStepPct: [0, 1],
+              clipVisionModel: 'ViT-H',
+              id: 'ref1',
+              imageName: 'ref.png',
+              method: 'full',
+              model: ipModel('sd-1'),
+              type: 'ip_adapter',
+              weight: 0.8,
+            },
+          ],
+        }),
+      ],
+    });
+    const ip = g.nodes.ip_adapter_ref1;
+    expect(ip.type).toBe('ip_adapter');
+    expect(ip.weight).toBe(0.8);
+    expect(ip.image).toEqual({ image_name: 'ref.png' });
+    expect(hasEdge(g, 'rg_mask_to_tensor_r1', 'mask', 'ip_adapter_ref1', 'mask')).toBe(true);
+    // A collector feeds denoise.ip_adapter.
+    const collectorEdge = g.edges.find(
+      (e) => e.destination.node_id === 'denoise_latents' && e.destination.field === 'ip_adapter'
+    );
+    expect(collectorEdge).toBeDefined();
+    expect(hasEdge(g, 'ip_adapter_ref1', 'ip_adapter', collectorEdge!.source.node_id, 'item')).toBe(true);
+  });
+});
+
+describe('addRegionalGuidance — SDXL', () => {
+  it('sets prompt + style on the sdxl encoder and copies clip + clip2', () => {
+    const g = run(sdBaseGraph({ sdxl: true }), { base: 'sdxl', regions: [region()] });
+    const posCond = g.nodes.rg_pos_cond_r1;
+    expect(posCond.type).toBe('sdxl_compel_prompt');
+    expect(posCond.prompt).toBe('a cat');
+    expect(posCond.style).toBe('a cat');
+    expect(hasEdge(g, 'clip_skip', 'clip', 'rg_pos_cond_r1', 'clip')).toBe(true);
+    expect(hasEdge(g, 'model_loader', 'clip2', 'rg_pos_cond_r1', 'clip2')).toBe(true);
+  });
+});
+
+describe('addRegionalGuidance — FLUX', () => {
+  it('wires a positive prompt into pos_cond_collect and copies clip/t5, no negative path', () => {
+    const g = run(fluxBaseGraph(), { base: 'flux', regions: [region({ negativePrompt: 'blurry' })] });
+    expect(g.nodes.rg_pos_cond_r1.type).toBe('flux_text_encoder');
+    expect(hasEdge(g, 'rg_pos_cond_r1', 'conditioning', 'pos_cond_collect', 'item')).toBe(true);
+    expect(hasEdge(g, 'model_loader', 't5_encoder', 'rg_pos_cond_r1', 't5_encoder')).toBe(true);
+    // No regional negative conditioning on FLUX.
+    expect(g.nodes.rg_neg_cond_r1).toBeUndefined();
+  });
+
+  it('ignores regional ip_adapter on FLUX and does not wire denoise.ip_adapter', () => {
+    const g = run(fluxBaseGraph(), {
+      base: 'flux',
+      regions: [
+        region({
+          referenceImages: [
+            {
+              beginEndStepPct: [0, 1],
+              clipVisionModel: 'ViT-H',
+              id: 'ref1',
+              imageName: 'ref.png',
+              method: 'full',
+              model: ipModel('flux'),
+              type: 'ip_adapter',
+              weight: 1,
+            },
+          ],
+        }),
+      ],
+    });
+    expect(g.nodes.ip_adapter_ref1).toBeUndefined();
+  });
+
+  it('wires a flux_redux reference image mask-scoped into denoise.redux_conditioning', () => {
+    const g = run(fluxBaseGraph(), {
+      base: 'flux',
+      regions: [
+        region({
+          referenceImages: [
+            {
+              id: 'ref2',
+              imageName: 'redux.png',
+              model: { base: 'flux', key: 'redux', name: 'Redux', type: 'flux_redux' },
+              settings: { downsampling_factor: 1, weight: 1 },
+              type: 'flux_redux',
+            },
+          ],
+        }),
+      ],
+    });
+    const redux = g.nodes.flux_redux_ref2;
+    expect(redux.type).toBe('flux_redux');
+    expect(hasEdge(g, 'rg_mask_to_tensor_r1', 'mask', 'flux_redux_ref2', 'mask')).toBe(true);
+    const reduxEdge = g.edges.find(
+      (e) => e.destination.node_id === 'denoise_latents' && e.destination.field === 'redux_conditioning'
+    );
+    expect(reduxEdge).toBeDefined();
+    expect(hasEdge(g, 'flux_redux_ref2', 'redux_cond', reduxEdge!.source.node_id, 'item')).toBe(true);
+  });
+});
+
+describe('addRegionalGuidance — multiple regions coexist', () => {
+  it('mints distinct deterministic node ids per region', () => {
+    const g = run(sdBaseGraph(), {
+      base: 'sd-1',
+      regions: [region({ id: 'a', positivePrompt: 'cat' }), region({ id: 'b', positivePrompt: 'dog' })],
+    });
+    expect(g.nodes.rg_pos_cond_a.prompt).toBe('cat');
+    expect(g.nodes.rg_pos_cond_b.prompt).toBe('dog');
+    expect(nodesOfType(g, 'alpha_mask_to_tensor')).toHaveLength(2);
+  });
+});
+
+describe('getRegionalGuidanceRejectionReason', () => {
+  const params = {
+    autoNegative: false,
+    hasContent: true,
+    layerName: 'Region 1',
+    mainBase: 'sd-1',
+    negativePrompt: null as string | null,
+    positivePrompt: 'a cat' as string | null,
+    referenceImageCount: 0,
+  };
+
+  it('accepts a valid SD region', () => {
+    expect(getRegionalGuidanceRejectionReason(params)).toBeNull();
+  });
+
+  it('rejects an unsupported base', () => {
+    expect(getRegionalGuidanceRejectionReason({ ...params, mainBase: 'sd-3' })).toMatch(/not supported/);
+  });
+
+  it('rejects an empty mask', () => {
+    expect(getRegionalGuidanceRejectionReason({ ...params, hasContent: false })).toMatch(/no masked region/);
+  });
+
+  it('rejects a region with no prompt and no reference images', () => {
+    expect(getRegionalGuidanceRejectionReason({ ...params, positivePrompt: null, referenceImageCount: 0 })).toMatch(
+      /no prompt or reference/
+    );
+  });
+
+  it('rejects a FLUX negative prompt / autoNegative', () => {
+    expect(getRegionalGuidanceRejectionReason({ ...params, mainBase: 'flux', negativePrompt: 'blurry' })).toMatch(
+      /negative prompts are not supported for FLUX/
+    );
+    expect(getRegionalGuidanceRejectionReason({ ...params, autoNegative: true, mainBase: 'flux' })).toMatch(
+      /auto-negative is not supported for FLUX/
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/addRegionalGuidance.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/addRegionalGuidance.ts
new file mode 100644
index 00000000000..e282b4a15b2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/addRegionalGuidance.ts
@@ -0,0 +1,356 @@
+/**
+ * Pure regional-guidance graph grafting (legacy parity).
+ *
+ * {@link addRegionalGuidance} wires each enabled, valid regional-guidance region
+ * into the canvas base graph's conditioning collectors: a per-region
+ * `alpha_mask_to_tensor` node (fed by the region's uploaded mask image) supplies
+ * a mask tensor that scopes per-region positive/negative prompt conditioning
+ * (into `pos_cond_collect` / `neg_cond_collect`), an `autoNegative` inverted-mask
+ * negative conditioning, and mask-scoped reference images (SD `ip_adapter`,
+ * FLUX `flux_redux`). It mutates the graph in place using the same
+ * `addNode`/`addEdge` helpers the base builders use — no fetch, no engine, no
+ * React. Node types + args mirror legacy
+ * `features/nodes/util/graph/generation/addRegions.ts`.
+ *
+ * ## Support matrix (legacy `getRegionalGuidanceWarnings`)
+ *
+ * - **sd-1 / sdxl**: full support — positive, negative, autoNegative, regional
+ *   `ip_adapter` reference images.
+ * - **flux**: positive prompt + `flux_redux` reference images only. Negative
+ *   prompt, autoNegative, and regional `ip_adapter` are NOT supported (silently
+ *   skipped here; surfaced as a rejection reason upstream).
+ * - Every other base is unsupported (region skipped; rejection reason emitted).
+ *
+ * The caller (`prepareCanvasInvocation`) composites + uploads each region's mask
+ * separately and resolves reference-image models, then passes only valid regions
+ * in — this module only shapes nodes/edges.
+ */
+
+import type { BackendGraphContract, BackendInvocationContract } from '@workbench/types';
+
+import { addEdge, addNode } from '@workbench/generation/graphBuilder';
+
+/** The deterministic denoise node id every canvas base graph uses. */
+const DENOISE_NODE_ID = 'denoise_latents';
+/** The deterministic global positive/negative conditioning + collector node ids. */
+const POS_COND_ID = 'pos_cond';
+const NEG_COND_ID = 'neg_cond';
+const POS_COND_COLLECT_ID = 'pos_cond_collect';
+const NEG_COND_COLLECT_ID = 'neg_cond_collect';
+
+/** The base models regional guidance supports (legacy: sd-1 / sdxl / flux). */
+export type RegionalGuidanceBase = 'sd-1' | 'sdxl' | 'flux';
+
+/** True when `base` supports regional guidance at all (SD1 / SDXL / FLUX). */
+export const isRegionalGuidanceSupportedForBase = (base: string): base is RegionalGuidanceBase =>
+  base === 'sd-1' || base === 'sdxl' || base === 'flux';
+
+/** Whether a base supports regional NEGATIVE prompts / autoNegative (SD family only, not FLUX). */
+const supportsRegionalNegative = (base: RegionalGuidanceBase): boolean => base === 'sd-1' || base === 'sdxl';
+
+/** A resolved reference-image (component) model identifier — the backend model field shape. */
+export interface RegionalReferenceModel {
+  key: string;
+  hash?: string;
+  name: string;
+  base: string;
+  type: string;
+}
+
+/** A regional `ip_adapter` reference image (SD1 / SDXL). */
+export interface RegionalIPAdapterInput {
+  type: 'ip_adapter';
+  /** The reference-image id (mints the deterministic `ip_adapter_${id}` node id). */
+  id: string;
+  imageName: string;
+  model: RegionalReferenceModel;
+  weight: number;
+  method: string;
+  clipVisionModel: string;
+  beginEndStepPct: [number, number];
+}
+
+/** A regional `flux_redux` reference image (FLUX). */
+export interface RegionalFluxReduxInput {
+  type: 'flux_redux';
+  /** The reference-image id (mints the deterministic `flux_redux_${id}` node id). */
+  id: string;
+  imageName: string;
+  model: RegionalReferenceModel;
+  /** Backend redux knobs (downsampling_factor + weight), resolved from imageInfluence upstream. */
+  settings: { downsampling_factor: number; weight: number };
+}
+
+/** One resolved regional reference image. */
+export type RegionalReferenceImageInput = RegionalIPAdapterInput | RegionalFluxReduxInput;
+
+/** One fully-resolved region's graph contribution (invalid regions filtered out first). */
+export interface RegionalGuidanceInput {
+  /** The document layer id (mints deterministic node ids). */
+  id: string;
+  /** The uploaded per-region mask image name (alpha = region coverage). */
+  maskImageName: string;
+  positivePrompt: string | null;
+  negativePrompt: string | null;
+  autoNegative: boolean;
+  referenceImages: readonly RegionalReferenceImageInput[];
+}
+
+/** Options for {@link addRegionalGuidance}. */
+export interface AddRegionalGuidanceOptions {
+  base: RegionalGuidanceBase;
+  regions: readonly RegionalGuidanceInput[];
+}
+
+/** Per-base conditioning encoder node type + the fields carrying the prompt. */
+const conditioningNodeType = (base: RegionalGuidanceBase): string => {
+  switch (base) {
+    case 'sdxl':
+      return 'sdxl_compel_prompt';
+    case 'flux':
+      return 'flux_text_encoder';
+    case 'sd-1':
+      return 'compel';
+  }
+};
+
+/** The prompt input fields to set on a regional conditioning node (SDXL mirrors prompt→style). */
+const promptFields = (base: RegionalGuidanceBase): readonly string[] =>
+  base === 'sdxl' ? ['prompt', 'style'] : ['prompt'];
+
+/**
+ * The encoder-input fields to COPY from the global conditioning node onto a
+ * regional one, so the region shares the same CLIP / T5 encoders (legacy copies
+ * the CLIP/T5 edges verbatim). `mask` is wired separately, so it's excluded here.
+ */
+const copyEncoderFields = (base: RegionalGuidanceBase): readonly string[] => {
+  switch (base) {
+    case 'sdxl':
+      return ['clip', 'clip2'];
+    case 'flux':
+      return ['clip', 't5_encoder', 't5_max_seq_len'];
+    case 'sd-1':
+      return ['clip'];
+  }
+};
+
+/**
+ * Copies every edge feeding `sourceNodeId`'s `fields` onto `target` (same source,
+ * same field). Used to share the global conditioning node's CLIP/T5 encoder
+ * inputs with a per-region conditioning node.
+ */
+const copyEncoderEdges = (
+  graph: BackendGraphContract,
+  sourceNodeId: string,
+  target: BackendInvocationContract,
+  fields: readonly string[]
+): void => {
+  const fieldSet = new Set(fields);
+  for (const edge of graph.edges) {
+    if (edge.destination.node_id !== sourceNodeId || !fieldSet.has(edge.destination.field)) {
+      continue;
+    }
+    graph.edges.push({
+      destination: { field: edge.destination.field, node_id: target.id },
+      source: { field: edge.source.field, node_id: edge.source.node_id },
+    });
+  }
+};
+
+/** Resolves (or lazily creates) the collector feeding `denoise.<field>`, with a stable fallback id. */
+const resolveDenoiseCollector = (
+  graph: BackendGraphContract,
+  denoise: BackendInvocationContract,
+  denoiseField: string,
+  fallbackId: string
+): BackendInvocationContract => {
+  const existing = graph.edges.find(
+    (edge) => edge.destination.node_id === denoise.id && edge.destination.field === denoiseField
+  );
+  if (existing) {
+    const node = graph.nodes[existing.source.node_id];
+    if (node) {
+      return node;
+    }
+  }
+  const collector = addNode(graph, { id: fallbackId, type: 'collect' });
+  addEdge(graph, collector, 'collection', denoise, denoiseField);
+  return collector;
+};
+
+/** Builds a per-region conditioning node with its prompt set and encoder edges copied. */
+const addRegionalConditioning = (
+  graph: BackendGraphContract,
+  base: RegionalGuidanceBase,
+  nodeId: string,
+  prompt: string,
+  copyFrom: string
+): BackendInvocationContract => {
+  const node = addNode(graph, { id: nodeId, type: conditioningNodeType(base) });
+  for (const field of promptFields(base)) {
+    (node as Record<string, unknown>)[field] = prompt;
+  }
+  copyEncoderEdges(graph, copyFrom, node, copyEncoderFields(base));
+  return node;
+};
+
+/**
+ * Grafts regional guidance onto a built canvas base graph. Assumes every input is
+ * already validated for `base` (supported base, non-empty region, resolved
+ * reference-image models) — use {@link getRegionalGuidanceRejectionReason} to
+ * filter first. Wires, per enabled region:
+ * - `alpha_mask_to_tensor` from the uploaded region mask;
+ * - positive prompt → regional conditioning → `pos_cond_collect`;
+ * - negative prompt (SD only) → regional conditioning → `neg_cond_collect`;
+ * - autoNegative (SD only) → `invert_tensor_mask` + positive prompt re-encoded →
+ *   `neg_cond_collect` (push the positive prompt away outside the region);
+ * - reference images → mask-scoped `ip_adapter` (SD) / `flux_redux` (FLUX).
+ */
+export const addRegionalGuidance = (graph: BackendGraphContract, options: AddRegionalGuidanceOptions): void => {
+  const { base, regions } = options;
+  const denoise = graph.nodes[DENOISE_NODE_ID];
+  if (!denoise) {
+    throw new Error('addRegionalGuidance: base graph is missing the denoise node.');
+  }
+  const posCondCollect = graph.nodes[POS_COND_COLLECT_ID];
+  if (!posCondCollect) {
+    throw new Error('addRegionalGuidance: base graph is missing the positive conditioning collector.');
+  }
+  const negCondCollect = graph.nodes[NEG_COND_COLLECT_ID] ?? null;
+  const withNegative = supportsRegionalNegative(base);
+
+  let ipAdapterCollector: BackendInvocationContract | null = null;
+  let fluxReduxCollector: BackendInvocationContract | null = null;
+
+  for (const region of regions) {
+    const maskToTensor = addNode(graph, {
+      id: `rg_mask_to_tensor_${region.id}`,
+      image: { image_name: region.maskImageName },
+      type: 'alpha_mask_to_tensor',
+    });
+
+    // Positive prompt → positive collector (mask-scoped).
+    if (region.positivePrompt) {
+      const posCond = addRegionalConditioning(
+        graph,
+        base,
+        `rg_pos_cond_${region.id}`,
+        region.positivePrompt,
+        POS_COND_ID
+      );
+      addEdge(graph, maskToTensor, 'mask', posCond, 'mask');
+      addEdge(graph, posCond, 'conditioning', posCondCollect, 'item');
+    }
+
+    // Negative prompt → negative collector (SD only; FLUX has no negative path).
+    if (region.negativePrompt && withNegative && negCondCollect) {
+      const negCond = addRegionalConditioning(
+        graph,
+        base,
+        `rg_neg_cond_${region.id}`,
+        region.negativePrompt,
+        NEG_COND_ID
+      );
+      addEdge(graph, maskToTensor, 'mask', negCond, 'mask');
+      addEdge(graph, negCond, 'conditioning', negCondCollect, 'item');
+    }
+
+    // autoNegative: re-encode the POSITIVE prompt over the INVERTED mask into the
+    // negative collector — pushes the region's prompt away everywhere outside it.
+    if (region.autoNegative && region.positivePrompt && withNegative && negCondCollect) {
+      const invert = addNode(graph, { id: `rg_invert_mask_${region.id}`, type: 'invert_tensor_mask' });
+      addEdge(graph, maskToTensor, 'mask', invert, 'mask');
+      const inverted = addRegionalConditioning(
+        graph,
+        base,
+        `rg_pos_cond_inverted_${region.id}`,
+        region.positivePrompt,
+        POS_COND_ID
+      );
+      addEdge(graph, invert, 'mask', inverted, 'mask');
+      addEdge(graph, inverted, 'conditioning', negCondCollect, 'item');
+    }
+
+    // Reference images (mask-scoped): ip_adapter on SD, flux_redux on FLUX.
+    for (const ref of region.referenceImages) {
+      if (ref.type === 'ip_adapter' && base !== 'flux') {
+        if (!ipAdapterCollector) {
+          ipAdapterCollector = resolveDenoiseCollector(graph, denoise, 'ip_adapter', 'regional_ip_adapter_collector');
+        }
+        const node = addNode(graph, {
+          begin_step_percent: ref.beginEndStepPct[0],
+          clip_vision_model: ref.clipVisionModel,
+          end_step_percent: ref.beginEndStepPct[1],
+          id: `ip_adapter_${ref.id}`,
+          image: { image_name: ref.imageName },
+          ip_adapter_model: ref.model,
+          method: ref.method,
+          type: 'ip_adapter',
+          weight: ref.weight,
+        });
+        addEdge(graph, maskToTensor, 'mask', node, 'mask');
+        addEdge(graph, node, 'ip_adapter', ipAdapterCollector, 'item');
+      } else if (ref.type === 'flux_redux' && base === 'flux') {
+        if (!fluxReduxCollector) {
+          fluxReduxCollector = resolveDenoiseCollector(
+            graph,
+            denoise,
+            'redux_conditioning',
+            'regional_flux_redux_collector'
+          );
+        }
+        const node = addNode(graph, {
+          downsampling_factor: ref.settings.downsampling_factor,
+          id: `flux_redux_${ref.id}`,
+          image: { image_name: ref.imageName },
+          redux_model: ref.model,
+          type: 'flux_redux',
+          weight: ref.settings.weight,
+        });
+        addEdge(graph, maskToTensor, 'mask', node, 'mask');
+        addEdge(graph, node, 'redux_cond', fluxReduxCollector, 'item');
+      }
+    }
+  }
+};
+
+/**
+ * Returns the legacy-parity rejection reason for a regional-guidance region, or
+ * `null` when it can contribute to generation. Mirrors
+ * `getRegionalGuidanceWarnings`:
+ * - unsupported main base (sd-2 / sd-3 / cogview / …) → "unsupported model";
+ * - no drawn mask content → "no region";
+ * - no positive prompt, no negative prompt, and no reference images → "empty";
+ * - FLUX with a negative prompt / autoNegative → those are unsupported on FLUX.
+ *
+ * Per-reference-image model/image validity is resolved by the caller (which drops
+ * incomplete reference images before building), matching how control layers work.
+ */
+export const getRegionalGuidanceRejectionReason = (params: {
+  layerName: string;
+  mainBase: string;
+  hasContent: boolean;
+  positivePrompt: string | null;
+  negativePrompt: string | null;
+  autoNegative: boolean;
+  referenceImageCount: number;
+}): string | null => {
+  const { autoNegative, hasContent, layerName, mainBase, negativePrompt, positivePrompt, referenceImageCount } = params;
+
+  if (!isRegionalGuidanceSupportedForBase(mainBase)) {
+    return `Regional guidance "${layerName}" is not supported for the selected base model.`;
+  }
+  if (!hasContent) {
+    return `Regional guidance "${layerName}" has no masked region.`;
+  }
+  if (!positivePrompt && !negativePrompt && referenceImageCount === 0) {
+    return `Regional guidance "${layerName}" has no prompt or reference image.`;
+  }
+  if (mainBase === 'flux' && negativePrompt) {
+    return `Regional guidance "${layerName}" negative prompts are not supported for FLUX.`;
+  }
+  if (mainBase === 'flux' && autoNegative) {
+    return `Regional guidance "${layerName}" auto-negative is not supported for FLUX.`;
+  }
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/canvasMode.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/canvasMode.test.ts
new file mode 100644
index 00000000000..9b831134a96
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/canvasMode.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+
+import type { CanvasModeInput } from './canvasMode';
+import type { Rect } from './types';
+
+import { detectCanvasMode } from './canvasMode';
+
+const BBOX: Rect = { height: 100, width: 100, x: 0, y: 0 };
+
+const input = (overrides: Partial<CanvasModeInput> = {}): CanvasModeInput => ({
+  bbox: BBOX,
+  bboxFullyCovered: false,
+  contentBounds: null,
+  hasActiveInpaintMask: false,
+  ...overrides,
+});
+
+describe('detectCanvasMode', () => {
+  describe('txt2img', () => {
+    it('returns txt2img when there is no content at all', () => {
+      expect(detectCanvasMode(input({ contentBounds: null }))).toBe('txt2img');
+    });
+
+    it('returns txt2img when content lies entirely outside the bbox', () => {
+      const contentBounds: Rect = { height: 50, width: 50, x: 200, y: 200 };
+      expect(detectCanvasMode(input({ contentBounds }))).toBe('txt2img');
+    });
+
+    it('treats a flush edge (0px interior overlap) as no intersection → txt2img', () => {
+      // Content's left edge sits exactly on the bbox's right edge (x = 100).
+      const contentBounds: Rect = { height: 100, width: 50, x: 100, y: 0 };
+      expect(detectCanvasMode(input({ contentBounds }))).toBe('txt2img');
+    });
+
+    it('returns txt2img for a zero-width bbox even when content overlaps its line', () => {
+      const bbox: Rect = { height: 100, width: 0, x: 0, y: 0 };
+      const contentBounds: Rect = { height: 100, width: 100, x: 0, y: 0 };
+      expect(detectCanvasMode(input({ bbox, bboxFullyCovered: true, contentBounds }))).toBe('txt2img');
+    });
+
+    it('returns txt2img for a zero-height bbox', () => {
+      const bbox: Rect = { height: 0, width: 100, x: 0, y: 0 };
+      const contentBounds: Rect = { height: 100, width: 100, x: 0, y: 0 };
+      expect(detectCanvasMode(input({ bbox, bboxFullyCovered: true, contentBounds }))).toBe('txt2img');
+    });
+
+    it('stays txt2img for a new canvas seeded with only an empty inpaint mask', () => {
+      // A brand-new canvas carries one empty inpaint mask (see
+      // `createNewCanvasStateV2`). An empty mask contributes no raster content
+      // (`contentBounds` stays null) and has no content (`hasActiveInpaintMask`
+      // is false), so mode detection must NOT flip to inpaint.
+      expect(detectCanvasMode(input({ contentBounds: null, hasActiveInpaintMask: false }))).toBe('txt2img');
+    });
+  });
+
+  describe('outpaint', () => {
+    it('returns outpaint when content intersects but does not fully cover the bbox', () => {
+      const contentBounds: Rect = { height: 100, width: 50, x: 0, y: 0 };
+      expect(detectCanvasMode(input({ bboxFullyCovered: false, contentBounds }))).toBe('outpaint');
+    });
+
+    it('counts a 1px interior overlap as intersecting → outpaint', () => {
+      // Content's left edge at x = 99: a 1px column overlaps the bbox interior.
+      const contentBounds: Rect = { height: 100, width: 50, x: 99, y: 0 };
+      expect(detectCanvasMode(input({ bboxFullyCovered: false, contentBounds }))).toBe('outpaint');
+    });
+
+    it('returns outpaint even with an active mask when coverage is incomplete', () => {
+      const contentBounds: Rect = { height: 100, width: 50, x: 0, y: 0 };
+      expect(detectCanvasMode(input({ bboxFullyCovered: false, contentBounds, hasActiveInpaintMask: true }))).toBe(
+        'outpaint'
+      );
+    });
+  });
+
+  describe('img2img', () => {
+    it('returns img2img when content fully covers the bbox and there is no mask', () => {
+      const contentBounds: Rect = { height: 100, width: 100, x: 0, y: 0 };
+      expect(detectCanvasMode(input({ bboxFullyCovered: true, contentBounds, hasActiveInpaintMask: false }))).toBe(
+        'img2img'
+      );
+    });
+
+    it('returns img2img when content extends past the bbox but covers it fully', () => {
+      const contentBounds: Rect = { height: 200, width: 200, x: -50, y: -50 };
+      expect(detectCanvasMode(input({ bboxFullyCovered: true, contentBounds }))).toBe('img2img');
+    });
+  });
+
+  describe('inpaint', () => {
+    it('returns inpaint when content fully covers the bbox and a mask is active', () => {
+      const contentBounds: Rect = { height: 100, width: 100, x: 0, y: 0 };
+      expect(detectCanvasMode(input({ bboxFullyCovered: true, contentBounds, hasActiveInpaintMask: true }))).toBe(
+        'inpaint'
+      );
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/canvasMode.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/canvasMode.ts
new file mode 100644
index 00000000000..d9ca60fb12a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/canvasMode.ts
@@ -0,0 +1,78 @@
+/**
+ * Pure canvas generation-mode detection.
+ *
+ * Given only plain geometry/coverage facts the engine + composite executor
+ * already computed, {@link detectCanvasMode} reproduces the legacy canvas
+ * behavior of picking txt2img / img2img / inpaint / outpaint. It touches no
+ * pixels and imports nothing from the engine — every input is precomputed and
+ * passed in, so the whole decision table is exhaustively node-testable.
+ *
+ * Rules (legacy parity):
+ * - No enabled raster content intersects the bbox → `txt2img`.
+ * - Content opaquely covers the whole bbox, no active inpaint mask → `img2img`.
+ * - Content opaquely covers the whole bbox, active inpaint mask → `inpaint`.
+ * - The bbox extends past content, or has transparent holes inside it (i.e.
+ *   content intersects but does not fully cover) → `outpaint`.
+ */
+
+import type { CanvasGenerationMode, Rect } from './types';
+
+/** The precomputed facts {@link detectCanvasMode} decides from. */
+export interface CanvasModeInput {
+  /** The generation bounding box, in document space. */
+  bbox: Rect;
+  /**
+   * Union of enabled raster-layer content bounds in document space, or `null`
+   * when no enabled raster content exists.
+   */
+  contentBounds: Rect | null;
+  /**
+   * Whether enabled raster content opaquely covers the entire bbox (no
+   * transparent holes) — the alpha scan of the composited bbox surface.
+   */
+  bboxFullyCovered: boolean;
+  /**
+   * Whether an enabled inpaint-mask layer with content exists. Always `false`
+   * in Phase 4.2 (the contract type exists but no mask is produced yet).
+   */
+  hasActiveInpaintMask: boolean;
+}
+
+/**
+ * True when two rects share interior area. Edge-touching or a shared corner is
+ * NOT an intersection (strict `<`), matching the engine's `rect.intersect`
+ * semantics, so a 1px edge overlap counts but a flush edge does not.
+ *
+ * Exported so the invoke orchestrator can run a bounds-only pre-pass: content
+ * that doesn't overlap the bbox means txt2img, which needs no composite upload.
+ */
+export const rectsIntersect = (a: Rect, b: Rect): boolean => {
+  if (a.width <= 0 || a.height <= 0 || b.width <= 0 || b.height <= 0) {
+    return false;
+  }
+  return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+};
+
+/** Resolves the generation mode for a canvas invoke from precomputed facts. */
+export const detectCanvasMode = (input: CanvasModeInput): CanvasGenerationMode => {
+  const { bbox, bboxFullyCovered, contentBounds, hasActiveInpaintMask } = input;
+
+  // A degenerate bbox can never contain content: nothing to reference.
+  if (bbox.width <= 0 || bbox.height <= 0) {
+    return 'txt2img';
+  }
+
+  // No enabled raster content touches the bbox: pure text-to-image.
+  if (!contentBounds || !rectsIntersect(contentBounds, bbox)) {
+    return 'txt2img';
+  }
+
+  // Content opaquely fills the whole bbox: img2img, or inpaint when masked.
+  if (bboxFullyCovered) {
+    return hasActiveInpaintMask ? 'inpaint' : 'img2img';
+  }
+
+  // Content intersects but leaves the bbox partly transparent (extends past
+  // content, or has holes): outpaint.
+  return 'outpaint';
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/compileCanvasGraph.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/compileCanvasGraph.test.ts
new file mode 100644
index 00000000000..d4f1bef1eb6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/compileCanvasGraph.test.ts
@@ -0,0 +1,749 @@
+import type {
+  ComponentModelConfig,
+  GenerateModelConfig,
+  GenerateSettings,
+  MainModelConfig,
+  VaeModelConfig,
+} from '@workbench/generation/types';
+import type { BackendGraphContract, ProjectSettings } from '@workbench/types';
+import type { CanvasCompositingSettings } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+
+import { getDefaultGenerateSettings } from '@workbench/generation/baseGenerationPolicies';
+import { DEFAULT_CANVAS_COMPOSITING } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+import { describe, expect, it } from 'vitest';
+
+import type { ControlLayerGraphInput } from './addControlLayers';
+import type { RegionalGuidanceInput } from './addRegionalGuidance';
+import type { CanvasCompileMode, Rect } from './types';
+
+import { compileCanvasGraph } from './compileCanvasGraph';
+
+const sd1Model: MainModelConfig = { base: 'sd-1', key: 'sd1-model', name: 'SD 1.5', type: 'main' };
+const sd2Model: MainModelConfig = { base: 'sd-2', key: 'sd2-model', name: 'SD 2', type: 'main' };
+const sdxlModel: MainModelConfig = { base: 'sdxl', key: 'sdxl-model', name: 'SDXL', type: 'main' };
+const sd3Model: MainModelConfig = { base: 'sd-3', key: 'sd3-model', name: 'SD3', type: 'main' };
+const fluxModel: MainModelConfig = { base: 'flux', key: 'flux-model', name: 'FLUX dev', type: 'main' };
+const flux2Model: MainModelConfig = {
+  base: 'flux2',
+  format: 'diffusers',
+  key: 'flux2-model',
+  name: 'FLUX.2',
+  type: 'main',
+};
+const cogView4Model: MainModelConfig = { base: 'cogview4', key: 'cog-model', name: 'CogView4', type: 'main' };
+const qwenImageModel: MainModelConfig = {
+  base: 'qwen-image',
+  format: 'diffusers',
+  key: 'qwen-model',
+  name: 'Qwen Image',
+  type: 'main',
+};
+const zImageModel: MainModelConfig = {
+  base: 'z-image',
+  format: 'diffusers',
+  key: 'z-model',
+  name: 'Z-Image',
+  type: 'main',
+};
+const animaModel: MainModelConfig = { base: 'anima', key: 'anima-model', name: 'Anima', type: 'main' };
+const externalModel: GenerateModelConfig = {
+  base: 'external',
+  capabilities: { modes: ['txt2img'], supports_seed: true },
+  format: 'external_api',
+  key: 'external-model',
+  name: 'OpenAI Image',
+  provider_id: 'openai',
+  type: 'external_image_generator',
+};
+
+const fluxVae: VaeModelConfig = { base: 'flux', key: 'flux-vae', name: 'FLUX VAE', type: 'vae' };
+const qwenImageVae: VaeModelConfig = { base: 'qwen-image', key: 'qwen-vae', name: 'Qwen VAE', type: 'vae' };
+const t5Encoder: ComponentModelConfig = { base: 'any', key: 't5', name: 'T5 Encoder', type: 't5_encoder' };
+const clipEmbed: ComponentModelConfig = { base: 'any', key: 'clip', name: 'CLIP Embed', type: 'clip_embed' };
+const qwen3Encoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'qwen3',
+  name: 'Qwen3 Encoder',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_06b',
+};
+
+const PROJECT_SETTINGS: Pick<ProjectSettings, 'useCpuNoise'> = { useCpuNoise: true };
+
+const settingsFor = (model: GenerateModelConfig, overrides: Partial<GenerateSettings> = {}): GenerateSettings => ({
+  ...getDefaultGenerateSettings(model),
+  seed: 1,
+  shouldRandomizeSeed: false,
+  ...overrides,
+});
+
+/** Per-base overrides needed to pass component validation. */
+const COMPONENT_OVERRIDES: Partial<Record<string, Partial<GenerateSettings>>> = {
+  flux: { clipEmbedModel: clipEmbed, t5EncoderModel: t5Encoder, vae: fluxVae },
+  anima: { qwen3EncoderModel: qwen3Encoder, vae: qwenImageVae },
+};
+
+const bbox: Rect = { height: 1024, width: 768, x: 128, y: 64 };
+
+const compile = (
+  model: GenerateModelConfig,
+  mode: CanvasCompileMode,
+  overrides: {
+    settings?: Partial<GenerateSettings>;
+    bbox?: Rect;
+    compositeImageName?: string | null;
+    maskImageName?: string | null;
+    noiseMaskImageName?: string | null;
+    compositing?: Partial<CanvasCompositingSettings>;
+    strength?: number;
+    destination?: 'canvas' | 'gallery';
+    controlLayers?: readonly ControlLayerGraphInput[];
+    regionalGuidance?: readonly RegionalGuidanceInput[];
+  } = {}
+) =>
+  compileCanvasGraph({
+    bbox: overrides.bbox ?? bbox,
+    compositeImageName:
+      'compositeImageName' in overrides ? (overrides.compositeImageName ?? null) : 'canvas-composite.png',
+    compositing: overrides.compositing
+      ? { ...DEFAULT_CANVAS_COMPOSITING, ...overrides.compositing }
+      : DEFAULT_CANVAS_COMPOSITING,
+    controlLayers: overrides.controlLayers,
+    regionalGuidance: overrides.regionalGuidance,
+    destination: overrides.destination ?? 'canvas',
+    maskImageName:
+      'maskImageName' in overrides ? overrides.maskImageName : mode === 'inpaint' ? 'canvas-mask.png' : null,
+    mode,
+    model,
+    noiseMaskImageName: overrides.noiseMaskImageName ?? null,
+    projectSettings: PROJECT_SETTINGS,
+    settings: settingsFor(model, {
+      ...COMPONENT_OVERRIDES[model.base],
+      ...overrides.settings,
+    }),
+    strength: overrides.strength ?? 0.6,
+  });
+
+const getEdge = (graph: BackendGraphContract, targetNodeId: string, targetField: string) =>
+  graph.edges.find((edge) => edge.destination.node_id === targetNodeId && edge.destination.field === targetField);
+
+const getNodeByType = (graph: BackendGraphContract, type: string) =>
+  Object.values(graph.nodes).find((node) => node.type === type);
+
+interface BaseCase {
+  model: MainModelConfig;
+  encodeType: string;
+  outputType: string;
+  denoiseType: string;
+  txt2imgMode: string;
+  img2imgMode: string;
+  /** sd-3 / flux / flux2 rescale strength with an exponent of 0.2 (legacy parity). */
+  optimizedDenoising: boolean;
+}
+
+/** Legacy-equivalent denoising_start for a strength on a given base. */
+const expectedDenoisingStart = (strength: number, optimizedDenoising: boolean): number =>
+  1 - strength ** (optimizedDenoising ? 0.2 : 1);
+
+const BASE_CASES: BaseCase[] = [
+  {
+    model: sd1Model,
+    encodeType: 'i2l',
+    outputType: 'l2i',
+    denoiseType: 'denoise_latents',
+    txt2imgMode: 'txt2img',
+    img2imgMode: 'img2img',
+    optimizedDenoising: false,
+  },
+  {
+    model: sd2Model,
+    encodeType: 'i2l',
+    outputType: 'l2i',
+    denoiseType: 'denoise_latents',
+    txt2imgMode: 'txt2img',
+    img2imgMode: 'img2img',
+    optimizedDenoising: false,
+  },
+  {
+    model: sdxlModel,
+    encodeType: 'i2l',
+    outputType: 'l2i',
+    denoiseType: 'denoise_latents',
+    txt2imgMode: 'sdxl_txt2img',
+    img2imgMode: 'sdxl_img2img',
+    optimizedDenoising: false,
+  },
+  {
+    model: sd3Model,
+    encodeType: 'sd3_i2l',
+    outputType: 'sd3_l2i',
+    denoiseType: 'sd3_denoise',
+    txt2imgMode: 'sd3_txt2img',
+    img2imgMode: 'sd3_img2img',
+    optimizedDenoising: true,
+  },
+  {
+    model: fluxModel,
+    encodeType: 'flux_vae_encode',
+    outputType: 'flux_vae_decode',
+    denoiseType: 'flux_denoise',
+    txt2imgMode: 'flux_txt2img',
+    img2imgMode: 'flux_img2img',
+    optimizedDenoising: true,
+  },
+  {
+    model: flux2Model,
+    encodeType: 'flux2_vae_encode',
+    outputType: 'flux2_vae_decode',
+    denoiseType: 'flux2_denoise',
+    txt2imgMode: 'flux2_txt2img',
+    img2imgMode: 'flux2_img2img',
+    optimizedDenoising: true,
+  },
+  {
+    model: cogView4Model,
+    encodeType: 'cogview4_i2l',
+    outputType: 'cogview4_l2i',
+    denoiseType: 'cogview4_denoise',
+    txt2imgMode: 'cogview4_txt2img',
+    img2imgMode: 'cogview4_img2img',
+    optimizedDenoising: false,
+  },
+  {
+    model: qwenImageModel,
+    encodeType: 'qwen_image_i2l',
+    outputType: 'qwen_image_l2i',
+    denoiseType: 'qwen_image_denoise',
+    txt2imgMode: 'qwen_image_txt2img',
+    img2imgMode: 'qwen_image_img2img',
+    optimizedDenoising: false,
+  },
+  {
+    model: zImageModel,
+    encodeType: 'z_image_i2l',
+    outputType: 'z_image_l2i',
+    denoiseType: 'z_image_denoise',
+    txt2imgMode: 'z_image_txt2img',
+    img2imgMode: 'z_image_img2img',
+    optimizedDenoising: false,
+  },
+  {
+    model: animaModel,
+    encodeType: 'anima_i2l',
+    outputType: 'anima_l2i',
+    denoiseType: 'anima_denoise',
+    txt2imgMode: 'anima_txt2img',
+    img2imgMode: 'anima_img2img',
+    optimizedDenoising: false,
+  },
+];
+
+describe('compileCanvasGraph', () => {
+  describe('txt2img per base', () => {
+    it.each(BASE_CASES)(
+      'builds a $model.base txt2img graph sized to the bbox',
+      ({ model, outputType, txt2imgMode }) => {
+        const { backendGraph, graph, mode } = compile(model, 'txt2img');
+
+        // No img2img encode node in a pure txt2img graph.
+        expect(getNodeByType(backendGraph, 'i2l')).toBeUndefined();
+        expect(getNodeByType(backendGraph, `${model.base}_i2l`)).toBeUndefined();
+        expect(getNodeByType(backendGraph, `${model.base}_vae_encode`)).toBeUndefined();
+
+        // Canvas destination: intermediate output of the base builder's decode type.
+        expect(backendGraph.nodes.canvas_output?.type).toBe(outputType);
+        expect(backendGraph.nodes.canvas_output?.is_intermediate).toBe(true);
+
+        // Deterministic prompt/seed node ids are present.
+        expect(backendGraph.nodes.positive_prompt).toBeDefined();
+        expect(backendGraph.nodes.seed).toBeDefined();
+
+        // Dimensions come from the bbox, not the settings.
+        expect(getNodeByType(backendGraph, 'core_metadata')?.width).toBe(bbox.width);
+        expect(getNodeByType(backendGraph, 'core_metadata')?.height).toBe(bbox.height);
+        expect(getNodeByType(backendGraph, 'core_metadata')?.generation_mode).toBe(txt2imgMode);
+
+        expect(mode).toBe('txt2img');
+        expect(graph.label).toBe(`${model.name} txt2img`);
+      }
+    );
+
+    it('applies bbox dimensions to the SD noise node', () => {
+      const { backendGraph } = compile(sd1Model, 'txt2img');
+
+      expect(backendGraph.nodes.noise?.width).toBe(bbox.width);
+      expect(backendGraph.nodes.noise?.height).toBe(bbox.height);
+    });
+
+    it('produces a durable (non-intermediate) output for a Gallery destination', () => {
+      // Canvas destination stages an intermediate; Gallery must be a durable image.
+      expect(compile(sd1Model, 'txt2img').backendGraph.nodes.canvas_output?.is_intermediate).toBe(true);
+      expect(
+        compile(sd1Model, 'txt2img', { destination: 'gallery' }).backendGraph.nodes.canvas_output?.is_intermediate
+      ).toBe(false);
+    });
+
+    it('applies bbox dimensions to a flow-model denoise node', () => {
+      const { backendGraph } = compile(fluxModel, 'txt2img');
+
+      expect(backendGraph.nodes.denoise_latents?.width).toBe(bbox.width);
+      expect(backendGraph.nodes.denoise_latents?.height).toBe(bbox.height);
+    });
+  });
+
+  describe('img2img per base', () => {
+    it.each(BASE_CASES)(
+      'grafts a $model.base image-to-latents encode node',
+      ({ model, encodeType, denoiseType, img2imgMode, optimizedDenoising }) => {
+        const { backendGraph, mode } = compile(model, 'img2img', { strength: 0.6 });
+
+        const encode = getNodeByType(backendGraph, encodeType);
+        expect(encode).toBeDefined();
+        expect(encode?.image).toEqual({ image_name: 'canvas-composite.png' });
+
+        // image → encode → denoise.latents
+        expect(getEdge(backendGraph, encode!.id, 'vae')).toBeDefined();
+        expect(getEdge(backendGraph, 'denoise_latents', 'latents')?.source.node_id).toBe(encode?.id);
+
+        // denoising_start follows the base's strength curve (linear, or the
+        // exponent-0.2 optimized curve for sd-3 / flux / flux2).
+        expect(backendGraph.nodes.denoise_latents?.type).toBe(denoiseType);
+        expect(backendGraph.nodes.denoise_latents?.denoising_start).toBeCloseTo(
+          expectedDenoisingStart(0.6, optimizedDenoising),
+          10
+        );
+        expect(backendGraph.nodes.denoise_latents?.denoising_end).toBe(1);
+
+        // metadata reflects the img2img mode + strength.
+        const metadata = getNodeByType(backendGraph, 'core_metadata');
+        expect(metadata?.generation_mode).toBe(img2imgMode);
+        expect(metadata?.strength).toBe(0.6);
+
+        expect(mode).toBe('img2img');
+      }
+    );
+
+    it('feeds the encode node from the same VAE source as the decode node', () => {
+      const { backendGraph } = compile(sd1Model, 'img2img');
+      const encode = getNodeByType(backendGraph, 'i2l');
+      const decodeVaeSource = getEdge(backendGraph, 'canvas_output', 'vae')?.source.node_id;
+      const encodeVaeSource = getEdge(backendGraph, encode!.id, 'vae')?.source.node_id;
+
+      expect(encodeVaeSource).toBe(decodeVaeSource);
+      expect(encodeVaeSource).toBe('model_loader');
+    });
+
+    it('routes the encode VAE through the seamless node when tiling is enabled', () => {
+      const { backendGraph } = compile(sd1Model, 'img2img', { settings: { seamlessXAxis: true } });
+      const encode = getNodeByType(backendGraph, 'i2l');
+
+      expect(getEdge(backendGraph, encode!.id, 'vae')?.source.node_id).toBe('seamless');
+    });
+
+    it('mirrors the decode precision onto the SD encode node', () => {
+      const fp16 = compile(sd1Model, 'img2img', { settings: { vaePrecision: 'fp16' } });
+      expect(getNodeByType(fp16.backendGraph, 'i2l')?.fp32).toBe(false);
+
+      const fp32 = compile(sd1Model, 'img2img', { settings: { vaePrecision: 'fp32' } });
+      expect(getNodeByType(fp32.backendGraph, 'i2l')?.fp32).toBe(true);
+    });
+
+    it('does not attach fp32 to non-SD encode nodes', () => {
+      const { backendGraph } = compile(fluxModel, 'img2img');
+
+      expect(getNodeByType(backendGraph, 'flux_vae_encode')?.fp32).toBeUndefined();
+    });
+
+    it('threads the composite image name into the encode node', () => {
+      const { backendGraph } = compile(sdxlModel, 'img2img', { compositeImageName: 'my-upload.png' });
+
+      expect(getNodeByType(backendGraph, 'i2l')?.image).toEqual({ image_name: 'my-upload.png' });
+    });
+
+    it('reflects strength in denoising_start', () => {
+      const { backendGraph } = compile(sd1Model, 'img2img', { strength: 0.25 });
+
+      expect(backendGraph.nodes.denoise_latents?.denoising_start).toBeCloseTo(0.75, 10);
+    });
+
+    it.each([sd3Model, fluxModel, flux2Model])(
+      'rescales strength with the optimized (exponent-0.2) curve for $base',
+      (model) => {
+        const { backendGraph } = compile(model, 'img2img', { strength: 0.75 });
+
+        // Legacy parity: 1 - 0.75 ** 0.2 ≈ 0.056 (not the linear 0.25).
+        expect(backendGraph.nodes.denoise_latents?.denoising_start).toBeCloseTo(1 - 0.75 ** 0.2, 10);
+      }
+    );
+  });
+
+  describe('unsupported models', () => {
+    it('rejects external image generators for txt2img', () => {
+      expect(() => compile(externalModel, 'txt2img')).toThrow('does not support canvas generation');
+    });
+
+    it('rejects external image generators for img2img', () => {
+      expect(() => compile(externalModel, 'img2img')).toThrow('does not support canvas generation');
+    });
+  });
+
+  describe('validation', () => {
+    it('rejects img2img without a composite image', () => {
+      expect(() => compile(sd1Model, 'img2img', { compositeImageName: null })).toThrow(
+        'Canvas generation requires a composited source image.'
+      );
+    });
+
+    it('rejects a strength of zero', () => {
+      expect(() => compile(sd1Model, 'img2img', { strength: 0 })).toThrow(
+        'Canvas denoising strength must be greater than 0 and at most 1.'
+      );
+    });
+
+    it('rejects a strength above one', () => {
+      expect(() => compile(sd1Model, 'img2img', { strength: 1.5 })).toThrow(
+        'Canvas denoising strength must be greater than 0 and at most 1.'
+      );
+    });
+
+    it('accepts a strength of exactly one', () => {
+      const { backendGraph } = compile(sd1Model, 'img2img', { strength: 1 });
+
+      expect(backendGraph.nodes.denoise_latents?.denoising_start).toBe(0);
+    });
+
+    it('rejects a zero-area bbox', () => {
+      expect(() => compile(sd1Model, 'txt2img', { bbox: { height: 0, width: 512, x: 0, y: 0 } })).toThrow(
+        'Canvas bounding box must have a positive area.'
+      );
+    });
+
+    it('rejects off-grid bbox dimensions', () => {
+      expect(() => compile(flux2Model, 'txt2img', { bbox: { height: 888, width: 1024, x: 0, y: 0 } })).toThrow(
+        'Generate height must be a multiple of 16.'
+      );
+    });
+
+    it('surfaces missing-component validation for the bbox-sized settings', () => {
+      // FLUX with no component overrides fails the shared generate validation.
+      expect(() =>
+        compileCanvasGraph({
+          bbox,
+          compositeImageName: null,
+          destination: 'canvas',
+          mode: 'txt2img',
+          model: fluxModel,
+          projectSettings: PROJECT_SETTINGS,
+          settings: settingsFor(fluxModel),
+          strength: 0.6,
+        })
+      ).toThrow('Generate needs a T5 Encoder for FLUX models.');
+    });
+  });
+});
+
+describe('compileCanvasGraph — inpaint per base', () => {
+  it.each(BASE_CASES)(
+    'grafts a $model.base inpaint pipeline (encode, gradient mask, blend composite-back)',
+    ({ model, encodeType, outputType, denoiseType, txt2imgMode, optimizedDenoising }) => {
+      const { backendGraph, mode } = compile(model, 'inpaint', { strength: 0.6 });
+      expect(mode).toBe('inpaint');
+
+      // Encode fed by the initial composite image → denoise.latents.
+      const encode = getNodeByType(backendGraph, encodeType);
+      expect(encode).toBeDefined();
+      expect(encode?.image).toEqual({ image_name: 'canvas-composite.png' });
+      expect(getEdge(backendGraph, 'denoise_latents', 'latents')?.source.node_id).toBe(encode?.id);
+
+      // create_gradient_mask carries coherence params + the mask image, and feeds denoise_mask.
+      const gradient = backendGraph.nodes.create_gradient_mask;
+      expect(gradient?.type).toBe('create_gradient_mask');
+      expect(gradient?.coherence_mode).toBe('Gaussian Blur');
+      expect(gradient?.edge_radius).toBe(16);
+      expect(gradient?.minimum_denoise).toBe(0);
+      expect(gradient?.image).toEqual({ image_name: 'canvas-composite.png' });
+      expect(gradient?.mask).toEqual({ image_name: 'canvas-mask.png' });
+      expect(getEdge(backendGraph, 'denoise_latents', 'denoise_mask')?.source.node_id).toBe('create_gradient_mask');
+
+      // fp32 only on the SD gradient mask (mirrors the SD i2l).
+      expect(gradient?.fp32).toBe(encodeType === 'i2l');
+
+      // The base decode is demoted to an intermediate canvas_l2i; the blend is canvas_output.
+      expect(backendGraph.nodes.canvas_l2i?.type).toBe(outputType);
+      expect(backendGraph.nodes.canvas_l2i?.is_intermediate).toBe(true);
+      const blend = backendGraph.nodes.canvas_output;
+      expect(blend?.type).toBe('invokeai_img_blend');
+      expect(blend?.is_intermediate).toBe(true);
+      expect(blend?.layer_base).toEqual({ image_name: 'canvas-composite.png' });
+      expect(getEdge(backendGraph, 'canvas_output', 'layer_upper')?.source.node_id).toBe('canvas_l2i');
+
+      // expand_mask_with_fade uses the mask blur and feeds the blend mask.
+      expect(backendGraph.nodes.expand_mask?.type).toBe('expand_mask_with_fade');
+      expect(backendGraph.nodes.expand_mask?.fade_size_px).toBe(16);
+      expect(getEdge(backendGraph, 'expand_mask', 'mask')?.source.node_id).toBe('create_gradient_mask');
+      expect(getEdge(backendGraph, 'canvas_output', 'mask')?.source.node_id).toBe('expand_mask');
+
+      // Strength curve + metadata mode.
+      expect(backendGraph.nodes.denoise_latents?.type).toBe(denoiseType);
+      expect(backendGraph.nodes.denoise_latents?.denoising_start).toBeCloseTo(
+        expectedDenoisingStart(0.6, optimizedDenoising)
+      );
+      const metadata = getNodeByType(backendGraph, 'core_metadata');
+      expect(metadata?.generation_mode).toBe(txt2imgMode.replace('txt2img', 'inpaint'));
+      expect(metadata?.strength).toBe(0.6);
+    }
+  );
+
+  it('re-points core_metadata onto the final blend output (not the intermediate decode)', () => {
+    const { backendGraph } = compile(sd1Model, 'inpaint');
+    const metadata = getNodeByType(backendGraph, 'core_metadata')!;
+    const metaEdge = backendGraph.edges.find(
+      (edge) => edge.source.node_id === metadata.id && edge.destination.field === 'metadata'
+    );
+    expect(metaEdge?.destination.node_id).toBe('canvas_output');
+  });
+
+  it('wires a UNet edge into create_gradient_mask only for SD-family models', () => {
+    const sd = compile(sd1Model, 'inpaint').backendGraph;
+    expect(getEdge(sd, 'create_gradient_mask', 'unet')).toBeDefined();
+    const flux = compile(fluxModel, 'inpaint').backendGraph;
+    expect(getEdge(flux, 'create_gradient_mask', 'unet')).toBeUndefined();
+  });
+
+  it('inserts an img_noise node before encode when a noise mask is present', () => {
+    const { backendGraph } = compile(sd1Model, 'inpaint', { noiseMaskImageName: 'noise.png' });
+    const noise = backendGraph.nodes.add_inpaint_noise;
+    expect(noise?.type).toBe('img_noise');
+    expect(noise?.image).toEqual({ image_name: 'canvas-composite.png' });
+    expect(noise?.mask).toEqual({ image_name: 'noise.png' });
+    expect(getEdge(backendGraph, 'add_inpaint_noise', 'seed')?.source.node_id).toBe('seed');
+    // noise → i2l.image
+    expect(getEdge(backendGraph, 'canvas_i2l', 'image')?.source.node_id).toBe('add_inpaint_noise');
+  });
+
+  it('feeds the composite directly into i2l when there is no noise mask', () => {
+    const { backendGraph } = compile(sd1Model, 'inpaint');
+    expect(backendGraph.nodes.add_inpaint_noise).toBeUndefined();
+    expect(backendGraph.nodes.canvas_i2l?.image).toEqual({ image_name: 'canvas-composite.png' });
+  });
+
+  it('rejects inpaint without a mask image', () => {
+    expect(() => compile(sd1Model, 'inpaint', { maskImageName: null })).toThrow(
+      'Canvas inpainting requires an inpaint mask.'
+    );
+  });
+
+  it('produces a durable blend output for a Gallery destination', () => {
+    expect(
+      compile(sd1Model, 'inpaint', { destination: 'gallery' }).backendGraph.nodes.canvas_output?.is_intermediate
+    ).toBe(false);
+  });
+});
+
+describe('compileCanvasGraph — outpaint per base', () => {
+  it.each(BASE_CASES)('grafts a $model.base outpaint pipeline (infill + alpha mask)', ({ model, txt2imgMode }) => {
+    const { backendGraph, mode } = compile(model, 'outpaint', { maskImageName: null });
+    expect(mode).toBe('outpaint');
+
+    // Infill applied to the initial image (default method: lama).
+    const infill = backendGraph.nodes.infill;
+    expect(infill?.type).toBe('infill_lama');
+    expect(infill?.image).toEqual({ image_name: 'canvas-composite.png' });
+
+    // Mask derived from the raster alpha (tomask) → gradient mask (no inpaint mask present).
+    expect(backendGraph.nodes.image_alpha_to_mask?.type).toBe('tomask');
+    expect(getEdge(backendGraph, 'create_gradient_mask', 'mask')?.source.node_id).toBe('image_alpha_to_mask');
+
+    // infill → i2l.image
+    expect(getEdge(backendGraph, 'canvas_i2l', 'image')?.source.node_id).toBe('infill');
+
+    // Composite-back blend claims canvas_output.
+    expect(backendGraph.nodes.canvas_output?.type).toBe('invokeai_img_blend');
+    expect(getNodeByType(backendGraph, 'core_metadata')?.generation_mode).toBe(
+      txt2imgMode.replace('txt2img', 'outpaint')
+    );
+  });
+
+  it('combines the inpaint mask with the raster alpha when a mask image is present', () => {
+    const { backendGraph } = compile(sd1Model, 'outpaint', { maskImageName: 'canvas-mask.png' });
+    const combine = backendGraph.nodes.mask_combine;
+    expect(combine?.type).toBe('mask_combine');
+    expect(combine?.mask1).toEqual({ image_name: 'canvas-mask.png' });
+    expect(getEdge(backendGraph, 'mask_combine', 'mask2')?.source.node_id).toBe('image_alpha_to_mask');
+    expect(getEdge(backendGraph, 'create_gradient_mask', 'mask')?.source.node_id).toBe('mask_combine');
+  });
+
+  it.each([
+    ['patchmatch', 'infill_patchmatch'],
+    ['lama', 'infill_lama'],
+    ['cv2', 'infill_cv2'],
+    ['tile', 'infill_tile'],
+    ['color', 'infill_rgba'],
+  ] as const)('uses the %s infill node', (method, nodeType) => {
+    const { backendGraph } = compile(sd1Model, 'outpaint', {
+      maskImageName: null,
+      compositing: { infillMethod: method },
+    });
+    expect(backendGraph.nodes.infill?.type).toBe(nodeType);
+  });
+
+  it('threads infill sub-params (tile size, patchmatch downscale, color)', () => {
+    const tile = compile(sd1Model, 'outpaint', {
+      maskImageName: null,
+      compositing: { infillMethod: 'tile', infillTileSize: 64 },
+    }).backendGraph;
+    expect(tile.nodes.infill?.tile_size).toBe(64);
+
+    const patch = compile(sd1Model, 'outpaint', {
+      maskImageName: null,
+      compositing: { infillMethod: 'patchmatch', infillPatchmatchDownscaleSize: 3 },
+    }).backendGraph;
+    expect(patch.nodes.infill?.downscale).toBe(3);
+
+    const color = compile(sd1Model, 'outpaint', {
+      maskImageName: null,
+      compositing: { infillMethod: 'color', infillColorValue: { r: 10, g: 20, b: 30, a: 1 } },
+    }).backendGraph;
+    expect(color.nodes.infill?.color).toEqual({ r: 10, g: 20, b: 30, a: 255 });
+  });
+
+  it('threads coherence + mask-blur settings into the outpaint gradient/expand nodes', () => {
+    const { backendGraph } = compile(sd1Model, 'outpaint', {
+      maskImageName: null,
+      compositing: { coherenceMode: 'Staged', coherenceEdgeSize: 8, coherenceMinDenoise: 0.3, maskBlur: 24 },
+    });
+    expect(backendGraph.nodes.create_gradient_mask?.coherence_mode).toBe('Staged');
+    expect(backendGraph.nodes.create_gradient_mask?.edge_radius).toBe(8);
+    expect(backendGraph.nodes.create_gradient_mask?.minimum_denoise).toBe(0.3);
+    expect(backendGraph.nodes.expand_mask?.fade_size_px).toBe(24);
+  });
+
+  it('rejects an external model for every image mode', () => {
+    expect(() => compile(externalModel, 'outpaint', { maskImageName: null })).toThrow(
+      'does not support canvas generation'
+    );
+  });
+});
+
+// Review fix (Task 38, finding 2): `addControlLayers` has its own isolated unit
+// coverage (addControlLayers.test.ts), but nothing previously drove control
+// layers through the REAL `compileCanvasGraph` entry point — so a wiring
+// regression at the seam between the two (e.g. the wrong denoise node id, or a
+// base graph that no longer exposes `denoise_latents`) could pass every
+// existing test here while breaking a real canvas invoke.
+describe('compileCanvasGraph — control layers (integration)', () => {
+  const controlNetLayer: ControlLayerGraphInput = {
+    beginEndStepPct: [0.1, 0.85],
+    controlMode: 'more_control',
+    id: 'control-layer-1',
+    imageName: 'control-composite.png',
+    kind: 'controlnet',
+    model: { base: 'sd-1', key: 'canny-controlnet', name: 'Canny ControlNet', type: 'controlnet' },
+    weight: 0.65,
+  };
+
+  it('grafts an enabled control layer through a real compiled canvas graph: control node args, collector → denoise.control wiring, base graph intact', () => {
+    const { backendGraph, graph, mode } = compile(sd1Model, 'img2img', { controlLayers: [controlNetLayer] });
+
+    expect(mode).toBe('img2img');
+
+    // The control node carries the resolved model/weight/begin-end/mode args.
+    const controlNode = backendGraph.nodes['control_net_control-layer-1'];
+    expect(controlNode?.type).toBe('controlnet');
+    expect(controlNode?.control_model).toEqual(controlNetLayer.model);
+    expect(controlNode?.control_weight).toBe(0.65);
+    expect(controlNode?.begin_step_percent).toBe(0.1);
+    expect(controlNode?.end_step_percent).toBe(0.85);
+    expect(controlNode?.control_mode).toBe('more_control');
+    expect(controlNode?.image).toEqual({ image_name: 'control-composite.png' });
+
+    // The control node feeds the collector, whose own output is what
+    // `denoise_latents.control` actually reads.
+    expect(backendGraph.nodes.control_net_collector?.type).toBe('collect');
+    expect(getEdge(backendGraph, 'control_net_collector', 'item')?.source.node_id).toBe('control_net_control-layer-1');
+    expect(getEdge(backendGraph, 'denoise_latents', 'control')?.source.node_id).toBe('control_net_collector');
+
+    // The base img2img graph is untouched by the control graft: prompts, seed,
+    // the encode → denoise plumbing, and the composite-back output are all
+    // still present and wired exactly as they would be with no control layers.
+    expect(backendGraph.nodes.positive_prompt).toBeDefined();
+    expect(backendGraph.nodes.negative_prompt).toBeDefined();
+    expect(backendGraph.nodes.seed).toBeDefined();
+    expect(backendGraph.nodes.canvas_i2l?.type).toBe('i2l');
+    expect(getEdge(backendGraph, 'denoise_latents', 'latents')?.source.node_id).toBe('canvas_i2l');
+    expect(backendGraph.nodes.canvas_output).toBeDefined();
+    expect(graph.label).toBe(`${sd1Model.name} img2img`);
+  });
+
+  it('grafts a Z-Image control into the real Z-Image base graph', () => {
+    const layer: ControlLayerGraphInput = {
+      beginEndStepPct: [0, 1],
+      controlMode: null,
+      id: 'z-control',
+      imageName: 'z-control.png',
+      kind: 'z_image_control',
+      model: { base: 'z-image', key: 'z-control-model', name: 'Z Control', type: 'controlnet' },
+      weight: 0.75,
+    };
+
+    const { backendGraph } = compile(zImageModel, 'txt2img', { controlLayers: [layer] });
+
+    expect(backendGraph.nodes.denoise_latents?.type).toBe('z_image_denoise');
+    expect(backendGraph.nodes['z_image_control_z-control']).toMatchObject({
+      control_context_scale: 0.75,
+      control_model: layer.model,
+      image: { image_name: 'z-control.png' },
+      type: 'z_image_control',
+    });
+    expect(getEdge(backendGraph, 'denoise_latents', 'control')?.source).toEqual({
+      field: 'control',
+      node_id: 'z_image_control_z-control',
+    });
+  });
+});
+
+describe('compileCanvasGraph — regional guidance', () => {
+  const region = (id: string, overrides: Partial<RegionalGuidanceInput> = {}) => ({
+    autoNegative: false,
+    id,
+    maskImageName: `${id}-mask.png`,
+    negativePrompt: null,
+    positivePrompt: 'a cat',
+    referenceImages: [],
+    ...overrides,
+  });
+
+  it('grafts SD1 regional conditioning into the pos/neg collectors', () => {
+    const { backendGraph } = compile(sd1Model, 'txt2img', {
+      regionalGuidance: [region('r1', { autoNegative: true })],
+    });
+    expect(backendGraph.nodes.rg_mask_to_tensor_r1).toBeDefined();
+    expect(backendGraph.nodes.rg_pos_cond_r1?.prompt).toBe('a cat');
+    // autoNegative inverted-mask node feeding the negative collector.
+    expect(backendGraph.nodes.rg_invert_mask_r1).toBeDefined();
+    expect(backendGraph.nodes.rg_pos_cond_inverted_r1).toBeDefined();
+  });
+
+  it('is a no-op for an unsupported base (sd-2)', () => {
+    const { backendGraph } = compile(sd2Model, 'txt2img', { regionalGuidance: [region('r1')] });
+    expect(backendGraph.nodes.rg_mask_to_tensor_r1).toBeUndefined();
+  });
+
+  it('coexists with control layers in one graph', () => {
+    const control: ControlLayerGraphInput = {
+      beginEndStepPct: [0, 0.75],
+      controlMode: 'balanced',
+      id: 'c1',
+      imageName: 'control.png',
+      kind: 'controlnet',
+      model: { base: 'sd-1', key: 'cn', name: 'CN', type: 'controlnet' },
+      weight: 1,
+    };
+    const { backendGraph } = compile(sd1Model, 'txt2img', {
+      controlLayers: [control],
+      regionalGuidance: [region('r1')],
+    });
+    expect(backendGraph.nodes.control_net_c1).toBeDefined();
+    expect(backendGraph.nodes.rg_pos_cond_r1).toBeDefined();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/compileCanvasGraph.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/compileCanvasGraph.ts
new file mode 100644
index 00000000000..064fd39ed49
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/compileCanvasGraph.ts
@@ -0,0 +1,544 @@
+/**
+ * Pure canvas generation-graph compiler.
+ *
+ * {@link compileCanvasGraph} builds the backend graph a canvas invoke submits by
+ * grafting image-to-image plumbing onto the existing per-base txt2img builders
+ * (`../graph.ts`). It is deliberately pure: no fetch, no engine imports, no
+ * React. The executor (Task 16) has already composited + uploaded the bbox
+ * source image and passes its name in; this module only shapes nodes/edges.
+ *
+ * ## Grafting strategy
+ *
+ * 1. Build the base txt2img graph via `GRAPH_BUILDERS[model.base]` with the
+ *    canvas destination (`outputIsIntermediate = true`) and a settings copy whose
+ *    width/height are the bbox size (builders read dims from settings).
+ * 2. For `img2img`, add a base-appropriate image-to-latents encode node fed by
+ *    the composite image + the graph's VAE source, wire its latents into
+ *    `denoise_latents.latents`, and set `denoising_start = 1 - strength`.
+ * 3. Update `core_metadata` (`generation_mode` → the `img2img` variant, plus
+ *    `strength`).
+ *
+ * Every base in `GRAPH_BUILDERS` has a backend image-to-latents node, so all ten
+ * families support img2img (see `CANVAS_I2L_NODE_TYPES`). External image
+ * generators have no latent img2img path and are rejected for every canvas mode.
+ */
+
+import type { SupportedGenerateBase } from '@workbench/generation/baseGenerationPolicies';
+import type { GenerateModelConfig, GenerateSettings } from '@workbench/generation/types';
+import type { BackendGraphContract, BackendInvocationContract } from '@workbench/types';
+import type { CanvasCompositingSettings, CanvasInfillMethod } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+
+import { getGenerationValidationReasons } from '@workbench/generation/baseGenerationPolicies';
+import { GRAPH_BUILDERS } from '@workbench/generation/graph';
+import { addEdge, addNode, toGraphContract } from '@workbench/generation/graphBuilder';
+import { DEFAULT_CANVAS_COMPOSITING } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+
+import type { CompileCanvasGraphInput, CompiledCanvasGraph } from './types';
+
+import { addControlLayers } from './addControlLayers';
+import { addRegionalGuidance, isRegionalGuidanceSupportedForBase } from './addRegionalGuidance';
+
+/**
+ * The backend image-to-latents (encode) node type per supported base. sd-1 /
+ * sd-2 / sdxl share the SD `i2l` node. Evidence: `invokeai/app/invocations/`
+ * and the legacy per-base builders under
+ * `features/nodes/util/graph/generation/`.
+ */
+const CANVAS_I2L_NODE_TYPES: Record<SupportedGenerateBase, string> = {
+  'sd-1': 'i2l',
+  'sd-2': 'i2l',
+  sdxl: 'i2l',
+  'sd-3': 'sd3_i2l',
+  flux: 'flux_vae_encode',
+  flux2: 'flux2_vae_encode',
+  cogview4: 'cogview4_i2l',
+  'qwen-image': 'qwen_image_i2l',
+  'z-image': 'z_image_i2l',
+  anima: 'anima_i2l',
+};
+
+/**
+ * The `denoising_start` for a canvas img2img graft, mirroring legacy
+ * `getDenoisingStartAndEnd` (web `graphBuilderUtils.ts`):
+ * - sd-3 / flux / flux2 rescale strength with an exponent of 0.2 so the slider's
+ *   full (0, 1] range is usable — without it nearly all perceptible change is
+ *   crammed into strength > 0.9 (e.g. strength 0.75 → start 0.056, not 0.25).
+ * - A FLUX Fill model (`flux` / `dev_fill`) always denoises fully (start = 0).
+ * - Every other base stays linear (`start = 1 - strength`).
+ *
+ * Legacy gates the exponent on an `optimizedDenoisingEnabled` user setting that
+ * defaults to `true`; webv2 exposes no such toggle, so the optimized curve is
+ * always applied for the eligible bases.
+ */
+const canvasDenoisingStart = (model: GenerateModelConfig, strength: number): number => {
+  if (model.base === 'flux' && model.variant === 'dev_fill') {
+    return 0;
+  }
+  const usesOptimizedCurve = model.base === 'sd-3' || model.base === 'flux' || model.base === 'flux2';
+  return 1 - strength ** (usesOptimizedCurve ? 0.2 : 1);
+};
+
+/** True for the image-referencing modes (everything but pure txt2img). */
+const isImageMode = (mode: CompileCanvasGraphInput['mode']): boolean => mode !== 'txt2img';
+
+/** Canvas-specific validation reasons layered on top of the shared generate ones. */
+const getCanvasValidationReasons = (input: CompileCanvasGraphInput): string[] => {
+  const { bbox, compositeImageName, maskImageName, mode, model, strength } = input;
+  const reasons: string[] = [];
+
+  if (model.type === 'external_image_generator') {
+    reasons.push(`${model.name} does not support canvas generation.`);
+    return reasons;
+  }
+
+  if (!Number.isFinite(bbox.width) || !Number.isFinite(bbox.height) || bbox.width <= 0 || bbox.height <= 0) {
+    reasons.push('Canvas bounding box must have a positive area.');
+  }
+
+  if (isImageMode(mode)) {
+    if (!compositeImageName) {
+      reasons.push('Canvas generation requires a composited source image.');
+    }
+
+    if (!Number.isFinite(strength) || strength <= 0 || strength > 1) {
+      reasons.push('Canvas denoising strength must be greater than 0 and at most 1.');
+    }
+  }
+
+  // Inpaint always needs a mask (an active inpaint mask defines the region);
+  // outpaint derives its mask from the raster alpha, so its mask is optional.
+  if (mode === 'inpaint' && !maskImageName) {
+    reasons.push('Canvas inpainting requires an inpaint mask.');
+  }
+
+  return reasons;
+};
+
+/** The settings a base builder sees: identical to the widget's, but sized to the bbox. */
+const withBboxDimensions = (settings: GenerateSettings, bbox: CompileCanvasGraphInput['bbox']): GenerateSettings => ({
+  ...settings,
+  height: bbox.height,
+  width: bbox.width,
+});
+
+/** Locates the node + field feeding a decode/denoise input edge (e.g. `canvas_output.vae`). */
+const findEdgeSource = (
+  graph: BackendGraphContract,
+  destNodeId: string,
+  destField: string
+): { node: BackendInvocationContract; field: string } | null => {
+  const edge = graph.edges.find(
+    (candidate) => candidate.destination.node_id === destNodeId && candidate.destination.field === destField
+  );
+  const node = edge ? graph.nodes[edge.source.node_id] : undefined;
+  return edge && node ? { field: edge.source.field, node } : null;
+};
+
+/** Resolves the VAE source feeding the graph's decode node (throws if absent). */
+const requireVaeSource = (graph: BackendGraphContract): { node: BackendInvocationContract; field: string } => {
+  const source = findEdgeSource(graph, 'canvas_output', 'vae');
+  if (!source) {
+    throw new Error('Canvas generation could not resolve a VAE source in the base graph.');
+  }
+  return source;
+};
+
+/**
+ * Renames a node in place: moves its map key, updates its `id`, and rewires every
+ * edge referencing the old id. Used to demote the base `canvas_output` decode to
+ * an intermediate `canvas_l2i` so the composite-back node can claim `canvas_output`.
+ */
+const renameNode = (graph: BackendGraphContract, oldId: string, newId: string): BackendInvocationContract => {
+  const node = graph.nodes[oldId];
+  if (!node) {
+    throw new Error(`Canvas generation could not find the "${oldId}" node to rename.`);
+  }
+  delete graph.nodes[oldId];
+  node.id = newId;
+  graph.nodes[newId] = node;
+  for (const edge of graph.edges) {
+    if (edge.source.node_id === oldId) {
+      edge.source.node_id = newId;
+    }
+    if (edge.destination.node_id === oldId) {
+      edge.destination.node_id = newId;
+    }
+  }
+  return node;
+};
+
+/** Sets the metadata `generation_mode` variant + strength (legacy parity). */
+const setMetadataMode = (graph: BackendGraphContract, mode: string, strength: number): void => {
+  const metadata = Object.values(graph.nodes).find((node) => node.type === 'core_metadata');
+  if (metadata) {
+    if (typeof metadata.generation_mode === 'string') {
+      metadata.generation_mode = metadata.generation_mode.replace('txt2img', mode);
+    }
+    metadata.strength = strength;
+  }
+};
+
+/** The SD `i2l` node carries fp32; every other family's encode node does not. */
+const isSdI2l = (i2lType: string): boolean => i2lType === 'i2l';
+
+/** Adds the base-appropriate image-to-latents encode node fed by `imageName`. */
+const addEncodeNode = (
+  graph: BackendGraphContract,
+  i2lType: string,
+  settings: GenerateSettings,
+  imageName: string | null
+): BackendInvocationContract =>
+  addNode(graph, {
+    id: 'canvas_i2l',
+    ...(imageName ? { image: { image_name: imageName } } : {}),
+    type: i2lType,
+    ...(isSdI2l(i2lType) ? { fp32: settings.vaePrecision === 'fp32' } : {}),
+  });
+
+/** Resolves the encode node type for a supported base (throws otherwise). */
+const requireI2lType = (model: GenerateModelConfig): string => {
+  if (model.type === 'external_image_generator') {
+    throw new Error(`${model.name} does not support canvas generation.`);
+  }
+  const i2lType = CANVAS_I2L_NODE_TYPES[model.base as SupportedGenerateBase];
+  if (!i2lType) {
+    throw new Error(`Canvas generation is not supported for ${model.name}.`);
+  }
+  return i2lType;
+};
+
+/** Resolves the base graph's denoise node (throws if absent). */
+const requireDenoise = (graph: BackendGraphContract): BackendInvocationContract => {
+  const denoise = graph.nodes.denoise_latents;
+  if (!denoise) {
+    throw new Error('Canvas generation could not find the denoise node in the base graph.');
+  }
+  return denoise;
+};
+
+/** Grafts the image-to-latents encode path onto a freshly built base graph (img2img). */
+const graftImageToImage = (
+  graph: BackendGraphContract,
+  model: GenerateModelConfig,
+  settings: GenerateSettings,
+  compositeImageName: string,
+  strength: number
+): void => {
+  const i2lType = requireI2lType(model);
+  const denoise = requireDenoise(graph);
+  const vaeSource = requireVaeSource(graph);
+  const encode = addEncodeNode(graph, i2lType, settings, compositeImageName);
+
+  addEdge(graph, vaeSource.node, vaeSource.field, encode, 'vae');
+  addEdge(graph, encode, 'latents', denoise, 'latents');
+  denoise.denoising_start = canvasDenoisingStart(model, strength);
+  denoise.denoising_end = 1;
+
+  setMetadataMode(graph, 'img2img', strength);
+};
+
+/** The backend infill node for the selected method (legacy `getInfill`). */
+const addInfillNode = (
+  graph: BackendGraphContract,
+  method: CanvasInfillMethod,
+  compositing: CanvasCompositingSettings
+): BackendInvocationContract => {
+  switch (method) {
+    case 'patchmatch':
+      return addNode(graph, {
+        downscale: compositing.infillPatchmatchDownscaleSize,
+        id: 'infill',
+        type: 'infill_patchmatch',
+      });
+    case 'lama':
+      return addNode(graph, { id: 'infill', type: 'infill_lama' });
+    case 'cv2':
+      return addNode(graph, { id: 'infill', type: 'infill_cv2' });
+    case 'tile':
+      return addNode(graph, { id: 'infill', tile_size: compositing.infillTileSize, type: 'infill_tile' });
+    case 'color': {
+      const { a, b, g, r } = compositing.infillColorValue;
+      return addNode(graph, {
+        color: { a: Math.round(a * 255), b, g, r },
+        id: 'infill',
+        type: 'infill_rgba',
+      });
+    }
+  }
+};
+
+/**
+ * Shared inpaint/outpaint tail: gradient denoise mask → denoise, expand-with-fade,
+ * and the composite-back blend (`canvas_output`). `maskSource` supplies the
+ * grayscale mask feeding `create_gradient_mask`; `initialImageName` is the base
+ * to paste the decoded result back onto.
+ */
+const graftMaskTail = (
+  graph: BackendGraphContract,
+  args: {
+    model: GenerateModelConfig;
+    settings: GenerateSettings;
+    i2lType: string;
+    denoise: BackendInvocationContract;
+    vaeSource: { node: BackendInvocationContract; field: string };
+    initialImageName: string;
+    compositing: CanvasCompositingSettings;
+    destination: CompileCanvasGraphInput['destination'];
+    /** Either a fixed mask image field or an edge-fed source node. */
+    gradientMaskImage?: { image_name: string };
+    gradientMaskEdge?: { node: BackendInvocationContract; field: string };
+  }
+): void => {
+  const { compositing, denoise, destination, i2lType, initialImageName, settings, vaeSource } = args;
+
+  // Demote the base decode to an intermediate `canvas_l2i`; the blend becomes `canvas_output`.
+  const l2i = renameNode(graph, 'canvas_output', 'canvas_l2i');
+  l2i.is_intermediate = true;
+
+  const gradientMask = addNode(graph, {
+    coherence_mode: compositing.coherenceMode,
+    edge_radius: compositing.coherenceEdgeSize,
+    fp32: isSdI2l(i2lType) ? settings.vaePrecision === 'fp32' : false,
+    id: 'create_gradient_mask',
+    image: { image_name: initialImageName },
+    minimum_denoise: compositing.coherenceMinDenoise,
+    type: 'create_gradient_mask',
+    ...(args.gradientMaskImage ? { mask: args.gradientMaskImage } : {}),
+  });
+
+  if (args.gradientMaskEdge) {
+    addEdge(graph, args.gradientMaskEdge.node, args.gradientMaskEdge.field, gradientMask, 'mask');
+  }
+  addEdge(graph, vaeSource.node, vaeSource.field, gradientMask, 'vae');
+  // The optional UNet edge only applies to SD-family models (legacy `isMainModelWithoutUnet`).
+  const unetSource = findEdgeSource(graph, 'denoise_latents', 'unet');
+  if (unetSource) {
+    addEdge(graph, unetSource.node, unetSource.field, gradientMask, 'unet');
+  }
+  addEdge(graph, gradientMask, 'denoise_mask', denoise, 'denoise_mask');
+
+  const expandMask = addNode(graph, {
+    fade_size_px: compositing.maskBlur,
+    id: 'expand_mask',
+    type: 'expand_mask_with_fade',
+  });
+  addEdge(graph, gradientMask, 'expanded_mask_area', expandMask, 'mask');
+
+  const blend = addNode(graph, {
+    id: 'canvas_output',
+    is_intermediate: destination === 'canvas',
+    layer_base: { image_name: initialImageName },
+    type: 'invokeai_img_blend',
+    use_cache: false,
+  });
+  addEdge(graph, l2i, 'image', blend, 'layer_upper');
+  addEdge(graph, expandMask, 'image', blend, 'mask');
+
+  // The base builder wired core_metadata → the decode's `metadata`; `renameNode`
+  // followed it onto the (now intermediate) canvas_l2i. Re-point it to the final
+  // blend so the saved image carries generation metadata (invokeai_img_blend is
+  // WithMetadata). Board fields, when present, ride the same node.
+  const metadataEdge = graph.edges.find(
+    (edge) => edge.destination.node_id === 'canvas_l2i' && edge.destination.field === 'metadata'
+  );
+  if (metadataEdge) {
+    metadataEdge.destination.node_id = 'canvas_output';
+  }
+};
+
+/** Optionally inserts an `img_noise` node before encode; returns the node feeding `i2l.image`. */
+const addNoiseBeforeEncode = (
+  graph: BackendGraphContract,
+  imageName: string,
+  noiseMaskImageName: string | null | undefined,
+  imageSourceNode: BackendInvocationContract | null
+): { imageField?: { image_name: string }; edgeFrom?: BackendInvocationContract } => {
+  if (!noiseMaskImageName) {
+    // No noise mask: encode reads the (infilled) initial image directly.
+    return imageSourceNode ? { edgeFrom: imageSourceNode } : { imageField: { image_name: imageName } };
+  }
+  const noise = addNode(graph, {
+    amount: 1.0,
+    id: 'add_inpaint_noise',
+    ...(imageSourceNode ? {} : { image: { image_name: imageName } }),
+    mask: { image_name: noiseMaskImageName },
+    noise_color: true,
+    noise_type: 'gaussian',
+    type: 'img_noise',
+  });
+  addEdge(graph, graph.nodes.seed, 'value', noise, 'seed');
+  if (imageSourceNode) {
+    addEdge(graph, imageSourceNode, 'image', noise, 'image');
+  }
+  return { edgeFrom: noise };
+};
+
+/** Grafts the inpaint pipeline (content covers the bbox, an inpaint mask restricts it). */
+const graftInpaint = (
+  graph: BackendGraphContract,
+  input: CompileCanvasGraphInput,
+  compositing: CanvasCompositingSettings
+): void => {
+  const { model } = input;
+  const i2lType = requireI2lType(model);
+  const denoise = requireDenoise(graph);
+  const vaeSource = requireVaeSource(graph);
+  const initialImageName = input.compositeImageName as string;
+  const maskImageName = input.maskImageName as string;
+  const strength = input.strength;
+
+  denoise.denoising_start = canvasDenoisingStart(model, strength);
+  denoise.denoising_end = 1;
+
+  const encode = addEncodeNode(graph, i2lType, input.settings, null);
+  const noiseResult = addNoiseBeforeEncode(graph, initialImageName, input.noiseMaskImageName, null);
+  if (noiseResult.edgeFrom) {
+    addEdge(graph, noiseResult.edgeFrom, 'image', encode, 'image');
+  } else if (noiseResult.imageField) {
+    encode.image = noiseResult.imageField;
+  }
+  addEdge(graph, vaeSource.node, vaeSource.field, encode, 'vae');
+  addEdge(graph, encode, 'latents', denoise, 'latents');
+
+  graftMaskTail(graph, {
+    compositing,
+    denoise,
+    destination: input.destination,
+    gradientMaskImage: { image_name: maskImageName },
+    i2lType,
+    initialImageName,
+    model,
+    settings: input.settings,
+    vaeSource,
+  });
+
+  setMetadataMode(graph, 'inpaint', strength);
+};
+
+/** Grafts the outpaint pipeline (bbox extends past content / has transparent holes). */
+const graftOutpaint = (
+  graph: BackendGraphContract,
+  input: CompileCanvasGraphInput,
+  compositing: CanvasCompositingSettings
+): void => {
+  const { model } = input;
+  const i2lType = requireI2lType(model);
+  const denoise = requireDenoise(graph);
+  const vaeSource = requireVaeSource(graph);
+  const initialImageName = input.compositeImageName as string;
+  const strength = input.strength;
+
+  denoise.denoising_start = canvasDenoisingStart(model, strength);
+  denoise.denoising_end = 1;
+
+  // Infill the transparent region before encode (legacy `getInfill`).
+  const infill = addInfillNode(graph, compositing.infillMethod, compositing);
+  infill.image = { image_name: initialImageName };
+
+  // Derive a mask from the initial image alpha (transparent → generate), combined
+  // with the inpaint mask when one exists.
+  const alphaToMask = addNode(graph, {
+    id: 'image_alpha_to_mask',
+    image: { image_name: initialImageName },
+    type: 'tomask',
+  });
+
+  let gradientMaskEdge: { node: BackendInvocationContract; field: string };
+  if (input.maskImageName) {
+    const maskCombine = addNode(graph, {
+      id: 'mask_combine',
+      mask1: { image_name: input.maskImageName },
+      type: 'mask_combine',
+    });
+    addEdge(graph, alphaToMask, 'image', maskCombine, 'mask2');
+    gradientMaskEdge = { field: 'image', node: maskCombine };
+  } else {
+    gradientMaskEdge = { field: 'image', node: alphaToMask };
+  }
+
+  const encode = addEncodeNode(graph, i2lType, input.settings, null);
+  const noiseResult = addNoiseBeforeEncode(graph, initialImageName, input.noiseMaskImageName, infill);
+  if (noiseResult.edgeFrom) {
+    addEdge(graph, noiseResult.edgeFrom, 'image', encode, 'image');
+  }
+  addEdge(graph, vaeSource.node, vaeSource.field, encode, 'vae');
+  addEdge(graph, encode, 'latents', denoise, 'latents');
+
+  graftMaskTail(graph, {
+    compositing,
+    denoise,
+    destination: input.destination,
+    gradientMaskEdge,
+    i2lType,
+    initialImageName,
+    model,
+    settings: input.settings,
+    vaeSource,
+  });
+
+  setMetadataMode(graph, 'outpaint', strength);
+};
+
+/**
+ * Compiles a canvas invoke into a backend graph. Throws a validation `Error`
+ * (message = first offending reason) for unsupported models/modes or bad
+ * geometry, mirroring `compileGenerateGraph`.
+ */
+export const compileCanvasGraph = (input: CompileCanvasGraphInput): CompiledCanvasGraph => {
+  const { bbox, compositeImageName, destination, mode, model, projectSettings, strength } = input;
+  const settings = withBboxDimensions(input.settings, bbox);
+
+  const validationReasons = [...getCanvasValidationReasons(input), ...getGenerationValidationReasons(model, settings)];
+
+  if (validationReasons.length > 0) {
+    throw new Error(validationReasons[0]);
+  }
+
+  const builder = GRAPH_BUILDERS[model.base as SupportedGenerateBase];
+
+  if (!builder || model.type === 'external_image_generator') {
+    throw new Error(`${model.name} does not support canvas generation.`);
+  }
+
+  // Mirror compileGenerateGraph: only a `canvas` destination stages an
+  // intermediate output; `gallery` produces a durable image.
+  const outputIsIntermediate = destination === 'canvas';
+  const backendGraph = builder(settings, model, outputIsIntermediate, projectSettings);
+  const compositing = input.compositing ?? DEFAULT_CANVAS_COMPOSITING;
+
+  // Validation above guarantees the composite/mask images required per mode.
+  if (mode === 'img2img') {
+    graftImageToImage(backendGraph, model, settings, compositeImageName as string, strength);
+  } else if (mode === 'inpaint') {
+    graftInpaint(backendGraph, input, compositing);
+  } else if (mode === 'outpaint') {
+    graftOutpaint(backendGraph, input, compositing);
+  }
+
+  // Control layers apply in every mode (legacy allows control with all). The
+  // executor already composited + uploaded each layer separately and resolved
+  // its model; the caller passes only valid layers.
+  if (input.controlLayers && input.controlLayers.length > 0) {
+    addControlLayers(backendGraph, {
+      base: model.base as SupportedGenerateBase,
+      layers: input.controlLayers,
+      modelVariant: model.variant ?? undefined,
+    });
+  }
+
+  // Regional guidance applies in every mode too. The executor already composited
+  // + uploaded each region's mask and resolved its reference-image models; it
+  // passes only valid regions for a supported base (sd-1 / sdxl / flux).
+  if (input.regionalGuidance && input.regionalGuidance.length > 0 && isRegionalGuidanceSupportedForBase(model.base)) {
+    addRegionalGuidance(backendGraph, { base: model.base, regions: input.regionalGuidance });
+  }
+
+  return {
+    backendGraph,
+    graph: toGraphContract(backendGraph, `${model.name} ${mode}`),
+    mode,
+    negativePromptNodeId: 'negative_prompt',
+    positivePromptNodeId: 'positive_prompt',
+    seedNodeId: 'seed',
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/compositePlan.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/compositePlan.test.ts
new file mode 100644
index 00000000000..cef05be6dbb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/compositePlan.test.ts
@@ -0,0 +1,512 @@
+import type {
+  CanvasControlLayerContract,
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+  CanvasRegionalGuidanceLayerContract,
+} from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import type { Rect } from './types';
+
+import {
+  getBaseRasterContentBounds,
+  planComposites,
+  planControlComposites,
+  planRegionalMaskComposites,
+} from './compositePlan';
+
+const imageRef = (imageName: string, width = 64, height = 48): CanvasImageRef => ({ height, imageName, width });
+
+const rasterLayer = (
+  id: string,
+  overrides: Partial<CanvasRasterLayerContractV2> = {}
+): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: imageRef(id), type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+  ...overrides,
+});
+
+const maskLayer = (id: string): CanvasLayerContract => ({
+  autoNegative: false,
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#ff0000', style: 'solid' } },
+  name: id,
+  negativePrompt: null,
+  opacity: 1,
+  positivePrompt: null,
+  referenceImages: [],
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'regional_guidance',
+});
+
+const BBOX: Rect = { height: 200, width: 200, x: 0, y: 0 };
+
+const makeDoc = (
+  layers: CanvasLayerContract[],
+  overrides: Partial<CanvasDocumentContractV2> = {}
+): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 200, width: 200, x: 0, y: 0 },
+  height: 300,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: 400,
+  ...overrides,
+});
+
+const keyOf = (doc: CanvasDocumentContractV2, bbox: Rect = BBOX): string => planComposites(doc, bbox).entries[0]!.key;
+
+describe('planComposites — plan shape', () => {
+  it('emits a single base-raster entry scoped to the bbox', () => {
+    const plan = planComposites(makeDoc([rasterLayer('a')]), BBOX);
+    expect(plan.bbox).toEqual(BBOX);
+    expect(plan.entries).toHaveLength(1);
+    const entry = plan.entries[0]!;
+    expect(entry.kind).toBe('base-raster');
+    expect(entry.bbox).toEqual(BBOX);
+  });
+
+  it('includes only enabled raster (image/paint) layers, preserving z-order', () => {
+    const doc = makeDoc([
+      rasterLayer('top'),
+      maskLayer('mask'),
+      rasterLayer('disabled', { isEnabled: false }),
+      rasterLayer('bottom', { source: { bitmap: imageRef('paint-bmp'), type: 'paint' } }),
+    ]);
+    const entry = planComposites(doc, BBOX).entries[0]!;
+    expect(entry.layers.map((l) => l.id)).toEqual(['top', 'bottom']);
+  });
+
+  it('excludes an inpaint mask (even one with a persisted bitmap) from the base-raster composite', () => {
+    const inpaintMask: CanvasLayerContract = {
+      blendMode: 'normal',
+      id: 'inpaint',
+      isEnabled: true,
+      isLocked: false,
+      mask: { bitmap: imageRef('mask-bmp'), fill: { color: '#e07575', style: 'diagonal' } },
+      name: 'inpaint',
+      opacity: 1,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'inpaint_mask',
+    };
+    const doc = makeDoc([rasterLayer('top'), inpaintMask]);
+    const entry = planComposites(doc, BBOX).entries[0]!;
+    // Masks feed the (next task's) mask composite, never the image composite.
+    expect(entry.layers.map((l) => l.id)).toEqual(['top']);
+  });
+
+  it('derives sourceRef + content-sized contentSize/contentOffset for image and paint layers', () => {
+    const doc = makeDoc([
+      rasterLayer('img', { source: { image: imageRef('pic', 128, 96), type: 'image' } }),
+      rasterLayer('paint', { source: { bitmap: imageRef('bmp', 200, 150), offset: { x: 40, y: 25 }, type: 'paint' } }),
+    ]);
+    const [img, paint] = planComposites(doc, BBOX).entries[0]!.layers;
+    expect(img!.sourceRef).toBe('image:pic');
+    expect(img!.contentSize).toEqual({ height: 96, width: 128 });
+    expect(img!.contentOffset).toEqual({ x: 0, y: 0 });
+    expect(paint!.sourceRef).toBe('paint:bmp');
+    // Paint layers are content-sized: the persisted bitmap dims placed at its offset.
+    expect(paint!.contentSize).toEqual({ height: 150, width: 200 });
+    expect(paint!.contentOffset).toEqual({ x: 40, y: 25 });
+  });
+
+  it('excludes an empty (bitmap: null) paint layer so it cannot force outpaint', () => {
+    // An auto-created paint layer left blank (e.g. its stroke was undone) carries
+    // no pixels; including it would inject a doc-sized transparent rect that reads
+    // as outpaint. It must not appear among the base-raster contributors.
+    const doc = makeDoc([
+      rasterLayer('img', { source: { image: imageRef('pic'), type: 'image' } }),
+      rasterLayer('blank', { source: { bitmap: null, type: 'paint' } }),
+    ]);
+    const entry = planComposites(doc, BBOX).entries[0]!;
+    expect(entry.layers.map((l) => l.id)).toEqual(['img']);
+  });
+
+  it('emits an empty layer list when the only paint layer is unpainted', () => {
+    const doc = makeDoc([rasterLayer('blank', { source: { bitmap: null, type: 'paint' } })]);
+    expect(planComposites(doc, BBOX).entries[0]!.layers).toEqual([]);
+  });
+});
+
+describe('planComposites — key stability', () => {
+  it('produces byte-identical keys for structurally identical documents', () => {
+    const build = () => makeDoc([rasterLayer('a'), rasterLayer('b', { opacity: 0.5 })]);
+    expect(keyOf(build())).toBe(keyOf(build()));
+  });
+});
+
+describe('planComposites — key sensitivity', () => {
+  it('changes the key when layers are reordered', () => {
+    const a = makeDoc([rasterLayer('a'), rasterLayer('b')]);
+    const b = makeDoc([rasterLayer('b'), rasterLayer('a')]);
+    expect(keyOf(a)).not.toBe(keyOf(b));
+  });
+
+  it('changes the key when a layer opacity changes', () => {
+    const a = makeDoc([rasterLayer('a', { opacity: 1 })]);
+    const b = makeDoc([rasterLayer('a', { opacity: 0.5 })]);
+    expect(keyOf(a)).not.toBe(keyOf(b));
+  });
+
+  it('changes the key when a layer transform changes', () => {
+    const a = makeDoc([rasterLayer('a')]);
+    const b = makeDoc([rasterLayer('a', { transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 10, y: 0 } })]);
+    expect(keyOf(a)).not.toBe(keyOf(b));
+  });
+
+  it('changes the key when a layer blend mode changes', () => {
+    const a = makeDoc([rasterLayer('a', { blendMode: 'normal' })]);
+    const b = makeDoc([rasterLayer('a', { blendMode: 'multiply' })]);
+    expect(keyOf(a)).not.toBe(keyOf(b));
+  });
+
+  it('changes the key when a layer source is swapped', () => {
+    const a = makeDoc([rasterLayer('a', { source: { image: imageRef('cat'), type: 'image' } })]);
+    const b = makeDoc([rasterLayer('a', { source: { image: imageRef('dog'), type: 'image' } })]);
+    expect(keyOf(a)).not.toBe(keyOf(b));
+  });
+
+  it('changes the key when the bbox moves', () => {
+    const doc = makeDoc([rasterLayer('a')]);
+    expect(keyOf(doc, { height: 200, width: 200, x: 0, y: 0 })).not.toBe(
+      keyOf(doc, { height: 200, width: 200, x: 10, y: 0 })
+    );
+  });
+
+  it('changes the key when a layer is toggled off', () => {
+    const a = makeDoc([rasterLayer('a')]);
+    const b = makeDoc([rasterLayer('a', { isEnabled: false })]);
+    expect(keyOf(a)).not.toBe(keyOf(b));
+  });
+});
+
+describe('planComposites — key insensitivity to irrelevant changes', () => {
+  it('ignores selectedLayerId', () => {
+    const a = makeDoc([rasterLayer('a')], { selectedLayerId: null });
+    const b = makeDoc([rasterLayer('a')], { selectedLayerId: 'a' });
+    expect(keyOf(a)).toBe(keyOf(b));
+  });
+
+  it('ignores the document background', () => {
+    const a = makeDoc([rasterLayer('a')], { background: 'transparent' });
+    const b = makeDoc([rasterLayer('a')], { background: { color: '#123456' } });
+    expect(keyOf(a)).toBe(keyOf(b));
+  });
+
+  it('ignores edits to a disabled layer', () => {
+    const a = makeDoc([rasterLayer('a'), rasterLayer('off', { isEnabled: false, opacity: 1 })]);
+    const b = makeDoc([rasterLayer('a'), rasterLayer('off', { isEnabled: false, opacity: 0.2, blendMode: 'screen' })]);
+    expect(keyOf(a)).toBe(keyOf(b));
+  });
+});
+
+const inpaintMask = (
+  id: string,
+  overrides: Partial<{
+    bitmap: CanvasImageRef | null;
+    noiseLevel: number;
+    denoiseLimit: number;
+    isEnabled: boolean;
+    offset: { x: number; y: number };
+  }> = {}
+): CanvasLayerContract => ({
+  blendMode: 'normal',
+  denoiseLimit: overrides.denoiseLimit,
+  id,
+  isEnabled: overrides.isEnabled ?? true,
+  isLocked: false,
+  mask: {
+    bitmap: 'bitmap' in overrides ? overrides.bitmap! : imageRef(`${id}-bmp`, 100, 80),
+    fill: { color: '#ff0000', style: 'solid' },
+    ...(overrides.offset ? { offset: overrides.offset } : {}),
+  },
+  name: id,
+  noiseLevel: overrides.noiseLevel,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+const entryOfKind = (doc: CanvasDocumentContractV2, kind: string) =>
+  planComposites(doc, BBOX).entries.find((e) => e.kind === kind);
+
+describe('planComposites — inpaint-mask entries', () => {
+  it('emits no mask entries when there are no active inpaint masks', () => {
+    const kinds = planComposites(makeDoc([rasterLayer('a')]), BBOX).entries.map((e) => e.kind);
+    expect(kinds).toEqual(['base-raster']);
+  });
+
+  it('emits an inpaint-mask entry for enabled masks with a persisted bitmap', () => {
+    const entry = entryOfKind(makeDoc([rasterLayer('a'), inpaintMask('m1')]), 'inpaint-mask');
+    expect(entry).toBeDefined();
+    expect(entry!.maskLayers!.map((l) => l.id)).toEqual(['m1']);
+    expect(entry!.maskLayers![0]!.sourceRef).toBe('mask:m1-bmp');
+    expect(entry!.maskLayers![0]!.contentSize).toEqual({ height: 80, width: 100 });
+  });
+
+  it('excludes disabled masks and empty (bitmap: null) masks', () => {
+    const doc = makeDoc([
+      inpaintMask('on'),
+      inpaintMask('off', { isEnabled: false }),
+      inpaintMask('empty', { bitmap: null }),
+    ]);
+    const entry = entryOfKind(doc, 'inpaint-mask');
+    expect(entry!.maskLayers!.map((l) => l.id)).toEqual(['on']);
+  });
+
+  it('resolves an undefined denoiseLimit to the legacy default (1.0)', () => {
+    const entry = entryOfKind(makeDoc([inpaintMask('m1')]), 'inpaint-mask');
+    expect(entry!.maskLayers![0]!.attributeValue).toBe(1);
+  });
+
+  it('uses the layer denoiseLimit when defined', () => {
+    const entry = entryOfKind(makeDoc([inpaintMask('m1', { denoiseLimit: 0.4 })]), 'inpaint-mask');
+    expect(entry!.maskLayers![0]!.attributeValue).toBe(0.4);
+  });
+
+  it('unions multiple masks into the denoise-limit entry', () => {
+    const doc = makeDoc([inpaintMask('a', { denoiseLimit: 0.3 }), inpaintMask('b')]);
+    const entry = entryOfKind(doc, 'inpaint-mask');
+    expect(entry!.maskLayers!.map((l) => l.id)).toEqual(['a', 'b']);
+  });
+});
+
+describe('planComposites — noise-mask entries', () => {
+  it('omits the noise-mask entry when no mask defines a noiseLevel (undefined is NOT 0)', () => {
+    const kinds = planComposites(makeDoc([inpaintMask('m1')]), BBOX).entries.map((e) => e.kind);
+    expect(kinds).toEqual(['base-raster', 'inpaint-mask']);
+  });
+
+  it('emits a noise-mask entry only for masks with a defined noiseLevel', () => {
+    const doc = makeDoc([inpaintMask('withNoise', { noiseLevel: 0.15 }), inpaintMask('noNoise')]);
+    const entry = entryOfKind(doc, 'noise-mask');
+    expect(entry).toBeDefined();
+    expect(entry!.maskLayers!.map((l) => l.id)).toEqual(['withNoise']);
+    expect(entry!.maskLayers![0]!.attributeValue).toBe(0.15);
+  });
+
+  it('treats noiseLevel 0 as defined (included), distinct from undefined (excluded)', () => {
+    const entry = entryOfKind(makeDoc([inpaintMask('m1', { noiseLevel: 0 })]), 'noise-mask');
+    expect(entry).toBeDefined();
+    expect(entry!.maskLayers![0]!.attributeValue).toBe(0);
+  });
+});
+
+describe('planComposites — mask entry keys', () => {
+  const maskKeyOf = (doc: CanvasDocumentContractV2, kind: string): string | undefined => entryOfKind(doc, kind)?.key;
+
+  it('is stable for identical documents', () => {
+    const a = makeDoc([inpaintMask('m1', { denoiseLimit: 0.5 })]);
+    const b = makeDoc([inpaintMask('m1', { denoiseLimit: 0.5 })]);
+    expect(maskKeyOf(a, 'inpaint-mask')).toBe(maskKeyOf(b, 'inpaint-mask'));
+  });
+
+  it('changes when the attribute value changes', () => {
+    const a = makeDoc([inpaintMask('m1', { denoiseLimit: 0.5 })]);
+    const b = makeDoc([inpaintMask('m1', { denoiseLimit: 0.6 })]);
+    expect(maskKeyOf(a, 'inpaint-mask')).not.toBe(maskKeyOf(b, 'inpaint-mask'));
+  });
+
+  it('changes when the mask bitmap changes', () => {
+    const a = makeDoc([inpaintMask('m1')]);
+    const b = makeDoc([inpaintMask('m1', { bitmap: imageRef('other', 100, 80) })]);
+    expect(maskKeyOf(a, 'inpaint-mask')).not.toBe(maskKeyOf(b, 'inpaint-mask'));
+  });
+});
+
+const controlLayer = (
+  id: string,
+  overrides: Partial<{
+    source: CanvasControlLayerContract['source'];
+    isEnabled: boolean;
+    withTransparencyEffect: boolean;
+    opacity: number;
+    blendMode: CanvasLayerContract['blendMode'];
+  }> = {}
+): CanvasLayerContract => ({
+  adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+  blendMode: overrides.blendMode ?? 'normal',
+  id,
+  isEnabled: overrides.isEnabled ?? true,
+  isLocked: false,
+  name: id,
+  opacity: overrides.opacity ?? 1,
+  source: overrides.source ?? { image: imageRef(id, 64, 48), type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: overrides.withTransparencyEffect ?? false,
+});
+
+describe('planComposites — control-layer exclusion', () => {
+  it('never includes control layers in the base-raster entry', () => {
+    const plan = planComposites(makeDoc([rasterLayer('r'), controlLayer('c')]), BBOX);
+    const base = plan.entries.find((entry) => entry.kind === 'base-raster');
+    expect(base?.layers.map((layer) => layer.id)).toEqual(['r']);
+  });
+
+  it('emits no control-layer entries from planComposites (they live in planControlComposites)', () => {
+    const plan = planComposites(makeDoc([controlLayer('c')]), BBOX);
+    expect(plan.entries.some((entry) => entry.kind === 'control-layer')).toBe(false);
+  });
+});
+
+describe('getBaseRasterContentBounds', () => {
+  it('returns rounded transformed bounds for enabled raster content only', () => {
+    const document = makeDoc([
+      rasterLayer('enabled', {
+        source: { image: imageRef('source', 100, 50), type: 'image' },
+        transform: { rotation: 0, scaleX: 2, scaleY: 1, x: -10.25, y: 20.5 },
+      }),
+      { ...controlLayer('control'), isEnabled: true },
+      { ...rasterLayer('disabled'), isEnabled: false },
+    ]);
+
+    expect(getBaseRasterContentBounds(document)).toEqual({ x: -11, y: 20, width: 201, height: 51 });
+  });
+
+  it('returns null when no enabled raster layer has content', () => {
+    expect(getBaseRasterContentBounds(makeDoc([controlLayer('control')]))).toBeNull();
+  });
+});
+
+describe('planControlComposites', () => {
+  it('emits one separate entry per enabled control layer with content', () => {
+    const composites = planControlComposites(makeDoc([controlLayer('c1'), controlLayer('c2')]), BBOX);
+    expect(composites.map((composite) => composite.layerId)).toEqual(['c1', 'c2']);
+    for (const { entry } of composites) {
+      expect(entry.kind).toBe('control-layer');
+      expect(entry.bbox).toEqual(BBOX);
+      expect(entry.layers).toHaveLength(1);
+      // Each control layer is composited SEPARATELY, never blended with others.
+      expect(entry.layerId).toBe(entry.layers[0]!.id);
+    }
+    // Distinct keys per layer.
+    expect(composites[0]!.entry.key).not.toBe(composites[1]!.entry.key);
+  });
+
+  it('excludes disabled control layers and empty paint-source control layers', () => {
+    const composites = planControlComposites(
+      makeDoc([
+        controlLayer('enabled'),
+        controlLayer('disabled', { isEnabled: false }),
+        controlLayer('empty', { source: { bitmap: null, type: 'paint' } }),
+      ]),
+      BBOX
+    );
+    expect(composites.map((composite) => composite.layerId)).toEqual(['enabled']);
+  });
+
+  it('ignores raster/mask layers entirely', () => {
+    const composites = planControlComposites(makeDoc([rasterLayer('r'), inpaintMask('m'), controlLayer('c')]), BBOX);
+    expect(composites.map((composite) => composite.layerId)).toEqual(['c']);
+  });
+
+  it('forces opacity 1 / normal blend so display tweaks and the transparency effect never churn the key', () => {
+    const a = planControlComposites(makeDoc([controlLayer('c')]), BBOX);
+    const b = planControlComposites(
+      makeDoc([controlLayer('c', { opacity: 0.3, blendMode: 'multiply', withTransparencyEffect: true })]),
+      BBOX
+    );
+    expect(a[0]!.entry.key).toBe(b[0]!.entry.key);
+    expect(a[0]!.entry.layers[0]!.opacity).toBe(1);
+    expect(a[0]!.entry.layers[0]!.blendMode).toBe('normal');
+  });
+
+  it('changes the key when the control source pixels change', () => {
+    const a = planControlComposites(makeDoc([controlLayer('c')]), BBOX);
+    const b = planControlComposites(
+      makeDoc([controlLayer('c', { source: { image: imageRef('other', 64, 48), type: 'image' } })]),
+      BBOX
+    );
+    expect(a[0]!.entry.key).not.toBe(b[0]!.entry.key);
+  });
+});
+
+const regionalLayer = (
+  id: string,
+  overrides: Partial<CanvasRegionalGuidanceLayerContract> = {}
+): CanvasLayerContract => ({
+  autoNegative: false,
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: imageRef(`${id}-mask`), fill: { color: '#ff0000', style: 'solid' } },
+  name: id,
+  negativePrompt: null,
+  opacity: 0.5,
+  positivePrompt: 'a cat',
+  referenceImages: [],
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'regional_guidance',
+  ...overrides,
+});
+
+describe('planRegionalMaskComposites', () => {
+  it('emits one alpha-mask entry per enabled region WITH mask content', () => {
+    const entries = planRegionalMaskComposites(makeDoc([regionalLayer('a'), regionalLayer('b')]), BBOX);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]!.entry.kind).toBe('regional-mask');
+    expect(entries[0]!.layerId).toBe('a');
+    // Composited at opacity 1 / normal (display opacity 0.5 must NOT alter the mask alpha sent to the backend).
+    expect(entries[0]!.entry.layers[0]!.opacity).toBe(1);
+    expect(entries[0]!.entry.layers[0]!.blendMode).toBe('normal');
+  });
+
+  it('skips regions with no mask bitmap and disabled regions', () => {
+    const entries = planRegionalMaskComposites(
+      makeDoc([
+        regionalLayer('empty', { mask: { bitmap: null, fill: { color: '#f00', style: 'solid' } } }),
+        regionalLayer('off', { isEnabled: false }),
+        regionalLayer('ok'),
+      ]),
+      BBOX
+    );
+    expect(entries.map((e) => e.layerId)).toEqual(['ok']);
+  });
+
+  it('keys are stable per region+bbox and change with the mask source', () => {
+    const a = planRegionalMaskComposites(makeDoc([regionalLayer('a')]), BBOX);
+    const b = planRegionalMaskComposites(
+      makeDoc([
+        regionalLayer('a', { mask: { bitmap: imageRef('other-mask'), fill: { color: '#f00', style: 'solid' } } }),
+      ]),
+      BBOX
+    );
+    expect(a[0]!.entry.key).not.toBe(b[0]!.entry.key);
+  });
+});
+
+describe('planComposites — raster adjustments in the base key', () => {
+  it('folds a non-identity adjustment into the base-raster entry (and its key)', () => {
+    const plain = rasterLayer('a');
+    const adjusted = rasterLayer('a', { adjustments: { brightness: 0.5, contrast: 0, saturation: 0 } });
+    const plan = planComposites(makeDoc([adjusted]), BBOX);
+    const ref = plan.entries[0]!.layers[0]!;
+    expect(ref.adjustments).toEqual({ brightness: 0.5, contrast: 0, saturation: 0 });
+    // A changed adjustment changes the entry key so the executor re-composites/uploads.
+    expect(keyOf(makeDoc([plain]))).not.toBe(keyOf(makeDoc([adjusted])));
+  });
+
+  it('ignores an identity adjustment (no key churn)', () => {
+    const plain = rasterLayer('a');
+    const identityAdj = rasterLayer('a', { adjustments: { brightness: 0, contrast: 0, saturation: 0 } });
+    expect(plan0(plain)).toBe(plan0(identityAdj));
+  });
+});
+
+const plan0 = (layer: CanvasLayerContract): string => planComposites(makeDoc([layer]), BBOX).entries[0]!.key;
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/compositePlan.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/compositePlan.ts
new file mode 100644
index 00000000000..ca5591186ff
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/compositePlan.ts
@@ -0,0 +1,328 @@
+/**
+ * Pure composite planner.
+ *
+ * {@link planComposites} turns a canvas document + generation bbox into a
+ * {@link CompositePlan} — a pixel-free description of what the executor must
+ * composite and upload — without touching any pixels or the engine. Phase 4.2
+ * emits a single `base-raster` entry: the enabled raster layers (image/paint
+ * sources) in z-order, each with its transform / opacity / blend mode.
+ *
+ * ## Stable identity key
+ *
+ * Each entry carries a `key` derived from exactly the inputs that determine its
+ * pixels: the bbox rect plus, for each contributing layer in z-order, its
+ * `(id, sourceRef, transform, opacity, blendMode)`. Only *enabled* raster
+ * layers contribute, so a layer's enablement is encoded by its presence in the
+ * list (toggling it on/off changes the set, and thus the key). This makes the
+ * key:
+ * - **stable**: same document + bbox → byte-identical key;
+ * - **sensitive** to reorder, opacity, transform, source swap, and bbox moves;
+ * - **insensitive** to irrelevant edits: `selectedLayerId`, background, and any
+ *   change to a disabled layer (it never appears in the list).
+ *
+ * The key is a plain deterministic string (no hashing needed) so it stays cheap
+ * and debuggable; the executor uses it as a map key to skip redundant work.
+ */
+
+import type {
+  CanvasControlLayerContract,
+  CanvasDocumentContractV2,
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+  CanvasRegionalGuidanceLayerContract,
+} from '@workbench/types';
+
+import { adjustmentsKey } from '@workbench/canvas-engine/render/adjustments';
+import {
+  getBaseRasterContentBounds,
+  getCompositeLayerBounds,
+  planBaseRasterComposite,
+} from '@workbench/canvas-engine/render/rasterComposite';
+
+import type { CompositeEntry, CompositeLayerRef, CompositeMaskLayerRef, CompositePlan, Rect } from './types';
+
+import { DEFAULT_MASK_DENOISE_LIMIT } from './types';
+
+/** A stable string identifying a source's pixels (its asset name, or an empty sentinel). */
+const sourceRefOf = (source: CanvasLayerSourceContract): string => {
+  switch (source.type) {
+    case 'image':
+      return `image:${source.image.imageName}`;
+    case 'paint':
+      return source.bitmap ? `paint:${source.bitmap.imageName}` : 'paint:empty';
+    default:
+      return `${source.type}:unsupported`;
+  }
+};
+
+/** Serializes a rect into a compact, deterministic key fragment. */
+const rectKey = (rect: Rect): string => `${rect.x},${rect.y},${rect.width},${rect.height}`;
+
+/** Serializes a layer ref's pixel-determining fields into a key fragment. */
+const layerKey = (ref: CompositeLayerRef): string => {
+  const t = ref.transform;
+  const o = ref.contentOffset;
+  return [
+    ref.id,
+    ref.sourceRef,
+    o.x,
+    o.y,
+    t.x,
+    t.y,
+    t.scaleX,
+    t.scaleY,
+    t.rotation,
+    ref.opacity,
+    ref.blendMode,
+    ref.adjustments ? adjustmentsKey(ref.adjustments) : '-',
+  ].join(':');
+};
+
+export { getBaseRasterContentBounds, getCompositeLayerBounds, planBaseRasterComposite };
+
+/** True when a layer is an enabled inpaint mask with persisted (non-empty) alpha. */
+const isActiveInpaintMaskLayer = (layer: CanvasLayerContract): layer is CanvasInpaintMaskLayerContract =>
+  layer.isEnabled && layer.type === 'inpaint_mask' && layer.mask.bitmap !== null;
+
+/** The native content rect of a mask layer's persisted bitmap (layer-local, at its offset). */
+const maskContentRect = (
+  layer: CanvasInpaintMaskLayerContract
+): { width: number; height: number; x: number; y: number } => {
+  const { bitmap, offset } = layer.mask;
+  if (bitmap) {
+    const o = offset ?? { x: 0, y: 0 };
+    return { height: bitmap.height, width: bitmap.width, x: o.x, y: o.y };
+  }
+  return { height: 0, width: 0, x: 0, y: 0 };
+};
+
+/** Projects a mask layer into a grayscale-composite contribution with its resolved attribute value. */
+const toMaskLayerRef = (layer: CanvasInpaintMaskLayerContract, attributeValue: number): CompositeMaskLayerRef => {
+  const rect = maskContentRect(layer);
+  return {
+    attributeValue,
+    contentOffset: { x: rect.x, y: rect.y },
+    contentSize: { height: rect.height, width: rect.width },
+    id: layer.id,
+    sourceRef: layer.mask.bitmap ? `mask:${layer.mask.bitmap.imageName}` : 'mask:empty',
+    transform: {
+      rotation: layer.transform.rotation,
+      scaleX: layer.transform.scaleX,
+      scaleY: layer.transform.scaleY,
+      x: layer.transform.x,
+      y: layer.transform.y,
+    },
+  };
+};
+
+/** Serializes a mask layer ref (adds `attributeValue` to the pixel-determining key). */
+const maskLayerKey = (ref: CompositeMaskLayerRef): string => {
+  const t = ref.transform;
+  const o = ref.contentOffset;
+  return [ref.id, ref.sourceRef, o.x, o.y, t.x, t.y, t.scaleX, t.scaleY, t.rotation, ref.attributeValue].join(':');
+};
+
+/** Derives the stable identity key for a grayscale mask entry. */
+const deriveMaskKey = (kind: string, bbox: Rect, layers: CompositeMaskLayerRef[]): string =>
+  `${kind}|${rectKey(bbox)}|${layers.map(maskLayerKey).join('|')}`;
+
+/**
+ * Plans the composites required to invoke `document` over `bbox`:
+ * - one `base-raster` entry (the initial image);
+ * - one `inpaint-mask` entry (grayscale denoise-limit mask) when enabled inpaint
+ *   masks with content exist — an undefined `denoiseLimit` resolves to the legacy
+ *   default (1.0, full denoise);
+ * - one `noise-mask` entry when at least one such mask defines a `noiseLevel`
+ *   (masks with an undefined `noiseLevel` are excluded, mirroring legacy — they
+ *   must NOT be treated as noise 0).
+ */
+export const planComposites = (document: CanvasDocumentContractV2, bbox: Rect): CompositePlan => {
+  const entries: CompositeEntry[] = [planBaseRasterComposite(document, bbox)];
+
+  const maskLayers = document.layers.filter(isActiveInpaintMaskLayer);
+
+  if (maskLayers.length > 0) {
+    const denoiseRefs = maskLayers.map((layer) =>
+      toMaskLayerRef(layer, layer.denoiseLimit ?? DEFAULT_MASK_DENOISE_LIMIT)
+    );
+    entries.push({
+      bbox,
+      key: deriveMaskKey('inpaint-mask', bbox, denoiseRefs),
+      kind: 'inpaint-mask',
+      layers: [],
+      maskLayers: denoiseRefs,
+    });
+
+    const noiseRefs = maskLayers
+      .filter((layer) => layer.noiseLevel !== undefined)
+      .map((layer) => toMaskLayerRef(layer, layer.noiseLevel as number));
+
+    if (noiseRefs.length > 0) {
+      entries.push({
+        bbox,
+        key: deriveMaskKey('noise-mask', bbox, noiseRefs),
+        kind: 'noise-mask',
+        layers: [],
+        maskLayers: noiseRefs,
+      });
+    }
+  }
+
+  return { bbox, entries };
+};
+
+/** True when a control layer is enabled and holds rasterizable (non-empty) content. */
+const hasControlContent = (layer: CanvasLayerContract): layer is CanvasControlLayerContract => {
+  if (!layer.isEnabled || layer.type !== 'control') {
+    return false;
+  }
+  if (layer.source.type === 'image') {
+    return true;
+  }
+  return layer.source.type === 'paint' && layer.source.bitmap !== null;
+};
+
+/** The native (unscaled) content rect of a control layer's source (layer-local). */
+const controlContentRect = (
+  layer: CanvasControlLayerContract,
+  doc: CanvasDocumentContractV2
+): { width: number; height: number; x: number; y: number } => {
+  const { source } = layer;
+  if (source.type === 'image') {
+    return { height: source.image.height, width: source.image.width, x: 0, y: 0 };
+  }
+  if (source.type === 'paint' && source.bitmap) {
+    const offset = source.offset ?? { x: 0, y: 0 };
+    return { height: source.bitmap.height, width: source.bitmap.width, x: offset.x, y: offset.y };
+  }
+  return { height: doc.height, width: doc.width, x: 0, y: 0 };
+};
+
+/**
+ * Projects a control layer into a standalone composite contribution. Opacity is
+ * forced to 1 and blend mode to `normal` (the layer's DISPLAY opacity/blend and
+ * transparency effect never alter the control image sent to the backend — legacy
+ * rasterizes control at opacity 1, no filters), so display tweaks don't churn the
+ * entry key.
+ */
+const toControlLayerRef = (layer: CanvasControlLayerContract, doc: CanvasDocumentContractV2): CompositeLayerRef => {
+  const rect = controlContentRect(layer, doc);
+  return {
+    blendMode: 'normal',
+    contentOffset: { x: rect.x, y: rect.y },
+    contentSize: { height: rect.height, width: rect.width },
+    id: layer.id,
+    opacity: 1,
+    sourceRef: sourceRefOf(layer.source),
+    transform: {
+      rotation: layer.transform.rotation,
+      scaleX: layer.transform.scaleX,
+      scaleY: layer.transform.scaleY,
+      x: layer.transform.x,
+      y: layer.transform.y,
+    },
+  };
+};
+
+/** One control layer's separate composite (never blended with other control layers). */
+export interface ControlCompositeEntry {
+  layerId: string;
+  entry: CompositeEntry;
+}
+
+/**
+ * Plans one composite per enabled control layer WITH content — each composited
+ * separately over `bbox` (legacy parity: control images are never blended
+ * together). Empty control layers (no source / blank paint) are excluded (they
+ * carry no control content and are rejected upstream with a "no control" reason).
+ * Control layers never contribute to the `base-raster` composite, so they never
+ * paint into the img2img/inpaint source.
+ */
+export const planControlComposites = (document: CanvasDocumentContractV2, bbox: Rect): ControlCompositeEntry[] =>
+  document.layers.filter(hasControlContent).map((layer) => {
+    const ref = toControlLayerRef(layer, document);
+    return {
+      entry: {
+        bbox,
+        key: `control-layer|${layer.id}|${rectKey(bbox)}|${layerKey(ref)}`,
+        kind: 'control-layer',
+        layerId: layer.id,
+        layers: [ref],
+      },
+      layerId: layer.id,
+    };
+  });
+
+/** True when a regional-guidance layer is enabled and holds a persisted (non-empty) mask. */
+const hasRegionalMaskContent = (layer: CanvasLayerContract): layer is CanvasRegionalGuidanceLayerContract =>
+  layer.isEnabled && layer.type === 'regional_guidance' && layer.mask.bitmap !== null;
+
+/** The native content rect of a regional mask's persisted bitmap (layer-local, at its offset). */
+const regionalMaskContentRect = (
+  layer: CanvasRegionalGuidanceLayerContract
+): { width: number; height: number; x: number; y: number } => {
+  const { bitmap, offset } = layer.mask;
+  if (bitmap) {
+    const o = offset ?? { x: 0, y: 0 };
+    return { height: bitmap.height, width: bitmap.width, x: o.x, y: o.y };
+  }
+  return { height: 0, width: 0, x: 0, y: 0 };
+};
+
+/**
+ * Projects a regional-guidance layer into a standalone ALPHA composite
+ * contribution (opacity 1, normal blend) — the executor composites the mask's
+ * alpha coverage over the bbox and uploads it, so `alpha_mask_to_tensor` can read
+ * the region's alpha. Display opacity/blend never alter the mask sent to the
+ * backend (mirrors control layers).
+ */
+const toRegionalMaskRef = (layer: CanvasRegionalGuidanceLayerContract): CompositeLayerRef => {
+  const rect = regionalMaskContentRect(layer);
+  return {
+    blendMode: 'normal',
+    contentOffset: { x: rect.x, y: rect.y },
+    contentSize: { height: rect.height, width: rect.width },
+    id: layer.id,
+    opacity: 1,
+    sourceRef: layer.mask.bitmap ? `mask:${layer.mask.bitmap.imageName}` : 'mask:empty',
+    transform: {
+      rotation: layer.transform.rotation,
+      scaleX: layer.transform.scaleX,
+      scaleY: layer.transform.scaleY,
+      x: layer.transform.x,
+      y: layer.transform.y,
+    },
+  };
+};
+
+/** One regional-guidance region's separate alpha-mask composite. */
+export interface RegionalMaskCompositeEntry {
+  layerId: string;
+  entry: CompositeEntry;
+}
+
+/**
+ * Plans one alpha-mask composite per enabled regional-guidance layer WITH mask
+ * content — each composited separately over `bbox` (a region's mask feeds its own
+ * `alpha_mask_to_tensor`; regions are never combined). Regions without mask
+ * content carry no region and are skipped (they'd be rejected upstream with a
+ * "no region" reason). Regional layers never contribute to `base-raster`.
+ */
+export const planRegionalMaskComposites = (
+  document: CanvasDocumentContractV2,
+  bbox: Rect
+): RegionalMaskCompositeEntry[] =>
+  document.layers.filter(hasRegionalMaskContent).map((layer) => {
+    const ref = toRegionalMaskRef(layer);
+    return {
+      entry: {
+        bbox,
+        key: `regional-mask|${layer.id}|${rectKey(bbox)}|${layerKey(ref)}`,
+        kind: 'regional-mask',
+        layerId: layer.id,
+        layers: [ref],
+      },
+      layerId: layer.id,
+    };
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/controlRecommendations.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlRecommendations.test.ts
new file mode 100644
index 00000000000..0d43066f142
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlRecommendations.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveDefaultFilterForModel } from './controlRecommendations';
+
+describe('resolveDefaultFilterForModel', () => {
+  it.each([
+    ['canny_edge_detection', 'canny_edge_detection'],
+    ['canny_image_processor', 'canny_edge_detection'],
+    ['normalbae_image_processor', 'normal_map'],
+    ['zoe_depth_image_processor', 'depth_anything_depth_estimation'],
+    ['lineart_anime_image_processor', 'lineart_anime_edge_detection'],
+  ])('resolves current ids and legacy alias %s', (preprocessor, expected) => {
+    expect(resolveDefaultFilterForModel({ default_settings: { preprocessor } })).toBe(expected);
+  });
+
+  it('returns null for missing or unknown metadata', () => {
+    expect(resolveDefaultFilterForModel(null)).toBeNull();
+    expect(resolveDefaultFilterForModel({ default_settings: null })).toBeNull();
+    expect(resolveDefaultFilterForModel({ default_settings: { preprocessor: 'future_processor' } })).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/controlRecommendations.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlRecommendations.ts
new file mode 100644
index 00000000000..51cad604cd8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlRecommendations.ts
@@ -0,0 +1,32 @@
+import type { ModelConfig } from '@workbench/models/types';
+
+import { isSupportedFilterType } from './filterGraphs';
+
+export const PROCESSOR_TO_FILTER_MAP: Readonly<Record<string, string>> = {
+  canny_image_processor: 'canny_edge_detection',
+  color_map_image_processor: 'color_map',
+  content_shuffle_image_processor: 'content_shuffle',
+  depth_anything_image_processor: 'depth_anything_depth_estimation',
+  dw_openpose_image_processor: 'dw_openpose_detection',
+  hed_image_processor: 'hed_edge_detection',
+  lineart_anime_image_processor: 'lineart_anime_edge_detection',
+  lineart_image_processor: 'lineart_edge_detection',
+  mediapipe_face_processor: 'mediapipe_face_detection',
+  mlsd_image_processor: 'mlsd_detection',
+  normalbae_image_processor: 'normal_map',
+  pidi_image_processor: 'pidi_edge_detection',
+  zoe_depth_image_processor: 'depth_anything_depth_estimation',
+};
+
+export const resolveDefaultFilterForModel = (
+  model: Pick<ModelConfig, 'default_settings'> | null | undefined
+): string | null => {
+  const preprocessor = model?.default_settings?.preprocessor;
+  if (!preprocessor) {
+    return null;
+  }
+  if (isSupportedFilterType(preprocessor)) {
+    return preprocessor;
+  }
+  return PROCESSOR_TO_FILTER_MAP[preprocessor] ?? null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/controlValidation.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlValidation.test.ts
new file mode 100644
index 00000000000..f6ed3c8e6ff
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlValidation.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+
+import { getControlValidationReason } from './controlValidation';
+
+const valid = {
+  adapterModel: { base: 'sd-1', type: 'controlnet' },
+  controlLoraIndex: 0,
+  kind: 'controlnet' as const,
+  mainBase: 'sd-1',
+  mainVariant: undefined,
+  beginEndStepPct: [0, 1] as [number, number],
+  weight: 0.75,
+};
+
+describe('getControlValidationReason', () => {
+  it('returns stable reason codes for the validation matrix', () => {
+    expect(getControlValidationReason(valid)).toBeNull();
+    expect(getControlValidationReason({ ...valid, adapterModel: null })).toBe('missing_model');
+    expect(getControlValidationReason({ ...valid, mainBase: 'sd-2' })).toBe('unsupported_adapter');
+    expect(getControlValidationReason({ ...valid, adapterModel: { base: 'sdxl', type: 'controlnet' } })).toBe(
+      'incompatible_base'
+    );
+    expect(getControlValidationReason({ ...valid, adapterModel: { base: 'sd-1', type: 't2i_adapter' } })).toBe(
+      'incompatible_adapter'
+    );
+    expect(
+      getControlValidationReason({
+        adapterModel: { base: 'flux', type: 'control_lora' },
+        beginEndStepPct: [0, 1],
+        controlLoraIndex: 1,
+        kind: 'control_lora',
+        mainBase: 'flux',
+        weight: 0.75,
+      })
+    ).toBe('control_lora_limit');
+    expect(
+      getControlValidationReason({
+        adapterModel: { base: 'flux', type: 'control_lora' },
+        beginEndStepPct: [0, 1],
+        controlLoraIndex: 0,
+        kind: 'control_lora',
+        mainBase: 'flux',
+        mainVariant: 'dev_fill',
+        weight: 0.75,
+      })
+    ).toBe('flux_fill_control_lora');
+  });
+
+  it('accepts only a Z-Image ControlNet model on a Z-Image main model', () => {
+    const zImage = {
+      adapterModel: { base: 'z-image', type: 'controlnet' },
+      beginEndStepPct: [0, 1] as [number, number],
+      controlLoraIndex: 0,
+      kind: 'z_image_control' as const,
+      mainBase: 'z-image',
+      weight: 0.75,
+    };
+    expect(getControlValidationReason(zImage)).toBeNull();
+    expect(getControlValidationReason({ ...zImage, mainBase: 'sd-1' })).toBe('unsupported_adapter');
+    expect(getControlValidationReason({ ...zImage, adapterModel: { base: 'sdxl', type: 'controlnet' } })).toBe(
+      'incompatible_base'
+    );
+    expect(getControlValidationReason({ ...zImage, adapterModel: { base: 'z-image', type: 't2i_adapter' } })).toBe(
+      'incompatible_adapter'
+    );
+    expect(
+      getControlValidationReason({
+        ...valid,
+        adapterModel: { base: 'z-image', type: 'controlnet' },
+        mainBase: 'z-image',
+      })
+    ).toBe('unsupported_adapter');
+  });
+
+  it('blocks a second Z-Image control', () => {
+    expect(
+      getControlValidationReason({
+        adapterModel: { base: 'z-image', type: 'controlnet' },
+        controlLoraIndex: 0,
+        kind: 'z_image_control',
+        mainBase: 'z-image',
+        beginEndStepPct: [0, 1],
+        weight: 0.75,
+        zImageControlIndex: 1,
+      })
+    ).toBe('z_image_control_limit');
+  });
+
+  it.each([
+    { beginEndStepPct: [0, 1] as [number, number], kind: 'controlnet' as const, weight: Number.NaN },
+    { beginEndStepPct: [0, 1] as [number, number], kind: 'controlnet' as const, weight: Number.POSITIVE_INFINITY },
+    { beginEndStepPct: [0, 1] as [number, number], kind: 'controlnet' as const, weight: -1.01 },
+    { beginEndStepPct: [0, 1] as [number, number], kind: 'controlnet' as const, weight: 2.01 },
+    { beginEndStepPct: [0, 1] as [number, number], kind: 'z_image_control' as const, weight: -0.01 },
+    { beginEndStepPct: [Number.NaN, 1] as [number, number], kind: 'controlnet' as const, weight: 0.75 },
+    { beginEndStepPct: [0, Number.POSITIVE_INFINITY] as [number, number], kind: 'controlnet' as const, weight: 0.75 },
+    { beginEndStepPct: [-0.01, 1] as [number, number], kind: 'controlnet' as const, weight: 0.75 },
+    { beginEndStepPct: [0, 1.01] as [number, number], kind: 'controlnet' as const, weight: 0.75 },
+    { beginEndStepPct: [0.5, 0.5] as [number, number], kind: 'controlnet' as const, weight: 0.75 },
+    { beginEndStepPct: [0.8, 0.2] as [number, number], kind: 'controlnet' as const, weight: 0.75 },
+  ])('rejects malformed adapter values %#', ({ beginEndStepPct, kind, weight }) => {
+    const zImage = kind === 'z_image_control';
+    expect(
+      getControlValidationReason({
+        ...valid,
+        adapterModel: { base: zImage ? 'z-image' : 'sd-1', type: 'controlnet' },
+        beginEndStepPct,
+        kind,
+        mainBase: zImage ? 'z-image' : 'sd-1',
+        weight,
+      })
+    ).toBe('invalid_adapter_values');
+  });
+
+  it('retains the legacy -1 lower weight bound for existing adapter kinds', () => {
+    expect(getControlValidationReason({ ...valid, weight: -1 })).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/controlValidation.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlValidation.ts
new file mode 100644
index 00000000000..af3c9c39148
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/controlValidation.ts
@@ -0,0 +1,73 @@
+export type ControlAdapterKind = 'controlnet' | 't2i_adapter' | 'control_lora' | 'z_image_control';
+
+export type ControlValidationReason =
+  | 'missing_model'
+  | 'unsupported_adapter'
+  | 'incompatible_base'
+  | 'incompatible_adapter'
+  | 'invalid_adapter_values'
+  | 'control_lora_limit'
+  | 'z_image_control_limit'
+  | 'flux_fill_control_lora';
+
+export const isControlKindSupportedForBase = (base: string, kind: ControlAdapterKind): boolean => {
+  if (kind === 'controlnet') {
+    return base === 'sd-1' || base === 'sdxl' || base === 'flux';
+  }
+  if (kind === 't2i_adapter') {
+    return base === 'sd-1' || base === 'sdxl';
+  }
+  if (kind === 'z_image_control') {
+    return base === 'z-image';
+  }
+  return base === 'flux';
+};
+
+export const getControlValidationReason = (params: {
+  adapterModel: { base: string; type: string } | null;
+  beginEndStepPct: [number, number];
+  controlLoraIndex: number;
+  kind: ControlAdapterKind;
+  mainBase: string;
+  mainVariant?: string;
+  weight: number;
+  zImageControlIndex?: number;
+}): ControlValidationReason | null => {
+  const {
+    adapterModel,
+    beginEndStepPct,
+    controlLoraIndex,
+    kind,
+    mainBase,
+    mainVariant,
+    weight,
+    zImageControlIndex = 0,
+  } = params;
+  if (!areControlAdapterValuesValid(kind, weight, beginEndStepPct)) {
+    return 'invalid_adapter_values';
+  }
+  if (!adapterModel) {
+    return 'missing_model';
+  }
+  if (!isControlKindSupportedForBase(mainBase, kind)) {
+    return 'unsupported_adapter';
+  }
+  if (adapterModel.base !== mainBase) {
+    return 'incompatible_base';
+  }
+  const expectedModelType = kind === 'z_image_control' ? 'controlnet' : kind;
+  if (adapterModel.type !== expectedModelType) {
+    return 'incompatible_adapter';
+  }
+  if (kind === 'control_lora' && controlLoraIndex > 0) {
+    return 'control_lora_limit';
+  }
+  if (kind === 'z_image_control' && zImageControlIndex > 0) {
+    return 'z_image_control_limit';
+  }
+  if (kind === 'control_lora' && mainBase === 'flux' && mainVariant === 'dev_fill') {
+    return 'flux_fill_control_lora';
+  }
+  return null;
+};
+import { areControlAdapterValuesValid } from '@workbench/controlAdapters';
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/filterGraphs.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/filterGraphs.test.ts
new file mode 100644
index 00000000000..c49f809facd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/filterGraphs.test.ts
@@ -0,0 +1,440 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildFilterDefaults,
+  buildFilterGraph,
+  CONTROL_FILTERS,
+  DEFAULT_CONTROL_FILTER_TYPE,
+  FILTER_NODE_ID,
+  getFilterNumberBounds,
+  getFilterDefinition,
+  isFilterConfigValid,
+  isSupportedFilterType,
+} from './filterGraphs';
+
+/** The exact legacy defaults for each supported filter — the spec under test. */
+const EXPECTED_DEFAULTS: Record<string, Record<string, unknown>> = {
+  canny_edge_detection: { low_threshold: 100, high_threshold: 200 },
+  depth_anything_depth_estimation: { model_size: 'small_v2' },
+  dw_openpose_detection: { draw_body: true, draw_face: true, draw_hands: true },
+  lineart_edge_detection: { coarse: false },
+  hed_edge_detection: { scribble: false },
+  mlsd_detection: { score_threshold: 0.1, distance_threshold: 20 },
+  pidi_edge_detection: { quantize_edges: false, scribble: false },
+  content_shuffle: { scale_factor: 256 },
+  mediapipe_face_detection: { max_faces: 1, min_confidence: 0.5 },
+  color_map: { tile_size: 64 },
+  adjust_image: { channel: 'Luminosity (LAB)', value: 1, scale_values: false },
+  lineart_anime_edge_detection: {},
+  normal_map: {},
+  spandrel_filter: { model: null, autoScale: true, scale: 1 },
+  img_blur: { blur_type: 'gaussian', radius: 8 },
+  img_noise: { noise_type: 'gaussian', amount: 0.3, noise_color: true, size: 1 },
+};
+
+const EXPECTED_TYPES = Object.keys(EXPECTED_DEFAULTS);
+const SPANDREL_MODEL = {
+  base: 'any',
+  hash: 'blake3-hash',
+  key: 'upscale',
+  name: 'Upscaler',
+  type: 'spandrel_image_to_image',
+};
+
+describe('CONTROL_FILTERS registry', () => {
+  it('contains exactly all sixteen legacy filter types', () => {
+    const types = CONTROL_FILTERS.map((definition) => definition.type);
+    expect(types).toHaveLength(16);
+    expect(new Set(types).size).toBe(16);
+    expect(types).toEqual(EXPECTED_TYPES);
+  });
+
+  it('projects each definition to its exact legacy defaults', () => {
+    for (const definition of CONTROL_FILTERS) {
+      expect(buildFilterDefaults(definition)).toEqual(EXPECTED_DEFAULTS[definition.type]);
+    }
+  });
+
+  it('names canny edge detection as the default control filter', () => {
+    expect(DEFAULT_CONTROL_FILTER_TYPE).toBe('canny_edge_detection');
+  });
+
+  it('declares localized labels for every enum option', () => {
+    for (const definition of CONTROL_FILTERS) {
+      for (const param of definition.params) {
+        if (param.kind === 'enum') {
+          expect(
+            param.options.every((option) => option.labelKey.startsWith('widgets.layers.control.filterOptions.'))
+          ).toBe(true);
+        }
+      }
+    }
+  });
+});
+
+describe('getFilterNumberBounds', () => {
+  it.each([
+    [
+      'canny_edge_detection',
+      'low_threshold',
+      {},
+      { inputMax: 255, inputMin: 0, sliderMax: 255, sliderMin: 0, step: 1 },
+    ],
+    [
+      'canny_edge_detection',
+      'high_threshold',
+      {},
+      { inputMax: 255, inputMin: 0, sliderMax: 255, sliderMin: 0, step: 1 },
+    ],
+    ['mlsd_detection', 'score_threshold', {}, { inputMax: 1, inputMin: 0, sliderMax: 1, sliderMin: 0, step: 0.01 }],
+    ['content_shuffle', 'scale_factor', {}, { inputMax: 4096, inputMin: 0, sliderMax: 4096, sliderMin: 0, step: 1 }],
+    ['mediapipe_face_detection', 'max_faces', {}, { inputMax: 20, inputMin: 1, sliderMax: 20, sliderMin: 1, step: 1 }],
+    [
+      'mediapipe_face_detection',
+      'min_confidence',
+      {},
+      { inputMax: 1, inputMin: 0, sliderMax: 1, sliderMin: 0, step: 0.01 },
+    ],
+    ['color_map', 'tile_size', {}, { inputMax: 4096, inputMin: 1, sliderMax: 256, sliderMin: 1, step: 1 }],
+    [
+      'mlsd_detection',
+      'distance_threshold',
+      {},
+      { inputMax: 1000, inputMin: 0, sliderMax: 100, sliderMin: 0, step: 1 },
+    ],
+    ['spandrel_filter', 'scale', {}, { inputMax: 16, inputMin: 1, sliderMax: 16, sliderMin: 1, step: 1 }],
+    ['img_blur', 'radius', {}, { inputMax: 4096, inputMin: 1, sliderMax: 64, sliderMin: 1, step: 0.1 }],
+    ['img_noise', 'amount', {}, { inputMax: 1, inputMin: 0, sliderMax: 1, sliderMin: 0, step: 0.01 }],
+    ['img_noise', 'size', {}, { inputMax: 256, inputMin: 1, sliderMax: 16, sliderMin: 1, step: 1 }],
+  ])('returns legacy slider and numeric bounds for %s.%s', (type, key, settings, expected) => {
+    const param = getFilterDefinition(type)?.params.find((candidate) => candidate.key === key);
+    if (param?.kind !== 'number') {
+      throw new Error(`Missing number param ${type}.${key}`);
+    }
+    expect(getFilterNumberBounds(param, settings)).toEqual(expected);
+  });
+
+  it('keeps independent legacy adjust slider and numeric bounds in both modes', () => {
+    const param = getFilterDefinition('adjust_image')?.params.find((candidate) => candidate.key === 'value');
+    if (param?.kind !== 'number') {
+      throw new Error('Missing adjust_image.value');
+    }
+    const expected = { inputMax: 255, inputMin: 0, sliderMax: 2, sliderMin: 0, step: 0.0025 };
+    expect(getFilterNumberBounds(param, { scale_values: false })).toEqual(expected);
+    expect(getFilterNumberBounds(param, { scale_values: true })).toEqual(expected);
+  });
+});
+
+describe('isSupportedFilterType / getFilterDefinition', () => {
+  it('recognises every supported filter', () => {
+    for (const type of EXPECTED_TYPES) {
+      expect(isSupportedFilterType(type)).toBe(true);
+      expect(getFilterDefinition(type)?.type).toBe(type);
+    }
+  });
+
+  it('rejects an unknown filter type', () => {
+    expect(isSupportedFilterType('not_a_filter')).toBe(false);
+    expect(getFilterDefinition('not_a_filter')).toBeUndefined();
+  });
+});
+
+describe('buildFilterGraph', () => {
+  const imageName = 'source-image.png';
+
+  it('builds the direct legacy filter nodes with default params', () => {
+    const directTypes = EXPECTED_TYPES.filter(
+      (type) => !['adjust_image', 'spandrel_filter', 'img_blur', 'img_noise'].includes(type)
+    );
+    for (const type of directTypes) {
+      const { graph, outputNodeId } = buildFilterGraph(type, imageName);
+
+      expect(outputNodeId).toBe(FILTER_NODE_ID);
+      expect(graph.edges).toEqual([]);
+      expect(typeof graph.id).toBe('string');
+      expect(graph.id).toContain(type);
+      expect(Object.keys(graph.nodes)).toEqual([FILTER_NODE_ID]);
+
+      const node = graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+      expect(node.id).toBe(FILTER_NODE_ID);
+      expect(node.type).toBe(type);
+      expect(node.image).toEqual({ image_name: imageName });
+      // Previews run intermediate (out of the gallery, GC-eligible); only Apply
+      // promotes the chosen image to durable via makeImageDurable.
+      expect(node.is_intermediate).toBe(true);
+      expect(node.use_cache).toBe(true);
+
+      // Every default param field is present on the node.
+      for (const [key, value] of Object.entries(EXPECTED_DEFAULTS[type])) {
+        expect(node[key]).toBe(value);
+      }
+    }
+  });
+
+  it('builds adjust_image as offset or channel multiply', () => {
+    const offset = buildFilterGraph('adjust_image', imageName).graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(offset).toMatchObject({
+      channel: 'Luminosity (LAB)',
+      image: { image_name: imageName },
+      offset: 0,
+      type: 'img_channel_offset',
+    });
+
+    const multiplied = buildFilterGraph('adjust_image', imageName, {
+      channel: 'Red (RGBA)',
+      scale_values: true,
+      value: 1.5,
+    }).graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(multiplied).toMatchObject({
+      channel: 'Red (RGBA)',
+      image: { image_name: imageName },
+      invert_channel: false,
+      scale: 1.5,
+      type: 'img_channel_multiply',
+    });
+
+    const multipliedAtLegacyMax = buildFilterGraph('adjust_image', imageName, {
+      scale_values: true,
+      value: 999,
+    }).graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(multipliedAtLegacyMax.scale).toBe(255);
+
+    const offsetAtMax = buildFilterGraph('adjust_image', imageName, {
+      scale_values: false,
+      value: 255,
+    }).graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(offsetAtMax.offset).toBe(255);
+  });
+
+  it('builds padded gaussian blur with alpha nudge wiring', () => {
+    const { graph, outputNodeId } = buildFilterGraph('img_blur', imageName);
+    expect(graph.nodes.control_filter_pad).toMatchObject({
+      bottom: 24,
+      image: { image_name: imageName },
+      left: 24,
+      right: 24,
+      top: 24,
+      type: 'img_pad_crop',
+    });
+    expect(graph.nodes[FILTER_NODE_ID]).toMatchObject({ blur_type: 'gaussian', radius: 8, type: 'img_blur' });
+    expect(graph.nodes.control_filter_alpha).toMatchObject({
+      channel: 'Alpha (RGBA)',
+      offset: 1,
+      type: 'img_channel_offset',
+    });
+    expect(graph.edges).toEqual([
+      {
+        destination: { field: 'image', node_id: FILTER_NODE_ID },
+        source: { field: 'image', node_id: 'control_filter_pad' },
+      },
+      {
+        destination: { field: 'image', node_id: 'control_filter_alpha' },
+        source: { field: 'image', node_id: FILTER_NODE_ID },
+      },
+    ]);
+    expect(outputNodeId).toBe('control_filter_alpha');
+  });
+
+  it('builds zero-radius blur directly without padding', () => {
+    const { graph, outputNodeId } = buildFilterGraph('img_blur', imageName, { radius: 0 });
+    expect(Object.keys(graph.nodes)).toEqual([FILTER_NODE_ID]);
+    expect(graph.nodes[FILTER_NODE_ID]).toMatchObject({ image: { image_name: imageName }, radius: 0 });
+    expect(graph.edges).toEqual([]);
+    expect(outputNodeId).toBe(FILTER_NODE_ID);
+  });
+
+  it('builds noise with an uncached rand_int seed edge', () => {
+    const { graph } = buildFilterGraph('img_noise', imageName);
+    expect(graph.nodes[FILTER_NODE_ID]).toMatchObject({ amount: 0.3, noise_color: true, size: 1, type: 'img_noise' });
+    expect(graph.nodes.control_filter_seed).toMatchObject({
+      high: 2147483647,
+      low: 0,
+      type: 'rand_int',
+      use_cache: false,
+    });
+    expect(graph.edges).toContainEqual({
+      destination: { field: 'seed', node_id: FILTER_NODE_ID },
+      source: { field: 'value', node_id: 'control_filter_seed' },
+    });
+  });
+
+  it('builds Spandrel autoscale and direct nodes and rejects a missing model', () => {
+    expect(() => buildFilterGraph('spandrel_filter', imageName)).toThrow(/model/i);
+    expect(
+      buildFilterGraph('spandrel_filter', imageName, { model: SPANDREL_MODEL, scale: 4 }).graph.nodes[FILTER_NODE_ID]
+    ).toMatchObject({
+      image_to_image_model: SPANDREL_MODEL,
+      scale: 4,
+      type: 'spandrel_image_to_image_autoscale',
+    });
+    const direct = buildFilterGraph('spandrel_filter', imageName, { autoScale: false, model: SPANDREL_MODEL }).graph
+      .nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(direct).toMatchObject({ image_to_image_model: SPANDREL_MODEL, type: 'spandrel_image_to_image' });
+    expect(direct.scale).toBeUndefined();
+  });
+
+  it('clamps and coerces persisted numeric settings to declared bounds', () => {
+    const canny = buildFilterGraph('canny_edge_detection', imageName, {
+      high_threshold: 999,
+      low_threshold: -12.8,
+    }).graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(canny.low_threshold).toBe(0);
+    expect(canny.high_threshold).toBe(255);
+
+    const noise = buildFilterGraph('img_noise', imageName, { amount: -2, size: 0.2 }).graph.nodes[
+      FILTER_NODE_ID
+    ] as Record<string, unknown>;
+    expect(noise.amount).toBe(0);
+    expect(noise.size).toBe(1);
+  });
+
+  it('coerces malformed persisted settings for every parameter of all sixteen filters', () => {
+    for (const definition of CONTROL_FILTERS) {
+      const malformed: Record<string, unknown> = Object.fromEntries(
+        definition.params.map((param) => [param.key, param.kind === 'boolean' ? 'false' : { invalid: true }])
+      );
+      if (definition.type === 'spandrel_filter') {
+        malformed.model = SPANDREL_MODEL;
+      }
+      const node = buildFilterGraph(definition.type, imageName, malformed).graph.nodes[FILTER_NODE_ID] as Record<
+        string,
+        unknown
+      >;
+      for (const param of definition.params) {
+        if (param.kind === 'model') {
+          continue;
+        }
+        const projectedKey = definition.type === 'adjust_image' && param.key === 'value' ? 'offset' : param.key;
+        if (definition.type === 'adjust_image' && param.key === 'value') {
+          expect(node[projectedKey], definition.type).toBe(0);
+        } else if (
+          (definition.type !== 'adjust_image' || param.key !== 'scale_values') &&
+          (definition.type !== 'spandrel_filter' || param.key !== 'autoScale')
+        ) {
+          expect(node[projectedKey], `${definition.type}.${param.key}`).toBe(param.default);
+        }
+      }
+    }
+  });
+
+  it('clamps every declared numeric parameter at both bounds', () => {
+    for (const definition of CONTROL_FILTERS) {
+      for (const param of definition.params) {
+        if (param.kind !== 'number') {
+          continue;
+        }
+        const lowSettings = { model: SPANDREL_MODEL, [param.key]: Number.MIN_SAFE_INTEGER };
+        const highSettings = { model: SPANDREL_MODEL, [param.key]: Number.MAX_SAFE_INTEGER };
+        const low = buildFilterGraph(definition.type, imageName, lowSettings).graph.nodes[FILTER_NODE_ID] as Record<
+          string,
+          unknown
+        >;
+        const high = buildFilterGraph(definition.type, imageName, highSettings).graph.nodes[FILTER_NODE_ID] as Record<
+          string,
+          unknown
+        >;
+        if (definition.type === 'adjust_image' && param.key === 'value') {
+          expect(low.offset).toBe(-255);
+          expect(high.offset).toBe(255);
+        } else if (param.min !== undefined) {
+          expect(low[param.key], `${definition.type}.${param.key}.min`).toBe(param.coerceMin ?? param.min);
+        }
+        if (param.max !== undefined && !(definition.type === 'adjust_image' && param.key === 'value')) {
+          expect(high[param.key], `${definition.type}.${param.key}.max`).toBe(param.max);
+        }
+      }
+    }
+  });
+
+  it('requires a complete nonempty backend Spandrel model identifier', () => {
+    expect(isFilterConfigValid('spandrel_filter', { model: SPANDREL_MODEL })).toBe(true);
+    for (const field of ['key', 'hash', 'name', 'base', 'type'] as const) {
+      expect(isFilterConfigValid('spandrel_filter', { model: { ...SPANDREL_MODEL, [field]: '' } }), field).toBe(false);
+    }
+    expect(isFilterConfigValid('spandrel_filter', { model: { ...SPANDREL_MODEL, type: 'controlnet' } })).toBe(false);
+    expect(() => buildFilterGraph('spandrel_filter', imageName, { model: { ...SPANDREL_MODEL, hash: '' } })).toThrow(
+      /model/i
+    );
+  });
+
+  it('applies valid custom settings, overriding defaults', () => {
+    const { graph } = buildFilterGraph('canny_edge_detection', imageName, {
+      low_threshold: 50,
+      high_threshold: 220,
+    });
+    const node = graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(node.low_threshold).toBe(50);
+    expect(node.high_threshold).toBe(220);
+  });
+
+  it('rounds non-integer values for integer params', () => {
+    const { graph } = buildFilterGraph('canny_edge_detection', imageName, {
+      low_threshold: 50.4,
+      high_threshold: 199.6,
+    });
+    const node = graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(node.low_threshold).toBe(50);
+    expect(node.high_threshold).toBe(200);
+  });
+
+  it('accepts a finite non-integer for a non-integer number param', () => {
+    const { graph } = buildFilterGraph('mediapipe_face_detection', imageName, {
+      min_confidence: 0.75,
+    });
+    const node = graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(node.min_confidence).toBe(0.75);
+  });
+
+  it('falls back to the default for wrong-typed number settings', () => {
+    const badString = buildFilterGraph('canny_edge_detection', imageName, {
+      low_threshold: 'bad',
+    });
+    expect((badString.graph.nodes[FILTER_NODE_ID] as Record<string, unknown>).low_threshold).toBe(100);
+
+    const nan = buildFilterGraph('canny_edge_detection', imageName, {
+      low_threshold: Number.NaN,
+    });
+    expect((nan.graph.nodes[FILTER_NODE_ID] as Record<string, unknown>).low_threshold).toBe(100);
+  });
+
+  it('falls back to the default for an unknown enum value', () => {
+    const { graph } = buildFilterGraph('depth_anything_depth_estimation', imageName, {
+      model_size: 'nonsense',
+    });
+    expect((graph.nodes[FILTER_NODE_ID] as Record<string, unknown>).model_size).toBe('small_v2');
+  });
+
+  it('accepts a valid enum value', () => {
+    const { graph } = buildFilterGraph('depth_anything_depth_estimation', imageName, {
+      model_size: 'large',
+    });
+    expect((graph.nodes[FILTER_NODE_ID] as Record<string, unknown>).model_size).toBe('large');
+  });
+
+  it('falls back to the default for a non-boolean boolean setting', () => {
+    const { graph } = buildFilterGraph('dw_openpose_detection', imageName, {
+      draw_body: 'yes',
+      draw_face: 1,
+    });
+    const node = graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(node.draw_body).toBe(true);
+    expect(node.draw_face).toBe(true);
+    expect(node.draw_hands).toBe(true);
+  });
+
+  it('honours a valid boolean override', () => {
+    const { graph } = buildFilterGraph('lineart_edge_detection', imageName, { coarse: true });
+    expect((graph.nodes[FILTER_NODE_ID] as Record<string, unknown>).coarse).toBe(true);
+  });
+
+  it('ignores unknown setting keys', () => {
+    const { graph } = buildFilterGraph('color_map', imageName, { unknown_key: 999 });
+    const node = graph.nodes[FILTER_NODE_ID] as Record<string, unknown>;
+    expect(node.tile_size).toBe(64);
+    expect(node.unknown_key).toBeUndefined();
+  });
+
+  it('throws for an unknown filter type', () => {
+    expect(() => buildFilterGraph('not_a_filter', imageName)).toThrow();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/filterGraphs.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/filterGraphs.ts
new file mode 100644
index 00000000000..65db2a02994
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/filterGraphs.ts
@@ -0,0 +1,438 @@
+/**
+ * Pure control-filter graph builders (legacy parity).
+ *
+ * A control layer can non-destructively preview a filter (canny, depth, pose, …)
+ * over its composited source. This module names each supported filter, its
+ * legacy-default settings, and the one-node backend graph it compiles to — with
+ * NO fetch, NO engine, NO React. The executor composites + uploads the layer's
+ * source image, then {@link buildFilterGraph} shapes the graph the utility queue
+ * runs; its `outputNodeId` names the node whose output image is the preview.
+ *
+ * Node type strings + defaults mirror legacy
+ * `features/controlLayers/store/filters.ts` (`IMAGE_FILTERS`): every filter here
+ * builds the exact backend nodes used by legacy, fed `image: { image_name }`
+ * plus the filter's parameters. The registry is the spec — settings editors
+ * read `buildDefaults()` and the param metadata.
+ */
+
+import type { BackendGraphContract } from '@workbench/types';
+
+/** The deterministic node id every single-node filter graph uses. */
+export const FILTER_NODE_ID = 'control_filter';
+
+/** A filter parameter's UI + validation metadata (drives the settings editor). */
+export type FilterParamSpec =
+  | {
+      kind: 'number';
+      key: string;
+      default: number;
+      min: number;
+      max: number;
+      step: number;
+      integer?: boolean;
+      sliderMin?: number;
+      sliderMax?: number;
+      coerceMin?: number;
+    }
+  | { kind: 'boolean'; key: string; default: boolean }
+  | {
+      kind: 'enum';
+      key: string;
+      default: string;
+      options: readonly { labelKey: string; value: string }[];
+    }
+  | { kind: 'string'; key: string; default: string }
+  | { kind: 'model'; key: string; default: null; modelType: 'spandrel_image_to_image' };
+
+/** One filter's identity, defaults, and node-arg projection. */
+export interface FilterDefinition {
+  /** The filter id (equals the backend node `type`). */
+  type: string;
+  /** Ordered parameter specs (also the default-settings source). */
+  params: readonly FilterParamSpec[];
+}
+
+/** Builds the default settings object for a filter definition. */
+export const buildFilterDefaults = (definition: FilterDefinition): Record<string, unknown> => {
+  const settings: Record<string, unknown> = {};
+  for (const param of definition.params) {
+    settings[param.key] = param.default;
+  }
+  return settings;
+};
+
+/**
+ * The supported filters, in the legacy display order of the required set
+ * (`features/controlLayers/store/filters.ts`). Each id equals its backend node
+ * `type`; params carry legacy defaults + ranges.
+ */
+export const CONTROL_FILTERS: readonly FilterDefinition[] = [
+  {
+    params: [
+      { default: 100, integer: true, key: 'low_threshold', kind: 'number', max: 255, min: 0, step: 1 },
+      { default: 200, integer: true, key: 'high_threshold', kind: 'number', max: 255, min: 0, step: 1 },
+    ],
+    type: 'canny_edge_detection',
+  },
+  {
+    params: [
+      {
+        default: 'small_v2',
+        key: 'model_size',
+        kind: 'enum',
+        options: [
+          { labelKey: 'widgets.layers.control.filterOptions.model_size.large', value: 'large' },
+          { labelKey: 'widgets.layers.control.filterOptions.model_size.base', value: 'base' },
+          { labelKey: 'widgets.layers.control.filterOptions.model_size.small', value: 'small' },
+          { labelKey: 'widgets.layers.control.filterOptions.model_size.small_v2', value: 'small_v2' },
+        ],
+      },
+    ],
+    type: 'depth_anything_depth_estimation',
+  },
+  {
+    params: [
+      { default: true, key: 'draw_body', kind: 'boolean' },
+      { default: true, key: 'draw_face', kind: 'boolean' },
+      { default: true, key: 'draw_hands', kind: 'boolean' },
+    ],
+    type: 'dw_openpose_detection',
+  },
+  {
+    params: [{ default: false, key: 'coarse', kind: 'boolean' }],
+    type: 'lineart_edge_detection',
+  },
+  {
+    params: [{ default: false, key: 'scribble', kind: 'boolean' }],
+    type: 'hed_edge_detection',
+  },
+  {
+    params: [
+      { default: 0.1, key: 'score_threshold', kind: 'number', max: 1, min: 0, step: 0.01 },
+      { default: 20, key: 'distance_threshold', kind: 'number', max: 1000, min: 0, sliderMax: 100, step: 1 },
+    ],
+    type: 'mlsd_detection',
+  },
+  {
+    params: [
+      { default: false, key: 'quantize_edges', kind: 'boolean' },
+      { default: false, key: 'scribble', kind: 'boolean' },
+    ],
+    type: 'pidi_edge_detection',
+  },
+  {
+    params: [{ default: 256, integer: true, key: 'scale_factor', kind: 'number', max: 4096, min: 0, step: 1 }],
+    type: 'content_shuffle',
+  },
+  {
+    params: [
+      { default: 1, integer: true, key: 'max_faces', kind: 'number', max: 20, min: 1, step: 1 },
+      { default: 0.5, key: 'min_confidence', kind: 'number', max: 1, min: 0, step: 0.01 },
+    ],
+    type: 'mediapipe_face_detection',
+  },
+  {
+    params: [
+      { default: 64, integer: true, key: 'tile_size', kind: 'number', max: 4096, min: 1, sliderMax: 256, step: 1 },
+    ],
+    type: 'color_map',
+  },
+  {
+    params: [
+      {
+        default: 'Luminosity (LAB)',
+        key: 'channel',
+        kind: 'enum',
+        options: [
+          { labelKey: 'widgets.layers.control.filterOptions.channel.red', value: 'Red (RGBA)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.green', value: 'Green (RGBA)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.blue', value: 'Blue (RGBA)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.alpha', value: 'Alpha (RGBA)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.cyan', value: 'Cyan (CMYK)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.magenta', value: 'Magenta (CMYK)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.yellow', value: 'Yellow (CMYK)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.black', value: 'Black (CMYK)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.hue', value: 'Hue (HSV)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.saturation', value: 'Saturation (HSV)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.value', value: 'Value (HSV)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.luminosity', value: 'Luminosity (LAB)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.lab_a', value: 'A (LAB)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.lab_b', value: 'B (LAB)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.y', value: 'Y (YCbCr)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.cb', value: 'Cb (YCbCr)' },
+          { labelKey: 'widgets.layers.control.filterOptions.channel.cr', value: 'Cr (YCbCr)' },
+        ],
+      },
+      { default: 1, key: 'value', kind: 'number', max: 255, min: 0, sliderMax: 2, step: 0.0025 },
+      { default: false, key: 'scale_values', kind: 'boolean' },
+    ],
+    type: 'adjust_image',
+  },
+  { params: [], type: 'lineart_anime_edge_detection' },
+  { params: [], type: 'normal_map' },
+  {
+    params: [
+      { default: null, key: 'model', kind: 'model', modelType: 'spandrel_image_to_image' },
+      { default: true, key: 'autoScale', kind: 'boolean' },
+      { default: 1, key: 'scale', kind: 'number', max: 16, min: 1, step: 1 },
+    ],
+    type: 'spandrel_filter',
+  },
+  {
+    params: [
+      {
+        default: 'gaussian',
+        key: 'blur_type',
+        kind: 'enum',
+        options: [
+          { labelKey: 'widgets.layers.control.filterOptions.blur_type.gaussian', value: 'gaussian' },
+          { labelKey: 'widgets.layers.control.filterOptions.blur_type.box', value: 'box' },
+        ],
+      },
+      { coerceMin: 0, default: 8, key: 'radius', kind: 'number', max: 4096, min: 1, sliderMax: 64, step: 0.1 },
+    ],
+    type: 'img_blur',
+  },
+  {
+    params: [
+      {
+        default: 'gaussian',
+        key: 'noise_type',
+        kind: 'enum',
+        options: [
+          { labelKey: 'widgets.layers.control.filterOptions.noise_type.gaussian', value: 'gaussian' },
+          {
+            labelKey: 'widgets.layers.control.filterOptions.noise_type.salt_and_pepper',
+            value: 'salt_and_pepper',
+          },
+        ],
+      },
+      { default: 0.3, key: 'amount', kind: 'number', max: 1, min: 0, step: 0.01 },
+      { default: true, key: 'noise_color', kind: 'boolean' },
+      { default: 1, integer: true, key: 'size', kind: 'number', max: 256, min: 1, sliderMax: 16, step: 1 },
+    ],
+    type: 'img_noise',
+  },
+];
+
+const FILTERS_BY_TYPE: ReadonlyMap<string, FilterDefinition> = new Map(
+  CONTROL_FILTERS.map((definition) => [definition.type, definition])
+);
+
+/** The default filter type applied when a control layer's filter section is enabled. */
+export const DEFAULT_CONTROL_FILTER_TYPE = 'canny_edge_detection';
+
+/** Looks up a filter definition by its type id (`undefined` for unknown filters). */
+export const getFilterDefinition = (type: string): FilterDefinition | undefined => FILTERS_BY_TYPE.get(type);
+
+/** True when `type` names a supported control filter. */
+export const isSupportedFilterType = (type: string): boolean => FILTERS_BY_TYPE.has(type);
+
+export interface FilterNumberBounds {
+  inputMax: number;
+  inputMin: number;
+  sliderMax: number;
+  sliderMin: number;
+  step: number;
+}
+
+/** Resolves independently declared legacy slider and numeric-input ranges. */
+export const getFilterNumberBounds = (
+  param: Extract<FilterParamSpec, { kind: 'number' }>,
+  _settings: Record<string, unknown>
+): FilterNumberBounds => {
+  return {
+    inputMax: param.max,
+    inputMin: param.min,
+    sliderMax: param.sliderMax ?? param.max,
+    sliderMin: param.sliderMin ?? param.min,
+    step: param.step,
+  };
+};
+
+const isNonemptyStringField = (value: object, key: string): boolean =>
+  key in value &&
+  typeof (value as Record<string, unknown>)[key] === 'string' &&
+  ((value as Record<string, unknown>)[key] as string).trim().length > 0;
+
+export const isSpandrelModelIdentifier = (value: unknown): boolean =>
+  typeof value === 'object' &&
+  value !== null &&
+  ['key', 'hash', 'name', 'base', 'type'].every((key) => isNonemptyStringField(value, key)) &&
+  (value as { type: string }).type === 'spandrel_image_to_image';
+
+/** True when settings contain everything required to run the selected filter. */
+export const isFilterConfigValid = (type: string, settings: Record<string, unknown>): boolean => {
+  if (type !== 'spandrel_filter') {
+    return FILTERS_BY_TYPE.has(type);
+  }
+  return isSpandrelModelIdentifier(settings.model);
+};
+
+/** Coerces arbitrary stored settings to the filter's params, falling back to each default. */
+const resolveSettings = (
+  definition: FilterDefinition,
+  settings: Record<string, unknown> | undefined
+): Record<string, unknown> => {
+  const resolved: Record<string, unknown> = {};
+  for (const param of definition.params) {
+    const value = settings?.[param.key];
+    if (param.kind === 'number' && typeof value === 'number' && Number.isFinite(value)) {
+      const bounds = getFilterNumberBounds(param, settings ?? {});
+      const clamped = Math.min(bounds.inputMax, Math.max(param.coerceMin ?? bounds.inputMin, value));
+      resolved[param.key] = param.integer ? Math.round(clamped) : clamped;
+    } else if (param.kind === 'boolean' && typeof value === 'boolean') {
+      resolved[param.key] = value;
+    } else if (
+      param.kind === 'enum' &&
+      typeof value === 'string' &&
+      param.options.some((option) => option.value === value)
+    ) {
+      resolved[param.key] = value;
+    } else if (param.kind === 'string' && typeof value === 'string') {
+      resolved[param.key] = value;
+    } else if (
+      param.kind === 'model' &&
+      param.modelType === 'spandrel_image_to_image' &&
+      isSpandrelModelIdentifier(value)
+    ) {
+      resolved[param.key] = value;
+    } else {
+      resolved[param.key] = param.default;
+    }
+  }
+  return resolved;
+};
+
+/** The result of {@link buildFilterGraph}: a one-node graph + the output node id. */
+export interface FilterGraphResult {
+  graph: BackendGraphContract;
+  outputNodeId: string;
+}
+
+/**
+ * Builds the single-node filter graph for `filterType` over `imageName`. Throws
+ * for an unknown filter type. Unknown / out-of-range settings fall back to the
+ * filter's legacy defaults, so a malformed persisted `filter.settings` still
+ * produces a valid graph. The output image is INTERMEDIATE (`is_intermediate:
+ * true`): every preview click runs this graph, and an intermediate output stays
+ * out of the gallery and is garbage-collected. Only on "Apply" does the caller
+ * promote the chosen image to durable (`makeImageDurable`), so it survives as
+ * the layer's new source without every preview littering the gallery.
+ */
+export const buildFilterGraph = (
+  filterType: string,
+  imageName: string,
+  settings?: Record<string, unknown>
+): FilterGraphResult => {
+  const definition = FILTERS_BY_TYPE.get(filterType);
+  if (!definition) {
+    throw new Error(`Unknown control filter "${filterType}".`);
+  }
+
+  const resolved = resolveSettings(definition, settings);
+  const node = {
+    id: FILTER_NODE_ID,
+    image: { image_name: imageName },
+    is_intermediate: true,
+    type: definition.type,
+    use_cache: true,
+    ...resolved,
+  };
+
+  const graph: BackendGraphContract = {
+    edges: [],
+    id: `control-filter-${definition.type}`,
+    nodes: { [FILTER_NODE_ID]: node },
+  };
+  const edge = (sourceId: string, sourceField: string, destinationId: string, destinationField: string): void => {
+    graph.edges.push({
+      destination: { field: destinationField, node_id: destinationId },
+      source: { field: sourceField, node_id: sourceId },
+    });
+  };
+
+  if (filterType === 'adjust_image') {
+    const { channel, scale_values: scaleValues, value } = resolved;
+    graph.nodes[FILTER_NODE_ID] = scaleValues
+      ? {
+          ...node,
+          channel,
+          invert_channel: false,
+          scale: value,
+          scale_values: undefined,
+          type: 'img_channel_multiply',
+          value: undefined,
+        }
+      : {
+          ...node,
+          channel,
+          offset: Math.round(255 * (Math.min(value as number, 2) - 1)),
+          scale_values: undefined,
+          type: 'img_channel_offset',
+          value: undefined,
+        };
+  } else if (filterType === 'spandrel_filter') {
+    const model = resolved.model;
+    if (!model) {
+      throw new Error('Spandrel filter requires an image-to-image model.');
+    }
+    graph.nodes[FILTER_NODE_ID] = resolved.autoScale
+      ? {
+          ...node,
+          autoScale: undefined,
+          image_to_image_model: model,
+          model: undefined,
+          type: 'spandrel_image_to_image_autoscale',
+        }
+      : {
+          ...node,
+          autoScale: undefined,
+          image_to_image_model: model,
+          model: undefined,
+          scale: undefined,
+          type: 'spandrel_image_to_image',
+        };
+  } else if (filterType === 'img_blur') {
+    const radius = resolved.radius as number;
+    const padding = Math.max(0, Math.ceil(radius * (resolved.blur_type === 'gaussian' ? 3 : 1)));
+    if (padding > 0) {
+      delete graph.nodes[FILTER_NODE_ID]!.image;
+      graph.nodes.control_filter_pad = {
+        bottom: padding,
+        id: 'control_filter_pad',
+        image: { image_name: imageName },
+        left: padding,
+        right: padding,
+        top: padding,
+        type: 'img_pad_crop',
+        use_cache: true,
+      };
+      graph.nodes.control_filter_alpha = {
+        channel: 'Alpha (RGBA)',
+        id: 'control_filter_alpha',
+        is_intermediate: true,
+        offset: 1,
+        type: 'img_channel_offset',
+        use_cache: true,
+      };
+      edge('control_filter_pad', 'image', FILTER_NODE_ID, 'image');
+      edge(FILTER_NODE_ID, 'image', 'control_filter_alpha', 'image');
+      return { graph, outputNodeId: 'control_filter_alpha' };
+    }
+  } else if (filterType === 'img_noise') {
+    graph.nodes.control_filter_seed = {
+      high: 2147483647,
+      id: 'control_filter_seed',
+      low: 0,
+      type: 'rand_int',
+      use_cache: false,
+    };
+    edge('control_filter_seed', 'value', FILTER_NODE_ID, 'seed');
+  }
+
+  return {
+    graph,
+    outputNodeId: FILTER_NODE_ID,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/samGraph.test.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/samGraph.test.ts
new file mode 100644
index 00000000000..4297f0f95ee
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/samGraph.test.ts
@@ -0,0 +1,359 @@
+import type { BackendGraphEdgeContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { buildSamGraph, documentToExportLocalSamInput, isSamDocumentInputValid, isSamInputValid } from './samGraph';
+
+const edge = (
+  sourceNodeId: string,
+  sourceField: string,
+  targetNodeId: string,
+  targetField: string
+): BackendGraphEdgeContract => ({
+  destination: { field: targetField, node_id: targetNodeId },
+  source: { field: sourceField, node_id: sourceNodeId },
+});
+
+const baseNodes = {
+  'sam-output': {
+    id: 'sam-output',
+    image: { image_name: 'source.png' },
+    invert: false,
+    is_intermediate: true,
+    type: 'apply_tensor_mask_to_image',
+    use_cache: true,
+  },
+  'sam-source': {
+    id: 'sam-source',
+    image: { image_name: 'source.png' },
+    is_intermediate: true,
+    type: 'image',
+    use_cache: true,
+  },
+};
+
+describe('buildSamGraph', () => {
+  it('builds the exact prompt graph through Grounding DINO', () => {
+    const { graph, outputNodeId } = buildSamGraph({
+      applyPolygonRefinement: false,
+      imageName: 'source.png',
+      input: { prompt: '  cat  ', type: 'prompt' },
+      invert: false,
+      model: 'segment-anything-2-large',
+    });
+
+    expect(outputNodeId).toBe('sam-output');
+    expect(graph).toEqual({
+      edges: [
+        edge('sam-source', 'image', 'sam-segment', 'image'),
+        edge('sam-source', 'image', 'sam-detect', 'image'),
+        edge('sam-detect', 'collection', 'sam-segment', 'bounding_boxes'),
+        edge('sam-segment', 'mask', 'sam-output', 'mask'),
+      ],
+      id: 'select-object-sam',
+      nodes: {
+        ...baseNodes,
+        'sam-detect': {
+          detection_threshold: 0.3,
+          id: 'sam-detect',
+          is_intermediate: true,
+          model: 'grounding-dino-base',
+          prompt: 'cat',
+          type: 'grounding_dino',
+          use_cache: true,
+        },
+        'sam-segment': {
+          apply_polygon_refinement: false,
+          id: 'sam-segment',
+          is_intermediate: true,
+          mask_filter: 'largest',
+          model: 'segment-anything-2-large',
+          type: 'segment_anything',
+          use_cache: true,
+        },
+      },
+    });
+  });
+
+  it('builds the exact point-only visual graph with include and exclude labels', () => {
+    const { graph } = buildSamGraph({
+      applyPolygonRefinement: false,
+      imageName: 'source.png',
+      input: {
+        bbox: null,
+        excludePoints: [{ x: 7, y: 8 }],
+        includePoints: [
+          { x: 1, y: 2 },
+          { x: 3, y: 4 },
+        ],
+        type: 'visual',
+      },
+      invert: false,
+      model: 'segment-anything-2-large',
+    });
+
+    expect(graph.edges).toEqual([
+      edge('sam-source', 'image', 'sam-segment', 'image'),
+      edge('sam-segment', 'mask', 'sam-output', 'mask'),
+    ]);
+    expect(graph.nodes['sam-segment']).toEqual({
+      apply_polygon_refinement: false,
+      id: 'sam-segment',
+      is_intermediate: true,
+      mask_filter: 'largest',
+      model: 'segment-anything-2-large',
+      point_lists: [
+        {
+          points: [
+            { label: 1, x: 1, y: 2 },
+            { label: 1, x: 3, y: 4 },
+            { label: -1, x: 7, y: 8 },
+          ],
+        },
+      ],
+      type: 'segment_anything',
+      use_cache: true,
+    });
+  });
+
+  it('builds the exact bbox-only visual graph', () => {
+    const { graph } = buildSamGraph({
+      applyPolygonRefinement: false,
+      imageName: 'source.png',
+      input: {
+        bbox: { height: 20, width: 10, x: 2, y: 3 },
+        excludePoints: [],
+        includePoints: [],
+        type: 'visual',
+      },
+      invert: false,
+      model: 'segment-anything-2-large',
+    });
+
+    expect(graph.nodes['sam-segment']).toMatchObject({
+      bounding_boxes: [{ x_max: 12, x_min: 2, y_max: 23, y_min: 3 }],
+    });
+    expect(graph.nodes['sam-segment']).not.toHaveProperty('point_lists');
+  });
+
+  it('aligns point and bbox lists for a combined visual graph', () => {
+    const { graph } = buildSamGraph({
+      applyPolygonRefinement: true,
+      imageName: 'source.png',
+      input: {
+        bbox: { height: 4, width: 3, x: 2, y: 1 },
+        excludePoints: [],
+        includePoints: [{ x: 3, y: 2 }],
+        type: 'visual',
+      },
+      invert: true,
+      model: 'segment-anything-huge',
+    });
+
+    expect(graph.nodes['sam-segment']).toMatchObject({
+      apply_polygon_refinement: true,
+      bounding_boxes: [{ x_max: 5, x_min: 2, y_max: 5, y_min: 1 }],
+      model: 'segment-anything-huge',
+      point_lists: [{ points: [{ label: 1, x: 3, y: 2 }] }],
+    });
+    expect(graph.nodes['sam-output']).toMatchObject({ invert: true });
+  });
+
+  it.each([
+    { prompt: '   ', type: 'prompt' } as const,
+    { bbox: null, excludePoints: [], includePoints: [], type: 'visual' } as const,
+    {
+      bbox: { height: 2, width: -1, x: 0, y: 0 },
+      excludePoints: [],
+      includePoints: [],
+      type: 'visual',
+    } as const,
+  ])('rejects invalid input $type', (input) => {
+    expect(() =>
+      buildSamGraph({
+        applyPolygonRefinement: false,
+        imageName: 'source.png',
+        input,
+        invert: false,
+        model: 'segment-anything-2-large',
+      })
+    ).toThrow(input.type === 'prompt' ? 'A Segment Anything object prompt is required.' : 'visual input is required');
+  });
+
+  it.each([
+    {
+      bbox: null,
+      excludePoints: [],
+      includePoints: [{ x: 1.5, y: 2 }],
+      type: 'visual',
+    },
+    {
+      bbox: null,
+      excludePoints: [{ x: Number.NaN, y: 2 }],
+      includePoints: [],
+      type: 'visual',
+    },
+    {
+      bbox: null,
+      excludePoints: [],
+      includePoints: [{ x: 1, y: Number.POSITIVE_INFINITY }],
+      type: 'visual',
+    },
+    {
+      bbox: { height: 2, width: 1.5, x: 0, y: 0 },
+      excludePoints: [],
+      includePoints: [],
+      type: 'visual',
+    },
+    {
+      bbox: { height: 2, width: 1, x: Number.NEGATIVE_INFINITY, y: 0 },
+      excludePoints: [],
+      includePoints: [],
+      type: 'visual',
+    },
+    {
+      bbox: { height: 2, width: 1.5, x: 0, y: 0 },
+      excludePoints: [],
+      includePoints: [{ x: 1, y: 2 }],
+      type: 'visual',
+    },
+    {
+      bbox: { height: 2, width: Number.MAX_VALUE, x: Number.MAX_VALUE, y: 0 },
+      excludePoints: [],
+      includePoints: [],
+      type: 'visual',
+    },
+  ] as const)('rejects backend-invalid coordinates %#', (input) => {
+    expect(isSamInputValid(input)).toBe(false);
+    expect(() =>
+      buildSamGraph({
+        applyPolygonRefinement: false,
+        imageName: 'source.png',
+        input,
+        invert: false,
+        model: 'segment-anything-2-large',
+      })
+    ).toThrow('visual input is required');
+  });
+
+  it('rejects a non-finite document bbox even when a finite point is present', () => {
+    expect(
+      isSamDocumentInputValid({
+        bbox: { height: 2, width: Number.POSITIVE_INFINITY, x: 0, y: 0 },
+        excludePoints: [],
+        includePoints: [{ x: 1.25, y: 2.75 }],
+        type: 'visual',
+      })
+    ).toBe(false);
+  });
+});
+
+describe('documentToExportLocalSamInput', () => {
+  it('subtracts a nonzero export origin, rounds finite points, and discards points outside the export', () => {
+    expect(
+      documentToExportLocalSamInput(
+        {
+          bbox: null,
+          excludePoints: [{ x: 111.6, y: 210.4 }],
+          includePoints: [
+            { x: 99, y: 199 },
+            { x: 105.4, y: 205.6 },
+          ],
+          type: 'visual',
+        },
+        { height: 10, width: 12, x: 100, y: 200 }
+      )
+    ).toEqual({
+      bbox: null,
+      excludePoints: [],
+      includePoints: [{ x: 5, y: 6 }],
+      type: 'visual',
+    });
+  });
+
+  it('keeps inside edge points while discarding non-finite and outside points', () => {
+    expect(
+      documentToExportLocalSamInput(
+        {
+          bbox: null,
+          excludePoints: [
+            { x: Number.NaN, y: 10 },
+            { x: 20, y: Number.POSITIVE_INFINITY },
+          ],
+          includePoints: [
+            { x: 10, y: 20 },
+            { x: 21.9, y: 29.9 },
+            { x: 22, y: 25 },
+          ],
+          type: 'visual',
+        },
+        { height: 10, width: 12, x: 10, y: 20 }
+      )
+    ).toEqual({
+      bbox: null,
+      excludePoints: [],
+      includePoints: [
+        { x: 0, y: 0 },
+        { x: 11, y: 9 },
+      ],
+      type: 'visual',
+    });
+  });
+
+  it('clips bbox edges in export-local coordinates', () => {
+    expect(
+      documentToExportLocalSamInput(
+        {
+          bbox: { height: 30, width: 40, x: 90, y: 190 },
+          excludePoints: [],
+          includePoints: [],
+          type: 'visual',
+        },
+        { height: 20, width: 30, x: 100, y: 200 }
+      )
+    ).toEqual({
+      bbox: { height: 20, width: 30, x: 0, y: 0 },
+      excludePoints: [],
+      includePoints: [],
+      type: 'visual',
+    });
+  });
+
+  it('drops a bbox fully outside the export and leaves prompt input unchanged', () => {
+    const prompt = { prompt: 'cat', type: 'prompt' } as const;
+    expect(documentToExportLocalSamInput(prompt, { height: 20, width: 30, x: 100, y: 200 })).toBe(prompt);
+    const converted = documentToExportLocalSamInput(
+      {
+        bbox: { height: 5, width: 5, x: 10, y: 20 },
+        excludePoints: [],
+        includePoints: [],
+        type: 'visual',
+      },
+      { height: 20, width: 30, x: 100, y: 200 }
+    );
+    expect(converted.type).toBe('visual');
+    if (converted.type !== 'visual') {
+      throw new Error('Expected visual SAM input.');
+    }
+    expect(converted.bbox).toBeNull();
+    expect(isSamInputValid(converted)).toBe(false);
+  });
+
+  it.each([
+    { height: 0, width: 30, x: 100, y: 200 },
+    { height: 20, width: 0, x: 100, y: 200 },
+  ])('produces an invalid empty visual input for a zero-size export %#', (exportRect) => {
+    const converted = documentToExportLocalSamInput(
+      {
+        bbox: null,
+        excludePoints: [{ x: 101, y: 201 }],
+        includePoints: [],
+        type: 'visual',
+      },
+      exportRect
+    );
+
+    expect(converted).toEqual({ bbox: null, excludePoints: [], includePoints: [], type: 'visual' });
+    expect(isSamInputValid(converted)).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/samGraph.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/samGraph.ts
new file mode 100644
index 00000000000..16c1a0788a7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/samGraph.ts
@@ -0,0 +1,172 @@
+import type { Rect, Vec2 } from '@workbench/canvas-engine/types';
+import type { SamInput, SamModel } from '@workbench/canvas-operations/operationTypes';
+import type { BackendGraphContract } from '@workbench/types';
+export type { SamInput, SamModel } from '@workbench/canvas-operations/operationTypes';
+
+import { documentToExportLocalSamPoint } from '@workbench/canvas-engine/samCoordinates';
+import { addEdge, addNode } from '@workbench/generation/graphBuilder';
+
+export interface BuildSamGraphOptions {
+  imageName: string;
+  input: SamInput;
+  model: SamModel;
+  invert: boolean;
+  applyPolygonRefinement: boolean;
+}
+
+export interface BuiltSamGraph {
+  graph: BackendGraphContract;
+  outputNodeId: string;
+}
+
+const clamp = (value: number, min: number, max: number): number => Math.min(max, Math.max(min, value));
+
+const isFinitePoint = ({ x, y }: Vec2): boolean => Number.isFinite(x) && Number.isFinite(y);
+const isIntegerPoint = (point: Vec2): boolean =>
+  isFinitePoint(point) && Number.isInteger(point.x) && Number.isInteger(point.y);
+const isFiniteBox = (bbox: Rect): boolean =>
+  Number.isFinite(bbox.x) &&
+  Number.isFinite(bbox.y) &&
+  Number.isFinite(bbox.width) &&
+  Number.isFinite(bbox.height) &&
+  bbox.width > 0 &&
+  bbox.height > 0 &&
+  Number.isFinite(bbox.x + bbox.width) &&
+  Number.isFinite(bbox.y + bbox.height) &&
+  bbox.x + bbox.width > bbox.x &&
+  bbox.y + bbox.height > bbox.y;
+const isIntegerBox = (bbox: Rect): boolean =>
+  isFiniteBox(bbox) &&
+  Number.isInteger(bbox.x) &&
+  Number.isInteger(bbox.y) &&
+  Number.isInteger(bbox.width) &&
+  Number.isInteger(bbox.height);
+
+/** Validates document-space inputs before scheduling or stable hashing. */
+export const isSamDocumentInputValid = (input: SamInput): boolean => {
+  if (input.type === 'prompt') {
+    return input.prompt.trim().length > 0;
+  }
+  const points = [...input.includePoints, ...input.excludePoints];
+  const hasBox = input.bbox !== null && input.bbox !== undefined;
+  const boxIsValid = input.bbox === null || input.bbox === undefined || isFiniteBox(input.bbox);
+  return points.every(isFinitePoint) && boxIsValid && (points.length > 0 || hasBox);
+};
+
+export const isSamInputValid = (input: SamInput): boolean => {
+  if (input.type === 'prompt') {
+    return input.prompt.trim().length > 0;
+  }
+  const points = [...input.includePoints, ...input.excludePoints];
+  const hasBox = input.bbox !== null && input.bbox !== undefined;
+  const boxIsValid = input.bbox === null || input.bbox === undefined || isIntegerBox(input.bbox);
+  return points.every(isIntegerPoint) && boxIsValid && (points.length > 0 || hasBox);
+};
+
+/** Converts document-space visual prompts to the pixel coordinates of a bounded layer export. */
+export const documentToExportLocalSamInput = (input: SamInput, exportRect: Rect): SamInput => {
+  if (input.type === 'prompt') {
+    return input;
+  }
+
+  if (
+    !Number.isFinite(exportRect.x) ||
+    !Number.isFinite(exportRect.y) ||
+    !Number.isInteger(exportRect.width) ||
+    !Number.isInteger(exportRect.height) ||
+    exportRect.width <= 0 ||
+    exportRect.height <= 0
+  ) {
+    return { bbox: null, excludePoints: [], includePoints: [], type: 'visual' };
+  }
+
+  const convertPoints = (points: readonly Vec2[]): Vec2[] =>
+    points.flatMap((point) => {
+      const converted = documentToExportLocalSamPoint(point, exportRect);
+      return converted ? [converted] : [];
+    });
+  let bbox: Rect | null = null;
+  if (input.bbox && isFiniteBox(input.bbox)) {
+    const xMin = clamp(Math.round(input.bbox.x - exportRect.x), 0, exportRect.width);
+    const yMin = clamp(Math.round(input.bbox.y - exportRect.y), 0, exportRect.height);
+    const xMax = clamp(Math.round(input.bbox.x + input.bbox.width - exportRect.x), 0, exportRect.width);
+    const yMax = clamp(Math.round(input.bbox.y + input.bbox.height - exportRect.y), 0, exportRect.height);
+    if (xMax > xMin && yMax > yMin) {
+      bbox = { height: yMax - yMin, width: xMax - xMin, x: xMin, y: yMin };
+    }
+  }
+
+  return {
+    bbox,
+    excludePoints: convertPoints(input.excludePoints),
+    includePoints: convertPoints(input.includePoints),
+    type: 'visual',
+  };
+};
+
+export const buildSamGraph = (options: BuildSamGraphOptions): BuiltSamGraph => {
+  if (!isSamInputValid(options.input)) {
+    throw new Error(
+      options.input.type === 'prompt'
+        ? 'A Segment Anything object prompt is required.'
+        : 'A Segment Anything visual input is required.'
+    );
+  }
+
+  const graph: BackendGraphContract = { edges: [], id: 'select-object-sam', nodes: {} };
+  const source = addNode(graph, {
+    id: 'sam-source',
+    image: { image_name: options.imageName },
+    type: 'image',
+  });
+  const points =
+    options.input.type === 'visual'
+      ? [
+          ...options.input.includePoints.map(({ x, y }) => ({ label: 1, x, y })),
+          ...options.input.excludePoints.map(({ x, y }) => ({ label: -1, x, y })),
+        ]
+      : [];
+  const bbox = options.input.type === 'visual' ? options.input.bbox : null;
+  const segment = addNode(graph, {
+    ...(points.length > 0 ? { point_lists: [{ points }] } : {}),
+    ...(bbox
+      ? {
+          bounding_boxes: [
+            {
+              x_max: bbox.x + bbox.width,
+              x_min: bbox.x,
+              y_max: bbox.y + bbox.height,
+              y_min: bbox.y,
+            },
+          ],
+        }
+      : {}),
+    apply_polygon_refinement: options.applyPolygonRefinement,
+    id: 'sam-segment',
+    mask_filter: 'largest',
+    model: options.model,
+    type: 'segment_anything',
+  });
+  const output = addNode(graph, {
+    id: 'sam-output',
+    image: { image_name: options.imageName },
+    invert: options.invert,
+    type: 'apply_tensor_mask_to_image',
+  });
+
+  addEdge(graph, source, 'image', segment, 'image');
+  if (options.input.type === 'prompt') {
+    const detect = addNode(graph, {
+      detection_threshold: 0.3,
+      id: 'sam-detect',
+      model: 'grounding-dino-base',
+      prompt: options.input.prompt.trim(),
+      type: 'grounding_dino',
+    });
+    addEdge(graph, source, 'image', detect, 'image');
+    addEdge(graph, detect, 'collection', segment, 'bounding_boxes');
+  }
+  addEdge(graph, segment, 'mask', output, 'mask');
+
+  return { graph, outputNodeId: output.id };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/canvas/types.ts b/invokeai/frontend/webv2/src/workbench/generation/canvas/types.ts
new file mode 100644
index 00000000000..4bc15cb9cad
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/canvas/types.ts
@@ -0,0 +1,163 @@
+/**
+ * Shared vocabulary for the canvas → generation-graph pipeline.
+ *
+ * This module is pure data: it names the generation mode a canvas invoke maps
+ * to and the shape of a *composite plan* — a pixel-free description of what the
+ * executor must composite and upload before a graph can be built. It has no
+ * runtime dependency on the canvas engine (shared engine vocabulary is imported
+ * type-only), so the planner (`compositePlan.ts`) and mode detector
+ * (`canvasMode.ts`) stay pure, node-testable, data-in/data-out functions.
+ *
+ * The plan is deliberately open-ended: Phase 4.2 only emits the single
+ * `base-raster` composite, but later phases add `control-layer`,
+ * `regional-mask`, and `inpaint-mask` composites to the same {@link CompositePlan}
+ * structure — each a {@link CompositeEntry} with its own stable identity key.
+ */
+
+import type {
+  CompositeEntry as RasterCompositeEntry,
+  CompositeLayerRef,
+} from '@workbench/canvas-engine/render/rasterComposite';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { GenerateModelConfig, GenerateSettings } from '@workbench/generation/types';
+import type { BackendGraphContract, GraphContract, ProjectSettings, ResultDestination } from '@workbench/types';
+import type { CanvasCompositingSettings } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+
+import type { ControlLayerGraphInput } from './addControlLayers';
+import type { RegionalGuidanceInput } from './addRegionalGuidance';
+
+export type { CompositeLayerRef, Rect };
+
+/** The legacy-parity generation modes a canvas invoke resolves to. */
+export type CanvasGenerationMode = 'txt2img' | 'img2img' | 'inpaint' | 'outpaint';
+
+/**
+ * Legacy default resolution for undefined mask attributes (`addInpaint.ts`):
+ * a fresh mask with `denoiseLimit === undefined` denoises fully (1.0), and a
+ * fresh mask with `noiseLevel === undefined` is EXCLUDED from the noise
+ * composite entirely (no `img_noise`) — it must not be treated as noise 0.
+ */
+export const DEFAULT_MASK_DENOISE_LIMIT = 1;
+
+/** The kind of composite an entry describes. */
+export type CompositeEntryKind = 'base-raster' | 'inpaint-mask' | 'noise-mask' | 'control-layer' | 'regional-mask';
+
+/**
+ * A mask layer's contribution to a grayscale mask composite. The executor draws
+ * each mask's alpha and colors it by `attributeValue` (white = keep, darker =
+ * inpaint), darken-compositing multiple masks over a white background, exactly
+ * like the legacy `getGrayscaleMaskCompositeImageDTO`.
+ */
+export interface CompositeMaskLayerRef extends Pick<
+  CompositeLayerRef,
+  'id' | 'sourceRef' | 'contentSize' | 'contentOffset' | 'transform'
+> {
+  /**
+   * The per-layer attribute value in [0, 1] driving the grayscale gray value
+   * (`255 - round(255 * attributeValue)` for masked pixels). For the
+   * `inpaint-mask` (denoise-limit) entry, an undefined `denoiseLimit` resolves
+   * to {@link DEFAULT_MASK_DENOISE_LIMIT}; for the `noise-mask` entry it is the
+   * layer's `noiseLevel` (only layers with a defined `noiseLevel` appear).
+   */
+  attributeValue: number;
+}
+
+/**
+ * One composite the executor must produce: a set of layers composited over a
+ * bbox into a single uploadable image. `key` is a content-identity hash of
+ * everything that determines the entry's pixels (see {@link CompositePlan}).
+ */
+export interface CompositeEntry extends RasterCompositeEntry {
+  kind: CompositeEntryKind;
+  /**
+   * Stable identity key: same document + bbox → same key, so the executor can
+   * skip recompositing / re-uploading when nothing that affects these pixels
+   * changed between invokes.
+   */
+  key: string;
+  /** Contributing mask layers, for grayscale mask entries (`inpaint-mask` / `noise-mask`). */
+  maskLayers?: CompositeMaskLayerRef[];
+  /**
+   * The single document layer id a `control-layer` entry composites (each
+   * enabled control layer is composited SEPARATELY, never blended together).
+   */
+  layerId?: string;
+}
+
+/**
+ * A pixel-free description of everything an invoke must composite/upload. Phase
+ * 4.2 emits exactly one `base-raster` entry; later phases append more.
+ */
+export interface CompositePlan {
+  /** The bbox (document space) the plan is scoped to. */
+  bbox: Rect;
+  entries: CompositeEntry[];
+}
+
+/** The generation modes the pure canvas graph compiler supports (full matrix). */
+export type CanvasCompileMode = CanvasGenerationMode;
+
+/**
+ * Everything {@link import('./compileCanvasGraph').compileCanvasGraph} needs to
+ * build a canvas generation graph. Pure data: the executor (Task 16) supplies
+ * the already-uploaded `compositeImageName`; no pixels or engine state leak in.
+ */
+export interface CompileCanvasGraphInput {
+  /** Prompts / steps / model-adjacent settings, reused verbatim from Generate. */
+  settings: GenerateSettings;
+  model: GenerateModelConfig;
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>;
+  /** The resolved canvas mode (from `canvasMode.ts`). */
+  mode: CanvasCompileMode;
+  /**
+   * The resolved result destination. `canvas` marks the output node intermediate
+   * (staging); `gallery` makes it a durable image, matching `compileGenerateGraph`.
+   */
+  destination: ResultDestination;
+  /** The generation bounding box, in document space. Its size overrides settings dims. */
+  bbox: Rect;
+  /** The uploaded bbox composite (executor result). Required for image-referencing modes. */
+  compositeImageName: string | null;
+  /**
+   * The uploaded grayscale denoise-limit mask (white = keep, dark = inpaint).
+   * Required for `inpaint` / `outpaint`.
+   */
+  maskImageName?: string | null;
+  /**
+   * The uploaded grayscale noise mask, present only when at least one enabled
+   * mask layer defines a `noiseLevel`. Adds an `img_noise` node before encode.
+   */
+  noiseMaskImageName?: string | null;
+  /** Denoising strength in (0, 1]. Consulted for `img2img` / `inpaint` / `outpaint`. */
+  strength: number;
+  /** Infill / coherence / mask-blur knobs. Defaults applied by the reader. */
+  compositing?: CanvasCompositingSettings;
+  /**
+   * Valid, already-resolved control layers (each with its own uploaded composite
+   * image name). The executor filters + composites these; the compiler only
+   * grafts adapter nodes. Present in every mode (control works with all).
+   */
+  controlLayers?: readonly ControlLayerGraphInput[];
+  /**
+   * Valid, already-resolved regional-guidance regions (each with its own uploaded
+   * mask image name + resolved reference-image models). The executor filters +
+   * composites these; the compiler only grafts the mask-tensor + conditioning
+   * nodes into the base graph's `pos_cond_collect` / `neg_cond_collect`. Applied
+   * only for supported bases (sd-1 / sdxl / flux).
+   */
+  regionalGuidance?: readonly RegionalGuidanceInput[];
+}
+
+/**
+ * Mirrors {@link import('../types').CompiledGenerateGraph} with the resolved
+ * canvas mode attached so downstream (Task 18) can label / branch without
+ * re-deriving it.
+ */
+export interface CompiledCanvasGraph {
+  backendGraph: BackendGraphContract;
+  graph: GraphContract;
+  negativePromptNodeId: string;
+  positivePromptNodeId: string;
+  seedNodeId: string;
+  mode: CanvasCompileMode;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/generation/componentCompatibility.test.ts b/invokeai/frontend/webv2/src/workbench/generation/componentCompatibility.test.ts
new file mode 100644
index 00000000000..3ffa2e05870
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/componentCompatibility.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ComponentModelConfig, GenerateModelConfig } from './types';
+
+import {
+  getCompatibleSelectedComponentKey,
+  isAnimaQwen3Encoder,
+  isAnimaVae,
+  isFlux2DiffusersSourceForModel,
+  isFlux2Qwen3EncoderForModel,
+  isNonAnimaQwen3Encoder,
+  isVaeCompatibleWithGenerateModel,
+  type GenerateComponentCandidate,
+} from './componentCompatibility';
+
+const flux2Model = (variant: string): GenerateModelConfig => ({
+  base: 'flux2',
+  key: `flux2-${variant}`,
+  name: `FLUX.2 ${variant}`,
+  type: 'main',
+  variant,
+});
+
+const candidate = (overrides: Partial<GenerateComponentCandidate>): GenerateComponentCandidate => ({
+  base: 'any',
+  type: 'qwen3_encoder',
+  ...overrides,
+});
+
+describe('Generate component compatibility', () => {
+  it('separates Anima Qwen3 0.6B encoders from other Qwen3 encoders', () => {
+    const qwen06b = candidate({ variant: 'qwen3_06b' });
+    const qwen4b = candidate({ variant: 'qwen3_4b' });
+
+    expect(isAnimaQwen3Encoder(qwen06b)).toBe(true);
+    expect(isAnimaQwen3Encoder(qwen4b)).toBe(false);
+    expect(isNonAnimaQwen3Encoder(qwen06b)).toBe(false);
+    expect(isNonAnimaQwen3Encoder(qwen4b)).toBe(true);
+  });
+
+  it('matches FLUX.2 Klein models to compatible Qwen3 encoder variants', () => {
+    const filter = isFlux2Qwen3EncoderForModel(flux2Model('klein_9b'));
+
+    expect(filter(candidate({ variant: 'qwen3_8b' }))).toBe(true);
+    expect(filter(candidate({ variant: 'qwen3_4b' }))).toBe(false);
+    expect(filter(candidate({ variant: 'qwen3_06b' }))).toBe(false);
+  });
+
+  it('matches FLUX.2 component sources by shared Qwen3 encoder variant', () => {
+    const filter = isFlux2DiffusersSourceForModel(flux2Model('klein_9b'));
+
+    expect(filter(candidate({ base: 'flux2', format: 'diffusers', type: 'main', variant: 'klein_9b_base' }))).toBe(
+      true
+    );
+    expect(filter(candidate({ base: 'flux2', format: 'diffusers', type: 'main', variant: 'klein_4b' }))).toBe(false);
+    expect(filter(candidate({ base: 'flux2', format: 'checkpoint', type: 'main', variant: 'klein_9b' }))).toBe(false);
+    expect(filter(candidate({ base: 'flux2', format: 'diffusers', type: 'main' }))).toBe(false);
+  });
+
+  it('allows only backend-supported Anima VAE families', () => {
+    expect(isAnimaVae(candidate({ base: 'anima', type: 'vae' }))).toBe(true);
+    expect(isAnimaVae(candidate({ base: 'qwen-image', type: 'vae' }))).toBe(true);
+    expect(isAnimaVae(candidate({ base: 'flux', type: 'vae' }))).toBe(true);
+    expect(isAnimaVae(candidate({ base: 'sdxl', type: 'vae' }))).toBe(false);
+  });
+
+  it('centralizes generate VAE compatibility for cross-base families', () => {
+    const vae = (base: string) => ({ base, key: `${base}-vae`, name: `${base} VAE`, type: 'vae' as const });
+
+    expect(isVaeCompatibleWithGenerateModel(flux2Model('klein_9b'), vae('flux2'))).toBe(true);
+    expect(isVaeCompatibleWithGenerateModel(flux2Model('klein_9b'), vae('flux'))).toBe(false);
+    expect(
+      isVaeCompatibleWithGenerateModel({ base: 'z-image', key: 'z-image', name: 'Z-Image', type: 'main' }, vae('flux'))
+    ).toBe(true);
+    expect(
+      isVaeCompatibleWithGenerateModel({ base: 'anima', key: 'anima', name: 'Anima', type: 'main' }, vae('qwen-image'))
+    ).toBe(true);
+  });
+
+  it('hides a stale selected component when it no longer passes the picker filter', () => {
+    const staleVae: ComponentModelConfig = { base: 'sdxl', key: 'sdxl-vae', name: 'SDXL VAE', type: 'vae' };
+
+    expect(getCompatibleSelectedComponentKey(staleVae, isAnimaVae)).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/componentCompatibility.ts b/invokeai/frontend/webv2/src/workbench/generation/componentCompatibility.ts
new file mode 100644
index 00000000000..3542a5fdcdb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/componentCompatibility.ts
@@ -0,0 +1,118 @@
+import type { ComponentModelConfig, GenerateModelConfig, VaeModelConfig } from './types';
+
+export type GenerateComponentCandidate = {
+  base: string;
+  format?: string;
+  key?: string;
+  type: string;
+  variant?: unknown;
+};
+
+export type GenerateComponentFilter = (model: GenerateComponentCandidate) => boolean;
+
+export const KLEIN_TO_QWEN3_VARIANT: Record<string, string> = {
+  klein_4b: 'qwen3_4b',
+  klein_4b_base: 'qwen3_4b',
+  klein_9b: 'qwen3_8b',
+  klein_9b_base: 'qwen3_8b',
+};
+
+export const getCompatibleSelectedComponentKey = (
+  value: ComponentModelConfig | null,
+  filter?: GenerateComponentFilter
+): string | null => (value && (!filter || filter(value)) ? value.key : null);
+
+export const isDiffusersMainForBase =
+  (base: string): GenerateComponentFilter =>
+  (model) =>
+    model.type === 'main' && model.base === base && model.format === 'diffusers';
+
+export const isVaeForBases =
+  (bases: readonly string[]): GenerateComponentFilter =>
+  (model) =>
+    model.type === 'vae' && (bases.length === 0 || bases.includes(model.base));
+
+export const isClipVariant =
+  (variant: string): GenerateComponentFilter =>
+  (model) =>
+    model.type === 'clip_embed' && model.variant === variant;
+
+export const isAnimaQwen3Encoder: GenerateComponentFilter = (model) =>
+  model.type === 'qwen3_encoder' && model.variant === 'qwen3_06b';
+
+export const isNonAnimaQwen3Encoder: GenerateComponentFilter = (model) =>
+  model.type === 'qwen3_encoder' && model.variant !== 'qwen3_06b';
+
+export const isFlux2Qwen3EncoderForModel = (selectedModel: GenerateModelConfig): GenerateComponentFilter => {
+  const requiredVariant =
+    typeof selectedModel.variant === 'string' ? KLEIN_TO_QWEN3_VARIANT[selectedModel.variant] : null;
+
+  return (model) => {
+    if (!isNonAnimaQwen3Encoder(model)) {
+      return false;
+    }
+
+    return requiredVariant ? model.variant === requiredVariant : true;
+  };
+};
+
+export const isFlux2DiffusersSourceForModel = (selectedModel: GenerateModelConfig): GenerateComponentFilter => {
+  const selectedVariant = typeof selectedModel.variant === 'string' ? selectedModel.variant : null;
+  const requiredVariant = selectedVariant ? KLEIN_TO_QWEN3_VARIANT[selectedVariant] : null;
+
+  return (model) => {
+    if (!isDiffusersMainForBase('flux2')(model)) {
+      return false;
+    }
+
+    if (!requiredVariant) {
+      return true;
+    }
+
+    const sourceVariant = typeof model.variant === 'string' ? model.variant : null;
+
+    return sourceVariant ? KLEIN_TO_QWEN3_VARIANT[sourceVariant] === requiredVariant : false;
+  };
+};
+
+export const isCompatibleDiffusersComponentSourceForModel = (
+  selectedModel: GenerateModelConfig,
+  source: GenerateComponentCandidate
+): boolean => {
+  if (selectedModel.type === 'external_image_generator') {
+    return false;
+  }
+
+  if (selectedModel.base === 'flux2') {
+    return isFlux2DiffusersSourceForModel(selectedModel)(source);
+  }
+
+  return isDiffusersMainForBase(selectedModel.base)(source);
+};
+
+export const getCompatibleDiffusersComponentSource = <T extends GenerateComponentCandidate>(
+  selectedModel: GenerateModelConfig,
+  source: T | null | undefined
+): T | undefined =>
+  source && isCompatibleDiffusersComponentSourceForModel(selectedModel, source) ? source : undefined;
+
+export const isAnimaVae = isVaeForBases(['anima', 'qwen-image', 'flux']);
+
+export const isVaeCompatibleWithGenerateModel = (model: GenerateModelConfig, vae: VaeModelConfig): boolean => {
+  if (model.type === 'external_image_generator') {
+    return false;
+  }
+
+  switch (model.base) {
+    case 'anima':
+      return isAnimaVae(vae);
+    case 'z-image':
+      return isVaeForBases(['flux'])(vae);
+    case 'qwen-image':
+      return isVaeForBases(['qwen-image'])(vae);
+    case 'flux2':
+      return isVaeForBases(['flux2'])(vae);
+    default:
+      return vae.type === 'vae' && vae.base === model.base;
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/graph.test.ts b/invokeai/frontend/webv2/src/workbench/generation/graph.test.ts
new file mode 100644
index 00000000000..70747801e80
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/graph.test.ts
@@ -0,0 +1,463 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  ComponentModelConfig,
+  GenerateModelConfig,
+  GenerateSettings,
+  LoraModelConfig,
+  MainModelConfig,
+  VaeModelConfig,
+} from './types';
+
+import { getDefaultGenerateSettings, isSupportedGenerateModel } from './baseGenerationPolicies';
+import { compileGenerateGraph, generateSeedSequence, resolveGenerateSeed } from './graph';
+
+const sd1Model: MainModelConfig = { base: 'sd-1', key: 'sd1-model', name: 'SD 1.5', type: 'main' };
+const sdxlModel: MainModelConfig = { base: 'sdxl', key: 'sdxl-model', name: 'SDXL', type: 'main' };
+const sd3Model: MainModelConfig = { base: 'sd-3', key: 'sd3-model', name: 'SD3', type: 'main' };
+const fluxModel: MainModelConfig = { base: 'flux', key: 'flux-model', name: 'FLUX dev', type: 'main' };
+const flux2Model: MainModelConfig = {
+  base: 'flux2',
+  format: 'diffusers',
+  key: 'flux2-model',
+  name: 'FLUX.2',
+  type: 'main',
+};
+const flux2Klein9bModel: MainModelConfig = {
+  base: 'flux2',
+  format: 'gguf_quantized',
+  key: 'flux2-klein-9b',
+  name: 'FLUX.2 Klein 9B',
+  type: 'main',
+  variant: 'klein_9b',
+};
+const fluxKontextModel: MainModelConfig = {
+  base: 'flux',
+  format: 'diffusers',
+  key: 'flux-kontext',
+  name: 'FLUX Kontext dev',
+  type: 'main',
+};
+const incompatibleFlux2Source: MainModelConfig = {
+  base: 'flux2',
+  format: 'diffusers',
+  key: 'flux2-klein-4b-source',
+  name: 'FLUX.2 Klein 4B Source',
+  type: 'main',
+  variant: 'klein_4b',
+};
+const cogView4Model: MainModelConfig = { base: 'cogview4', key: 'cog-model', name: 'CogView4', type: 'main' };
+const qwenImageModel: MainModelConfig = {
+  base: 'qwen-image',
+  format: 'diffusers',
+  key: 'qwen-model',
+  name: 'Qwen Image',
+  type: 'main',
+};
+const zImageModel: MainModelConfig = {
+  base: 'z-image',
+  format: 'diffusers',
+  key: 'z-model',
+  name: 'Z-Image',
+  type: 'main',
+};
+const animaModel: MainModelConfig = { base: 'anima', key: 'anima-model', name: 'Anima', type: 'main' };
+const externalModel: GenerateModelConfig = {
+  base: 'external',
+  capabilities: { modes: ['txt2img'], supports_seed: true },
+  format: 'external_api',
+  key: 'external-model',
+  name: 'OpenAI Image',
+  provider_id: 'openai',
+  type: 'external_image_generator',
+};
+const sd1Lora: LoraModelConfig = { base: 'sd-1', key: 'sd1-lora', name: 'SD 1.5 LoRA', type: 'lora' };
+const sd2Lora: LoraModelConfig = { base: 'sd-2', key: 'sd2-lora', name: 'SD 2 LoRA', type: 'lora' };
+const sdxlLora: LoraModelConfig = { base: 'sdxl', key: 'sdxl-lora', name: 'SDXL LoRA', type: 'lora' };
+const fluxLora: LoraModelConfig = { base: 'flux', key: 'flux-lora', name: 'FLUX LoRA', type: 'lora' };
+const sd1IpAdapter: ComponentModelConfig = {
+  base: 'sd-1',
+  key: 'sd1-ip-adapter',
+  name: 'SD 1 IP Adapter',
+  type: 'ip_adapter',
+};
+const fluxRedux: ComponentModelConfig = {
+  base: 'flux',
+  key: 'flux-redux',
+  name: 'FLUX Redux',
+  type: 'flux_redux',
+};
+const vae: VaeModelConfig = { base: 'sd-1', key: 'vae-model', name: 'Custom VAE', type: 'vae' };
+const fluxVae: VaeModelConfig = { base: 'flux', key: 'flux-vae', name: 'FLUX VAE', type: 'vae' };
+const flux2Vae: VaeModelConfig = { base: 'flux2', key: 'flux2-vae', name: 'FLUX.2 VAE', type: 'vae' };
+const qwenImageVae: VaeModelConfig = { base: 'qwen-image', key: 'qwen-vae', name: 'Qwen VAE', type: 'vae' };
+const t5Encoder: ComponentModelConfig = { base: 'any', key: 't5', name: 'T5 Encoder', type: 't5_encoder' };
+const clipEmbed: ComponentModelConfig = { base: 'any', key: 'clip', name: 'CLIP Embed', type: 'clip_embed' };
+const qwen3Encoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'qwen3',
+  name: 'Qwen3 Encoder',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_06b',
+};
+
+const createSettings = (model: GenerateModelConfig, overrides: Partial<GenerateSettings> = {}): GenerateSettings => ({
+  ...getDefaultGenerateSettings(model),
+  seed: 1,
+  shouldRandomizeSeed: false,
+  ...overrides,
+});
+
+const refImage = {
+  height: 768,
+  imageName: 'reference.png',
+  imageUrl: '/api/v1/images/i/reference.png/full',
+  queuedAt: '2026-01-01T00:00:00.000Z',
+  sourceQueueItemId: 'backend-gallery',
+  thumbnailUrl: '/api/v1/images/i/reference.png/thumbnail',
+  width: 512,
+};
+
+const compile = (model: GenerateModelConfig, overrides: Partial<GenerateSettings> = {}) =>
+  compileGenerateGraph(createSettings(model, overrides), model, 'gallery', { useCpuNoise: true }).backendGraph;
+
+const getEdge = (graph: ReturnType<typeof compile>, targetNodeId: string, targetField: string) =>
+  graph.edges.find((edge) => edge.destination.node_id === targetNodeId && edge.destination.field === targetField);
+
+const getNodeByType = (graph: ReturnType<typeof compile>, type: string) =>
+  Object.values(graph.nodes).find((node) => node.type === type);
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('compileGenerateGraph', () => {
+  it('recognizes the legacy-supported generate model families', () => {
+    expect(
+      [
+        sd1Model,
+        sdxlModel,
+        sd3Model,
+        fluxModel,
+        flux2Model,
+        cogView4Model,
+        qwenImageModel,
+        zImageModel,
+        animaModel,
+        externalModel,
+      ].every(isSupportedGenerateModel)
+    ).toBe(true);
+  });
+
+  it('builds a plain txt2img graph without optional nodes', () => {
+    const graph = compile(sd1Model);
+
+    expect(graph.nodes.seamless).toBeUndefined();
+    expect(graph.nodes.vae_loader).toBeUndefined();
+    expect(getEdge(graph, 'denoise_latents', 'unet')?.source.node_id).toBe('model_loader');
+    expect(getEdge(graph, 'canvas_output', 'vae')?.source.node_id).toBe('model_loader');
+    expect(graph.nodes.canvas_output?.fp32).toBe(true);
+    expect(graph.nodes.canvas_output?.color_compensation).toBe('None');
+  });
+
+  it('passes SDXL color compensation to the VAE decode node when enabled', () => {
+    const graph = compile(sdxlModel, { colorCompensation: true });
+
+    expect(graph.nodes.canvas_output?.color_compensation).toBe('SDXL');
+  });
+
+  it('coerces invalid SD schedulers before graph submission', () => {
+    const graph = compile(sd1Model, { scheduler: 'not-a-scheduler' });
+    const metadata = getNodeByType(graph, 'core_metadata');
+
+    expect(graph.nodes.denoise_latents?.scheduler).toBe('euler_a');
+    expect(metadata?.scheduler).toBe('euler_a');
+  });
+
+  it('wires CLIP skip into the SD1 conditioning chain', () => {
+    const graph = compile(sd1Model, { clipSkip: 2 });
+
+    expect(graph.nodes.clip_skip?.skipped_layers).toBe(2);
+  });
+
+  it('routes the UNet and VAE through the seamless node when tiling is enabled', () => {
+    const graph = compile(sd1Model, { seamlessXAxis: true, vae });
+
+    expect(graph.nodes.seamless?.seamless_x).toBe(true);
+    expect(graph.nodes.seamless?.seamless_y).toBe(false);
+    expect(graph.nodes.vae_loader?.vae_model).toEqual(vae);
+    expect(getEdge(graph, 'seamless', 'unet')?.source.node_id).toBe('model_loader');
+    expect(getEdge(graph, 'seamless', 'vae')?.source.node_id).toBe('vae_loader');
+    expect(getEdge(graph, 'denoise_latents', 'unet')?.source.node_id).toBe('seamless');
+    expect(getEdge(graph, 'canvas_output', 'vae')?.source.node_id).toBe('seamless');
+  });
+
+  it('uses a VAE override only when it matches the model base', () => {
+    const matching = compile(sd1Model, { vae, vaePrecision: 'fp16' });
+
+    expect(getEdge(matching, 'canvas_output', 'vae')?.source.node_id).toBe('vae_loader');
+    expect(matching.nodes.canvas_output?.fp32).toBe(false);
+
+    const mismatched = compile(sdxlModel, { vae });
+
+    expect(mismatched.nodes.vae_loader).toBeUndefined();
+    expect(getEdge(mismatched, 'canvas_output', 'vae')?.source.node_id).toBe('model_loader');
+  });
+
+  it('routes SD LoRAs through the UNet and CLIP conditioning chain', () => {
+    const graph = compile(sd1Model, {
+      loras: [{ isEnabled: true, model: sd1Lora, weight: 0.5 }],
+    });
+    const loraLoader = getNodeByType(graph, 'lora_collection_loader');
+    const metadata = getNodeByType(graph, 'core_metadata');
+
+    expect(loraLoader).toBeDefined();
+    expect(getEdge(graph, 'denoise_latents', 'unet')?.source.node_id).toBe(loraLoader?.id);
+    expect(getEdge(graph, 'pos_cond', 'clip')?.source.node_id).toBe(loraLoader?.id);
+    expect(getEdge(graph, 'neg_cond', 'clip')?.source.node_id).toBe(loraLoader?.id);
+    expect(metadata?.loras).toEqual([
+      { model: { base: 'sd-1', key: 'sd1-lora', name: 'SD 1.5 LoRA', type: 'lora' }, weight: 0.5 },
+    ]);
+  });
+
+  it('routes SDXL LoRAs through both CLIP encoders', () => {
+    const graph = compile(sdxlModel, {
+      loras: [{ isEnabled: true, model: sdxlLora, weight: 0.65 }],
+    });
+    const loraLoader = getNodeByType(graph, 'sdxl_lora_collection_loader');
+
+    expect(loraLoader).toBeDefined();
+    expect(getEdge(graph, 'denoise_latents', 'unet')?.source.node_id).toBe(loraLoader?.id);
+    expect(getEdge(graph, 'pos_cond', 'clip')?.source.node_id).toBe(loraLoader?.id);
+    expect(getEdge(graph, 'pos_cond', 'clip2')?.source.node_id).toBe(loraLoader?.id);
+    expect(getEdge(graph, 'neg_cond', 'clip2')?.source.node_id).toBe(loraLoader?.id);
+  });
+
+  it('ignores disabled and incompatible LoRAs', () => {
+    const graph = compile(sd1Model, {
+      loras: [
+        { isEnabled: true, model: sd2Lora, weight: 1 },
+        { isEnabled: false, model: sd1Lora, weight: 1 },
+      ],
+    });
+    const metadata = getNodeByType(graph, 'core_metadata');
+
+    expect(getNodeByType(graph, 'lora_collection_loader')).toBeUndefined();
+    expect(getEdge(graph, 'denoise_latents', 'unet')?.source.node_id).toBe('model_loader');
+    expect(metadata?.loras).toBeUndefined();
+  });
+
+  it('builds a FLUX graph with required components and FLUX LoRAs', () => {
+    const graph = compile(fluxModel, {
+      clipEmbedModel: clipEmbed,
+      loras: [{ isEnabled: true, model: fluxLora, weight: 0.8 }],
+      t5EncoderModel: t5Encoder,
+      vae: fluxVae,
+    });
+    const loraLoader = getNodeByType(graph, 'flux_lora_collection_loader');
+
+    expect(graph.nodes.model_loader?.type).toBe('flux_model_loader');
+    expect(graph.nodes.model_loader?.t5_encoder_model).toEqual(t5Encoder);
+    expect(graph.nodes.model_loader?.clip_embed_model).toEqual(clipEmbed);
+    expect(graph.nodes.denoise_latents?.type).toBe('flux_denoise');
+    expect(graph.nodes.canvas_output?.type).toBe('flux_vae_decode');
+    expect(loraLoader).toBeDefined();
+    expect(getEdge(graph, 'denoise_latents', 'transformer')?.source.node_id).toBe(loraLoader?.id);
+  });
+
+  it('fails early when required FLUX components are missing', () => {
+    expect(() => compile(fluxModel)).toThrow('Generate needs a T5 Encoder for FLUX models.');
+  });
+
+  it('builds modern Diffusers-family graphs without separate component overrides', () => {
+    expect(compile(sd3Model).nodes.model_loader?.type).toBe('sd3_model_loader');
+    expect(compile(flux2Model).nodes.model_loader?.type).toBe('flux2_klein_model_loader');
+    expect(compile(cogView4Model).nodes.model_loader?.type).toBe('cogview4_model_loader');
+    expect(compile(qwenImageModel).nodes.model_loader?.type).toBe('qwen_image_model_loader');
+    expect(compile(zImageModel).nodes.model_loader?.type).toBe('z_image_model_loader');
+  });
+
+  it('does not enable FLUX.2 CFG without negative conditioning', () => {
+    const graph = compile(flux2Model, { cfgScale: 4 });
+
+    expect(graph.nodes.denoise_latents?.cfg_scale).toBe(1);
+    expect(getEdge(graph, 'denoise_latents', 'negative_text_conditioning')).toBeUndefined();
+  });
+
+  it('rejects a stale incompatible FLUX.2 component source when Qwen3 is missing', () => {
+    expect(() => compile(flux2Klein9bModel, { componentSourceModel: incompatibleFlux2Source, vae: flux2Vae })).toThrow(
+      'Generate needs a Qwen3 Encoder for non-Diffusers FLUX.2 models.'
+    );
+  });
+
+  it('rejects dimensions that are not on the selected model family grid', () => {
+    expect(() => compile(flux2Model, { height: 888 })).toThrow('Generate height must be a multiple of 16.');
+  });
+
+  it('builds an Anima graph with required components', () => {
+    expect(() => compile(animaModel)).toThrow('Generate needs a Qwen3 Encoder for Anima models.');
+
+    const graph = compile(animaModel, { qwen3EncoderModel: qwen3Encoder, vae: qwenImageVae });
+
+    expect(graph.nodes.model_loader?.type).toBe('anima_model_loader');
+    expect(graph.nodes.model_loader?.qwen3_encoder_model).toEqual(qwen3Encoder);
+    expect(graph.nodes.model_loader?.vae_model).toEqual(qwenImageVae);
+    expect(graph.nodes.canvas_output?.type).toBe('anima_l2i');
+  });
+
+  it('builds an external provider graph', () => {
+    const graph = compile(externalModel);
+
+    expect(graph.nodes.canvas_output?.type).toBe('openai_image_generation');
+    expect(graph.nodes.canvas_output?.model).toEqual(externalModel);
+    expect(getEdge(graph, 'canvas_output', 'prompt')?.source.node_id).toBe('positive_prompt');
+    expect(getEdge(graph, 'canvas_output', 'seed')?.source.node_id).toBe('seed');
+  });
+
+  it('does not wire unsupported external provider seed or negative prompt inputs', () => {
+    const graph = compile({ ...externalModel, capabilities: { modes: ['txt2img'] } });
+
+    expect(getEdge(graph, 'canvas_output', 'prompt')?.source.node_id).toBe('positive_prompt');
+    expect(getEdge(graph, 'canvas_output', 'seed')).toBeUndefined();
+    expect(getEdge(graph, 'canvas_output', 'negative_prompt')).toBeUndefined();
+  });
+
+  it('wires external negative prompt only when the provider advertises support', () => {
+    const graph = compile({
+      ...externalModel,
+      capabilities: { modes: ['txt2img'], supports_negative_prompt: true, supports_seed: false },
+    });
+
+    expect(getEdge(graph, 'canvas_output', 'negative_prompt')?.source.node_id).toBe('negative_prompt');
+    expect(getEdge(graph, 'canvas_output', 'seed')).toBeUndefined();
+  });
+
+  it('wires external provider reference images when supported', () => {
+    const graph = compile(
+      { ...externalModel, capabilities: { modes: ['txt2img'], supports_reference_images: true } },
+      {
+        referenceImages: [
+          { id: 'ref-1', isEnabled: true, config: { type: 'external_reference_image', image: refImage } },
+        ],
+      }
+    );
+
+    expect(graph.nodes.canvas_output?.reference_images).toEqual([{ image_name: 'reference.png' }]);
+  });
+
+  it('wires SD IP Adapter reference images into denoise', () => {
+    const graph = compile(sd1Model, {
+      referenceImages: [
+        {
+          id: 'ref-1',
+          isEnabled: true,
+          config: {
+            beginEndStepPct: [0.1, 0.8],
+            clipVisionModel: 'ViT-H',
+            image: refImage,
+            method: 'style',
+            model: sd1IpAdapter,
+            type: 'ip_adapter',
+            weight: 0.6,
+          },
+        },
+      ],
+    });
+    const adapter = getNodeByType(graph, 'ip_adapter');
+
+    expect(adapter).toMatchObject({
+      begin_step_percent: 0.1,
+      clip_vision_model: 'ViT-H',
+      end_step_percent: 0.8,
+      image: { image_name: 'reference.png' },
+      ip_adapter_model: sd1IpAdapter,
+      method: 'style',
+      weight: 0.6,
+    });
+    expect(getEdge(graph, 'denoise_latents', 'ip_adapter')?.source.node_id).toContain('ip_adapter_collector');
+  });
+
+  it('wires FLUX Redux reference images into denoise', () => {
+    const graph = compile(fluxModel, {
+      clipEmbedModel: clipEmbed,
+      referenceImages: [
+        {
+          id: 'ref-redux',
+          isEnabled: true,
+          config: { image: refImage, imageInfluence: 'medium', model: fluxRedux, type: 'flux_redux' },
+        },
+      ],
+      t5EncoderModel: t5Encoder,
+      vae: fluxVae,
+    });
+    const redux = getNodeByType(graph, 'flux_redux');
+
+    expect(redux).toMatchObject({ image: { image_name: 'reference.png' }, redux_model: fluxRedux });
+    expect(getEdge(graph, 'denoise_latents', 'redux_conditioning')?.source.node_id).toContain('flux_redux_collector');
+  });
+
+  it('wires FLUX Kontext reference images into denoise', () => {
+    const graph = compile(fluxKontextModel, {
+      clipEmbedModel: clipEmbed,
+      referenceImages: [
+        {
+          id: 'ref-kontext',
+          isEnabled: true,
+          config: { image: refImage, model: fluxKontextModel, type: 'flux_kontext_reference_image' },
+        },
+      ],
+      t5EncoderModel: t5Encoder,
+      vae: fluxVae,
+    });
+
+    expect(getNodeByType(graph, 'flux_kontext')).toBeDefined();
+    expect(getEdge(graph, 'denoise_latents', 'kontext_conditioning')?.source.node_id).toContain('flux_kontext_collect');
+  });
+
+  it('wires FLUX.2 built-in reference images into denoise', () => {
+    const graph = compile(flux2Model, {
+      referenceImages: [
+        { id: 'ref-flux2', isEnabled: true, config: { image: refImage, type: 'flux2_reference_image' } },
+      ],
+    });
+
+    expect(getNodeByType(graph, 'flux_kontext')).toBeDefined();
+    expect(getEdge(graph, 'denoise_latents', 'kontext_conditioning')?.source.node_id).toContain(
+      'flux2_kontext_collect'
+    );
+  });
+
+  it('wires Qwen Image Edit reference images into text encoder and denoise latents', () => {
+    const graph = compile(
+      { ...qwenImageModel, variant: 'edit' },
+      {
+        referenceImages: [
+          { id: 'ref-qwen', isEnabled: true, config: { image: refImage, type: 'qwen_image_reference_image' } },
+        ],
+      }
+    );
+
+    expect(getEdge(graph, 'pos_cond', 'reference_images')).toBeDefined();
+    expect(getEdge(graph, 'denoise_latents', 'reference_latents')).toBeDefined();
+  });
+});
+
+describe('generate seeds', () => {
+  it('keeps an explicit seed when randomization is disabled', () => {
+    const settings = createSettings(sdxlModel, { seed: 123, shouldRandomizeSeed: false });
+
+    expect(resolveGenerateSeed(settings)).toBe(123);
+  });
+
+  it('resolves a random seed when randomization is enabled', () => {
+    vi.spyOn(Math, 'random').mockReturnValue(0.5);
+
+    const settings = createSettings(sdxlModel, { seed: 123, shouldRandomizeSeed: true });
+
+    expect(resolveGenerateSeed(settings)).toBe(2147483647);
+  });
+
+  it('builds the legacy-style sequential seed batch starting from the resolved seed', () => {
+    expect(generateSeedSequence(10, 4)).toEqual([10, 11, 12, 13]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/graph.ts b/invokeai/frontend/webv2/src/workbench/generation/graph.ts
new file mode 100644
index 00000000000..95054d3254b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/graph.ts
@@ -0,0 +1,1056 @@
+import type {
+  BackendGraphContract,
+  BackendInvocationContract,
+  ProjectSettings,
+  ResultDestination,
+} from '@workbench/types';
+
+import type {
+  CompiledGenerateGraph,
+  ComponentModelConfig,
+  GenerateLora,
+  GenerateModelConfig,
+  GenerateReferenceImage,
+  GenerateReferenceImageAsset,
+  GenerateReferenceImageConfig,
+  GenerateSettings,
+  MainModelConfig,
+} from './types';
+
+import {
+  coerceSchedulerForGraph,
+  getExternalProviderNodeType,
+  getFlux2DiffusersComponentSource,
+  getGenerationDimensions,
+  getGenerationValidationReasons,
+  type SupportedGenerateBase,
+} from './baseGenerationPolicies';
+import {
+  getCompatibleDiffusersComponentSource,
+  isAnimaQwen3Encoder,
+  isAnimaVae,
+  isFlux2Qwen3EncoderForModel,
+  isNonAnimaQwen3Encoder,
+  isVaeForBases,
+} from './componentCompatibility';
+import {
+  addEdge,
+  addMetadata,
+  addNode,
+  createId,
+  getActiveCompatibleLoras,
+  toModelIdentifier,
+  toGraphContract,
+} from './graphBuilder';
+import { SEED_MAX } from './settings';
+
+const getCompatibleComponentSource = (
+  settings: GenerateSettings,
+  model: MainModelConfig
+): MainModelConfig | undefined => getCompatibleDiffusersComponentSource(model, settings.componentSourceModel);
+
+const getCompatibleVae = (settings: GenerateSettings, bases: readonly string[]) =>
+  settings.vae && isVaeForBases(bases)(settings.vae) ? settings.vae : null;
+
+const toImageField = (image: GenerateReferenceImageAsset) => ({ image_name: image.imageName });
+
+const getEnabledReferenceImages = <T extends GenerateReferenceImageConfig['type']>(
+  settings: GenerateSettings,
+  type: T
+): Array<GenerateReferenceImage & { config: Extract<GenerateReferenceImageConfig, { type: T }> }> =>
+  settings.referenceImages.filter(
+    (
+      referenceImage
+    ): referenceImage is GenerateReferenceImage & { config: Extract<GenerateReferenceImageConfig, { type: T }> } =>
+      referenceImage.isEnabled && referenceImage.config.type === type && referenceImage.config.image !== null
+  );
+
+const addReferenceImageMetadata = (
+  graph: BackendGraphContract,
+  outputNode: BackendInvocationContract,
+  settings: GenerateSettings
+) => {
+  const enabled = settings.referenceImages.filter(
+    (referenceImage) => referenceImage.isEnabled && referenceImage.config.image
+  );
+
+  if (enabled.length === 0) {
+    return;
+  }
+
+  const metadata = Object.values(graph.nodes).find((node) => node.type === 'core_metadata');
+
+  if (metadata) {
+    metadata.ref_images = enabled;
+    return;
+  }
+
+  outputNode.ref_images = enabled;
+};
+
+const addIPAdapterReferenceImages = (
+  graph: BackendGraphContract,
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  denoise: BackendInvocationContract
+) => {
+  const refs = getEnabledReferenceImages(settings, 'ip_adapter').filter((ref) => ref.config.model?.base === model.base);
+
+  if (refs.length === 0) {
+    return;
+  }
+
+  const collector = addNode(graph, { id: createId('ip_adapter_collector'), type: 'collect' });
+
+  for (const ref of refs) {
+    const { beginEndStepPct, clipVisionModel, image, method, model: adapterModel, weight } = ref.config;
+
+    if (!image || !adapterModel) {
+      continue;
+    }
+
+    const node = addNode(graph, {
+      begin_step_percent: beginEndStepPct[0],
+      clip_vision_model: clipVisionModel,
+      end_step_percent: beginEndStepPct[1],
+      id: createId('ip_adapter'),
+      image: toImageField(image),
+      ip_adapter_model: adapterModel,
+      method,
+      type: model.base === 'flux' ? 'flux_ip_adapter' : 'ip_adapter',
+      weight,
+    });
+
+    addEdge(graph, node, 'ip_adapter', collector, 'item');
+  }
+
+  addEdge(graph, collector, 'collection', denoise, 'ip_adapter');
+};
+
+const FLUX_REDUX_INFLUENCE = {
+  lowest: { downsampling_factor: 5, weight: 1 },
+  low: { downsampling_factor: 4, weight: 1 },
+  medium: { downsampling_factor: 3, weight: 1 },
+  high: { downsampling_factor: 2, weight: 1 },
+  highest: { downsampling_factor: 1, weight: 1 },
+} as const;
+
+const addFluxReduxReferenceImages = (
+  graph: BackendGraphContract,
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  denoise: BackendInvocationContract
+) => {
+  const refs = getEnabledReferenceImages(settings, 'flux_redux').filter((ref) => ref.config.model?.base === model.base);
+
+  if (refs.length === 0) {
+    return;
+  }
+
+  const collector = addNode(graph, { id: createId('flux_redux_collector'), type: 'collect' });
+
+  for (const ref of refs) {
+    const { image, imageInfluence, model: reduxModel } = ref.config;
+
+    if (!image || !reduxModel) {
+      continue;
+    }
+
+    const node = addNode(graph, {
+      id: createId('flux_redux'),
+      image: toImageField(image),
+      redux_model: reduxModel,
+      type: 'flux_redux',
+      ...FLUX_REDUX_INFLUENCE[imageInfluence],
+    });
+
+    addEdge(graph, node, 'redux_cond', collector, 'item');
+  }
+
+  addEdge(graph, collector, 'collection', denoise, 'redux_conditioning');
+};
+
+const addFluxKontextReferenceImages = (
+  graph: BackendGraphContract,
+  settings: GenerateSettings,
+  denoise: BackendInvocationContract,
+  type: 'flux2_reference_image' | 'flux_kontext_reference_image'
+) => {
+  const refs = getEnabledReferenceImages(settings, type);
+
+  if (refs.length === 0) {
+    return;
+  }
+
+  let prevCollect: BackendInvocationContract | null = null;
+
+  for (const ref of refs) {
+    const { image } = ref.config;
+
+    if (!image) {
+      continue;
+    }
+
+    const kontext = addNode(graph, {
+      id: createId('flux_kontext'),
+      image: toImageField(image),
+      type: 'flux_kontext',
+    });
+    const collect = addNode(graph, {
+      id: createId(type === 'flux2_reference_image' ? 'flux2_kontext_collect' : 'flux_kontext_collect'),
+      type: 'collect',
+    });
+
+    addEdge(graph, kontext, 'kontext_cond', collect, 'item');
+    if (prevCollect) {
+      addEdge(graph, prevCollect, 'collection', collect, 'collection');
+    }
+    prevCollect = collect;
+  }
+
+  if (prevCollect) {
+    addEdge(graph, prevCollect, 'collection', denoise, 'kontext_conditioning');
+  }
+};
+
+const getDiffusersSource = (settings: GenerateSettings, model: MainModelConfig): MainModelConfig | undefined =>
+  getCompatibleComponentSource(settings, model) ?? (model.format === 'diffusers' ? model : undefined);
+
+const requireComponent = <T extends ComponentModelConfig | null>(value: T, label: string): NonNullable<T> => {
+  if (!value) {
+    throw new Error(`${label} is required for this model family.`);
+  }
+
+  return value;
+};
+
+const addLoraSelectors = (
+  graph: BackendGraphContract,
+  loras: GenerateLora[],
+  loaderType: string
+): BackendInvocationContract => {
+  const collector = addNode(graph, { id: createId('lora_collector'), type: 'collect' });
+  const loader = addNode(graph, { id: createId(loaderType), type: loaderType });
+
+  addEdge(graph, collector, 'collection', loader, 'loras');
+
+  for (const lora of loras) {
+    const selector = addNode(graph, {
+      id: createId('lora_selector'),
+      lora: toModelIdentifier(lora.model),
+      type: 'lora_selector',
+      weight: lora.weight,
+    });
+
+    addEdge(graph, selector, 'lora', collector, 'item');
+  }
+
+  return loader;
+};
+
+const addLoraCollectionLoader = (
+  graph: BackendGraphContract,
+  loras: GenerateLora[],
+  model: GenerateModelConfig,
+  sources: {
+    clip: BackendInvocationContract;
+    clip2?: BackendInvocationContract;
+    unet: BackendInvocationContract;
+  }
+): BackendInvocationContract => {
+  const loaderType = model.base === 'sdxl' ? 'sdxl_lora_collection_loader' : 'lora_collection_loader';
+  const loader = addLoraSelectors(graph, loras, loaderType);
+
+  addEdge(graph, sources.unet, 'unet', loader, 'unet');
+  addEdge(graph, sources.clip, 'clip', loader, 'clip');
+
+  if (sources.clip2) {
+    addEdge(graph, sources.clip2, 'clip2', loader, 'clip2');
+  }
+
+  return loader;
+};
+
+const addTransformerLoraCollectionLoader = (
+  graph: BackendGraphContract,
+  loras: GenerateLora[],
+  loaderType: string,
+  modelLoader: BackendInvocationContract,
+  fields: string[]
+): BackendInvocationContract => {
+  const loader = addLoraSelectors(graph, loras, loaderType);
+
+  for (const field of fields) {
+    addEdge(graph, modelLoader, field, loader, field);
+  }
+
+  return loader;
+};
+
+const buildSDGraph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  const graph: BackendGraphContract = { edges: [], id: createId(`${model.base}_graph`), nodes: {} };
+  const modelLoaderType = model.base === 'sdxl' ? 'sdxl_model_loader' : 'main_model_loader';
+  const compelType = model.base === 'sdxl' ? 'sdxl_compel_prompt' : 'compel';
+  const activeLoras = getActiveCompatibleLoras(settings, model);
+  const scheduler = coerceSchedulerForGraph(model, settings.scheduler);
+  const colorCompensation = settings.colorCompensation ? 'SDXL' : 'None';
+
+  const positivePrompt = addNode(graph, { id: 'positive_prompt', type: 'string' });
+  const negativePrompt = addNode(graph, { id: 'negative_prompt', type: 'string' });
+  const seed = addNode(graph, { id: 'seed', type: 'integer' });
+  const modelLoader = addNode(graph, { id: 'model_loader', model, type: modelLoaderType });
+  const posCond = addNode(graph, { id: 'pos_cond', type: compelType });
+  const negCond = addNode(graph, { id: 'neg_cond', type: compelType });
+  const posCondCollect = addNode(graph, { id: 'pos_cond_collect', type: 'collect' });
+  const negCondCollect = addNode(graph, { id: 'neg_cond_collect', type: 'collect' });
+  const noise = addNode(graph, {
+    height: settings.height,
+    id: 'noise',
+    type: 'noise',
+    use_cpu: projectSettings.useCpuNoise,
+    width: settings.width,
+  });
+  const denoise = addNode(graph, {
+    cfg_rescale_multiplier: settings.cfgRescaleMultiplier,
+    cfg_scale: settings.cfgScale,
+    denoising_end: 1,
+    denoising_start: 0,
+    id: 'denoise_latents',
+    scheduler,
+    steps: settings.steps,
+    type: 'denoise_latents',
+  });
+  const output = addNode(graph, {
+    color_compensation: colorCompensation,
+    fp32: settings.vaePrecision === 'fp32',
+    id: 'canvas_output',
+    is_intermediate: outputIsIntermediate,
+    type: 'l2i',
+    use_cache: false,
+  });
+  // A VAE override only applies when it matches the main model's architecture.
+  const vaeLoader =
+    settings.vae && settings.vae.base === model.base
+      ? addNode(graph, { id: 'vae_loader', type: 'vae_loader', vae_model: settings.vae })
+      : null;
+  const seamless =
+    settings.seamlessXAxis || settings.seamlessYAxis
+      ? addNode(graph, {
+          id: 'seamless',
+          seamless_x: settings.seamlessXAxis,
+          seamless_y: settings.seamlessYAxis,
+          type: 'seamless',
+        })
+      : null;
+  let unetSource: BackendInvocationContract = seamless ?? modelLoader;
+  let clipSource: BackendInvocationContract = modelLoader;
+  let clip2Source: BackendInvocationContract | undefined;
+
+  if (model.base === 'sdxl') {
+    clip2Source = modelLoader;
+    addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+    addEdge(graph, positivePrompt, 'value', posCond, 'style');
+    addEdge(graph, negativePrompt, 'value', negCond, 'prompt');
+    addEdge(graph, negativePrompt, 'value', negCond, 'style');
+  } else {
+    const clipSkip = addNode(graph, { id: 'clip_skip', skipped_layers: settings.clipSkip, type: 'clip_skip' });
+
+    addEdge(graph, modelLoader, 'clip', clipSkip, 'clip');
+    clipSource = clipSkip;
+    addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+    addEdge(graph, negativePrompt, 'value', negCond, 'prompt');
+  }
+
+  if (activeLoras.length > 0) {
+    const loraLoader = addLoraCollectionLoader(graph, activeLoras, model, {
+      clip: clipSource,
+      clip2: clip2Source,
+      unet: unetSource,
+    });
+
+    unetSource = loraLoader;
+    clipSource = loraLoader;
+    clip2Source = model.base === 'sdxl' ? loraLoader : undefined;
+  }
+
+  if (model.base === 'sdxl') {
+    addEdge(graph, clipSource, 'clip', posCond, 'clip');
+    addEdge(graph, clip2Source ?? modelLoader, 'clip2', posCond, 'clip2');
+    addEdge(graph, clipSource, 'clip', negCond, 'clip');
+    addEdge(graph, clip2Source ?? modelLoader, 'clip2', negCond, 'clip2');
+  } else {
+    addEdge(graph, clipSource, 'clip', posCond, 'clip');
+    addEdge(graph, clipSource, 'clip', negCond, 'clip');
+  }
+
+  addEdge(graph, posCond, 'conditioning', posCondCollect, 'item');
+  addEdge(graph, posCondCollect, 'collection', denoise, 'positive_conditioning');
+  addEdge(graph, negCond, 'conditioning', negCondCollect, 'item');
+  addEdge(graph, negCondCollect, 'collection', denoise, 'negative_conditioning');
+  addEdge(graph, seed, 'value', noise, 'seed');
+
+  // Seamless slots in between the model loader and the denoise/decode nodes,
+  // patching both the UNet and the (possibly overridden) VAE.
+  if (seamless) {
+    addEdge(graph, modelLoader, 'unet', seamless, 'unet');
+    addEdge(graph, vaeLoader ?? modelLoader, 'vae', seamless, 'vae');
+  }
+
+  addEdge(graph, unetSource, 'unet', denoise, 'unet');
+  addEdge(graph, noise, 'noise', denoise, 'noise');
+  addIPAdapterReferenceImages(graph, settings, model, denoise);
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addEdge(graph, seamless ?? vaeLoader ?? modelLoader, 'vae', output, 'vae');
+  addMetadata(graph, output, settings, model, model.base === 'sdxl' ? 'sdxl_txt2img' : 'txt2img', projectSettings, {
+    scheduler,
+  });
+  addReferenceImageMetadata(graph, output, settings);
+
+  return graph;
+};
+
+const addPromptAndSeedNodes = (graph: BackendGraphContract) => ({
+  negativePrompt: addNode(graph, { id: 'negative_prompt', type: 'string' }),
+  positivePrompt: addNode(graph, { id: 'positive_prompt', type: 'string' }),
+  seed: addNode(graph, { id: 'seed', type: 'integer' }),
+});
+
+const addImageOutputNode = (graph: BackendGraphContract, type: string, outputIsIntermediate: boolean) =>
+  addNode(graph, { id: 'canvas_output', is_intermediate: outputIsIntermediate, type, use_cache: false });
+
+const buildSD3Graph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  const graph: BackendGraphContract = { edges: [], id: createId('sd3_graph'), nodes: {} };
+  const { negativePrompt, positivePrompt, seed } = addPromptAndSeedNodes(graph);
+  const modelLoader = addNode(graph, {
+    clip_g_model: settings.clipGEmbedModel ?? undefined,
+    clip_l_model: settings.clipLEmbedModel ?? undefined,
+    id: 'model_loader',
+    model,
+    t5_encoder_model: settings.t5EncoderModel ?? undefined,
+    type: 'sd3_model_loader',
+    vae_model: settings.vae ?? undefined,
+  });
+  const posCond = addNode(graph, { id: 'pos_cond', type: 'sd3_text_encoder' });
+  const negCond = addNode(graph, { id: 'neg_cond', type: 'sd3_text_encoder' });
+  const denoise = addNode(graph, {
+    cfg_scale: settings.cfgScale,
+    denoising_end: 1,
+    denoising_start: 0,
+    height: settings.height,
+    id: 'denoise_latents',
+    steps: settings.steps,
+    type: 'sd3_denoise',
+    width: settings.width,
+  });
+  const output = addImageOutputNode(graph, 'sd3_l2i', outputIsIntermediate);
+
+  addEdge(graph, modelLoader, 'transformer', denoise, 'transformer');
+  addEdge(graph, modelLoader, 'clip_l', posCond, 'clip_l');
+  addEdge(graph, modelLoader, 'clip_l', negCond, 'clip_l');
+  addEdge(graph, modelLoader, 'clip_g', posCond, 'clip_g');
+  addEdge(graph, modelLoader, 'clip_g', negCond, 'clip_g');
+  addEdge(graph, modelLoader, 't5_encoder', posCond, 't5_encoder');
+  addEdge(graph, modelLoader, 't5_encoder', negCond, 't5_encoder');
+  addEdge(graph, modelLoader, 'vae', output, 'vae');
+  addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+  addEdge(graph, negativePrompt, 'value', negCond, 'prompt');
+  addEdge(graph, posCond, 'conditioning', denoise, 'positive_conditioning');
+  addEdge(graph, negCond, 'conditioning', denoise, 'negative_conditioning');
+  addEdge(graph, seed, 'value', denoise, 'seed');
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addMetadata(graph, output, settings, model, 'sd3_txt2img', projectSettings, {
+    scheduler: undefined,
+    vae: settings.vae ?? undefined,
+  });
+
+  return graph;
+};
+
+const buildFluxGraph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  if (model.variant === 'dev_fill') {
+    throw new Error('FLUX Fill models do not support text-to-image generation.');
+  }
+
+  const graph: BackendGraphContract = { edges: [], id: createId('flux_graph'), nodes: {} };
+  const { positivePrompt } = addPromptAndSeedNodes(graph);
+  const t5EncoderModel = requireComponent(settings.t5EncoderModel, 'T5 Encoder');
+  const clipEmbedModel = requireComponent(settings.clipEmbedModel, 'CLIP Embed');
+  const vaeModel = requireComponent(getCompatibleVae(settings, ['flux']), 'FLUX VAE');
+  const scheduler = coerceSchedulerForGraph(model, settings.scheduler);
+  const activeLoras = getActiveCompatibleLoras(settings, model);
+  const modelLoader = addNode(graph, {
+    clip_embed_model: clipEmbedModel,
+    id: 'model_loader',
+    model,
+    t5_encoder_model: t5EncoderModel,
+    type: 'flux_model_loader',
+    vae_model: vaeModel,
+  });
+  const loraSource = activeLoras.length
+    ? addTransformerLoraCollectionLoader(graph, activeLoras, 'flux_lora_collection_loader', modelLoader, [
+        'transformer',
+        'clip',
+        't5_encoder',
+      ])
+    : modelLoader;
+  const posCond = addNode(graph, { id: 'pos_cond', type: 'flux_text_encoder' });
+  const posCondCollect = addNode(graph, { id: 'pos_cond_collect', type: 'collect' });
+  const denoise = addNode(graph, {
+    denoising_end: 1,
+    denoising_start: 0,
+    guidance: settings.cfgScale,
+    height: settings.height,
+    id: 'denoise_latents',
+    num_steps: settings.steps,
+    scheduler,
+    type: 'flux_denoise',
+    width: settings.width,
+  });
+  const output = addImageOutputNode(graph, 'flux_vae_decode', outputIsIntermediate);
+
+  addEdge(graph, loraSource, 'clip', posCond, 'clip');
+  addEdge(graph, loraSource, 't5_encoder', posCond, 't5_encoder');
+  addEdge(graph, modelLoader, 'max_seq_len', posCond, 't5_max_seq_len');
+  addEdge(graph, loraSource, 'transformer', denoise, 'transformer');
+  addEdge(graph, modelLoader, 'vae', denoise, 'controlnet_vae');
+  addEdge(graph, modelLoader, 'vae', output, 'vae');
+  addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+  addEdge(graph, posCond, 'conditioning', posCondCollect, 'item');
+  addEdge(graph, posCondCollect, 'collection', denoise, 'positive_text_conditioning');
+  addEdge(graph, graph.nodes.seed, 'value', denoise, 'seed');
+  if (model.name.toLowerCase().includes('kontext')) {
+    addFluxKontextReferenceImages(graph, settings, denoise, 'flux_kontext_reference_image');
+  }
+  addIPAdapterReferenceImages(graph, settings, model, denoise);
+  addFluxReduxReferenceImages(graph, settings, model, denoise);
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addMetadata(graph, output, settings, model, 'flux_txt2img', projectSettings, {
+    clip_embed_model: clipEmbedModel,
+    guidance: settings.cfgScale,
+    scheduler,
+    t5_encoder: t5EncoderModel,
+    vae: vaeModel,
+  });
+  addReferenceImageMetadata(graph, output, settings);
+
+  return graph;
+};
+
+const buildFlux2Graph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  const sourceModel = getFlux2DiffusersComponentSource(model, settings);
+  const hasBundledComponents = model.format === 'diffusers' || sourceModel;
+  const qwen3EncoderModel =
+    settings.qwen3EncoderModel && isFlux2Qwen3EncoderForModel(model)(settings.qwen3EncoderModel)
+      ? settings.qwen3EncoderModel
+      : null;
+  const vaeModel = getCompatibleVae(settings, ['flux2']);
+
+  if (!hasBundledComponents && (!vaeModel || !qwen3EncoderModel)) {
+    throw new Error('FLUX.2 non-Diffusers models require a VAE and Qwen3 Encoder, or a Diffusers component source.');
+  }
+
+  const graph: BackendGraphContract = { edges: [], id: createId('flux2_graph'), nodes: {} };
+  const { positivePrompt } = addPromptAndSeedNodes(graph);
+  const scheduler = coerceSchedulerForGraph(model, settings.scheduler);
+  const activeLoras = getActiveCompatibleLoras(settings, model);
+  const modelLoader = addNode(graph, {
+    id: 'model_loader',
+    model,
+    qwen3_encoder_model: qwen3EncoderModel ?? undefined,
+    qwen3_source_model: sourceModel,
+    type: 'flux2_klein_model_loader',
+    vae_model: vaeModel ?? undefined,
+  });
+  const loraSource = activeLoras.length
+    ? addTransformerLoraCollectionLoader(graph, activeLoras, 'flux2_klein_lora_collection_loader', modelLoader, [
+        'transformer',
+        'qwen3_encoder',
+      ])
+    : modelLoader;
+  const posCond = addNode(graph, { id: 'pos_cond', type: 'flux2_klein_text_encoder' });
+  const denoise = addNode(graph, {
+    cfg_scale: 1,
+    denoising_end: 1,
+    denoising_start: 0,
+    guidance: settings.cfgScale,
+    height: settings.height,
+    id: 'denoise_latents',
+    num_steps: settings.steps,
+    scheduler,
+    type: 'flux2_denoise',
+    width: settings.width,
+  });
+  const output = addImageOutputNode(graph, 'flux2_vae_decode', outputIsIntermediate);
+
+  addEdge(graph, loraSource, 'qwen3_encoder', posCond, 'qwen3_encoder');
+  addEdge(graph, modelLoader, 'max_seq_len', posCond, 'max_seq_len');
+  addEdge(graph, loraSource, 'transformer', denoise, 'transformer');
+  addEdge(graph, modelLoader, 'vae', denoise, 'vae');
+  addEdge(graph, modelLoader, 'vae', output, 'vae');
+  addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+  addEdge(graph, posCond, 'conditioning', denoise, 'positive_text_conditioning');
+  addEdge(graph, graph.nodes.seed, 'value', denoise, 'seed');
+  addFluxKontextReferenceImages(graph, settings, denoise, 'flux2_reference_image');
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addMetadata(graph, output, settings, model, 'flux2_txt2img', projectSettings, {
+    qwen3_encoder: qwen3EncoderModel ?? undefined,
+    qwen3_source: sourceModel,
+    scheduler,
+    vae: vaeModel ?? undefined,
+  });
+  addReferenceImageMetadata(graph, output, settings);
+
+  return graph;
+};
+
+const buildCogView4Graph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  const graph: BackendGraphContract = { edges: [], id: createId('cogview4_graph'), nodes: {} };
+  const { negativePrompt, positivePrompt, seed } = addPromptAndSeedNodes(graph);
+  const modelLoader = addNode(graph, { id: 'model_loader', model, type: 'cogview4_model_loader' });
+  const posCond = addNode(graph, { id: 'pos_cond', type: 'cogview4_text_encoder' });
+  const negCond = addNode(graph, { id: 'neg_cond', type: 'cogview4_text_encoder' });
+  const denoise = addNode(graph, {
+    cfg_scale: settings.cfgScale,
+    height: settings.height,
+    id: 'denoise_latents',
+    steps: settings.steps,
+    type: 'cogview4_denoise',
+    width: settings.width,
+  });
+  const output = addImageOutputNode(graph, 'cogview4_l2i', outputIsIntermediate);
+
+  addEdge(graph, modelLoader, 'transformer', denoise, 'transformer');
+  addEdge(graph, modelLoader, 'glm_encoder', posCond, 'glm_encoder');
+  addEdge(graph, modelLoader, 'glm_encoder', negCond, 'glm_encoder');
+  addEdge(graph, modelLoader, 'vae', output, 'vae');
+  addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+  addEdge(graph, negativePrompt, 'value', negCond, 'prompt');
+  addEdge(graph, posCond, 'conditioning', denoise, 'positive_conditioning');
+  addEdge(graph, negCond, 'conditioning', denoise, 'negative_conditioning');
+  addEdge(graph, seed, 'value', denoise, 'seed');
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addMetadata(graph, output, settings, model, 'cogview4_txt2img', projectSettings, { scheduler: undefined });
+
+  return graph;
+};
+
+const buildQwenImageGraph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  const sourceModel = getCompatibleComponentSource(settings, model);
+  const hasBundledComponents = model.format === 'diffusers' || sourceModel;
+  const vaeModel = getCompatibleVae(settings, ['qwen-image']);
+
+  if (!hasBundledComponents && (!vaeModel || !settings.qwenVLEncoderModel)) {
+    throw new Error(
+      'Qwen Image non-Diffusers models require a VAE and Qwen VL Encoder, or a Diffusers component source.'
+    );
+  }
+
+  const graph: BackendGraphContract = { edges: [], id: createId('qwen_image_graph'), nodes: {} };
+  const { negativePrompt, positivePrompt, seed } = addPromptAndSeedNodes(graph);
+  const activeLoras = getActiveCompatibleLoras(settings, model);
+  const useCfg = settings.cfgScale > 1;
+  const modelLoader = addNode(graph, {
+    component_source: sourceModel,
+    id: 'model_loader',
+    model,
+    qwen_vl_encoder_model: settings.qwenVLEncoderModel ?? undefined,
+    type: 'qwen_image_model_loader',
+    vae_model: vaeModel ?? undefined,
+  });
+  const loraSource = activeLoras.length
+    ? addTransformerLoraCollectionLoader(graph, activeLoras, 'qwen_image_lora_collection_loader', modelLoader, [
+        'transformer',
+      ])
+    : modelLoader;
+  const posCond = addNode(graph, { id: 'pos_cond', type: 'qwen_image_text_encoder' });
+  const negCond = useCfg ? addNode(graph, { id: 'neg_cond', type: 'qwen_image_text_encoder' }) : null;
+  const denoise = addNode(graph, {
+    cfg_scale: settings.cfgScale,
+    height: settings.height,
+    id: 'denoise_latents',
+    steps: settings.steps,
+    type: 'qwen_image_denoise',
+    width: settings.width,
+  });
+  const output = addImageOutputNode(graph, 'qwen_image_l2i', outputIsIntermediate);
+
+  addEdge(graph, loraSource, 'transformer', denoise, 'transformer');
+  addEdge(graph, modelLoader, 'qwen_vl_encoder', posCond, 'qwen_vl_encoder');
+  addEdge(graph, modelLoader, 'vae', output, 'vae');
+  addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+  addEdge(graph, posCond, 'conditioning', denoise, 'positive_conditioning');
+
+  if (negCond) {
+    addEdge(graph, modelLoader, 'qwen_vl_encoder', negCond, 'qwen_vl_encoder');
+    addEdge(graph, negativePrompt, 'value', negCond, 'prompt');
+    addEdge(graph, negCond, 'conditioning', denoise, 'negative_conditioning');
+  }
+
+  addEdge(graph, seed, 'value', denoise, 'seed');
+  const qwenReferenceImages =
+    model.variant === 'edit' ? getEnabledReferenceImages(settings, 'qwen_image_reference_image') : [];
+
+  if (qwenReferenceImages.length > 0) {
+    let prevCollect: BackendInvocationContract | null = null;
+
+    for (const { config } of qwenReferenceImages) {
+      if (!config.image) {
+        continue;
+      }
+
+      const imageNode = addNode(graph, {
+        id: createId('qwen_ref_img'),
+        image: toImageField(config.image),
+        type: 'image',
+      });
+      const collectNode = addNode(graph, { id: createId('qwen_ref_img_collect'), type: 'collect' });
+
+      addEdge(graph, imageNode, 'image', collectNode, 'item');
+      if (prevCollect) {
+        addEdge(graph, prevCollect, 'collection', collectNode, 'collection');
+      }
+      prevCollect = collectNode;
+    }
+
+    if (prevCollect) {
+      addEdge(graph, prevCollect, 'collection', posCond, 'reference_images');
+    }
+
+    const firstImage = qwenReferenceImages[0]?.config.image;
+    if (firstImage) {
+      const refI2l = addNode(graph, { id: createId('qwen_ref_i2l'), type: 'qwen_image_i2l' });
+      const refImageNode = addNode(graph, {
+        id: createId('qwen_ref_img_for_vae'),
+        image: toImageField(firstImage),
+        type: 'image',
+      });
+
+      addEdge(graph, refImageNode, 'image', refI2l, 'image');
+      addEdge(graph, modelLoader, 'vae', refI2l, 'vae');
+      addEdge(graph, refI2l, 'latents', denoise, 'reference_latents');
+    }
+  }
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addMetadata(graph, output, settings, model, 'qwen_image_txt2img', projectSettings, {
+    qwen_image_component_source: sourceModel,
+    qwen_image_qwen_vl_encoder: settings.qwenVLEncoderModel ?? undefined,
+    qwen_image_vae: vaeModel ?? undefined,
+    scheduler: undefined,
+  });
+  addReferenceImageMetadata(graph, output, settings);
+
+  return graph;
+};
+
+const buildZImageGraph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  const sourceModel = getDiffusersSource(settings, model);
+  const qwen3EncoderModel =
+    settings.qwen3EncoderModel && isNonAnimaQwen3Encoder(settings.qwen3EncoderModel)
+      ? settings.qwen3EncoderModel
+      : null;
+  const vaeModel = getCompatibleVae(settings, ['flux']);
+
+  if (!sourceModel && (!vaeModel || !qwen3EncoderModel)) {
+    throw new Error('Z-Image models require a VAE and Qwen3 Encoder, or a Diffusers component source.');
+  }
+
+  const graph: BackendGraphContract = { edges: [], id: createId('z_image_graph'), nodes: {} };
+  const { negativePrompt, positivePrompt, seed } = addPromptAndSeedNodes(graph);
+  const scheduler = coerceSchedulerForGraph(model, settings.scheduler);
+  const activeLoras = getActiveCompatibleLoras(settings, model);
+  const useCfg = settings.cfgScale > 1;
+  const modelLoader = addNode(graph, {
+    id: 'model_loader',
+    model,
+    qwen3_encoder_model: qwen3EncoderModel ?? undefined,
+    qwen3_source_model: sourceModel,
+    type: 'z_image_model_loader',
+    vae_model: vaeModel ?? undefined,
+  });
+  const loraSource = activeLoras.length
+    ? addTransformerLoraCollectionLoader(graph, activeLoras, 'z_image_lora_collection_loader', modelLoader, [
+        'transformer',
+        'qwen3_encoder',
+      ])
+    : modelLoader;
+  const posCond = addNode(graph, { id: 'pos_cond', type: 'z_image_text_encoder' });
+  const posCondCollect = addNode(graph, { id: 'pos_cond_collect', type: 'collect' });
+  const negCond = useCfg ? addNode(graph, { id: 'neg_cond', type: 'z_image_text_encoder' }) : null;
+  const negCondCollect = useCfg ? addNode(graph, { id: 'neg_cond_collect', type: 'collect' }) : null;
+  const denoise = addNode(graph, {
+    denoising_end: 1,
+    denoising_start: 0,
+    guidance_scale: settings.cfgScale,
+    height: settings.height,
+    id: 'denoise_latents',
+    scheduler,
+    steps: settings.steps,
+    type: 'z_image_denoise',
+    width: settings.width,
+  });
+  const output = addImageOutputNode(graph, 'z_image_l2i', outputIsIntermediate);
+
+  addEdge(graph, loraSource, 'transformer', denoise, 'transformer');
+  addEdge(graph, loraSource, 'qwen3_encoder', posCond, 'qwen3_encoder');
+  addEdge(graph, modelLoader, 'vae', denoise, 'vae');
+  addEdge(graph, modelLoader, 'vae', output, 'vae');
+  addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+  addEdge(graph, posCond, 'conditioning', posCondCollect, 'item');
+  addEdge(graph, posCondCollect, 'collection', denoise, 'positive_conditioning');
+
+  if (negCond && negCondCollect) {
+    addEdge(graph, loraSource, 'qwen3_encoder', negCond, 'qwen3_encoder');
+    addEdge(graph, negativePrompt, 'value', negCond, 'prompt');
+    addEdge(graph, negCond, 'conditioning', negCondCollect, 'item');
+    addEdge(graph, negCondCollect, 'collection', denoise, 'negative_conditioning');
+  }
+
+  addEdge(graph, seed, 'value', denoise, 'seed');
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addMetadata(graph, output, settings, model, 'z_image_txt2img', projectSettings, {
+    qwen3_encoder: qwen3EncoderModel ?? undefined,
+    qwen3_source: sourceModel,
+    scheduler,
+    vae: vaeModel ?? undefined,
+  });
+
+  return graph;
+};
+
+const buildAnimaGraph = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  const vaeModel = requireComponent(settings.vae && isAnimaVae(settings.vae) ? settings.vae : null, 'Anima VAE');
+  const qwen3EncoderModel = requireComponent(
+    settings.qwen3EncoderModel && isAnimaQwen3Encoder(settings.qwen3EncoderModel) ? settings.qwen3EncoderModel : null,
+    'Qwen3 Encoder'
+  );
+  const graph: BackendGraphContract = { edges: [], id: createId('anima_graph'), nodes: {} };
+  const { negativePrompt, positivePrompt, seed } = addPromptAndSeedNodes(graph);
+  const scheduler = coerceSchedulerForGraph(model, settings.scheduler);
+  const activeLoras = getActiveCompatibleLoras(settings, model);
+  const useCfg = settings.cfgScale > 1;
+  const modelLoader = addNode(graph, {
+    id: 'model_loader',
+    model,
+    qwen3_encoder_model: qwen3EncoderModel,
+    type: 'anima_model_loader',
+    vae_model: vaeModel,
+  });
+  const loraSource = activeLoras.length
+    ? addTransformerLoraCollectionLoader(graph, activeLoras, 'anima_lora_collection_loader', modelLoader, [
+        'transformer',
+        'qwen3_encoder',
+      ])
+    : modelLoader;
+  const posCond = addNode(graph, { id: 'pos_cond', type: 'anima_text_encoder' });
+  const posCondCollect = addNode(graph, { id: 'pos_cond_collect', type: 'collect' });
+  const negCond = useCfg ? addNode(graph, { id: 'neg_cond', type: 'anima_text_encoder' }) : null;
+  const negCondCollect = useCfg ? addNode(graph, { id: 'neg_cond_collect', type: 'collect' }) : null;
+  const denoise = addNode(graph, {
+    denoising_end: 1,
+    denoising_start: 0,
+    guidance_scale: settings.cfgScale,
+    height: settings.height,
+    id: 'denoise_latents',
+    scheduler,
+    steps: settings.steps,
+    type: 'anima_denoise',
+    width: settings.width,
+  });
+  const output = addImageOutputNode(graph, 'anima_l2i', outputIsIntermediate);
+
+  addEdge(graph, loraSource, 'transformer', denoise, 'transformer');
+  addEdge(graph, loraSource, 'qwen3_encoder', posCond, 'qwen3_encoder');
+  addEdge(graph, modelLoader, 'vae', output, 'vae');
+  addEdge(graph, positivePrompt, 'value', posCond, 'prompt');
+  addEdge(graph, posCond, 'conditioning', posCondCollect, 'item');
+  addEdge(graph, posCondCollect, 'collection', denoise, 'positive_conditioning');
+
+  if (negCond && negCondCollect) {
+    addEdge(graph, loraSource, 'qwen3_encoder', negCond, 'qwen3_encoder');
+    addEdge(graph, negativePrompt, 'value', negCond, 'prompt');
+    addEdge(graph, negCond, 'conditioning', negCondCollect, 'item');
+    addEdge(graph, negCondCollect, 'collection', denoise, 'negative_conditioning');
+  }
+
+  addEdge(graph, seed, 'value', denoise, 'seed');
+  addEdge(graph, denoise, 'latents', output, 'latents');
+  addMetadata(graph, output, settings, model, 'anima_txt2img', projectSettings, {
+    qwen3_encoder: qwen3EncoderModel,
+    scheduler,
+    vae: vaeModel,
+  });
+
+  return graph;
+};
+
+const buildExternalGraph = (
+  settings: GenerateSettings,
+  model: GenerateModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): BackendGraphContract => {
+  if (model.type !== 'external_image_generator') {
+    throw new Error('Selected model is not an external image generator.');
+  }
+
+  if (model.capabilities?.modes && !model.capabilities.modes.includes('txt2img')) {
+    throw new Error(`${model.name} does not support text-to-image generation.`);
+  }
+
+  const providerId = typeof model.provider_id === 'string' ? model.provider_id : '';
+  const nodeType = getExternalProviderNodeType(providerId);
+
+  if (!nodeType) {
+    throw new Error(`No invocation node registered for external provider '${providerId}'.`);
+  }
+
+  const graph: BackendGraphContract = { edges: [], id: createId('external_graph'), nodes: {} };
+  const { negativePrompt, positivePrompt, seed } = addPromptAndSeedNodes(graph);
+  const output = addNode(graph, {
+    height: settings.height,
+    id: 'canvas_output',
+    image_size: null,
+    is_intermediate: outputIsIntermediate,
+    mode: 'txt2img',
+    model,
+    num_images: 1,
+    type: nodeType,
+    use_cache: false,
+    width: settings.width,
+  });
+
+  addEdge(graph, positivePrompt, 'value', output, 'prompt');
+  if (model.capabilities?.supports_negative_prompt === true) {
+    addEdge(graph, negativePrompt, 'value', output, 'negative_prompt');
+  }
+
+  if (model.capabilities?.supports_seed === true) {
+    addEdge(graph, seed, 'value', output, 'seed');
+  }
+  if (model.capabilities?.supports_reference_images === true) {
+    const referenceImages = getEnabledReferenceImages(settings, 'external_reference_image')
+      .map((referenceImage) => referenceImage.config.image)
+      .filter((image): image is GenerateReferenceImageAsset => image !== null)
+      .map(toImageField);
+
+    if (referenceImages.length > 0) {
+      (output as Record<string, unknown>).reference_images = referenceImages;
+    }
+  }
+  addMetadata(graph, output, settings, model, null, projectSettings, { scheduler: undefined });
+  addReferenceImageMetadata(graph, output, settings);
+
+  return graph;
+};
+
+type GenerateGraphBuilder = (
+  settings: GenerateSettings,
+  model: MainModelConfig,
+  outputIsIntermediate: boolean,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+) => BackendGraphContract;
+
+export const GRAPH_BUILDERS = {
+  'sd-1': buildSDGraph,
+  'sd-2': buildSDGraph,
+  sdxl: buildSDGraph,
+  'sd-3': buildSD3Graph,
+  flux: buildFluxGraph,
+  flux2: buildFlux2Graph,
+  cogview4: buildCogView4Graph,
+  'qwen-image': buildQwenImageGraph,
+  'z-image': buildZImageGraph,
+  anima: buildAnimaGraph,
+} satisfies Record<SupportedGenerateBase, GenerateGraphBuilder>;
+
+export const compileGenerateGraph = (
+  settings: GenerateSettings,
+  model: GenerateModelConfig,
+  destination: ResultDestination,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>
+): CompiledGenerateGraph => {
+  const validationReasons = getGenerationValidationReasons(model, settings);
+
+  if (validationReasons.length > 0) {
+    throw new Error(validationReasons[0]);
+  }
+
+  const outputIsIntermediate = destination === 'canvas';
+  const backendGraph = (() => {
+    if (model.type === 'external_image_generator') {
+      return buildExternalGraph(settings, model, outputIsIntermediate, projectSettings);
+    }
+
+    const builder = GRAPH_BUILDERS[model.base as SupportedGenerateBase];
+
+    if (!builder) {
+      const dimensionGrid = getGenerationDimensions(model).grid;
+
+      throw new Error(`${model.name} dimensions must be multiples of ${dimensionGrid}.`);
+    }
+
+    return builder(settings, model, outputIsIntermediate, projectSettings);
+  })();
+
+  return {
+    backendGraph,
+    graph: toGraphContract(backendGraph, `${model.name} txt2img`),
+    negativePromptNodeId: 'negative_prompt',
+    positivePromptNodeId: 'positive_prompt',
+    seedNodeId: 'seed',
+  };
+};
+
+export const resolveGenerateSeed = (settings: GenerateSettings): number =>
+  settings.shouldRandomizeSeed ? Math.floor(Math.random() * SEED_MAX) : settings.seed;
+
+export const generateSeedSequence = (start: number, count: number): number[] => {
+  const seedCount = Math.max(1, Math.round(count));
+  const seeds: number[] = [];
+
+  for (let index = 0; index < seedCount; index += 1) {
+    seeds.push((start + index) % SEED_MAX);
+  }
+
+  return seeds;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/graphBuilder.ts b/invokeai/frontend/webv2/src/workbench/generation/graphBuilder.ts
new file mode 100644
index 00000000000..bfae73f1609
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/graphBuilder.ts
@@ -0,0 +1,118 @@
+import type {
+  BackendGraphContract,
+  BackendGraphEdgeContract,
+  BackendInvocationContract,
+  ProjectSettings,
+} from '@workbench/types';
+
+import type { GenerateLora, GenerateModelConfig, GenerateSettings } from './types';
+
+import { coerceSchedulerForGraph } from './baseGenerationPolicies';
+import { isLoraCompatibleWithModel } from './settings';
+
+const now = (): string => new Date().toISOString();
+
+export const createId = (prefix: string): string =>
+  `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+
+export const addNode = <T extends BackendInvocationContract>(graph: BackendGraphContract, node: T): T => {
+  graph.nodes[node.id] = {
+    is_intermediate: true,
+    use_cache: true,
+    ...node,
+  };
+
+  return graph.nodes[node.id] as T;
+};
+
+export const addEdge = (
+  graph: BackendGraphContract,
+  source: BackendInvocationContract,
+  sourceField: string,
+  destination: BackendInvocationContract,
+  destinationField: string
+): BackendGraphEdgeContract => {
+  const edge = {
+    destination: { field: destinationField, node_id: destination.id },
+    source: { field: sourceField, node_id: source.id },
+  };
+  graph.edges.push(edge);
+
+  return edge;
+};
+
+export const getActiveCompatibleLoras = (settings: GenerateSettings, model: GenerateModelConfig): GenerateLora[] =>
+  settings.loras.filter((lora) => lora.isEnabled && isLoraCompatibleWithModel(lora.model, model));
+
+export const toModelIdentifier = (
+  model: { base: string; key: string; name: string; type: string } & Record<string, unknown>
+) => ({
+  base: model.base,
+  key: model.key,
+  name: model.name,
+  type: model.type,
+  ...(typeof model.hash === 'string' ? { hash: model.hash } : {}),
+  ...(typeof model.submodel_type === 'string' ? { submodel_type: model.submodel_type } : {}),
+});
+
+export const addMetadata = (
+  graph: BackendGraphContract,
+  outputNode: BackendInvocationContract,
+  settings: GenerateSettings,
+  model: GenerateModelConfig,
+  generationMode: string | null,
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>,
+  extras: Record<string, unknown> = {}
+) => {
+  const activeLoras = getActiveCompatibleLoras(settings, model);
+  const scheduler = coerceSchedulerForGraph(model, settings.scheduler);
+  const metadata = addNode(graph, {
+    cfg_scale: settings.cfgScale,
+    cfg_rescale_multiplier: settings.cfgRescaleMultiplier,
+    ...(generationMode ? { generation_mode: generationMode } : {}),
+    height: settings.height,
+    id: createId('core_metadata'),
+    model,
+    rand_device: projectSettings.useCpuNoise ? 'cpu' : 'cuda',
+    scheduler,
+    seamless_x: settings.seamlessXAxis,
+    seamless_y: settings.seamlessYAxis,
+    steps: settings.steps,
+    type: 'core_metadata',
+    vae: settings.vae ?? undefined,
+    width: settings.width,
+    ...extras,
+    ...(activeLoras.length
+      ? {
+          loras: activeLoras.map((lora) => ({
+            model: toModelIdentifier(lora.model),
+            weight: lora.weight,
+          })),
+        }
+      : {}),
+    ...(model.base === 'sdxl' ? {} : { clip_skip: settings.clipSkip }),
+  });
+
+  addEdge(graph, graph.nodes.seed, 'value', metadata, 'seed');
+  addEdge(graph, graph.nodes.positive_prompt, 'value', metadata, 'positive_prompt');
+  if (graph.nodes.negative_prompt) {
+    addEdge(graph, graph.nodes.negative_prompt, 'value', metadata, 'negative_prompt');
+  }
+  addEdge(graph, metadata, 'metadata', outputNode, 'metadata');
+};
+
+export const toGraphContract = (backendGraph: BackendGraphContract, label: string) => ({
+  backendGraph,
+  edges: backendGraph.edges.map((edge, index) => ({
+    id: `edge-${index}`,
+    sourceField: edge.source.field,
+    sourceNodeId: edge.source.node_id,
+    targetField: edge.destination.field,
+    targetNodeId: edge.destination.node_id,
+  })),
+  id: backendGraph.id,
+  label,
+  nodes: Object.values(backendGraph.nodes).map(({ id, type, ...inputs }) => ({ id, inputs, type })),
+  updatedAt: now(),
+  version: 1 as const,
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/prompt/ast.test.ts b/invokeai/frontend/webv2/src/workbench/generation/prompt/ast.test.ts
new file mode 100644
index 00000000000..02be42e8cb7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/prompt/ast.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+
+import { parsePrompt, serializePrompt, tokenizePrompt } from './ast';
+
+describe('prompt AST', () => {
+  const roundTrip = (prompt: string): string => serializePrompt(parsePrompt(prompt));
+
+  it('tokenizes symbolic weights without treating hyphenated words as attention', () => {
+    expect(tokenizePrompt('cat+').map((token) => token.type)).toEqual(['word', 'weight']);
+    expect(tokenizePrompt('razor-sharp').map((token) => token.type)).toEqual(['word', 'punct', 'word']);
+  });
+
+  it('parses prompt function argument ranges', () => {
+    const node = parsePrompt("('one two', 'three four').and()")[0];
+
+    expect(node?.type).toBe('prompt_function');
+
+    if (node?.type !== 'prompt_function') {
+      return;
+    }
+
+    expect(node.promptArgs).toHaveLength(2);
+    expect(node.promptArgs[0]?.contentRange).toEqual({ start: 2, end: 9 });
+    expect(node.promptArgs[1]?.contentRange).toEqual({ start: 13, end: 23 });
+  });
+
+  it.each([
+    'a cat',
+    '(a cat)',
+    '(a cat)1.2',
+    'cat+',
+    'cat++',
+    'cat-',
+    '(hello world)+',
+    '\\(medium\\)',
+    'colored pencil \\(medium\\) (enhanced)',
+    '<embedding_name>',
+    'portrait \\(realistic\\) (high quality)1.2',
+    "('one two', 'three four').and()",
+    "('one', 'two three. four.').or()",
+    "('one', 'two').blend(0.7, 0.3)",
+    "('hello+', '(world)-').and()",
+    "some text, ('a', 'b').and(), more text",
+    "('a', 'b', 'c').blend(0.5, 0.3, 0.2)",
+    '(one two, three four).and()',
+    '(one two, three four).blend(0.7, 0.3)',
+    '(a, b, c).blend(0.5, 0.3, 0.2)',
+    'some text, (a, b).and(), more text',
+    '(\u201cone\u201d, \u201ctwo\u201d).and()',
+    '(\u2018one\u2019, \u2018two\u2019).or()',
+    "('one',\n 'two',\n 'three').and()",
+    'A bear \\(with razor-sharp teeth\\) in a forest.',
+  ])('round-trips %s', (prompt) => {
+    expect(roundTrip(prompt)).toBe(prompt);
+  });
+
+  it('normalizes whitespace between prompt function args and method names', () => {
+    expect(roundTrip("('one', 'two')\n.and()")).toBe("('one', 'two').and()");
+    expect(roundTrip('(one, two)\n.and()')).toBe('(one, two).and()');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/prompt/ast.ts b/invokeai/frontend/webv2/src/workbench/generation/prompt/ast.ts
new file mode 100644
index 00000000000..791214af285
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/prompt/ast.ts
@@ -0,0 +1,792 @@
+export type PromptAttention = string | number;
+
+export interface PromptRange {
+  start: number;
+  end: number;
+}
+
+export type PromptToken =
+  | { type: 'word'; value: string; range: PromptRange }
+  | { type: 'whitespace'; value: string; range: PromptRange }
+  | { type: 'punct'; value: string; range: PromptRange }
+  | { type: 'lparen'; range: PromptRange }
+  | { type: 'rparen'; range: PromptRange }
+  | { type: 'weight'; value: PromptAttention; range: PromptRange }
+  | { type: 'lembed'; range: PromptRange }
+  | { type: 'rembed'; range: PromptRange }
+  | { type: 'escaped_paren'; value: '(' | ')'; range: PromptRange };
+
+export interface PromptFunctionArg {
+  nodes: PromptAstNode[];
+  quote: string;
+  contentRange: PromptRange;
+  separator?: string;
+}
+
+export type PromptAstNode =
+  | { type: 'word'; text: string; attention?: PromptAttention; range: PromptRange; isSelection?: boolean }
+  | { type: 'group'; children: PromptAstNode[]; attention?: PromptAttention; range: PromptRange; isSelection?: boolean }
+  | { type: 'embedding'; value: string; range: PromptRange; isSelection?: boolean }
+  | { type: 'whitespace'; value: string; range: PromptRange; isSelection?: boolean }
+  | { type: 'punct'; value: string; range: PromptRange; isSelection?: boolean }
+  | { type: 'escaped_paren'; value: '(' | ')'; range: PromptRange; isSelection?: boolean }
+  | {
+      type: 'prompt_function';
+      name: string;
+      promptArgs: PromptFunctionArg[];
+      functionParams: string;
+      range: PromptRange;
+      isSelection?: boolean;
+    };
+
+const WORD_CHAR = /[A-Za-z0-9_]/;
+const WHITESPACE = /\s/;
+const NUMERIC_WEIGHT = /^[+-]?\d+(?:\.\d+)?/;
+const SYMBOLIC_WEIGHT = /^[+-]+/;
+const PUNCTUATION = new Set([
+  '.',
+  ',',
+  '/',
+  '!',
+  '?',
+  ';',
+  ':',
+  "'",
+  '"',
+  '\u2018',
+  '\u2019',
+  '\u201c',
+  '\u201d',
+  '`',
+  '~',
+  '@',
+  '#',
+  '$',
+  '%',
+  '^',
+  '&',
+  '*',
+  '=',
+  '_',
+  '|',
+  '+',
+  '-',
+]);
+
+const OPEN_QUOTES = new Set(["'", '"', '\u2018', '\u201c']);
+const CLOSE_QUOTE_BY_OPEN: Record<string, string> = {
+  "'": "'",
+  '"': '"',
+  '\u2018': '\u2019',
+  '\u201c': '\u201d',
+};
+
+const range = (start: number, end: number): PromptRange => ({ start, end });
+
+const isWordChar = (char: string | undefined): boolean => Boolean(char && WORD_CHAR.test(char));
+
+const attentionValue = (raw: string): PromptAttention => {
+  const numeric = Number(raw);
+
+  return Number.isNaN(numeric) ? raw : numeric;
+};
+
+const readWhitespace = (prompt: string, start: number): PromptToken => {
+  let end = start + 1;
+
+  while (end < prompt.length && WHITESPACE.test(prompt[end] ?? '')) {
+    end++;
+  }
+
+  return { type: 'whitespace', value: prompt.slice(start, end), range: range(start, end) };
+};
+
+const readSymbolicAttention = (prompt: string, start: number): { value: string; end: number } | null => {
+  const match = prompt.slice(start).match(SYMBOLIC_WEIGHT)?.[0];
+
+  if (!match) {
+    return null;
+  }
+
+  const end = start + match.length;
+
+  if (isWordChar(prompt[end])) {
+    return null;
+  }
+
+  return { value: match, end };
+};
+
+const readNumericAttention = (prompt: string, start: number): { value: number; end: number } | null => {
+  const match = prompt.slice(start).match(NUMERIC_WEIGHT)?.[0];
+
+  if (!match) {
+    return null;
+  }
+
+  const end = start + match.length;
+
+  if (prompt[end] === '.' || isWordChar(prompt[end])) {
+    return null;
+  }
+
+  return { value: Number(match), end };
+};
+
+const readWord = (prompt: string, start: number): { token: PromptToken; extraToken?: PromptToken; end: number } => {
+  let end = start + 1;
+
+  while (end < prompt.length && isWordChar(prompt[end])) {
+    end++;
+  }
+
+  const token: PromptToken = { type: 'word', value: prompt.slice(start, end), range: range(start, end) };
+  const symbolic = readSymbolicAttention(prompt, end);
+
+  if (!symbolic) {
+    return { token, end };
+  }
+
+  return {
+    token,
+    extraToken: { type: 'weight', value: symbolic.value, range: range(end, symbolic.end) },
+    end: symbolic.end,
+  };
+};
+
+export const tokenizePrompt = (prompt: string): PromptToken[] => {
+  const tokens: PromptToken[] = [];
+  let index = 0;
+
+  while (index < prompt.length) {
+    const char = prompt[index] ?? '';
+
+    if (WHITESPACE.test(char)) {
+      const token = readWhitespace(prompt, index);
+      tokens.push(token);
+      index = token.range.end;
+      continue;
+    }
+
+    if (char === '\\' && (prompt[index + 1] === '(' || prompt[index + 1] === ')')) {
+      tokens.push({ type: 'escaped_paren', value: prompt[index + 1] as '(' | ')', range: range(index, index + 2) });
+      index += 2;
+      continue;
+    }
+
+    if (char === '(') {
+      tokens.push({ type: 'lparen', range: range(index, index + 1) });
+      index++;
+      continue;
+    }
+
+    if (char === ')') {
+      tokens.push({ type: 'rparen', range: range(index, index + 1) });
+
+      const numeric = readNumericAttention(prompt, index + 1);
+      const symbolic = numeric ? null : readSymbolicAttention(prompt, index + 1);
+      const weight = numeric ?? symbolic;
+
+      if (weight) {
+        tokens.push({ type: 'weight', value: weight.value, range: range(index + 1, weight.end) });
+        index = weight.end;
+      } else {
+        index++;
+      }
+      continue;
+    }
+
+    if (char === '<') {
+      tokens.push({ type: 'lembed', range: range(index, index + 1) });
+      index++;
+      continue;
+    }
+
+    if (char === '>') {
+      tokens.push({ type: 'rembed', range: range(index, index + 1) });
+      index++;
+      continue;
+    }
+
+    if (isWordChar(char)) {
+      const result = readWord(prompt, index);
+      tokens.push(result.token);
+
+      if (result.extraToken) {
+        tokens.push(result.extraToken);
+      }
+
+      index = result.end;
+      continue;
+    }
+
+    if (PUNCTUATION.has(char)) {
+      tokens.push({ type: 'punct', value: char, range: range(index, index + 1) });
+      index++;
+      continue;
+    }
+
+    tokens.push({ type: 'word', value: char, range: range(index, index + 1) });
+    index++;
+  }
+
+  return tokens;
+};
+
+const tokenValue = (token: PromptToken | undefined): string | undefined => {
+  if (!token || !('value' in token)) {
+    return undefined;
+  }
+
+  return String(token.value);
+};
+
+const tokenSource = (token: PromptToken): string => {
+  switch (token.type) {
+    case 'lparen':
+      return '(';
+    case 'rparen':
+      return ')';
+    case 'lembed':
+      return '<';
+    case 'rembed':
+      return '>';
+    case 'escaped_paren':
+      return `\\${token.value}`;
+    case 'weight':
+      return String(token.value);
+    default:
+      return token.value;
+  }
+};
+
+class PromptParser {
+  private index = 0;
+
+  constructor(private readonly tokens: PromptToken[]) {}
+
+  parse(): PromptAstNode[] {
+    return this.parseNodes();
+  }
+
+  private peek(offset = 0): PromptToken | undefined {
+    return this.tokens[this.index + offset];
+  }
+
+  private consume(): PromptToken {
+    const token = this.tokens[this.index];
+
+    if (!token) {
+      throw new Error('Unexpected end of prompt tokens');
+    }
+
+    this.index++;
+    return token;
+  }
+
+  private isPunct(offset: number, value: string): boolean {
+    return this.peek(offset)?.type === 'punct' && tokenValue(this.peek(offset)) === value;
+  }
+
+  private quotedPromptFunctionAhead(): boolean {
+    let offset = 0;
+
+    while (this.peek(offset)?.type === 'whitespace') {
+      offset++;
+    }
+
+    const token = this.peek(offset);
+
+    return token?.type === 'punct' && OPEN_QUOTES.has(tokenValue(token) ?? '');
+  }
+
+  private unquotedPromptFunctionAhead(): boolean {
+    let offset = 0;
+    let depth = 0;
+    let hasComma = false;
+
+    while (this.peek(offset)) {
+      const token = this.peek(offset);
+
+      if (token?.type === 'lparen') {
+        depth++;
+      } else if (token?.type === 'rparen') {
+        if (depth === 0) {
+          if (!hasComma) {
+            return false;
+          }
+
+          let tailOffset = offset + 1;
+
+          while (this.peek(tailOffset)?.type === 'whitespace') {
+            tailOffset++;
+          }
+
+          return (
+            this.isPunct(tailOffset, '.') &&
+            this.peek(tailOffset + 1)?.type === 'word' &&
+            this.peek(tailOffset + 2)?.type === 'lparen'
+          );
+        }
+
+        depth--;
+      } else if (depth === 0 && token?.type === 'punct' && tokenValue(token) === ',') {
+        hasComma = true;
+      }
+
+      offset++;
+    }
+
+    return false;
+  }
+
+  private parseMethodTail(savedIndex: number): { name: string; params: string; end: number } | null {
+    while (this.peek()?.type === 'whitespace') {
+      this.consume();
+    }
+
+    if (!this.isPunct(0, '.') || this.peek(1)?.type !== 'word' || this.peek(2)?.type !== 'lparen') {
+      this.index = savedIndex;
+      return null;
+    }
+
+    this.consume();
+    const name = tokenValue(this.consume()) ?? '';
+    this.consume();
+
+    let depth = 0;
+    let params = '';
+
+    while (this.peek()) {
+      const token = this.peek();
+
+      if (token?.type === 'rparen' && depth === 0) {
+        break;
+      }
+
+      const consumed = this.consume();
+
+      if (consumed.type === 'lparen') {
+        depth++;
+      } else if (consumed.type === 'rparen') {
+        depth--;
+      }
+
+      params += tokenSource(consumed);
+    }
+
+    if (this.peek()?.type !== 'rparen') {
+      this.index = savedIndex;
+      return null;
+    }
+
+    const close = this.consume();
+
+    return { name, params, end: close.range.end };
+  }
+
+  private parseQuotedPromptFunction(
+    lparen: PromptToken & { type: 'lparen' },
+    savedIndex: number
+  ): PromptAstNode | null {
+    const args: PromptFunctionArg[] = [];
+    let expectedOpenQuote: string | null = null;
+    let pendingSeparator: string | undefined;
+
+    while (this.peek()) {
+      while (this.peek()?.type === 'whitespace') {
+        this.consume();
+      }
+
+      if (this.peek()?.type === 'rparen') {
+        break;
+      }
+
+      if (args.length > 0) {
+        if (!this.isPunct(0, ',')) {
+          this.index = savedIndex;
+          return null;
+        }
+
+        this.consume();
+        pendingSeparator = this.consumeWhitespaceValue();
+      }
+
+      const openQuote = this.peek();
+      const quote = tokenValue(openQuote);
+
+      if (openQuote?.type !== 'punct' || !quote || !OPEN_QUOTES.has(quote)) {
+        this.index = savedIndex;
+        return null;
+      }
+
+      if (expectedOpenQuote === null) {
+        expectedOpenQuote = quote;
+      } else if (quote !== expectedOpenQuote) {
+        this.index = savedIndex;
+        return null;
+      }
+
+      this.consume();
+
+      const closeQuote = CLOSE_QUOTE_BY_OPEN[quote] ?? quote;
+      const contentStart = openQuote.range.end;
+      const argTokens: PromptToken[] = [];
+      let contentEnd = contentStart;
+
+      while (this.peek() && !(this.peek()?.type === 'punct' && tokenValue(this.peek()) === closeQuote)) {
+        const token = this.consume();
+        argTokens.push(token);
+        contentEnd = token.range.end;
+      }
+
+      if (!(this.peek()?.type === 'punct' && tokenValue(this.peek()) === closeQuote)) {
+        this.index = savedIndex;
+        return null;
+      }
+
+      this.consume();
+      args.push({
+        contentRange: range(contentStart, contentEnd),
+        nodes: parsePromptTokens(argTokens),
+        quote,
+        separator: pendingSeparator,
+      });
+      pendingSeparator = undefined;
+    }
+
+    if (args.length === 0 || this.peek()?.type !== 'rparen') {
+      this.index = savedIndex;
+      return null;
+    }
+
+    this.consume();
+
+    const tail = this.parseMethodTail(savedIndex);
+
+    if (!tail) {
+      return null;
+    }
+
+    return {
+      type: 'prompt_function',
+      name: tail.name,
+      promptArgs: args,
+      functionParams: tail.params,
+      range: range(lparen.range.start, tail.end),
+    };
+  }
+
+  private parseUnquotedPromptFunction(
+    lparen: PromptToken & { type: 'lparen' },
+    savedIndex: number
+  ): PromptAstNode | null {
+    const args: PromptFunctionArg[] = [];
+    let pendingSeparator: string | undefined;
+
+    while (this.peek()) {
+      if (this.peek()?.type === 'rparen') {
+        break;
+      }
+
+      if (args.length > 0) {
+        if (!this.isPunct(0, ',')) {
+          this.index = savedIndex;
+          return null;
+        }
+
+        this.consume();
+        pendingSeparator = this.consumeWhitespaceValue();
+      }
+
+      const argTokens = this.consumeUnquotedArgTokens();
+
+      if (argTokens.length === 0) {
+        this.index = savedIndex;
+        return null;
+      }
+
+      const trimmedTokens = trimWhitespaceTokens(argTokens);
+      const first = trimmedTokens[0];
+      const last = trimmedTokens.at(-1);
+
+      if (!first || !last) {
+        this.index = savedIndex;
+        return null;
+      }
+
+      args.push({
+        contentRange: range(first.range.start, last.range.end),
+        nodes: parsePromptTokens(trimmedTokens),
+        quote: '',
+        separator: pendingSeparator,
+      });
+      pendingSeparator = undefined;
+    }
+
+    if (args.length < 2 || this.peek()?.type !== 'rparen') {
+      this.index = savedIndex;
+      return null;
+    }
+
+    this.consume();
+
+    const tail = this.parseMethodTail(savedIndex);
+
+    if (!tail) {
+      return null;
+    }
+
+    return {
+      type: 'prompt_function',
+      name: tail.name,
+      promptArgs: args,
+      functionParams: tail.params,
+      range: range(lparen.range.start, tail.end),
+    };
+  }
+
+  private consumeWhitespaceValue(): string {
+    let value = '';
+
+    while (this.peek()?.type === 'whitespace') {
+      value += tokenValue(this.consume()) ?? '';
+    }
+
+    return value;
+  }
+
+  private consumeUnquotedArgTokens(): PromptToken[] {
+    const tokens: PromptToken[] = [];
+    let depth = 0;
+
+    while (this.peek()) {
+      const token = this.peek();
+
+      if (token?.type === 'lparen') {
+        depth++;
+      } else if (token?.type === 'rparen') {
+        if (depth === 0) {
+          break;
+        }
+
+        depth--;
+      } else if (depth === 0 && token?.type === 'punct' && tokenValue(token) === ',') {
+        break;
+      }
+
+      tokens.push(this.consume());
+    }
+
+    return tokens;
+  }
+
+  private parseNodes(): PromptAstNode[] {
+    const nodes: PromptAstNode[] = [];
+
+    while (this.peek() && this.peek()?.type !== 'rparen') {
+      const token = this.consume();
+
+      switch (token.type) {
+        case 'whitespace':
+          nodes.push({ type: 'whitespace', value: token.value, range: token.range });
+          break;
+        case 'lparen': {
+          const lparen = token;
+          const savedIndex = this.index;
+          const promptFunction = this.parsePromptFunctionIfPresent(lparen, savedIndex);
+
+          if (promptFunction) {
+            nodes.push(promptFunction);
+            break;
+          }
+
+          const children = this.parseNodes();
+          let nodeEnd = lparen.range.end;
+          let attention: PromptAttention | undefined;
+
+          if (this.peek()?.type === 'rparen') {
+            const rparen = this.consume();
+            nodeEnd = rparen.range.end;
+
+            if (this.peek()?.type === 'weight') {
+              const weight = this.consume() as PromptToken & { type: 'weight' };
+              attention = weight.value;
+              nodeEnd = weight.range.end;
+            }
+          } else if (children.length > 0) {
+            nodeEnd = children.at(-1)?.range.end ?? nodeEnd;
+          }
+
+          nodes.push({ type: 'group', attention, children, range: range(lparen.range.start, nodeEnd) });
+          break;
+        }
+        case 'lembed': {
+          let value = '';
+          let nodeEnd = token.range.end;
+
+          while (this.peek() && this.peek()?.type !== 'rembed') {
+            const embedToken = this.consume();
+            value += tokenSource(embedToken);
+            nodeEnd = embedToken.range.end;
+          }
+
+          if (this.peek()?.type === 'rembed') {
+            nodeEnd = this.consume().range.end;
+          }
+
+          nodes.push({ type: 'embedding', value: value.trim(), range: range(token.range.start, nodeEnd) });
+          break;
+        }
+        case 'word': {
+          let nodeEnd = token.range.end;
+          let attention: PromptAttention | undefined;
+
+          if (this.peek()?.type === 'weight') {
+            const weight = this.consume() as PromptToken & { type: 'weight' };
+            attention = attentionValue(String(weight.value));
+            nodeEnd = weight.range.end;
+          }
+
+          nodes.push({ type: 'word', text: token.value, attention, range: range(token.range.start, nodeEnd) });
+          break;
+        }
+        case 'punct':
+          nodes.push({ type: 'punct', value: token.value, range: token.range });
+          break;
+        case 'escaped_paren':
+          nodes.push({ type: 'escaped_paren', value: token.value, range: token.range });
+          break;
+        default:
+          break;
+      }
+    }
+
+    return nodes;
+  }
+
+  private parsePromptFunctionIfPresent(
+    lparen: PromptToken & { type: 'lparen' },
+    savedIndex: number
+  ): PromptAstNode | null {
+    if (this.quotedPromptFunctionAhead()) {
+      const quoted = this.parseQuotedPromptFunction(lparen, savedIndex);
+
+      if (quoted) {
+        return quoted;
+      }
+    }
+
+    if (this.unquotedPromptFunctionAhead()) {
+      const unquoted = this.parseUnquotedPromptFunction(lparen, savedIndex);
+
+      if (unquoted) {
+        return unquoted;
+      }
+    }
+
+    this.index = savedIndex;
+    return null;
+  }
+}
+
+const trimWhitespaceTokens = (tokens: PromptToken[]): PromptToken[] => {
+  let start = 0;
+  let end = tokens.length;
+
+  while (start < end && tokens[start]?.type === 'whitespace') {
+    start++;
+  }
+
+  while (end > start && tokens[end - 1]?.type === 'whitespace') {
+    end--;
+  }
+
+  return tokens.slice(start, end);
+};
+
+export const parsePromptTokens = (tokens: PromptToken[]): PromptAstNode[] => new PromptParser(tokens).parse();
+
+export const parsePrompt = (prompt: string): PromptAstNode[] => parsePromptTokens(tokenizePrompt(prompt));
+
+interface SerializeVisitor {
+  onNode?: (node: PromptAstNode, start: number, end: number) => void;
+}
+
+const appendAttention = (attention: PromptAttention | undefined): string =>
+  attention === undefined ? '' : String(attention);
+
+const serializeInto = (nodes: PromptAstNode[], output: { value: string }, visitor?: SerializeVisitor): void => {
+  for (const node of nodes) {
+    const start = output.value.length;
+
+    switch (node.type) {
+      case 'punct':
+      case 'whitespace':
+        output.value += node.value;
+        break;
+      case 'escaped_paren':
+        output.value += `\\${node.value}`;
+        break;
+      case 'word':
+        output.value += `${node.text}${appendAttention(node.attention)}`;
+        break;
+      case 'group':
+        output.value += '(';
+        serializeInto(node.children, output, visitor);
+        output.value += `)${appendAttention(node.attention)}`;
+        break;
+      case 'embedding':
+        output.value += `<${node.value}>`;
+        break;
+      case 'prompt_function':
+        output.value += '(';
+        node.promptArgs.forEach((arg, index) => {
+          if (index > 0) {
+            output.value += `,${arg.separator ?? ' '}`;
+          }
+
+          output.value += arg.quote;
+          serializeInto(arg.nodes, output, visitor);
+          output.value += CLOSE_QUOTE_BY_OPEN[arg.quote] ?? arg.quote;
+        });
+        output.value += `).${node.name}(${node.functionParams})`;
+        break;
+    }
+
+    visitor?.onNode?.(node, start, output.value.length);
+  }
+};
+
+export const serializePrompt = (nodes: PromptAstNode[]): string => {
+  const output = { value: '' };
+
+  serializeInto(nodes, output);
+
+  return output.value;
+};
+
+export const serializePromptWithSelection = (
+  nodes: PromptAstNode[]
+): { prompt: string; selectionStart: number; selectionEnd: number } => {
+  const output = { value: '' };
+  let selectionStart = Infinity;
+  let selectionEnd = -1;
+
+  serializeInto(nodes, output, {
+    onNode: (node, start, end) => {
+      if (!node.isSelection) {
+        return;
+      }
+
+      selectionStart = Math.min(selectionStart, start);
+      selectionEnd = Math.max(selectionEnd, end);
+    },
+  });
+
+  if (selectionStart === Infinity) {
+    return { prompt: output.value, selectionStart: 0, selectionEnd: output.value.length };
+  }
+
+  return { prompt: output.value, selectionStart, selectionEnd };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/prompt/attention.test.ts b/invokeai/frontend/webv2/src/workbench/generation/prompt/attention.test.ts
new file mode 100644
index 00000000000..c24305d802d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/prompt/attention.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+
+import type { PromptAttentionDirection } from './attention';
+
+import { adjustPromptAttention } from './attention';
+
+const adjust = (
+  prompt: string,
+  selected: string | [number, number],
+  direction: PromptAttentionDirection,
+  preferNumericAttentionStyle = false
+) => {
+  const range =
+    typeof selected === 'string'
+      ? ([prompt.indexOf(selected), prompt.indexOf(selected) + selected.length] as [number, number])
+      : selected;
+
+  return adjustPromptAttention(prompt, range[0], range[1], direction, preferNumericAttentionStyle);
+};
+
+describe('prompt attention adjustment', () => {
+  it.each([
+    ['hello world', 'hello', 'increment', 'hello+ world'],
+    ['hello world', 'hello', 'decrement', 'hello- world'],
+    ['hello+ world', 'hello+', 'increment', 'hello++ world'],
+    ['hello+ world', 'hello+', 'decrement', 'hello world'],
+    ['hello- world', 'hello-', 'decrement', 'hello-- world'],
+    ['hello- world', 'hello-', 'increment', 'hello world'],
+  ] as const)('adjusts a single word: %s %s', (prompt, selected, direction, expected) => {
+    expect(adjust(prompt, selected, direction).prompt).toBe(expected);
+  });
+
+  it.each([
+    ['hello world', [0, 11], 'increment', '(hello world)+'],
+    ['hello world', [0, 11], 'decrement', '(hello world)-'],
+    ['one, two', [3, 3], 'increment', 'one+, two'],
+    ['one, two', [5, 5], 'increment', 'one, two+'],
+  ] as const)('adjusts selections and cursor boundaries: %s', (prompt, selected, direction, expected) => {
+    expect(adjust(prompt, selected as [number, number], direction).prompt).toBe(expected);
+  });
+
+  it.each([
+    ['(hello world)+', [13, 14], 'increment', '(hello world)++'],
+    ['(hello world)+', [0, 14], 'decrement', 'hello world'],
+    ['(a b)+', [1, 2], 'increment', '(a+ b)+'],
+    ['(a b)+ c', [3, 8], 'increment', '(a b+ c)+'],
+    ['(a b)+ c', [3, 8], 'decrement', 'a+ b c-'],
+  ] as const)('preserves and splits existing groups: %s', (prompt, selected, direction, expected) => {
+    expect(adjust(prompt, selected as [number, number], direction).prompt).toBe(expected);
+  });
+
+  it('preserves the adjusted selection range', () => {
+    const result = adjust('(a b)+', [1, 2], 'increment');
+
+    expect(result.prompt).toBe('(a+ b)+');
+    expect(result.prompt.slice(result.selectionStart, result.selectionEnd)).toBe('a+');
+  });
+
+  it.each([
+    ['(masterpiece)1.3', [0, 16], 'increment', '(masterpiece)1.4'],
+    ['(masterpiece)1.3', [0, 16], 'decrement', '(masterpiece)1.2'],
+    ['(sunny midday light)1.15', [0, 24], 'increment', '(sunny midday light)1.25'],
+  ] as const)('adjusts explicit numeric weights additively: %s', (prompt, selected, direction, expected) => {
+    expect(adjust(prompt, selected as [number, number], direction).prompt).toBe(expected);
+  });
+
+  it('does not corrupt unselected numeric weights', () => {
+    const prompt = '(masterpiece)1.3, best quality, (sunny midday light)1.15, clear sky';
+    const result = adjust(prompt, 'clear sky', 'increment');
+
+    expect(result.prompt).toContain('(masterpiece)1.3');
+    expect(result.prompt).toContain('(sunny midday light)1.15');
+    expect(result.prompt).toContain('(clear sky)+');
+    expect(result.prompt).not.toMatch(/\d\.\d{5,}/);
+  });
+
+  it.each([
+    ["('hello world', 'other').and()", 'hello', 'increment', "('hello+ world', 'other').and()"],
+    ["('a', 'hello world').or()", 'hello world', 'increment', "('a', '(hello world)+').or()"],
+    ["('one two', 'three four').blend(0.7, 0.3)", 'two', 'increment', "('one two+', 'three four').blend(0.7, 0.3)"],
+    ['(hello world, foo bar).and()', 'hello', 'increment', '(hello+ world, foo bar).and()'],
+    [
+      '(\u201chello world\u201d, \u201cother\u201d).and()',
+      'hello',
+      'increment',
+      '(\u201chello+ world\u201d, \u201cother\u201d).and()',
+    ],
+  ] as const)('adjusts inside prompt function args: %s', (prompt, selected, direction, expected) => {
+    expect(adjust(prompt, selected, direction).prompt).toBe(expected);
+  });
+
+  it('adjusts both prompt function args when a selection spans an argument separator', () => {
+    const prompt = "('one two', 'three four').and()";
+    const start = prompt.indexOf('two');
+    const end = prompt.indexOf('three') + 'three'.length;
+    const result = adjustPromptAttention(prompt, start, end, 'increment');
+
+    expect(result.prompt).toBe("('one two+', 'three+ four').and()");
+    expect(result.prompt.slice(result.selectionStart, result.selectionEnd)).toContain('two+');
+    expect(result.prompt.slice(result.selectionStart, result.selectionEnd)).toContain('three+');
+  });
+
+  it('supports project numeric attention style for new weights', () => {
+    expect(adjust('hello world', 'hello', 'increment', true).prompt).toBe('(hello)1.1 world');
+    expect(adjust('hello world', [0, 11], 'decrement', true).prompt).toBe('(hello world)0.9');
+    expect(adjust("('one two', 'three four').and()", 'one', 'increment', true).prompt).toBe(
+      "('(one)1.1 two', 'three four').and()"
+    );
+  });
+
+  it('keeps hyphenated words intact when adjacent text is adjusted', () => {
+    expect(adjust('razor-sharp teeth', 'teeth', 'increment').prompt).toBe('razor-sharp teeth+');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/prompt/attention.ts b/invokeai/frontend/webv2/src/workbench/generation/prompt/attention.ts
new file mode 100644
index 00000000000..3c15b55e634
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/prompt/attention.ts
@@ -0,0 +1,553 @@
+import type { PromptAstNode, PromptAttention, PromptFunctionArg, PromptRange } from './ast';
+
+import { parsePrompt, serializePromptWithSelection } from './ast';
+
+export type PromptAttentionDirection = 'increment' | 'decrement';
+
+export interface PromptAttentionAdjustment {
+  prompt: string;
+  selectionStart: number;
+  selectionEnd: number;
+}
+
+const ATTENTION_FACTOR = 1.1;
+const NUMERIC_STEP = 0.1;
+const WEIGHT_EPSILON = 0.001;
+const FACTOR_EPSILON = 0.005;
+const GENERATED_RANGE: PromptRange = { start: 0, end: 0 };
+
+type PromptFunctionNode = Extract<PromptAstNode, { type: 'prompt_function' }>;
+type LeafNode = Exclude<PromptAstNode, { type: 'group' | 'prompt_function' }>;
+
+interface WeightedLeaf {
+  text: string;
+  type: LeafNode['type'];
+  weight: number;
+  range: PromptRange;
+  parentRange?: PromptRange;
+  hasExplicitAttention: boolean;
+  usesNumericAttention: boolean;
+  isSelected: boolean;
+}
+
+type Region =
+  | { type: 'normal'; nodes: PromptAstNode[]; range: PromptRange }
+  | { type: 'prompt_function'; node: PromptFunctionNode };
+
+const roundWeight = (weight: number): number => Number(weight.toFixed(4));
+
+const isNeutralWeight = (weight: number): boolean => Math.abs(weight - 1) < WEIGHT_EPSILON;
+
+const parseAttention = (attention: PromptAttention): number => {
+  if (typeof attention === 'number') {
+    return attention;
+  }
+
+  if (attention.startsWith('+')) {
+    return ATTENTION_FACTOR ** attention.length;
+  }
+
+  if (attention.startsWith('-')) {
+    return ATTENTION_FACTOR ** -attention.length;
+  }
+
+  const numeric = Number(attention);
+
+  return Number.isNaN(numeric) ? 1 : numeric;
+};
+
+const getSymbolicStepCount = (weight: number): number | null => {
+  if (weight <= 0) {
+    return null;
+  }
+
+  if (isNeutralWeight(weight)) {
+    return 0;
+  }
+
+  const steps = Math.round(Math.log(weight) / Math.log(ATTENTION_FACTOR));
+
+  if (steps === 0) {
+    return null;
+  }
+
+  return Math.abs(ATTENTION_FACTOR ** steps - weight) < FACTOR_EPSILON ? steps : null;
+};
+
+const addSymbolicAttention = (current: PromptAttention | undefined, next: '+' | '-'): PromptAttention | undefined => {
+  if (current === undefined) {
+    return next;
+  }
+
+  if (typeof current === 'number') {
+    return next === '+' ? roundWeight(current * ATTENTION_FACTOR) : roundWeight(current / ATTENTION_FACTOR);
+  }
+
+  const cancels = (current.startsWith('+') && next === '-') || (current.startsWith('-') && next === '+');
+
+  if (!cancels) {
+    return `${current}${next}`;
+  }
+
+  const remaining = current.slice(1);
+
+  return remaining ? remaining : undefined;
+};
+
+const clipRange = (selectionStart: number, selectionEnd: number, range: PromptRange): PromptRange | null => {
+  if (selectionStart === selectionEnd) {
+    return selectionStart >= range.start && selectionStart <= range.end
+      ? { start: selectionStart, end: selectionEnd }
+      : null;
+  }
+
+  const start = Math.max(selectionStart, range.start);
+  const end = Math.min(selectionEnd, range.end);
+
+  return start < end ? { start, end } : null;
+};
+
+const rangesOverlap = (selectionStart: number, selectionEnd: number, range: PromptRange): boolean => {
+  if (selectionStart === selectionEnd) {
+    return range.start <= selectionStart && range.end >= selectionStart;
+  }
+
+  return range.start < selectionEnd && range.end > selectionStart;
+};
+
+const extractRegions = (nodes: PromptAstNode[]): Region[] => {
+  const regions: Region[] = [];
+  let normalNodes: PromptAstNode[] = [];
+
+  const flushNormalNodes = () => {
+    const first = normalNodes[0];
+    const last = normalNodes.at(-1);
+
+    if (!first || !last) {
+      return;
+    }
+
+    regions.push({ type: 'normal', nodes: normalNodes, range: { start: first.range.start, end: last.range.end } });
+    normalNodes = [];
+  };
+
+  for (const node of nodes) {
+    if (node.type === 'prompt_function') {
+      flushNormalNodes();
+      regions.push({ type: 'prompt_function', node });
+    } else {
+      normalNodes.push(node);
+    }
+  }
+
+  flushNormalNodes();
+
+  return regions;
+};
+
+const flattenNodes = (
+  nodes: PromptAstNode[],
+  inheritedWeight = 1,
+  parentRange?: PromptRange,
+  inheritedNumericAttention = false
+): WeightedLeaf[] => {
+  const leaves: WeightedLeaf[] = [];
+
+  for (const node of nodes) {
+    let weight = inheritedWeight;
+    let usesNumericAttention = inheritedNumericAttention;
+
+    if ((node.type === 'word' || node.type === 'group') && node.attention !== undefined) {
+      weight *= parseAttention(node.attention);
+      usesNumericAttention = typeof node.attention === 'number';
+    }
+
+    if (node.type === 'group') {
+      leaves.push(...flattenNodes(node.children, weight, node.range, usesNumericAttention));
+      continue;
+    }
+
+    if (node.type === 'prompt_function') {
+      continue;
+    }
+
+    leaves.push({
+      hasExplicitAttention: node.type === 'word' && node.attention !== undefined,
+      isSelected: false,
+      parentRange,
+      range: node.range,
+      text: node.type === 'word' ? node.text : node.value,
+      type: node.type,
+      usesNumericAttention,
+      weight,
+    });
+  }
+
+  return leaves;
+};
+
+const selectLeaves = (leaves: WeightedLeaf[], selectionStart: number, selectionEnd: number): WeightedLeaf[] => {
+  const selected = leaves.filter((leaf) => {
+    if (!rangesOverlap(selectionStart, selectionEnd, leaf.range)) {
+      return false;
+    }
+
+    if (!leaf.parentRange) {
+      return true;
+    }
+
+    const parentContainsSelection = leaf.parentRange.start <= selectionStart && leaf.parentRange.end >= selectionEnd;
+    const selectionCoversParent = selectionStart <= leaf.parentRange.start && selectionEnd >= leaf.parentRange.end;
+
+    return parentContainsSelection || selectionCoversParent || !leaf.hasExplicitAttention;
+  });
+
+  if (selectionStart !== selectionEnd || selected.length < 2) {
+    return selected;
+  }
+
+  const contentLeaves = selected.filter((leaf) => leaf.type === 'word' || leaf.type === 'embedding');
+
+  return contentLeaves.length > 0 ? contentLeaves : selected;
+};
+
+const findSelectedGroup = (
+  nodes: PromptAstNode[],
+  selectionStart: number,
+  selectionEnd: number
+): Extract<PromptAstNode, { type: 'group' }> | null => {
+  for (const node of nodes) {
+    if (node.type !== 'group') {
+      continue;
+    }
+
+    const childGroup = findSelectedGroup(node.children, selectionStart, selectionEnd);
+
+    if (childGroup) {
+      return childGroup;
+    }
+
+    if (rangesOverlap(selectionStart, selectionEnd, node.range)) {
+      return node;
+    }
+  }
+
+  return null;
+};
+
+const applyWeightStep = (leaves: WeightedLeaf[], direction: PromptAttentionDirection): void => {
+  for (const leaf of leaves) {
+    if (leaf.usesNumericAttention) {
+      leaf.weight = roundWeight(leaf.weight + (direction === 'increment' ? NUMERIC_STEP : -NUMERIC_STEP));
+    } else {
+      leaf.weight = roundWeight(leaf.weight * (direction === 'increment' ? ATTENTION_FACTOR : 1 / ATTENTION_FACTOR));
+    }
+  }
+};
+
+const createLeafNode = (leaf: WeightedLeaf): PromptAstNode => {
+  const isSelection = leaf.isSelected || undefined;
+
+  switch (leaf.type) {
+    case 'word':
+      return { type: 'word', text: leaf.text, range: leaf.range, isSelection };
+    case 'whitespace':
+      return { type: 'whitespace', value: leaf.text, range: leaf.range, isSelection };
+    case 'punct':
+      return { type: 'punct', value: leaf.text, range: leaf.range, isSelection };
+    case 'embedding':
+      return { type: 'embedding', value: leaf.text, range: leaf.range, isSelection };
+    case 'escaped_paren':
+      return { type: 'escaped_paren', value: leaf.text as '(' | ')', range: leaf.range, isSelection };
+  }
+};
+
+const findRunEnd = (leaves: WeightedLeaf[], start: number, predicate: (leaf: WeightedLeaf) => boolean): number => {
+  let end = start;
+
+  while (end < leaves.length) {
+    const leaf = leaves[end];
+
+    if (!leaf) {
+      break;
+    }
+
+    if (predicate(leaf)) {
+      end++;
+      continue;
+    }
+
+    if (leaf.type !== 'whitespace') {
+      break;
+    }
+
+    let nextContent = end + 1;
+
+    while (leaves[nextContent]?.type === 'whitespace') {
+      nextContent++;
+    }
+
+    if (!leaves[nextContent] || !predicate(leaves[nextContent])) {
+      break;
+    }
+
+    end = nextContent;
+  }
+
+  return end;
+};
+
+const trimWhitespaceRun = (leaves: WeightedLeaf[], start: number, end: number): PromptRange => {
+  let trimmedStart = start;
+  let trimmedEnd = end;
+
+  while (trimmedStart < trimmedEnd && leaves[trimmedStart]?.type === 'whitespace') {
+    trimmedStart++;
+  }
+
+  while (trimmedEnd > trimmedStart && leaves[trimmedEnd - 1]?.type === 'whitespace') {
+    trimmedEnd--;
+  }
+
+  return { start: trimmedStart, end: trimmedEnd };
+};
+
+const pushLeaves = (nodes: PromptAstNode[], leaves: WeightedLeaf[], start: number, end: number): void => {
+  for (let index = start; index < end; index++) {
+    const leaf = leaves[index];
+
+    if (leaf) {
+      nodes.push(createLeafNode(leaf));
+    }
+  }
+};
+
+const selectedAll = (leaves: WeightedLeaf[]): boolean => leaves.length > 0 && leaves.every((leaf) => leaf.isSelected);
+
+const createSymbolicRunNode = (leaves: WeightedLeaf[], sign: '+' | '-'): PromptAstNode | null => {
+  const factor = sign === '+' ? ATTENTION_FACTOR : 1 / ATTENTION_FACTOR;
+  const children = groupWeightedLeaves(leaves.map((leaf) => ({ ...leaf, weight: leaf.weight / factor })));
+
+  if (children.length === 0) {
+    return null;
+  }
+
+  const isSelection = selectedAll(leaves) || undefined;
+
+  if (children.length === 1) {
+    const child = children[0];
+
+    if (child?.type === 'word' || child?.type === 'group') {
+      return { ...child, attention: addSymbolicAttention(child.attention, sign), isSelection };
+    }
+  }
+
+  return { type: 'group', attention: sign, children, range: GENERATED_RANGE, isSelection };
+};
+
+const createNumericRunNode = (leaves: WeightedLeaf[], weight: number): PromptAstNode | null => {
+  const children = groupWeightedLeaves(leaves.map((leaf) => ({ ...leaf, weight: 1 })));
+
+  if (children.length === 0) {
+    return null;
+  }
+
+  return {
+    type: 'group',
+    attention: roundWeight(weight),
+    children,
+    range: GENERATED_RANGE,
+    isSelection: selectedAll(leaves) || undefined,
+  };
+};
+
+const groupWeightedLeaves = (leaves: WeightedLeaf[]): PromptAstNode[] => {
+  const nodes: PromptAstNode[] = [];
+  let index = 0;
+
+  while (index < leaves.length) {
+    const leaf = leaves[index];
+
+    if (!leaf) {
+      break;
+    }
+
+    const stepCount = getSymbolicStepCount(leaf.weight);
+
+    if (stepCount !== null && stepCount !== 0 && !leaf.usesNumericAttention) {
+      const isPositive = stepCount > 0;
+      const sign = isPositive ? '+' : '-';
+      const runEnd = findRunEnd(leaves, index, (candidate) => {
+        if (candidate.usesNumericAttention) {
+          return false;
+        }
+
+        const candidateSteps = getSymbolicStepCount(candidate.weight);
+
+        return candidateSteps !== null && (isPositive ? candidateSteps > 0 : candidateSteps < 0);
+      });
+      const trimmed = trimWhitespaceRun(leaves, index, runEnd);
+
+      pushLeaves(nodes, leaves, index, trimmed.start);
+
+      const runNode = createSymbolicRunNode(leaves.slice(trimmed.start, trimmed.end), sign);
+
+      if (runNode) {
+        nodes.push(runNode);
+      }
+
+      pushLeaves(nodes, leaves, trimmed.end, runEnd);
+      index = runEnd;
+      continue;
+    }
+
+    if (isNeutralWeight(leaf.weight)) {
+      nodes.push(createLeafNode(leaf));
+      index++;
+      continue;
+    }
+
+    const runWeight = leaf.weight;
+    const runEnd = findRunEnd(leaves, index, (candidate) => Math.abs(candidate.weight - runWeight) < WEIGHT_EPSILON);
+    const trimmed = trimWhitespaceRun(leaves, index, runEnd);
+
+    pushLeaves(nodes, leaves, index, trimmed.start);
+
+    const runNode = createNumericRunNode(leaves.slice(trimmed.start, trimmed.end), runWeight);
+
+    if (runNode) {
+      nodes.push(runNode);
+    }
+
+    pushLeaves(nodes, leaves, trimmed.end, runEnd);
+    index = runEnd;
+  }
+
+  return nodes;
+};
+
+const adjustNodes = (
+  nodes: PromptAstNode[],
+  selectionStart: number,
+  selectionEnd: number,
+  direction: PromptAttentionDirection,
+  preferNumericAttentionStyle: boolean
+): { nodes: PromptAstNode[]; modified: boolean } => {
+  const leaves = flattenNodes(nodes);
+  let selectedLeaves = selectLeaves(leaves, selectionStart, selectionEnd);
+
+  if (selectedLeaves.length === 0) {
+    const group = findSelectedGroup(nodes, selectionStart, selectionEnd);
+
+    if (group) {
+      selectedLeaves = leaves.filter(
+        (leaf) => leaf.range.start >= group.range.start && leaf.range.end <= group.range.end
+      );
+    }
+  }
+
+  if (selectedLeaves.length === 0) {
+    return { nodes, modified: false };
+  }
+
+  for (const leaf of selectedLeaves) {
+    leaf.isSelected = true;
+
+    if (preferNumericAttentionStyle && !leaf.hasExplicitAttention) {
+      leaf.usesNumericAttention = true;
+    }
+  }
+
+  applyWeightStep(selectedLeaves, direction);
+
+  return { nodes: groupWeightedLeaves(leaves), modified: true };
+};
+
+const adjustPromptFunction = (
+  node: PromptFunctionNode,
+  selectionStart: number,
+  selectionEnd: number,
+  direction: PromptAttentionDirection,
+  preferNumericAttentionStyle: boolean
+): { node: PromptFunctionNode; modified: boolean } => {
+  let modified = false;
+  const promptArgs: PromptFunctionArg[] = node.promptArgs.map((arg) => {
+    const clipped = clipRange(selectionStart, selectionEnd, arg.contentRange);
+
+    if (!clipped) {
+      return arg;
+    }
+
+    const result = adjustNodes(arg.nodes, clipped.start, clipped.end, direction, preferNumericAttentionStyle);
+
+    if (!result.modified) {
+      return arg;
+    }
+
+    modified = true;
+    return { ...arg, nodes: result.nodes };
+  });
+
+  return modified ? { node: { ...node, promptArgs }, modified: true } : { node, modified: false };
+};
+
+const adjustPromptAttentionUnchecked = (
+  prompt: string,
+  selectionStart: number,
+  selectionEnd: number,
+  direction: PromptAttentionDirection,
+  preferNumericAttentionStyle = false
+): PromptAttentionAdjustment => {
+  const nodes = parsePrompt(prompt);
+  const nextNodes: PromptAstNode[] = [];
+  let modified = false;
+
+  for (const region of extractRegions(nodes)) {
+    if (region.type === 'normal') {
+      const clipped = clipRange(selectionStart, selectionEnd, region.range);
+
+      if (!clipped) {
+        nextNodes.push(...region.nodes);
+        continue;
+      }
+
+      const result = adjustNodes(region.nodes, clipped.start, clipped.end, direction, preferNumericAttentionStyle);
+      modified = modified || result.modified;
+      nextNodes.push(...result.nodes);
+      continue;
+    }
+
+    const clipped = clipRange(selectionStart, selectionEnd, region.node.range);
+
+    if (!clipped) {
+      nextNodes.push(region.node);
+      continue;
+    }
+
+    const result = adjustPromptFunction(
+      region.node,
+      clipped.start,
+      clipped.end,
+      direction,
+      preferNumericAttentionStyle
+    );
+    modified = modified || result.modified;
+    nextNodes.push(result.node);
+  }
+
+  return modified ? serializePromptWithSelection(nextNodes) : { prompt, selectionStart, selectionEnd };
+};
+
+export const adjustPromptAttention = (
+  prompt: string,
+  selectionStart: number,
+  selectionEnd: number,
+  direction: PromptAttentionDirection,
+  preferNumericAttentionStyle = false
+): PromptAttentionAdjustment => {
+  try {
+    return adjustPromptAttentionUnchecked(prompt, selectionStart, selectionEnd, direction, preferNumericAttentionStyle);
+  } catch {
+    return { prompt, selectionStart, selectionEnd };
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/prompt/highlight.test.ts b/invokeai/frontend/webv2/src/workbench/generation/prompt/highlight.test.ts
new file mode 100644
index 00000000000..7a75a2053ac
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/prompt/highlight.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildPromptHighlightSegments, type PromptHighlightKind } from './highlight';
+
+const segmentsByText = (prompt: string, text: string) =>
+  buildPromptHighlightSegments(prompt).filter((segment) => segment.text === text || segment.text.includes(text));
+
+const kindForText = (prompt: string, text: string): PromptHighlightKind | undefined =>
+  segmentsByText(prompt, text)[0]?.kind;
+
+describe('prompt highlight segments', () => {
+  it('highlights symbolic and numeric attention separately', () => {
+    const segments = buildPromptHighlightSegments('cat+ (dog)1.2');
+
+    expect(segments).toContainEqual({ kind: 'attention', range: { start: 3, end: 4 }, text: '+' });
+    expect(segments).toContainEqual({ kind: 'attentionNumeric', range: { start: 10, end: 13 }, text: '1.2' });
+  });
+
+  it('highlights embeddings as a semantic range', () => {
+    const prompt = 'use <embedding_name> now';
+
+    expect(kindForText(prompt, '<embedding_name>')).toBe('embedding');
+  });
+
+  it('highlights escaped parentheses as literal prompt syntax', () => {
+    const segments = buildPromptHighlightSegments('literal \\(medium\\)');
+
+    expect(segments).toContainEqual({ kind: 'escapedParen', range: { start: 8, end: 10 }, text: '\\(' });
+    expect(segments).toContainEqual({ kind: 'escapedParen', range: { start: 16, end: 18 }, text: '\\)' });
+  });
+
+  it('highlights prompt function args and method tails cosmetically', () => {
+    const prompt = "('one two', 'three four').and()";
+
+    expect(kindForText(prompt, 'one two')).toBe('promptFunctionArg');
+    expect(kindForText(prompt, 'three four')).toBe('promptFunctionArg');
+    expect(kindForText(prompt, '.and()')).toBe('promptFunctionMethod');
+  });
+
+  it('keeps attention syntax inside prompt function args higher priority than arg background', () => {
+    const prompt = "('one+', 'two').and()";
+
+    expect(kindForText(prompt, '+')).toBe('attention');
+  });
+
+  it('marks unmatched parentheses as cosmetic errors', () => {
+    expect(kindForText('(unclosed', '(')).toBe('error');
+    expect(kindForText('extra)', ')')).toBe('error');
+  });
+
+  it('does not mark hyphenated words as attention', () => {
+    const prompt = 'razor-sharp teeth';
+
+    expect(kindForText(prompt, '-')).toBe('punctuation');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/prompt/highlight.ts b/invokeai/frontend/webv2/src/workbench/generation/prompt/highlight.ts
new file mode 100644
index 00000000000..47098e77633
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/prompt/highlight.ts
@@ -0,0 +1,196 @@
+import type { PromptAstNode, PromptRange, PromptToken } from './ast';
+
+import { parsePromptTokens, tokenizePrompt } from './ast';
+
+export type PromptHighlightKind =
+  | 'text'
+  | 'attention'
+  | 'attentionNumeric'
+  | 'group'
+  | 'embedding'
+  | 'escapedParen'
+  | 'promptFunctionMethod'
+  | 'promptFunctionArg'
+  | 'punctuation'
+  | 'error';
+
+export interface PromptHighlightSegment {
+  kind: PromptHighlightKind;
+  range: PromptRange;
+  text: string;
+}
+
+interface HighlightAnnotation {
+  kind: PromptHighlightKind;
+  priority: number;
+  range: PromptRange;
+}
+
+const ANNOTATION_PRIORITY = {
+  error: 100,
+  embedding: 40,
+  promptFunctionMethod: 35,
+  promptFunctionArg: 5,
+} as const;
+
+const BASE_PRIORITY: Record<PromptHighlightKind, number> = {
+  attention: 30,
+  attentionNumeric: 30,
+  embedding: 30,
+  error: 100,
+  escapedParen: 20,
+  group: 20,
+  promptFunctionArg: 5,
+  promptFunctionMethod: 35,
+  punctuation: 10,
+  text: 0,
+};
+
+const isNumericAttention = (value: unknown): boolean => typeof value === 'number' || !Number.isNaN(Number(value));
+
+const tokenKind = (token: PromptToken): PromptHighlightKind => {
+  switch (token.type) {
+    case 'weight':
+      return isNumericAttention(token.value) ? 'attentionNumeric' : 'attention';
+    case 'lparen':
+    case 'rparen':
+      return 'group';
+    case 'lembed':
+    case 'rembed':
+      return 'embedding';
+    case 'escaped_paren':
+      return 'escapedParen';
+    case 'punct':
+      return 'punctuation';
+    default:
+      return 'text';
+  }
+};
+
+const covers = (outer: PromptRange, inner: PromptRange): boolean =>
+  outer.start <= inner.start && outer.end >= inner.end;
+
+const getBestAnnotation = (
+  annotations: HighlightAnnotation[],
+  tokenRange: PromptRange
+): HighlightAnnotation | undefined =>
+  annotations
+    .filter((annotation) => covers(annotation.range, tokenRange))
+    .sort((left, right) => right.priority - left.priority)[0];
+
+const addPromptFunctionAnnotations = (
+  prompt: string,
+  node: Extract<PromptAstNode, { type: 'prompt_function' }>,
+  annotations: HighlightAnnotation[]
+): void => {
+  for (const arg of node.promptArgs) {
+    annotations.push({
+      kind: 'promptFunctionArg',
+      priority: ANNOTATION_PRIORITY.promptFunctionArg,
+      range: arg.contentRange,
+    });
+  }
+
+  const lastArg = node.promptArgs.at(-1);
+  const methodStart = lastArg ? prompt.indexOf('.', lastArg.contentRange.end) : -1;
+
+  if (methodStart >= 0 && methodStart < node.range.end) {
+    annotations.push({
+      kind: 'promptFunctionMethod',
+      priority: ANNOTATION_PRIORITY.promptFunctionMethod,
+      range: { start: methodStart, end: node.range.end },
+    });
+  }
+};
+
+const collectAnnotations = (
+  prompt: string,
+  nodes: PromptAstNode[],
+  annotations: HighlightAnnotation[] = []
+): HighlightAnnotation[] => {
+  for (const node of nodes) {
+    if (node.type === 'embedding') {
+      annotations.push({ kind: 'embedding', priority: ANNOTATION_PRIORITY.embedding, range: node.range });
+      continue;
+    }
+
+    if (node.type === 'group') {
+      collectAnnotations(prompt, node.children, annotations);
+      continue;
+    }
+
+    if (node.type === 'prompt_function') {
+      addPromptFunctionAnnotations(prompt, node, annotations);
+      collectAnnotations(
+        prompt,
+        node.promptArgs.flatMap((arg) => arg.nodes),
+        annotations
+      );
+    }
+  }
+
+  return annotations;
+};
+
+const collectParenthesisErrors = (tokens: PromptToken[]): HighlightAnnotation[] => {
+  const annotations: HighlightAnnotation[] = [];
+  const stack: PromptToken[] = [];
+
+  for (const token of tokens) {
+    if (token.type === 'lparen') {
+      stack.push(token);
+    } else if (token.type === 'rparen') {
+      if (stack.length > 0) {
+        stack.pop();
+      } else {
+        annotations.push({ kind: 'error', priority: ANNOTATION_PRIORITY.error, range: token.range });
+      }
+    }
+  }
+
+  for (const token of stack) {
+    annotations.push({ kind: 'error', priority: ANNOTATION_PRIORITY.error, range: token.range });
+  }
+
+  return annotations;
+};
+
+const appendSegment = (segments: PromptHighlightSegment[], segment: PromptHighlightSegment): void => {
+  const previous = segments.at(-1);
+
+  if (previous && previous.kind === segment.kind && previous.range.end === segment.range.start) {
+    previous.text += segment.text;
+    previous.range.end = segment.range.end;
+    return;
+  }
+
+  segments.push(segment);
+};
+
+export const buildPromptHighlightSegments = (prompt: string): PromptHighlightSegment[] => {
+  if (!prompt) {
+    return [];
+  }
+
+  try {
+    const tokens = tokenizePrompt(prompt);
+    const annotations = [...collectAnnotations(prompt, parsePromptTokens(tokens)), ...collectParenthesisErrors(tokens)];
+    const segments: PromptHighlightSegment[] = [];
+
+    for (const token of tokens) {
+      const annotation = getBestAnnotation(annotations, token.range);
+      const baseKind = tokenKind(token);
+      const kind = annotation && annotation.priority > BASE_PRIORITY[baseKind] ? annotation.kind : baseKind;
+
+      appendSegment(segments, {
+        kind,
+        range: { ...token.range },
+        text: prompt.slice(token.range.start, token.range.end),
+      });
+    }
+
+    return segments;
+  } catch {
+    return [{ kind: 'text', range: { start: 0, end: prompt.length }, text: prompt }];
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/generation/promptHistory.ts b/invokeai/frontend/webv2/src/workbench/generation/promptHistory.ts
new file mode 100644
index 00000000000..7b9fefdc02a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/promptHistory.ts
@@ -0,0 +1,55 @@
+import type { PromptHistoryItem } from '@workbench/types';
+
+import type { GenerateSettings } from './types';
+
+export const MAX_PROMPT_HISTORY = 100;
+
+export const normalizePromptHistoryItem = (item: PromptHistoryItem): PromptHistoryItem | null => {
+  const positivePrompt = item.positivePrompt.trim();
+  const negativePrompt = item.negativePrompt?.trim() || null;
+
+  if (positivePrompt.length === 0 && !negativePrompt) {
+    return null;
+  }
+
+  return { negativePrompt, positivePrompt };
+};
+
+const isSamePromptHistoryItem = (a: PromptHistoryItem, b: PromptHistoryItem): boolean =>
+  a.positivePrompt === b.positivePrompt && (a.negativePrompt ?? null) === (b.negativePrompt ?? null);
+
+export const addPromptHistoryItem = (
+  history: readonly PromptHistoryItem[],
+  item: PromptHistoryItem
+): PromptHistoryItem[] => {
+  const prompt = normalizePromptHistoryItem(item);
+
+  if (!prompt) {
+    return [...history];
+  }
+
+  return [prompt, ...history.filter((entry) => !isSamePromptHistoryItem(entry, prompt))].slice(0, MAX_PROMPT_HISTORY);
+};
+
+export const removePromptHistoryItem = (
+  history: readonly PromptHistoryItem[],
+  item: PromptHistoryItem
+): PromptHistoryItem[] => history.filter((entry) => !isSamePromptHistoryItem(entry, item));
+
+export const filterPromptHistory = (history: readonly PromptHistoryItem[], searchTerm: string): PromptHistoryItem[] => {
+  const query = searchTerm.trim().toLowerCase();
+
+  if (!query) {
+    return [...history];
+  }
+
+  return history.filter(
+    (item) =>
+      item.positivePrompt.toLowerCase().includes(query) || (item.negativePrompt ?? '').toLowerCase().includes(query)
+  );
+};
+
+export const getPromptHistoryItemFromGenerateSettings = (settings: GenerateSettings): PromptHistoryItem => ({
+  negativePrompt: settings.negativePromptEnabled ? settings.negativePrompt : null,
+  positivePrompt: settings.positivePrompt,
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/promptUtilities.ts b/invokeai/frontend/webv2/src/workbench/generation/promptUtilities.ts
new file mode 100644
index 00000000000..de73b9bab1f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/promptUtilities.ts
@@ -0,0 +1,36 @@
+import { apiFetchJson } from '@workbench/backend/http';
+
+export interface ExpandPromptRequest {
+  prompt: string;
+  model_key: string;
+  max_tokens?: number;
+  system_prompt?: string | null;
+}
+
+export interface ExpandPromptResponse {
+  expanded_prompt: string;
+  error?: string | null;
+}
+
+export interface ImageToPromptRequest {
+  image_name: string;
+  model_key: string;
+  instruction?: string;
+}
+
+export interface ImageToPromptResponse {
+  prompt: string;
+  error?: string | null;
+}
+
+export const expandPrompt = (request: ExpandPromptRequest): Promise<ExpandPromptResponse> =>
+  apiFetchJson('/api/v1/utilities/expand-prompt', {
+    body: JSON.stringify(request),
+    method: 'POST',
+  });
+
+export const imageToPrompt = (request: ImageToPromptRequest): Promise<ImageToPromptResponse> =>
+  apiFetchJson('/api/v1/utilities/image-to-prompt', {
+    body: JSON.stringify(request),
+    method: 'POST',
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/generation/settings.test.ts b/invokeai/frontend/webv2/src/workbench/generation/settings.test.ts
new file mode 100644
index 00000000000..846d72943fb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/settings.test.ts
@@ -0,0 +1,323 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  ComponentModelConfig,
+  GenerateLora,
+  GenerateWidgetValues,
+  LoraModelConfig,
+  MainModelConfig,
+  VaeModelConfig,
+} from './types';
+
+import { getGenerationDimensions } from './baseGenerationPolicies';
+import {
+  calculateNewSize,
+  clampDimension,
+  cloneGenerateWidgetValues,
+  deriveAspectRatioId,
+  getDefaultLoraWeight,
+  getModelDefaultVae,
+  hasModelDefaultVae,
+  isLoraCompatibleWithModel,
+  isGenerateSettings,
+  normalizeGenerateSettings,
+  syncGenerateWidgetValuesWithModels,
+  syncGenerateLorasWithModels,
+} from './settings';
+
+/** The persisted widget-value shape from before aspect ratio / VAE / seamless / CLIP skip landed. */
+const legacyStoredValues = {
+  batchCount: 2,
+  cfgRescaleMultiplier: 0,
+  cfgScale: 7,
+  height: 768,
+  modelKey: 'legacy-model',
+  negativePrompt: 'blurry',
+  positivePrompt: 'a castle',
+  scheduler: 'euler_a',
+  seed: 123,
+  shouldRandomizeSeed: false,
+  steps: 30,
+  width: 512,
+};
+
+describe('normalizeGenerateSettings', () => {
+  it('normalizes persisted reference images and drops invalid entries', () => {
+    const normalized = normalizeGenerateSettings({
+      ...legacyStoredValues,
+      referenceImages: [
+        {
+          id: 'ref-1',
+          isEnabled: true,
+          config: {
+            type: 'qwen_image_reference_image',
+            image: {
+              height: 768,
+              imageName: 'reference.png',
+              imageUrl: '/api/v1/images/i/reference.png/full',
+              queuedAt: '2026-01-01T00:00:00.000Z',
+              sourceQueueItemId: 'backend-gallery',
+              thumbnailUrl: '/api/v1/images/i/reference.png/thumbnail',
+              width: 512,
+            },
+          },
+        },
+        { id: 'broken', isEnabled: true, config: { type: 'qwen_image_reference_image', image: { imageName: 3 } } },
+      ],
+    });
+
+    expect(normalized?.referenceImages).toHaveLength(1);
+    expect(normalized?.referenceImages[0]).toMatchObject({
+      id: 'ref-1',
+      isEnabled: true,
+      config: { type: 'qwen_image_reference_image', image: { imageName: 'reference.png' } },
+    });
+  });
+
+  it('keeps more than five valid persisted reference images for provider-specific caps', () => {
+    const referenceImages = Array.from({ length: 6 }, (_, index) => ({
+      id: `ref-${index}`,
+      isEnabled: true,
+      config: {
+        type: 'external_reference_image',
+        image: {
+          height: 768,
+          imageName: `reference-${index}.png`,
+          imageUrl: `/api/v1/images/i/reference-${index}.png/full`,
+          queuedAt: '2026-01-01T00:00:00.000Z',
+          sourceQueueItemId: 'backend-gallery',
+          thumbnailUrl: `/api/v1/images/i/reference-${index}.png/thumbnail`,
+          width: 512,
+        },
+      },
+    }));
+
+    const normalized = normalizeGenerateSettings({ ...legacyStoredValues, referenceImages });
+
+    expect(normalized?.referenceImages).toHaveLength(6);
+  });
+
+  it('upgrades legacy persisted values without losing the core fields', () => {
+    const normalized = normalizeGenerateSettings(legacyStoredValues);
+
+    expect(normalized).not.toBeNull();
+    expect(normalized?.positivePrompt).toBe('a castle');
+    expect(normalized?.width).toBe(512);
+    expect(normalized?.height).toBe(768);
+    expect(normalized?.aspectRatioId).toBe('2:3');
+    expect(normalized?.aspectRatioIsLocked).toBe(false);
+    expect(normalized?.clipSkip).toBe(0);
+    expect(normalized?.colorCompensation).toBe(false);
+    expect(normalized?.loras).toEqual([]);
+    expect(normalized?.negativePromptEnabled).toBe(true);
+    expect(normalized?.negativePromptHeightPx).toBe(56);
+    expect(normalized?.positivePromptHeightPx).toBe(96);
+    expect(normalized?.seamlessXAxis).toBe(false);
+    expect(normalized?.vae).toBeNull();
+    expect(normalized?.vaePrecision).toBe('fp32');
+    expect(normalized && isGenerateSettings(normalized)).toBe(true);
+  });
+
+  it('rejects values missing core fields', () => {
+    expect(normalizeGenerateSettings({})).toBeNull();
+    expect(normalizeGenerateSettings({ ...legacyStoredValues, seed: Number.NaN })).toBeNull();
+    expect(normalizeGenerateSettings({ ...legacyStoredValues, positivePrompt: undefined })).toBeNull();
+    expect(normalizeGenerateSettings(null)).toBeNull();
+  });
+
+  it('defaults an omitted batch count to one', () => {
+    const { batchCount, ...storedValues } = legacyStoredValues;
+
+    expect(batchCount).toBe(2);
+    expect(normalizeGenerateSettings(storedValues)?.batchCount).toBe(1);
+  });
+
+  it('drops malformed values for the newer fields back to defaults', () => {
+    const normalized = normalizeGenerateSettings({
+      ...legacyStoredValues,
+      aspectRatioId: 'bogus',
+      loras: [{ isEnabled: true, model: { key: 'k', name: 'n', type: 'main' }, weight: 1 }],
+      vae: { key: 'k', name: 'n', type: 'main' },
+      vaePrecision: 'fp64',
+    });
+
+    expect(normalized?.aspectRatioId).toBe('2:3');
+    expect(normalized?.loras).toEqual([]);
+    expect(normalized?.vae).toBeNull();
+    expect(normalized?.vaePrecision).toBe('fp32');
+  });
+
+  it('drops malformed persisted model identifiers missing a base', () => {
+    const normalized = normalizeGenerateSettings({
+      ...legacyStoredValues,
+      loras: [{ isEnabled: true, model: { key: 'lora', name: 'LoRA', type: 'lora' }, weight: 1 }],
+      qwen3EncoderModel: { key: 'qwen3', name: 'Qwen3', type: 'qwen3_encoder' },
+      vae: { key: 'vae', name: 'VAE', type: 'vae' },
+    });
+
+    expect(normalized?.loras).toEqual([]);
+    expect(normalized?.qwen3EncoderModel).toBeNull();
+    expect(normalized?.vae).toBeNull();
+  });
+});
+
+describe('Generate widget value snapshots', () => {
+  const model: MainModelConfig = { base: 'flux2', key: 'model', name: 'Old Model', type: 'main' };
+  const component: ComponentModelConfig = { base: 'any', key: 'qwen3', name: 'Old Qwen3', type: 'qwen3_encoder' };
+  const vae: VaeModelConfig = { base: 'flux2', key: 'vae', name: 'Old VAE', type: 'vae' };
+  const lora: LoraModelConfig = { base: 'flux2', key: 'lora', name: 'Old LoRA', type: 'lora' };
+  const values: GenerateWidgetValues = {
+    ...(normalizeGenerateSettings(legacyStoredValues) as NonNullable<ReturnType<typeof normalizeGenerateSettings>>),
+    clipEmbedModel: { base: 'any', key: 'clip', name: 'CLIP', type: 'clip_embed' },
+    componentSourceModel: model,
+    loras: [{ isEnabled: true, model: lora, weight: 0.5 }],
+    model,
+    modelKey: model.key,
+    qwen3EncoderModel: component,
+    vae,
+  };
+
+  it('deep-clones every nested model selection', () => {
+    const clone = cloneGenerateWidgetValues(values);
+
+    expect(clone).toEqual(values);
+    expect(clone.model).not.toBe(values.model);
+    expect(clone.componentSourceModel).not.toBe(values.componentSourceModel);
+    expect(clone.qwen3EncoderModel).not.toBe(values.qwen3EncoderModel);
+    expect(clone.vae).not.toBe(values.vae);
+    expect(clone.loras[0]).not.toBe(values.loras[0]);
+    expect(clone.loras[0]?.model).not.toBe(values.loras[0]?.model);
+  });
+
+  it('uses current backend model records for same-key stored selections', () => {
+    const currentModel = { ...model, format: 'diffusers' as const, name: 'Current Model' };
+    const currentComponent = { ...component, name: 'Current Qwen3' };
+    const currentVae = { ...vae, name: 'Current VAE' };
+    const currentLora = { ...lora, name: 'Current LoRA' };
+    const synced = syncGenerateWidgetValuesWithModels(values, [
+      currentModel,
+      currentComponent,
+      currentVae,
+      currentLora,
+    ]);
+
+    expect(synced.model).toBe(currentModel);
+    expect(synced.componentSourceModel).toBe(currentModel);
+    expect(synced.qwen3EncoderModel).toBe(currentComponent);
+    expect(synced.vae).toBe(currentVae);
+    expect(synced.loras[0]?.model).toBe(currentLora);
+  });
+
+  it('does not resync cloned current model snapshots by reference alone', () => {
+    const currentModel = { ...model, format: 'diffusers' as const, name: 'Current Model' };
+    const currentComponent = { ...component, name: 'Current Qwen3' };
+    const currentVae = { ...vae, name: 'Current VAE' };
+    const currentLora = { ...lora, name: 'Current LoRA' };
+    const currentValues = {
+      ...values,
+      componentSourceModel: currentModel,
+      loras: [{ isEnabled: true, model: currentLora, weight: 0.5 }],
+      model: currentModel,
+      qwen3EncoderModel: currentComponent,
+      vae: currentVae,
+    };
+    const clonedValues = cloneGenerateWidgetValues(currentValues);
+    const synced = syncGenerateWidgetValuesWithModels(clonedValues, [
+      currentModel,
+      currentComponent,
+      currentVae,
+      currentLora,
+    ]);
+
+    expect(synced).toBe(clonedValues);
+  });
+});
+
+describe('LoRA settings helpers', () => {
+  it('uses current model records when reading selected LoRA defaults', () => {
+    const staleModel: LoraModelConfig = {
+      base: 'sdxl',
+      default_settings: { weight: 0.75 },
+      key: 'lora-key',
+      name: 'Old LoRA Name',
+      type: 'lora',
+    };
+    const currentModel: LoraModelConfig = {
+      ...staleModel,
+      default_settings: { weight: 1.25 },
+      name: 'Updated LoRA Name',
+      trigger_phrases: ['updated trigger'],
+    };
+    const selectedLora: GenerateLora = { isEnabled: true, model: staleModel, weight: 0.5 };
+
+    const [syncedLora] = syncGenerateLorasWithModels([selectedLora], [currentModel]);
+
+    expect(syncedLora?.model).toBe(currentModel);
+    expect(syncedLora?.weight).toBe(0.5);
+    expect(getDefaultLoraWeight(syncedLora!.model)).toBe(1.25);
+  });
+
+  it('allows FLUX LoRAs for FLUX.2 while preserving FLUX.2 variant checks', () => {
+    const flux2Model: MainModelConfig = { base: 'flux2', key: 'flux2', name: 'FLUX.2', type: 'main' };
+
+    expect(isLoraCompatibleWithModel({ base: 'flux' }, flux2Model)).toBe(true);
+    expect(
+      isLoraCompatibleWithModel({ base: 'flux2', variant: 'klein_4b' }, { ...flux2Model, variant: 'klein_9b' })
+    ).toBe(false);
+  });
+});
+
+describe('model defaults', () => {
+  it('uses shared VAE compatibility for cross-base default VAEs', () => {
+    const zImageModel: MainModelConfig = {
+      base: 'z-image',
+      default_settings: { vae: 'flux-vae' },
+      key: 'z-image',
+      name: 'Z-Image',
+      type: 'main',
+    };
+    const fluxVae: VaeModelConfig = { base: 'flux', key: 'flux-vae', name: 'FLUX VAE', type: 'vae' };
+
+    expect(getModelDefaultVae(zImageModel, [fluxVae])).toBe(fluxVae);
+  });
+
+  it('distinguishes absent VAE defaults from explicit VAE defaults', () => {
+    expect(hasModelDefaultVae({ base: 'sdxl', key: 'sdxl', name: 'SDXL', type: 'main' })).toBe(false);
+    expect(
+      hasModelDefaultVae({ base: 'sdxl', default_settings: { vae: null }, key: 'sdxl', name: 'SDXL', type: 'main' })
+    ).toBe(false);
+    expect(
+      hasModelDefaultVae({ base: 'sdxl', default_settings: { vae: 'vae' }, key: 'sdxl', name: 'SDXL', type: 'main' })
+    ).toBe(true);
+  });
+});
+
+describe('dimension helpers', () => {
+  it('derives the closest preset aspect ratio', () => {
+    expect(deriveAspectRatioId(1024, 1024)).toBe('1:1');
+    expect(deriveAspectRatioId(1536, 1024)).toBe('3:2');
+    expect(deriveAspectRatioId(1000, 770)).toBe('Free');
+  });
+
+  it('fits a ratio into a pixel area on the dimension grid', () => {
+    const { height, width } = calculateNewSize(1, 1024 * 1024);
+
+    expect(width).toBe(1024);
+    expect(height).toBe(1024);
+
+    const wide = calculateNewSize(16 / 9, 1024 * 1024);
+
+    expect(wide.width % 8).toBe(0);
+    expect(wide.height % 8).toBe(0);
+    expect(wide.width / wide.height).toBeCloseTo(16 / 9, 1);
+  });
+
+  it('uses larger dimension grids for model families that require them', () => {
+    expect(getGenerationDimensions({ base: 'sdxl', type: 'main' }).grid).toBe(8);
+    expect(getGenerationDimensions({ base: 'anima', type: 'main' }).grid).toBe(8);
+    expect(getGenerationDimensions({ base: 'flux2', type: 'main' }).grid).toBe(16);
+    expect(getGenerationDimensions({ base: 'qwen-image', type: 'main' }).grid).toBe(16);
+    expect(getGenerationDimensions({ base: 'cogview4', type: 'main' }).grid).toBe(32);
+    expect(clampDimension(888, getGenerationDimensions({ base: 'flux2', type: 'main' }).grid)).toBe(896);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/generation/settings.ts b/invokeai/frontend/webv2/src/workbench/generation/settings.ts
new file mode 100644
index 00000000000..227b343b211
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/settings.ts
@@ -0,0 +1,646 @@
+import type {
+  AspectRatioId,
+  ComponentModelConfig,
+  GenerateLora,
+  GenerateModelConfig,
+  GenerateReferenceImage,
+  GenerateReferenceImageAsset,
+  GenerateReferenceImageConfig,
+  GenerateSettings,
+  GenerateWidgetValues,
+  LoraModelConfig,
+  MainModelConfig,
+  VaeModelConfig,
+  VaePrecision,
+} from './types';
+
+import { sanitizeBatchCount } from './batch';
+import { isVaeCompatibleWithGenerateModel } from './componentCompatibility';
+
+/** Preset ratios, with the preset to switch to when dimensions are swapped. */
+export const ASPECT_RATIO_MAP: Record<Exclude<AspectRatioId, 'Free'>, { ratio: number; inverseId: AspectRatioId }> = {
+  '8:1': { inverseId: '1:8', ratio: 8 / 1 },
+  '4:1': { inverseId: '1:4', ratio: 4 / 1 },
+  '21:9': { inverseId: '9:21', ratio: 21 / 9 },
+  '16:9': { inverseId: '9:16', ratio: 16 / 9 },
+  '3:2': { inverseId: '2:3', ratio: 3 / 2 },
+  '5:4': { inverseId: '4:5', ratio: 5 / 4 },
+  '4:3': { inverseId: '3:4', ratio: 4 / 3 },
+  '1:1': { inverseId: '1:1', ratio: 1 },
+  '3:4': { inverseId: '4:3', ratio: 3 / 4 },
+  '4:5': { inverseId: '5:4', ratio: 4 / 5 },
+  '2:3': { inverseId: '3:2', ratio: 2 / 3 },
+  '9:16': { inverseId: '16:9', ratio: 9 / 16 },
+  '1:4': { inverseId: '4:1', ratio: 1 / 4 },
+  '9:21': { inverseId: '21:9', ratio: 9 / 21 },
+  '1:8': { inverseId: '8:1', ratio: 1 / 8 },
+};
+
+export const ASPECT_RATIO_OPTIONS: AspectRatioId[] = [
+  'Free',
+  '21:9',
+  '16:9',
+  '3:2',
+  '4:3',
+  '1:1',
+  '3:4',
+  '2:3',
+  '9:16',
+  '9:21',
+];
+
+export const isAspectRatioId = (value: unknown): value is AspectRatioId =>
+  value === 'Free' || (typeof value === 'string' && value in ASPECT_RATIO_MAP);
+
+export const DIMENSION_GRID = 8;
+export const MIN_DIMENSION = 64;
+export const MAX_DIMENSION = 4096;
+
+export const SEED_MAX = 4_294_967_295;
+export const MIN_NEGATIVE_PROMPT_HEIGHT_PX = 56;
+export const MAX_NEGATIVE_PROMPT_HEIGHT_PX = 240;
+export const DEFAULT_NEGATIVE_PROMPT_HEIGHT_PX = 56;
+export const MIN_POSITIVE_PROMPT_HEIGHT_PX = 96;
+export const MAX_POSITIVE_PROMPT_HEIGHT_PX = 360;
+export const DEFAULT_POSITIVE_PROMPT_HEIGHT_PX = 96;
+
+export const DEFAULT_LORA_WEIGHT_CONFIG = {
+  coarseStep: 0.05,
+  initial: 0.75,
+  numberInputMax: 10,
+  numberInputMin: -10,
+  sliderMax: 2,
+  sliderMin: -1,
+};
+
+export const clampDimension = (value: number, grid = DIMENSION_GRID): number =>
+  Math.min(MAX_DIMENSION, Math.max(MIN_DIMENSION, Math.round(value / grid) * grid));
+
+/** Fit a width/height of the given ratio into approximately the given pixel area, snapped to the grid. */
+export const calculateNewSize = (
+  ratio: number,
+  area: number,
+  grid = DIMENSION_GRID
+): { width: number; height: number } => {
+  const exactWidth = Math.sqrt(area * ratio);
+
+  return { height: clampDimension(exactWidth / ratio, grid), width: clampDimension(exactWidth, grid) };
+};
+
+/** Best-matching preset for existing dimensions, falling back to Free. */
+export const deriveAspectRatioId = (width: number, height: number): AspectRatioId => {
+  if (height <= 0) {
+    return 'Free';
+  }
+
+  const ratio = width / height;
+
+  for (const [id, entry] of Object.entries(ASPECT_RATIO_MAP)) {
+    if (Math.abs(entry.ratio - ratio) < 0.0001) {
+      return id as AspectRatioId;
+    }
+  }
+
+  return 'Free';
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === 'object';
+
+const hasFiniteNumber = (record: Record<string, unknown>, key: string): boolean =>
+  typeof record[key] === 'number' && Number.isFinite(record[key]);
+
+const getClampedNumber = (record: Record<string, unknown>, key: string, min: number, max: number, fallback: number) =>
+  hasFiniteNumber(record, key) ? Math.min(Math.max(record[key] as number, min), max) : fallback;
+
+export const isMainModelConfig = (value: unknown): value is MainModelConfig =>
+  isRecord(value) &&
+  typeof value.key === 'string' &&
+  typeof value.name === 'string' &&
+  typeof value.base === 'string' &&
+  value.type === 'main';
+
+export const isExternalImageGeneratorModelConfig = (value: unknown): value is GenerateModelConfig =>
+  isRecord(value) &&
+  typeof value.key === 'string' &&
+  typeof value.name === 'string' &&
+  value.base === 'external' &&
+  value.type === 'external_image_generator';
+
+export const isGenerateModelConfig = (value: unknown): value is GenerateModelConfig =>
+  isMainModelConfig(value) || isExternalImageGeneratorModelConfig(value);
+
+export const isModelIdentifierConfig = (value: unknown): value is ComponentModelConfig =>
+  isRecord(value) &&
+  typeof value.key === 'string' &&
+  typeof value.name === 'string' &&
+  typeof value.base === 'string' &&
+  typeof value.type === 'string';
+
+export const isVaeModelConfig = (value: unknown): value is VaeModelConfig =>
+  isRecord(value) &&
+  typeof value.key === 'string' &&
+  typeof value.name === 'string' &&
+  typeof value.base === 'string' &&
+  value.type === 'vae';
+
+export const isLoraModelConfig = (value: unknown): value is LoraModelConfig =>
+  isRecord(value) &&
+  typeof value.key === 'string' &&
+  typeof value.name === 'string' &&
+  typeof value.base === 'string' &&
+  value.type === 'lora';
+
+const getModelIdentifierOrNull = (value: unknown): ComponentModelConfig | null =>
+  isModelIdentifierConfig(value) ? value : null;
+
+const getMainModelOrNull = (value: unknown): MainModelConfig | null => (isMainModelConfig(value) ? value : null);
+
+const isVaePrecision = (value: unknown): value is VaePrecision => value === 'fp16' || value === 'fp32';
+
+const isGenerateLora = (value: unknown): value is GenerateLora =>
+  isRecord(value) &&
+  isLoraModelConfig(value.model) &&
+  hasFiniteNumber(value, 'weight') &&
+  typeof value.isEnabled === 'boolean';
+
+export const DEFAULT_REFERENCE_IMAGE_LIMIT = 5;
+
+const REFERENCE_IMAGE_CONFIG_TYPES = new Set([
+  'external_reference_image',
+  'flux2_reference_image',
+  'flux_kontext_reference_image',
+  'flux_redux',
+  'ip_adapter',
+  'qwen_image_reference_image',
+]);
+
+const isClipVisionModel = (value: unknown): value is 'ViT-H' | 'ViT-G' | 'ViT-L' =>
+  value === 'ViT-H' || value === 'ViT-G' || value === 'ViT-L';
+
+const isIPAdapterMethod = (
+  value: unknown
+): value is 'full' | 'style' | 'composition' | 'style_strong' | 'style_precise' =>
+  value === 'full' ||
+  value === 'style' ||
+  value === 'composition' ||
+  value === 'style_strong' ||
+  value === 'style_precise';
+
+const isFluxReduxImageInfluence = (value: unknown): value is 'lowest' | 'low' | 'medium' | 'high' | 'highest' =>
+  value === 'lowest' || value === 'low' || value === 'medium' || value === 'high' || value === 'highest';
+
+export const isReferenceImageAsset = (value: unknown): value is GenerateReferenceImageAsset =>
+  isRecord(value) &&
+  typeof value.imageName === 'string' &&
+  typeof value.imageUrl === 'string' &&
+  typeof value.thumbnailUrl === 'string' &&
+  typeof value.queuedAt === 'string' &&
+  typeof value.sourceQueueItemId === 'string' &&
+  hasFiniteNumber(value, 'width') &&
+  hasFiniteNumber(value, 'height');
+
+const cloneReferenceImageAsset = (image: GenerateReferenceImageAsset): GenerateReferenceImageAsset => ({ ...image });
+
+const normalizeReferenceImageAsset = (value: unknown): GenerateReferenceImageAsset | null =>
+  value === null ? null : isReferenceImageAsset(value) ? cloneReferenceImageAsset(value) : null;
+
+const normalizeReferenceImageConfig = (value: unknown): GenerateReferenceImageConfig | null => {
+  if (!isRecord(value) || typeof value.type !== 'string' || !REFERENCE_IMAGE_CONFIG_TYPES.has(value.type)) {
+    return null;
+  }
+
+  const image = normalizeReferenceImageAsset(value.image);
+
+  if (value.image !== null && image === null) {
+    return null;
+  }
+
+  switch (value.type) {
+    case 'external_reference_image':
+    case 'flux2_reference_image':
+    case 'qwen_image_reference_image':
+      return { image, type: value.type };
+    case 'flux_kontext_reference_image':
+      return { image, model: getMainModelOrNull(value.model), type: value.type };
+    case 'flux_redux':
+      return {
+        image,
+        imageInfluence: isFluxReduxImageInfluence(value.imageInfluence) ? value.imageInfluence : 'highest',
+        model: getModelIdentifierOrNull(value.model),
+        type: value.type,
+      };
+    case 'ip_adapter':
+      return {
+        beginEndStepPct:
+          Array.isArray(value.beginEndStepPct) &&
+          value.beginEndStepPct.length === 2 &&
+          value.beginEndStepPct.every((item) => typeof item === 'number' && Number.isFinite(item))
+            ? [value.beginEndStepPct[0], value.beginEndStepPct[1]]
+            : [0, 1],
+        clipVisionModel: isClipVisionModel(value.clipVisionModel) ? value.clipVisionModel : 'ViT-H',
+        image,
+        method: isIPAdapterMethod(value.method) ? value.method : 'full',
+        model: getModelIdentifierOrNull(value.model),
+        type: value.type,
+        weight: hasFiniteNumber(value, 'weight') ? (value.weight as number) : 1,
+      };
+  }
+
+  return null;
+};
+
+export const normalizeReferenceImages = (value: unknown): GenerateReferenceImage[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const images: GenerateReferenceImage[] = [];
+
+  for (const item of value) {
+    if (!isRecord(item) || typeof item.id !== 'string') {
+      continue;
+    }
+
+    const config = normalizeReferenceImageConfig(item.config);
+
+    if (!config) {
+      continue;
+    }
+
+    images.push({ config, id: item.id, isEnabled: item.isEnabled !== false });
+  }
+
+  return images;
+};
+
+const cloneReferenceImageConfig = (config: GenerateReferenceImageConfig): GenerateReferenceImageConfig => {
+  switch (config.type) {
+    case 'external_reference_image':
+    case 'flux2_reference_image':
+    case 'qwen_image_reference_image':
+      return { ...config, image: config.image ? cloneReferenceImageAsset(config.image) : null };
+    case 'flux_kontext_reference_image':
+      return {
+        ...config,
+        image: config.image ? cloneReferenceImageAsset(config.image) : null,
+        model: config.model ? { ...config.model } : null,
+      };
+    case 'flux_redux':
+    case 'ip_adapter':
+      return {
+        ...config,
+        image: config.image ? cloneReferenceImageAsset(config.image) : null,
+        model: config.model ? { ...config.model } : null,
+      };
+  }
+};
+
+export const cloneReferenceImages = (
+  referenceImages: readonly GenerateReferenceImage[] = []
+): GenerateReferenceImage[] =>
+  referenceImages.map((referenceImage) => ({
+    ...referenceImage,
+    config: cloneReferenceImageConfig(referenceImage.config),
+  }));
+
+export const getDefaultLoraWeight = (model: LoraModelConfig): number => {
+  const weight = model.default_settings?.weight;
+
+  return Number.isFinite(weight) && weight !== null && weight !== undefined
+    ? weight
+    : DEFAULT_LORA_WEIGHT_CONFIG.initial;
+};
+
+const areModelSnapshotsEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) {
+    return true;
+  }
+
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+};
+
+export const syncGenerateLorasWithModels = (loras: GenerateLora[], models: readonly unknown[]): GenerateLora[] => {
+  const modelsByKey = new Map<string, LoraModelConfig>();
+
+  for (const model of models) {
+    if (isLoraModelConfig(model)) {
+      modelsByKey.set(model.key, model);
+    }
+  }
+
+  let didSync = false;
+  const syncedLoras = loras.map((lora) => {
+    const currentModel = modelsByKey.get(lora.model.key);
+
+    if (!currentModel || areModelSnapshotsEqual(currentModel, lora.model)) {
+      return lora;
+    }
+
+    didSync = true;
+    return { ...lora, model: currentModel };
+  });
+
+  return didSync ? syncedLoras : loras;
+};
+
+const syncModelIdentifierWithModels = <T extends ComponentModelConfig | null>(
+  value: T,
+  modelsByKey: Map<string, unknown>
+): T => {
+  if (!value) {
+    return value;
+  }
+
+  const currentModel = modelsByKey.get(value.key);
+
+  return isModelIdentifierConfig(currentModel) && !areModelSnapshotsEqual(currentModel, value)
+    ? (currentModel as T)
+    : value;
+};
+
+export const getModelDefaultVae = (
+  model: GenerateModelConfig,
+  vaeModels: readonly VaeModelConfig[]
+): VaeModelConfig | null => {
+  const defaultVaeKey = (model.default_settings as { vae?: string | null } | null | undefined)?.vae;
+
+  return defaultVaeKey
+    ? (vaeModels.find((vae) => vae.key === defaultVaeKey && isVaeCompatibleWithGenerateModel(model, vae)) ?? null)
+    : null;
+};
+
+export const hasModelDefaultVae = (model: GenerateModelConfig): boolean =>
+  typeof (model.default_settings as { vae?: unknown } | null | undefined)?.vae === 'string';
+
+export const cloneGenerateWidgetValues = (
+  values: GenerateWidgetValues
+): GenerateWidgetValues & Record<string, unknown> => ({
+  ...values,
+  clipEmbedModel: values.clipEmbedModel ? { ...values.clipEmbedModel } : null,
+  clipGEmbedModel: values.clipGEmbedModel ? { ...values.clipGEmbedModel } : null,
+  clipLEmbedModel: values.clipLEmbedModel ? { ...values.clipLEmbedModel } : null,
+  componentSourceModel: values.componentSourceModel ? { ...values.componentSourceModel } : null,
+  loras: values.loras.map((lora) => ({ ...lora, model: { ...lora.model } })),
+  model: { ...values.model },
+  qwen3EncoderModel: values.qwen3EncoderModel ? { ...values.qwen3EncoderModel } : null,
+  qwenVLEncoderModel: values.qwenVLEncoderModel ? { ...values.qwenVLEncoderModel } : null,
+  referenceImages: cloneReferenceImages(values.referenceImages),
+  t5EncoderModel: values.t5EncoderModel ? { ...values.t5EncoderModel } : null,
+  vae: values.vae ? { ...values.vae } : null,
+});
+
+const syncReferenceImageConfigWithModels = (
+  config: GenerateReferenceImageConfig,
+  modelsByKey: Map<string, unknown>
+): GenerateReferenceImageConfig => {
+  switch (config.type) {
+    case 'flux_kontext_reference_image': {
+      const model = syncModelIdentifierWithModels(config.model, modelsByKey);
+
+      return model === config.model ? config : { ...config, model: isMainModelConfig(model) ? model : config.model };
+    }
+    case 'flux_redux':
+    case 'ip_adapter': {
+      const model = syncModelIdentifierWithModels(config.model, modelsByKey);
+
+      return model === config.model ? config : { ...config, model };
+    }
+    case 'external_reference_image':
+    case 'flux2_reference_image':
+    case 'qwen_image_reference_image':
+      return config;
+  }
+};
+
+export const syncReferenceImagesWithModels = (
+  referenceImages: GenerateReferenceImage[],
+  models: readonly unknown[]
+): GenerateReferenceImage[] => {
+  const modelsByKey = new Map<string, unknown>();
+
+  for (const model of models) {
+    if (isModelIdentifierConfig(model)) {
+      modelsByKey.set(model.key, model);
+    }
+  }
+
+  let didSync = false;
+  const synced = referenceImages.map((referenceImage) => {
+    const config = syncReferenceImageConfigWithModels(referenceImage.config, modelsByKey);
+
+    if (config === referenceImage.config) {
+      return referenceImage;
+    }
+
+    didSync = true;
+    return { ...referenceImage, config };
+  });
+
+  return didSync ? synced : referenceImages;
+};
+
+export const syncGenerateWidgetValuesWithModels = (
+  values: GenerateWidgetValues,
+  models: readonly unknown[]
+): GenerateWidgetValues => {
+  const modelsByKey = new Map<string, unknown>();
+
+  for (const model of models) {
+    if (isModelIdentifierConfig(model)) {
+      modelsByKey.set(model.key, model);
+    }
+  }
+
+  const currentModel = modelsByKey.get(values.model.key);
+  const model =
+    isGenerateModelConfig(currentModel) && !areModelSnapshotsEqual(currentModel, values.model)
+      ? currentModel
+      : values.model;
+  const vae = syncModelIdentifierWithModels(values.vae, modelsByKey);
+  const componentSourceModel = syncModelIdentifierWithModels(values.componentSourceModel, modelsByKey);
+  const nextValues: GenerateWidgetValues = {
+    ...values,
+    clipEmbedModel: syncModelIdentifierWithModels(values.clipEmbedModel, modelsByKey),
+    clipGEmbedModel: syncModelIdentifierWithModels(values.clipGEmbedModel, modelsByKey),
+    clipLEmbedModel: syncModelIdentifierWithModels(values.clipLEmbedModel, modelsByKey),
+    componentSourceModel: isMainModelConfig(componentSourceModel) ? componentSourceModel : values.componentSourceModel,
+    loras: syncGenerateLorasWithModels(values.loras, models),
+    model,
+    modelKey: model.key,
+    qwen3EncoderModel: syncModelIdentifierWithModels(values.qwen3EncoderModel, modelsByKey),
+    qwenVLEncoderModel: syncModelIdentifierWithModels(values.qwenVLEncoderModel, modelsByKey),
+    referenceImages: syncReferenceImagesWithModels(values.referenceImages, models),
+    t5EncoderModel: syncModelIdentifierWithModels(values.t5EncoderModel, modelsByKey),
+    vae: isVaeModelConfig(vae) ? vae : values.vae,
+  };
+
+  return nextValues.model === values.model &&
+    nextValues.loras === values.loras &&
+    nextValues.vae === values.vae &&
+    nextValues.t5EncoderModel === values.t5EncoderModel &&
+    nextValues.clipEmbedModel === values.clipEmbedModel &&
+    nextValues.clipLEmbedModel === values.clipLEmbedModel &&
+    nextValues.clipGEmbedModel === values.clipGEmbedModel &&
+    nextValues.qwen3EncoderModel === values.qwen3EncoderModel &&
+    nextValues.qwenVLEncoderModel === values.qwenVLEncoderModel &&
+    nextValues.referenceImages === values.referenceImages &&
+    nextValues.componentSourceModel === values.componentSourceModel &&
+    nextValues.modelKey === values.modelKey
+    ? values
+    : nextValues;
+};
+
+export const isLoraCompatibleWithModel = (
+  loraModel: Pick<LoraModelConfig, 'base' | 'variant'>,
+  mainModel: Pick<GenerateModelConfig, 'base' | 'variant'>
+): boolean => {
+  if (mainModel.base === 'flux2') {
+    if (loraModel.base !== 'flux2' && loraModel.base !== 'flux') {
+      return false;
+    }
+
+    return (
+      loraModel.base === 'flux' || !mainModel.variant || !loraModel.variant || loraModel.variant === mainModel.variant
+    );
+  }
+
+  if (loraModel.base !== mainModel.base) {
+    return false;
+  }
+
+  return true;
+};
+
+/**
+ * Validate stored widget values and fill in fields that older persisted
+ * projects predate. The core fields must be present and well-typed; newer
+ * fields fall back to their defaults so old projects keep their prompts and
+ * dimensions instead of being reset wholesale.
+ */
+export const normalizeGenerateSettings = (values: unknown): GenerateSettings | null => {
+  if (!isRecord(values)) {
+    return null;
+  }
+
+  const isCoreShapeValid =
+    typeof values.modelKey === 'string' &&
+    typeof values.positivePrompt === 'string' &&
+    typeof values.negativePrompt === 'string' &&
+    typeof values.scheduler === 'string' &&
+    typeof values.shouldRandomizeSeed === 'boolean' &&
+    ['width', 'height', 'steps', 'cfgScale', 'cfgRescaleMultiplier', 'seed'].every((key) =>
+      hasFiniteNumber(values, key)
+    );
+
+  if (!isCoreShapeValid) {
+    return null;
+  }
+
+  const width = values.width as number;
+  const height = values.height as number;
+
+  return {
+    aspectRatioId: isAspectRatioId(values.aspectRatioId) ? values.aspectRatioId : deriveAspectRatioId(width, height),
+    aspectRatioIsLocked: typeof values.aspectRatioIsLocked === 'boolean' ? values.aspectRatioIsLocked : false,
+    aspectRatioValue:
+      hasFiniteNumber(values, 'aspectRatioValue') && (values.aspectRatioValue as number) > 0
+        ? (values.aspectRatioValue as number)
+        : height > 0
+          ? width / height
+          : 1,
+    batchCount: sanitizeBatchCount(values.batchCount),
+    cfgRescaleMultiplier: values.cfgRescaleMultiplier as number,
+    cfgScale: values.cfgScale as number,
+    clipSkip: hasFiniteNumber(values, 'clipSkip') ? (values.clipSkip as number) : 0,
+    colorCompensation: typeof values.colorCompensation === 'boolean' ? values.colorCompensation : false,
+    height,
+    loras: Array.isArray(values.loras) ? values.loras.filter(isGenerateLora) : [],
+    modelKey: values.modelKey as string,
+    negativePromptEnabled: typeof values.negativePromptEnabled === 'boolean' ? values.negativePromptEnabled : true,
+    negativePrompt: values.negativePrompt as string,
+    negativePromptHeightPx: getClampedNumber(
+      values,
+      'negativePromptHeightPx',
+      MIN_NEGATIVE_PROMPT_HEIGHT_PX,
+      MAX_NEGATIVE_PROMPT_HEIGHT_PX,
+      DEFAULT_NEGATIVE_PROMPT_HEIGHT_PX
+    ),
+    positivePrompt: values.positivePrompt as string,
+    positivePromptHeightPx: getClampedNumber(
+      values,
+      'positivePromptHeightPx',
+      MIN_POSITIVE_PROMPT_HEIGHT_PX,
+      MAX_POSITIVE_PROMPT_HEIGHT_PX,
+      DEFAULT_POSITIVE_PROMPT_HEIGHT_PX
+    ),
+    referenceImages: normalizeReferenceImages(values.referenceImages),
+    scheduler: values.scheduler as string,
+    seamlessXAxis: typeof values.seamlessXAxis === 'boolean' ? values.seamlessXAxis : false,
+    seamlessYAxis: typeof values.seamlessYAxis === 'boolean' ? values.seamlessYAxis : false,
+    seed: values.seed as number,
+    shouldRandomizeSeed: values.shouldRandomizeSeed as boolean,
+    steps: values.steps as number,
+    vae: isVaeModelConfig(values.vae) ? values.vae : null,
+    vaePrecision: isVaePrecision(values.vaePrecision) ? values.vaePrecision : 'fp32',
+    t5EncoderModel: getModelIdentifierOrNull(values.t5EncoderModel),
+    clipEmbedModel: getModelIdentifierOrNull(values.clipEmbedModel),
+    clipLEmbedModel: getModelIdentifierOrNull(values.clipLEmbedModel),
+    clipGEmbedModel: getModelIdentifierOrNull(values.clipGEmbedModel),
+    qwen3EncoderModel: getModelIdentifierOrNull(values.qwen3EncoderModel),
+    qwenVLEncoderModel: getModelIdentifierOrNull(values.qwenVLEncoderModel),
+    componentSourceModel: getMainModelOrNull(values.componentSourceModel),
+    width,
+  };
+};
+
+export const normalizeGenerateWidgetValues = (values: unknown): GenerateWidgetValues | null => {
+  const settings = normalizeGenerateSettings(values);
+
+  if (!settings || !isRecord(values) || !isGenerateModelConfig(values.model)) {
+    return null;
+  }
+
+  return { ...settings, model: values.model };
+};
+
+export const isGenerateSettings = (values: unknown): values is GenerateSettings => {
+  const normalized = normalizeGenerateSettings(values);
+
+  if (!normalized || !isRecord(values)) {
+    return false;
+  }
+
+  // Strict only over the keys normalize would have to invent.
+  return (
+    isAspectRatioId(values.aspectRatioId) &&
+    typeof values.aspectRatioIsLocked === 'boolean' &&
+    hasFiniteNumber(values, 'aspectRatioValue') &&
+    hasFiniteNumber(values, 'clipSkip') &&
+    typeof values.colorCompensation === 'boolean' &&
+    typeof values.negativePromptEnabled === 'boolean' &&
+    hasFiniteNumber(values, 'negativePromptHeightPx') &&
+    hasFiniteNumber(values, 'positivePromptHeightPx') &&
+    Array.isArray(values.loras) &&
+    values.loras.every(isGenerateLora) &&
+    Array.isArray(values.referenceImages) &&
+    normalizeReferenceImages(values.referenceImages).length === values.referenceImages.length &&
+    typeof values.seamlessXAxis === 'boolean' &&
+    typeof values.seamlessYAxis === 'boolean' &&
+    isVaePrecision(values.vaePrecision) &&
+    (values.vae === null || isVaeModelConfig(values.vae)) &&
+    (values.t5EncoderModel === null || isModelIdentifierConfig(values.t5EncoderModel)) &&
+    (values.clipEmbedModel === null || isModelIdentifierConfig(values.clipEmbedModel)) &&
+    (values.clipLEmbedModel === null || isModelIdentifierConfig(values.clipLEmbedModel)) &&
+    (values.clipGEmbedModel === null || isModelIdentifierConfig(values.clipGEmbedModel)) &&
+    (values.qwen3EncoderModel === null || isModelIdentifierConfig(values.qwen3EncoderModel)) &&
+    (values.qwenVLEncoderModel === null || isModelIdentifierConfig(values.qwenVLEncoderModel)) &&
+    (values.componentSourceModel === null || isMainModelConfig(values.componentSourceModel))
+  );
+};
+
+export const isGenerateWidgetValues = (values: unknown): values is GenerateWidgetValues =>
+  isGenerateSettings(values) && isGenerateModelConfig((values as unknown as Record<string, unknown>).model);
diff --git a/invokeai/frontend/webv2/src/workbench/generation/types.ts b/invokeai/frontend/webv2/src/workbench/generation/types.ts
new file mode 100644
index 00000000000..1906a0aae52
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/generation/types.ts
@@ -0,0 +1,229 @@
+import type { BackendGraphContract, GeneratedImageContract, GraphContract, ResultDestination } from '@workbench/types';
+
+export type ModelIdentifierConfig = {
+  key: string;
+  name: string;
+  base: string;
+  type: string;
+  format?: string;
+  variant?: string | null;
+  hash?: string;
+  submodel_type?: string;
+  [key: string]: unknown;
+};
+
+export type MainModelConfig = ModelIdentifierConfig & {
+  type: 'main';
+  default_settings?: {
+    scheduler?: string | null;
+    steps?: number | null;
+    cfg_scale?: number | null;
+    guidance?: number | null;
+    cfg_rescale_multiplier?: number | null;
+    width?: number | null;
+    height?: number | null;
+    vae?: string | null;
+    vae_precision?: string | null;
+  } | null;
+};
+
+export type ExternalImageGeneratorModelConfig = ModelIdentifierConfig & {
+  base: 'external';
+  type: 'external_image_generator';
+  format: 'external_api';
+  provider_id?: string;
+  capabilities?: {
+    modes?: string[];
+    supports_seed?: boolean;
+    supports_negative_prompt?: boolean;
+    supports_reference_images?: boolean;
+    max_reference_images?: number | null;
+  } | null;
+  default_settings?: {
+    width?: number | null;
+    height?: number | null;
+    num_images?: number | null;
+  } | null;
+};
+
+export type GenerateModelConfig = MainModelConfig | ExternalImageGeneratorModelConfig;
+
+export type ComponentModelConfig = ModelIdentifierConfig;
+
+export type VaeModelConfig = ModelIdentifierConfig & {
+  type: 'vae';
+};
+
+export type LoraModelConfig = ModelIdentifierConfig & {
+  type: 'lora';
+  trigger_phrases?: string[] | null;
+  default_settings?: {
+    weight?: number | null;
+  } | null;
+  variant?: string | null;
+};
+
+export interface GenerateLora {
+  isEnabled: boolean;
+  model: LoraModelConfig;
+  weight: number;
+}
+
+export type GenerateReferenceImageAsset = GeneratedImageContract;
+
+export type ClipVisionModel = 'ViT-H' | 'ViT-G' | 'ViT-L';
+
+export type IPAdapterMethod = 'full' | 'style' | 'composition' | 'style_strong' | 'style_precise';
+
+export type FluxReduxImageInfluence = 'lowest' | 'low' | 'medium' | 'high' | 'highest';
+
+export type GenerateReferenceImageConfig =
+  | {
+      type: 'ip_adapter';
+      image: GenerateReferenceImageAsset | null;
+      model: ComponentModelConfig | null;
+      weight: number;
+      beginEndStepPct: [number, number];
+      method: IPAdapterMethod;
+      clipVisionModel: ClipVisionModel;
+    }
+  | {
+      type: 'flux_redux';
+      image: GenerateReferenceImageAsset | null;
+      model: ComponentModelConfig | null;
+      imageInfluence: FluxReduxImageInfluence;
+    }
+  | {
+      type: 'flux_kontext_reference_image';
+      image: GenerateReferenceImageAsset | null;
+      model: MainModelConfig | null;
+    }
+  | { type: 'flux2_reference_image'; image: GenerateReferenceImageAsset | null }
+  | { type: 'qwen_image_reference_image'; image: GenerateReferenceImageAsset | null }
+  | { type: 'external_reference_image'; image: GenerateReferenceImageAsset | null };
+
+export interface GenerateReferenceImage {
+  id: string;
+  isEnabled: boolean;
+  config: GenerateReferenceImageConfig;
+}
+
+export type VaePrecision = 'fp16' | 'fp32';
+
+export type AspectRatioId =
+  | 'Free'
+  | '8:1'
+  | '4:1'
+  | '21:9'
+  | '16:9'
+  | '3:2'
+  | '5:4'
+  | '4:3'
+  | '1:1'
+  | '3:4'
+  | '4:5'
+  | '2:3'
+  | '9:16'
+  | '1:4'
+  | '9:21'
+  | '1:8';
+
+export interface GenerateSettings {
+  batchCount: number;
+  modelKey: string;
+  positivePrompt: string;
+  positivePromptHeightPx: number;
+  negativePromptEnabled: boolean;
+  negativePrompt: string;
+  negativePromptHeightPx: number;
+  width: number;
+  height: number;
+  aspectRatioId: AspectRatioId;
+  /** width / height ratio enforced while locked. Tracks the preset, or the captured ratio in Free mode. */
+  aspectRatioValue: number;
+  aspectRatioIsLocked: boolean;
+  steps: number;
+  cfgScale: number;
+  cfgRescaleMultiplier: number;
+  scheduler: string;
+  clipSkip: number;
+  colorCompensation: boolean;
+  seed: number;
+  shouldRandomizeSeed: boolean;
+  seamlessXAxis: boolean;
+  seamlessYAxis: boolean;
+  /** Optional VAE override; null uses the VAE bundled with the main model. */
+  vae: VaeModelConfig | null;
+  vaePrecision: VaePrecision;
+  loras: GenerateLora[];
+  referenceImages: GenerateReferenceImage[];
+  t5EncoderModel: ComponentModelConfig | null;
+  clipEmbedModel: ComponentModelConfig | null;
+  clipLEmbedModel: ComponentModelConfig | null;
+  clipGEmbedModel: ComponentModelConfig | null;
+  qwen3EncoderModel: ComponentModelConfig | null;
+  qwenVLEncoderModel: ComponentModelConfig | null;
+  /** Optional Diffusers main model used as a component source for split/quantized model families. */
+  componentSourceModel: MainModelConfig | null;
+}
+
+export interface GenerateWidgetValues extends GenerateSettings {
+  model: GenerateModelConfig;
+}
+
+export interface CompiledGenerateGraph {
+  backendGraph: BackendGraphContract;
+  graph: GraphContract;
+  negativePromptNodeId: string;
+  positivePromptNodeId: string;
+  seedNodeId: string;
+}
+
+export interface EnqueueGenerateResult {
+  batchId?: string;
+  enqueued: number;
+  itemIds: number[];
+  requested: number;
+}
+
+export interface QueueItemDTO {
+  item_id: number;
+  status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'canceled';
+  batch_id?: string;
+  origin?: string | null;
+  destination?: string | null;
+  error_type?: string | null;
+  error_message?: string | null;
+  session?: {
+    prepared_source_mapping?: Record<string, string>;
+    results: Record<string, unknown>;
+  };
+}
+
+/** A source-agnostic graph submission (used by the workflow source). */
+export interface EnqueueWorkflowRequest {
+  batchCount: number;
+  destination: ResultDestination;
+  graph: BackendGraphContract;
+  projectId: string;
+  sourceQueueItemId: string;
+}
+
+export interface EnqueueGenerateRequest {
+  batchCount: number;
+  destination: ResultDestination;
+  graph: BackendGraphContract;
+  negativePrompt: string;
+  negativePromptNodeId: string;
+  positivePrompt: string;
+  positivePromptNodeId: string;
+  seed: number;
+  seedNodeId: string;
+  shouldRandomizeSeed: boolean;
+  projectId: string;
+  sourceQueueItemId: string;
+}
+
+export interface ImageDTO extends GeneratedImageContract {
+  isIntermediate: boolean;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/graph-preview/FlowMiniMap.tsx b/invokeai/frontend/webv2/src/workbench/graph-preview/FlowMiniMap.tsx
new file mode 100644
index 00000000000..dbf9ffdf0c4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/graph-preview/FlowMiniMap.tsx
@@ -0,0 +1,23 @@
+import { chakra } from '@chakra-ui/react';
+import { MiniMap } from '@xyflow/react';
+
+/**
+ * xyflow's MiniMap wrapped in the chakra factory so its frame is styled with
+ * workbench tokens (the fills inside the SVG come from the `--xy-minimap-*`
+ * vars in `flowTheme.ts`).
+ */
+const StyledMiniMap = chakra(MiniMap);
+
+export const FlowMiniMap = () => (
+  <StyledMiniMap
+    borderColor="border.subtle"
+    borderWidth="1px"
+    m="3"
+    overflow="hidden"
+    pannable
+    position="bottom-right"
+    rounded="md"
+    shadow="sm"
+    zoomable
+  />
+);
diff --git a/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewDialog.test.ts b/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewDialog.test.ts
new file mode 100644
index 00000000000..a61cbe6eeae
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewDialog.test.ts
@@ -0,0 +1,138 @@
+import type {
+  GenerateWidgetValues,
+  MainModelConfig,
+  VaeModelConfig,
+  ComponentModelConfig,
+} from '@workbench/generation/types';
+
+import { getDefaultGenerateSettings } from '@workbench/generation/baseGenerationPolicies';
+import { createInitialWorkbenchState, workbenchReducer } from '@workbench/workbenchState';
+import { describe, expect, it, vi } from 'vitest';
+
+import { resolveAndSubmitGraphPreviewInvocation } from './GraphPreviewDialog';
+
+const animaModel: MainModelConfig = { base: 'anima', key: 'anima-model', name: 'Anima', type: 'main' };
+const animaVae: VaeModelConfig = { base: 'qwen-image', key: 'anima-vae', name: 'Anima VAE', type: 'vae' };
+const qwen3Encoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'qwen3-encoder',
+  name: 'Qwen3 Encoder',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_06b',
+};
+
+const createGenerateValues = (overrides: Partial<GenerateWidgetValues> = {}): GenerateWidgetValues => ({
+  ...getDefaultGenerateSettings(animaModel),
+  model: animaModel,
+  modelKey: animaModel.key,
+  positivePrompt: 'an anima prompt',
+  qwen3EncoderModel: qwen3Encoder,
+  vae: animaVae,
+  ...overrides,
+});
+
+const getActiveProject = (values: GenerateWidgetValues) => {
+  const state = workbenchReducer(createInitialWorkbenchState(), { type: 'setGenerateSettings', values });
+  const project = state.projects.find((candidate) => candidate.id === state.activeProjectId);
+
+  expect(project).toBeDefined();
+
+  return project!;
+};
+
+// Mounts the canvas widget into the center region so `resolveInvocationRoute`
+// treats a `canvas` source as available (mirrors invocation.test.ts's
+// `canvasInputFor` mountedWidgetIds override, but here as an actual project
+// mutation since `resolveAndSubmitGraphPreviewInvocation` takes a real Project).
+const withCanvasWidgetMounted = (
+  project: ReturnType<typeof getActiveProject>
+): ReturnType<typeof getActiveProject> => ({
+  ...project,
+  widgetRegions: {
+    ...project.widgetRegions,
+    center: {
+      ...project.widgetRegions.center,
+      activeInstanceId: 'canvas',
+      instanceIds: ['canvas'],
+    },
+  },
+});
+
+describe('resolveAndSubmitGraphPreviewInvocation', () => {
+  it('routes a canvas source through prepareCanvasInvocation and does not dispatch a resolved snapshot', () => {
+    const project = withCanvasWidgetMounted(getActiveProject(createGenerateValues()));
+    const dispatch = vi.fn();
+    const prepareCanvasInvocation = vi.fn();
+
+    const submitted = resolveAndSubmitGraphPreviewInvocation({
+      dispatch,
+      models: undefined,
+      prepareCanvasInvocation,
+      project,
+      sourceId: 'canvas',
+    });
+
+    expect(submitted).toBe(true);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(prepareCanvasInvocation).toHaveBeenCalledTimes(1);
+    expect(prepareCanvasInvocation.mock.calls[0]?.[0]).toMatchObject({ projectId: project.id });
+  });
+
+  it('dispatches submitResolvedInvocationSnapshot for a non-canvas source and never prepares the canvas', () => {
+    const project = getActiveProject(createGenerateValues());
+    const dispatch = vi.fn();
+    const prepareCanvasInvocation = vi.fn();
+
+    const submitted = resolveAndSubmitGraphPreviewInvocation({
+      dispatch,
+      models: undefined,
+      prepareCanvasInvocation,
+      project,
+      sourceId: 'generate',
+    });
+
+    expect(submitted).toBe(true);
+    expect(prepareCanvasInvocation).not.toHaveBeenCalled();
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch.mock.calls[0]?.[0]).toMatchObject({
+      route: expect.objectContaining({ sourceId: 'generate' }),
+      type: 'submitResolvedInvocationSnapshot',
+    });
+  });
+
+  it('returns false and does not submit when there is no sourceId', () => {
+    const project = getActiveProject(createGenerateValues());
+    const dispatch = vi.fn();
+    const prepareCanvasInvocation = vi.fn();
+
+    const submitted = resolveAndSubmitGraphPreviewInvocation({
+      dispatch,
+      models: undefined,
+      prepareCanvasInvocation,
+      project,
+      sourceId: undefined,
+    });
+
+    expect(submitted).toBe(false);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(prepareCanvasInvocation).not.toHaveBeenCalled();
+  });
+
+  it('returns false and does not submit when the resolved route is invalid', () => {
+    const project = getActiveProject(createGenerateValues({ qwen3EncoderModel: undefined }));
+    const dispatch = vi.fn();
+    const prepareCanvasInvocation = vi.fn();
+
+    const submitted = resolveAndSubmitGraphPreviewInvocation({
+      dispatch,
+      models: undefined,
+      prepareCanvasInvocation,
+      project,
+      sourceId: 'generate',
+    });
+
+    expect(submitted).toBe(false);
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(prepareCanvasInvocation).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewDialog.tsx b/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewDialog.tsx
new file mode 100644
index 00000000000..20f65aa22c2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewDialog.tsx
@@ -0,0 +1,206 @@
+import type { ModelConfig } from '@workbench/models/types';
+import type { GraphContract, GraphId, InvocationSourceId, Project } from '@workbench/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+import type { XYPosition } from '@workbench/workflows/types';
+
+import { Box, Dialog, Portal, SegmentGroup, Text } from '@chakra-ui/react';
+import { Button, JsonPreview } from '@workbench/components/ui';
+import {
+  createInvocationRouteInputSelector,
+  formatRoute,
+  isInvocationRouteValid,
+  resolveInvocationRoute,
+  resolveInvocationRouteInput,
+} from '@workbench/invocation';
+import { submitResolvedInvocation } from '@workbench/invocationSubmit';
+import { ensureModelsLoaded, useModelsSelector } from '@workbench/models/modelsStore';
+import { prepareCanvasInvocation } from '@workbench/widgets/canvas/invoke/prepareCanvasInvocation';
+import { flushGenerateDrafts } from '@workbench/widgets/generate/generateDraftRegistry';
+import { useActiveProjectSelector, useWorkbenchDispatch, useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { GraphPreviewFlow } from './GraphPreviewFlow';
+
+export interface GraphPreviewInvokeDeps {
+  dispatch: (action: WorkbenchAction) => void;
+  models: readonly ModelConfig[] | undefined;
+  prepareCanvasInvocation: typeof prepareCanvasInvocation;
+  project: Project;
+  sourceId: InvocationSourceId | undefined;
+}
+
+/**
+ * Resolves the dialog-locked invocation route for `sourceId` against the
+ * post-flush project and, when valid, submits it through the shared
+ * canvas-vs-generate submit decision (`submitResolvedInvocation`) — the same
+ * routing the topbar Invoke control and the Invoke hotkey use. Without this,
+ * a valid Canvas route would dispatch `submitResolvedInvocationSnapshot`
+ * directly, which silently no-ops for a canvas source. Returns whether the
+ * route was valid and submitted, so the dialog only closes on success.
+ */
+export const resolveAndSubmitGraphPreviewInvocation = ({
+  dispatch,
+  models,
+  prepareCanvasInvocation: prepareCanvas,
+  project,
+  sourceId,
+}: GraphPreviewInvokeDeps): boolean => {
+  if (!sourceId) {
+    return false;
+  }
+
+  const route = resolveInvocationRoute(
+    project,
+    'dialog',
+    { ...project.invocation, sourceId, sourceLocked: true },
+    models
+  );
+
+  if (!isInvocationRouteValid(route)) {
+    return false;
+  }
+
+  submitResolvedInvocation({ dispatch, models, prepareCanvasInvocation: prepareCanvas, project, route });
+  return true;
+};
+
+interface GraphPreviewDialogProps {
+  graph: GraphContract | null;
+  graphId: GraphId;
+  isOpen: boolean;
+  /** Editor positions keyed by node id, when the graph mirrors an editable document. */
+  positionHints?: Record<string, XYPosition>;
+  sourceId?: InvocationSourceId;
+  title: string;
+  onOpenChange: (isOpen: boolean) => void;
+}
+
+type PreviewMode = 'nodes' | 'json';
+
+const selectInvocationRouteInput = createInvocationRouteInputSelector();
+const modeItems = [
+  { labelKey: 'graphPreview.nodes', value: 'nodes' },
+  { labelKey: 'common.json', value: 'json' },
+];
+
+const PreviewPane = ({ children }: { children: ReactNode }) => (
+  <Box flex="1" h="full" minH="0" minW="0" w="full" rounded="md" borderWidth={1} overflow="hidden">
+    {children}
+  </Box>
+);
+
+export const GraphPreviewDialog = ({
+  graph,
+  graphId,
+  isOpen,
+  positionHints,
+  sourceId,
+  title,
+  onOpenChange,
+}: GraphPreviewDialogProps) => {
+  const { t } = useTranslation();
+  const routeInput = useActiveProjectSelector(selectInvocationRouteInput);
+  const dispatch = useWorkbenchDispatch();
+  const store = useWorkbenchStore();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const modelsStatus = useModelsSelector((snapshot) => snapshot.status);
+  const availabilityModels = modelsStatus === 'loaded' ? models : undefined;
+  const [mode, setMode] = useState<PreviewMode>('nodes');
+
+  useInvocationTemplatesSelector((snapshot) => snapshot.status);
+
+  const dialogRoute = sourceId
+    ? resolveInvocationRouteInput(
+        routeInput,
+        'dialog',
+        { ...routeInput.invocation, sourceId, sourceLocked: true },
+        availabilityModels
+      )
+    : null;
+  const canInvoke = dialogRoute ? isInvocationRouteValid(dialogRoute) : false;
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  const handleOpenChange = useCallback((event: { open: boolean }) => onOpenChange(event.open), [onOpenChange]);
+  const handleModeChange = useCallback(
+    (event: { value: string | null }) => setMode(event.value === 'json' ? 'json' : 'nodes'),
+    []
+  );
+  const closeDialog = useCallback(() => onOpenChange(false), [onOpenChange]);
+  const invokeRoute = useCallback(() => {
+    flushGenerateDrafts();
+    const postFlushProject = store.getSnapshot().activeProject;
+    const submitted = resolveAndSubmitGraphPreviewInvocation({
+      dispatch,
+      models: availabilityModels,
+      prepareCanvasInvocation,
+      project: postFlushProject,
+      sourceId,
+    });
+
+    if (submitted) {
+      onOpenChange(false);
+    }
+  }, [availabilityModels, dispatch, onOpenChange, sourceId, store]);
+  const jsonLabel = useMemo(() => t('graphPreview.graphJsonLabel', { title }), [t, title]);
+
+  return (
+    <Dialog.Root open={isOpen} size="xl" onOpenChange={handleOpenChange}>
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content h="62vh" maxH="62vh">
+            <Dialog.Header alignItems="center" flexDirection="row" justifyContent="space-between">
+              <Dialog.Title>{t('graphPreview.title', { title })}</Dialog.Title>
+              <SegmentGroup.Root size="xs" value={mode} onValueChange={handleModeChange}>
+                <SegmentGroup.Indicator />
+                {modeItems.map((item) => (
+                  <SegmentGroup.Item key={item.value} value={item.value}>
+                    <SegmentGroup.ItemHiddenInput />
+                    <SegmentGroup.ItemText>{t(item.labelKey)}</SegmentGroup.ItemText>
+                  </SegmentGroup.Item>
+                ))}
+              </SegmentGroup.Root>
+            </Dialog.Header>
+            <Dialog.Body display="flex" flex="1" flexDirection="column" minH="0">
+              {!graph ? (
+                <Text color="fg.muted" fontSize="sm">
+                  {t('graphPreview.noCompiledGraph', { graphId })}
+                </Text>
+              ) : mode === 'nodes' ? (
+                <PreviewPane>
+                  <GraphPreviewFlow graph={graph} positionHints={positionHints} />
+                </PreviewPane>
+              ) : (
+                <PreviewPane>
+                  <JsonPreview h="full" label={jsonLabel} maxH="100%" value={graph} />
+                </PreviewPane>
+              )}
+            </Dialog.Body>
+            <Dialog.Footer>
+              {dialogRoute ? (
+                <Button
+                  aria-disabled={!canInvoke}
+                  cursor={canInvoke ? undefined : 'not-allowed'}
+                  opacity={canInvoke ? undefined : 0.6}
+                  size="sm"
+                  title={dialogRoute.validationMessage}
+                  onClick={invokeRoute}
+                >
+                  {t('graphPreview.invokeRoute', { route: formatRoute(dialogRoute) })}
+                </Button>
+              ) : null}
+              <Button size="sm" variant="outline" onClick={closeDialog}>
+                {t('common.close')}
+              </Button>
+            </Dialog.Footer>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewFlow.tsx b/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewFlow.tsx
new file mode 100644
index 00000000000..2ab939b3453
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/graph-preview/GraphPreviewFlow.tsx
@@ -0,0 +1,213 @@
+import type { GraphContract } from '@workbench/types';
+
+import { Badge, Box, Stack, Text } from '@chakra-ui/react';
+import { useWorkbenchPreferenceSelector } from '@workbench/settings/store';
+import '@xyflow/react/dist/style.css';
+import { getResolvedWorkflowEdges } from '@workbench/workflows/connectors';
+import { isInvocationNode, type ProjectGraphState, type XYPosition } from '@workbench/workflows/types';
+import {
+  Background,
+  BackgroundVariant,
+  Handle,
+  Position,
+  ReactFlow,
+  type Edge as FlowEdge,
+  type Node as FlowNode,
+  type NodeProps,
+  type NodeTypes,
+} from '@xyflow/react';
+import { useId, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { flowThemeCss, getFlowColorMode } from './flowTheme';
+
+/**
+ * A read-only flow rendering of a compiled `GraphContract` — the "nodes" half
+ * of the graph preview dialog. Contracts carry no positions, so the renderer
+ * uses the caller's hints (the editable document's positions, when the graph
+ * came from the project graph) and falls back to a layered topological layout.
+ */
+
+type PreviewFlowNode = FlowNode<{ inputCount: number; nodeId: string; nodeType: string }, 'preview'>;
+
+/**
+ * A lightweight contract view of an editable document (no templates needed),
+ * for previewing workflows that are not the active project graph — e.g.
+ * library entries before loading them.
+ */
+export const documentToPreviewGraph = (
+  document: ProjectGraphState,
+  fallbackLabel: string
+): { graph: GraphContract; positionHints: Record<string, XYPosition> } => {
+  const invocationNodes = document.nodes.filter(isInvocationNode);
+  const invocationNodeIds = new Set(invocationNodes.map((node) => node.id));
+
+  return {
+    graph: {
+      edges: getResolvedWorkflowEdges(document.nodes, document.edges)
+        .filter((edge) => invocationNodeIds.has(edge.source) && invocationNodeIds.has(edge.target))
+        .map((edge) => ({
+          id: edge.id,
+          sourceField: edge.sourceHandle,
+          sourceNodeId: edge.source,
+          targetField: edge.targetHandle,
+          targetNodeId: edge.target,
+        })),
+      id: document.id,
+      label: document.name || fallbackLabel,
+      nodes: invocationNodes.map((node) => ({
+        id: node.id,
+        inputs: Object.fromEntries(Object.values(node.data.inputs).map((instance) => [instance.name, instance.value])),
+        type: node.data.type,
+      })),
+      updatedAt: document.updatedAt,
+      version: 1,
+    },
+    positionHints: Object.fromEntries(document.nodes.map((node) => [node.id, node.position])),
+  };
+};
+
+const LAYER_WIDTH = 300;
+const ROW_HEIGHT = 100;
+const handleStyle = { background: 'var(--wb-flow-grid)', border: 'none' } as const;
+const reactFlowProOptions = { hideAttribution: true } as const;
+const reactFlowStyle = { background: 'transparent' } as const;
+
+const PreviewNode = ({ data }: NodeProps<PreviewFlowNode>) => {
+  const { t } = useTranslation();
+
+  return (
+    <Box bg="bg" borderColor="border.emphasized" borderWidth="1px" fontSize="xs" minW="14rem" rounded="lg" shadow="sm">
+      <Handle position={Position.Left} style={handleStyle} type="target" />
+      <Handle position={Position.Right} style={handleStyle} type="source" />
+      <Stack gap="0.5" px="3" py="2">
+        <Badge fontFamily="mono" size="xs" w="fit-content">
+          {data.nodeType}
+        </Badge>
+        <Text color="fg.subtle" fontSize="2xs" truncate>
+          {data.nodeId} · {t('graphPreview.inputCount', { count: data.inputCount })}
+        </Text>
+      </Stack>
+    </Box>
+  );
+};
+
+const nodeTypes: NodeTypes = { preview: PreviewNode };
+
+/** Longest-path-from-roots depth per node; cycle members settle at their first depth. */
+const getNodeDepths = (graph: GraphContract): Map<string, number> => {
+  const depths = new Map<string, number>();
+  const incoming = new Map<string, string[]>();
+
+  for (const edge of graph.edges) {
+    incoming.set(edge.targetNodeId, [...(incoming.get(edge.targetNodeId) ?? []), edge.sourceNodeId]);
+  }
+
+  const resolve = (nodeId: string, seen: Set<string>): number => {
+    const known = depths.get(nodeId);
+
+    if (known !== undefined) {
+      return known;
+    }
+
+    if (seen.has(nodeId)) {
+      return 0;
+    }
+
+    seen.add(nodeId);
+
+    const parents = incoming.get(nodeId) ?? [];
+    const depth = parents.length === 0 ? 0 : Math.max(...parents.map((parent) => resolve(parent, seen))) + 1;
+
+    depths.set(nodeId, depth);
+
+    return depth;
+  };
+
+  for (const node of graph.nodes) {
+    resolve(node.id, new Set());
+  }
+
+  return depths;
+};
+
+const toPreviewNodes = (graph: GraphContract, positionHints?: Record<string, XYPosition>): PreviewFlowNode[] => {
+  const depths = getNodeDepths(graph);
+  const rowsPerDepth = new Map<number, number>();
+
+  return graph.nodes.map((node) => {
+    const hint = positionHints?.[node.id];
+
+    if (hint) {
+      return {
+        data: { inputCount: Object.keys(node.inputs).length, nodeId: node.id, nodeType: node.type },
+        id: node.id,
+        position: hint,
+        type: 'preview' as const,
+      };
+    }
+
+    const depth = depths.get(node.id) ?? 0;
+    const row = rowsPerDepth.get(depth) ?? 0;
+
+    rowsPerDepth.set(depth, row + 1);
+
+    return {
+      data: { inputCount: Object.keys(node.inputs).length, nodeId: node.id, nodeType: node.type },
+      id: node.id,
+      position: { x: depth * LAYER_WIDTH, y: row * ROW_HEIGHT },
+      type: 'preview' as const,
+    };
+  });
+};
+
+const toPreviewEdges = (graph: GraphContract): FlowEdge[] =>
+  graph.edges.map((edge) => ({
+    id: edge.id,
+    source: edge.sourceNodeId,
+    target: edge.targetNodeId,
+    type: 'default',
+  }));
+
+export const GraphPreviewFlow = ({
+  graph,
+  positionHints,
+}: {
+  graph: GraphContract;
+  positionHints?: Record<string, XYPosition>;
+}) => {
+  const themeId = useWorkbenchPreferenceSelector((preferences) => preferences.themeId);
+  const backgroundId = useId().replace(/:/g, '');
+  const nodes = useMemo(() => toPreviewNodes(graph, positionHints), [graph, positionHints]);
+  const edges = useMemo(() => toPreviewEdges(graph), [graph]);
+
+  return (
+    <Box bg="bg.inset" css={flowThemeCss} h="full" rounded="md" w="full">
+      <ReactFlow
+        colorMode={getFlowColorMode(themeId)}
+        edges={edges}
+        edgesFocusable={false}
+        elementsSelectable={false}
+        fitView
+        maxZoom={1.5}
+        minZoom={0.1}
+        nodes={nodes}
+        nodesConnectable={false}
+        nodesDraggable={false}
+        nodesFocusable={false}
+        nodeTypes={nodeTypes}
+        proOptions={reactFlowProOptions}
+        style={reactFlowStyle}
+      >
+        <Background
+          bgColor="var(--xy-background-color)"
+          color="var(--wb-flow-grid)"
+          gap={24}
+          id={`preview-grid-${backgroundId}`}
+          size={1.5}
+          variant={BackgroundVariant.Dots}
+        />
+      </ReactFlow>
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/graph-preview/flowTheme.ts b/invokeai/frontend/webv2/src/workbench/graph-preview/flowTheme.ts
new file mode 100644
index 00000000000..4013aa234fb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/graph-preview/flowTheme.ts
@@ -0,0 +1,29 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+import type { WorkbenchThemeId } from '@workbench/types';
+
+import { THEMES_BY_ID } from '@theme/themes';
+
+/**
+ * Theme bridge for xyflow surfaces. xyflow's stylesheet only knows light/dark,
+ * so every flow renderer (workflow editor, graph preview) applies these
+ * Chakra-token-backed `--xy-*` override vars on its wrapper — they inherit
+ * into `.react-flow` and outrank the colorMode defaults. `--wb-flow-grid` is
+ * ours, consumed by `<Background color>` and preview handles.
+ */
+export const flowThemeCss: SystemStyleObject = {
+  '--wb-flow-grid': '{colors.fg.grid}',
+  '--xy-attribution-background-color': 'transparent',
+  '--xy-background-color': '{colors.bg}',
+  '--xy-connectionline-stroke': '{colors.accent.solid}',
+  '--xy-edge-stroke': '{colors.border.emphasized}',
+  '--xy-edge-stroke-selected': '{colors.accent.solid}',
+  '--xy-minimap-background-color': '{colors.bg.muted}',
+  '--xy-minimap-mask-background-color': '{colors.bg.inset/70}',
+  '--xy-minimap-mask-stroke-color': '{colors.border.subtle}',
+  '--xy-minimap-node-background-color': '{colors.bg.emphasized}',
+  '--xy-selection-background-color': '{colors.accent.solid/10}',
+  '--xy-selection-border': '1px dashed {colors.accent.solid}',
+};
+
+/** The xyflow color mode matching a workbench theme. */
+export const getFlowColorMode = (themeId: WorkbenchThemeId): 'light' | 'dark' => THEMES_BY_ID[themeId].colorScheme;
diff --git a/invokeai/frontend/webv2/src/workbench/graph-preview/index.ts b/invokeai/frontend/webv2/src/workbench/graph-preview/index.ts
new file mode 100644
index 00000000000..0c178971ffc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/graph-preview/index.ts
@@ -0,0 +1,4 @@
+export { FlowMiniMap } from './FlowMiniMap';
+export { flowThemeCss, getFlowColorMode } from './flowTheme';
+export { GraphPreviewDialog } from './GraphPreviewDialog';
+export { documentToPreviewGraph, GraphPreviewFlow } from './GraphPreviewFlow';
diff --git a/invokeai/frontend/webv2/src/workbench/graphSurfaces.ts b/invokeai/frontend/webv2/src/workbench/graphSurfaces.ts
new file mode 100644
index 00000000000..42d8821b676
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/graphSurfaces.ts
@@ -0,0 +1,26 @@
+import type { GraphBearingSurfaceContract, WidgetManifest, WorkbenchRegion } from './types';
+
+import { isInvocationSourceAvailable } from './invocation';
+
+export const createGraphBearingSurface = (
+  manifest: WidgetManifest,
+  region: WorkbenchRegion,
+  label: string
+): GraphBearingSurfaceContract | null => {
+  const graphBearing = manifest.graphBearing;
+
+  if (!graphBearing || !graphBearing.surfaces.includes(region)) {
+    return null;
+  }
+
+  return {
+    canPreviewGraph: true,
+    canSetSource: isInvocationSourceAvailable(graphBearing.sourceId),
+    graphId: graphBearing.defaultGraphId,
+    label,
+    region,
+    sourceId: graphBearing.sourceId,
+    surfaceId: `${manifest.id}:${region}`,
+    widgetId: manifest.id,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/WorkbenchHotkeyRuntime.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/WorkbenchHotkeyRuntime.test.ts
new file mode 100644
index 00000000000..27887cfe17f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/WorkbenchHotkeyRuntime.test.ts
@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { HotkeyContext, RegisteredHotkey } from './types';
+
+import { resolveHotkey } from './resolve';
+import { getHotkeyExecutionSource, shouldPreventHotkeyDefault } from './WorkbenchHotkeyRuntime';
+
+const source = { instanceId: 'alpha', projectId: 'project-1', region: 'right', typeId: 'test-widget' } as const;
+const activeSource = { instanceId: 'beta', projectId: 'project-1', region: 'left', typeId: 'other-widget' } as const;
+
+const createHotkey = (overrides: Partial<RegisteredHotkey>): RegisteredHotkey => ({
+  category: 'app',
+  commandId: 'test.command',
+  defaultKeys: ['x'],
+  id: 'test.hotkey',
+  keys: ['x'],
+  scope: { kind: 'global' },
+  title: 'Test hotkey',
+  ...overrides,
+});
+
+describe('getHotkeyExecutionSource', () => {
+  it('does not let source-less global hotkeys execute against the focused widget source', () => {
+    expect(getHotkeyExecutionSource(createHotkey({}), activeSource)).toBeNull();
+  });
+
+  it('uses the registering source for sourced global hotkeys', () => {
+    expect(getHotkeyExecutionSource(createHotkey({ source }), activeSource)).toBe(source);
+  });
+
+  it('uses the focused source for widget-scoped hotkeys', () => {
+    expect(
+      getHotkeyExecutionSource(createHotkey({ scope: { kind: 'widget', typeId: 'test-widget' }, source }), activeSource)
+    ).toBe(activeSource);
+  });
+});
+
+describe('shouldPreventHotkeyDefault', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('prevents the browser default for a matched binding with no explicit preventDefault', () => {
+    // Regression: widget hotkeys (e.g. canvas `mod+d`) are registered without a
+    // `preventDefault` flag; a claimed binding must still swallow the browser
+    // default (mod+d used to open the bookmark dialog).
+    expect(shouldPreventHotkeyDefault(createHotkey({}))).toBe(true);
+  });
+
+  it('honours an explicit opt-out with preventDefault: false', () => {
+    expect(shouldPreventHotkeyDefault(createHotkey({ preventDefault: false }))).toBe(false);
+  });
+
+  it('does not prevent the default when no binding claimed the event', () => {
+    expect(shouldPreventHotkeyDefault(null)).toBe(false);
+  });
+
+  it('prevents the default for a matched-and-run widget binding, but not when skipped by an editable target', () => {
+    class FakeHTMLElement {
+      closest(): FakeHTMLElement {
+        return this;
+      }
+    }
+    vi.stubGlobal('HTMLElement', FakeHTMLElement);
+
+    // A canvas-scoped binding claimed by an active canvas widget, registered
+    // without an explicit preventDefault (like the real widget registrations).
+    const canvasDeselect: RegisteredHotkey = createHotkey({
+      allowInEditable: false,
+      commandId: 'canvas.deselect',
+      id: 'canvas.deselect',
+      keys: ['mod+d'],
+      preventDefault: undefined,
+      scope: { kind: 'widget', typeId: 'canvas' },
+    });
+    const context: HotkeyContext = {
+      activeInstanceId: 'canvas',
+      activeWidgetTypeId: 'canvas',
+      focusedRegion: null,
+      isModalLayerActive: false,
+      projectId: 'project-1',
+    };
+
+    // Non-editable target: the binding resolves and must prevent the default.
+    const matched = resolveHotkey({
+      context,
+      event: { target: null } as KeyboardEvent,
+      hotkeys: [canvasDeselect],
+      matchedKey: 'mod+d',
+    });
+    expect(matched?.commandId).toBe('canvas.deselect');
+    expect(shouldPreventHotkeyDefault(matched)).toBe(true);
+
+    // Editable target: the binding is skipped (allowInEditable: false) so the
+    // event is left alone and the browser default is untouched.
+    const skipped = resolveHotkey({
+      context,
+      event: { target: new FakeHTMLElement() } as unknown as KeyboardEvent,
+      hotkeys: [canvasDeselect],
+      matchedKey: 'mod+d',
+    });
+    expect(skipped).toBeNull();
+    expect(shouldPreventHotkeyDefault(skipped)).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/WorkbenchHotkeyRuntime.tsx b/invokeai/frontend/webv2/src/workbench/hotkeys/WorkbenchHotkeyRuntime.tsx
new file mode 100644
index 00000000000..fc927e5aa43
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/WorkbenchHotkeyRuntime.tsx
@@ -0,0 +1,133 @@
+/* eslint-disable react/react-compiler */
+import type { WidgetContributionSource } from '@workbench/types';
+
+import { commandApi } from '@workbench/extensions/extensionApi';
+import { getFocusedRegionSnapshot } from '@workbench/focusRegions';
+import { useWorkbenchPreferenceSelector } from '@workbench/settings/store';
+import { areWidgetPlacementProjectsEqual, getWidgetPlacementProject } from '@workbench/widgetPlacementMeta';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useEffect, useEffectEvent, useMemo } from 'react';
+import { tinykeys } from 'tinykeys';
+
+import type { RegisteredHotkey } from './types';
+
+import { firstPartyHotkeyCatalog } from './catalog';
+import { useExtensionHotkeyDefinitions } from './extensionHotkeys';
+import { useRegisterFirstPartyCommands } from './firstPartyCommands';
+import { toTinykeysBinding } from './keys';
+import { useIsHotkeyModalLayerActive } from './modalLayer';
+import { applyCustomHotkeys, resolveHotkey } from './resolve';
+import { getHotkeyTargetWidget } from './targetWidget';
+
+export const getHotkeyExecutionSource = (
+  hotkey: Pick<RegisteredHotkey, 'scope' | 'source'>,
+  activeSource: WidgetContributionSource | null
+): WidgetContributionSource | null => (hotkey.scope.kind === 'global' ? (hotkey.source ?? null) : activeSource);
+
+/**
+ * Whether the browser default should be suppressed for a resolved hotkey.
+ *
+ * `resolveHotkey` only returns a hotkey once it has *claimed* the event — the
+ * scope is active and it is not skipped by the editable-target/modal-layer
+ * rules — so a matched-and-run binding must swallow the browser default (e.g.
+ * `mod+d` opening the bookmark dialog). Prevention is therefore on by default;
+ * a binding opts out only by explicitly setting `preventDefault: false`. A
+ * `null` hotkey (no binding claimed the event) never prevents the default.
+ */
+export const shouldPreventHotkeyDefault = (hotkey: RegisteredHotkey | null): boolean =>
+  hotkey !== null && hotkey.preventDefault !== false;
+
+export const WorkbenchHotkeyRuntime = () => {
+  useRegisterFirstPartyCommands();
+
+  const customHotkeys = useWorkbenchPreferenceSelector((preferences) => preferences.customHotkeys);
+  const project = useActiveProjectSelector(getWidgetPlacementProject, areWidgetPlacementProjectsEqual);
+  const extensionHotkeys = useExtensionHotkeyDefinitions();
+  const isModalLayerActive = useIsHotkeyModalLayerActive();
+
+  const registeredHotkeys = useMemo(() => {
+    const firstPartyHotkeys = firstPartyHotkeyCatalog.map((hotkey) => applyCustomHotkeys(hotkey, customHotkeys));
+    const widgetHotkeys = extensionHotkeys.map((hotkey) => applyCustomHotkeys(hotkey, customHotkeys));
+
+    return [...firstPartyHotkeys, ...widgetHotkeys];
+  }, [customHotkeys, extensionHotkeys]);
+
+  const executeHotkey = useEffectEvent((hotkey: RegisteredHotkey, source: WidgetContributionSource | null) => {
+    void commandApi.executeForSource(hotkey.commandId, getHotkeyExecutionSource(hotkey, source));
+  });
+
+  const handleHotkey = useEffectEvent((event: KeyboardEvent, matchedKey: string) => {
+    if (event.isComposing || event.keyCode === 229) {
+      return;
+    }
+
+    const focusedRegion = getFocusedRegionSnapshot();
+    const targetWidget = getHotkeyTargetWidget(event.target);
+    const activeRegion = focusedRegion ? project.widgetRegions[focusedRegion] : null;
+    const activeInstanceId = targetWidget?.instanceId ?? activeRegion?.activeInstanceId ?? null;
+    const activeWidgetTypeId = activeInstanceId
+      ? (targetWidget?.typeId ?? project.widgetInstances[activeInstanceId]?.typeId ?? null)
+      : null;
+    const commandSource: WidgetContributionSource | null =
+      activeInstanceId && activeWidgetTypeId && (targetWidget?.region || focusedRegion)
+        ? {
+            instanceId: activeInstanceId,
+            projectId: project.projectId ?? '',
+            region: (targetWidget?.region ?? focusedRegion)!,
+            typeId: activeWidgetTypeId,
+          }
+        : null;
+    const hotkey = resolveHotkey({
+      context: {
+        activeInstanceId,
+        activeWidgetTypeId,
+        focusedRegion,
+        isModalLayerActive,
+        projectId: project.projectId ?? '',
+      },
+      event,
+      hotkeys: registeredHotkeys,
+      matchedKey,
+    });
+
+    if (!hotkey) {
+      return;
+    }
+
+    if (shouldPreventHotkeyDefault(hotkey)) {
+      event.preventDefault();
+    }
+
+    executeHotkey(hotkey, commandSource);
+  });
+
+  const keybindings = useMemo(() => {
+    const bindings: Record<string, (event: KeyboardEvent) => void> = {};
+
+    for (const hotkey of registeredHotkeys) {
+      if (hotkey.implemented === false) {
+        continue;
+      }
+
+      for (const key of hotkey.keys) {
+        const tinykeysBinding = toTinykeysBinding(key);
+
+        if (tinykeysBinding) {
+          bindings[tinykeysBinding] = (event) => handleHotkey(event, key);
+        }
+      }
+    }
+
+    return bindings;
+  }, [registeredHotkeys]);
+
+  useEffect(() => {
+    if (Object.keys(keybindings).length === 0) {
+      return;
+    }
+
+    return tinykeys(window, keybindings, { ignore: () => false });
+  }, [keybindings]);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/catalog.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/catalog.test.ts
new file mode 100644
index 00000000000..c84eccc581a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/catalog.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { firstPartyHotkeyCatalog } from './catalog';
+
+describe('firstPartyHotkeyCatalog', () => {
+  it('keeps legacy default hotkey parity', () => {
+    // 91 legacy-parity entries + `canvas.newSession` (webv2 new-canvas command,
+    // no default keys — Task 46).
+    expect(firstPartyHotkeyCatalog).toHaveLength(92);
+    expect(firstPartyHotkeyCatalog.map((hotkey) => hotkey.id)).toContain('app.invoke');
+    expect(firstPartyHotkeyCatalog.map((hotkey) => hotkey.id)).toContain('canvas.mergeDown');
+    expect(firstPartyHotkeyCatalog.map((hotkey) => hotkey.id)).toContain('canvas.newSession');
+    expect(firstPartyHotkeyCatalog.map((hotkey) => hotkey.id)).toContain('workflows.copySelection');
+    expect(firstPartyHotkeyCatalog.map((hotkey) => hotkey.id)).toContain('gallery.galleryNavLeft');
+    expect(firstPartyHotkeyCatalog.map((hotkey) => hotkey.id)).toContain('gallery.remix');
+    expect(firstPartyHotkeyCatalog.map((hotkey) => hotkey.id)).toContain('viewer.deleteImage');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/catalog.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/catalog.ts
new file mode 100644
index 00000000000..8cce9b18785
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/catalog.ts
@@ -0,0 +1,199 @@
+import type { HotkeyCategory, HotkeyDefinition } from './types';
+
+const categoryScopes = {
+  app: { kind: 'global' },
+  canvas: { kind: 'widget', typeId: 'canvas' },
+  gallery: { kind: 'widget', typeId: 'gallery' },
+  viewer: { kind: 'widget', typeId: 'preview' },
+  workflows: { kind: 'widget', typeId: 'workflow' },
+} as const;
+
+const implemented = new Set([
+  'app.cancelQueueItem',
+  'app.clearQueue',
+  'app.focusPrompt',
+  'app.invoke',
+  'app.invokeFront',
+  'app.promptHistoryNext',
+  'app.promptHistoryPrev',
+  'app.promptWeightDown',
+  'app.promptWeightUp',
+  'app.resetPanelLayout',
+  'app.selectCanvasTab',
+  'app.selectGenerateTab',
+  'app.selectModelsTab',
+  'app.selectQueueTab',
+  'app.selectWorkflowsTab',
+  'app.toggleLeftPanel',
+  'app.togglePanels',
+  'app.toggleRightPanel',
+  'canvas.deleteSelected',
+  'canvas.fitBboxToLayers',
+  'canvas.fitBboxToMasks',
+  'canvas.newSession',
+  'canvas.nextEntity',
+  'canvas.prevEntity',
+  'canvas.redo',
+  'canvas.undo',
+  'gallery.clearSelection',
+  'gallery.deleteSelection',
+  'gallery.galleryNavDown',
+  'gallery.galleryNavDownAlt',
+  'gallery.galleryNavLeft',
+  'gallery.galleryNavLeftAlt',
+  'gallery.galleryNavRight',
+  'gallery.galleryNavRightAlt',
+  'gallery.galleryNavUp',
+  'gallery.galleryNavUpAlt',
+  'gallery.remix',
+  'gallery.selectAllOnPage',
+  'gallery.starImage',
+  'viewer.nextComparisonMode',
+  'viewer.deleteImage',
+  'viewer.recallAll',
+  'viewer.recallPrompts',
+  'viewer.recallSeed',
+  'viewer.remix',
+  'viewer.swapImages',
+  'viewer.toggleViewer',
+  'viewer.useSize',
+  'workflows.addNode',
+  'workflows.copySelection',
+  'workflows.deleteSelection',
+  'workflows.pasteSelection',
+  'workflows.pasteSelectionWithEdges',
+  'workflows.redo',
+  'workflows.selectAll',
+  'workflows.undo',
+]);
+
+const editableAppHotkeys = new Set([
+  'app.focusPrompt',
+  'app.invoke',
+  'app.invokeFront',
+  'app.promptHistoryNext',
+  'app.promptHistoryPrev',
+  'app.promptWeightDown',
+  'app.promptWeightUp',
+]);
+
+const formatHotkeyTitle = (id: string): string =>
+  id
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+
+const hotkey = (category: HotkeyCategory, id: string, defaultKeys: string[]): HotkeyDefinition => {
+  const commandId = `${category}.${id}`;
+
+  return {
+    allowInEditable: editableAppHotkeys.has(commandId),
+    category,
+    commandId,
+    defaultKeys,
+    id: commandId,
+    implemented: implemented.has(commandId),
+    preventDefault: true,
+    scope: categoryScopes[category],
+    title: formatHotkeyTitle(id),
+  };
+};
+
+export const firstPartyHotkeyCatalog: HotkeyDefinition[] = [
+  hotkey('app', 'invoke', ['mod+enter']),
+  hotkey('app', 'invokeFront', ['mod+shift+enter']),
+  hotkey('app', 'cancelQueueItem', ['shift+x']),
+  hotkey('app', 'clearQueue', ['mod+shift+x']),
+  hotkey('app', 'selectGenerateTab', ['1']),
+  hotkey('app', 'selectCanvasTab', ['2']),
+  hotkey('app', 'selectUpscalingTab', ['3']),
+  hotkey('app', 'selectWorkflowsTab', ['4']),
+  hotkey('app', 'selectModelsTab', ['5']),
+  hotkey('app', 'selectQueueTab', ['6']),
+  hotkey('app', 'promptHistoryPrev', ['alt+arrowup']),
+  hotkey('app', 'promptHistoryNext', ['alt+arrowdown']),
+  hotkey('app', 'promptWeightUp', ['ctrl+arrowup']),
+  hotkey('app', 'promptWeightDown', ['ctrl+arrowdown']),
+  hotkey('app', 'focusPrompt', ['alt+a']),
+  hotkey('app', 'toggleLeftPanel', ['t', 'o']),
+  hotkey('app', 'toggleRightPanel', ['g']),
+  hotkey('app', 'resetPanelLayout', ['shift+r']),
+  hotkey('app', 'togglePanels', ['f']),
+  hotkey('canvas', 'selectBrushTool', ['b']),
+  hotkey('canvas', 'selectBboxTool', ['c']),
+  hotkey('canvas', 'decrementToolWidth', ['[']),
+  hotkey('canvas', 'incrementToolWidth', [']']),
+  hotkey('canvas', 'selectEraserTool', ['e']),
+  hotkey('canvas', 'selectMoveTool', ['v']),
+  hotkey('canvas', 'selectRectTool', ['u']),
+  hotkey('canvas', 'selectLassoTool', ['l']),
+  hotkey('canvas', 'selectViewTool', ['h']),
+  hotkey('canvas', 'selectColorPickerTool', ['i']),
+  hotkey('canvas', 'setFillColorsToDefault', ['d']),
+  hotkey('canvas', 'toggleFillColor', ['x']),
+  hotkey('canvas', 'fitLayersToCanvas', ['mod+0']),
+  hotkey('canvas', 'fitBboxToCanvas', ['mod+shift+0']),
+  hotkey('canvas', 'fitBboxToLayers', ['shift+n']),
+  hotkey('canvas', 'setZoomTo100Percent', ['mod+1']),
+  hotkey('canvas', 'setZoomTo200Percent', ['mod+2']),
+  hotkey('canvas', 'setZoomTo400Percent', ['mod+3']),
+  hotkey('canvas', 'setZoomTo800Percent', ['mod+4']),
+  hotkey('canvas', 'quickSwitch', ['q']),
+  hotkey('canvas', 'deleteSelected', ['delete', 'backspace']),
+  hotkey('canvas', 'resetSelected', ['shift+c']),
+  hotkey('canvas', 'mergeDown', ['mod+e']),
+  hotkey('canvas', 'mergeVisible', ['mod+shift+e']),
+  hotkey('canvas', 'transformSelected', ['shift+t']),
+  hotkey('canvas', 'filterSelected', ['shift+f']),
+  hotkey('canvas', 'invertMask', ['shift+v']),
+  hotkey('canvas', 'undo', ['mod+z']),
+  hotkey('canvas', 'redo', ['mod+shift+z', 'mod+y']),
+  hotkey('canvas', 'nextEntity', ['alt+]']),
+  hotkey('canvas', 'prevEntity', ['alt+[']),
+  hotkey('canvas', 'applyFilter', ['enter']),
+  hotkey('canvas', 'cancelFilter', ['esc']),
+  hotkey('canvas', 'applyTransform', ['enter']),
+  hotkey('canvas', 'cancelTransform', ['esc']),
+  hotkey('canvas', 'applySegmentAnything', ['enter']),
+  hotkey('canvas', 'cancelSegmentAnything', ['esc']),
+  hotkey('canvas', 'toggleNonRasterLayers', ['shift+h']),
+  hotkey('canvas', 'fitBboxToMasks', ['shift+b']),
+  hotkey('canvas', 'toggleBbox', ['shift+o']),
+  // New canvas session: no default keys — assignable via the hotkeys settings.
+  hotkey('canvas', 'newSession', []),
+  hotkey('workflows', 'addNode', ['shift+a', 'space']),
+  hotkey('workflows', 'copySelection', ['mod+c']),
+  hotkey('workflows', 'pasteSelection', ['mod+v']),
+  hotkey('workflows', 'pasteSelectionWithEdges', ['mod+shift+v']),
+  hotkey('workflows', 'selectAll', ['mod+a']),
+  hotkey('workflows', 'deleteSelection', ['delete', 'backspace']),
+  hotkey('workflows', 'undo', ['mod+z']),
+  hotkey('workflows', 'redo', ['mod+shift+z', 'mod+y']),
+  hotkey('viewer', 'toggleViewer', ['z']),
+  hotkey('viewer', 'swapImages', ['c']),
+  hotkey('viewer', 'nextComparisonMode', ['m']),
+  hotkey('viewer', 'deleteImage', ['delete', 'backspace']),
+  hotkey('viewer', 'loadWorkflow', ['w']),
+  hotkey('viewer', 'recallAll', ['a']),
+  hotkey('viewer', 'recallSeed', ['s']),
+  hotkey('viewer', 'recallPrompts', ['p']),
+  hotkey('viewer', 'remix', ['r']),
+  hotkey('viewer', 'useSize', ['d']),
+  hotkey('viewer', 'toggleMetadata', ['i']),
+  hotkey('gallery', 'selectAllOnPage', ['mod+a']),
+  hotkey('gallery', 'clearSelection', ['esc']),
+  hotkey('gallery', 'galleryNavUp', ['up']),
+  hotkey('gallery', 'galleryNavRight', ['right']),
+  hotkey('gallery', 'galleryNavDown', ['down']),
+  hotkey('gallery', 'galleryNavLeft', ['left']),
+  hotkey('gallery', 'galleryNavUpAlt', ['alt+up']),
+  hotkey('gallery', 'galleryNavRightAlt', ['alt+right']),
+  hotkey('gallery', 'galleryNavDownAlt', ['alt+down']),
+  hotkey('gallery', 'galleryNavLeftAlt', ['alt+left']),
+  hotkey('gallery', 'deleteSelection', ['delete', 'backspace']),
+  hotkey('gallery', 'remix', ['r']),
+  hotkey('gallery', 'starImage', ['.']),
+];
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/extensionHotkeys.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/extensionHotkeys.test.ts
new file mode 100644
index 00000000000..badaa42210d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/extensionHotkeys.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+
+import { toExtensionHotkeyDefinition } from './extensionHotkeys';
+
+describe('toExtensionHotkeyDefinition', () => {
+  it('preserves the registering widget source for command execution', () => {
+    const source = { instanceId: 'alpha', projectId: 'project-1', region: 'right', typeId: 'test-widget' } as const;
+
+    expect(
+      toExtensionHotkeyDefinition({
+        commandId: 'test.command',
+        defaultKeys: ['mod+x'],
+        id: 'test.hotkey',
+        scope: 'global',
+        source,
+        title: 'Test hotkey',
+      })
+    ).toMatchObject({ source });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/extensionHotkeys.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/extensionHotkeys.ts
new file mode 100644
index 00000000000..80e7ed5b446
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/extensionHotkeys.ts
@@ -0,0 +1,48 @@
+import type { WidgetHotkeyContribution, WidgetRegion, WorkbenchRegion } from '@workbench/types';
+
+import { extensionContributionStores } from '@workbench/extensions/extensionApi';
+import { useMemo } from 'react';
+
+import type { HotkeyDefinition } from './types';
+
+const widgetRegions = new Set<WorkbenchRegion>(['bottom', 'center', 'left', 'right']);
+
+const isWidgetRegion = (region: WorkbenchRegion | undefined): region is WidgetRegion =>
+  region !== undefined && widgetRegions.has(region);
+
+export const toExtensionHotkeyDefinition = (hotkey: WidgetHotkeyContribution): HotkeyDefinition | null => {
+  const source = hotkey.source;
+  const scope = hotkey.scope ?? 'widget';
+
+  if (scope === 'global') {
+    return { ...hotkey, category: 'app', implemented: true, scope: { kind: 'global' } };
+  }
+
+  if (scope === 'instance' && source) {
+    return {
+      ...hotkey,
+      category: 'app',
+      implemented: true,
+      scope: { instanceId: source.instanceId, kind: 'instance' },
+    };
+  }
+
+  if (scope === 'focused-region' && isWidgetRegion(source?.region)) {
+    return { ...hotkey, category: 'app', implemented: true, scope: { kind: 'focused-region', region: source.region } };
+  }
+
+  if (source) {
+    return { ...hotkey, category: 'app', implemented: true, scope: { kind: 'widget', typeId: source.typeId } };
+  }
+
+  return null;
+};
+
+export const useExtensionHotkeyDefinitions = (): HotkeyDefinition[] => {
+  const hotkeys = extensionContributionStores.hotkeys.useList();
+
+  return useMemo(
+    () => hotkeys.map(toExtensionHotkeyDefinition).filter((hotkey): hotkey is HotkeyDefinition => hotkey !== null),
+    [hotkeys]
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/firstPartyCommands.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/firstPartyCommands.test.ts
new file mode 100644
index 00000000000..215ad7989d2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/firstPartyCommands.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { firstPartyHotkeyCatalog } from './catalog';
+import {
+  FIRST_PARTY_APP_COMMAND_IDS,
+  FIRST_PARTY_COMMAND_IDS,
+  FIRST_PARTY_IMAGE_RECALL_COMMAND_IDS,
+} from './firstPartyCommands';
+
+const centrallyOwnedCommandIds = new Set(FIRST_PARTY_COMMAND_IDS);
+
+describe('first-party hotkey commands', () => {
+  it('registers handlers for implemented app and shared image recall commands', () => {
+    const sharedImageRecallCommands = new Set([
+      'gallery.remix',
+      'viewer.recallAll',
+      'viewer.recallPrompts',
+      'viewer.recallSeed',
+      'viewer.remix',
+      'viewer.useSize',
+    ]);
+    const expectedCentralCommands = new Set(
+      firstPartyHotkeyCatalog
+        .filter((hotkey) => hotkey.implemented !== false)
+        .filter((hotkey) => hotkey.category === 'app' || sharedImageRecallCommands.has(hotkey.commandId))
+        .map((hotkey) => hotkey.commandId)
+    );
+
+    expect(centrallyOwnedCommandIds).toEqual(expectedCentralCommands);
+    expect(new Set(FIRST_PARTY_COMMAND_IDS).size).toBe(FIRST_PARTY_COMMAND_IDS.length);
+    expect(new Set(FIRST_PARTY_APP_COMMAND_IDS).size).toBe(FIRST_PARTY_APP_COMMAND_IDS.length);
+    expect(new Set(FIRST_PARTY_IMAGE_RECALL_COMMAND_IDS).size).toBe(FIRST_PARTY_IMAGE_RECALL_COMMAND_IDS.length);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/firstPartyCommands.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/firstPartyCommands.ts
new file mode 100644
index 00000000000..ec5f3494d9e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/firstPartyCommands.ts
@@ -0,0 +1,294 @@
+import { getConnectionStatus } from '@workbench/backend/connectionStore';
+import { commandApi } from '@workbench/extensions/extensionApi';
+import { cancelCurrentQueueItem } from '@workbench/generation/api';
+import { executeImageRecall, getSelectedGalleryImage, type ImageRecallKind } from '@workbench/image-actions';
+import { isInvocationRouteValid, resolveInvocationRoute } from '@workbench/invocation';
+import { submitResolvedInvocation } from '@workbench/invocationSubmit';
+import { ensureModelsLoaded, useModelsSelector } from '@workbench/models/modelsStore';
+import { openWidgetPlacement } from '@workbench/widgetPlacementCommands';
+import { getWidgetsForRegion } from '@workbench/widgetRegistry';
+import { prepareCanvasInvocation } from '@workbench/widgets/canvas/invoke/prepareCanvasInvocation';
+import { flushGenerateDrafts } from '@workbench/widgets/generate/generateDraftRegistry';
+import { focusPositivePrompt } from '@workbench/widgets/generate/promptFields';
+import { adjustFocusedPromptAttention } from '@workbench/widgets/generate/promptFields/promptAttentionHotkeys';
+import { navigatePromptHistory } from '@workbench/widgets/generate/promptFields/promptHistoryNavigation';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useWorkbenchDispatch, useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import { useEffect, useEffectEvent, useRef } from 'react';
+
+const imageRecallCommands: Record<string, ImageRecallKind> = {
+  'gallery.remix': 'remix',
+  'viewer.recallAll': 'all',
+  'viewer.recallPrompts': 'prompts',
+  'viewer.recallSeed': 'seed',
+  'viewer.remix': 'remix',
+  'viewer.useSize': 'dimensions',
+};
+
+export const FIRST_PARTY_APP_COMMAND_IDS = [
+  'app.invoke',
+  'app.invokeFront',
+  'app.cancelQueueItem',
+  'app.clearQueue',
+  'app.selectGenerateTab',
+  'app.selectCanvasTab',
+  'app.selectWorkflowsTab',
+  'app.selectModelsTab',
+  'app.selectQueueTab',
+  'app.promptHistoryPrev',
+  'app.promptHistoryNext',
+  'app.promptWeightUp',
+  'app.promptWeightDown',
+  'app.focusPrompt',
+  'app.toggleLeftPanel',
+  'app.toggleRightPanel',
+  'app.resetPanelLayout',
+  'app.togglePanels',
+] as const;
+
+export const FIRST_PARTY_IMAGE_RECALL_COMMAND_IDS = Object.keys(imageRecallCommands);
+
+export const FIRST_PARTY_COMMAND_IDS = [...FIRST_PARTY_APP_COMMAND_IDS, ...Object.keys(imageRecallCommands)] as const;
+
+export const useRegisterFirstPartyCommands = () => {
+  const store = useWorkbenchStore();
+  const dispatch = useWorkbenchDispatch();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const modelsStatus = useModelsSelector((snapshot) => snapshot.status);
+  const availabilityModels = modelsStatus === 'loaded' ? models : undefined;
+  const projectRef = useRef(store.getSnapshot().activeProject);
+  const modelsRef = useRef(availabilityModels);
+
+  useInvocationTemplatesSelector((snapshot) => snapshot.status);
+
+  useEffect(() => {
+    modelsRef.current = availabilityModels;
+  }, [availabilityModels]);
+
+  useEffect(
+    () =>
+      store.subscribe(() => {
+        projectRef.current = store.getSnapshot().activeProject;
+      }),
+    [store]
+  );
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  const submitInvocation = useEffectEvent(() => {
+    flushGenerateDrafts();
+
+    const activeProject = projectRef.current;
+    const resolvedRoute = resolveInvocationRoute(activeProject, 'global', activeProject.invocation, modelsRef.current);
+    const { status } = getConnectionStatus();
+
+    if (!isInvocationRouteValid(resolvedRoute) || status !== 'connected') {
+      return;
+    }
+
+    submitResolvedInvocation({
+      dispatch,
+      models: modelsRef.current,
+      prepareCanvasInvocation,
+      project: activeProject,
+      route: resolvedRoute,
+    });
+  });
+
+  const recallSelectedImage = useEffectEvent(async (kind: ImageRecallKind) => {
+    const activeProject = projectRef.current;
+    const image = getSelectedGalleryImage(activeProject);
+
+    if (!image) {
+      dispatch({
+        kind: 'info',
+        message: 'Select an image in Gallery or Preview first.',
+        title: 'No image selected',
+        type: 'recordNotice',
+      });
+      return;
+    }
+
+    const didRecall = await executeImageRecall({
+      dispatch,
+      generateValues: getProjectWidgetValues(activeProject, 'generate'),
+      image,
+      kind,
+      models: modelsRef.current ?? [],
+      projectId: activeProject.id,
+    });
+
+    if (didRecall && store.getSnapshot().activeProject.id === activeProject.id) {
+      openWidgetPlacement({
+        dispatch,
+        getWidgetsForRegion,
+        options: { preferredRegions: ['left'] },
+        typeId: 'generate',
+      });
+    }
+  });
+
+  useEffect(() => {
+    const disposers = [
+      commandApi.register({ handler: submitInvocation, id: 'app.invoke', title: 'Invoke' }),
+      commandApi.register({ handler: submitInvocation, id: 'app.invokeFront', title: 'Invoke front' }),
+      commandApi.register({
+        handler: () => void cancelCurrentQueueItem().finally(() => dispatch({ type: 'refreshBackendData' })),
+        id: 'app.cancelQueueItem',
+        title: 'Cancel current queue item',
+      }),
+      commandApi.register({
+        handler: () => dispatch({ projectId: projectRef.current.id, type: 'cancelAllQueueItems' }),
+        id: 'app.clearQueue',
+        title: 'Clear queue',
+      }),
+      commandApi.register({
+        handler: () =>
+          openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { preferredRegions: ['left'] },
+            typeId: 'generate',
+          }),
+        id: 'app.selectGenerateTab',
+        title: 'Select Generate tab',
+      }),
+      commandApi.register({
+        handler: () =>
+          openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { preferredRegions: ['center'], requireCenterView: true },
+            typeId: 'canvas',
+          }),
+        id: 'app.selectCanvasTab',
+        title: 'Select Canvas tab',
+      }),
+      commandApi.register({
+        handler: () =>
+          openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { preferredRegions: ['center'], requireCenterView: true },
+            typeId: 'workflow',
+          }),
+        id: 'app.selectWorkflowsTab',
+        title: 'Select Workflows tab',
+      }),
+      commandApi.register({
+        handler: () => (window.location.hash = '#/models'),
+        id: 'app.selectModelsTab',
+        title: 'Select Models tab',
+      }),
+      commandApi.register({
+        handler: () =>
+          openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { preferredRegions: ['right', 'bottom'] },
+            typeId: 'queue',
+          }),
+        id: 'app.selectQueueTab',
+        title: 'Select Queue tab',
+      }),
+      commandApi.register({
+        handler: () => {
+          openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { preferredRegions: ['left'] },
+            typeId: 'generate',
+          });
+          window.requestAnimationFrame(() => focusPositivePrompt());
+        },
+        id: 'app.focusPrompt',
+        title: 'Focus prompt',
+      }),
+      commandApi.register({
+        handler: () => {
+          flushGenerateDrafts();
+
+          navigatePromptHistory({
+            direction: -1,
+            dispatch,
+            models: modelsRef.current,
+            project: projectRef.current,
+          });
+        },
+        id: 'app.promptHistoryPrev',
+        title: 'Previous prompt history item',
+      }),
+      commandApi.register({
+        handler: () => {
+          flushGenerateDrafts();
+
+          navigatePromptHistory({
+            direction: 1,
+            dispatch,
+            models: modelsRef.current,
+            project: projectRef.current,
+          });
+        },
+        id: 'app.promptHistoryNext',
+        title: 'Next prompt history item',
+      }),
+      commandApi.register({
+        handler: () =>
+          adjustFocusedPromptAttention('increment', projectRef.current.settings.preferNumericAttentionStyle),
+        id: 'app.promptWeightUp',
+        title: 'Increase prompt weight',
+      }),
+      commandApi.register({
+        handler: () =>
+          adjustFocusedPromptAttention('decrement', projectRef.current.settings.preferNumericAttentionStyle),
+        id: 'app.promptWeightDown',
+        title: 'Decrease prompt weight',
+      }),
+      commandApi.register({
+        handler: () => {
+          const region = projectRef.current.widgetRegions.left;
+
+          dispatch({ isCollapsed: !region.isCollapsed, region: 'left', type: 'setRegionWidgetCollapsed' });
+        },
+        id: 'app.toggleLeftPanel',
+        title: 'Toggle left panel',
+      }),
+      commandApi.register({
+        handler: () => {
+          const region = projectRef.current.widgetRegions.right;
+
+          dispatch({ isCollapsed: !region.isCollapsed, region: 'right', type: 'setRegionWidgetCollapsed' });
+        },
+        id: 'app.toggleRightPanel',
+        title: 'Toggle right panel',
+      }),
+      commandApi.register({
+        handler: () => dispatch({ type: 'resetActiveLayout' }),
+        id: 'app.resetPanelLayout',
+        title: 'Reset panel layout',
+      }),
+      commandApi.register({
+        handler: () => {
+          const { bottom, left, right } = projectRef.current.widgetRegions;
+          const shouldCollapse = !left.isCollapsed || !right.isCollapsed || !bottom.isCollapsed;
+
+          dispatch({ isCollapsed: shouldCollapse, region: 'left', type: 'setRegionWidgetCollapsed' });
+          dispatch({ isCollapsed: shouldCollapse, region: 'right', type: 'setRegionWidgetCollapsed' });
+          dispatch({ isCollapsed: shouldCollapse, region: 'bottom', type: 'setRegionWidgetCollapsed' });
+        },
+        id: 'app.togglePanels',
+        title: 'Toggle panels',
+      }),
+      ...Object.entries(imageRecallCommands).map(([id, kind]) =>
+        commandApi.register({ handler: () => recallSelectedImage(kind), id, title: id })
+      ),
+    ];
+
+    return () => {
+      disposers.forEach((dispose) => dispose());
+    };
+  }, [dispatch]);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/index.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/index.ts
new file mode 100644
index 00000000000..7153873171d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/index.ts
@@ -0,0 +1,7 @@
+export * from './catalog';
+export * from './extensionHotkeys';
+export * from './keys';
+export * from './modalLayer';
+export * from './resolve';
+export * from './targetWidget';
+export * from './types';
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/keys.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/keys.test.ts
new file mode 100644
index 00000000000..abfcfc07c41
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/keys.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { eventToHotkeyString, normalizeHotkeyString, toTinykeysBinding } from './keys';
+
+describe('hotkey keys', () => {
+  it('normalizes modifier order and aliases', () => {
+    expect(normalizeHotkeyString('Shift+Mod+Enter')).toBe('mod+shift+enter');
+    expect(normalizeHotkeyString('escape')).toBe('esc');
+    expect(normalizeHotkeyString('Alt+ArrowUp')).toBe('alt+arrowup');
+  });
+
+  it('converts normalized keys to tinykeys syntax', () => {
+    expect(toTinykeysBinding('mod+enter')).toBe('$mod+Enter');
+    expect(toTinykeysBinding('alt+]')).toBe('Alt+BracketRight');
+    expect(toTinykeysBinding('.')).toBe('Period');
+  });
+
+  it('ignores IME composition events when recording hotkeys', () => {
+    expect(eventToHotkeyString({ isComposing: true, key: 'a' } as KeyboardEvent)).toBe('');
+    expect(eventToHotkeyString({ key: 'Process', keyCode: 229 } as KeyboardEvent)).toBe('');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/keys.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/keys.ts
new file mode 100644
index 00000000000..e74b9ad6d18
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/keys.ts
@@ -0,0 +1,109 @@
+const MODIFIER_ORDER = ['mod', 'ctrl', 'meta', 'shift', 'alt'] as const;
+
+const KEY_ALIASES: Record<string, string> = {
+  ' ': 'space',
+  arrowdown: 'arrowdown',
+  arrowleft: 'arrowleft',
+  arrowright: 'arrowright',
+  arrowup: 'arrowup',
+  del: 'delete',
+  escape: 'esc',
+  return: 'enter',
+};
+
+const TINY_KEY_ALIASES: Record<string, string> = {
+  '[': 'BracketLeft',
+  ']': 'BracketRight',
+  '.': 'Period',
+  ',': 'Comma',
+  '/': 'Slash',
+  '\\': 'Backslash',
+  '-': 'Minus',
+  '=': 'Equal',
+  arrowdown: 'ArrowDown',
+  arrowleft: 'ArrowLeft',
+  arrowright: 'ArrowRight',
+  arrowup: 'ArrowUp',
+  backspace: 'Backspace',
+  delete: 'Delete',
+  enter: 'Enter',
+  esc: 'Escape',
+  space: 'Space',
+};
+
+const TINY_MODIFIER_ALIASES: Record<string, string> = {
+  alt: 'Alt',
+  ctrl: 'Control',
+  meta: 'Meta',
+  mod: '$mod',
+  shift: 'Shift',
+};
+
+export const IS_MAC_OS =
+  typeof navigator !== 'undefined' &&
+  (
+    (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform ??
+    navigator.platform ??
+    ''
+  )
+    .toLowerCase()
+    .includes('mac');
+
+export const normalizeHotkeyString = (hotkey: string): string => {
+  const parts = hotkey
+    .split('+')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean)
+    .map((part) => KEY_ALIASES[part] ?? part);
+  const modifiers = parts
+    .filter((part) => MODIFIER_ORDER.includes(part as (typeof MODIFIER_ORDER)[number]))
+    .sort((left, right) => MODIFIER_ORDER.indexOf(left as never) - MODIFIER_ORDER.indexOf(right as never));
+  const key = parts.find((part) => !MODIFIER_ORDER.includes(part as (typeof MODIFIER_ORDER)[number]));
+
+  return key ? [...modifiers, key].join('+') : '';
+};
+
+export const eventToHotkeyString = (event: KeyboardEvent): string => {
+  if (event.isComposing || event.keyCode === 229 || ['Alt', 'Control', 'Meta', 'Shift'].includes(event.key)) {
+    return '';
+  }
+
+  const modifiers: string[] = [];
+
+  if (event.metaKey || event.ctrlKey) {
+    modifiers.push(IS_MAC_OS ? (event.metaKey ? 'mod' : 'ctrl') : event.ctrlKey ? 'mod' : 'meta');
+  }
+  if (event.shiftKey) {
+    modifiers.push('shift');
+  }
+  if (event.altKey) {
+    modifiers.push('alt');
+  }
+
+  return normalizeHotkeyString([...modifiers, event.key].join('+'));
+};
+
+export const toTinykeysBinding = (hotkey: string): string => {
+  const normalized = normalizeHotkeyString(hotkey);
+  const parts = normalized.split('+').filter(Boolean);
+
+  return parts.map((part) => TINY_MODIFIER_ALIASES[part] ?? TINY_KEY_ALIASES[part] ?? part).join('+');
+};
+
+export const formatHotkeyForPlatform = (hotkey: string): string[] =>
+  normalizeHotkeyString(hotkey)
+    .split('+')
+    .filter(Boolean)
+    .map((part) => (IS_MAC_OS ? part.replace('mod', 'cmd').replace('alt', 'option') : part.replace('mod', 'ctrl')));
+
+export const isEditableHotkeyTarget = (target: EventTarget | null): boolean => {
+  if (typeof HTMLElement === 'undefined') {
+    return false;
+  }
+
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+
+  return Boolean(target.closest('input, textarea, select, [contenteditable="true"]'));
+};
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/modalLayer.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/modalLayer.test.ts
new file mode 100644
index 00000000000..1a780a7809e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/modalLayer.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { isHotkeyModalLayerActive, registerHotkeyModalLayer } from './modalLayer';
+
+describe('hotkey modal layer registry', () => {
+  it('is active only while a registered layer is mounted', () => {
+    expect(isHotkeyModalLayerActive()).toBe(false);
+
+    const unregister = registerHotkeyModalLayer('settings');
+
+    expect(isHotkeyModalLayerActive()).toBe(true);
+
+    unregister();
+
+    expect(isHotkeyModalLayerActive()).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/modalLayer.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/modalLayer.ts
new file mode 100644
index 00000000000..600bde0bd77
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/modalLayer.ts
@@ -0,0 +1,19 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+const store = createExternalStore<{ activeLayerIds: ReadonlySet<string> }>({ activeLayerIds: new Set<string>() });
+
+export const registerHotkeyModalLayer = (id: string): (() => void) => {
+  store.patchSnapshot({ activeLayerIds: new Set([...store.getSnapshot().activeLayerIds, id]) });
+
+  return () => {
+    const activeLayerIds = new Set(store.getSnapshot().activeLayerIds);
+
+    activeLayerIds.delete(id);
+    store.patchSnapshot({ activeLayerIds });
+  };
+};
+
+export const isHotkeyModalLayerActive = (): boolean => store.getSnapshot().activeLayerIds.size > 0;
+
+export const useIsHotkeyModalLayerActive = (): boolean =>
+  store.useSelector((snapshot) => snapshot.activeLayerIds.size > 0);
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/resolve.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/resolve.test.ts
new file mode 100644
index 00000000000..b01b4a9ba0f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/resolve.test.ts
@@ -0,0 +1,209 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { RegisteredHotkey } from './types';
+
+import { applyCustomHotkeys, resolveHotkey } from './resolve';
+
+const event = { target: null } as KeyboardEvent;
+const context = {
+  activeInstanceId: null,
+  activeWidgetTypeId: null,
+  focusedRegion: null,
+  isModalLayerActive: false,
+  projectId: 'project-1',
+} as const;
+
+const base = {
+  category: 'app',
+  defaultKeys: ['x'] as string[],
+  implemented: true,
+  keys: ['x'] as string[],
+  preventDefault: true,
+} as const;
+
+describe('resolveHotkey', () => {
+  it('prefers active widget over global', () => {
+    const globalHotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'global',
+      id: 'global',
+      scope: { kind: 'global' },
+      title: 'Global',
+    };
+    const widgetHotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'widget',
+      id: 'widget',
+      scope: { kind: 'widget', typeId: 'gallery' },
+      title: 'Widget',
+    };
+
+    expect(
+      resolveHotkey({
+        context: { ...context, activeInstanceId: 'gallery-1', activeWidgetTypeId: 'gallery', focusedRegion: 'left' },
+        event,
+        hotkeys: [globalHotkey, widgetHotkey],
+        matchedKey: 'x',
+      })?.commandId
+    ).toBe('widget');
+  });
+
+  it('prefers active instance over widget', () => {
+    const widgetHotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'widget',
+      id: 'widget',
+      scope: { kind: 'widget', typeId: 'gallery' },
+      title: 'Widget',
+    };
+    const instanceHotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'instance',
+      id: 'instance',
+      scope: { instanceId: 'gallery-1', kind: 'instance' },
+      title: 'Instance',
+    };
+
+    expect(
+      resolveHotkey({
+        context: { ...context, activeInstanceId: 'gallery-1', activeWidgetTypeId: 'gallery', focusedRegion: 'left' },
+        event,
+        hotkeys: [widgetHotkey, instanceHotkey],
+        matchedKey: 'x',
+      })?.commandId
+    ).toBe('instance');
+  });
+
+  it('resolves by the matched canonical key instead of re-serializing the event', () => {
+    const hotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'symbol',
+      id: 'symbol',
+      keys: ['shift+1'],
+      scope: { kind: 'global' },
+      title: 'Symbol',
+    };
+
+    expect(
+      resolveHotkey({
+        context,
+        event: { ...event, key: '!' } as KeyboardEvent,
+        hotkeys: [hotkey],
+        matchedKey: 'shift+1',
+      })?.commandId
+    ).toBe('symbol');
+  });
+
+  it('does not match region-less focused-region hotkeys without a focused region', () => {
+    const globalHotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'global',
+      id: 'global',
+      scope: { kind: 'global' },
+      title: 'Global',
+    };
+    const focusedHotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'focused',
+      id: 'focused',
+      scope: { kind: 'focused-region' },
+      title: 'Focused',
+    };
+
+    expect(resolveHotkey({ context, event, hotkeys: [globalHotkey, focusedHotkey], matchedKey: 'x' })?.commandId).toBe(
+      'global'
+    );
+    expect(
+      resolveHotkey({
+        context: { ...context, focusedRegion: 'left' },
+        event,
+        hotkeys: [globalHotkey, focusedHotkey],
+        matchedKey: 'x',
+      })?.commandId
+    ).toBe('focused');
+  });
+
+  it('does not resolve hotkeys contributed by another project source', () => {
+    const staleProjectHotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'stale',
+      id: 'stale',
+      scope: { kind: 'widget', typeId: 'gallery' },
+      source: { instanceId: 'gallery-1', projectId: 'project-2', region: 'left', typeId: 'gallery' },
+      title: 'Stale project',
+    };
+
+    expect(
+      resolveHotkey({
+        context: { ...context, activeInstanceId: 'gallery-1', activeWidgetTypeId: 'gallery', focusedRegion: 'left' },
+        event,
+        hotkeys: [staleProjectHotkey],
+        matchedKey: 'x',
+      })
+    ).toBeNull();
+  });
+
+  it('suppresses editable targets unless allowed', () => {
+    class FakeHTMLElement {
+      closest(): FakeHTMLElement {
+        return this;
+      }
+    }
+    vi.stubGlobal('HTMLElement', FakeHTMLElement);
+    const input = new FakeHTMLElement();
+    const hotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'global',
+      id: 'global',
+      scope: { kind: 'global' },
+      title: 'Global',
+    };
+
+    expect(
+      resolveHotkey({
+        context,
+        event: { target: input } as unknown as KeyboardEvent,
+        hotkeys: [hotkey],
+        matchedKey: 'x',
+      })
+    ).toBeNull();
+  });
+
+  it('suppresses hotkeys while a modal layer is active unless allowed', () => {
+    const hotkey: RegisteredHotkey = {
+      ...base,
+      commandId: 'global',
+      id: 'global',
+      scope: { kind: 'global' },
+      title: 'Global',
+    };
+    const modalHotkey: RegisteredHotkey = {
+      ...hotkey,
+      allowInModal: true,
+      commandId: 'modal',
+      id: 'modal',
+      title: 'Modal',
+    };
+
+    expect(
+      resolveHotkey({
+        context: { ...context, isModalLayerActive: true },
+        event,
+        hotkeys: [hotkey],
+        matchedKey: 'x',
+      })
+    ).toBeNull();
+    expect(
+      resolveHotkey({
+        context: { ...context, isModalLayerActive: true },
+        event,
+        hotkeys: [hotkey, modalHotkey],
+        matchedKey: 'x',
+      })?.commandId
+    ).toBe('modal');
+  });
+
+  it('keeps an empty custom key array as a disabled hotkey', () => {
+    expect(applyCustomHotkeys({ defaultKeys: ['x'], id: 'app.invoke' }, { 'app.invoke': [] }).keys).toEqual([]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/resolve.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/resolve.ts
new file mode 100644
index 00000000000..c9395254774
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/resolve.ts
@@ -0,0 +1,58 @@
+import type { HotkeyContext, RegisteredHotkey } from './types';
+
+import { isEditableHotkeyTarget, normalizeHotkeyString } from './keys';
+
+const getScopePriority = (hotkey: RegisteredHotkey, context: HotkeyContext): number => {
+  const { scope } = hotkey;
+
+  if (hotkey.source && hotkey.source.projectId !== context.projectId) {
+    return -1;
+  }
+
+  if (scope.kind === 'instance') {
+    return scope.instanceId === context.activeInstanceId ? 400 : -1;
+  }
+
+  if (scope.kind === 'widget') {
+    return scope.typeId === context.activeWidgetTypeId ? 300 : -1;
+  }
+
+  if (scope.kind === 'focused-region') {
+    return context.focusedRegion && (!scope.region || scope.region === context.focusedRegion) ? 200 : -1;
+  }
+
+  return 100;
+};
+
+export const applyCustomHotkeys = <Hotkey extends { defaultKeys: string[]; id: string }>(
+  hotkey: Hotkey,
+  customHotkeys: Record<string, string[]>
+): Hotkey & { keys: string[] } => ({
+  ...hotkey,
+  keys: (customHotkeys[hotkey.id] ?? hotkey.defaultKeys).map(normalizeHotkeyString).filter(Boolean),
+});
+
+export const resolveHotkey = ({
+  context,
+  event,
+  hotkeys,
+  matchedKey,
+}: {
+  context: HotkeyContext;
+  event: KeyboardEvent;
+  hotkeys: RegisteredHotkey[];
+  matchedKey: string;
+}): RegisteredHotkey | null => {
+  const normalized = normalizeHotkeyString(matchedKey);
+  const isEditable = isEditableHotkeyTarget(event.target);
+
+  return (
+    hotkeys
+      .filter((hotkey) => hotkey.implemented !== false && hotkey.keys.includes(normalized))
+      .filter((hotkey) => hotkey.allowInEditable || !isEditable)
+      .filter((hotkey) => hotkey.allowInModal || !context.isModalLayerActive)
+      .map((hotkey) => ({ hotkey, priority: getScopePriority(hotkey, context) }))
+      .filter(({ priority }) => priority >= 0)
+      .sort((left, right) => right.priority - left.priority)[0]?.hotkey ?? null
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/targetWidget.test.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/targetWidget.test.ts
new file mode 100644
index 00000000000..a4b245fe7a4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/targetWidget.test.ts
@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { getHotkeyTargetWidget } from './targetWidget';
+
+class FakeElement {
+  constructor(private readonly attrs: Record<string, string> | null) {}
+
+  closest(): FakeElement | null {
+    return this.attrs ? this : null;
+  }
+
+  getAttribute(name: string): string | null {
+    return this.attrs?.[name] ?? null;
+  }
+}
+
+describe('getHotkeyTargetWidget', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('reads the nearest hotkey widget shell from the event target', () => {
+    vi.stubGlobal('Element', FakeElement);
+
+    expect(
+      getHotkeyTargetWidget(
+        new FakeElement({
+          'data-hotkey-widget-instance-id': 'preview',
+          'data-hotkey-widget-region': 'center',
+          'data-hotkey-widget-type-id': 'preview',
+        }) as unknown as EventTarget
+      )
+    ).toEqual({ instanceId: 'preview', region: 'center', typeId: 'preview' });
+  });
+
+  it('ignores targets outside widget shells', () => {
+    vi.stubGlobal('Element', FakeElement);
+
+    expect(getHotkeyTargetWidget(new FakeElement(null) as unknown as EventTarget)).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/targetWidget.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/targetWidget.ts
new file mode 100644
index 00000000000..ce201e64ba6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/targetWidget.ts
@@ -0,0 +1,18 @@
+import type { WidgetInstanceId, WidgetTypeId, WorkbenchRegion } from '@workbench/types';
+
+export const getHotkeyTargetWidget = (
+  target: EventTarget | null
+): { instanceId: WidgetInstanceId; region: WorkbenchRegion | null; typeId: WidgetTypeId } | null => {
+  if (!(target instanceof Element)) {
+    return null;
+  }
+
+  const widgetElement = target.closest('[data-hotkey-widget-instance-id][data-hotkey-widget-type-id]');
+  const instanceId = widgetElement?.getAttribute('data-hotkey-widget-instance-id');
+  const region = widgetElement?.getAttribute('data-hotkey-widget-region') ?? null;
+  const typeId = widgetElement?.getAttribute('data-hotkey-widget-type-id');
+
+  return instanceId && typeId
+    ? { instanceId, region: region as WorkbenchRegion | null, typeId: typeId as WidgetTypeId }
+    : null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/hotkeys/types.ts b/invokeai/frontend/webv2/src/workbench/hotkeys/types.ts
new file mode 100644
index 00000000000..3a586c98e2e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/hotkeys/types.ts
@@ -0,0 +1,39 @@
+import type { WidgetContributionSource, WidgetInstanceId, WidgetRegion, WidgetTypeId } from '@workbench/types';
+
+export type HotkeyCategory = 'app' | 'canvas' | 'gallery' | 'viewer' | 'workflows';
+
+export type HotkeyScope =
+  | { kind: 'global' }
+  | { kind: 'focused-region'; region?: WidgetRegion }
+  | { kind: 'widget'; typeId: WidgetTypeId }
+  | { kind: 'instance'; instanceId: WidgetInstanceId };
+
+export interface HotkeyDefinition {
+  id: string;
+  category: HotkeyCategory;
+  commandId: string;
+  defaultKeys: string[];
+  title: string;
+  description?: string;
+  scope: HotkeyScope;
+  preventDefault?: boolean;
+  allowInEditable?: boolean;
+  allowInModal?: boolean;
+  unavailableReason?: string;
+  implemented?: boolean;
+  source?: WidgetContributionSource;
+}
+
+export interface RegisteredHotkey extends HotkeyDefinition {
+  keys: string[];
+}
+
+export interface HotkeyContext {
+  focusedRegion: WidgetRegion | null;
+  activeInstanceId: WidgetInstanceId | null;
+  activeWidgetTypeId: WidgetTypeId | null;
+  isModalLayerActive: boolean;
+  projectId: string;
+}
+
+export type CustomHotkeys = Record<string, string[]>;
diff --git a/invokeai/frontend/webv2/src/workbench/i18n/I18nController.tsx b/invokeai/frontend/webv2/src/workbench/i18n/I18nController.tsx
new file mode 100644
index 00000000000..e6fca0ff90b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/i18n/I18nController.tsx
@@ -0,0 +1,36 @@
+import { useWorkbenchPreferenceSelector, useWorkbenchSettingsSelector } from '@workbench/settings/store';
+import { useLayoutEffect } from 'react';
+
+import i18n from '@/i18n';
+
+import { getWorkbenchLanguageDirection } from './languages';
+
+const LANGUAGE_HINT_STORAGE_KEY = 'invokeai:v7:webv2:language';
+
+export const I18nController = () => {
+  const language = useWorkbenchPreferenceSelector((preferences) => preferences.language);
+  const status = useWorkbenchSettingsSelector((snapshot) => snapshot.status);
+  const hasResolved = status === 'ready' || status === 'error';
+
+  useLayoutEffect(() => {
+    if (!hasResolved) {
+      return;
+    }
+
+    const direction = getWorkbenchLanguageDirection(language);
+    const root = document.documentElement;
+
+    root.lang = language;
+    root.dir = direction;
+    document.body.dir = direction;
+    void i18n.changeLanguage(language);
+
+    try {
+      window.localStorage.setItem(LANGUAGE_HINT_STORAGE_KEY, language);
+    } catch {
+      // Storage unavailable; the next load paints with the default language.
+    }
+  }, [hasResolved, language]);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/i18n/index.ts b/invokeai/frontend/webv2/src/workbench/i18n/index.ts
new file mode 100644
index 00000000000..4a9d71541ea
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/i18n/index.ts
@@ -0,0 +1,9 @@
+export { I18nController } from './I18nController';
+export {
+  getWorkbenchLanguageDirection,
+  normalizeWorkbenchLanguage,
+  WORKBENCH_LANGUAGE_OPTIONS,
+  WORKBENCH_LANGUAGES,
+  type WorkbenchLanguage,
+  type WorkbenchLanguageDirection,
+} from './languages';
diff --git a/invokeai/frontend/webv2/src/workbench/i18n/languages.ts b/invokeai/frontend/webv2/src/workbench/i18n/languages.ts
new file mode 100644
index 00000000000..90c7a41af88
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/i18n/languages.ts
@@ -0,0 +1,47 @@
+export const WORKBENCH_LANGUAGE_OPTIONS = [
+  { value: 'ar', label: 'العربية', direction: 'rtl' },
+  { value: 'az', label: 'Azərbaycan dili', direction: 'ltr' },
+  { value: 'bg', label: 'Български', direction: 'ltr' },
+  { value: 'de', label: 'Deutsch', direction: 'ltr' },
+  { value: 'en', label: 'English', direction: 'ltr' },
+  { value: 'en-GB', label: 'English (UK)', direction: 'ltr' },
+  { value: 'es', label: 'Español', direction: 'ltr' },
+  { value: 'fi', label: 'Suomi', direction: 'ltr' },
+  { value: 'fr', label: 'Français', direction: 'ltr' },
+  { value: 'he', label: 'עִבְֿרִית', direction: 'rtl' },
+  { value: 'hu', label: 'Magyar Nyelv', direction: 'ltr' },
+  { value: 'it', label: 'Italiano', direction: 'ltr' },
+  { value: 'ja', label: '日本語', direction: 'ltr' },
+  { value: 'ko', label: '한국어', direction: 'ltr' },
+  { value: 'mn', label: 'Монгол', direction: 'ltr' },
+  { value: 'nl', label: 'Nederlands', direction: 'ltr' },
+  { value: 'pl', label: 'Polski', direction: 'ltr' },
+  { value: 'pt', label: 'Português', direction: 'ltr' },
+  { value: 'pt-BR', label: 'Português do Brasil', direction: 'ltr' },
+  { value: 'ro', label: 'Română', direction: 'ltr' },
+  { value: 'ru', label: 'Русский', direction: 'ltr' },
+  { value: 'sv', label: 'Svenska', direction: 'ltr' },
+  { value: 'tr', label: 'Türkçe', direction: 'ltr' },
+  { value: 'uk', label: 'Українська', direction: 'ltr' },
+  { value: 'vi', label: 'Tiếng Việt', direction: 'ltr' },
+  { value: 'zh-CN', label: '简体中文', direction: 'ltr' },
+  { value: 'zh-Hant', label: '漢語', direction: 'ltr' },
+] as const;
+
+export type WorkbenchLanguage = (typeof WORKBENCH_LANGUAGE_OPTIONS)[number]['value'];
+export type WorkbenchLanguageDirection = (typeof WORKBENCH_LANGUAGE_OPTIONS)[number]['direction'];
+
+export const WORKBENCH_LANGUAGES: WorkbenchLanguage[] = WORKBENCH_LANGUAGE_OPTIONS.map((option) => option.value);
+
+export const normalizeWorkbenchLanguage = (value: unknown): WorkbenchLanguage | null => {
+  if (value === 'ua') {
+    return 'uk';
+  }
+
+  return typeof value === 'string' && WORKBENCH_LANGUAGES.includes(value as WorkbenchLanguage)
+    ? (value as WorkbenchLanguage)
+    : null;
+};
+
+export const getWorkbenchLanguageDirection = (language: WorkbenchLanguage): WorkbenchLanguageDirection =>
+  WORKBENCH_LANGUAGE_OPTIONS.find((option) => option.value === language)?.direction ?? 'ltr';
diff --git a/invokeai/frontend/webv2/src/workbench/iconResolver.tsx b/invokeai/frontend/webv2/src/workbench/iconResolver.tsx
new file mode 100644
index 00000000000..0704ee8a7fb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/iconResolver.tsx
@@ -0,0 +1,10 @@
+import { Icon, type IconProps } from '@chakra-ui/react';
+import { SquareIcon } from 'lucide-react';
+
+import type { WidgetIconComponent } from './types';
+
+export const WidgetIcon = ({ icon, ...props }: IconProps & { icon?: WidgetIconComponent }) => {
+  const ResolvedIcon = icon ?? SquareIcon;
+
+  return <Icon as={ResolvedIcon} {...props} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/ImageContextMenu.test.ts b/invokeai/frontend/webv2/src/workbench/image-actions/ImageContextMenu.test.ts
new file mode 100644
index 00000000000..947b8fe0f76
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/ImageContextMenu.test.ts
@@ -0,0 +1,82 @@
+import type { GalleryImage } from '@workbench/gallery/api';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getGalleryCanvasImportMenuItems,
+  getImageContextMenuImages,
+  getImageContextMenuRecallRequestKey,
+} from './ImageContextMenu';
+
+const image: GalleryImage = {
+  boardId: 'none',
+  height: 512,
+  imageCategory: 'general',
+  imageName: 'image.png',
+  imageUrl: '/image.png',
+  queuedAt: '2026-06-15T00:00:00Z',
+  sourceQueueItemId: 'queue-item',
+  starred: false,
+  thumbnailUrl: '/thumb.png',
+  width: 512,
+};
+
+describe('getImageContextMenuImages', () => {
+  it('returns only usable images from a context menu target', () => {
+    expect(getImageContextMenuImages({ images: [image], x: 0, y: 0 })).toEqual([image]);
+    expect(
+      getImageContextMenuImages({ images: [image, { imageName: 'missing-urls.png' } as GalleryImage], x: 0, y: 0 })
+    ).toEqual([image]);
+  });
+
+  it('tolerates stale or malformed targets', () => {
+    expect(getImageContextMenuImages(null)).toEqual([]);
+    expect(getImageContextMenuImages({ images: undefined as unknown as GalleryImage[], x: 0, y: 0 })).toEqual([]);
+  });
+});
+
+describe('getImageContextMenuRecallRequestKey', () => {
+  it('uses stable image primitives instead of object identity', () => {
+    const refreshedImage = { ...image };
+
+    expect(getImageContextMenuRecallRequestKey(image, false)).toBe(
+      getImageContextMenuRecallRequestKey(refreshedImage, false)
+    );
+  });
+
+  it('does not request single-image recall for empty or bulk menu targets', () => {
+    expect(getImageContextMenuRecallRequestKey(null, false)).toBeNull();
+    expect(getImageContextMenuRecallRequestKey(image, true)).toBeNull();
+  });
+});
+
+describe('getGalleryCanvasImportMenuItems', () => {
+  const expectedDestinationsAndLabels = [
+    ['raster', 'widgets.canvas.import.raster'],
+    ['control', 'widgets.canvas.import.control'],
+    ['inpaint-mask', 'widgets.canvas.import.inpaintMask'],
+    ['regional-guidance', 'widgets.canvas.import.regionalGuidance'],
+    ['regional-reference', 'widgets.canvas.import.regionalReference'],
+    ['control-resized', 'widgets.canvas.import.resizedControl'],
+  ];
+
+  it('returns the six stable single-image canvas import entries in order', () => {
+    expect(getGalleryCanvasImportMenuItems(false)).toEqual(
+      expectedDestinationsAndLabels.map(([destination, label]) => ({
+        destination,
+        label,
+        value: `send-image-to-canvas-${destination}`,
+      }))
+    );
+  });
+
+  it('returns the same six destinations for bulk imports with stable bulk values', () => {
+    expect(getGalleryCanvasImportMenuItems(true)).toEqual(
+      expectedDestinationsAndLabels.map(([destination, label]) => ({
+        destination,
+        label,
+        value: `send-images-to-canvas-${destination}`,
+      }))
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/ImageContextMenu.tsx b/invokeai/frontend/webv2/src/workbench/image-actions/ImageContextMenu.tsx
new file mode 100644
index 00000000000..78f92d4886d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/ImageContextMenu.tsx
@@ -0,0 +1,725 @@
+/* eslint-disable react/react-compiler */
+import type { GalleryCanvasImportDestination } from '@workbench/canvas-operations/api';
+import type { GalleryBoard, GalleryImage } from '@workbench/gallery/api';
+
+import { Dialog, HStack, Icon, Menu, Portal, ScrollArea, Text } from '@chakra-ui/react';
+import { Button, MenuContent, Tooltip } from '@workbench/components/ui';
+import { useWorkbenchPreferenceSelector } from '@workbench/settings/store';
+import {
+  AsteriskIcon,
+  ChevronRightIcon,
+  CopyIcon,
+  DownloadIcon,
+  ExternalLinkIcon,
+  EyeIcon,
+  FileImageIcon,
+  FolderIcon,
+  ImageIcon,
+  ImagesIcon,
+  LayersIcon,
+  QuoteIcon,
+  RulerIcon,
+  ScanIcon,
+  ScissorsIcon,
+  ShuffleIcon,
+  SproutIcon,
+  StarIcon,
+  Trash2Icon,
+  TypeIcon,
+  WorkflowIcon,
+  type LucideIcon,
+} from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ImageActions } from './useImageActions';
+
+import { EMPTY_IMAGE_RECALL_CAPABILITIES, type ImageRecallCapabilities } from './imageRecall';
+
+export interface ImageContextMenuTarget {
+  /** Right-clicked image first; more entries switch the menu into bulk mode. */
+  images: GalleryImage[];
+  x: number;
+  y: number;
+}
+
+/** Extras on top of the shared MenuContent surface styling. */
+const MENU_CONTENT_PROPS = {
+  minW: '13rem',
+  overflow: 'hidden',
+} as const;
+const MENU_POSITIONING_PROPS = { placement: 'right-start' } as const;
+const QUICK_MENU_TOOLTIP_CONTENT_PROPS = { fontSize: '2xs' } as const;
+const QUICK_MENU_TOOLTIP_POSITIONING_PROPS = { placement: 'top' } as const;
+
+const isUsableGalleryImage = (value: unknown): value is GalleryImage =>
+  Boolean(value) &&
+  typeof value === 'object' &&
+  typeof (value as GalleryImage).imageName === 'string' &&
+  typeof (value as GalleryImage).imageUrl === 'string' &&
+  typeof (value as GalleryImage).thumbnailUrl === 'string';
+
+interface GalleryCanvasImportMenuItem {
+  destination: GalleryCanvasImportDestination;
+  label: string;
+  value: string;
+}
+
+const GALLERY_CANVAS_IMPORT_MENU_ITEMS = [
+  { destination: 'raster', label: 'widgets.canvas.import.raster' },
+  { destination: 'control', label: 'widgets.canvas.import.control' },
+  { destination: 'inpaint-mask', label: 'widgets.canvas.import.inpaintMask' },
+  { destination: 'regional-guidance', label: 'widgets.canvas.import.regionalGuidance' },
+  { destination: 'regional-reference', label: 'widgets.canvas.import.regionalReference' },
+  { destination: 'control-resized', label: 'widgets.canvas.import.resizedControl' },
+] as const satisfies readonly Omit<GalleryCanvasImportMenuItem, 'value'>[];
+
+export const getGalleryCanvasImportMenuItems = (isBulk: boolean): GalleryCanvasImportMenuItem[] =>
+  GALLERY_CANVAS_IMPORT_MENU_ITEMS.map((item) => ({
+    ...item,
+    value: `send-${isBulk ? 'images' : 'image'}-to-canvas-${item.destination}`,
+  }));
+
+export const getImageContextMenuImages = (target: ImageContextMenuTarget | null): GalleryImage[] => {
+  if (!Array.isArray(target?.images)) {
+    return [];
+  }
+
+  return target.images.filter(isUsableGalleryImage);
+};
+
+export const getImageContextMenuRecallRequestKey = (image: GalleryImage | null, isBulk: boolean): string | null => {
+  if (!image || isBulk) {
+    return null;
+  }
+
+  return `${image.imageName}:${image.width}:${image.height}`;
+};
+
+/**
+ * Shared right-click menu for backend images, usable from any widget (gallery
+ * grid, preview, ...). Anchored to the cursor through a virtual rect, so it
+ * needs no trigger element — set `target` to open it.
+ */
+export const ImageContextMenu = ({
+  actions,
+  boards,
+  target,
+  onClose,
+}: {
+  actions: ImageActions;
+  boards: GalleryBoard[];
+  target: ImageContextMenuTarget | null;
+  onClose: () => void;
+}) => {
+  const images = getImageContextMenuImages(target);
+  const image = images[0] ?? null;
+
+  if (!target || !image) {
+    return null;
+  }
+
+  return (
+    <ImageContextMenuContent
+      key={`${image.imageName}:${images.length}`}
+      actions={actions}
+      boards={boards}
+      image={image}
+      images={images}
+      target={target}
+      onClose={onClose}
+    />
+  );
+};
+
+const ImageContextMenuContent = ({
+  actions,
+  boards,
+  image,
+  images,
+  target,
+  onClose,
+}: {
+  actions: ImageActions;
+  boards: GalleryBoard[];
+  image: GalleryImage;
+  images: GalleryImage[];
+  target: ImageContextMenuTarget;
+  onClose: () => void;
+}) => {
+  const confirmImageDeletion = useWorkbenchPreferenceSelector((preferences) => preferences.confirmImageDeletion);
+  const [pendingDeletion, setPendingDeletion] = useState<string[] | null>(null);
+  const [recallCapabilities, setRecallCapabilities] = useState<ImageRecallCapabilities>(
+    EMPTY_IMAGE_RECALL_CAPABILITIES
+  );
+  const [isLoadingRecallCapabilities, setIsLoadingRecallCapabilities] = useState(false);
+  const targetRef = useRef(target);
+  const imageRef = useRef<GalleryImage | null>(null);
+
+  targetRef.current = target;
+
+  const isBulk = images.length > 1;
+  const imageNames = useMemo(() => images.map((candidate) => candidate.imageName), [images]);
+  const recallRequestKey = getImageContextMenuRecallRequestKey(image, isBulk);
+  const getImageRecallCapabilities = actions.getImageRecallCapabilities;
+
+  imageRef.current = image;
+
+  useEffect(() => {
+    if (!recallRequestKey) {
+      return;
+    }
+
+    let isCancelled = false;
+    const recallImage = imageRef.current;
+
+    if (!recallImage) {
+      return;
+    }
+
+    setIsLoadingRecallCapabilities((current) => (current ? current : true));
+    getImageRecallCapabilities(recallImage)
+      .then((capabilities) => {
+        if (!isCancelled) {
+          setRecallCapabilities(capabilities);
+        }
+      })
+      .catch(() => {
+        if (!isCancelled) {
+          setRecallCapabilities(EMPTY_IMAGE_RECALL_CAPABILITIES);
+        }
+      })
+      .finally(() => {
+        if (!isCancelled) {
+          setIsLoadingRecallCapabilities(false);
+        }
+      });
+
+    return () => {
+      isCancelled = true;
+    };
+  }, [getImageRecallCapabilities, recallRequestKey]);
+
+  const requestDeletion = useCallback(
+    (names: string[]) => {
+      if (confirmImageDeletion) {
+        setPendingDeletion(names);
+      } else {
+        void actions.deleteImages(names);
+      }
+    },
+    [actions, confirmImageDeletion]
+  );
+
+  const positioning = useMemo(
+    () => ({
+      getAnchorRect: () => {
+        const currentTarget = targetRef.current;
+
+        return { height: 1, width: 1, x: currentTarget.x, y: currentTarget.y };
+      },
+      placement: 'bottom-start' as const,
+    }),
+    []
+  );
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+  const handleDeleteDialogOpenChange = useCallback((event: { open: boolean }) => {
+    if (!event.open) {
+      setPendingDeletion(null);
+    }
+  }, []);
+  const handleCancelDeletion = useCallback(() => setPendingDeletion(null), []);
+  const handleConfirmDeletion = useCallback(() => {
+    if (pendingDeletion) {
+      void actions.deleteImages(pendingDeletion);
+    }
+
+    setPendingDeletion(null);
+  }, [actions, pendingDeletion]);
+
+  return (
+    <>
+      <Menu.Root lazyMount open positioning={positioning} unmountOnExit onOpenChange={handleOpenChange}>
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent {...MENU_CONTENT_PROPS} maxH="min(28rem, calc(100vh - 2rem))" minW="16rem" overflowY="auto">
+              {isBulk ? (
+                <BulkMenuItems
+                  actions={actions}
+                  boards={boards}
+                  imageNames={imageNames}
+                  images={images}
+                  onRequestDeletion={requestDeletion}
+                />
+              ) : (
+                <SingleImageMenuItems
+                  actions={actions}
+                  boards={boards}
+                  image={image}
+                  images={images}
+                  isLoadingRecallCapabilities={isLoadingRecallCapabilities}
+                  onRequestDeletion={requestDeletion}
+                  recallCapabilities={recallCapabilities}
+                />
+              )}
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <Dialog.Root open={pendingDeletion !== null} role="alertdialog" onOpenChange={handleDeleteDialogOpenChange}>
+        <Portal>
+          <Dialog.Backdrop />
+          <Dialog.Positioner>
+            <Dialog.Content>
+              <Dialog.Header>
+                <Dialog.Title fontSize="sm">
+                  {pendingDeletion && pendingDeletion.length > 1
+                    ? `Delete ${pendingDeletion.length} images?`
+                    : 'Delete image?'}
+                </Dialog.Title>
+              </Dialog.Header>
+              <Dialog.Body>
+                <Text color="fg.subtle" fontSize="xs">
+                  This permanently deletes{' '}
+                  {pendingDeletion && pendingDeletion.length > 1 ? 'these images' : 'the image'} from every board and
+                  from disk. This cannot be undone. You can disable this confirmation in Settings.
+                </Text>
+              </Dialog.Body>
+              <Dialog.Footer gap="2">
+                <Button size="xs" variant="outline" onClick={handleCancelDeletion}>
+                  Cancel
+                </Button>
+                <Button colorPalette="red" size="xs" onClick={handleConfirmDeletion}>
+                  Delete
+                </Button>
+              </Dialog.Footer>
+            </Dialog.Content>
+          </Dialog.Positioner>
+        </Portal>
+      </Dialog.Root>
+    </>
+  );
+};
+
+const SingleImageMenuItems = ({
+  actions,
+  boards,
+  image,
+  images,
+  isLoadingRecallCapabilities,
+  onRequestDeletion,
+  recallCapabilities,
+}: {
+  actions: ImageActions;
+  boards: GalleryBoard[];
+  image: GalleryImage;
+  images: GalleryImage[];
+  isLoadingRecallCapabilities: boolean;
+  onRequestDeletion: (imageNames: string[]) => void;
+  recallCapabilities: ImageRecallCapabilities;
+}) => {
+  const handleMove = useCallback(
+    (boardId: string) => void actions.moveImagesToBoard([image.imageName], boardId),
+    [actions, image.imageName]
+  );
+  const handleDelete = useCallback(() => onRequestDeletion([image.imageName]), [image.imageName, onRequestDeletion]);
+  const handleRecallAll = useRecallImageDataHandler(actions, image, 'all');
+  const handleRecallRemix = useRecallImageDataHandler(actions, image, 'remix');
+  const handleRecallPrompts = useRecallImageDataHandler(actions, image, 'prompts');
+  const handleRecallSeed = useRecallImageDataHandler(actions, image, 'seed');
+  const handleRecallDimensions = useRecallImageDataHandler(actions, image, 'dimensions');
+  const handleRecallClipSkip = useRecallImageDataHandler(actions, image, 'clipSkip');
+  const handleSelectForCompare = useSelectForCompareHandler(actions, image);
+  const handleUseAsReferenceImage = useUseAsReferenceImageHandler(actions, image);
+
+  return (
+    <>
+      <HStack gap="1">
+        <OpenInNewTabQuickMenuItem image={image} />
+        <CopyQuickMenuItem actions={actions} image={image} />
+        <DownloadQuickMenuItem actions={actions} image={image} />
+        <OpenPreviewQuickMenuItem actions={actions} image={image} />
+        <ToggleStarQuickMenuItem actions={actions} image={image} />
+      </HStack>
+      <Menu.Separator borderColor="border.subtle" />
+      <ContextMenuItem disabled icon={WorkflowIcon} label="Load Workflow" value="load-workflow" />
+      <ContextSubMenu icon={AsteriskIcon} label="Recall Metadata">
+        <ContextMenuItem
+          disabled={isLoadingRecallCapabilities || !recallCapabilities.all}
+          icon={AsteriskIcon}
+          label="Recall All"
+          value="recall-all"
+          onClick={handleRecallAll}
+        />
+        <ContextMenuItem
+          disabled={isLoadingRecallCapabilities || !recallCapabilities.remix}
+          icon={ShuffleIcon}
+          label="Remix Image"
+          value="remix"
+          onClick={handleRecallRemix}
+        />
+        <ContextMenuItem
+          disabled={isLoadingRecallCapabilities || !recallCapabilities.prompts}
+          icon={QuoteIcon}
+          label="Use Prompt"
+          value="use-prompt"
+          onClick={handleRecallPrompts}
+        />
+        <ContextMenuItem
+          disabled={isLoadingRecallCapabilities || !recallCapabilities.seed}
+          icon={SproutIcon}
+          label="Use Seed"
+          value="use-seed"
+          onClick={handleRecallSeed}
+        />
+        <ContextMenuItem
+          disabled={isLoadingRecallCapabilities || !recallCapabilities.dimensions}
+          icon={RulerIcon}
+          label="Use Size"
+          value="use-size"
+          onClick={handleRecallDimensions}
+        />
+        <ContextMenuItem
+          disabled={isLoadingRecallCapabilities || !recallCapabilities.clipSkip}
+          icon={ScissorsIcon}
+          label="Use CLIP Skip"
+          value="use-clip-skip"
+          onClick={handleRecallClipSkip}
+        />
+      </ContextSubMenu>
+      <Menu.Separator borderColor="border.subtle" />
+      <ContextMenuItem disabled icon={ScanIcon} label="Send to Upscale" value="send-to-upscale" />
+      <ContextMenuItem
+        disabled={!actions.canUseAsReferenceImage}
+        icon={ImageIcon}
+        label="Use as Reference Image"
+        value="use-as-reference-image"
+        onClick={handleUseAsReferenceImage}
+      />
+      <ContextMenuItem disabled icon={TypeIcon} label="Use as Prompt Template" value="use-as-prompt-template" />
+      <ContextMenuItem
+        icon={ImagesIcon}
+        label="Select for Compare"
+        value="select-for-compare"
+        onClick={handleSelectForCompare}
+      />
+      <Menu.Separator borderColor="border.subtle" />
+      <NewFromImageSubMenu actions={actions} images={images} isBulk={false} />
+      <ChangeBoardSubMenu boards={boards} currentBoardId={image.boardId} onMove={handleMove} />
+      <Menu.Separator borderColor="border.subtle" />
+      <ContextMenuItem
+        color="fg.error"
+        icon={Trash2Icon}
+        label="Delete Image"
+        value="delete-image"
+        onClick={handleDelete}
+      />
+    </>
+  );
+};
+
+type RecallImageDataKind = Parameters<ImageActions['recallImageData']>[1];
+
+const useRecallImageDataHandler = (actions: ImageActions, image: GalleryImage, kind: RecallImageDataKind) =>
+  useCallback(() => void actions.recallImageData(image, kind), [actions, image, kind]);
+
+const useSelectForCompareHandler = (actions: ImageActions, image: GalleryImage) =>
+  useCallback(() => actions.selectForCompare(image), [actions, image]);
+
+const useUseAsReferenceImageHandler = (actions: ImageActions, image: GalleryImage) =>
+  useCallback(() => actions.useAsReferenceImage(image), [actions, image]);
+
+const OpenInNewTabQuickMenuItem = ({ image }: { image: GalleryImage }) => {
+  const handleClick = useCallback(() => window.open(image.imageUrl, '_blank', 'noopener'), [image.imageUrl]);
+
+  return (
+    <QuickMenuItem icon={ExternalLinkIcon} label="Open in new tab" value="open-in-new-tab" onClick={handleClick} />
+  );
+};
+
+const CopyQuickMenuItem = ({ actions, image }: { actions: ImageActions; image: GalleryImage }) => {
+  const handleClick = useCallback(() => void actions.copyImage(image), [actions, image]);
+
+  return <QuickMenuItem icon={CopyIcon} label="Copy to clipboard" value="copy-to-clipboard" onClick={handleClick} />;
+};
+
+const DownloadQuickMenuItem = ({ actions, image }: { actions: ImageActions; image: GalleryImage }) => {
+  const handleClick = useCallback(() => void actions.downloadImage(image), [actions, image]);
+
+  return <QuickMenuItem icon={DownloadIcon} label="Download image" value="download-image" onClick={handleClick} />;
+};
+
+const OpenPreviewQuickMenuItem = ({ actions, image }: { actions: ImageActions; image: GalleryImage }) => {
+  const handleClick = useCallback(() => actions.openImageInPreview(image), [actions, image]);
+
+  return <QuickMenuItem icon={EyeIcon} label="Open in preview" value="open-in-preview" onClick={handleClick} />;
+};
+
+const ToggleStarQuickMenuItem = ({ actions, image }: { actions: ImageActions; image: GalleryImage }) => {
+  const handleClick = useCallback(
+    () => void actions.setImagesStarred([image.imageName], !image.starred),
+    [actions, image.imageName, image.starred]
+  );
+
+  return (
+    <QuickMenuItem
+      icon={StarIcon}
+      label={image.starred ? 'Unstar image' : 'Star image'}
+      value="toggle-starred"
+      onClick={handleClick}
+    />
+  );
+};
+
+const BulkMenuItems = ({
+  actions,
+  boards,
+  imageNames,
+  images,
+  onRequestDeletion,
+}: {
+  actions: ImageActions;
+  boards: GalleryBoard[];
+  imageNames: string[];
+  images: GalleryImage[];
+  onRequestDeletion: (imageNames: string[]) => void;
+}) => {
+  const allStarred = images.every((image) => image.starred);
+  const handleToggleStarred = useCallback(
+    () => void actions.setImagesStarred(imageNames, !allStarred),
+    [actions, allStarred, imageNames]
+  );
+  const handleDownload = useCallback(() => void actions.downloadImages(imageNames), [actions, imageNames]);
+  const handleMove = useCallback(
+    (boardId: string) => void actions.moveImagesToBoard(imageNames, boardId),
+    [actions, imageNames]
+  );
+  const handleDelete = useCallback(() => onRequestDeletion(imageNames), [imageNames, onRequestDeletion]);
+
+  return (
+    <>
+      <Text color="fg.subtle" fontSize="2xs" fontWeight="700" px="3" py="1.5" textTransform="uppercase">
+        {images.length} images selected
+      </Text>
+      <Menu.Separator borderColor="border.subtle" />
+      <ContextMenuItem
+        icon={StarIcon}
+        label={allStarred ? 'Unstar All' : 'Star All'}
+        value="toggle-starred-all"
+        onClick={handleToggleStarred}
+      />
+      <ContextMenuItem
+        icon={DownloadIcon}
+        label="Download Selection"
+        value="download-selection"
+        onClick={handleDownload}
+      />
+      <NewFromImageSubMenu actions={actions} images={images} isBulk />
+      <ChangeBoardSubMenu boards={boards} currentBoardId={null} onMove={handleMove} />
+      <Menu.Separator borderColor="border.subtle" />
+      <ContextMenuItem
+        color="fg.error"
+        icon={Trash2Icon}
+        label="Delete Selection"
+        value="delete-selection"
+        onClick={handleDelete}
+      />
+    </>
+  );
+};
+
+const NewFromImageSubMenu = ({
+  actions,
+  images,
+  isBulk,
+}: {
+  actions: ImageActions;
+  images: GalleryImage[];
+  isBulk: boolean;
+}) => (
+  <ContextSubMenu icon={FileImageIcon} label={isBulk ? 'New from Images' : 'New from Image'}>
+    <ContextMenuItem disabled icon={FileImageIcon} label="New Canvas from Image" value="new-canvas-from-image" />
+    <GalleryCanvasImportSubMenu actions={actions} images={images} isBulk={isBulk} />
+  </ContextSubMenu>
+);
+
+const GalleryCanvasImportSubMenu = ({
+  actions,
+  images,
+  isBulk,
+}: {
+  actions: ImageActions;
+  images: GalleryImage[];
+  isBulk: boolean;
+}) => {
+  const { t } = useTranslation();
+  const items = getGalleryCanvasImportMenuItems(isBulk);
+
+  return (
+    <ContextSubMenu icon={LayersIcon} label={t('widgets.canvas.import.newLayerFromImage')}>
+      {items.map((item) => (
+        <GalleryCanvasImportDestinationMenuItem key={item.destination} actions={actions} images={images} item={item} />
+      ))}
+    </ContextSubMenu>
+  );
+};
+
+const GalleryCanvasImportDestinationMenuItem = ({
+  actions,
+  images,
+  item,
+}: {
+  actions: ImageActions;
+  images: GalleryImage[];
+  item: GalleryCanvasImportMenuItem;
+}) => {
+  const { t } = useTranslation();
+  const handleClick = useCallback(
+    () => void actions.sendToCanvas(images, item.destination),
+    [actions, images, item.destination]
+  );
+
+  return <ContextMenuItem icon={LayersIcon} label={t(item.label)} value={item.value} onClick={handleClick} />;
+};
+
+const ChangeBoardSubMenu = ({
+  boards,
+  currentBoardId,
+  onMove,
+}: {
+  boards: GalleryBoard[];
+  currentBoardId: string | null;
+  onMove: (boardId: string) => void;
+}) => {
+  const handleRemoveFromBoard = useCallback(() => onMove('none'), [onMove]);
+  const visibleBoards = useMemo(
+    () => boards.filter((board) => board.kind === 'board' && board.id !== currentBoardId),
+    [boards, currentBoardId]
+  );
+
+  return (
+    <ContextSubMenu icon={FolderIcon} label="Change Board" scrollArea>
+      {currentBoardId !== 'none' && (
+        <ContextMenuItem
+          icon={FolderIcon}
+          label="Remove from Board"
+          value="remove-from-board"
+          onClick={handleRemoveFromBoard}
+        />
+      )}
+      {visibleBoards.map((board) => (
+        <ChangeBoardMenuItem key={board.id} board={board} onMove={onMove} />
+      ))}
+    </ContextSubMenu>
+  );
+};
+
+const ChangeBoardMenuItem = ({ board, onMove }: { board: GalleryBoard; onMove: (boardId: string) => void }) => {
+  const handleClick = useCallback(() => onMove(board.id), [board.id, onMove]);
+
+  return (
+    <Menu.Item value={`move-to-${board.id}`} onClick={handleClick}>
+      <Text fontSize="xs" minW="0" truncate>
+        {board.name}
+      </Text>
+    </Menu.Item>
+  );
+};
+
+const ContextSubMenu = ({
+  children,
+  icon,
+  label,
+  scrollArea,
+}: {
+  children: ReactNode;
+  icon: LucideIcon;
+  label: string;
+  scrollArea?: boolean;
+}) => (
+  <Menu.Root positioning={MENU_POSITIONING_PROPS}>
+    <Menu.TriggerItem>
+      <HStack gap="2" minW="0" w="full">
+        <Icon as={icon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+        <Text flex="1" fontSize="xs">
+          {label}
+        </Text>
+        <Icon as={ChevronRightIcon} boxSize="3" color="fg.subtle" flexShrink={0} />
+      </HStack>
+    </Menu.TriggerItem>
+    <Portal>
+      <Menu.Positioner>
+        <MenuContent {...MENU_CONTENT_PROPS} maxH="18rem" overflowY={scrollArea ? undefined : 'auto'}>
+          {scrollArea ? (
+            <ScrollArea.Root maxH="inherit" size="xs" variant="hover" w="full">
+              <ScrollArea.Viewport maxH="inherit" w="full">
+                <ScrollArea.Content>{children}</ScrollArea.Content>
+              </ScrollArea.Viewport>
+              <ScrollArea.Scrollbar>
+                <ScrollArea.Thumb />
+              </ScrollArea.Scrollbar>
+            </ScrollArea.Root>
+          ) : (
+            children
+          )}
+        </MenuContent>
+      </Menu.Positioner>
+    </Portal>
+  </Menu.Root>
+);
+
+const QuickMenuItem = ({
+  icon,
+  label,
+  value,
+  onClick,
+}: {
+  icon: LucideIcon;
+  label: string;
+  value: string;
+  onClick: () => void;
+}) => (
+  <Tooltip
+    showArrow
+    content={label}
+    contentProps={QUICK_MENU_TOOLTIP_CONTENT_PROPS}
+    openDelay={300}
+    positioning={QUICK_MENU_TOOLTIP_POSITIONING_PROPS}
+  >
+    <Menu.Item aria-label={label} flex="1" justifyContent="center" value={value} onClick={onClick}>
+      <Icon as={icon} boxSize="4" color="fg" />
+    </Menu.Item>
+  </Tooltip>
+);
+
+const ContextMenuItem = ({
+  color,
+  disabled,
+  icon,
+  label,
+  value,
+  onClick,
+}: {
+  color?: string;
+  disabled?: boolean;
+  icon: LucideIcon;
+  label: string;
+  value: string;
+  onClick?: () => void;
+}) => (
+  <Menu.Item color={color} disabled={disabled} value={value} onClick={onClick}>
+    <HStack gap="2" minW="0" w="full">
+      <Icon as={icon} boxSize="3.5" color={color ?? 'fg.subtle'} flexShrink={0} />
+      <Text flex="1" fontSize="xs">
+        {label}
+      </Text>
+    </HStack>
+  </Menu.Item>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/canvasImportError.test.ts b/invokeai/frontend/webv2/src/workbench/image-actions/canvasImportError.test.ts
new file mode 100644
index 00000000000..c30fee61b7d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/canvasImportError.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { recordCanvasImportError } from './canvasImportError';
+
+describe('recordCanvasImportError', () => {
+  it('dispatches one localized diagnostic error and no notice', () => {
+    const dispatch = vi.fn();
+
+    recordCanvasImportError({
+      dispatch,
+      error: new Error('resize backend failed'),
+      localizedMessage: "Couldn't add images to canvas",
+      projectId: 'project-1',
+    });
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch).toHaveBeenCalledWith({
+      area: 'image-actions',
+      context: { error: 'resize backend failed' },
+      message: "Couldn't add images to canvas",
+      namespace: 'gallery',
+      projectId: 'project-1',
+      type: 'recordError',
+    });
+    expect(dispatch.mock.calls.some(([action]) => action.type === 'recordNotice')).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/canvasImportError.ts b/invokeai/frontend/webv2/src/workbench/image-actions/canvasImportError.ts
new file mode 100644
index 00000000000..f558b7a82f5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/canvasImportError.ts
@@ -0,0 +1,25 @@
+import type { WorkbenchAction } from '@workbench/workbenchState';
+import type { Dispatch } from 'react';
+
+const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+export const recordCanvasImportError = ({
+  dispatch,
+  error,
+  localizedMessage,
+  projectId,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  error: unknown;
+  localizedMessage: string;
+  projectId?: string;
+}): void => {
+  dispatch({
+    area: 'image-actions',
+    context: { error: toErrorMessage(error) },
+    message: localizedMessage,
+    namespace: 'gallery',
+    projectId,
+    type: 'recordError',
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/executeImageRecall.test.ts b/invokeai/frontend/webv2/src/workbench/image-actions/executeImageRecall.test.ts
new file mode 100644
index 00000000000..5be89556b71
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/executeImageRecall.test.ts
@@ -0,0 +1,93 @@
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { ModelConfig } from '@workbench/models/types';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const galleryApi = vi.hoisted(() => ({
+  getGalleryImageMetadata: vi.fn(),
+}));
+
+vi.mock('@workbench/gallery/api', () => galleryApi);
+
+import { executeImageRecall } from './executeImageRecall';
+
+const model = {
+  base: 'sdxl',
+  file_size: 1,
+  format: 'checkpoint',
+  hash: 'hash',
+  key: 'sdxl-model',
+  name: 'SDXL',
+  path: '/models/sdxl.safetensors',
+  source: 'local',
+  source_type: 'path',
+  type: 'main',
+} as ModelConfig;
+
+const image: GalleryImage = {
+  boardId: 'none',
+  height: 768,
+  imageCategory: 'general',
+  imageName: 'selected.png',
+  imageUrl: '/selected.png',
+  queuedAt: '2026-06-19T00:00:00.000Z',
+  sourceQueueItemId: 'backend-gallery',
+  starred: false,
+  thumbnailUrl: '/selected-thumb.png',
+  width: 512,
+};
+
+describe('executeImageRecall', () => {
+  beforeEach(() => {
+    galleryApi.getGalleryImageMetadata.mockReset();
+  });
+
+  it('recalls remix settings into Generate values', async () => {
+    const dispatch = vi.fn();
+
+    galleryApi.getGalleryImageMetadata.mockResolvedValue({ positive_prompt: 'recalled prompt' });
+
+    await expect(
+      executeImageRecall({
+        dispatch,
+        generateValues: { modelKey: model.key },
+        image,
+        kind: 'remix',
+        models: [model],
+        projectId: 'project-1',
+      })
+    ).resolves.toBe(true);
+
+    expect(galleryApi.getGalleryImageMetadata).toHaveBeenCalledWith('selected.png');
+    expect(dispatch).toHaveBeenCalledWith({
+      projectId: 'project-1',
+      type: 'setGenerateSettings',
+      values: expect.objectContaining({ positivePrompt: 'recalled prompt' }),
+    });
+    expect(dispatch).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: 'success', title: 'Recalled remix settings', type: 'recordNotice' })
+    );
+  });
+
+  it('uses the freshest Generate values when recalling image dimensions', async () => {
+    const dispatch = vi.fn();
+
+    await expect(
+      executeImageRecall({
+        dispatch,
+        generateValues: { modelKey: model.key, positivePrompt: 'stale prompt' },
+        getGenerateValues: () => ({ modelKey: model.key, positivePrompt: 'fresh prompt' }),
+        image,
+        kind: 'dimensions',
+        models: [model],
+        projectId: 'project-1',
+      })
+    ).resolves.toBe(true);
+
+    expect(dispatch).toHaveBeenCalledWith({
+      projectId: 'project-1',
+      type: 'setGenerateSettings',
+      values: expect.objectContaining({ positivePrompt: 'fresh prompt', height: image.height, width: image.width }),
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/executeImageRecall.ts b/invokeai/frontend/webv2/src/workbench/image-actions/executeImageRecall.ts
new file mode 100644
index 00000000000..49ab18d0578
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/executeImageRecall.ts
@@ -0,0 +1,139 @@
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { GenerateModelConfig, GenerateWidgetValues, VaeModelConfig } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+import type { Dispatch } from 'react';
+
+import { getGalleryImageMetadata } from '@workbench/gallery/api';
+import { getDefaultGenerateSettings, isSupportedGenerateModel } from '@workbench/generation/baseGenerationPolicies';
+import { isVaeModelConfig, normalizeGenerateWidgetValues } from '@workbench/generation/settings';
+
+import {
+  buildImageRecallSettings,
+  getImageRecallMessage,
+  getImageRecallTitle,
+  type ImageRecallKind,
+} from './imageRecall';
+
+const imageMetadataRequests = new Map<string, Promise<unknown>>();
+
+const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+const loadImageMetadata = (imageName: string): Promise<unknown> => {
+  const cachedRequest = imageMetadataRequests.get(imageName);
+
+  if (cachedRequest) {
+    return cachedRequest;
+  }
+
+  const request = getGalleryImageMetadata(imageName).catch((error: unknown) => {
+    imageMetadataRequests.delete(imageName);
+    throw error;
+  });
+
+  imageMetadataRequests.set(imageName, request);
+
+  return request;
+};
+
+export const getCurrentGenerateValues = ({
+  generateValues,
+  supportedModels,
+}: {
+  generateValues: Record<string, unknown>;
+  supportedModels: GenerateModelConfig[];
+}) => {
+  const normalizedValues = normalizeGenerateWidgetValues(generateValues);
+
+  if (normalizedValues) {
+    return normalizedValues;
+  }
+
+  const fallbackModelKey = typeof generateValues.modelKey === 'string' ? generateValues.modelKey : null;
+  const fallbackModel = supportedModels.find((model) => model.key === fallbackModelKey) ?? supportedModels[0];
+
+  return fallbackModel
+    ? ({
+        ...getDefaultGenerateSettings(fallbackModel),
+        ...generateValues,
+        model: fallbackModel,
+        modelKey: fallbackModel.key,
+      } as GenerateWidgetValues)
+    : null;
+};
+
+export const executeImageRecall = async ({
+  dispatch,
+  generateValues,
+  getGenerateValues,
+  image,
+  kind,
+  models,
+  projectId,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  generateValues: Record<string, unknown>;
+  getGenerateValues?: () => Record<string, unknown>;
+  image: GalleryImage;
+  kind: ImageRecallKind;
+  models: ModelConfig[];
+  projectId?: string;
+}): Promise<boolean> => {
+  const supportedModels = models.filter(isSupportedGenerateModel);
+  const vaeModels = models.filter(isVaeModelConfig).map((model) => model as VaeModelConfig);
+  const currentGenerateValues = getCurrentGenerateValues({
+    generateValues: getGenerateValues?.() ?? generateValues,
+    supportedModels,
+  });
+
+  try {
+    if (!currentGenerateValues) {
+      dispatch({
+        kind: 'info',
+        message: 'Select a supported Generate model first.',
+        title: 'Cannot recall image data',
+        type: 'recordNotice',
+      });
+      return false;
+    }
+
+    const metadata = kind === 'dimensions' ? null : await loadImageMetadata(image.imageName);
+    const result = buildImageRecallSettings({
+      currentValues: currentGenerateValues,
+      image,
+      kind,
+      metadata,
+      models,
+      supportedModels,
+      vaeModels,
+    });
+
+    if (!result) {
+      dispatch({
+        kind: 'info',
+        message: 'This image does not include supported Generate metadata.',
+        title: 'No recallable image data',
+        type: 'recordNotice',
+      });
+      return false;
+    }
+
+    dispatch({ projectId, type: 'setGenerateSettings', values: result.values });
+    dispatch({
+      kind: 'success',
+      message: getImageRecallMessage(result.fields),
+      title: getImageRecallTitle(kind),
+      type: 'recordNotice',
+    });
+    return true;
+  } catch (error: unknown) {
+    dispatch({
+      area: 'image-recall',
+      message: toErrorMessage(error),
+      namespace: 'generation',
+      projectId,
+      type: 'recordError',
+    });
+    return false;
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/imageRecall.test.ts b/invokeai/frontend/webv2/src/workbench/image-actions/imageRecall.test.ts
new file mode 100644
index 00000000000..471eb5508a5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/imageRecall.test.ts
@@ -0,0 +1,324 @@
+import type { GalleryImage } from '@workbench/gallery/api';
+import type {
+  ComponentModelConfig,
+  GenerateWidgetValues,
+  MainModelConfig,
+  VaeModelConfig,
+} from '@workbench/generation/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { buildImageRecallSettings, getImageRecallCapabilities } from './imageRecall';
+
+const sdxlModel: MainModelConfig = { base: 'sdxl', key: 'sdxl-model', name: 'SDXL', type: 'main' };
+const sd1Model: MainModelConfig = { base: 'sd-1', key: 'sd1-model', name: 'SD 1.5', type: 'main' };
+const animaModel: MainModelConfig = { base: 'anima', key: 'anima-model', name: 'Anima', type: 'main' };
+const vaeModel: VaeModelConfig = { base: 'sd-1', key: 'vae-model', name: 'SD 1.5 VAE', type: 'vae' };
+const qwenImageVae: VaeModelConfig = { base: 'qwen-image', key: 'qwen-vae', name: 'Qwen VAE', type: 'vae' };
+const animaQwen3: ComponentModelConfig = {
+  base: 'any',
+  key: 'anima-qwen3',
+  name: 'Anima Qwen3',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_06b',
+};
+const qwenVLEncoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'qwen-vl',
+  name: 'Qwen VL',
+  type: 'qwen_vl_encoder',
+};
+
+const createValues = (overrides: Partial<GenerateWidgetValues> = {}): GenerateWidgetValues => ({
+  aspectRatioId: '1:1',
+  aspectRatioIsLocked: false,
+  aspectRatioValue: 1,
+  batchCount: 1,
+  cfgRescaleMultiplier: 0,
+  cfgScale: 7,
+  clipEmbedModel: null,
+  clipGEmbedModel: null,
+  clipLEmbedModel: null,
+  clipSkip: 0,
+  colorCompensation: false,
+  componentSourceModel: null,
+  height: 1024,
+  loras: [],
+  model: sdxlModel,
+  modelKey: sdxlModel.key,
+  negativePromptEnabled: true,
+  negativePrompt: '',
+  negativePromptHeightPx: 56,
+  positivePrompt: '',
+  positivePromptHeightPx: 96,
+  qwen3EncoderModel: null,
+  qwenVLEncoderModel: null,
+  referenceImages: [],
+  scheduler: 'euler_a',
+  seamlessXAxis: false,
+  seamlessYAxis: false,
+  seed: 123,
+  shouldRandomizeSeed: true,
+  steps: 30,
+  t5EncoderModel: null,
+  vae: null,
+  vaePrecision: 'fp32',
+  width: 1024,
+  ...overrides,
+});
+
+const image: GalleryImage = {
+  boardId: 'none',
+  height: 770,
+  imageCategory: 'general',
+  imageName: 'image.png',
+  imageUrl: '/image.png',
+  queuedAt: '2026-06-12T00:00:00.000Z',
+  sourceQueueItemId: 'backend-gallery',
+  starred: false,
+  thumbnailUrl: '/thumbnail.png',
+  width: 513,
+};
+
+const metadata = {
+  cfg_rescale_multiplier: 0.25,
+  cfg_scale: 8,
+  height: 770,
+  model: { key: sd1Model.key },
+  negative_prompt: null,
+  positive_prompt: 'a recalled prompt',
+  scheduler: 'euler',
+  seamless_x: true,
+  seed: 42,
+  steps: 25,
+  vae: { key: vaeModel.key },
+  width: 513,
+};
+
+describe('image recall', () => {
+  it('recalls supported image metadata into generate settings', () => {
+    const result = buildImageRecallSettings({
+      currentValues: createValues(),
+      image,
+      kind: 'all',
+      metadata,
+      models: [sd1Model, vaeModel],
+      supportedModels: [sd1Model],
+      vaeModels: [vaeModel],
+    });
+
+    expect(result?.values).toMatchObject({
+      cfgRescaleMultiplier: 0.25,
+      cfgScale: 8,
+      clipSkip: 0,
+      height: 768,
+      modelKey: sd1Model.key,
+      negativePrompt: '',
+      positivePrompt: 'a recalled prompt',
+      scheduler: 'euler',
+      seamlessXAxis: true,
+      seed: 42,
+      shouldRandomizeSeed: false,
+      steps: 25,
+      width: 512,
+    });
+    expect(result?.values.vae).toEqual(vaeModel);
+    expect(result?.fields).toContain('model');
+    expect(result?.fields).toContain('vae');
+    expect(result?.fields).toContain('prompts');
+    expect(result?.fields).toContain('seed');
+  });
+
+  it('recalls reference images from metadata, re-targeting configs to the effective model', () => {
+    // The metadata model is not installed, so the current SDXL model stays
+    // selected and the Qwen reference config is rebuilt for SDXL.
+    const result = buildImageRecallSettings({
+      currentValues: createValues(),
+      image,
+      kind: 'all',
+      metadata: {
+        ref_images: [
+          {
+            id: 'ref-1',
+            isEnabled: true,
+            config: {
+              image: {
+                height: 770,
+                imageName: 'reference.png',
+                imageUrl: '/api/v1/images/i/reference.png/full',
+                queuedAt: '2026-01-01T00:00:00.000Z',
+                sourceQueueItemId: 'backend-gallery',
+                thumbnailUrl: '/api/v1/images/i/reference.png/thumbnail',
+                width: 513,
+              },
+              type: 'qwen_image_reference_image',
+            },
+          },
+        ],
+      },
+      models: [],
+      supportedModels: [sdxlModel],
+      vaeModels: [],
+    });
+
+    expect(result?.values.referenceImages).toHaveLength(1);
+    expect(result?.values.referenceImages[0]?.config).toMatchObject({
+      image: { imageName: 'reference.png' },
+      type: 'ip_adapter',
+    });
+    expect(result?.fields).toContain('referenceImages');
+  });
+
+  it('drops recalled reference images when the effective model does not support them', () => {
+    const result = buildImageRecallSettings({
+      currentValues: createValues({ model: animaModel, modelKey: animaModel.key }),
+      image,
+      kind: 'all',
+      metadata: {
+        positive_prompt: 'a recalled prompt',
+        ref_images: [
+          {
+            id: 'ref-1',
+            isEnabled: true,
+            config: {
+              image: {
+                height: 770,
+                imageName: 'reference.png',
+                imageUrl: '/api/v1/images/i/reference.png/full',
+                queuedAt: '2026-01-01T00:00:00.000Z',
+                sourceQueueItemId: 'backend-gallery',
+                thumbnailUrl: '/api/v1/images/i/reference.png/thumbnail',
+                width: 513,
+              },
+              type: 'qwen_image_reference_image',
+            },
+          },
+        ],
+      },
+      models: [],
+      supportedModels: [animaModel],
+      vaeModels: [],
+    });
+
+    expect(result?.fields).toContain('prompts');
+    expect(result?.values.referenceImages).toEqual([]);
+    expect(result?.fields).not.toContain('referenceImages');
+  });
+
+  it('remixes without changing the current seed state', () => {
+    const result = buildImageRecallSettings({
+      currentValues: createValues({ seed: 999, shouldRandomizeSeed: false }),
+      image,
+      kind: 'remix',
+      metadata,
+      models: [sd1Model],
+      supportedModels: [sd1Model],
+      vaeModels: [],
+    });
+
+    expect(result?.values.seed).toBe(999);
+    expect(result?.values.shouldRandomizeSeed).toBe(false);
+    expect(result?.values.positivePrompt).toBe('a recalled prompt');
+    expect(result?.fields).not.toContain('seed');
+  });
+
+  it('uses actual image dimensions for Use Size', () => {
+    const result = buildImageRecallSettings({
+      currentValues: createValues(),
+      image,
+      kind: 'dimensions',
+      metadata: null,
+      models: [],
+      supportedModels: [],
+      vaeModels: [],
+    });
+
+    expect(result?.values.width).toBe(512);
+    expect(result?.values.height).toBe(768);
+    expect(result?.values.aspectRatioId).toBe('2:3');
+  });
+
+  it('only enables standalone CLIP skip when the current model supports it', () => {
+    const sdxlCapabilities = getImageRecallCapabilities({
+      currentValues: createValues({ model: sdxlModel, modelKey: sdxlModel.key }),
+      image,
+      metadata: { clip_skip: 3 },
+      models: [],
+      supportedModels: [],
+      vaeModels: [],
+    });
+    const sd1Capabilities = getImageRecallCapabilities({
+      currentValues: createValues({ model: sd1Model, modelKey: sd1Model.key }),
+      image,
+      metadata: { clip_skip: 3 },
+      models: [],
+      supportedModels: [],
+      vaeModels: [],
+    });
+
+    expect(sdxlCapabilities.clipSkip).toBe(false);
+    expect(sd1Capabilities.clipSkip).toBe(true);
+  });
+
+  it('enables recall actions for component-only metadata', () => {
+    const capabilities = getImageRecallCapabilities({
+      currentValues: createValues(),
+      image,
+      metadata: { qwen3_encoder: { key: animaQwen3.key } },
+      models: [animaQwen3],
+      supportedModels: [],
+      vaeModels: [],
+    });
+
+    expect(capabilities.all).toBe(true);
+    expect(capabilities.remix).toBe(true);
+  });
+
+  it('recalls required component models for component-based families', () => {
+    const result = buildImageRecallSettings({
+      currentValues: createValues({ model: sd1Model, modelKey: sd1Model.key }),
+      image,
+      kind: 'all',
+      metadata: {
+        height: 1024,
+        model: { key: animaModel.key },
+        qwen3_encoder: { key: animaQwen3.key },
+        vae: { key: qwenImageVae.key },
+        width: 1024,
+      },
+      models: [animaModel, animaQwen3, qwenImageVae],
+      supportedModels: [animaModel],
+      vaeModels: [qwenImageVae],
+    });
+
+    expect(result?.values.model).toBe(animaModel);
+    expect(result?.values.qwen3EncoderModel).toBe(animaQwen3);
+    expect(result?.values.vae).toBe(qwenImageVae);
+    expect(result?.fields).toContain('components');
+  });
+
+  it('clears component models when recalled metadata explicitly stores null', () => {
+    const result = buildImageRecallSettings({
+      currentValues: createValues({
+        componentSourceModel: sd1Model,
+        qwen3EncoderModel: animaQwen3,
+        qwenVLEncoderModel: qwenVLEncoder,
+      }),
+      image,
+      kind: 'all',
+      metadata: {
+        qwen3_encoder: null,
+        qwen3_source: null,
+        qwen_image_qwen_vl_encoder: null,
+      },
+      models: [sd1Model, animaQwen3, qwenVLEncoder],
+      supportedModels: [],
+      vaeModels: [],
+    });
+
+    expect(result?.values.componentSourceModel).toBeNull();
+    expect(result?.values.qwen3EncoderModel).toBeNull();
+    expect(result?.values.qwenVLEncoderModel).toBeNull();
+    expect(result?.fields).toContain('components');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/imageRecall.ts b/invokeai/frontend/webv2/src/workbench/image-actions/imageRecall.ts
new file mode 100644
index 00000000000..122e7e70724
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/imageRecall.ts
@@ -0,0 +1,563 @@
+import type { GalleryImage } from '@workbench/gallery/api';
+import type {
+  ComponentModelConfig,
+  GenerateModelConfig,
+  GenerateWidgetValues,
+  MainModelConfig,
+  VaeModelConfig,
+} from '@workbench/generation/types';
+
+import {
+  getCompatibleReferenceImages,
+  getGenerationDimensions,
+  getGenerationUiPolicy,
+  getSettingsWithModelDefaults,
+  isKnownScheduler,
+} from '@workbench/generation/baseGenerationPolicies';
+import { isVaeCompatibleWithGenerateModel } from '@workbench/generation/componentCompatibility';
+import {
+  cloneGenerateWidgetValues,
+  getModelDefaultVae,
+  hasModelDefaultVae,
+  isMainModelConfig,
+  isModelIdentifierConfig,
+  clampDimension,
+  deriveAspectRatioId,
+  normalizeReferenceImages,
+  SEED_MAX,
+} from '@workbench/generation/settings';
+
+export type ImageRecallKind = 'all' | 'remix' | 'prompts' | 'seed' | 'dimensions' | 'clipSkip';
+
+export interface ImageRecallCapabilities {
+  all: boolean;
+  remix: boolean;
+  prompts: boolean;
+  seed: boolean;
+  dimensions: boolean;
+  clipSkip: boolean;
+}
+
+export const EMPTY_IMAGE_RECALL_CAPABILITIES: ImageRecallCapabilities = {
+  all: false,
+  clipSkip: false,
+  dimensions: false,
+  prompts: false,
+  remix: false,
+  seed: false,
+};
+
+type RecalledField =
+  | 'model'
+  | 'vae'
+  | 'prompts'
+  | 'seed'
+  | 'size'
+  | 'steps'
+  | 'cfg'
+  | 'scheduler'
+  | 'seamless'
+  | 'clipSkip'
+  | 'components'
+  | 'referenceImages';
+
+export interface ImageRecallResult {
+  fields: RecalledField[];
+  values: GenerateWidgetValues;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const getRecord = (value: unknown, key: string): Record<string, unknown> | null => {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const child = value[key];
+
+  return isRecord(child) ? child : null;
+};
+
+const getString = (metadata: unknown, key: string): string | null => {
+  if (!isRecord(metadata)) {
+    return null;
+  }
+
+  const value = metadata[key];
+
+  return typeof value === 'string' ? value : null;
+};
+
+const getNullableString = (metadata: unknown, key: string): string | null | undefined => {
+  if (!isRecord(metadata)) {
+    return undefined;
+  }
+
+  const value = metadata[key];
+
+  if (value === null) {
+    return null;
+  }
+
+  return typeof value === 'string' ? value : undefined;
+};
+
+const getBoolean = (metadata: unknown, key: string): boolean | null => {
+  if (!isRecord(metadata)) {
+    return null;
+  }
+
+  const value = metadata[key];
+
+  return typeof value === 'boolean' ? value : null;
+};
+
+const getNumber = (metadata: unknown, key: string): number | null => {
+  if (!isRecord(metadata)) {
+    return null;
+  }
+
+  const value = metadata[key];
+
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+};
+
+const getInteger = (metadata: unknown, key: string): number | null => {
+  const value = getNumber(metadata, key);
+
+  return value !== null && Number.isInteger(value) ? value : null;
+};
+
+const getSeed = (metadata: unknown): number | null => {
+  const seed = getInteger(metadata, 'seed');
+
+  return seed !== null && seed >= 0 && seed <= SEED_MAX ? seed : null;
+};
+
+const getDimension = (metadata: unknown, key: 'height' | 'width', grid: number): number | null => {
+  const dimension = getNumber(metadata, key);
+
+  return dimension !== null && dimension >= 64 ? clampDimension(dimension, grid) : null;
+};
+
+const getImageDimension = (image: GalleryImage, key: 'height' | 'width', grid: number): number | null => {
+  const dimension = image[key];
+
+  return Number.isFinite(dimension) && dimension >= 64 ? clampDimension(dimension, grid) : null;
+};
+
+const getSteps = (metadata: unknown): number | null => {
+  const steps = getInteger(metadata, 'steps');
+
+  return steps !== null && steps >= 1 ? steps : null;
+};
+
+const getCfgScale = (metadata: unknown): number | null => {
+  const cfgScale = getNumber(metadata, 'cfg_scale');
+
+  return cfgScale !== null && cfgScale >= 1 ? cfgScale : null;
+};
+
+const getCfgRescaleMultiplier = (metadata: unknown): number | null => {
+  const cfgRescaleMultiplier = getNumber(metadata, 'cfg_rescale_multiplier');
+
+  return cfgRescaleMultiplier !== null && cfgRescaleMultiplier >= 0 && cfgRescaleMultiplier < 1
+    ? cfgRescaleMultiplier
+    : null;
+};
+
+const getScheduler = (metadata: unknown): string | null => {
+  const scheduler = getString(metadata, 'scheduler');
+
+  return scheduler !== null && isKnownScheduler(scheduler) ? scheduler : null;
+};
+
+const getClipSkip = (metadata: unknown): number | null => {
+  const clipSkip = getInteger(metadata, 'clip_skip');
+
+  return clipSkip !== null && clipSkip >= 0 ? clipSkip : null;
+};
+
+const getClipSkipMax = (model: GenerateModelConfig): number | null =>
+  getGenerationUiPolicy(model, { cfgScale: 1 }).clipSkipMax;
+
+const getImageSize = (
+  image: GalleryImage,
+  model: GenerateModelConfig
+): Pick<GenerateWidgetValues, 'height' | 'width'> | null => {
+  const grid = getGenerationDimensions(model).grid;
+  const width = getImageDimension(image, 'width', grid);
+  const height = getImageDimension(image, 'height', grid);
+
+  return width !== null && height !== null ? { height, width } : null;
+};
+
+const getMetadataSize = (
+  metadata: unknown,
+  model: GenerateModelConfig
+): Partial<Pick<GenerateWidgetValues, 'height' | 'width'>> => {
+  const grid = getGenerationDimensions(model).grid;
+  const width = getDimension(metadata, 'width', grid);
+  const height = getDimension(metadata, 'height', grid);
+
+  return {
+    ...(width !== null ? { width } : {}),
+    ...(height !== null ? { height } : {}),
+  };
+};
+
+const getMetadataModelKey = (metadata: unknown, key: 'model' | 'vae'): string | null => {
+  const model = getRecord(metadata, key);
+
+  return typeof model?.key === 'string' ? model.key : null;
+};
+
+const getSupportedMetadataModel = (
+  metadata: unknown,
+  supportedModels: GenerateModelConfig[]
+): GenerateModelConfig | null => {
+  const modelKey = getMetadataModelKey(metadata, 'model');
+
+  return modelKey ? (supportedModels.find((model) => model.key === modelKey) ?? null) : null;
+};
+
+const getModelFromMetadata = <T extends ComponentModelConfig>(
+  metadata: unknown,
+  key: string,
+  models: readonly ComponentModelConfig[],
+  guard: (model: unknown) => model is T
+): T | null | undefined => {
+  if (!isRecord(metadata) || !(key in metadata)) {
+    return undefined;
+  }
+
+  if (metadata[key] === null) {
+    return null;
+  }
+
+  const modelKey = getMetadataModelKey(metadata, key as 'model' | 'vae');
+
+  if (!modelKey) {
+    return undefined;
+  }
+
+  const model = models.find((candidate) => candidate.key === modelKey);
+
+  return guard(model) ? model : undefined;
+};
+
+const getMetadataComponent = (
+  metadata: unknown,
+  key: string,
+  models: readonly ComponentModelConfig[]
+): ComponentModelConfig | null | undefined => getModelFromMetadata(metadata, key, models, isModelIdentifierConfig);
+
+const getMetadataMainModel = (
+  metadata: unknown,
+  key: string,
+  models: readonly ComponentModelConfig[]
+): MainModelConfig | null | undefined => getModelFromMetadata(metadata, key, models, isMainModelConfig);
+
+const getMetadataVae = (
+  metadata: unknown,
+  model: GenerateModelConfig,
+  vaeModels: VaeModelConfig[]
+): VaeModelConfig | null | undefined => {
+  if (!isRecord(metadata) || !('vae' in metadata)) {
+    return undefined;
+  }
+
+  if (metadata.vae === null) {
+    return null;
+  }
+
+  const vaeKey = getMetadataModelKey(metadata, 'vae');
+
+  if (!vaeKey) {
+    return undefined;
+  }
+
+  const vae = vaeModels.find((vae) => vae.key === vaeKey);
+
+  return vae && isVaeCompatibleWithGenerateModel(model, vae) ? vae : undefined;
+};
+
+const getPromptPatch = (
+  metadata: unknown
+): Partial<Pick<GenerateWidgetValues, 'negativePrompt' | 'positivePrompt'>> => {
+  const positivePrompt = getString(metadata, 'positive_prompt');
+  const negativePrompt = getNullableString(metadata, 'negative_prompt');
+
+  return {
+    ...(positivePrompt !== null ? { positivePrompt } : {}),
+    ...(negativePrompt !== undefined ? { negativePrompt: negativePrompt ?? '' } : {}),
+  };
+};
+
+const hasPrompt = (metadata: unknown): boolean => Object.keys(getPromptPatch(metadata)).length > 0;
+
+const hasMetadataSize = (metadata: unknown, model: GenerateModelConfig): boolean =>
+  Object.keys(getMetadataSize(metadata, model)).length > 0;
+
+const hasGenerationSettings = (metadata: unknown): boolean =>
+  getSteps(metadata) !== null ||
+  getCfgScale(metadata) !== null ||
+  getCfgRescaleMultiplier(metadata) !== null ||
+  getScheduler(metadata) !== null ||
+  getBoolean(metadata, 'seamless_x') !== null ||
+  getBoolean(metadata, 'seamless_y') !== null;
+
+const hasComponentModels = (metadata: unknown, models: readonly ComponentModelConfig[]): boolean =>
+  getMetadataMainModel(metadata, 'qwen3_source', models) !== undefined ||
+  getMetadataMainModel(metadata, 'qwen_image_component_source', models) !== undefined ||
+  getMetadataComponent(metadata, 'qwen3_encoder', models) !== undefined ||
+  getMetadataComponent(metadata, 'qwen_image_qwen_vl_encoder', models) !== undefined;
+
+const getMetadataReferenceImages = (metadata: unknown) =>
+  isRecord(metadata) ? normalizeReferenceImages(metadata.ref_images) : [];
+
+const withDimensions = (
+  values: GenerateWidgetValues,
+  size: Partial<Pick<GenerateWidgetValues, 'height' | 'width'>>
+): GenerateWidgetValues => {
+  const width = size.width ?? values.width;
+  const height = size.height ?? values.height;
+
+  return {
+    ...values,
+    ...size,
+    aspectRatioId: deriveAspectRatioId(width, height),
+    aspectRatioValue: height > 0 ? width / height : 1,
+  };
+};
+
+const getSupportedClipSkip = (metadata: unknown, model: GenerateModelConfig): number | null => {
+  const clipSkip = getClipSkip(metadata);
+  const clipSkipMax = getClipSkipMax(model);
+
+  return clipSkip !== null && clipSkipMax !== null ? Math.min(clipSkipMax, clipSkip) : null;
+};
+
+export const getImageRecallCapabilities = ({
+  currentValues,
+  image,
+  metadata,
+  models,
+  supportedModels,
+  vaeModels,
+}: {
+  currentValues: GenerateWidgetValues;
+  image: GalleryImage;
+  metadata: unknown;
+  supportedModels: GenerateModelConfig[];
+  models: ComponentModelConfig[];
+  vaeModels: VaeModelConfig[];
+}): ImageRecallCapabilities => {
+  const supportedMetadataModel = getSupportedMetadataModel(metadata, supportedModels);
+  const clipSkipModel = supportedMetadataModel ?? currentValues.model;
+  const hasVae = getMetadataVae(metadata, clipSkipModel, vaeModels) !== undefined;
+  const hasClipSkip = getSupportedClipSkip(metadata, clipSkipModel) !== null;
+  const hasSeed = getSeed(metadata) !== null;
+  const hasPrompts = hasPrompt(metadata);
+  const hasSize = hasMetadataSize(metadata, currentValues.model);
+  const hasSettings = hasGenerationSettings(metadata);
+  const hasComponents = hasComponentModels(metadata, models);
+  const hasReferenceImages = getMetadataReferenceImages(metadata).length > 0;
+  const hasModel = supportedMetadataModel !== null;
+  const hasAnyMetadata =
+    hasModel ||
+    hasVae ||
+    hasPrompts ||
+    hasSeed ||
+    hasSize ||
+    hasSettings ||
+    hasClipSkip ||
+    hasComponents ||
+    hasReferenceImages;
+  const hasNonSeedMetadata =
+    hasModel || hasVae || hasPrompts || hasSize || hasSettings || hasClipSkip || hasComponents || hasReferenceImages;
+
+  return {
+    all: hasAnyMetadata,
+    clipSkip: getSupportedClipSkip(metadata, currentValues.model) !== null,
+    dimensions: getImageSize(image, currentValues.model) !== null,
+    prompts: hasPrompts,
+    remix: hasNonSeedMetadata,
+    seed: hasSeed,
+  };
+};
+
+export const buildImageRecallSettings = ({
+  currentValues,
+  image,
+  kind,
+  metadata,
+  supportedModels,
+  models,
+  vaeModels,
+}: {
+  currentValues: GenerateWidgetValues;
+  image: GalleryImage;
+  kind: ImageRecallKind;
+  metadata: unknown;
+  supportedModels: GenerateModelConfig[];
+  models: ComponentModelConfig[];
+  vaeModels: VaeModelConfig[];
+}): ImageRecallResult | null => {
+  const fields: RecalledField[] = [];
+  let values: GenerateWidgetValues = cloneGenerateWidgetValues(currentValues);
+
+  if (kind === 'all' || kind === 'remix') {
+    const model = getSupportedMetadataModel(metadata, supportedModels);
+
+    if (model) {
+      const valuesWithModelDefaults = getSettingsWithModelDefaults(values, model);
+      values = {
+        ...valuesWithModelDefaults,
+        model,
+        ...(hasModelDefaultVae(model) ? { vae: getModelDefaultVae(model, vaeModels) } : {}),
+      };
+      fields.push('model');
+    }
+
+    const qwen3SourceModel = getMetadataMainModel(metadata, 'qwen3_source', models);
+    const qwenImageSourceModel = getMetadataMainModel(metadata, 'qwen_image_component_source', models);
+    const componentSourceModel = qwen3SourceModel !== undefined ? qwen3SourceModel : qwenImageSourceModel;
+    const qwen3EncoderModel = getMetadataComponent(metadata, 'qwen3_encoder', models);
+    const qwenVLEncoderModel = getMetadataComponent(metadata, 'qwen_image_qwen_vl_encoder', models);
+    const componentPatch = {
+      componentSourceModel: componentSourceModel !== undefined ? componentSourceModel : values.componentSourceModel,
+      qwen3EncoderModel: qwen3EncoderModel !== undefined ? qwen3EncoderModel : values.qwen3EncoderModel,
+      qwenVLEncoderModel: qwenVLEncoderModel !== undefined ? qwenVLEncoderModel : values.qwenVLEncoderModel,
+    };
+
+    if (
+      componentPatch.componentSourceModel !== values.componentSourceModel ||
+      componentPatch.qwen3EncoderModel !== values.qwen3EncoderModel ||
+      componentPatch.qwenVLEncoderModel !== values.qwenVLEncoderModel
+    ) {
+      values = { ...values, ...componentPatch };
+      fields.push('components');
+    }
+
+    const vae = getMetadataVae(metadata, values.model, vaeModels);
+
+    if (vae !== undefined) {
+      values = { ...values, vae };
+      fields.push('vae');
+    }
+
+    // Recalled reference images must fit the effective model — when the
+    // metadata model was not recalled (e.g. uninstalled), `values.model` is
+    // still the current one and incompatible configs are re-targeted or dropped.
+    const referenceImages = getCompatibleReferenceImages(getMetadataReferenceImages(metadata), values.model, models);
+
+    if (referenceImages.length > 0) {
+      values = { ...values, referenceImages };
+      fields.push('referenceImages');
+    }
+  }
+
+  if (kind === 'all' || kind === 'remix' || kind === 'prompts') {
+    const promptPatch = getPromptPatch(metadata);
+
+    if (Object.keys(promptPatch).length > 0) {
+      values = { ...values, ...promptPatch };
+      fields.push('prompts');
+    }
+  }
+
+  if (kind === 'all' || kind === 'seed') {
+    const seed = getSeed(metadata);
+
+    if (seed !== null) {
+      values = { ...values, seed, shouldRandomizeSeed: false };
+      fields.push('seed');
+    }
+  }
+
+  if (kind === 'dimensions') {
+    const size = getImageSize(image, values.model);
+
+    if (size) {
+      values = withDimensions(values, size);
+      fields.push('size');
+    }
+  } else if (kind === 'all' || kind === 'remix') {
+    const size = getMetadataSize(metadata, values.model);
+
+    if (Object.keys(size).length > 0) {
+      values = withDimensions(values, size);
+      fields.push('size');
+    }
+  }
+
+  if (kind === 'all' || kind === 'remix') {
+    const steps = getSteps(metadata);
+    const cfgScale = getCfgScale(metadata);
+    const cfgRescaleMultiplier = getCfgRescaleMultiplier(metadata);
+    const scheduler = getScheduler(metadata);
+    const seamlessXAxis = getBoolean(metadata, 'seamless_x');
+    const seamlessYAxis = getBoolean(metadata, 'seamless_y');
+
+    if (steps !== null) {
+      values = { ...values, steps };
+      fields.push('steps');
+    }
+
+    if (cfgScale !== null || cfgRescaleMultiplier !== null) {
+      values = {
+        ...values,
+        ...(cfgScale !== null ? { cfgScale } : {}),
+        ...(cfgRescaleMultiplier !== null ? { cfgRescaleMultiplier } : {}),
+      };
+      fields.push('cfg');
+    }
+
+    if (scheduler !== null) {
+      values = { ...values, scheduler };
+      fields.push('scheduler');
+    }
+
+    if (seamlessXAxis !== null || seamlessYAxis !== null) {
+      values = {
+        ...values,
+        ...(seamlessXAxis !== null ? { seamlessXAxis } : {}),
+        ...(seamlessYAxis !== null ? { seamlessYAxis } : {}),
+      };
+      fields.push('seamless');
+    }
+  }
+
+  if (kind === 'all' || kind === 'remix' || kind === 'clipSkip') {
+    const clipSkip = getSupportedClipSkip(metadata, values.model);
+
+    if (clipSkip !== null) {
+      values = { ...values, clipSkip };
+      fields.push('clipSkip');
+    }
+  }
+
+  return fields.length > 0 ? { fields, values } : null;
+};
+
+export const getImageRecallTitle = (kind: ImageRecallKind): string => {
+  switch (kind) {
+    case 'all':
+      return 'Recalled image metadata';
+    case 'remix':
+      return 'Recalled remix settings';
+    case 'prompts':
+      return 'Recalled prompts';
+    case 'seed':
+      return 'Recalled seed';
+    case 'dimensions':
+      return 'Recalled image size';
+    case 'clipSkip':
+      return 'Recalled CLIP skip';
+  }
+};
+
+export const getImageRecallMessage = (fields: RecalledField[]): string =>
+  `${fields.length} field${fields.length === 1 ? '' : 's'} applied to Generate.`;
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/index.ts b/invokeai/frontend/webv2/src/workbench/image-actions/index.ts
new file mode 100644
index 00000000000..9e1417d6c11
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/index.ts
@@ -0,0 +1,19 @@
+export {
+  ImageContextMenu,
+  getImageContextMenuImages,
+  getImageContextMenuRecallRequestKey,
+  type ImageContextMenuTarget,
+} from './ImageContextMenu';
+export {
+  buildImageRecallSettings,
+  EMPTY_IMAGE_RECALL_CAPABILITIES,
+  getImageRecallCapabilities,
+  getImageRecallMessage,
+  getImageRecallTitle,
+  type ImageRecallCapabilities,
+  type ImageRecallKind,
+  type ImageRecallResult,
+} from './imageRecall';
+export { executeImageRecall, getCurrentGenerateValues } from './executeImageRecall';
+export { getSelectedGalleryImage, getSelectedGalleryImageFromValues } from './selectedImage';
+export { saveBlobToDisk, useImageActions, type ImageActions } from './useImageActions';
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/selectedImage.test.ts b/invokeai/frontend/webv2/src/workbench/image-actions/selectedImage.test.ts
new file mode 100644
index 00000000000..8096ef5a34e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/selectedImage.test.ts
@@ -0,0 +1,36 @@
+import type { GeneratedImageContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { getSelectedGalleryImageFromValues } from './selectedImage';
+
+const image: GeneratedImageContract = {
+  height: 768,
+  imageName: 'selected.png',
+  imageUrl: '/selected.png',
+  queuedAt: '2026-06-19T00:00:00.000Z',
+  sourceQueueItemId: 'queue-item',
+  thumbnailUrl: '/selected-thumb.png',
+  width: 512,
+};
+
+describe('getSelectedGalleryImageFromValues', () => {
+  it('normalizes the stored selected image for shared image actions', () => {
+    expect(getSelectedGalleryImageFromValues({ selectedBoardId: 'board-1', selectedImage: image })).toMatchObject({
+      boardId: 'board-1',
+      imageCategory: 'general',
+      imageName: 'selected.png',
+      starred: false,
+    });
+  });
+
+  it('falls back to recent images by selected name', () => {
+    expect(
+      getSelectedGalleryImageFromValues({
+        recentImages: [image],
+        selectedBoardId: 'board-1',
+        selectedImageName: image.imageName,
+      })
+    )?.toMatchObject({ imageName: 'selected.png' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/selectedImage.ts b/invokeai/frontend/webv2/src/workbench/image-actions/selectedImage.ts
new file mode 100644
index 00000000000..e2c6812e4ca
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/selectedImage.ts
@@ -0,0 +1,36 @@
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { GeneratedImageContract, Project } from '@workbench/types';
+
+import { getProjectWidgetValues } from '@workbench/widgetState';
+
+const isGeneratedImage = (value: unknown): value is GeneratedImageContract =>
+  Boolean(value) && typeof value === 'object' && typeof (value as GeneratedImageContract).imageName === 'string';
+
+const toGalleryImage = (
+  image: GeneratedImageContract & Partial<GalleryImage>,
+  galleryValues: Record<string, unknown>
+): GalleryImage => ({
+  ...image,
+  boardId:
+    image.boardId ?? (typeof galleryValues.selectedBoardId === 'string' ? galleryValues.selectedBoardId : 'none'),
+  imageCategory: image.imageCategory ?? 'general',
+  starred: image.starred ?? false,
+});
+
+export const getSelectedGalleryImageFromValues = (galleryValues: Record<string, unknown>): GalleryImage | null => {
+  if (isGeneratedImage(galleryValues.selectedImage)) {
+    return toGalleryImage(galleryValues.selectedImage, galleryValues);
+  }
+
+  const selectedImageName =
+    typeof galleryValues.selectedImageName === 'string' ? galleryValues.selectedImageName : null;
+  const recentImages = Array.isArray(galleryValues.recentImages) ? galleryValues.recentImages : [];
+  const recentImage = recentImages.find(
+    (image): image is GeneratedImageContract => isGeneratedImage(image) && image.imageName === selectedImageName
+  );
+
+  return recentImage ? toGalleryImage(recentImage, galleryValues) : null;
+};
+
+export const getSelectedGalleryImage = (project: Project): GalleryImage | null =>
+  getSelectedGalleryImageFromValues(getProjectWidgetValues(project, 'gallery'));
diff --git a/invokeai/frontend/webv2/src/workbench/image-actions/useImageActions.ts b/invokeai/frontend/webv2/src/workbench/image-actions/useImageActions.ts
new file mode 100644
index 00000000000..ea4b5d38f7e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/image-actions/useImageActions.ts
@@ -0,0 +1,355 @@
+import type { VaeModelConfig } from '@workbench/generation/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import { importGalleryImagesToCanvas, type GalleryCanvasImportDestination } from '@workbench/canvas-operations/api';
+import { getCanvasImportNotice } from '@workbench/canvas-operations/canvasImportNotice';
+import { getEngine } from '@workbench/canvas-operations/engineRegistry';
+import {
+  addImagesToGalleryBoard,
+  deleteGalleryImages,
+  downloadGalleryArchive,
+  getGalleryImageMetadata,
+  removeImagesFromGalleryBoard,
+  starGalleryImages,
+  unstarGalleryImages,
+  type GalleryBoard,
+  type GalleryImage,
+} from '@workbench/gallery/api';
+import {
+  createReferenceImageId,
+  getDefaultReferenceImageConfig,
+  getMaxReferenceImages,
+  isReferenceImageSupported,
+  isSupportedGenerateModel,
+} from '@workbench/generation/baseGenerationPolicies';
+import { isVaeModelConfig } from '@workbench/generation/settings';
+import { ensureModelsLoaded, useModelsSelector } from '@workbench/models/modelsStore';
+import { useOpenWorkbenchWidget } from '@workbench/useOpenWorkbenchWidget';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useEffect, useMemo, type Dispatch } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { recordCanvasImportError } from './canvasImportError';
+import { executeImageRecall, getCurrentGenerateValues } from './executeImageRecall';
+import {
+  EMPTY_IMAGE_RECALL_CAPABILITIES,
+  getImageRecallCapabilities,
+  type ImageRecallCapabilities,
+  type ImageRecallKind,
+} from './imageRecall';
+
+/**
+ * Image operations shared by every surface that shows backend images (gallery
+ * grid, preview, image context menus). Each mutation notifies the gallery via
+ * a refresh action so any mounted gallery widget refetches affected backend data.
+ */
+export interface ImageActions {
+  /** Whether the generate widget's current model can accept another reference image. */
+  canUseAsReferenceImage: boolean;
+  copyImage: (image: GalleryImage) => Promise<void>;
+  deleteImages: (imageNames: string[]) => Promise<void>;
+  downloadImage: (image: GalleryImage) => Promise<void>;
+  downloadImages: (imageNames: string[]) => Promise<void>;
+  getImageRecallCapabilities: (image: GalleryImage) => Promise<ImageRecallCapabilities>;
+  moveImagesToBoard: (imageNames: string[], boardId: string) => Promise<void>;
+  openImageInPreview: (image: GalleryImage) => void;
+  recallImageData: (image: GalleryImage, kind: ImageRecallKind) => Promise<void>;
+  selectForCompare: (image: GalleryImage) => void;
+  sendToCanvas: (images: readonly GalleryImage[], destination: GalleryCanvasImportDestination) => Promise<void>;
+  setImagesStarred: (imageNames: string[], starred: boolean) => Promise<void>;
+  useAsReferenceImage: (image: GalleryImage) => void;
+}
+
+export const saveBlobToDisk = (blob: Blob, fileName: string): void => {
+  const objectUrl = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+
+  anchor.href = objectUrl;
+  anchor.download = fileName;
+  anchor.click();
+  URL.revokeObjectURL(objectUrl);
+};
+
+const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+const toPngBlob = async (blob: Blob): Promise<Blob> => {
+  if (blob.type === 'image/png') {
+    return blob;
+  }
+
+  const bitmap = await createImageBitmap(blob);
+  const canvas = document.createElement('canvas');
+  canvas.width = bitmap.width;
+  canvas.height = bitmap.height;
+  canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((pngBlob) => (pngBlob ? resolve(pngBlob) : reject(new Error('Failed to encode PNG.'))), 'image/png');
+  });
+};
+
+export const useImageActions = ({
+  boards,
+  dispatch,
+  generateValues,
+  onImagesDeleted,
+  onStarredChange,
+  projectId,
+}: {
+  boards: GalleryBoard[];
+  dispatch: Dispatch<WorkbenchAction>;
+  generateValues: Record<string, unknown>;
+  projectId?: string;
+  /** Called after a successful deletion so the host can select a neighboring image. */
+  onImagesDeleted?: (imageNames: string[]) => void;
+  /** Optional optimistic hook, called before the request and re-called inverted on failure. */
+  onStarredChange?: (imageNames: string[], starred: boolean) => void;
+}): ImageActions => {
+  const openWorkbenchWidget = useOpenWorkbenchWidget();
+  const store = useWorkbenchStore();
+  const { t } = useTranslation();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const supportedModels = useMemo(() => models.filter(isSupportedGenerateModel), [models]);
+  const vaeModels = useMemo(() => models.filter(isVaeModelConfig).map((model) => model as VaeModelConfig), [models]);
+  const currentGenerateValues = useMemo(() => {
+    return getCurrentGenerateValues({ generateValues, supportedModels });
+  }, [generateValues, supportedModels]);
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  return useMemo<ImageActions>(() => {
+    const recordError = (error: unknown) =>
+      dispatch({
+        area: 'image-actions',
+        message: toErrorMessage(error),
+        namespace: 'gallery',
+        projectId,
+        type: 'recordError',
+      });
+    const recordSuccess = (title: string, message?: string) =>
+      dispatch({ kind: 'success', message, title, type: 'recordNotice' });
+    const refreshGallery = () => dispatch({ projectId, type: 'touchGalleryRefresh' });
+    const refreshGalleryImages = () => dispatch({ projectId, type: 'touchGalleryImagesRefresh' });
+    const getBoardName = (boardId: string) => boards.find((board) => board.id === boardId)?.name ?? 'Uncategorized';
+    const getLatestGenerateValues = () => {
+      const snapshot = store.getSnapshot();
+      const project = projectId
+        ? snapshot.state.projects.find((candidate) => candidate.id === projectId)
+        : snapshot.activeProject;
+
+      return project ? getProjectWidgetValues(project, 'generate') : {};
+    };
+
+    return {
+      copyImage: async (image) => {
+        try {
+          const response = await fetch(image.imageUrl);
+          const blob = await toPngBlob(await response.blob());
+
+          await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })]);
+          recordSuccess('Copied image to clipboard');
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      deleteImages: async (imageNames) => {
+        try {
+          await deleteGalleryImages(imageNames);
+          dispatch({ imageNames, projectId, type: 'removeGalleryImages' });
+          onImagesDeleted?.(imageNames);
+          recordSuccess(imageNames.length === 1 ? 'Deleted image' : `Deleted ${imageNames.length} images`);
+          refreshGallery();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      downloadImage: async (image) => {
+        try {
+          const response = await fetch(image.imageUrl);
+          const objectUrl = URL.createObjectURL(await response.blob());
+          const anchor = document.createElement('a');
+
+          anchor.href = objectUrl;
+          anchor.download = image.imageName;
+          anchor.click();
+          URL.revokeObjectURL(objectUrl);
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      downloadImages: async (imageNames) => {
+        try {
+          dispatch({
+            kind: 'info',
+            message: `Preparing an archive of ${imageNames.length} images.`,
+            title: 'Preparing download',
+            type: 'recordNotice',
+          });
+
+          const { blob, fileName } = await downloadGalleryArchive({ imageNames });
+
+          saveBlobToDisk(blob, fileName);
+          recordSuccess('Download ready');
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      getImageRecallCapabilities: async (image) => {
+        if (!currentGenerateValues) {
+          return EMPTY_IMAGE_RECALL_CAPABILITIES;
+        }
+
+        try {
+          const metadata = await getGalleryImageMetadata(image.imageName);
+
+          return getImageRecallCapabilities({
+            currentValues: currentGenerateValues,
+            image,
+            metadata,
+            models,
+            supportedModels,
+            vaeModels,
+          });
+        } catch {
+          return {
+            ...EMPTY_IMAGE_RECALL_CAPABILITIES,
+            dimensions:
+              Number.isFinite(image.width) && image.width >= 64 && Number.isFinite(image.height) && image.height >= 64,
+          };
+        }
+      },
+      moveImagesToBoard: async (imageNames, boardId) => {
+        try {
+          if (boardId === 'none') {
+            await removeImagesFromGalleryBoard(imageNames);
+          } else {
+            await addImagesToGalleryBoard(boardId, imageNames);
+          }
+
+          recordSuccess(
+            imageNames.length === 1
+              ? `Moved image to ${getBoardName(boardId)}`
+              : `Moved ${imageNames.length} images to ${getBoardName(boardId)}`
+          );
+          refreshGallery();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      openImageInPreview: (image) => {
+        dispatch({ image, projectId, type: 'selectGalleryImage' });
+        openWorkbenchWidget('preview', { preferredRegions: ['center'], requireCenterView: true });
+      },
+      recallImageData: async (image, kind) => {
+        const didRecall = await executeImageRecall({
+          dispatch,
+          generateValues,
+          getGenerateValues: getLatestGenerateValues,
+          image,
+          kind,
+          models,
+          projectId,
+        });
+
+        if (didRecall && (!projectId || store.getSnapshot().activeProject.id === projectId)) {
+          openWorkbenchWidget('generate', { preferredRegions: ['left'] });
+        }
+      },
+      selectForCompare: (image) => {
+        dispatch({ image, projectId, type: 'setGalleryCompareImage' });
+      },
+      sendToCanvas: async (images, destination) => {
+        try {
+          const state = store.getState();
+          const targetProjectId = projectId ?? state.activeProjectId;
+          const project = state.projects.find((candidate) => candidate.id === targetProjectId);
+
+          if (!project) {
+            const notice = getCanvasImportNotice({ status: 'stale-project' });
+            dispatch({ kind: notice.kind, title: t(notice.titleKey, notice.options ?? {}), type: 'recordNotice' });
+            return;
+          }
+
+          const result = await importGalleryImagesToCanvas({
+            destination,
+            dispatch,
+            engine: getEngine(project.id) ?? null,
+            getState: store.getState,
+            images,
+            project,
+          });
+          const notice = getCanvasImportNotice(result);
+          dispatch({ kind: notice.kind, title: t(notice.titleKey, notice.options ?? {}), type: 'recordNotice' });
+
+          if (result.status === 'imported' && store.getState().activeProjectId === project.id) {
+            openWorkbenchWidget('canvas', { preferredRegions: ['center'], requireCenterView: true });
+          }
+        } catch (error: unknown) {
+          recordCanvasImportError({
+            dispatch,
+            error,
+            localizedMessage: t('widgets.canvas.import.failed'),
+            projectId,
+          });
+        }
+      },
+      setImagesStarred: async (imageNames, starred) => {
+        onStarredChange?.(imageNames, starred);
+
+        try {
+          await (starred ? starGalleryImages : unstarGalleryImages)(imageNames);
+          refreshGalleryImages();
+        } catch (error: unknown) {
+          onStarredChange?.(imageNames, !starred);
+          recordError(error);
+        }
+      },
+      canUseAsReferenceImage: Boolean(
+        currentGenerateValues &&
+        currentGenerateValues.referenceImages.length < getMaxReferenceImages(currentGenerateValues.model)
+      ),
+      useAsReferenceImage: (image) => {
+        const latestGenerateValues = getLatestGenerateValues();
+        const currentValues = getCurrentGenerateValues({ generateValues: latestGenerateValues, supportedModels });
+
+        if (
+          !currentValues ||
+          !isReferenceImageSupported(currentValues.model) ||
+          currentValues.referenceImages.length >= getMaxReferenceImages(currentValues.model)
+        ) {
+          return;
+        }
+
+        const referenceImage = {
+          config: getDefaultReferenceImageConfig(currentValues.model, models, image),
+          id: createReferenceImageId(),
+          isEnabled: true,
+        };
+
+        dispatch({
+          projectId,
+          type: 'patchGenerateSettings',
+          values: { referenceImages: [...currentValues.referenceImages, referenceImage] },
+        });
+        openWorkbenchWidget('generate', { preferredRegions: ['left'] });
+      },
+    };
+  }, [
+    boards,
+    currentGenerateValues,
+    dispatch,
+    generateValues,
+    models,
+    onImagesDeleted,
+    onStarredChange,
+    openWorkbenchWidget,
+    projectId,
+    store,
+    supportedModels,
+    t,
+    vaeModels,
+  ]);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/images/StreamingImageFrame.tsx b/invokeai/frontend/webv2/src/workbench/images/StreamingImageFrame.tsx
new file mode 100644
index 00000000000..a8228b51aa1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/images/StreamingImageFrame.tsx
@@ -0,0 +1,47 @@
+import { Box, type BoxProps } from '@chakra-ui/react';
+import { useMemo, type CSSProperties, type ReactNode } from 'react';
+
+import type { StreamingImageSource } from './streamingImageSource';
+
+import { useStreamingImageSource } from './useStreamingImageSource';
+
+export const StreamingImageFrame = ({
+  badge,
+  fallbackImage,
+  finalImage,
+  fit = 'cover',
+  liveImage,
+  shouldAntialiasLiveImage = true,
+  children,
+  ...boxProps
+}: {
+  badge?: ReactNode | ((source: StreamingImageSource) => ReactNode);
+  fallbackImage?: StreamingImageSource | null;
+  finalImage?: StreamingImageSource | null;
+  fit?: 'contain' | 'cover';
+  liveImage?: StreamingImageSource | null;
+  shouldAntialiasLiveImage?: boolean;
+} & BoxProps) => {
+  const source = useStreamingImageSource({ fallbackImage, finalImage, liveImage });
+  const renderedBadge: ReactNode = typeof badge === 'function' ? (source ? badge(source) : null) : badge;
+  const imageStyle = useMemo<CSSProperties>(
+    () => ({
+      display: 'block',
+      height: '100%',
+      imageRendering: source?.kind === 'live' && !shouldAntialiasLiveImage ? 'pixelated' : 'auto',
+      inset: 0,
+      maxWidth: 'none',
+      objectFit: fit,
+      position: 'absolute',
+      width: '100%',
+    }),
+    [fit, shouldAntialiasLiveImage, source?.kind]
+  );
+
+  return (
+    <Box overflow="hidden" position="relative" {...boxProps}>
+      {source ? <img alt={source.alt} draggable={false} src={source.src} style={imageStyle} /> : children}
+      {renderedBadge}
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/images/streamingImageSource.test.ts b/invokeai/frontend/webv2/src/workbench/images/streamingImageSource.test.ts
new file mode 100644
index 00000000000..0fdb55fbcc1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/images/streamingImageSource.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  mergeDenoiseProgressImage,
+  progressImageToStreamingSource,
+  resolveStreamingImageSource,
+  type DenoiseProgressImage,
+  type StreamingImageSource,
+} from './streamingImageSource';
+
+const liveImage: StreamingImageSource = {
+  alt: 'Live preview',
+  height: 32,
+  kind: 'live',
+  src: 'data:image/png;base64,live',
+  width: 64,
+};
+const heldLiveImage: StreamingImageSource = {
+  alt: 'Held preview',
+  height: 32,
+  kind: 'live',
+  src: 'data:image/png;base64,held',
+  width: 64,
+};
+const finalImage: StreamingImageSource = {
+  alt: 'Final image',
+  height: 512,
+  kind: 'final',
+  src: '/api/final.png',
+  width: 512,
+};
+const fallbackImage: StreamingImageSource = {
+  alt: 'Fallback image',
+  height: 512,
+  kind: 'fallback',
+  src: '/api/fallback.png',
+  width: 512,
+};
+
+describe('resolveStreamingImageSource', () => {
+  it('prioritizes final images over live and fallback images', () => {
+    expect(resolveStreamingImageSource({ fallbackImage, finalImage, heldLiveImage, liveImage })).toBe(finalImage);
+  });
+
+  it('uses the current live image before a held live image', () => {
+    expect(resolveStreamingImageSource({ fallbackImage, heldLiveImage, liveImage })).toBe(liveImage);
+  });
+
+  it('keeps the held live image while waiting for final image data', () => {
+    expect(resolveStreamingImageSource({ fallbackImage, heldLiveImage })).toBe(heldLiveImage);
+  });
+
+  it('falls back when no final or live image is available', () => {
+    expect(resolveStreamingImageSource({ fallbackImage })).toBe(fallbackImage);
+  });
+});
+
+describe('mergeDenoiseProgressImage', () => {
+  it('keeps the previous denoise image when the next update is omitted', () => {
+    const previous: DenoiseProgressImage = { dataUrl: 'data:image/png;base64,old', height: 32, width: 64 };
+
+    expect(mergeDenoiseProgressImage(previous, undefined)).toBe(previous);
+  });
+
+  it('replaces the previous denoise image when a next update is provided', () => {
+    const previous: DenoiseProgressImage = { dataUrl: 'data:image/png;base64,old', height: 32, width: 64 };
+    const next: DenoiseProgressImage = { dataUrl: 'data:image/png;base64,next', height: 48, width: 96 };
+
+    expect(mergeDenoiseProgressImage(previous, next)).toBe(next);
+  });
+
+  it('clears the previous denoise image when the next update is null', () => {
+    const previous: DenoiseProgressImage = { dataUrl: 'data:image/png;base64,old', height: 32, width: 64 };
+
+    expect(mergeDenoiseProgressImage(previous, null)).toBeNull();
+  });
+});
+
+describe('progressImageToStreamingSource', () => {
+  it('maps a denoise progress image to a live streaming source', () => {
+    expect(
+      progressImageToStreamingSource({ dataUrl: 'data:image/png;base64,abc', height: 32, width: 64 }, 'Preview')
+    ).toEqual({
+      alt: 'Preview',
+      height: 32,
+      kind: 'live',
+      src: 'data:image/png;base64,abc',
+      width: 64,
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/images/streamingImageSource.ts b/invokeai/frontend/webv2/src/workbench/images/streamingImageSource.ts
new file mode 100644
index 00000000000..87de536f6b1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/images/streamingImageSource.ts
@@ -0,0 +1,69 @@
+export type StreamingImageKind = 'fallback' | 'final' | 'live';
+
+export interface DenoiseProgressImage {
+  dataUrl: string;
+  height: number;
+  width: number;
+}
+
+export interface StreamingImageSource {
+  alt: string;
+  height?: number;
+  kind: StreamingImageKind;
+  src: string;
+  width?: number;
+}
+
+export const mergeDenoiseProgressImage = <Image extends DenoiseProgressImage>(
+  previous: Image | null | undefined,
+  next: Image | null | undefined
+): Image | null | undefined => (next === undefined ? previous : next);
+
+export const progressImageToStreamingSource = (
+  image: DenoiseProgressImage | null | undefined,
+  alt = 'In-progress diffusion preview'
+): StreamingImageSource | null =>
+  image
+    ? {
+        alt,
+        height: image.height,
+        kind: 'live',
+        src: image.dataUrl,
+        width: image.width,
+      }
+    : null;
+
+export const imageUrlToStreamingSource = ({
+  alt,
+  height,
+  kind = 'final',
+  src,
+  width,
+}: {
+  alt: string;
+  height?: number;
+  kind?: Exclude<StreamingImageKind, 'live'>;
+  src: string | null | undefined;
+  width?: number;
+}): StreamingImageSource | null =>
+  src
+    ? {
+        alt,
+        height,
+        kind,
+        src,
+        width,
+      }
+    : null;
+
+export const resolveStreamingImageSource = ({
+  fallbackImage,
+  finalImage,
+  heldLiveImage,
+  liveImage,
+}: {
+  fallbackImage?: StreamingImageSource | null;
+  finalImage?: StreamingImageSource | null;
+  heldLiveImage?: StreamingImageSource | null;
+  liveImage?: StreamingImageSource | null;
+}): StreamingImageSource | null => finalImage ?? liveImage ?? heldLiveImage ?? fallbackImage ?? null;
diff --git a/invokeai/frontend/webv2/src/workbench/images/useStreamingImageSource.ts b/invokeai/frontend/webv2/src/workbench/images/useStreamingImageSource.ts
new file mode 100644
index 00000000000..9c84119fc53
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/images/useStreamingImageSource.ts
@@ -0,0 +1,11 @@
+import { resolveStreamingImageSource, type StreamingImageSource } from './streamingImageSource';
+
+export const useStreamingImageSource = ({
+  fallbackImage,
+  finalImage,
+  liveImage,
+}: {
+  fallbackImage?: StreamingImageSource | null;
+  finalImage?: StreamingImageSource | null;
+  liveImage?: StreamingImageSource | null;
+}): StreamingImageSource | null => resolveStreamingImageSource({ fallbackImage, finalImage, liveImage });
diff --git a/invokeai/frontend/webv2/src/workbench/invocation.test.ts b/invokeai/frontend/webv2/src/workbench/invocation.test.ts
new file mode 100644
index 00000000000..09422dac88a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/invocation.test.ts
@@ -0,0 +1,234 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  ComponentModelConfig,
+  GenerateModelConfig,
+  GenerateWidgetValues,
+  MainModelConfig,
+  VaeModelConfig,
+} from './generation/types';
+import type { InvocationRoute, WidgetId } from './types';
+
+import { getDefaultGenerateSettings } from './generation/baseGenerationPolicies';
+import { getInvocationRouteInput, resolveInvocationRoute, resolveInvocationRouteInput } from './invocation';
+import { submitResolvedInvocation } from './invocationSubmit';
+import { createInitialWorkbenchState, workbenchReducer } from './workbenchState';
+
+const animaModel: MainModelConfig = { base: 'anima', key: 'anima-model', name: 'Anima', type: 'main' };
+const animaVae: VaeModelConfig = { base: 'qwen-image', key: 'anima-vae', name: 'Anima VAE', type: 'vae' };
+const flux2Model: MainModelConfig = {
+  base: 'flux2',
+  format: 'gguf_quantized',
+  key: 'flux2-klein-9b',
+  name: 'FLUX.2 Klein 9B',
+  type: 'main',
+  variant: 'klein_9b',
+};
+const incompatibleFlux2Source: MainModelConfig = {
+  base: 'flux2',
+  format: 'diffusers',
+  key: 'flux2-klein-4b-source',
+  name: 'FLUX.2 Klein 4B Source',
+  type: 'main',
+  variant: 'klein_4b',
+};
+const flux2Vae: VaeModelConfig = { base: 'flux2', key: 'flux2-vae', name: 'FLUX.2 VAE', type: 'vae' };
+const flux2Qwen3Encoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'flux2-qwen3-encoder',
+  name: 'Qwen3 8B Encoder',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_8b',
+};
+const qwen3Encoder: ComponentModelConfig = {
+  base: 'any',
+  key: 'qwen3-encoder',
+  name: 'Qwen3 Encoder',
+  type: 'qwen3_encoder',
+  variant: 'qwen3_06b',
+};
+const unknownExternalModel: GenerateModelConfig = {
+  base: 'external',
+  capabilities: { modes: ['txt2img'] },
+  format: 'external_api',
+  key: 'external-unknown',
+  name: 'Unknown External Provider',
+  provider_id: 'future-provider',
+  type: 'external_image_generator',
+};
+
+const createGenerateValues = (
+  model: GenerateModelConfig = animaModel,
+  overrides: Partial<GenerateWidgetValues> = {}
+): GenerateWidgetValues => ({
+  ...getDefaultGenerateSettings(model),
+  model,
+  modelKey: model.key,
+  positivePrompt: 'an anima prompt',
+  ...overrides,
+});
+
+const getActiveProject = (values: GenerateWidgetValues) => {
+  const state = workbenchReducer(createInitialWorkbenchState(), { type: 'setGenerateSettings', values });
+  const project = state.projects.find((candidate) => candidate.id === state.activeProjectId);
+
+  expect(project).toBeDefined();
+
+  return project!;
+};
+
+describe('resolveInvocationRoute', () => {
+  it('invalidates Anima generation until required components are selected', () => {
+    const missingComponentsRoute = resolveInvocationRoute(
+      getActiveProject(createGenerateValues(animaModel, { vae: animaVae }))
+    );
+
+    expect(missingComponentsRoute.sourceValid).toBe(false);
+    expect(missingComponentsRoute.validationReasons).toContain('Generate needs a Qwen3 Encoder for Anima models.');
+
+    const validRoute = resolveInvocationRoute(
+      getActiveProject(createGenerateValues(animaModel, { qwen3EncoderModel: qwen3Encoder, vae: animaVae }))
+    );
+
+    expect(validRoute.sourceValid).toBe(true);
+    expect(validRoute.validationReasons).toEqual([]);
+  });
+
+  it('invalidates non-Diffusers FLUX.2 generation when a stale component source cannot provide the required Qwen3 encoder', () => {
+    const route = resolveInvocationRoute(
+      getActiveProject(
+        createGenerateValues(flux2Model, { componentSourceModel: incompatibleFlux2Source, vae: flux2Vae })
+      )
+    );
+
+    expect(route.sourceValid).toBe(false);
+    expect(route.validationReasons).toContain('Generate needs a Qwen3 Encoder for non-Diffusers FLUX.2 models.');
+  });
+
+  it('invalidates FLUX.2 generation when dimensions are not on the required 16px grid', () => {
+    const route = resolveInvocationRoute(
+      getActiveProject(
+        createGenerateValues(flux2Model, { height: 888, qwen3EncoderModel: flux2Qwen3Encoder, vae: flux2Vae })
+      )
+    );
+
+    expect(route.sourceValid).toBe(false);
+    expect(route.validationReasons).toContain('Generate height must be a multiple of 16.');
+  });
+
+  it('invalidates external providers without a registered invocation node', () => {
+    const route = resolveInvocationRoute(getActiveProject(createGenerateValues(unknownExternalModel)));
+
+    expect(route.sourceValid).toBe(false);
+    expect(route.validationReasons).toContain("No invocation node registered for external provider 'future-provider'.");
+  });
+});
+
+describe('resolveInvocationRoute — canvas source', () => {
+  const canvasRoute: InvocationRoute = {
+    destination: 'canvas',
+    destinationLocked: false,
+    sourceId: 'canvas',
+    sourceLocked: false,
+  };
+
+  const validGenerateValues = createGenerateValues(animaModel, { qwen3EncoderModel: qwen3Encoder, vae: animaVae });
+
+  const canvasInputFor = (
+    overrides: {
+      generateValues?: typeof validGenerateValues;
+      mountedWidgetIds?: WidgetId[];
+      bbox?: { width: number; height: number };
+    } = {}
+  ) => {
+    const project = getActiveProject(overrides.generateValues ?? validGenerateValues);
+
+    return {
+      ...getInvocationRouteInput(project),
+      canvasBbox: overrides.bbox ?? { height: 512, width: 512 },
+      mountedWidgetIds: overrides.mountedWidgetIds ?? (['canvas', 'generate'] as WidgetId[]),
+    };
+  };
+
+  it('is a valid source when the widget is mounted, the model is valid, and the frame has area', () => {
+    const route = resolveInvocationRouteInput(canvasInputFor(), 'global', canvasRoute);
+
+    expect(route.sourceValid).toBe(true);
+    expect(route.validationReasons).toEqual([]);
+  });
+
+  it('invalidates a zero-area generation frame', () => {
+    const route = resolveInvocationRouteInput(
+      canvasInputFor({ bbox: { height: 0, width: 512 } }),
+      'global',
+      canvasRoute
+    );
+
+    expect(route.sourceValid).toBe(false);
+    expect(route.validationReasons).toContain('Canvas generation frame must have a positive area.');
+  });
+
+  it('reuses the generate model validation reasons', () => {
+    const route = resolveInvocationRouteInput(
+      canvasInputFor({ generateValues: createGenerateValues(animaModel, { vae: animaVae }) }),
+      'global',
+      canvasRoute
+    );
+
+    expect(route.sourceValid).toBe(false);
+    expect(route.validationReasons).toContain('Generate needs a Qwen3 Encoder for Anima models.');
+  });
+
+  it('invalidates when the canvas widget is not mounted', () => {
+    const route = resolveInvocationRouteInput(
+      canvasInputFor({ mountedWidgetIds: ['generate'] as WidgetId[] }),
+      'global',
+      canvasRoute
+    );
+
+    expect(route.sourceValid).toBe(false);
+    expect(route.validationReasons).toContain('The Canvas widget is not mounted in this project.');
+  });
+});
+
+describe('submitResolvedInvocation', () => {
+  const routeFor = (project: Parameters<typeof resolveInvocationRoute>[0], route: InvocationRoute) =>
+    resolveInvocationRoute(project, 'global', route);
+
+  it('routes a canvas source through prepareCanvasInvocation and does not dispatch a resolved snapshot', () => {
+    const project = getActiveProject(
+      createGenerateValues(animaModel, { qwen3EncoderModel: qwen3Encoder, vae: animaVae })
+    );
+    const dispatch = vi.fn();
+    const prepareCanvasInvocation = vi.fn();
+    const route = routeFor(project, { ...project.invocation, destination: 'gallery', sourceId: 'canvas' });
+
+    submitResolvedInvocation({ dispatch, models: undefined, prepareCanvasInvocation, project, route });
+
+    expect(dispatch).not.toHaveBeenCalled();
+    expect(prepareCanvasInvocation).toHaveBeenCalledTimes(1);
+    // The resolved destination rides through so a Canvas source can target the Gallery.
+    expect(prepareCanvasInvocation.mock.calls[0]?.[0]).toMatchObject({
+      destination: 'gallery',
+      projectId: project.id,
+    });
+  });
+
+  it('dispatches submitResolvedInvocationSnapshot for a non-canvas source and never prepares the canvas', () => {
+    const project = getActiveProject(
+      createGenerateValues(animaModel, { qwen3EncoderModel: qwen3Encoder, vae: animaVae })
+    );
+    const dispatch = vi.fn();
+    const prepareCanvasInvocation = vi.fn();
+    const route = routeFor(project, { ...project.invocation, destination: 'gallery', sourceId: 'generate' });
+
+    submitResolvedInvocation({ dispatch, models: undefined, prepareCanvasInvocation, project, route });
+
+    expect(prepareCanvasInvocation).not.toHaveBeenCalled();
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch.mock.calls[0]?.[0]).toMatchObject({
+      route: expect.objectContaining({ destination: 'gallery', sourceId: 'generate' }),
+      type: 'submitResolvedInvocationSnapshot',
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/invocation.ts b/invokeai/frontend/webv2/src/workbench/invocation.ts
new file mode 100644
index 00000000000..afb7af86198
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/invocation.ts
@@ -0,0 +1,224 @@
+import type { ModelConfig } from './models/types';
+import type {
+  InvocationMode,
+  InvocationRoute,
+  InvocationSourceId,
+  Project,
+  ResolvedInvocationRoute,
+  ResultDestination,
+  WidgetId,
+} from './types';
+import type { ProjectGraphState } from './workflows/types';
+
+import {
+  getGenerationModelAvailabilityReasons,
+  getGenerationValidationReasons,
+  isSupportedGenerateModel,
+} from './generation/baseGenerationPolicies';
+import { normalizeGenerateWidgetValues } from './generation/settings';
+import { getProjectWidgetValues } from './widgetState';
+import { areArraysEqual, createStableSelector } from './workbenchSelectors';
+import { getProjectGraphReadiness } from './workflows/buildGraph';
+import { getInvocationTemplatesSnapshot } from './workflows/templates';
+
+/**
+ * Static metadata for the Invocation Controller surfaces.
+ *
+ * MVP destinations are limited to Canvas and Gallery per the spec. Sources are
+ * the first-party graph-bearing surfaces; only `generate` is wired in Phase 1,
+ * the rest are declared so the source menu reads as a real (if partly inert)
+ * placeholder for later phases.
+ */
+export interface InvocationSourceMeta {
+  id: InvocationSourceId;
+  label: string;
+  /** Whether the source is selectable yet, or a forward-looking placeholder. */
+  available: boolean;
+}
+
+export interface ResultDestinationMeta {
+  id: ResultDestination;
+  label: string;
+}
+
+export const invocationSources: InvocationSourceMeta[] = [
+  { id: 'generate', label: 'Generate', available: true },
+  { id: 'workflow', label: 'Workflow', available: true },
+  { id: 'upscale', label: 'Upscale', available: false },
+  { id: 'canvas', label: 'Canvas', available: true },
+];
+
+export const resultDestinations: ResultDestinationMeta[] = [
+  { id: 'canvas', label: 'Canvas' },
+  { id: 'gallery', label: 'Gallery' },
+];
+
+const sourceLabels = new Map(invocationSources.map((source) => [source.id, source.label]));
+const destinationLabels = new Map(resultDestinations.map((destination) => [destination.id, destination.label]));
+
+export const getSourceLabel = (id: InvocationSourceId): string => sourceLabels.get(id) ?? 'Generate';
+
+export const isInvocationSourceAvailable = (id: InvocationSourceId): boolean =>
+  invocationSources.some((source) => source.id === id && source.available);
+
+export const getDestinationLabel = (id: ResultDestination): string => destinationLabels.get(id) ?? 'Canvas';
+
+export const formatRoute = (route: InvocationRoute): string =>
+  `${getSourceLabel(route.sourceId)} → ${getDestinationLabel(route.destination)}`;
+
+export const defaultInvocationRoute: InvocationRoute = {
+  sourceId: 'generate',
+  destination: 'canvas',
+  sourceLocked: false,
+  destinationLocked: false,
+};
+
+const validDestinationIds = new Set(resultDestinations.map((destination) => destination.id));
+
+const sourceWidgetIds: Partial<Record<InvocationSourceId, WidgetId>> = {
+  canvas: 'canvas',
+  generate: 'generate',
+  workflow: 'workflow',
+};
+
+export interface InvocationRouteInput {
+  generateValues: Record<string, unknown>;
+  invocation: InvocationRoute;
+  mountedWidgetIds: readonly WidgetId[];
+  projectGraph: ProjectGraphState;
+  projectId: string;
+  /** The canvas generation frame (document space) — its area gates a canvas invoke. */
+  canvasBbox: { width: number; height: number };
+}
+
+const getMountedWidgetIds = (project: Project): WidgetId[] => {
+  const mountedWidgetIds = new Set<WidgetId>();
+
+  for (const region of Object.values(project.widgetRegions)) {
+    for (const instanceId of region.instanceIds) {
+      const widgetId = project.widgetInstances[instanceId]?.typeId;
+
+      if (widgetId) {
+        mountedWidgetIds.add(widgetId);
+      }
+    }
+  }
+
+  return Array.from(mountedWidgetIds).sort();
+};
+
+export const getInvocationRouteInput = (project: Project): InvocationRouteInput => ({
+  canvasBbox: {
+    height: project.canvas.document.bbox.height,
+    width: project.canvas.document.bbox.width,
+  },
+  generateValues: getProjectWidgetValues(project, 'generate'),
+  invocation: project.invocation,
+  mountedWidgetIds: getMountedWidgetIds(project),
+  projectGraph: project.projectGraph,
+  projectId: project.id,
+});
+
+export const areInvocationRouteInputsEqual = (left: InvocationRouteInput, right: InvocationRouteInput): boolean =>
+  left.projectId === right.projectId &&
+  left.invocation === right.invocation &&
+  left.projectGraph === right.projectGraph &&
+  left.generateValues === right.generateValues &&
+  left.canvasBbox.width === right.canvasBbox.width &&
+  left.canvasBbox.height === right.canvasBbox.height &&
+  areArraysEqual(left.mountedWidgetIds, right.mountedWidgetIds);
+
+export const createInvocationRouteInputSelector = () =>
+  createStableSelector(getInvocationRouteInput, areInvocationRouteInputsEqual);
+
+const isWidgetMounted = (input: InvocationRouteInput, widgetId: WidgetId): boolean =>
+  input.mountedWidgetIds.includes(widgetId);
+
+const getGenerateSnapshotValidationReasons = (
+  generateValues: Record<string, unknown>,
+  models?: readonly ModelConfig[]
+): string[] => {
+  const values = normalizeGenerateWidgetValues(generateValues);
+
+  if (!values || !isSupportedGenerateModel(values.model)) {
+    return ['Generate needs a supported model before it can be invoked.'];
+  }
+
+  return [
+    ...getGenerationValidationReasons(values.model, values),
+    ...(models ? getGenerationModelAvailabilityReasons(values.model, values, models) : []),
+  ];
+};
+
+export const isResultDestinationAvailable = (destination: ResultDestination): boolean =>
+  validDestinationIds.has(destination);
+
+export const resolveInvocationRoute = (
+  project: Project,
+  mode: InvocationMode = 'global',
+  route: InvocationRoute = project.invocation,
+  models?: readonly ModelConfig[]
+): ResolvedInvocationRoute => resolveInvocationRouteInput(getInvocationRouteInput(project), mode, route, models);
+
+export const resolveInvocationRouteInput = (
+  input: InvocationRouteInput,
+  mode: InvocationMode = 'global',
+  route: InvocationRoute = input.invocation,
+  models?: readonly ModelConfig[]
+): ResolvedInvocationRoute => {
+  const sourceId = route.sourceId;
+  const destination = route.destination;
+  const sourceWidgetId = sourceWidgetIds[sourceId];
+  // The project graph validates against its compiled readiness; templates are
+  // read imperatively, and surfaces that render the route subscribe to the
+  // templates store so the result stays live.
+  const projectGraphReadiness =
+    sourceId === 'workflow' ? getProjectGraphReadiness(input.projectGraph, getInvocationTemplatesSnapshot()) : null;
+  const validationReasons: string[] = [];
+
+  if (!isInvocationSourceAvailable(sourceId)) {
+    validationReasons.push(`${getSourceLabel(sourceId)} is not an available invocation source.`);
+  } else if (sourceWidgetId && !isWidgetMounted(input, sourceWidgetId)) {
+    validationReasons.push(`The ${getSourceLabel(sourceId)} widget is not mounted in this project.`);
+  }
+
+  if (sourceId === 'generate') {
+    validationReasons.push(...getGenerateSnapshotValidationReasons(input.generateValues, models));
+  }
+
+  if (sourceId === 'canvas') {
+    // Canvas shares the generate model/prompt/steps, so reuse those reasons, then
+    // require a non-degenerate generation frame (a zero-area bbox has nothing to
+    // generate into and the graph compiler would reject it anyway).
+    validationReasons.push(...getGenerateSnapshotValidationReasons(input.generateValues, models));
+
+    if (input.canvasBbox.width <= 0 || input.canvasBbox.height <= 0) {
+      validationReasons.push('Canvas generation frame must have a positive area.');
+    }
+  }
+
+  if (projectGraphReadiness && !projectGraphReadiness.canInvoke) {
+    validationReasons.push(...projectGraphReadiness.reasons);
+  }
+
+  const sourceValid = validationReasons.length === 0;
+  const destinationValid = isResultDestinationAvailable(destination);
+
+  if (!destinationValid) {
+    validationReasons.push(`${getDestinationLabel(destination)} is not an available result destination.`);
+  }
+
+  return {
+    ...route,
+    destination,
+    destinationValid,
+    mode,
+    sourceId,
+    sourceValid,
+    validationMessage: validationReasons[0],
+    validationReasons,
+  };
+};
+
+export const isInvocationRouteValid = (route: ResolvedInvocationRoute): boolean =>
+  route.sourceValid && route.destinationValid;
diff --git a/invokeai/frontend/webv2/src/workbench/invocationSubmit.ts b/invokeai/frontend/webv2/src/workbench/invocationSubmit.ts
new file mode 100644
index 00000000000..e613ceb75f0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/invocationSubmit.ts
@@ -0,0 +1,73 @@
+/**
+ * The single canvas-vs-generate submit decision, shared by the three Invoke
+ * surfaces: the topbar Invoke button (`shell/topbar/InvokeControl`), the Invoke
+ * hotkey command (`hotkeys/firstPartyCommands`), and the graph-preview dialog's
+ * submit (`graph-preview/GraphPreviewDialog`).
+ *
+ * Both surfaces flush drafts, resolve the route, and gate on route validity +
+ * backend connection themselves; this helper owns only what happens *after* that
+ * gate — routing a `canvas` source through the async canvas pipeline
+ * (`prepareCanvasInvocation`, honoring the resolved destination) versus
+ * dispatching the reducer's `submitResolvedInvocationSnapshot` for every other
+ * source. `prepareCanvasInvocation` is injected so the decision stays pure and
+ * node-testable with a fake dispatch + a stubbed canvas pipeline.
+ */
+
+import type { ModelConfig } from './models/types';
+import type { Project, ResolvedInvocationRoute } from './types';
+import type { PrepareCanvasInvocationArgs } from './widgets/canvas/invoke/prepareCanvasInvocation';
+import type { WorkbenchAction } from './workbenchState';
+
+import { readCanvasCompositingSettings } from './widgets/canvas/invoke/canvasCompositing';
+import { readCanvasDenoisingStrength } from './widgets/canvas/invoke/canvasStrength';
+import { getProjectWidgetValues } from './widgetState';
+
+export interface SubmitResolvedInvocationDeps {
+  /** The resolved route to submit — the caller has already checked it is valid. */
+  route: ResolvedInvocationRoute;
+  /** The project the canvas pipeline reads its generate/canvas widget values from. */
+  project: Project;
+  /** Loaded models (or `undefined` while loading), forwarded verbatim to both paths. */
+  models: readonly ModelConfig[] | undefined;
+  dispatch: (action: WorkbenchAction) => void;
+  /**
+   * The async canvas-invoke entry point, injected for testability. The real
+   * implementation is fire-and-track (its returned promise is intentionally not
+   * awaited); a canvas source never dispatches `submitResolvedInvocationSnapshot`.
+   */
+  prepareCanvasInvocation: (args: PrepareCanvasInvocationArgs) => unknown;
+}
+
+export const submitResolvedInvocation = ({
+  dispatch,
+  models,
+  prepareCanvasInvocation,
+  project,
+  route,
+}: SubmitResolvedInvocationDeps): void => {
+  if (route.sourceId === 'canvas') {
+    // The canvas graph is composited + compiled asynchronously outside the
+    // reducer; fire-and-track (the orchestrator records any failure notice and
+    // guards against concurrent invokes internally). The resolved destination is
+    // threaded through so a Canvas source can still land its output in the
+    // Gallery (durable, non-intermediate) instead of canvas staging.
+    prepareCanvasInvocation({
+      compositing: readCanvasCompositingSettings(getProjectWidgetValues(project, 'canvas')),
+      destination: route.destination,
+      dispatch,
+      generateValues: getProjectWidgetValues(project, 'generate'),
+      models,
+      projectId: project.id,
+      projectSettings: project.settings,
+      strength: readCanvasDenoisingStrength(getProjectWidgetValues(project, 'canvas')),
+    });
+    return;
+  }
+
+  dispatch({
+    backendSupportsCancellation: true,
+    models,
+    route,
+    type: 'submitResolvedInvocationSnapshot',
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/Launchpad.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/Launchpad.tsx
new file mode 100644
index 00000000000..b05d34a5a63
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/Launchpad.tsx
@@ -0,0 +1,153 @@
+import { Box, Flex, type SystemStyleObject } from '@chakra-ui/react';
+import { useLocation, useNavigate } from '@tanstack/react-router';
+import { useCapabilities } from '@workbench/auth/capabilities';
+import { Tabs } from '@workbench/components/ui';
+import { BoxIcon, BlocksIcon, FolderIcon, UsersIcon, type LucideIcon } from 'lucide-react';
+import { useCallback, useMemo, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { LaunchpadNav } from './LaunchpadNav';
+import { LaunchpadTopBar } from './LaunchpadTopBar';
+import { ModelsPage } from './pages/ModelsPage';
+import { NodesPage } from './pages/NodesPage';
+import { ProjectsPage } from './pages/ProjectsPage';
+import { UsersPage } from './pages/UsersPage';
+
+/**
+ * The landing surface at `/`: a full-height shell with a slim section rail and
+ * a full-width page area — the editor equivalent of Photoshop's home screen.
+ * Sections live as switchable pages (Projects, the model manager, and admin
+ * user management) so the surface has room to grow without crowding any one of
+ * them. It deliberately mounts none of the workbench providers or runtimes, so
+ * it stays on the light side of the route-level code split; the heaviest page,
+ * the model manager, lazy-loads its own chunk the first time it is opened.
+ */
+
+type LaunchpadSectionId = 'projects' | 'models' | 'nodes' | 'users';
+
+interface LaunchpadSection {
+  id: LaunchpadSectionId;
+  label: string;
+  icon: LucideIcon;
+  render: () => ReactNode;
+  condition?: boolean;
+}
+
+const DEFAULT_SECTION_ID: LaunchpadSectionId = 'projects';
+const SECTION_IDS: readonly string[] = ['projects', 'models', 'nodes', 'users'];
+
+const isSectionId = (value: string): value is LaunchpadSectionId => SECTION_IDS.includes(value);
+
+const normalizeSectionId = (value: string): LaunchpadSectionId | null => {
+  const id = value.replace(/^\/+/, '');
+
+  return isSectionId(id) ? id : null;
+};
+
+const SECTION_PATHS: Record<LaunchpadSectionId, '/projects' | '/models' | '/nodes' | '/users'> = {
+  models: '/models',
+  nodes: '/nodes',
+  projects: '/projects',
+  users: '/users',
+};
+
+const TABS_CSS: SystemStyleObject = {
+  display: 'flex',
+  flex: 1,
+  flexDirection: { base: 'column', md: 'row' },
+  minH: 0,
+};
+
+const getRequestedSectionId = (pathname: string): LaunchpadSectionId | null => normalizeSectionId(pathname);
+
+const getActiveSectionId = (
+  sections: LaunchpadSection[],
+  requestedSectionId: LaunchpadSectionId | null
+): LaunchpadSectionId =>
+  requestedSectionId && sections.some((section) => section.id === requestedSectionId)
+    ? requestedSectionId
+    : DEFAULT_SECTION_ID;
+
+export const Launchpad = () => {
+  const { canManageModels, canManageNodes, canManageUsers } = useCapabilities();
+  const { t } = useTranslation();
+
+  const filtered = useMemo<LaunchpadSection[]>(
+    () =>
+      (
+        [
+          {
+            icon: FolderIcon,
+            id: 'projects',
+            label: t('launchpad.sections.projects'),
+            render: () => <ProjectsPage />,
+          },
+          {
+            condition: canManageModels,
+            icon: BoxIcon,
+            id: 'models',
+            label: t('launchpad.sections.models'),
+            render: () => <ModelsPage />,
+          },
+          {
+            condition: canManageNodes,
+            icon: BlocksIcon,
+            id: 'nodes',
+            label: t('launchpad.sections.nodes'),
+            render: () => <NodesPage />,
+          },
+          {
+            condition: canManageUsers,
+            icon: UsersIcon,
+            id: 'users',
+            label: t('launchpad.sections.users'),
+            render: () => <UsersPage />,
+          },
+        ] satisfies (LaunchpadSection & { condition?: boolean })[]
+      ).filter((section) => section.condition ?? true),
+    [canManageModels, canManageNodes, canManageUsers, t]
+  );
+
+  return (
+    <Flex bg="bg" color="fg" direction="column" h="100dvh" overflow="hidden">
+      <LaunchpadTopBar />
+      <LaunchpadSections sections={filtered} />
+    </Flex>
+  );
+};
+
+const LaunchpadSections = ({ sections }: { sections: LaunchpadSection[] }) => {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const requestedSectionId = getRequestedSectionId(location.pathname);
+  const activeSectionId = getActiveSectionId(sections, requestedSectionId);
+  const handleValueChange = useCallback(
+    (details: { value: string }) => {
+      if (isSectionId(details.value)) {
+        void navigate({ to: SECTION_PATHS[details.value] });
+      }
+    },
+    [navigate]
+  );
+
+  return (
+    <Tabs.Root
+      css={TABS_CSS}
+      lazyMount
+      size="sm"
+      orientation="vertical"
+      value={activeSectionId}
+      variant="subtle"
+      onValueChange={handleValueChange}
+    >
+      <LaunchpadNav items={sections} />
+      <Box flex="1" minH="0" minW="0" position="relative">
+        {sections.map((section) => (
+          <Tabs.Content key={section.id} h="full" m="0" minH="0" p="0" value={section.id}>
+            {section.render()}
+          </Tabs.Content>
+        ))}
+      </Box>
+    </Tabs.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/LaunchpadNav.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/LaunchpadNav.tsx
new file mode 100644
index 00000000000..ecf41f4d01c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/LaunchpadNav.tsx
@@ -0,0 +1,53 @@
+import type { LucideIcon } from 'lucide-react';
+
+import { Box, Icon, Stack, Text } from '@chakra-ui/react';
+import { Tabs } from '@workbench/components/ui';
+
+import { ResourceLinks } from './ResourceLinks';
+
+const NAV_BORDER_END_WIDTH = { md: '1px' } as const;
+const NAV_WIDTH = { base: 'full', md: '56' } as const;
+const RESOURCE_LINKS_MARGIN_TOP = { md: 'auto' } as const;
+
+export interface LaunchpadNavItem {
+  id: string;
+  label: string;
+  icon: LucideIcon;
+}
+
+/**
+ * The Launchpad's persistent left rail: top-level section switcher up top,
+ * docs/community links pinned to the bottom. Kept deliberately narrow so the
+ * page area to its right gets the room — the model manager in particular wants
+ * the full width. Renders inside the section `Tabs.Root`, so the triggers carry
+ * the roving-focus and selection semantics for free.
+ */
+export const LaunchpadNav = ({ items }: { items: LaunchpadNavItem[] }) => (
+  <Stack
+    aria-label="Launchpad sections"
+    as="nav"
+    borderColor="border.subtle"
+    borderEndWidth={NAV_BORDER_END_WIDTH}
+    flexShrink={0}
+    gap="4"
+    h="full"
+    minH="0"
+    p="2"
+    w={NAV_WIDTH}
+  >
+    {items.length > 1 ? (
+      <Tabs.List flexShrink={0}>
+        {items.map((item) => (
+          <Tabs.Trigger key={item.id} value={item.id}>
+            <Icon as={item.icon} boxSize="3.5" flexShrink={0} />
+            <Text truncate>{item.label}</Text>
+          </Tabs.Trigger>
+        ))}
+      </Tabs.List>
+    ) : null}
+
+    <Box mt={RESOURCE_LINKS_MARGIN_TOP}>
+      <ResourceLinks />
+    </Box>
+  </Stack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/LaunchpadTopBar.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/LaunchpadTopBar.tsx
new file mode 100644
index 00000000000..5d35c8f4ceb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/LaunchpadTopBar.tsx
@@ -0,0 +1,67 @@
+import type { BackendConnectionStatus } from '@workbench/types';
+
+import { Box, Flex, HStack, Text } from '@chakra-ui/react';
+import { AccountMenu } from '@workbench/auth/components/AccountMenu';
+import { useConnectionStatusSelector } from '@workbench/backend/connectionStore';
+import { InvokeMark } from '@workbench/components/InvokeMark';
+import { SettingsButton } from '@workbench/settings/SettingsDialog';
+
+const CONNECTION_LABEL: Record<Exclude<BackendConnectionStatus, 'connected'>, string> = {
+  connecting: 'Connecting…',
+  disconnected: 'Disconnected',
+};
+
+/** Subtle backend-connection indicator; hidden while the socket is healthy. */
+const ConnectionChip = () => {
+  const status = useConnectionStatusSelector((snapshot) => snapshot.status);
+
+  if (status === 'connected') {
+    return null;
+  }
+
+  const isDown = status === 'disconnected';
+
+  return (
+    <HStack
+      bg="bg.muted"
+      borderColor={isDown ? 'border.error' : 'border.subtle'}
+      borderWidth="1px"
+      gap="1.5"
+      px="2.5"
+      py="1"
+      rounded="full"
+    >
+      <Box bg={isDown ? 'fg.error' : 'fg.muted'} boxSize="1.5" rounded="full" />
+      <Text color={isDown ? 'fg.error' : 'fg.muted'} fontSize="2xs" fontWeight="600">
+        {CONNECTION_LABEL[status]}
+      </Text>
+    </HStack>
+  );
+};
+
+export const LaunchpadTopBar = () => (
+  <Flex
+    align="center"
+    borderBottomWidth="1px"
+    bg="bg.subtle"
+    flexShrink={0}
+    justify="space-between"
+    pe="1.5"
+    ps="4"
+    h="12"
+  >
+    <HStack gap="3">
+      <InvokeMark size={20} />
+      <Text fontSize="sm" fontWeight="700">
+        Invoke
+      </Text>
+    </HStack>
+    <HStack gap="2">
+      <ConnectionChip />
+      <HStack gap="0.5">
+        <SettingsButton />
+        <AccountMenu />
+      </HStack>
+    </HStack>
+  </Flex>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/NewProjectCard.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/NewProjectCard.tsx
new file mode 100644
index 00000000000..c09b88e22c1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/NewProjectCard.tsx
@@ -0,0 +1,39 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Flex, Icon, Text } from '@chakra-ui/react';
+import { Link } from '@tanstack/react-router';
+import { PlusIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+/** The grid's leading cell: start a fresh draft in the editor. */
+export const NewProjectCard = () => {
+  const { t } = useTranslation();
+
+  return (
+    <Flex
+      align="center"
+      borderColor="border.subtle"
+      borderStyle="dashed"
+      borderWidth="1.5px"
+      direction="column"
+      gap="2"
+      justify="center"
+      minH="40"
+      position="relative"
+      rounded="lg"
+      transition="border-color var(--wb-motion-duration-medium) ease, background var(--wb-motion-duration-medium) ease"
+      _hover={{ bg: 'bg.subtle', borderColor: 'border.emphasized' }}
+    >
+      <Link
+        aria-label={t('projects.createNewProject')}
+        search={{ new: true }}
+        style={{ inset: 0, position: 'absolute' }}
+        to="/app"
+      />
+      <Icon as={PlusIcon} boxSize="6" color="fg.muted" />
+      <Text color="fg.muted" fontSize="xs" fontWeight="600">
+        {t('projects.newProject')}
+      </Text>
+    </Flex>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/ProjectCard.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/ProjectCard.tsx
new file mode 100644
index 00000000000..8e96f173e76
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/ProjectCard.tsx
@@ -0,0 +1,223 @@
+import { Box, Flex, Icon, Menu, Portal, Stack, Text } from '@chakra-ui/react';
+import { Link } from '@tanstack/react-router';
+import { IconButton, ConfirmDialog, MenuContent, RenameDialog, toaster } from '@workbench/components/ui';
+import {
+  deleteLibraryProject,
+  duplicateLibraryProject,
+  renameLibraryProject,
+  type ProjectSummary,
+} from '@workbench/projects/library';
+import { exportLibraryProject } from '@workbench/projects/projectFile';
+import {
+  ArrowRightIcon,
+  CopyIcon,
+  EllipsisVerticalIcon,
+  FileDownIcon,
+  FolderIcon,
+  PencilIcon,
+  Trash2Icon,
+} from 'lucide-react';
+import { useCallback, useMemo, useState, type MouseEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { formatRelativeTime } from './formatRelativeTime';
+
+const CARD_HOVER = { bg: 'bg.muted', borderColor: 'border.emphasized' } as const;
+const LINK_STYLE = { inset: 0, position: 'absolute' } as const;
+const MENU_ITEM_DELETE_HOVER = { bg: 'bg.error', color: 'fg.error' } as const;
+const MENU_POSITION_BOTTOM_END = { placement: 'bottom-end' } as const;
+
+/**
+ * One saved project in the Home grid. The whole card is a deep link into the
+ * editor (`/app?project=…` — hovering preloads the editor chunk); the corner
+ * menu carries the library actions, which all run against the server without
+ * mounting the editor.
+ */
+export const ProjectCard = ({ summary }: { summary: ProjectSummary }) => {
+  const { t } = useTranslation();
+  const [isRenameOpen, setIsRenameOpen] = useState(false);
+  const [isDeleteOpen, setIsDeleteOpen] = useState(false);
+  const [isActionsOpen, setIsActionsOpen] = useState(false);
+  const [contextMenuTarget, setContextMenuTarget] = useState<{ x: number; y: number } | null>(null);
+
+  const projectSearch = useMemo(() => ({ project: summary.id }), [summary.id]);
+  const menuPositioning = useMemo(
+    () =>
+      contextMenuTarget
+        ? {
+            getAnchorRect: () => ({ height: 1, width: 1, x: contextMenuTarget.x, y: contextMenuTarget.y }),
+            placement: 'bottom-start' as const,
+          }
+        : MENU_POSITION_BOTTOM_END,
+    [contextMenuTarget]
+  );
+
+  const handleRename = useCallback(
+    async (name: string) => {
+      try {
+        await renameLibraryProject(summary.id, name);
+      } catch (error) {
+        toaster.create({
+          description: error instanceof Error ? error.message : undefined,
+          title: t('projects.renameFailed'),
+          type: 'error',
+        });
+        throw error;
+      }
+    },
+    [summary.id, t]
+  );
+
+  const handleDuplicate = useCallback(async () => {
+    try {
+      const copy = await duplicateLibraryProject(summary.id);
+
+      toaster.create({
+        description: t('projects.projectDuplicatedDescription', { name: copy.name }),
+        title: t('projects.projectDuplicated'),
+        type: 'success',
+      });
+    } catch (error) {
+      toaster.create({
+        description: error instanceof Error ? error.message : undefined,
+        title: t('projects.duplicateFailed'),
+        type: 'error',
+      });
+    }
+  }, [summary.id, t]);
+
+  const handleExport = useCallback(async () => {
+    try {
+      await exportLibraryProject(summary.id);
+    } catch (error) {
+      toaster.create({
+        description: error instanceof Error ? error.message : undefined,
+        title: t('projects.exportFailed'),
+        type: 'error',
+      });
+    }
+  }, [summary.id, t]);
+
+  const handleDelete = useCallback(async () => {
+    try {
+      await deleteLibraryProject(summary.id);
+    } catch (error) {
+      toaster.create({
+        description: error instanceof Error ? error.message : undefined,
+        title: t('projects.deleteFailed'),
+        type: 'error',
+      });
+    }
+  }, [summary.id, t]);
+  const handleContextMenu = useCallback((event: MouseEvent<HTMLDivElement>) => {
+    event.preventDefault();
+    setContextMenuTarget({ x: event.clientX, y: event.clientY });
+    setIsActionsOpen(true);
+  }, []);
+  const handleOpenChange = useCallback((event: { open: boolean }) => {
+    setIsActionsOpen(event.open);
+
+    if (!event.open) {
+      setContextMenuTarget(null);
+    }
+  }, []);
+  const clearContextMenuTarget = useCallback(() => setContextMenuTarget(null), []);
+  const openRenameDialog = useCallback(() => setIsRenameOpen(true), []);
+  const closeRenameDialog = useCallback(() => setIsRenameOpen(false), []);
+  const openDeleteDialog = useCallback(() => setIsDeleteOpen(true), []);
+  const closeDeleteDialog = useCallback(() => setIsDeleteOpen(false), []);
+
+  return (
+    <Box
+      bg="bg.subtle"
+      borderColor="border.subtle"
+      borderWidth="1px"
+      overflow="hidden"
+      position="relative"
+      rounded="lg"
+      transition="border-color var(--wb-motion-duration-medium) ease, background var(--wb-motion-duration-medium) ease"
+      _hover={CARD_HOVER}
+      onContextMenu={handleContextMenu}
+    >
+      <Link
+        aria-label={t('projects.openProjectLabel', { name: summary.name })}
+        search={projectSearch}
+        style={LINK_STYLE}
+        to="/app"
+      />
+      <Flex align="center" bg="bg.muted" h="24" justify="center" pointerEvents="none">
+        <Icon as={FolderIcon} boxSize="8" color="fg.subtle" opacity={0.6} />
+      </Flex>
+      <Flex align="center" gap="2" p="3" pointerEvents="none">
+        <Stack flex="1" gap="0" minW="0">
+          <Text fontSize="xs" fontWeight="600" truncate>
+            {summary.name}
+          </Text>
+          <Text color="fg.muted" fontSize="2xs">
+            {t('projects.editedRelative', { time: formatRelativeTime(summary.updatedAt) })}
+          </Text>
+        </Stack>
+      </Flex>
+      <Box bottom="2" pointerEvents="auto" position="absolute" right="2" zIndex="1">
+        <Menu.Root open={isActionsOpen} positioning={menuPositioning} onOpenChange={handleOpenChange}>
+          <Menu.Trigger asChild>
+            <IconButton
+              aria-label={t('common.actions')}
+              color="fg.muted"
+              size="2xs"
+              variant="ghost"
+              onClick={clearContextMenuTarget}
+            >
+              <EllipsisVerticalIcon />
+            </IconButton>
+          </Menu.Trigger>
+          <Portal>
+            <Menu.Positioner>
+              <MenuContent minW="44">
+                <Menu.Item asChild value="open">
+                  <Link search={projectSearch} to="/app">
+                    <Icon as={ArrowRightIcon} boxSize="3.5" />
+                    {t('common.open')}
+                  </Link>
+                </Menu.Item>
+                <Menu.Item value="rename" onClick={openRenameDialog}>
+                  <Icon as={PencilIcon} boxSize="3.5" />
+                  {t('projects.renameWithEllipsis')}
+                </Menu.Item>
+                <Menu.Item value="duplicate" onClick={handleDuplicate}>
+                  <Icon as={CopyIcon} boxSize="3.5" />
+                  {t('common.duplicate')}
+                </Menu.Item>
+                <Menu.Item value="export" onClick={handleExport}>
+                  <Icon as={FileDownIcon} boxSize="3.5" />
+                  {t('common.export')}
+                </Menu.Item>
+                <Menu.Separator />
+                <Menu.Item color="fg.error" value="delete" _hover={MENU_ITEM_DELETE_HOVER} onClick={openDeleteDialog}>
+                  <Icon as={Trash2Icon} boxSize="3.5" />
+                  {t('common.delete')}…
+                </Menu.Item>
+              </MenuContent>
+            </Menu.Positioner>
+          </Portal>
+        </Menu.Root>
+      </Box>
+
+      <RenameDialog
+        initialName={summary.name}
+        isOpen={isRenameOpen}
+        onClose={closeRenameDialog}
+        onSubmit={handleRename}
+      />
+
+      <ConfirmDialog
+        body={t('projects.deleteProjectCardBody', { name: summary.name })}
+        confirmLabel={t('projects.deleteProject')}
+        isOpen={isDeleteOpen}
+        title={t('projects.deleteProjectQuestion')}
+        onClose={closeDeleteDialog}
+        onConfirm={handleDelete}
+      />
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/ProjectsGrid.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/ProjectsGrid.tsx
new file mode 100644
index 00000000000..4f9fee16318
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/ProjectsGrid.tsx
@@ -0,0 +1,46 @@
+import { Alert, SimpleGrid, Skeleton, Stack } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { refreshProjectLibrary, useProjectLibrarySelector } from '@workbench/projects/library';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { NewProjectCard } from './NewProjectCard';
+import { ProjectCard } from './ProjectCard';
+
+const GRID_COLUMNS = { base: 1, lg: 3, sm: 2 } as const;
+
+/**
+ * The saved-projects grid, fed by the project library store (summaries are
+ * already sorted most-recently-edited first). The "new project" cell always
+ * leads, so an empty library still presents the next step.
+ */
+export const ProjectsGrid = () => {
+  const { t } = useTranslation();
+  const error = useProjectLibrarySelector((snapshot) => snapshot.error);
+  const status = useProjectLibrarySelector((snapshot) => snapshot.status);
+  const summaries = useProjectLibrarySelector((snapshot) => snapshot.summaries);
+  const isFirstLoad = summaries.length === 0 && (status === 'idle' || status === 'loading');
+  const handleRetry = useCallback(() => void refreshProjectLibrary(), []);
+
+  return (
+    <Stack gap="3">
+      {status === 'error' ? (
+        <Alert.Root borderRadius="md" size="sm" status="error">
+          <Alert.Indicator />
+          <Alert.Title flex="1" fontSize="xs">
+            {error ?? t('projects.failedToLoad')}
+          </Alert.Title>
+          <Button size="2xs" variant="outline" onClick={handleRetry}>
+            {t('common.retry')}
+          </Button>
+        </Alert.Root>
+      ) : null}
+      <SimpleGrid columns={GRID_COLUMNS} gap="4">
+        <NewProjectCard />
+        {isFirstLoad
+          ? Array.from({ length: 3 }, (_value, index) => <Skeleton key={index} minH="40" rounded="lg" />)
+          : summaries.map((summary) => <ProjectCard key={summary.id} summary={summary} />)}
+      </SimpleGrid>
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/ResourceLinks.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/ResourceLinks.tsx
new file mode 100644
index 00000000000..e8296153eed
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/ResourceLinks.tsx
@@ -0,0 +1,52 @@
+import type { ComponentType } from 'react';
+
+import { Card, Flex, Icon, Link, Stack, Text } from '@chakra-ui/react';
+import { BookOpenTextIcon, ClapperboardIcon, CodeIcon, ExternalLinkIcon, MessagesSquareIcon } from 'lucide-react';
+
+type ResourceLink = { href: string; icon: ComponentType; label: string };
+
+const COMMUNITY: ResourceLink[] = [
+  { href: 'https://discord.gg/ZmtBAhwWhy', icon: MessagesSquareIcon, label: 'Discord' },
+  { href: 'https://github.com/invoke-ai/InvokeAI', icon: CodeIcon, label: 'GitHub' },
+];
+
+const GUIDES: ResourceLink[] = [
+  { href: 'https://invoke-ai.github.io/InvokeAI/', icon: BookOpenTextIcon, label: 'Documentation' },
+  { href: 'https://www.youtube.com/@invokeai', icon: ClapperboardIcon, label: 'YouTube' },
+];
+
+const RESOURCES = [
+  {
+    label: 'Community',
+    resources: COMMUNITY,
+  },
+  {
+    label: 'Guides',
+    resources: GUIDES,
+  },
+];
+
+const ResourceItem = ({ href, icon, label }: ResourceLink) => (
+  <Link href={href} target="_blank" rel="noreferrer" asChild>
+    <Flex align="center" gap={2} py={1}>
+      <Icon as={icon} boxSize="3.5" />
+      <Text fontSize="sm">{label}</Text>
+      <Icon as={ExternalLinkIcon} boxSize="3" color="fg.subtle" ms="auto" />
+    </Flex>
+  </Link>
+);
+
+export const ResourceLinks = () => (
+  <Stack>
+    {RESOURCES.map((section) => (
+      <Card.Root variant="outline" size="sm" key={section.label}>
+        <Card.Header fontSize="sm">{section.label}</Card.Header>
+        <Card.Body pt="2">
+          {section.resources.map((resource) => (
+            <ResourceItem {...resource} key={resource.href} />
+          ))}
+        </Card.Body>
+      </Card.Root>
+    ))}
+  </Stack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/formatRelativeTime.ts b/invokeai/frontend/webv2/src/workbench/launchpad/formatRelativeTime.ts
new file mode 100644
index 00000000000..7182fc52325
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/formatRelativeTime.ts
@@ -0,0 +1,37 @@
+/**
+ * Compact "Edited 5 minutes ago" timestamps for the Home grid and the Open
+ * Project dialog. Expects ISO timestamps (the project library normalizes the
+ * backend's SQLite format at its boundary).
+ */
+
+const DIVISIONS: { amount: number; unit: Intl.RelativeTimeFormatUnit }[] = [
+  { amount: 60, unit: 'second' },
+  { amount: 60, unit: 'minute' },
+  { amount: 24, unit: 'hour' },
+  { amount: 7, unit: 'day' },
+  { amount: 4.345, unit: 'week' },
+  { amount: 12, unit: 'month' },
+  { amount: Number.POSITIVE_INFINITY, unit: 'year' },
+];
+
+const formatter = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+
+export const formatRelativeTime = (timestamp: string): string => {
+  const date = new Date(timestamp);
+
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+
+  let duration = (date.getTime() - Date.now()) / 1000;
+
+  for (const division of DIVISIONS) {
+    if (Math.abs(duration) < division.amount) {
+      return formatter.format(Math.round(duration), division.unit);
+    }
+
+    duration /= division.amount;
+  }
+
+  return '';
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/ModelManagerView.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/ModelManagerView.tsx
new file mode 100644
index 00000000000..ba30a42d9ae
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/ModelManagerView.tsx
@@ -0,0 +1,24 @@
+import { Flex } from '@chakra-ui/react';
+import { ModelInstallRuntime } from '@workbench/models/ModelInstallRuntime';
+import { ensureModelsLoaded } from '@workbench/models/modelsStore';
+import { useEffect } from 'react';
+
+import { DetailPane } from './manager/DetailPane';
+import { LibraryColumn } from './manager/LibraryColumn';
+
+/** Full model manager: persistent library column plus right-side detail pane. */
+export const ModelManagerView = () => {
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  return (
+    <Flex direction="column" h="full" minH="0" w="full">
+      <ModelInstallRuntime />
+      <Flex flex="1" minH="0" w="full">
+        <LibraryColumn />
+        <DetailPane />
+      </Flex>
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/AccessTokenPopover.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/AccessTokenPopover.tsx
new file mode 100644
index 00000000000..18cbf1aaaa7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/AccessTokenPopover.tsx
@@ -0,0 +1,61 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Icon, Input, Popover, Portal, Stack, Text } from '@chakra-ui/react';
+import { Button, IconButton } from '@workbench/components/ui';
+import { KeyRoundIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+/** Key icon -> popover with a one-off access token and a jump to the keys tab. */
+export const AccessTokenPopover = ({
+  onChange,
+  onManageKeys,
+  value,
+}: {
+  onChange: (value: string) => void;
+  onManageKeys: () => void;
+  value: string;
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <Popover.Root lazyMount positioning={{ placement: 'bottom-end' }}>
+      <Popover.Trigger asChild>
+        <IconButton
+          aria-label={t('models.accessTokenForDownload')}
+          color={value.trim() === '' ? 'fg.muted' : 'accent.solid'}
+          size="sm"
+          variant="outline"
+        >
+          <Icon as={KeyRoundIcon} boxSize="4" />
+        </IconButton>
+      </Popover.Trigger>
+      <Portal>
+        <Popover.Positioner>
+          <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="20rem">
+            <Popover.Body p="2.5">
+              <Stack gap="2">
+                <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+                  {t('models.accessToken')}
+                </Text>
+                <Input
+                  aria-label={t('models.accessToken')}
+                  placeholder={t('models.accessTokenPlaceholder')}
+                  size="xs"
+                  type="password"
+                  value={value}
+                  onChange={(event) => onChange(event.currentTarget.value)}
+                />
+                <Text color="fg.subtle" fontSize="2xs">
+                  {t('models.accessTokenHelp')}
+                </Text>
+                <Button alignSelf="start" size="2xs" variant="ghost" onClick={onManageKeys}>
+                  {t('models.manageApiKeys')} {'->'}
+                </Button>
+              </Stack>
+            </Popover.Body>
+          </Popover.Content>
+        </Popover.Positioner>
+      </Portal>
+    </Popover.Root>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/AddModelsView.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/AddModelsView.tsx
new file mode 100644
index 00000000000..de03d036167
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/AddModelsView.tsx
@@ -0,0 +1,443 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelSortField } from '@workbench/models/library';
+import type { StarterModel } from '@workbench/models/types';
+
+import { Box, Checkbox, Flex, HStack, Icon, Input, InputGroup, Stack, Text } from '@chakra-ui/react';
+import { Button, Scrollable, Tooltip } from '@workbench/components/ui';
+import { getExternalProviderConfigs, getHuggingFaceModels, scanFolderForModels } from '@workbench/models/api';
+import { getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { collectBases, collectTypes } from '@workbench/models/library';
+import { ensureStartersLoaded, useStartersSelector } from '@workbench/models/startersStore';
+import { updateModelsUi, useModelsUiSelector } from '@workbench/models/uiStore';
+import { useNotify } from '@workbench/useNotify';
+import { DownloadIcon, FileIcon, FolderIcon, FolderSearchIcon, LinkIcon, SearchIcon } from 'lucide-react';
+import { useDeferredValue, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { SiHuggingface } from 'react-icons/si';
+
+import type { StarterInstallSource } from './starterModelInstallSources';
+
+import { AccessTokenPopover } from './AccessTokenPopover';
+import { BundleChips } from './BundleChips';
+import { HuggingFaceFiles } from './HuggingFaceFiles';
+import { ScanResults } from './ScanResults';
+import { SelectedBundleBar } from './SelectedBundleBar';
+import { classifySource } from './sourceClassifier';
+import { DEFAULT_STARTER_MODEL_FILTERS, StarterFilterMenu, type StarterModelFilters } from './StarterFilterMenu';
+import { StarterList } from './StarterList';
+import { getStarterBundleInstallSources, getStarterModelInstallSources } from './starterModelInstallSources';
+import { useInstallActions } from './useInstallActions';
+
+interface IndexedStarterModel {
+  index: number;
+  model: StarterModel;
+}
+
+const compareStarterModels = (a: IndexedStarterModel, b: IndexedStarterModel, field: ModelSortField): number => {
+  switch (field) {
+    case 'default':
+      return a.index - b.index;
+    case 'name':
+      return a.model.name.localeCompare(b.model.name, undefined, { sensitivity: 'base' });
+    case 'base':
+      return getModelBaseLabel(a.model.base).localeCompare(getModelBaseLabel(b.model.base));
+    case 'format':
+      return String(a.model.format ?? '').localeCompare(String(b.model.format ?? ''));
+    case 'size':
+      return 0;
+  }
+};
+
+/**
+ * One box to add any model. The same field searches the curated starter
+ * catalog and accepts a URL, local path, or HuggingFace repo to install
+ * directly. Source-specific result panels live under `add-models/` so this file
+ * stays focused on state and install orchestration.
+ */
+export const AddModelsView = () => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const { install, pendingSources } = useInstallActions();
+  const loadError = useStartersSelector((snapshot) => snapshot.error);
+  const response = useStartersSelector((snapshot) => snapshot.response);
+  const status = useStartersSelector((snapshot) => snapshot.status);
+  const { hfLookup, scan } = useModelsUiSelector(
+    (snapshot) => ({ hfLookup: snapshot.hfLookup, scan: snapshot.scan }),
+    (left, right) => left.hfLookup === right.hfLookup && left.scan === right.scan
+  );
+
+  const [query, setQuery] = useState('');
+  const [accessToken, setAccessToken] = useState('');
+  const [inplace, setInplace] = useState(true);
+  const [selectedBundleName, setSelectedBundleName] = useState<string | null>(null);
+  const [isPulling, setIsPulling] = useState(false);
+  const [isScanning, setIsScanning] = useState(false);
+  const [installingBundle, setInstallingBundle] = useState<string | null>(null);
+  const [configuredExternalProviders, setConfiguredExternalProviders] = useState<ReadonlySet<string>>(() => new Set());
+  const [starterFilters, setStarterFilters] = useState<StarterModelFilters>(DEFAULT_STARTER_MODEL_FILTERS);
+
+  useEffect(() => {
+    ensureStartersLoaded();
+  }, []);
+
+  useEffect(() => {
+    let isStale = false;
+
+    getExternalProviderConfigs()
+      .then((configs) => {
+        if (isStale) {
+          return;
+        }
+
+        setConfiguredExternalProviders(
+          new Set(configs.filter((config) => config.api_key_configured).map((config) => config.provider_id))
+        );
+      })
+      .catch((error) => {
+        if (isStale) {
+          return;
+        }
+
+        setConfiguredExternalProviders(new Set());
+        notify.error(
+          t('models.externalProviderKeysUnavailable'),
+          error instanceof Error ? error.message : String(error)
+        );
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [notify, t]);
+
+  const trimmed = query.trim();
+  const deferredTrimmed = useDeferredValue(trimmed);
+  // A pull/scan results panel is showing: focus on the results and hide the
+  // browse-only chrome (bundles, filter menu, starter catalog).
+  const hasResults = hfLookup !== null || scan !== null;
+  const kind = useMemo(() => classifySource(trimmed), [trimmed]);
+  const searchIcon = kind.looksRepo
+    ? SiHuggingface
+    : kind.looksUrl
+      ? LinkIcon
+      : kind.localKind === 'file'
+        ? FileIcon
+        : kind.localKind === 'folder'
+          ? FolderIcon
+          : SearchIcon;
+  const token = accessToken.trim() === '' ? undefined : accessToken.trim();
+  // The primary action depends on the detected input: folders are scanned for
+  // models; files, URLs, and HF repos are pulled. Access tokens only apply to URLs.
+  const canScan = kind.localKind === 'folder';
+  const canPull = kind.isInstallable && !canScan;
+
+  const bundles = useMemo(() => (response ? Object.values(response.starter_bundles) : []), [response]);
+  const selectedBundle = useMemo(
+    () => bundles.find((bundle) => bundle.name === selectedBundleName) ?? null,
+    [bundles, selectedBundleName]
+  );
+  const sourceModels = useMemo(
+    () => selectedBundle?.models ?? response?.starter_models ?? [],
+    [response, selectedBundle]
+  );
+  const selectedBundleSources = useMemo(
+    () => (selectedBundle ? new Set(selectedBundle.models.map((model) => model.source)) : undefined),
+    [selectedBundle]
+  );
+  const availableStarterBases = useMemo(() => collectBases(sourceModels), [sourceModels]);
+  const availableStarterTypes = useMemo(() => collectTypes(sourceModels), [sourceModels]);
+
+  const filteredModels = useMemo(() => {
+    const terms = deferredTrimmed.toLowerCase().split(/\s+/).filter(Boolean);
+    const directionFactor = starterFilters.sortDirection === 'desc' ? -1 : 1;
+
+    return sourceModels
+      .map((model, index) => ({ index, model }))
+      .filter(({ model }) => {
+        const haystack =
+          `${model.name} ${model.description} ${model.base} ${model.type} ${model.format ?? ''} ${model.variant ?? ''}`.toLowerCase();
+
+        return (
+          (starterFilters.typeFilter === null || model.type === starterFilters.typeFilter) &&
+          (starterFilters.baseFilter === null || model.base === starterFilters.baseFilter) &&
+          terms.every((term) => haystack.includes(term))
+        );
+      })
+      .sort((a, b) => compareStarterModels(a, b, starterFilters.sortField) * directionFactor)
+      .map(({ model }) => model);
+  }, [deferredTrimmed, sourceModels, starterFilters]);
+
+  const queueSources = async (entries: StarterInstallSource[]): Promise<number> => {
+    let queued = 0;
+
+    for (const { config, source } of entries) {
+      if (await install({ config, source }, { silent: true })) {
+        queued += 1;
+      }
+    }
+
+    return queued;
+  };
+
+  const installStarter = async (model: StarterModel) => {
+    const queued = await queueSources(
+      getStarterModelInstallSources(model, { dependencySourcesToSkip: selectedBundleSources })
+    );
+
+    if (queued > 0) {
+      notify.success(
+        t('models.modelInstallQueued'),
+        queued > 1 ? t('models.modelAndDependenciesQueued', { count: queued - 1, name: model.name }) : model.name
+      );
+    }
+  };
+
+  const installBundle = async () => {
+    if (!selectedBundle) {
+      return;
+    }
+
+    setInstallingBundle(selectedBundle.name);
+
+    try {
+      const queued = await queueSources(getStarterBundleInstallSources(selectedBundle));
+
+      if (queued > 0) {
+        notify.success(
+          t('models.bundleInstallQueued'),
+          t('models.bundleInstallQueuedDescription', { count: queued, name: selectedBundle.name })
+        );
+      }
+    } finally {
+      setInstallingBundle(null);
+    }
+  };
+
+  const handlePull = async () => {
+    if (!kind.isInstallable) {
+      return;
+    }
+
+    setIsPulling(true);
+
+    try {
+      if (kind.looksRepo) {
+        const lookup = await getHuggingFaceModels(trimmed);
+
+        if (lookup.is_diffusers) {
+          updateModelsUi({ hfLookup: null });
+
+          if (await install({ accessToken: token, source: trimmed })) {
+            setQuery('');
+          }
+
+          return;
+        }
+
+        if (!lookup.urls || lookup.urls.length === 0) {
+          notify.error(t('models.noModelFilesFoundTitle'), t('models.noInstallableModelFiles'));
+
+          return;
+        }
+
+        // A single-file repo has nothing to choose from — install it directly,
+        // mirroring the diffusers path, instead of showing a one-row list.
+        const [onlyUrl] = lookup.urls;
+
+        if (lookup.urls.length === 1 && onlyUrl) {
+          updateModelsUi({ hfLookup: null });
+
+          if (await install({ accessToken: token, source: onlyUrl })) {
+            setQuery('');
+          }
+
+          return;
+        }
+
+        updateModelsUi({ hfLookup: { repo: trimmed, urls: lookup.urls } });
+
+        return;
+      }
+
+      if (await install({ accessToken: token, inplace: kind.looksLocal ? inplace : undefined, source: trimmed })) {
+        setQuery('');
+      }
+    } catch (error) {
+      notify.error(t('models.installFailed'), error instanceof Error ? error.message : String(error));
+    } finally {
+      setIsPulling(false);
+    }
+  };
+
+  const handleScan = async () => {
+    setIsScanning(true);
+
+    try {
+      updateModelsUi({ scan: { path: trimmed, results: await scanFolderForModels(trimmed) } });
+    } catch (error) {
+      notify.error(t('models.scanFailed'), error instanceof Error ? error.message : String(error));
+    } finally {
+      setIsScanning(false);
+    }
+  };
+
+  return (
+    <Flex direction="column" h="full" minH="0">
+      <Stack gap="2" pb="2" pt="3">
+        <HStack align="center" gap="2" px="3">
+          <InputGroup flex="1" startElement={<Icon as={searchIcon} boxSize="3.5" color="fg.subtle" />}>
+            <Input
+              aria-label={t('models.searchOrAdd')}
+              placeholder={t('models.searchOrAddPlaceholder')}
+              size="sm"
+              value={query}
+              onChange={(event) => setQuery(event.currentTarget.value)}
+              onKeyDown={(event) => {
+                if (event.key !== 'Enter') {
+                  return;
+                }
+
+                if (canScan) {
+                  event.preventDefault();
+                  void handleScan();
+                } else if (canPull) {
+                  event.preventDefault();
+                  void handlePull();
+                }
+              }}
+            />
+          </InputGroup>
+
+          {kind.looksUrl ? (
+            <AccessTokenPopover
+              value={accessToken}
+              onChange={setAccessToken}
+              onManageKeys={() => updateModelsUi({ activeTab: 'keys' })}
+            />
+          ) : null}
+
+          {canScan ? (
+            <Tooltip content={t('models.scanFolderTooltip')}>
+              <Button loading={isScanning} size="sm" variant="solid" onClick={() => void handleScan()}>
+                <Icon as={FolderSearchIcon} boxSize="3.5" />
+                {t('models.scan')}
+              </Button>
+            </Tooltip>
+          ) : null}
+
+          {canPull ? (
+            <Button loading={isPulling} size="sm" variant="solid" onClick={() => void handlePull()}>
+              <Icon as={DownloadIcon} boxSize="3.5" />
+              {t('models.pull')}
+            </Button>
+          ) : null}
+        </HStack>
+
+        {kind.isInstallable && !hasResults ? (
+          <HStack color="fg.subtle" fontSize="2xs" gap="2" px="3" wrap="wrap">
+            {canScan ? (
+              <Text>
+                {t('models.press')}{' '}
+                <Text as="span" color="fg.muted" fontWeight="600">
+                  {t('models.scan')}
+                </Text>{' '}
+                {t('models.toFindModelsInFolder')}
+              </Text>
+            ) : (
+              <Text>
+                {t('models.press')}{' '}
+                <Text as="span" color="fg.muted" fontWeight="600">
+                  {t('models.pull')}
+                </Text>{' '}
+                {t('models.toInstallFrom', { source: kind.label })}
+              </Text>
+            )}
+            {kind.localKind === 'file' ? (
+              <Checkbox.Root
+                checked={inplace}
+                colorPalette="accent"
+                size="xs"
+                onCheckedChange={(event) => setInplace(event.checked === true)}
+              >
+                <Checkbox.HiddenInput />
+                <Checkbox.Control />
+                <Checkbox.Label fontSize="2xs">{t('models.installInPlace')}</Checkbox.Label>
+              </Checkbox.Root>
+            ) : null}
+          </HStack>
+        ) : null}
+
+        {!hasResults ? (
+          <>
+            <BundleChips
+              bundles={bundles}
+              selectedName={selectedBundleName}
+              starterCount={response?.starter_models.length ?? 0}
+              trailing={
+                response ? (
+                  <StarterFilterMenu
+                    availableBases={availableStarterBases}
+                    availableTypes={availableStarterTypes}
+                    filters={starterFilters}
+                    onChange={setStarterFilters}
+                  />
+                ) : undefined
+              }
+              onSelect={setSelectedBundleName}
+            />
+
+            {selectedBundle ? (
+              <SelectedBundleBar
+                bundle={selectedBundle}
+                isInstalling={installingBundle === selectedBundle.name}
+                onInstall={() => void installBundle()}
+              />
+            ) : null}
+          </>
+        ) : null}
+      </Stack>
+
+      <Box flex="1" minH="0">
+        <Scrollable h="full" label={t('models.addModelsResults')} minH="0" px="3" pb="3">
+          <Stack gap="3">
+            {hfLookup ? (
+              <HuggingFaceFiles
+                lookup={hfLookup}
+                pendingSources={pendingSources}
+                onClear={() => updateModelsUi({ hfLookup: null })}
+                onInstall={(url) => void install({ accessToken: token, source: url })}
+              />
+            ) : null}
+
+            {scan ? (
+              <ScanResults
+                inplace={inplace}
+                pendingSources={pendingSources}
+                scan={scan}
+                onClear={() => updateModelsUi({ scan: null })}
+                onInstall={(path) => void install({ inplace, source: path })}
+                onSetInplace={setInplace}
+              />
+            ) : null}
+
+            {!hasResults ? (
+              <StarterList
+                configuredExternalProviders={configuredExternalProviders}
+                isInstallable={kind.isInstallable}
+                loadError={loadError}
+                models={filteredModels}
+                pendingSources={pendingSources}
+                response={response}
+                selectedBundleSources={selectedBundleSources}
+                status={status}
+                onConfigureExternalProvider={() => updateModelsUi({ activeTab: 'keys' })}
+                onInstall={(model) => void installStarter(model)}
+              />
+            ) : null}
+          </Stack>
+        </Scrollable>
+      </Box>
+    </Flex>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/BundleChips.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/BundleChips.tsx
new file mode 100644
index 00000000000..069ece9ec99
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/BundleChips.tsx
@@ -0,0 +1,90 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { StarterModelBundle } from '@workbench/models/types';
+import type { ReactNode } from 'react';
+
+import { Badge, Box, HStack, Icon } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { CheckIcon, FolderIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+/** Horizontal row of bundle filters. */
+export const BundleChips = ({
+  bundles,
+  onSelect,
+  selectedName,
+  starterCount,
+  trailing,
+}: {
+  bundles: StarterModelBundle[];
+  onSelect: (name: string | null) => void;
+  selectedName: string | null;
+  starterCount: number;
+  trailing?: ReactNode;
+}) => {
+  const { t } = useTranslation();
+
+  if (bundles.length === 0 && !trailing) {
+    return null;
+  }
+
+  return (
+    <HStack align="center" gap="2" minW="0" px="3" pb="1">
+      {bundles.length > 0 ? (
+        <HStack
+          flex="1"
+          gap="1.5"
+          minW="0"
+          overflowX="auto"
+          css={{ scrollbarWidth: 'thin', '&::-webkit-scrollbar': { height: '4px' } }}
+        >
+          <BundleChip
+            isSelected={selectedName === null}
+            label={t('common.all')}
+            subLabel={`${starterCount}`}
+            onSelect={() => onSelect(null)}
+          />
+          {bundles.map((bundle) => {
+            const missingCount = bundle.models.filter((model) => !model.is_installed).length;
+
+            return (
+              <BundleChip
+                key={bundle.name}
+                isComplete={missingCount === 0}
+                isSelected={selectedName === bundle.name}
+                label={bundle.name}
+                subLabel={`${bundle.models.length}`}
+                onSelect={() => onSelect(bundle.name)}
+              />
+            );
+          })}
+        </HStack>
+      ) : (
+        <Box flex="1" minW="0" />
+      )}
+      {trailing}
+    </HStack>
+  );
+};
+
+const BundleChip = ({
+  isComplete = false,
+  isSelected,
+  label,
+  onSelect,
+  subLabel,
+}: {
+  isComplete?: boolean;
+  isSelected: boolean;
+  label: string;
+  onSelect: () => void;
+  subLabel: string;
+}) => (
+  <Button flexShrink={0} size="xs" variant={isSelected ? 'solid' : 'subtle'} onClick={onSelect}>
+    <Icon as={isComplete ? CheckIcon : FolderIcon} boxSize="3" />
+    {label}
+    <Badge variant="surface" size="xs" ms="1" me="-1">
+      {subLabel}
+    </Badge>
+  </Button>
+);
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/HuggingFaceFiles.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/HuggingFaceFiles.tsx
new file mode 100644
index 00000000000..70743b4f45a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/HuggingFaceFiles.tsx
@@ -0,0 +1,68 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { HFLookupState } from '@workbench/models/uiStore';
+
+import { Stack } from '@chakra-ui/react';
+import { ResultsListHeader } from '@workbench/launchpad/models/shared/ResultsListHeader';
+import { InstallSourceButton, SourceListItem } from '@workbench/launchpad/models/shared/SourceListItem';
+import { useDeferredValue, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const fileNameOf = (url: string): string => url.split(/[\\/]/).at(-1) ?? url;
+
+export const HuggingFaceFiles = ({
+  lookup,
+  onClear,
+  onInstall,
+  pendingSources,
+}: {
+  lookup: HFLookupState;
+  onClear: () => void;
+  onInstall: (url: string) => void;
+  pendingSources: ReadonlySet<string>;
+}) => {
+  const { t } = useTranslation();
+  const [filter, setFilter] = useState('');
+  const deferredFilter = useDeferredValue(filter);
+
+  const filteredUrls = useMemo(() => {
+    const term = deferredFilter.trim().toLowerCase();
+
+    if (!term) {
+      return lookup.urls;
+    }
+
+    return lookup.urls.filter((url) => fileNameOf(url).toLowerCase().includes(term));
+  }, [deferredFilter, lookup.urls]);
+
+  const installAll = () => {
+    for (const url of filteredUrls) {
+      onInstall(url);
+    }
+  };
+
+  return (
+    <Stack gap="1.5">
+      <ResultsListHeader
+        installAllDisabled={filteredUrls.length === 0}
+        installAllLabel={t('models.installAllCount', { count: filteredUrls.length })}
+        searchPlaceholder={t('models.filterFiles')}
+        searchValue={filter}
+        summary={t('models.filesInRepo', { count: lookup.urls.length, repo: lookup.repo })}
+        onClear={onClear}
+        onInstallAll={installAll}
+        onSearchChange={setFilter}
+      />
+      {filteredUrls.map((url) => (
+        <SourceListItem
+          key={url}
+          title={fileNameOf(url)}
+          titleTooltip={url}
+          trailing={
+            <InstallSourceButton isPending={pendingSources.has(url)} source={url} onInstall={() => onInstall(url)} />
+          }
+        />
+      ))}
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/ScanResults.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/ScanResults.tsx
new file mode 100644
index 00000000000..63386acec5a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/ScanResults.tsx
@@ -0,0 +1,111 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { FoundModel } from '@workbench/models/types';
+
+import { Checkbox, HStack, Icon, Stack, Text } from '@chakra-ui/react';
+import { IconButton } from '@workbench/components/ui';
+import { ResultsListHeader } from '@workbench/launchpad/models/shared/ResultsListHeader';
+import { InstallSourceButton, SourceListItem } from '@workbench/launchpad/models/shared/SourceListItem';
+import { XIcon } from 'lucide-react';
+import { useDeferredValue, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const fileNameOf = (path: string): string => path.split(/[\\/]/).at(-1) ?? path;
+
+export const ScanResults = ({
+  inplace,
+  onClear,
+  onInstall,
+  onSetInplace,
+  pendingSources,
+  scan,
+}: {
+  inplace: boolean;
+  onClear: () => void;
+  onInstall: (path: string) => void;
+  onSetInplace: (inplace: boolean) => void;
+  pendingSources: ReadonlySet<string>;
+  scan: { path: string; results: FoundModel[] };
+}) => {
+  const { t } = useTranslation();
+  const [filter, setFilter] = useState('');
+  const deferredFilter = useDeferredValue(filter);
+
+  const filteredResults = useMemo(() => {
+    const term = deferredFilter.trim().toLowerCase();
+
+    if (!term) {
+      return scan.results;
+    }
+
+    return scan.results.filter((result) => fileNameOf(result.path).toLowerCase().includes(term));
+  }, [deferredFilter, scan.results]);
+
+  const notInstalledCount = scan.results.filter((result) => !result.is_installed).length;
+  const installable = filteredResults.filter((result) => !result.is_installed);
+
+  const installAll = () => {
+    for (const result of installable) {
+      onInstall(result.path);
+    }
+  };
+
+  if (scan.results.length === 0) {
+    return (
+      <HStack justify="space-between">
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('models.noModelFilesFound', { path: scan.path })}
+        </Text>
+        <IconButton aria-label={t('models.dismissScanResults')} size="2xs" variant="ghost" onClick={onClear}>
+          <Icon as={XIcon} boxSize="3" />
+        </IconButton>
+      </HStack>
+    );
+  }
+
+  return (
+    <Stack gap="1.5">
+      <ResultsListHeader
+        extra={
+          <Checkbox.Root
+            checked={inplace}
+            colorPalette="accent"
+            size="xs"
+            onCheckedChange={(event) => onSetInplace(event.checked === true)}
+          >
+            <Checkbox.HiddenInput />
+            <Checkbox.Control />
+            <Checkbox.Label fontSize="2xs">{t('models.installInPlace')}</Checkbox.Label>
+          </Checkbox.Root>
+        }
+        installAllDisabled={installable.length === 0}
+        installAllLabel={t('models.installAllCount', { count: installable.length })}
+        searchValue={filter}
+        summary={t('models.scanSummary', {
+          count: scan.results.length,
+          notInstalled: notInstalledCount,
+          path: scan.path,
+        })}
+        onClear={onClear}
+        onInstallAll={installAll}
+        onSearchChange={setFilter}
+      />
+      {filteredResults.map((result) => (
+        <SourceListItem
+          key={result.path}
+          description={result.path}
+          title={fileNameOf(result.path)}
+          titleTooltip={result.path}
+          trailing={
+            <InstallSourceButton
+              isInstalled={result.is_installed}
+              isPending={pendingSources.has(result.path)}
+              source={result.path}
+              onInstall={() => onInstall(result.path)}
+            />
+          }
+        />
+      ))}
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/SelectedBundleBar.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/SelectedBundleBar.tsx
new file mode 100644
index 00000000000..fb9ef8305ad
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/SelectedBundleBar.tsx
@@ -0,0 +1,33 @@
+import type { StarterModelBundle } from '@workbench/models/types';
+
+import { HStack, Icon, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { DownloadIcon } from 'lucide-react';
+
+/** Summary + install action for the currently selected bundle. */
+export const SelectedBundleBar = ({
+  bundle,
+  isInstalling,
+  onInstall,
+}: {
+  bundle: StarterModelBundle;
+  isInstalling: boolean;
+  onInstall: () => void;
+}) => {
+  const missingCount = bundle.models.filter((model) => !model.is_installed).length;
+
+  return (
+    <HStack gap="2" justify="space-between" px="3">
+      <Text color="fg.subtle" fontSize="2xs" truncate>
+        {bundle.name} · {bundle.models.length} models ·{' '}
+        {missingCount === 0 ? 'all installed' : `${missingCount} to install`}
+      </Text>
+      {missingCount > 0 ? (
+        <Button flexShrink={0} loading={isInstalling} size="2xs" variant="outline" onClick={onInstall}>
+          <Icon as={DownloadIcon} boxSize="3" />
+          Install bundle
+        </Button>
+      ) : null}
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/StarterFilterMenu.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/StarterFilterMenu.tsx
new file mode 100644
index 00000000000..29f8ddf8ba6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/StarterFilterMenu.tsx
@@ -0,0 +1,65 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelFilterSortOption } from '@workbench/launchpad/models/shared/ModelFilterMenu';
+import type { ModelSortField } from '@workbench/models/library';
+import type { ModelTaxonomyType } from '@workbench/models/types';
+
+import { ModelFilterMenu } from '@workbench/launchpad/models/shared/ModelFilterMenu';
+import { useTranslation } from 'react-i18next';
+
+export interface StarterModelFilters {
+  /** null = all types. */
+  typeFilter: ModelTaxonomyType | null;
+  /** null = all bases. */
+  baseFilter: string | null;
+  sortField: ModelSortField;
+  sortDirection: 'asc' | 'desc';
+}
+
+export const DEFAULT_STARTER_MODEL_FILTERS: StarterModelFilters = {
+  baseFilter: null,
+  sortDirection: 'asc',
+  sortField: 'default',
+  typeFilter: null,
+};
+
+const STARTER_SORT_FIELDS: ModelFilterSortOption[] = [
+  { field: 'default', labelKey: 'models.sortDefault' },
+  { field: 'name', labelKey: 'models.sortName' },
+  { field: 'base', labelKey: 'models.sortBase' },
+  { field: 'format', labelKey: 'models.sortFormat' },
+];
+
+const isFiltering = (filters: StarterModelFilters): boolean =>
+  filters.typeFilter !== null || filters.baseFilter !== null;
+
+export const StarterFilterMenu = ({
+  availableBases,
+  availableTypes,
+  filters,
+  onChange,
+}: {
+  availableBases: string[];
+  availableTypes: ModelTaxonomyType[];
+  filters: StarterModelFilters;
+  onChange: (filters: StarterModelFilters) => void;
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <ModelFilterMenu
+      ariaLabel={t('models.filterAndSortStarterModels')}
+      availableBases={availableBases}
+      availableTypes={availableTypes}
+      baseFilter={filters.baseFilter}
+      isActive={isFiltering(filters)}
+      sortDirection={filters.sortDirection}
+      sortField={filters.sortField}
+      sortFields={STARTER_SORT_FIELDS}
+      typeFilter={filters.typeFilter}
+      onBaseFilterChange={(baseFilter) => onChange({ ...filters, baseFilter })}
+      onSortChange={(sortField, sortDirection) => onChange({ ...filters, sortDirection, sortField })}
+      onTypeFilterChange={(typeFilter) => onChange({ ...filters, typeFilter })}
+    />
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/StarterList.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/StarterList.tsx
new file mode 100644
index 00000000000..ad94f9d2359
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/StarterList.tsx
@@ -0,0 +1,140 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { useStartersSnapshot } from '@workbench/models/startersStore';
+import type { StarterModel } from '@workbench/models/types';
+
+import { Badge, Flex, Icon, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { InstallSourceButton, SourceListItem } from '@workbench/launchpad/models/shared/SourceListItem';
+import { getModelBaseColorPalette, getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { getModelTypeLabel } from '@workbench/models/taxonomy';
+import { KeyRoundIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+const getExternalProviderId = (source: string): string | null => {
+  if (!source.startsWith('external://')) {
+    return null;
+  }
+
+  return source.slice('external://'.length).split('/', 1)[0] || null;
+};
+
+export const StarterList = ({
+  configuredExternalProviders,
+  isInstallable,
+  loadError,
+  models,
+  onConfigureExternalProvider,
+  onInstall,
+  pendingSources,
+  response,
+  selectedBundleSources,
+  status,
+}: {
+  configuredExternalProviders: ReadonlySet<string>;
+  isInstallable: boolean;
+  loadError: string | null;
+  models: StarterModel[];
+  onConfigureExternalProvider: () => void;
+  onInstall: (model: StarterModel) => void;
+  pendingSources: ReadonlySet<string>;
+  response: ReturnType<typeof useStartersSnapshot>['response'];
+  selectedBundleSources: ReadonlySet<string> | undefined;
+  status: ReturnType<typeof useStartersSnapshot>['status'];
+}) => {
+  const { t } = useTranslation();
+
+  if (status === 'error' && loadError) {
+    return (
+      <Stack align="center" gap="1" py="8">
+        <Text color="fg.error" fontSize="xs" fontWeight="600">
+          {t('models.couldNotLoadStarterModels')}
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          {loadError}
+        </Text>
+      </Stack>
+    );
+  }
+
+  if (!response) {
+    return (
+      <Flex align="center" justify="center" py="10">
+        <Spinner color="fg.subtle" size="sm" />
+      </Flex>
+    );
+  }
+
+  if (models.length === 0) {
+    return (
+      <Text color="fg.subtle" fontSize="2xs" py="6" textAlign="center">
+        {isInstallable ? t('models.noStarterModelsPull') : t('models.noStarterModelsSearch')}
+      </Text>
+    );
+  }
+
+  return (
+    <Stack gap="1.5">
+      {models.map((model) => {
+        const externalProviderId = getExternalProviderId(model.source);
+        const dependencyCount = (model.dependencies ?? []).filter(
+          (dependency) => !dependency.is_installed && !selectedBundleSources?.has(dependency.source)
+        ).length;
+        const trailing = externalProviderId ? (
+          configuredExternalProviders.has(externalProviderId) ? (
+            <Badge colorPalette="green" flexShrink={0} fontSize="2xs" size="sm" variant="surface">
+              {t('models.installed')}
+            </Badge>
+          ) : (
+            <Button
+              flexShrink={0}
+              size="2xs"
+              variant="outline"
+              onClick={(event) => {
+                event.stopPropagation();
+                onConfigureExternalProvider();
+              }}
+            >
+              <Icon as={KeyRoundIcon} boxSize="3" />
+              {t('common.configure')}
+            </Button>
+          )
+        ) : (
+          <InstallSourceButton
+            isInstalled={model.is_installed}
+            isPending={pendingSources.has(model.source)}
+            source={model.source}
+            onInstall={() => onInstall(model)}
+          />
+        );
+
+        return (
+          <SourceListItem
+            key={`${model.source}-${model.name}`}
+            badges={
+              <>
+                <Badge
+                  colorPalette={getModelBaseColorPalette(model.base)}
+                  flexShrink={0}
+                  fontSize="2xs"
+                  size="sm"
+                  variant="surface"
+                >
+                  {getModelBaseLabel(model.base)}
+                </Badge>
+                <Badge colorPalette="gray" flexShrink={0} fontSize="2xs" size="sm" variant="outline">
+                  {getModelTypeLabel(model.type)}
+                </Badge>
+              </>
+            }
+            description={`${model.description}${
+              dependencyCount > 0 ? t('models.installsDependencies', { count: dependencyCount }) : ''
+            }`}
+            title={model.name}
+            trailing={trailing}
+          />
+        );
+      })}
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/sourceClassifier.ts b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/sourceClassifier.ts
new file mode 100644
index 00000000000..523f52ab001
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/sourceClassifier.ts
@@ -0,0 +1,41 @@
+/** owner/repo with optional :variant[:path] qualifiers - the HF repo shape. */
+const HF_REPO_PATTERN = /^[\w.-]+\/[\w.-]+(:[\w./-]*)*$/;
+const FILE_EXTENSION_PATTERN = /\.[A-Za-z0-9]{1,10}$/;
+
+export interface SourceKind {
+  looksLocal: boolean;
+  looksUrl: boolean;
+  looksRepo: boolean;
+  isInstallable: boolean;
+  localKind: 'file' | 'folder' | null;
+  /** Human label of the detected source kind, or null when it reads as a search. */
+  label: string | null;
+}
+
+const classifyLocalPath = (value: string): 'file' | 'folder' => {
+  if (/[\\/]$/.test(value)) {
+    return 'folder';
+  }
+
+  const lastSegment = value.split(/[\\/]/).at(-1) ?? '';
+
+  return FILE_EXTENSION_PATTERN.test(lastSegment) ? 'file' : 'folder';
+};
+
+/** Classify the box's text: a search term, or an installable source to Pull. */
+export const classifySource = (value: string): SourceKind => {
+  const looksLocal = value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value);
+  const looksUrl = /^https?:\/\//i.test(value);
+  const looksRepo = !looksLocal && !looksUrl && HF_REPO_PATTERN.test(value);
+  const isInstallable = looksLocal || looksUrl || looksRepo;
+  const localKind = looksLocal ? classifyLocalPath(value) : null;
+
+  return {
+    isInstallable,
+    label: looksLocal ? `${localKind} path` : looksUrl ? 'URL' : looksRepo ? 'Hugging Face repo' : null,
+    localKind,
+    looksLocal,
+    looksRepo,
+    looksUrl,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/starterModelInstallSources.test.ts b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/starterModelInstallSources.test.ts
new file mode 100644
index 00000000000..3f5600e6bca
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/starterModelInstallSources.test.ts
@@ -0,0 +1,60 @@
+import type { StarterModel, StarterModelBundle } from '@workbench/models/types';
+
+import { describe, expect, it } from 'vitest';
+
+import type { StarterInstallSource } from './starterModelInstallSources';
+
+import { getStarterBundleInstallSources, getStarterModelInstallSources } from './starterModelInstallSources';
+
+const model = (source: string, overrides: Partial<StarterModel> = {}): StarterModel => ({
+  base: 'sdxl',
+  description: source,
+  is_installed: false,
+  name: source,
+  source,
+  type: 'main',
+  ...overrides,
+});
+
+const sourcesOf = (entries: StarterInstallSource[]): string[] => entries.map((entry) => entry.source);
+
+describe('starter model install sources', () => {
+  it('queues uninstalled dependencies before the model', () => {
+    const sources = getStarterModelInstallSources(
+      model('main', { dependencies: [model('vae'), model('encoder', { is_installed: true })] })
+    );
+
+    expect(sourcesOf(sources)).toEqual(['vae', 'main']);
+  });
+
+  it('registers each entry with its own curated config', () => {
+    const sources = getStarterModelInstallSources(
+      model('main', { base: 'flux', dependencies: [model('vae', { base: 'sdxl', type: 'vae' })] })
+    );
+
+    expect(sources).toEqual([
+      { config: { base: 'sdxl', description: 'vae', name: 'vae', type: 'vae' }, source: 'vae' },
+      { config: { base: 'flux', description: 'main', name: 'main', type: 'main' }, source: 'main' },
+    ]);
+  });
+
+  it('skips dependency sources already visible in the opened bundle', () => {
+    const sources = getStarterModelInstallSources(model('main', { dependencies: [model('vae'), model('encoder')] }), {
+      dependencySourcesToSkip: new Set(['vae']),
+    });
+
+    expect(sourcesOf(sources)).toEqual(['encoder', 'main']);
+  });
+
+  it('deduplicates sources across bundle models', () => {
+    const bundle: StarterModelBundle = {
+      models: [
+        model('main-a', { dependencies: [model('shared-vae')] }),
+        model('main-b', { dependencies: [model('shared-vae')] }),
+      ],
+      name: 'Bundle',
+    };
+
+    expect(sourcesOf(getStarterBundleInstallSources(bundle))).toEqual(['shared-vae', 'main-a', 'main-b']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/starterModelInstallSources.ts b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/starterModelInstallSources.ts
new file mode 100644
index 00000000000..1d17e06ad00
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/starterModelInstallSources.ts
@@ -0,0 +1,75 @@
+import type { ModelRecordChanges, StarterModel, StarterModelBundle } from '@workbench/models/types';
+
+/** A source to install plus the curated config metadata to register it with. */
+export interface StarterInstallSource {
+  source: string;
+  config: ModelRecordChanges;
+}
+
+export interface StarterModelInstallSourceOptions {
+  /** Dependencies visible as their own rows in the active bundle should not be auto-installed by a row action. */
+  dependencySourcesToSkip?: ReadonlySet<string>;
+}
+
+/**
+ * The curated metadata a starter carries: passed as the install `config` so the
+ * model is registered with its known name/base/type instead of relying purely on
+ * server-side probing (matches the legacy install path). Built per-model, so a
+ * dependency gets its own metadata rather than the parent's.
+ */
+const buildStarterConfig = (model: StarterModel | Omit<StarterModel, 'dependencies'>): ModelRecordChanges => ({
+  base: model.base,
+  description: model.description,
+  name: model.name,
+  type: model.type,
+  ...(model.format ? { format: model.format } : {}),
+  ...(model.variant ? { variant: model.variant } : {}),
+});
+
+const appendSource = (sources: StarterInstallSource[], seen: Set<string>, entry: StarterInstallSource): void => {
+  if (seen.has(entry.source)) {
+    return;
+  }
+
+  seen.add(entry.source);
+  sources.push(entry);
+};
+
+export const getStarterModelInstallSources = (
+  model: StarterModel,
+  options: StarterModelInstallSourceOptions = {}
+): StarterInstallSource[] => {
+  const sources: StarterInstallSource[] = [];
+  const seen = new Set<string>();
+
+  for (const dependency of model.dependencies ?? []) {
+    if (dependency.is_installed || options.dependencySourcesToSkip?.has(dependency.source)) {
+      continue;
+    }
+
+    appendSource(sources, seen, { config: buildStarterConfig(dependency), source: dependency.source });
+  }
+
+  if (!model.is_installed) {
+    appendSource(sources, seen, { config: buildStarterConfig(model), source: model.source });
+  }
+
+  return sources;
+};
+
+export const getStarterBundleInstallSources = (bundle: StarterModelBundle): StarterInstallSource[] => {
+  const sources: StarterInstallSource[] = [];
+  const seen = new Set<string>();
+
+  for (const model of bundle.models) {
+    if (model.is_installed) {
+      continue;
+    }
+
+    for (const entry of getStarterModelInstallSources(model)) {
+      appendSource(sources, seen, entry);
+    }
+  }
+
+  return sources;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/useInstallActions.ts b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/useInstallActions.ts
new file mode 100644
index 00000000000..970271abb75
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/add-models/useInstallActions.ts
@@ -0,0 +1,53 @@
+import { installModel, type InstallModelRequest } from '@workbench/models/api';
+import { getAccessTokenForSource } from '@workbench/models/apiKeys';
+import { addInstallJob } from '@workbench/models/installsStore';
+import { useNotify } from '@workbench/useNotify';
+import { useCallback, useState } from 'react';
+
+/**
+ * Shared install entry point: queues an install job, optimistically adds it to
+ * the install store, and surfaces a notification. A saved Civitai API key is
+ * attached automatically for civitai.com URLs unless the caller supplies an
+ * explicit token. Bulk flows pass `silent` and emit one summary notice instead
+ * of a toast per model; failures always notify.
+ */
+export const useInstallActions = () => {
+  const notify = useNotify();
+  const [pendingSources, setPendingSources] = useState<ReadonlySet<string>>(new Set());
+
+  const install = useCallback(
+    async (request: InstallModelRequest, options?: { silent?: boolean }): Promise<boolean> => {
+      setPendingSources((current) => new Set(current).add(request.source));
+
+      try {
+        const job = await installModel({
+          ...request,
+          accessToken: request.accessToken ?? getAccessTokenForSource(request.source),
+        });
+
+        addInstallJob(job);
+
+        if (!options?.silent) {
+          notify.success('Model install queued', request.source);
+        }
+
+        return true;
+      } catch (error) {
+        notify.error('Model install failed to start', error instanceof Error ? error.message : String(error));
+
+        return false;
+      } finally {
+        setPendingSources((current) => {
+          const next = new Set(current);
+
+          next.delete(request.source);
+
+          return next;
+        });
+      }
+    },
+    [notify]
+  );
+
+  return { install, pendingSources };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/credentials/ApiKeysSection.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/credentials/ApiKeysSection.tsx
new file mode 100644
index 00000000000..c7f0332e9be
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/credentials/ApiKeysSection.tsx
@@ -0,0 +1,556 @@
+/* eslint-disable react/react-compiler, react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { HFTokenStatus } from '@workbench/models/types';
+
+import { Badge, Flex, Grid, HStack, Icon, Input, Stack, Switch, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import {
+  getExternalProviderConfigs,
+  getHFTokenStatus,
+  resetExternalProviderConfig,
+  resetHFToken,
+  setExternalProviderConfig,
+  setHFToken,
+  type ExternalProviderConfig,
+} from '@workbench/models/api';
+import { clearCivitaiApiKey, getCivitaiApiKey, setCivitaiApiKey } from '@workbench/models/apiKeys';
+import { refreshInstalls } from '@workbench/models/installsStore';
+import { refreshStartersIfLoaded } from '@workbench/models/startersStore';
+import { useNotify } from '@workbench/useNotify';
+import { HexagonIcon } from 'lucide-react';
+import { useEffect, useState, type ElementType } from 'react';
+import { useTranslation } from 'react-i18next';
+import { SiAlibabacloud, SiBytedance, SiGooglegemini, SiHuggingface, SiOpenai } from 'react-icons/si';
+
+/**
+ * Credentials for every model source, as one uniform grid of key cards:
+ * HuggingFace (server-stored, verified), Civitai (browser-local), and the
+ * external image providers (server config). Each card shares the same
+ * edit/display anatomy: icon, status, prefix-hinted input, save/clear.
+ */
+export const ApiKeysSection = () => {
+  const notify = useNotify();
+  const { t } = useTranslation();
+
+  return (
+    <Stack gap="3">
+      <Text color="fg.subtle" fontSize="2xs">
+        {t('models.apiKeysDescription')}
+      </Text>
+      <Grid gap="2.5" templateColumns="repeat(auto-fill, minmax(19rem, 1fr))">
+        <HuggingFaceKeyCard onError={notify.error} />
+        <CivitaiKeyCard onError={(message) => notify.error(t('models.civitaiKey'), message)} />
+        <ExternalProviderKeyCards onError={notify.error} />
+      </Grid>
+    </Stack>
+  );
+};
+
+interface KeyStatusBadge {
+  label: string;
+  palette: string;
+}
+
+/** The shared card: identical anatomy whether the key is set or not. */
+const ApiKeyCard = ({
+  description,
+  icon,
+  isLoading = false,
+  onClear,
+  onError,
+  onSave,
+  placeholder,
+  status,
+  title,
+}: {
+  description: string;
+  icon: ElementType;
+  isLoading?: boolean;
+  /** Absent until a key exists; clears the stored key. */
+  onClear?: () => Promise<void> | void;
+  /** Save/clear failures (network, backend rejection) land here. */
+  onError: (message: string) => void;
+  onSave: (key: string) => Promise<void> | void;
+  /** Hint at the expected shape, e.g. "hf_…" or "sk-…". */
+  placeholder: string;
+  status: KeyStatusBadge | null;
+  title: string;
+}) => {
+  const { t } = useTranslation();
+  const [draft, setDraft] = useState('');
+  const [isBusy, setIsBusy] = useState(false);
+
+  const runAction = async (action: () => Promise<void> | void): Promise<boolean> => {
+    setIsBusy(true);
+
+    try {
+      await action();
+
+      return true;
+    } catch (error) {
+      onError(error instanceof Error ? error.message : t('common.somethingWentWrong'));
+
+      return false;
+    } finally {
+      setIsBusy(false);
+    }
+  };
+
+  const handleSave = async () => {
+    const key = draft.trim();
+
+    if (key.length === 0) {
+      return;
+    }
+
+    // Keep the draft on failure so the key can be corrected and retried.
+    if (await runAction(() => onSave(key))) {
+      setDraft('');
+    }
+  };
+
+  return (
+    <Stack bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" gap="2.5" p="3" rounded="lg">
+      <HStack align="start" gap="2.5">
+        <Flex
+          align="center"
+          bg="bg.emphasized"
+          borderColor="border.subtle"
+          borderWidth="1px"
+          boxSize="8"
+          color="fg.muted"
+          flexShrink={0}
+          justify="center"
+          rounded="md"
+        >
+          <Icon as={icon} boxSize="4" />
+        </Flex>
+        <Stack flex="1" gap="0" minW="0">
+          <HStack gap="1.5">
+            <Text fontSize="xs" fontWeight="700" truncate>
+              {title}
+            </Text>
+            {status ? (
+              <Badge colorPalette={status.palette} flexShrink={0} fontSize="2xs" size="sm" variant="surface">
+                {status.label}
+              </Badge>
+            ) : null}
+          </HStack>
+          <Text color="fg.subtle" fontSize="2xs" lineClamp={2}>
+            {description}
+          </Text>
+        </Stack>
+      </HStack>
+      <HStack gap="1.5">
+        <Input
+          aria-label={t('models.apiKeyFor', { title })}
+          disabled={isLoading}
+          placeholder={placeholder}
+          size="xs"
+          type="password"
+          value={draft}
+          onChange={(event) => setDraft(event.currentTarget.value)}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') {
+              event.preventDefault();
+              void handleSave();
+            }
+          }}
+        />
+        <Button
+          disabled={draft.trim().length === 0 || isLoading}
+          loading={isBusy && draft.trim().length > 0}
+          size="xs"
+          variant="solid"
+          onClick={() => void handleSave()}
+        >
+          {t('common.save')}
+        </Button>
+        {onClear ? (
+          <Button disabled={isBusy || isLoading} size="sm" variant="ghost" onClick={() => void runAction(onClear)}>
+            {t('common.clear')}
+          </Button>
+        ) : null}
+      </HStack>
+    </Stack>
+  );
+};
+
+const HF_STATUS_PALETTES: Record<HFTokenStatus, string> = {
+  invalid: 'red',
+  unknown: 'gray',
+  valid: 'green',
+};
+
+const HuggingFaceKeyCard = ({ onError }: { onError: (title: string, message: string) => void }) => {
+  const { t } = useTranslation();
+  const [status, setStatus] = useState<HFTokenStatus | null>(null);
+  const statusBadge = status ? { label: t(`models.keyStatus.${status}`), palette: HF_STATUS_PALETTES[status] } : null;
+
+  useEffect(() => {
+    let isStale = false;
+
+    getHFTokenStatus()
+      .then((tokenStatus) => {
+        if (!isStale) {
+          setStatus(tokenStatus);
+        }
+      })
+      .catch(() => {
+        if (!isStale) {
+          setStatus('unknown');
+        }
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [t]);
+
+  return (
+    <ApiKeyCard
+      description={t('models.huggingFaceKeyDescription')}
+      icon={SiHuggingface}
+      isLoading={status === null}
+      placeholder="hf_…"
+      status={statusBadge}
+      title="HuggingFace"
+      onError={(message) => onError(t('models.huggingFaceToken'), message)}
+      onClear={
+        status === 'valid' || status === 'invalid'
+          ? async () => {
+              setStatus(await resetHFToken());
+            }
+          : undefined
+      }
+      onSave={async (key) => {
+        const nextStatus = await setHFToken(key);
+
+        setStatus(nextStatus);
+
+        if (nextStatus === 'invalid') {
+          onError(t('models.huggingFaceToken'), t('models.huggingFaceRejectedToken'));
+        }
+      }}
+    />
+  );
+};
+
+const CivitaiKeyCard = ({ onError }: { onError: (message: string) => void }) => {
+  const { t } = useTranslation();
+  const [hasKey, setHasKey] = useState(() => getCivitaiApiKey() !== null);
+
+  return (
+    <ApiKeyCard
+      description={t('models.civitaiKeyDescription')}
+      icon={HexagonIcon}
+      placeholder={t('models.civitaiKeyPlaceholder')}
+      status={
+        hasKey
+          ? { label: t('models.keyStatus.saved'), palette: 'green' }
+          : { label: t('models.keyStatus.unknown'), palette: 'gray' }
+      }
+      title="Civitai"
+      onError={onError}
+      onClear={
+        hasKey
+          ? () => {
+              clearCivitaiApiKey();
+              setHasKey(false);
+            }
+          : undefined
+      }
+      onSave={(key) => {
+        setCivitaiApiKey(key);
+        setHasKey(true);
+      }}
+    />
+  );
+};
+
+const EXTERNAL_PROVIDER_PRESENTATION: Record<string, { title: string; icon: ElementType; placeholder: string }> = {
+  alibabacloud: { icon: SiAlibabacloud, placeholder: 'sk-…', title: 'Alibaba Cloud (Qwen)' },
+  gemini: { icon: SiGooglegemini, placeholder: 'AIza…', title: 'Google Gemini' },
+  openai: { icon: SiOpenai, placeholder: 'sk-…', title: 'OpenAI' },
+  seedream: { icon: SiBytedance, placeholder: 'byteplus', title: 'Seedream' },
+};
+
+const ExternalProviderKeyCards = ({ onError }: { onError: (title: string, message: string) => void }) => {
+  const { t } = useTranslation();
+  const [configs, setConfigs] = useState<ExternalProviderConfig[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let isStale = false;
+
+    getExternalProviderConfigs()
+      .then((providerConfigs) => {
+        if (!isStale) {
+          setConfigs(providerConfigs);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!isStale) {
+          setConfigs([]);
+          setLoadError(error instanceof Error ? error.message : t('models.failedToLoadExternalProviders'));
+        }
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [t]);
+
+  const replaceConfig = (next: ExternalProviderConfig) => {
+    setConfigs((current) => (current ?? []).map((config) => (config.provider_id === next.provider_id ? next : config)));
+  };
+
+  if (loadError) {
+    return (
+      <Text color="fg.error" fontSize="2xs">
+        {t('models.externalProvidersUnavailable', { error: loadError })}
+      </Text>
+    );
+  }
+
+  return (
+    <>
+      {(configs ?? []).map((config) => {
+        const presentation = EXTERNAL_PROVIDER_PRESENTATION[config.provider_id] ?? {
+          icon: HexagonIcon,
+          placeholder: 'generic',
+          title: config.provider_id,
+        };
+        const placeholder =
+          presentation.placeholder === 'byteplus'
+            ? t('models.bytePlusApiKeyPlaceholder')
+            : presentation.placeholder === 'generic'
+              ? t('models.apiKey')
+              : presentation.placeholder;
+
+        return (
+          <ExternalProviderKeyCard
+            config={config}
+            key={config.provider_id}
+            description={t('models.externalProviderKeyDescription')}
+            icon={presentation.icon}
+            placeholder={placeholder}
+            title={presentation.title}
+            onError={(message) => onError(presentation.title, message)}
+            onUpdated={replaceConfig}
+          />
+        );
+      })}
+    </>
+  );
+};
+
+const ExternalProviderKeyCard = ({
+  config,
+  description,
+  icon,
+  onError,
+  onUpdated,
+  placeholder,
+  title,
+}: {
+  config: ExternalProviderConfig;
+  description: string;
+  icon: ElementType;
+  onError: (message: string) => void;
+  onUpdated: (next: ExternalProviderConfig) => void;
+  placeholder: string;
+  title: string;
+}) => {
+  const { t } = useTranslation();
+  const [apiKeyDraft, setApiKeyDraft] = useState('');
+  const [baseUrlDraft, setBaseUrlDraft] = useState(config.base_url ?? '');
+  const [overrideBaseUrl, setOverrideBaseUrl] = useState(config.base_url !== null);
+  const [isBusy, setIsBusy] = useState(false);
+
+  useEffect(() => {
+    setApiKeyDraft('');
+    setBaseUrlDraft(config.base_url ?? '');
+    setOverrideBaseUrl(config.base_url !== null);
+  }, [config.base_url, config.provider_id]);
+
+  const hasApiKeyDraft = apiKeyDraft.trim().length > 0;
+  const hasBaseUrlChange = overrideBaseUrl ? baseUrlDraft.trim() !== (config.base_url ?? '') : config.base_url !== null;
+
+  const runAction = async (
+    action: () => Promise<ExternalProviderConfig>,
+    onSuccess?: (next: ExternalProviderConfig) => void
+  ): Promise<void> => {
+    setIsBusy(true);
+
+    try {
+      const nextConfig = await action();
+
+      onUpdated(nextConfig);
+      setApiKeyDraft('');
+      setBaseUrlDraft(nextConfig.base_url ?? '');
+      setOverrideBaseUrl(nextConfig.base_url !== null);
+      onSuccess?.(nextConfig);
+    } catch (error) {
+      onError(error instanceof Error ? error.message : t('common.somethingWentWrong'));
+    } finally {
+      setIsBusy(false);
+    }
+  };
+
+  const handleSave = async () => {
+    const apiKey = apiKeyDraft.trim();
+    const baseUrl = baseUrlDraft.trim();
+    const nextConfig: { api_key?: string; base_url?: string | null } = {};
+
+    if (apiKey.length > 0) {
+      nextConfig.api_key = apiKey;
+    }
+
+    if (!overrideBaseUrl && config.base_url !== null) {
+      nextConfig.base_url = '';
+    } else if (overrideBaseUrl && baseUrl !== (config.base_url ?? '')) {
+      nextConfig.base_url = baseUrl;
+    }
+
+    if (!nextConfig.api_key && nextConfig.base_url === undefined) {
+      return;
+    }
+
+    const apiKeyWasSet = nextConfig.api_key !== undefined;
+
+    await runAction(
+      () => setExternalProviderConfig(config.provider_id, nextConfig),
+      (next) => {
+        if (apiKeyWasSet && next.api_key_configured) {
+          // The backend queues this provider's external starter models on
+          // key-set; pull the new jobs and refresh starters so its rows flip to
+          // Installed without an app restart.
+          void refreshInstalls();
+          refreshStartersIfLoaded();
+        }
+      }
+    );
+  };
+
+  const canClear = config.api_key_configured || config.base_url !== null;
+
+  return (
+    <Stack bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" gap="2.5" p="3" rounded="lg">
+      <HStack align="start" gap="2.5">
+        <Flex
+          align="center"
+          bg="bg.emphasized"
+          borderColor="border.subtle"
+          borderWidth="1px"
+          boxSize="8"
+          color="fg.muted"
+          flexShrink={0}
+          justify="center"
+          rounded="md"
+        >
+          <Icon as={icon} boxSize="4" />
+        </Flex>
+        <Stack flex="1" gap="0" minW="0">
+          <HStack gap="1.5">
+            <Text fontSize="xs" fontWeight="700" truncate>
+              {title}
+            </Text>
+            <Badge
+              colorPalette={config.api_key_configured ? 'green' : 'gray'}
+              flexShrink={0}
+              fontSize="2xs"
+              size="sm"
+              variant="surface"
+            >
+              {config.api_key_configured ? t('models.keyStatus.configured') : t('models.keyStatus.unknown')}
+            </Badge>
+          </HStack>
+          <Text color="fg.subtle" fontSize="2xs" lineClamp={2}>
+            {description}
+          </Text>
+        </Stack>
+      </HStack>
+
+      <Stack gap="2">
+        <HStack gap="1.5">
+          <Input
+            aria-label={t('models.apiKeyFor', { title })}
+            disabled={isBusy}
+            placeholder={config.api_key_configured ? t('models.apiKeyConfigured') : placeholder}
+            size="xs"
+            type="password"
+            value={apiKeyDraft}
+            onChange={(event) => setApiKeyDraft(event.currentTarget.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                event.preventDefault();
+                void handleSave();
+              }
+            }}
+          />
+        </HStack>
+        <Switch.Root
+          checked={overrideBaseUrl}
+          disabled={isBusy}
+          size="sm"
+          onCheckedChange={(event) => {
+            const checked = event.checked === true;
+
+            setOverrideBaseUrl(checked);
+
+            if (!checked) {
+              setBaseUrlDraft('');
+            }
+          }}
+        >
+          <Switch.HiddenInput />
+          <Switch.Control _checked={{ bg: 'accent.solid' }}>
+            <Switch.Thumb />
+          </Switch.Control>
+          <Switch.Label color="fg.muted" fontSize="2xs">
+            {t('models.overrideBaseUrl')}
+          </Switch.Label>
+        </Switch.Root>
+        {overrideBaseUrl ? (
+          <Input
+            aria-label={t('models.baseUrlFor', { title })}
+            disabled={isBusy}
+            placeholder="https://api.example.com"
+            size="xs"
+            value={baseUrlDraft}
+            onChange={(event) => setBaseUrlDraft(event.currentTarget.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                event.preventDefault();
+                void handleSave();
+              }
+            }}
+          />
+        ) : null}
+      </Stack>
+
+      <HStack gap="1.5">
+        <Button
+          disabled={(!hasApiKeyDraft && !hasBaseUrlChange) || isBusy}
+          loading={isBusy}
+          size="xs"
+          variant="solid"
+          onClick={() => void handleSave()}
+        >
+          {t('common.save')}
+        </Button>
+        {canClear ? (
+          <Button
+            disabled={isBusy}
+            size="sm"
+            variant="ghost"
+            onClick={() => void runAction(() => resetExternalProviderConfig(config.provider_id))}
+          >
+            {t('common.clear')}
+          </Button>
+        ) : null}
+      </HStack>
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/DefaultSettingsSection.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/DefaultSettingsSection.tsx
new file mode 100644
index 00000000000..1ecaf6362aa
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/DefaultSettingsSection.tsx
@@ -0,0 +1,390 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { AnyModelDefaultSettings, ModelConfig } from '@workbench/models/types';
+import type { TFunction } from 'i18next';
+
+import { Grid, HStack, Icon, NativeSelect, NumberInput, Stack, Switch, Text } from '@chakra-ui/react';
+import { Button, FieldLabel, Panel } from '@workbench/components/ui';
+import { updateModel } from '@workbench/models/api';
+import { replaceModelInStore } from '@workbench/models/modelsStore';
+import { loraDefaultSettingsSchema, mainDefaultSettingsSchema } from '@workbench/models/schemas';
+import { MoveHorizontalIcon } from 'lucide-react';
+import { useMemo, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Per-model generation defaults ("use these settings when this model is
+ * selected"). Every field is individually toggleable: off = inherit the app
+ * default (stored as null). Validation runs through zod on save.
+ */
+
+const SCHEDULERS = [
+  'ddim',
+  'ddpm',
+  'deis',
+  'deis_k',
+  'dpmpp_2s',
+  'dpmpp_2s_k',
+  'dpmpp_2m',
+  'dpmpp_2m_k',
+  'dpmpp_2m_sde',
+  'dpmpp_2m_sde_k',
+  'dpmpp_3m',
+  'dpmpp_3m_k',
+  'dpmpp_sde',
+  'dpmpp_sde_k',
+  'euler',
+  'euler_k',
+  'euler_a',
+  'heun',
+  'heun_k',
+  'kdpm_2',
+  'kdpm_2_k',
+  'kdpm_2_a',
+  'kdpm_2_a_k',
+  'lcm',
+  'lms',
+  'lms_k',
+  'pndm',
+  'tcd',
+  'unipc',
+  'unipc_k',
+];
+
+const CONTROL_ADAPTER_TYPES = new Set(['controlnet', 't2i_adapter', 'control_lora']);
+
+const PREPROCESSORS = [
+  'canny_edge_detection',
+  'color_map',
+  'content_shuffle',
+  'depth_anything_depth_estimation',
+  'dw_openpose_detection',
+  'hed_edge_detection',
+  'lineart_anime_edge_detection',
+  'lineart_edge_detection',
+  'mediapipe_face_detection',
+  'mlsd_detection',
+  'normal_map',
+  'pidi_edge_detection',
+  'tile',
+];
+
+type DefaultSettingsModel = Pick<ModelConfig, 'default_settings' | 'key' | 'type'>;
+
+interface DefaultSettingsDraft {
+  modelKey: string;
+  settings: AnyModelDefaultSettings;
+  source: AnyModelDefaultSettings | null | undefined;
+}
+
+export const supportsDefaultSettings = (model: Pick<ModelConfig, 'type'>): boolean =>
+  model.type === 'main' || model.type === 'lora' || CONTROL_ADAPTER_TYPES.has(model.type);
+
+interface FieldSpec {
+  key: keyof AnyModelDefaultSettings;
+  labelKey: string;
+  /** Render the control; disabled (showing the inherited value) until customized. */
+  control: (value: unknown, setValue: (value: unknown) => void, disabled: boolean) => ReactNode;
+  /** Value used when the toggle is switched on; also previewed while off. */
+  defaultValue: unknown;
+  /** Translation key for what applies while the toggle is off. */
+  inheritLabelKey: string;
+}
+
+const numberControl =
+  (props: { max?: number; min?: number; step?: number }) =>
+  (value: unknown, setValue: (value: unknown) => void, disabled: boolean) => (
+    <NumberInput.Root
+      disabled={disabled}
+      max={props.max}
+      min={props.min}
+      position="relative"
+      size="sm"
+      step={props.step ?? 1}
+      value={typeof value === 'number' ? String(value) : ''}
+      w="full"
+      onValueChange={(details) => {
+        // Empty/partial input is transient; only commit finite numbers so the
+        // field never silently flips back to "off".
+        if (Number.isFinite(details.valueAsNumber)) {
+          setValue(details.valueAsNumber);
+        }
+      }}
+    >
+      <NumberInput.Control />
+      {/* Drag horizontally on the handle to scrub the value. */}
+      <NumberInput.Scrubber
+        alignItems="center"
+        bottom="0"
+        cursor="ew-resize"
+        display="flex"
+        left="2"
+        position="absolute"
+        top="0"
+        zIndex={1}
+      >
+        <Icon as={MoveHorizontalIcon} boxSize="3" color="fg.subtle" />
+      </NumberInput.Scrubber>
+      <NumberInput.Input ps="7" />
+    </NumberInput.Root>
+  );
+
+const selectControl =
+  (options: string[]) => (value: unknown, setValue: (value: unknown) => void, disabled: boolean) => (
+    <NativeSelect.Root disabled={disabled} size="sm">
+      <NativeSelect.Field
+        value={typeof value === 'string' ? value : ''}
+        onChange={(event) => setValue(event.currentTarget.value)}
+      >
+        {options.map((option) => (
+          <option key={option} value={option}>
+            {option}
+          </option>
+        ))}
+      </NativeSelect.Field>
+      <NativeSelect.Indicator />
+    </NativeSelect.Root>
+  );
+
+const MAIN_FIELDS: FieldSpec[] = [
+  {
+    control: selectControl(SCHEDULERS),
+    defaultValue: 'euler_a',
+    inheritLabelKey: 'models.defaultFieldInherited.scheduler',
+    key: 'scheduler',
+    labelKey: 'models.defaultFields.scheduler',
+  },
+  {
+    control: numberControl({ max: 10000, min: 1 }),
+    defaultValue: 30,
+    inheritLabelKey: 'models.defaultFieldInherited.steps',
+    key: 'steps',
+    labelKey: 'models.defaultFields.steps',
+  },
+  {
+    control: numberControl({ max: 200, min: 1, step: 0.5 }),
+    defaultValue: 7,
+    inheritLabelKey: 'models.defaultFieldInherited.cfgScale',
+    key: 'cfg_scale',
+    labelKey: 'models.defaultFields.cfgScale',
+  },
+  {
+    control: numberControl({ max: 0.99, min: 0, step: 0.05 }),
+    defaultValue: 0,
+    inheritLabelKey: 'models.defaultFieldInherited.cfgRescale',
+    key: 'cfg_rescale_multiplier',
+    labelKey: 'models.defaultFields.cfgRescale',
+  },
+  {
+    control: numberControl({ max: 20, min: 1, step: 0.5 }),
+    defaultValue: 4,
+    inheritLabelKey: 'models.defaultFieldInherited.guidance',
+    key: 'guidance',
+    labelKey: 'models.defaultFields.guidance',
+  },
+  {
+    control: numberControl({ max: 8192, min: 64, step: 8 }),
+    defaultValue: 1024,
+    inheritLabelKey: 'models.defaultFieldInherited.width',
+    key: 'width',
+    labelKey: 'models.defaultFields.width',
+  },
+  {
+    control: numberControl({ max: 8192, min: 64, step: 8 }),
+    defaultValue: 1024,
+    inheritLabelKey: 'models.defaultFieldInherited.height',
+    key: 'height',
+    labelKey: 'models.defaultFields.height',
+  },
+  {
+    control: selectControl(['fp16', 'fp32']),
+    defaultValue: 'fp16',
+    inheritLabelKey: 'models.defaultFieldInherited.vaePrecision',
+    key: 'vae_precision',
+    labelKey: 'models.defaultFields.vaePrecision',
+  },
+];
+
+const LORA_FIELDS: FieldSpec[] = [
+  {
+    control: numberControl({ max: 10, min: -10, step: 0.05 }),
+    defaultValue: 0.75,
+    inheritLabelKey: 'models.defaultFieldInherited.weight',
+    key: 'weight',
+    labelKey: 'models.defaultFields.weight',
+  },
+];
+
+const CONTROL_ADAPTER_FIELDS: FieldSpec[] = [
+  {
+    control: selectControl(PREPROCESSORS),
+    defaultValue: 'canny_edge_detection',
+    inheritLabelKey: 'models.defaultFieldInherited.preprocessor',
+    key: 'preprocessor',
+    labelKey: 'models.defaultFields.preprocessor',
+  },
+];
+
+const getFieldsForModel = (model: Pick<ModelConfig, 'type'>): FieldSpec[] => {
+  if (model.type === 'main') {
+    return MAIN_FIELDS;
+  }
+
+  if (model.type === 'lora') {
+    return LORA_FIELDS;
+  }
+
+  return CONTROL_ADAPTER_FIELDS;
+};
+
+const validateDefaults = (
+  model: Pick<ModelConfig, 'type'>,
+  settings: AnyModelDefaultSettings,
+  t: TFunction
+): string | null => {
+  if (model.type === 'main') {
+    const result = mainDefaultSettingsSchema.safeParse({
+      cfgRescaleMultiplier: settings.cfg_rescale_multiplier ?? null,
+      cfgScale: settings.cfg_scale ?? null,
+      guidance: settings.guidance ?? null,
+      height: settings.height ?? null,
+      scheduler: settings.scheduler ?? null,
+      steps: settings.steps ?? null,
+      vaePrecision: settings.vae_precision ?? null,
+      width: settings.width ?? null,
+    });
+
+    return result.success ? null : (result.error.issues[0]?.message ?? t('models.invalidDefaultSettings'));
+  }
+
+  if (model.type === 'lora') {
+    const result = loraDefaultSettingsSchema.safeParse({ weight: settings.weight ?? null });
+
+    return result.success ? null : (result.error.issues[0]?.message ?? t('models.invalidDefaultSettings'));
+  }
+
+  return null;
+};
+
+export const DefaultSettingsSection = ({
+  model,
+  onError,
+  onSaved,
+}: {
+  model: DefaultSettingsModel;
+  onError: (message: string) => void;
+  onSaved: () => void;
+}) => {
+  const { t } = useTranslation();
+  const fields = useMemo(() => getFieldsForModel(model), [model]);
+  const [draft, setDraft] = useState<DefaultSettingsDraft>(() => ({
+    modelKey: model.key,
+    settings: { ...model.default_settings },
+    source: model.default_settings,
+  }));
+  const [error, setError] = useState<string | null>(null);
+  const [isSaving, setIsSaving] = useState(false);
+  const isDraftCurrent = draft.modelKey === model.key && draft.source === model.default_settings;
+  const savedSettingsDraft = useMemo(() => ({ ...model.default_settings }), [model.default_settings]);
+  const settings = isDraftCurrent ? draft.settings : savedSettingsDraft;
+  const visibleError = isDraftCurrent ? error : null;
+  const visibleIsSaving = isDraftCurrent ? isSaving : false;
+
+  const isDirty = useMemo(() => {
+    const saved = model.default_settings ?? {};
+
+    return fields.some((field) => (settings[field.key] ?? null) !== (saved[field.key] ?? null));
+  }, [fields, model.default_settings, settings]);
+
+  const setFieldValue = (key: keyof AnyModelDefaultSettings, value: unknown) => {
+    setDraft({
+      modelKey: model.key,
+      settings: { ...settings, [key]: value as never },
+      source: model.default_settings,
+    });
+    setError(null);
+  };
+
+  const handleSave = async () => {
+    const validationError = validateDefaults(model, settings, t);
+
+    if (validationError) {
+      setError(validationError);
+      return;
+    }
+
+    setIsSaving(true);
+
+    try {
+      replaceModelInStore(await updateModel(model.key, { default_settings: settings }));
+      onSaved();
+    } catch (saveError) {
+      onError(saveError instanceof Error ? saveError.message : t('models.failedToSaveDefaults'));
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  return (
+    <Stack gap="3">
+      <HStack justify="space-between">
+        <Stack gap="0.5">
+          <FieldLabel>{t('models.defaultSettings')}</FieldLabel>
+          <Text color="fg.subtle" fontSize="2xs">
+            {t('models.defaultSettingsHelp')}
+          </Text>
+        </Stack>
+        <Button
+          disabled={!isDirty}
+          loading={visibleIsSaving}
+          size="xs"
+          variant="solid"
+          onClick={() => void handleSave()}
+        >
+          {t('models.saveDefaults')}
+        </Button>
+      </HStack>
+      {visibleError ? (
+        <Text color="fg.error" fontSize="2xs" role="alert">
+          {visibleError}
+        </Text>
+      ) : null}
+      <Grid gap="2.5" templateColumns="repeat(auto-fill, minmax(13rem, 1fr))">
+        {fields.map((field) => {
+          const value = settings[field.key] ?? null;
+          const isEnabled = value !== null && value !== undefined;
+
+          return (
+            <Panel key={field.key} gap="2" p="2.5" tone="control">
+              <HStack justify="space-between">
+                <Text fontSize="2xs" fontWeight="600" textTransform="uppercase">
+                  {t(field.labelKey)}
+                </Text>
+                <Switch.Root
+                  checked={isEnabled}
+                  colorPalette="accent"
+                  size="xs"
+                  onCheckedChange={(event) => setFieldValue(field.key, event.checked ? field.defaultValue : null)}
+                >
+                  <Switch.HiddenInput />
+                  <Switch.Control>
+                    <Switch.Thumb />
+                  </Switch.Control>
+                  <Switch.Label srOnly>{t('models.customizeDefaultField', { field: t(field.labelKey) })}</Switch.Label>
+                </Switch.Root>
+              </HStack>
+              {field.control(
+                isEnabled ? value : field.defaultValue,
+                (nextValue) => setFieldValue(field.key, nextValue),
+                !isEnabled
+              )}
+              <Text color="fg.subtle" fontSize="2xs">
+                {isEnabled ? t('models.customizedForThisModel') : t(field.inheritLabelKey)}
+              </Text>
+            </Panel>
+          );
+        })}
+      </Grid>
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelBadges.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelBadges.tsx
new file mode 100644
index 00000000000..347fbb2075c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelBadges.tsx
@@ -0,0 +1,31 @@
+import type { ModelConfig } from '@workbench/models/types';
+
+import { Badge, HStack } from '@chakra-ui/react';
+import { getModelBaseColorPalette, getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { getModelFormatLabel } from '@workbench/models/taxonomy';
+
+export const ModelBaseBadge = ({ base }: { base: ModelConfig['base'] }) => (
+  <Badge colorPalette={getModelBaseColorPalette(base)} flexShrink={0} fontSize="2xs" size="sm" variant="surface">
+    {getModelBaseLabel(base)}
+  </Badge>
+);
+
+export const ModelFormatBadge = ({ format }: { format: ModelConfig['format'] }) => (
+  <Badge colorPalette="gray" flexShrink={0} fontSize="2xs" size="sm" variant="outline">
+    {getModelFormatLabel(format)}
+  </Badge>
+);
+
+export const MissingFileBadge = () => (
+  <Badge colorPalette="red" flexShrink={0} fontSize="2xs" size="sm" variant="surface">
+    Missing file
+  </Badge>
+);
+
+export const ModelBadgeRow = ({ isMissing, model }: { isMissing?: boolean; model: ModelConfig }) => (
+  <HStack gap="1" minW="0" wrap="wrap">
+    <ModelBaseBadge base={model.base} />
+    <ModelFormatBadge format={model.format} />
+    {isMissing ? <MissingFileBadge /> : null}
+  </HStack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelDetail.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelDetail.tsx
new file mode 100644
index 00000000000..36447916ae4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelDetail.tsx
@@ -0,0 +1,444 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { AnyModelDefaultSettings, ModelConfig, ModelTaxonomyType } from '@workbench/models/types';
+
+import { DataList, HStack, Icon, Menu, Portal, Separator, Stack, Text } from '@chakra-ui/react';
+import { Button, IconButton, ConfirmDialog, MenuContent } from '@workbench/components/ui';
+import { isConvertibleToDiffusers } from '@workbench/models/baseIdentity';
+import { useModelsSelector } from '@workbench/models/modelsStore';
+import { formatBytes } from '@workbench/models/taxonomy';
+import { useNotify } from '@workbench/useNotify';
+import { areArraysEqual } from '@workbench/workbenchSelectors';
+import { ArrowLeftIcon, MoreHorizontalIcon, PencilIcon, RefreshCcwIcon, Trash2Icon } from 'lucide-react';
+import { memo, useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { SiHuggingface } from 'react-icons/si';
+
+import { DefaultSettingsSection, supportsDefaultSettings } from './DefaultSettingsSection';
+import { MissingFileBadge, ModelBaseBadge, ModelFormatBadge } from './ModelBadges';
+import { ModelEditForm } from './ModelEditForm';
+import { ModelImageUpload } from './ModelImageUpload';
+import { RelatedModelsSection } from './RelatedModelsSection';
+import { MemoizedTriggerPhrasesEditor } from './TriggerPhrasesEditor';
+import { useModelActions } from './useModelActions';
+
+const TRIGGER_PHRASE_TYPES = new Set(['main', 'lora', 'embedding']);
+const RELATED_MODEL_TYPES = new Set(['main', 'lora']);
+const EMPTY_TRIGGER_PHRASES: readonly string[] = [];
+
+type ModelDetailShellModel = Pick<ModelConfig, 'key' | 'type'>;
+type DefaultSettingsModel = { default_settings?: AnyModelDefaultSettings | null; key: string; type: ModelTaxonomyType };
+type TriggerPhrasesModel = Pick<ModelConfig, 'key' | 'trigger_phrases'>;
+type ModelIdentityModel = Pick<
+  ModelConfig,
+  | 'base'
+  | 'cover_image'
+  | 'description'
+  | 'file_size'
+  | 'format'
+  | 'hash'
+  | 'key'
+  | 'name'
+  | 'path'
+  | 'prediction_type'
+  | 'source'
+  | 'source_url'
+  | 'type'
+  | 'variant'
+>;
+
+const findModel = (models: readonly ModelConfig[], modelKey: string): ModelConfig | undefined =>
+  models.find((candidate) => candidate.key === modelKey);
+
+const selectModelShell = (models: readonly ModelConfig[], modelKey: string): ModelDetailShellModel | null => {
+  const model = findModel(models, modelKey);
+
+  return model ? { key: model.key, type: model.type } : null;
+};
+
+const selectModelIdentity = (models: readonly ModelConfig[], modelKey: string): ModelIdentityModel | null => {
+  const model = findModel(models, modelKey);
+
+  return model
+    ? {
+        base: model.base,
+        cover_image: model.cover_image,
+        description: model.description,
+        file_size: model.file_size,
+        format: model.format,
+        hash: model.hash,
+        key: model.key,
+        name: model.name,
+        path: model.path,
+        prediction_type: model.prediction_type,
+        source: model.source,
+        source_url: model.source_url,
+        type: model.type,
+        variant: model.variant,
+      }
+    : null;
+};
+
+const selectDefaultSettingsModel = (models: readonly ModelConfig[], modelKey: string): DefaultSettingsModel | null => {
+  const model = findModel(models, modelKey);
+
+  return model ? { default_settings: model.default_settings, key: model.key, type: model.type } : null;
+};
+
+const selectTriggerPhrasesModel = (models: readonly ModelConfig[], modelKey: string): TriggerPhrasesModel | null => {
+  const model = findModel(models, modelKey);
+
+  return model ? { key: model.key, trigger_phrases: model.trigger_phrases } : null;
+};
+
+const areTriggerPhrasesModelsEqual = (left: TriggerPhrasesModel | null, right: TriggerPhrasesModel | null): boolean =>
+  left?.key === right?.key && areArraysEqual(left?.trigger_phrases ?? [], right?.trigger_phrases ?? []);
+
+/**
+ * Full detail pane for one model: identity (view/edit), per-model default
+ * settings, related models, trigger phrases, and lifecycle actions (convert,
+ * re-identify, delete). Mount keyed by model key so per-model form state never
+ * leaks between models. `density="panel"` tightens the side-panel drill-in.
+ */
+export const ModelDetail = ({
+  density = 'full',
+  modelKey,
+  onBack,
+  onDeleted,
+}: {
+  density?: 'panel' | 'full';
+  modelKey: string;
+  onBack?: () => void;
+  onDeleted: () => void;
+}) => {
+  const model = useModelsSelector((snapshot) => selectModelShell(snapshot.models, modelKey));
+
+  if (!model) {
+    return (
+      <Stack align="start" gap="2" p="1">
+        {onBack ? <BackButton onBack={onBack} /> : null}
+        <Text color="fg.subtle" fontSize="xs">
+          This model is no longer in the library.
+        </Text>
+      </Stack>
+    );
+  }
+
+  return (
+    <Stack gap={density === 'panel' ? '3' : '4'} pb="4">
+      {onBack ? <BackButton onBack={onBack} /> : null}
+
+      <ModelIdentitySectionContainer density={density} modelKey={model.key} onDeleted={onDeleted} />
+
+      {supportsDefaultSettings(model) ? (
+        <>
+          <Separator borderColor="border.subtle" />
+          <DefaultSettingsSectionContainer modelKey={model.key} />
+        </>
+      ) : null}
+
+      {RELATED_MODEL_TYPES.has(model.type) ? (
+        <>
+          <Separator borderColor="border.subtle" />
+          <RelatedModelsSectionContainer modelKey={model.key} />
+        </>
+      ) : null}
+
+      {TRIGGER_PHRASE_TYPES.has(model.type) ? (
+        <>
+          <Separator borderColor="border.subtle" />
+          <TriggerPhrasesEditorContainer modelKey={model.key} />
+        </>
+      ) : null}
+    </Stack>
+  );
+};
+
+interface ModelIdentitySectionProps {
+  density: 'panel' | 'full';
+  isMissing: boolean;
+  model: ModelIdentityModel;
+  onDeleted: () => void;
+}
+
+const ModelIdentitySectionContainer = memo(function ModelIdentitySectionContainer({
+  density,
+  modelKey,
+  onDeleted,
+}: {
+  density: 'panel' | 'full';
+  modelKey: string;
+  onDeleted: () => void;
+}) {
+  const model = useModelsSelector((snapshot) => selectModelIdentity(snapshot.models, modelKey));
+  const isMissing = useModelsSelector((snapshot) => snapshot.missingModelKeys.has(modelKey));
+
+  if (!model) {
+    return null;
+  }
+
+  return <ModelIdentitySection density={density} isMissing={isMissing} model={model} onDeleted={onDeleted} />;
+});
+
+const ModelIdentitySection = memo(function ModelIdentitySection({
+  density,
+  isMissing,
+  model,
+  onDeleted,
+}: ModelIdentitySectionProps) {
+  const notify = useNotify();
+  const { t } = useTranslation();
+  const [editingModelKey, setEditingModelKey] = useState<string | null>(null);
+  const isEditing = editingModelKey === model.key;
+
+  return (
+    <>
+      <HStack align="start" gap="3">
+        <ModelImageUpload
+          key={model.key}
+          model={model}
+          onError={(message) => notify.error(t('models.modelImage'), message)}
+          onUpdated={() => notify.success(t('models.modelImageUpdated'))}
+        />
+        <Stack flex="1" gap="1" minW="0">
+          <Text fontSize="sm" fontWeight="700" lineClamp={2}>
+            {model.name}
+          </Text>
+          <HStack gap="1" minW="0" wrap="wrap">
+            <ModelBaseBadge base={model.base} />
+            <ModelFormatBadge format={model.format} />
+          </HStack>
+          {isMissing ? (
+            <HStack gap="1.5">
+              <MissingFileBadge />
+              <Text color="fg.subtle" fontSize="2xs">
+                {t('models.fileNotFoundOnDisk')}
+              </Text>
+            </HStack>
+          ) : null}
+          {model.description ? (
+            <Text color="fg.muted" fontSize="2xs" lineClamp={3}>
+              {model.description}
+            </Text>
+          ) : null}
+        </Stack>
+        <ModelDetailActions
+          isEditing={isEditing}
+          model={model}
+          onDeleted={onDeleted}
+          onToggleEditing={() => setEditingModelKey((key) => (key === model.key ? null : model.key))}
+        />
+      </HStack>
+
+      {isEditing ? (
+        <ModelEditForm
+          model={model}
+          onCancel={() => setEditingModelKey(null)}
+          onSaved={() => {
+            setEditingModelKey(null);
+            notify.success(t('models.modelUpdated'), model.name);
+          }}
+        />
+      ) : (
+        <ModelAttributes density={density} model={model} />
+      )}
+    </>
+  );
+});
+
+const ModelDetailActions = ({
+  isEditing,
+  model,
+  onDeleted,
+  onToggleEditing,
+}: {
+  isEditing: boolean;
+  model: ModelIdentityModel;
+  onDeleted: () => void;
+  onToggleEditing: () => void;
+}) => {
+  const { t } = useTranslation();
+  const { convert, reidentify, remove } = useModelActions();
+  const [pendingAction, setPendingAction] = useState<'delete' | 'convert' | null>(null);
+  const [isActionBusy, setIsActionBusy] = useState(false);
+
+  const handleReidentify = async () => {
+    setIsActionBusy(true);
+
+    try {
+      await reidentify(model);
+    } finally {
+      setIsActionBusy(false);
+    }
+  };
+
+  return (
+    <HStack flexShrink={0} gap="1" wrap="wrap">
+      {isConvertibleToDiffusers(model) ? (
+        <Button size="xs" variant="outline" onClick={() => setPendingAction('convert')}>
+          <Icon as={SiHuggingface} boxSize="3" />
+          {t('models.convertToDiffusers')}
+        </Button>
+      ) : null}
+      <Button size="xs" variant={isEditing ? 'solid' : 'outline'} onClick={onToggleEditing}>
+        <Icon as={PencilIcon} boxSize="3" />
+        {isEditing ? t('models.editing') : t('common.edit')}
+      </Button>
+      <Menu.Root positioning={{ placement: 'bottom-end' }}>
+        <Menu.Trigger asChild>
+          <IconButton aria-label={t('models.actions')} loading={isActionBusy} size="xs" variant="ghost">
+            <Icon as={MoreHorizontalIcon} boxSize="4" />
+          </IconButton>
+        </Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent minW="12rem">
+              <Menu.Item value="reidentify" onClick={() => void handleReidentify()}>
+                <Icon as={RefreshCcwIcon} boxSize="3.5" />
+                <Menu.ItemText fontSize="xs">{t('models.reidentify')}</Menu.ItemText>
+              </Menu.Item>
+              <Menu.Separator />
+              <Menu.Item color="fg.error" value="delete" onClick={() => setPendingAction('delete')}>
+                <Icon as={Trash2Icon} boxSize="3.5" />
+                <Menu.ItemText fontSize="xs">{t('models.deleteModel')}</Menu.ItemText>
+              </Menu.Item>
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <ConfirmDialog
+        body={t('models.deleteBody', { name: model.name })}
+        confirmLabel={t('models.deleteModel')}
+        isOpen={pendingAction === 'delete'}
+        title={t('models.deleteModel')}
+        onClose={() => setPendingAction(null)}
+        onConfirm={async () => {
+          await remove(model);
+          onDeleted();
+        }}
+      />
+      {/* Destructive styling: the original checkpoint file is replaced. */}
+      <ConfirmDialog
+        body={t('models.convertBody', { name: model.name })}
+        confirmLabel={t('models.convert')}
+        isOpen={pendingAction === 'convert'}
+        title={t('models.convertToDiffusers')}
+        onClose={() => setPendingAction(null)}
+        onConfirm={() => convert(model)}
+      />
+    </HStack>
+  );
+};
+
+const DefaultSettingsSectionContainer = memo(function DefaultSettingsSectionContainer({
+  modelKey,
+}: {
+  modelKey: string;
+}) {
+  const notify = useNotify();
+  const { t } = useTranslation();
+  const model = useModelsSelector((snapshot) => selectDefaultSettingsModel(snapshot.models, modelKey));
+
+  if (!model || !supportsDefaultSettings(model)) {
+    return null;
+  }
+
+  return (
+    <DefaultSettingsSection
+      model={model}
+      onError={(message) => notify.error(t('models.defaultSettings'), message)}
+      onSaved={() => notify.success(t('models.defaultSettingsSaved'))}
+    />
+  );
+});
+
+const TriggerPhrasesEditorContainer = memo(function TriggerPhrasesEditorContainer({ modelKey }: { modelKey: string }) {
+  const notify = useNotify();
+  const { t } = useTranslation();
+  const handleError = useCallback((message: string) => notify.error(t('models.triggerPhrases'), message), [notify, t]);
+  const model = useModelsSelector(
+    (snapshot) => selectTriggerPhrasesModel(snapshot.models, modelKey),
+    areTriggerPhrasesModelsEqual
+  );
+
+  if (!model) {
+    return null;
+  }
+
+  return (
+    <MemoizedTriggerPhrasesEditor
+      modelKey={model.key}
+      phrases={model.trigger_phrases ?? EMPTY_TRIGGER_PHRASES}
+      onError={handleError}
+    />
+  );
+});
+
+const RelatedModelsSectionContainer = memo(function RelatedModelsSectionContainer({ modelKey }: { modelKey: string }) {
+  const notify = useNotify();
+  const { t } = useTranslation();
+  const model = useModelsSelector(
+    (snapshot) => {
+      const candidate = snapshot.models.find((model) => model.key === modelKey);
+
+      return candidate ? { base: candidate.base, key: candidate.key } : null;
+    },
+    (left, right) => left?.key === right?.key && left?.base === right?.base
+  );
+  const handleSectionError = useCallback(
+    (message: string) => notify.error(t('models.modelManager'), message),
+    [notify, t]
+  );
+
+  if (!model) {
+    return null;
+  }
+
+  return <RelatedModelsSection model={model} onError={handleSectionError} />;
+});
+
+const BackButton = ({ onBack }: { onBack: () => void }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Button alignSelf="start" size="2xs" variant="ghost" onClick={onBack}>
+      <Icon as={ArrowLeftIcon} boxSize="3" />
+      {t('models.allModels')}
+    </Button>
+  );
+};
+
+const isAbsolutePath = (path: string): boolean => path.startsWith('/') || /^[A-Za-z]:[\\/]/.test(path);
+
+const ModelAttributes = ({ density, model }: { density: 'panel' | 'full'; model: ModelIdentityModel }) => {
+  const { t } = useTranslation();
+  const modelsDir = useModelsSelector((snapshot) => snapshot.modelsDir);
+  // Managed models store paths relative to the models directory; show the
+  // resolved absolute path so it can be found on disk.
+  const fullPath =
+    isAbsolutePath(model.path) || !modelsDir ? model.path : `${modelsDir.replace(/\/+$/, '')}/${model.path}`;
+
+  const attributes: { label: string; value: string }[] = [
+    { label: t('models.fileSize'), value: formatBytes(model.file_size) },
+    { label: t('models.variant'), value: model.variant ?? '—' },
+    { label: t('models.predictionType'), value: model.prediction_type ?? '—' },
+    { label: t('models.hash'), value: model.hash },
+    { label: t('models.path'), value: fullPath },
+    { label: t('models.source'), value: model.source },
+  ];
+
+  return (
+    <DataList.Root gap="2.5" orientation={density === 'panel' ? 'vertical' : 'horizontal'} size="sm" variant="subtle">
+      {attributes.map((attribute) => (
+        <DataList.Item key={attribute.label}>
+          <DataList.ItemLabel color="fg.subtle" fontSize="2xs" minW="8rem" textTransform="uppercase">
+            {attribute.label}
+          </DataList.ItemLabel>
+          <DataList.ItemValue fontSize="2xs" overflowWrap="anywhere">
+            {attribute.value}
+          </DataList.ItemValue>
+        </DataList.Item>
+      ))}
+    </DataList.Root>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelEditForm.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelEditForm.tsx
new file mode 100644
index 00000000000..20ebd42e8d3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelEditForm.tsx
@@ -0,0 +1,174 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelConfig, PredictionType } from '@workbench/models/types';
+
+import { HStack, Input, NativeSelect, Stack, Text, Textarea } from '@chakra-ui/react';
+import { Button, Field } from '@workbench/components/ui';
+import { updateModel } from '@workbench/models/api';
+import { getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { replaceModelInStore } from '@workbench/models/modelsStore';
+import { modelEditSchema, type ModelEditFormValues } from '@workbench/models/schemas';
+import { getModelTypeLabel, MODEL_CATEGORIES } from '@workbench/models/taxonomy';
+import { useZodForm } from '@workbench/models/useZodForm';
+import { useTranslation } from 'react-i18next';
+
+const KNOWN_BASES = [
+  'sd-1',
+  'sd-2',
+  'sd-3',
+  'sdxl',
+  'sdxl-refiner',
+  'flux',
+  'flux2',
+  'cogview4',
+  'qwen-image',
+  'z-image',
+  'anima',
+  'any',
+  'unknown',
+];
+
+/** Zod-validated editor for a model's identity fields. */
+type ModelEditTarget = Pick<
+  ModelConfig,
+  'base' | 'description' | 'key' | 'name' | 'prediction_type' | 'source_url' | 'type' | 'variant'
+>;
+
+export const ModelEditForm = ({
+  model,
+  onCancel,
+  onSaved,
+}: {
+  model: ModelEditTarget;
+  onCancel: () => void;
+  onSaved: () => void;
+}) => {
+  const { t } = useTranslation();
+  const form = useZodForm(modelEditSchema, {
+    base: String(model.base),
+    description: model.description ?? '',
+    name: model.name,
+    predictionType: (model.prediction_type ?? '') as ModelEditFormValues['predictionType'],
+    sourceUrl: model.source_url ?? '',
+    type: String(model.type),
+    variant: model.variant ?? '',
+  });
+
+  const bases = KNOWN_BASES.includes(String(model.base)) ? KNOWN_BASES : [String(model.base), ...KNOWN_BASES];
+
+  const handleSave = () =>
+    form.handleSubmit(async (values) => {
+      const updated = await updateModel(model.key, {
+        base: values.base,
+        description: values.description || null,
+        name: values.name,
+        prediction_type: values.predictionType === '' ? null : (values.predictionType as PredictionType),
+        source_url: values.sourceUrl === '' ? null : values.sourceUrl,
+        type: values.type,
+        variant: values.variant === '' ? null : values.variant,
+      });
+
+      replaceModelInStore(updated);
+      onSaved();
+    });
+
+  return (
+    <Stack gap="3">
+      <Field error={form.errors.name} label={t('common.name')}>
+        <Input
+          aria-invalid={form.errors.name ? true : undefined}
+          size="sm"
+          value={form.values.name}
+          onChange={(event) => form.setValue('name', event.currentTarget.value)}
+        />
+      </Field>
+      <Field error={form.errors.description} label={t('models.description')}>
+        <Textarea
+          rows={2}
+          size="sm"
+          value={form.values.description}
+          onChange={(event) => form.setValue('description', event.currentTarget.value)}
+        />
+      </Field>
+      <HStack align="start" gap="2">
+        <Field error={form.errors.base} label={t('models.base')}>
+          <NativeSelect.Root size="sm">
+            <NativeSelect.Field
+              value={form.values.base}
+              onChange={(event) => form.setValue('base', event.currentTarget.value)}
+            >
+              {bases.map((base) => (
+                <option key={base} value={base}>
+                  {getModelBaseLabel(base)}
+                </option>
+              ))}
+            </NativeSelect.Field>
+            <NativeSelect.Indicator />
+          </NativeSelect.Root>
+        </Field>
+        <Field error={form.errors.type} label={t('models.type')}>
+          <NativeSelect.Root size="sm">
+            <NativeSelect.Field
+              value={form.values.type}
+              onChange={(event) => form.setValue('type', event.currentTarget.value)}
+            >
+              {MODEL_CATEGORIES.map((category) => (
+                <option key={category.type} value={category.type}>
+                  {getModelTypeLabel(category.type)}
+                </option>
+              ))}
+            </NativeSelect.Field>
+            <NativeSelect.Indicator />
+          </NativeSelect.Root>
+        </Field>
+      </HStack>
+      <HStack align="start" gap="2">
+        <Field error={form.errors.variant} helpText={t('models.variantHelp')} label={t('models.variant')}>
+          <Input
+            size="sm"
+            value={form.values.variant}
+            onChange={(event) => form.setValue('variant', event.currentTarget.value)}
+          />
+        </Field>
+        <Field error={form.errors.predictionType} label={t('models.predictionType')}>
+          <NativeSelect.Root size="sm">
+            <NativeSelect.Field
+              value={form.values.predictionType}
+              onChange={(event) =>
+                form.setValue('predictionType', event.currentTarget.value as ModelEditFormValues['predictionType'])
+              }
+            >
+              <option value="">{t('common.none')}</option>
+              <option value="epsilon">epsilon</option>
+              <option value="v_prediction">v_prediction</option>
+              <option value="sample">sample</option>
+            </NativeSelect.Field>
+            <NativeSelect.Indicator />
+          </NativeSelect.Root>
+        </Field>
+      </HStack>
+      <Field error={form.errors.sourceUrl} helpText={t('models.sourceUrlHelp')} label={t('models.sourceUrl')}>
+        <Input
+          aria-invalid={form.errors.sourceUrl ? true : undefined}
+          placeholder="https://…"
+          size="sm"
+          value={form.values.sourceUrl}
+          onChange={(event) => form.setValue('sourceUrl', event.currentTarget.value)}
+        />
+      </Field>
+      {form.formError ? (
+        <Text color="fg.error" fontSize="2xs" role="alert">
+          {form.formError}
+        </Text>
+      ) : null}
+      <HStack gap="2" justify="flex-end">
+        <Button disabled={form.isSubmitting} size="xs" variant="ghost" onClick={onCancel}>
+          {t('common.cancel')}
+        </Button>
+        <Button loading={form.isSubmitting} size="xs" variant="solid" onClick={() => void handleSave()}>
+          {t('users.saveChanges')}
+        </Button>
+      </HStack>
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelImageUpload.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelImageUpload.tsx
new file mode 100644
index 00000000000..bbe52ef0f87
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/ModelImageUpload.tsx
@@ -0,0 +1,220 @@
+/* eslint-disable react/react-compiler, react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelConfig } from '@workbench/models/types';
+
+import { Box, Flex, Icon, Image, Stack, Text } from '@chakra-ui/react';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { deleteModelImage, getModelImageUrl, updateModelImage } from '@workbench/models/api';
+import { markCoverImageChanged, useModelsSelector } from '@workbench/models/modelsStore';
+import { ImageIcon, UploadIcon, XIcon } from 'lucide-react';
+import { useEffect, useRef, useState, type DragEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const ACCEPTED_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
+
+const dragContainsFiles = (event: DragEvent): boolean => Array.from(event.dataTransfer.types).includes('Files');
+
+/**
+ * The model's cover image as one large dropzone: click anywhere on the tile
+ * or drop an image file onto it to upload. The remove button sits in the top
+ * corner and is hover/focus-revealed (and inert while hidden).
+ */
+export const ModelImageUpload = ({
+  model,
+  onError,
+  onUpdated,
+}: {
+  model: Pick<ModelConfig, 'cover_image' | 'key' | 'name'>;
+  onError: (message: string) => void;
+  onUpdated: () => void;
+}) => {
+  const { t } = useTranslation();
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const dragDepthRef = useRef(0);
+  const imageVersion = useModelsSelector((snapshot) => snapshot.coverImageVersions[model.key]);
+  const [hasImage, setHasImage] = useState(Boolean(model.cover_image));
+  const [isBusy, setIsBusy] = useState(false);
+  const [isDropActive, setIsDropActive] = useState(false);
+
+  useEffect(() => {
+    dragDepthRef.current = 0;
+    setHasImage(Boolean(model.cover_image));
+    setIsBusy(false);
+    setIsDropActive(false);
+  }, [model.cover_image, model.key]);
+
+  const handleFile = async (file: File | undefined) => {
+    if (!file) {
+      return;
+    }
+
+    if (!ACCEPTED_TYPES.has(file.type)) {
+      onError(t('models.useSupportedImage'));
+      return;
+    }
+
+    setIsBusy(true);
+    const modelKey = model.key;
+
+    try {
+      await updateModelImage(modelKey, file);
+      setHasImage(true);
+      // Bumps the cache-bust version so this tile and list thumbnails reload.
+      markCoverImageChanged(modelKey, true);
+      onUpdated();
+    } catch (error) {
+      onError(error instanceof Error ? error.message : t('models.failedToUploadModelImage'));
+    } finally {
+      setIsBusy(false);
+    }
+  };
+
+  const handleDelete = async () => {
+    setIsBusy(true);
+    const modelKey = model.key;
+
+    try {
+      await deleteModelImage(modelKey);
+      setHasImage(false);
+      markCoverImageChanged(modelKey, false);
+      onUpdated();
+    } catch (error) {
+      onError(error instanceof Error ? error.message : t('models.failedToRemoveModelImage'));
+    } finally {
+      setIsBusy(false);
+    }
+  };
+
+  return (
+    <Box
+      aria-busy={isBusy || undefined}
+      aria-label={t('models.uploadCoverImageFor', { name: model.name })}
+      bg="bg.emphasized"
+      borderColor={isDropActive ? 'accent.solid' : 'border.subtle'}
+      borderStyle={hasImage ? 'solid' : 'dashed'}
+      borderWidth={isDropActive ? '2px' : '1px'}
+      boxSize="24"
+      cursor="pointer"
+      flexShrink={0}
+      overflow="hidden"
+      position="relative"
+      role="button"
+      rounded="lg"
+      tabIndex={0}
+      className="group"
+      _focusVisible={{ outline: '2px solid {colors.accent.solid}', outlineOffset: '2px' }}
+      onClick={() => {
+        if (!isBusy) {
+          inputRef.current?.click();
+        }
+      }}
+      onKeyDown={(event) => {
+        if ((event.key === 'Enter' || event.key === ' ') && !isBusy) {
+          event.preventDefault();
+          inputRef.current?.click();
+        }
+      }}
+      onDragEnter={(event) => {
+        if (!dragContainsFiles(event)) {
+          return;
+        }
+
+        event.preventDefault();
+        dragDepthRef.current += 1;
+        setIsDropActive(true);
+      }}
+      onDragLeave={(event) => {
+        if (!dragContainsFiles(event)) {
+          return;
+        }
+
+        dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+
+        if (dragDepthRef.current === 0) {
+          setIsDropActive(false);
+        }
+      }}
+      onDragOver={(event) => {
+        if (dragContainsFiles(event)) {
+          event.preventDefault();
+        }
+      }}
+      onDrop={(event) => {
+        if (!dragContainsFiles(event)) {
+          return;
+        }
+
+        event.preventDefault();
+        dragDepthRef.current = 0;
+        setIsDropActive(false);
+        void handleFile(event.dataTransfer.files[0]);
+      }}
+    >
+      <input
+        ref={inputRef}
+        accept="image/png,image/jpeg,image/webp"
+        hidden
+        type="file"
+        onChange={(event) => {
+          void handleFile(event.currentTarget.files?.[0] ?? undefined);
+          event.currentTarget.value = '';
+        }}
+        onClick={(event) => event.stopPropagation()}
+      />
+      {hasImage ? (
+        <Image
+          alt={t('models.modelCoverAlt', { name: model.name })}
+          boxSize="full"
+          fit="cover"
+          src={getModelImageUrl(model.key, imageVersion ? String(imageVersion) : undefined)}
+          onError={() => setHasImage(false)}
+        />
+      ) : (
+        <Stack align="center" boxSize="full" color="fg.subtle" gap="1" justify="center">
+          <Icon as={ImageIcon} boxSize="5" />
+          <Text fontSize="2xs">{t('models.addImage')}</Text>
+        </Stack>
+      )}
+      {isDropActive ? (
+        <Flex
+          align="center"
+          bg="bg.muted/85"
+          boxSize="full"
+          inset="0"
+          justify="center"
+          pointerEvents="none"
+          position="absolute"
+        >
+          <Icon as={UploadIcon} boxSize="5" color="accent.solid" />
+        </Flex>
+      ) : null}
+      {hasImage && !isDropActive ? (
+        <Box
+          opacity={0}
+          pointerEvents="none"
+          position="absolute"
+          right="1"
+          top="1"
+          transition="opacity var(--wb-motion-duration-fast) ease"
+          _groupFocusWithin={{ opacity: 1, pointerEvents: 'auto' }}
+          _groupHover={{ opacity: 1, pointerEvents: 'auto' }}
+        >
+          <Tooltip content={t('models.removeImage')}>
+            <IconButton
+              aria-label={t('models.removeModelImage')}
+              colorPalette="red"
+              size="2xs"
+              variant="solid"
+              onClick={(event) => {
+                event.stopPropagation();
+                void handleDelete();
+              }}
+            >
+              <Icon as={XIcon} boxSize="3" />
+            </IconButton>
+          </Tooltip>
+        </Box>
+      ) : null}
+    </Box>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/RelatedModelsSection.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/RelatedModelsSection.tsx
new file mode 100644
index 00000000000..4794f74597c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/RelatedModelsSection.tsx
@@ -0,0 +1,176 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelConfig, ModelTaxonomyType } from '@workbench/models/types';
+
+import { Badge, Icon, Spinner, Stack, Text } from '@chakra-ui/react';
+import { IconButton, FieldLabel, Tooltip } from '@workbench/components/ui';
+import { SourceListItem } from '@workbench/launchpad/models/shared/SourceListItem';
+import { addModelRelationship, getRelatedModelKeys, removeModelRelationship } from '@workbench/models/api';
+import { getModelBaseColorPalette, getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { ModelSelect } from '@workbench/models/components';
+import { useModelsSelector } from '@workbench/models/modelsStore';
+import { getModelTypeLabel } from '@workbench/models/taxonomy';
+import { Link2OffIcon } from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/** Types offered when linking related models, grouped in one picker. */
+const LINKABLE_TYPES: ModelTaxonomyType[] = [
+  'main',
+  'lora',
+  'embedding',
+  'vae',
+  'controlnet',
+  't2i_adapter',
+  'ip_adapter',
+];
+
+/**
+ * Bidirectional "related models" links — e.g. attach the LoRAs and VAE that
+ * pair well with a checkpoint so other surfaces can suggest them together.
+ * One grouped, compatibility-filtered picker searches every linkable type at
+ * once; linked models render as rows with an unlink action.
+ */
+export const RelatedModelsSection = ({
+  model,
+  onError,
+}: {
+  model: Pick<ModelConfig, 'base' | 'key'>;
+  onError: (message: string) => void;
+}) => {
+  const { t } = useTranslation();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const [relatedKeys, setRelatedKeys] = useState<string[] | null>(null);
+  const [isMutating, setIsMutating] = useState(false);
+
+  useEffect(() => {
+    let isStale = false;
+
+    getRelatedModelKeys(model.key)
+      .then((keys) => {
+        if (!isStale) {
+          setRelatedKeys(keys);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!isStale) {
+          setRelatedKeys([]);
+          onError(error instanceof Error ? error.message : t('models.failedToLoadRelatedModels'));
+        }
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [model.key, onError, t]);
+
+  const relatedModels = useMemo(() => {
+    const byKey = new Map(models.map((candidate) => [candidate.key, candidate]));
+
+    return (relatedKeys ?? []).map((key) => ({ key, model: byKey.get(key) ?? null }));
+  }, [models, relatedKeys]);
+
+  const excludeKeys = useMemo(() => new Set([model.key, ...(relatedKeys ?? [])]), [model.key, relatedKeys]);
+
+  const handleAdd = async (target: ModelConfig | null) => {
+    if (!target || isMutating) {
+      return;
+    }
+
+    setIsMutating(true);
+
+    try {
+      await addModelRelationship(model.key, target.key);
+      setRelatedKeys((current) => [...(current ?? []), target.key]);
+    } catch (error) {
+      onError(error instanceof Error ? error.message : t('models.failedToLinkModels'));
+    } finally {
+      setIsMutating(false);
+    }
+  };
+
+  const handleRemove = async (key: string) => {
+    setIsMutating(true);
+
+    try {
+      await removeModelRelationship(model.key, key);
+      setRelatedKeys((current) => (current ?? []).filter((existing) => existing !== key));
+    } catch (error) {
+      onError(error instanceof Error ? error.message : t('models.failedToUnlink'));
+    } finally {
+      setIsMutating(false);
+    }
+  };
+
+  return (
+    <Stack gap="2">
+      <Stack gap="0.5">
+        <FieldLabel>{t('models.relatedModels')}</FieldLabel>
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('models.relatedModelsHelp')}
+        </Text>
+      </Stack>
+      <ModelSelect
+        excludeKeys={excludeKeys}
+        filter={(candidate) => candidate.base === model.base || candidate.base === 'any' || model.base === 'any'}
+        modelTypes={LINKABLE_TYPES}
+        placeholder={t('models.searchCompatibleToLink')}
+        showManagerButton={false}
+        size="sm"
+        value={null}
+        onChange={(target) => {
+          void handleAdd(target);
+        }}
+      />
+      {relatedKeys === null ? (
+        <Spinner color="fg.subtle" size="xs" />
+      ) : relatedModels.length === 0 ? (
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('models.noRelatedModels')}
+        </Text>
+      ) : (
+        <Stack gap="1.5">
+          {relatedModels.map(({ key, model: relatedModel }) => (
+            <SourceListItem
+              key={key}
+              badges={
+                relatedModel ? (
+                  <>
+                    <Badge
+                      colorPalette={getModelBaseColorPalette(relatedModel.base)}
+                      flexShrink={0}
+                      fontSize="2xs"
+                      size="sm"
+                      variant="surface"
+                    >
+                      {getModelBaseLabel(relatedModel.base)}
+                    </Badge>
+                    <Badge colorPalette="gray" flexShrink={0} fontSize="2xs" size="sm" variant="outline">
+                      {getModelTypeLabel(relatedModel.type)}
+                    </Badge>
+                  </>
+                ) : undefined
+              }
+              title={relatedModel?.name ?? key}
+              trailing={
+                <Tooltip content={t('models.unlink')}>
+                  <IconButton
+                    aria-label={t('models.unlinkNamed', { name: relatedModel?.name ?? key })}
+                    disabled={isMutating}
+                    size="2xs"
+                    variant="ghost"
+                    onClick={() => {
+                      void handleRemove(key);
+                    }}
+                  >
+                    <Icon as={Link2OffIcon} boxSize="3" />
+                  </IconButton>
+                </Tooltip>
+              }
+            />
+          ))}
+        </Stack>
+      )}
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/TriggerPhrasesEditor.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/TriggerPhrasesEditor.tsx
new file mode 100644
index 00000000000..8f380496f0e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/TriggerPhrasesEditor.tsx
@@ -0,0 +1,147 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { HStack, Icon, Input, Tag, Text, Wrap } from '@chakra-ui/react';
+import { Button, Field } from '@workbench/components/ui';
+import { updateModel } from '@workbench/models/api';
+import { replaceModelInStore } from '@workbench/models/modelsStore';
+import { triggerPhraseSchema } from '@workbench/models/schemas';
+import { PlusIcon } from 'lucide-react';
+import { memo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+interface TriggerPhrasesEditorState {
+  draft: string;
+  error: string | null;
+  isSaving: boolean;
+  modelKey: string;
+}
+
+/**
+ * Tag-style editor for a model's trigger phrases. Each add/remove persists
+ * immediately — there is no separate save step for phrases.
+ */
+export const TriggerPhrasesEditor = ({
+  modelKey,
+  onError,
+  phrases,
+}: {
+  modelKey: string;
+  onError: (message: string) => void;
+  phrases: readonly string[];
+}) => {
+  const { t } = useTranslation();
+  const [editor, setEditor] = useState<TriggerPhrasesEditorState>(() => ({
+    draft: '',
+    error: null,
+    isSaving: false,
+    modelKey,
+  }));
+  const isEditorCurrent = editor.modelKey === modelKey;
+  const draft = isEditorCurrent ? editor.draft : '';
+  const error = isEditorCurrent ? editor.error : null;
+  const isSaving = isEditorCurrent ? editor.isSaving : false;
+
+  const persist = async (nextPhrases: string[]): Promise<boolean> => {
+    setEditor((current) => ({
+      draft: current.modelKey === modelKey ? current.draft : '',
+      error: current.modelKey === modelKey ? current.error : null,
+      isSaving: true,
+      modelKey,
+    }));
+
+    try {
+      replaceModelInStore(await updateModel(modelKey, { trigger_phrases: nextPhrases }));
+
+      return true;
+    } catch (persistError) {
+      onError(persistError instanceof Error ? persistError.message : t('models.failedToUpdateTriggerPhrases'));
+
+      return false;
+    } finally {
+      setEditor((current) => (current.modelKey === modelKey ? { ...current, isSaving: false } : current));
+    }
+  };
+
+  const addPhrase = async () => {
+    const parsed = triggerPhraseSchema.safeParse(draft);
+
+    if (!parsed.success) {
+      setEditor({
+        draft,
+        error: parsed.error.issues[0]?.message ?? t('models.invalidTriggerPhrase'),
+        isSaving,
+        modelKey,
+      });
+      return;
+    }
+
+    if (phrases.some((phrase) => phrase.toLowerCase() === parsed.data.toLowerCase())) {
+      setEditor({ draft, error: t('models.triggerPhraseDuplicate'), isSaving, modelKey });
+      return;
+    }
+
+    setEditor({ draft, error: null, isSaving, modelKey });
+
+    // Clear the draft only once it is saved, so a failure never eats the text.
+    if (await persist([...phrases, parsed.data])) {
+      setEditor((current) => (current.modelKey === modelKey ? { ...current, draft: '' } : current));
+    }
+  };
+
+  return (
+    <Field error={error} helpText={t('models.triggerPhrasesHelp')} label={t('models.triggerPhrases')}>
+      <HStack gap="1.5">
+        <Input
+          aria-invalid={error ? true : undefined}
+          placeholder={t('models.addTriggerPhrase')}
+          size="xs"
+          value={draft}
+          onChange={(event) => {
+            setEditor({ draft: event.currentTarget.value, error: null, isSaving, modelKey });
+          }}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') {
+              event.preventDefault();
+              void addPhrase();
+            }
+          }}
+        />
+        <Button
+          disabled={draft.trim().length === 0}
+          loading={isSaving}
+          size="xs"
+          variant="outline"
+          onClick={() => {
+            void addPhrase();
+          }}
+        >
+          <Icon as={PlusIcon} boxSize="3.5" />
+          {t('common.add')}
+        </Button>
+      </HStack>
+      {phrases.length > 0 ? (
+        <Wrap gap="1">
+          {phrases.map((phrase) => (
+            <Tag.Root key={phrase} size="sm" variant="surface">
+              <Tag.Label>{phrase}</Tag.Label>
+              <Tag.EndElement>
+                <Tag.CloseTrigger
+                  aria-label={t('models.removeTriggerPhrase', { phrase })}
+                  onClick={() => {
+                    void persist(phrases.filter((existing) => existing !== phrase));
+                  }}
+                />
+              </Tag.EndElement>
+            </Tag.Root>
+          ))}
+        </Wrap>
+      ) : (
+        <Text color="fg.subtle" fontSize="2xs">
+          No trigger phrases yet.
+        </Text>
+      )}
+    </Field>
+  );
+};
+
+export const MemoizedTriggerPhrasesEditor = memo(TriggerPhrasesEditor);
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/useModelActions.ts b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/useModelActions.ts
new file mode 100644
index 00000000000..52865ed8460
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/detail/useModelActions.ts
@@ -0,0 +1,58 @@
+import type { ModelConfig } from '@workbench/models/types';
+
+import { convertModelToDiffusers, deleteModel, reidentifyModel } from '@workbench/models/api';
+import { removeModelsFromStore, replaceModelInStore } from '@workbench/models/modelsStore';
+import { pruneModelsUiKeys } from '@workbench/models/uiStore';
+import { useNotify } from '@workbench/useNotify';
+import { useCallback } from 'react';
+
+/**
+ * Lifecycle actions for a single model, shared by the detail page and the
+ * library row context menu so behavior and notifications stay identical.
+ * Confirmation UI is the caller's job; these just act and notify.
+ */
+type ModelActionTarget = Pick<ModelConfig, 'key' | 'name'>;
+
+export const useModelActions = () => {
+  const notify = useNotify();
+
+  const remove = useCallback(
+    async (model: ModelActionTarget) => {
+      try {
+        await deleteModel(model.key);
+        removeModelsFromStore([model.key]);
+        pruneModelsUiKeys([model.key]);
+        notify.success('Model deleted', model.name);
+      } catch (error) {
+        notify.error('Delete failed', error instanceof Error ? error.message : String(error));
+      }
+    },
+    [notify]
+  );
+
+  const convert = useCallback(
+    async (model: ModelActionTarget) => {
+      try {
+        replaceModelInStore(await convertModelToDiffusers(model.key));
+        notify.success('Converted to diffusers', model.name);
+      } catch (error) {
+        notify.error('Conversion failed', error instanceof Error ? error.message : String(error));
+      }
+    },
+    [notify]
+  );
+
+  const reidentify = useCallback(
+    async (model: ModelActionTarget) => {
+      try {
+        replaceModelInStore(await reidentifyModel(model.key));
+        notify.success('Model re-identified', model.name);
+      } catch (error) {
+        notify.error('Re-identify failed', error instanceof Error ? error.message : String(error));
+      }
+    },
+    [notify]
+  );
+
+  return { convert, reidentify, remove };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallJobProgress.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallJobProgress.tsx
new file mode 100644
index 00000000000..b3c63398a27
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallJobProgress.tsx
@@ -0,0 +1,30 @@
+import type { ModelInstallJob } from '@workbench/models/types';
+
+import { Box, Progress, Text } from '@chakra-ui/react';
+import { useInstallProgress } from '@workbench/models/installsStore';
+import { formatBytes } from '@workbench/models/taxonomy';
+import { useTranslation } from 'react-i18next';
+
+export const InstallJobProgress = ({ job }: { job: ModelInstallJob }) => {
+  const { t } = useTranslation();
+  const liveProgress = useInstallProgress(job.id);
+  const bytes = liveProgress?.bytes ?? job.bytes ?? 0;
+  const totalBytes = liveProgress?.totalBytes ?? job.total_bytes ?? 0;
+  const hasTotal = totalBytes > 0;
+  const ratio = hasTotal ? Math.min(1, bytes / totalBytes) : null;
+
+  return (
+    <Box>
+      <Progress.Root aria-label={t('models.downloadProgress')} max={1} size="xs" value={ratio}>
+        <Progress.Track>
+          <Progress.Range />
+        </Progress.Track>
+      </Progress.Root>
+      <Text color="fg.subtle" fontSize="2xs" mt="1">
+        {hasTotal
+          ? `${Math.round((ratio ?? 0) * 100)}% · ${formatBytes(bytes)} / ${formatBytes(totalBytes)}`
+          : t('models.waitingForDownload')}
+      </Text>
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallJobRow.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallJobRow.tsx
new file mode 100644
index 00000000000..5c80c980857
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallJobRow.tsx
@@ -0,0 +1,198 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelInstallJob } from '@workbench/models/types';
+
+import { Badge, HStack, Icon, Stack, Text } from '@chakra-ui/react';
+import { useConnectionStatusSelector } from '@workbench/backend/connectionStore';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import {
+  cancelModelInstall,
+  pauseModelInstall,
+  restartFailedModelInstall,
+  restartModelInstallFile,
+  resumeModelInstall,
+} from '@workbench/models/api';
+import { isActiveInstallStatus, refreshInstalls, replaceInstallJob } from '@workbench/models/installsStore';
+import { getInstallSourceLabel } from '@workbench/models/taxonomy';
+import { PauseIcon, PlayIcon, RotateCcwIcon, TriangleAlertIcon, XIcon } from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { InstallJobProgress } from './InstallJobProgress';
+import { STATUS_BADGES, getInstallJobDisplayName } from './queueUtils';
+
+const partFileName = (part: { url?: string; source?: string; local_path?: string }): string =>
+  (part.url ?? part.source ?? part.local_path ?? 'file').split(/[\\/]/).at(-1) ?? 'file';
+
+export const InstallJobRow = ({
+  job,
+  onError,
+}: {
+  job: ModelInstallJob;
+  onError: (title: string, message: string) => void;
+}) => {
+  const { t } = useTranslation();
+  const [isActing, setIsActing] = useState(false);
+  const connectionStatus = useConnectionStatusSelector((snapshot) => snapshot.status);
+  const badge = STATUS_BADGES[job.status] ?? { label: job.status, palette: 'gray' };
+  const sourceLabel = getInstallSourceLabel(job.source);
+  const displayName = getInstallJobDisplayName(job);
+  // Parts the backend could not resume (or that errored) need a manual restart.
+  const problemParts = (job.download_parts ?? []).filter(
+    (part) => part.resume_required === true || part.status === 'error'
+  );
+  const showDisconnected = connectionStatus !== 'connected' && isActiveInstallStatus(job.status);
+
+  const runAction = async (action: () => Promise<unknown>, failureTitle: string) => {
+    setIsActing(true);
+
+    try {
+      const result = await action();
+
+      if (result && typeof result === 'object' && 'id' in (result as ModelInstallJob)) {
+        replaceInstallJob(result as ModelInstallJob);
+      } else {
+        await refreshInstalls();
+      }
+    } catch (actionError) {
+      onError(failureTitle, actionError instanceof Error ? actionError.message : String(actionError));
+    } finally {
+      setIsActing(false);
+    }
+  };
+
+  return (
+    <Stack
+      bg="bg"
+      borderColor={job.status === 'error' ? 'border.error' : 'border.subtle'}
+      borderWidth="1px"
+      gap="1.5"
+      p="2"
+      rounded="md"
+    >
+      <HStack gap="2" justify="space-between">
+        <Text flex="1" fontSize="2xs" fontWeight="600" minW="0" truncate title={sourceLabel}>
+          {displayName}
+        </Text>
+        {showDisconnected ? (
+          <Tooltip content={t('models.backendDisconnectedProgressStale')}>
+            <Icon as={TriangleAlertIcon} boxSize="3" color="fg.warning" flexShrink={0} />
+          </Tooltip>
+        ) : null}
+        <Badge colorPalette={badge.palette} flexShrink={0} fontSize="2xs" size="sm" variant="surface">
+          {badge.label}
+        </Badge>
+        <HStack flexShrink={0} gap="0.5">
+          {job.status === 'downloading' ? (
+            <Tooltip content={t('models.pauseDownload')}>
+              <IconButton
+                aria-label={t('models.pauseInstall')}
+                disabled={isActing}
+                size="2xs"
+                variant="ghost"
+                onClick={() => void runAction(() => pauseModelInstall(job.id), t('models.pauseFailed'))}
+              >
+                <Icon as={PauseIcon} boxSize="3" />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+          {job.status === 'paused' ? (
+            <Tooltip content={t('models.resumeDownload')}>
+              <IconButton
+                aria-label={t('models.resumeInstall')}
+                disabled={isActing}
+                size="2xs"
+                variant="ghost"
+                onClick={() => void runAction(() => resumeModelInstall(job.id), t('models.resumeFailed'))}
+              >
+                <Icon as={PlayIcon} boxSize="3" />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+          {job.status === 'error' ? (
+            <Tooltip content={t('models.retryFailedDownload')}>
+              <IconButton
+                aria-label={t('models.retryInstall')}
+                disabled={isActing}
+                size="2xs"
+                variant="ghost"
+                onClick={() => void runAction(() => restartFailedModelInstall(job.id), t('models.retryFailed'))}
+              >
+                <Icon as={RotateCcwIcon} boxSize="3" />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+          {isActiveInstallStatus(job.status) || job.status === 'paused' ? (
+            <Tooltip content={t('models.cancelInstall')}>
+              <IconButton
+                aria-label={t('models.cancelInstall')}
+                disabled={isActing}
+                size="2xs"
+                variant="ghost"
+                onClick={() => void runAction(() => cancelModelInstall(job.id), t('models.cancelFailed'))}
+              >
+                <Icon as={XIcon} boxSize="3" />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+        </HStack>
+      </HStack>
+      {displayName !== sourceLabel ? (
+        <Text color="fg.subtle" fontSize="2xs" truncate>
+          {sourceLabel}
+        </Text>
+      ) : null}
+      {job.status === 'downloading' || job.status === 'waiting' ? <InstallJobProgress job={job} /> : null}
+      {job.status === 'error' && job.error ? (
+        <Text color="fg.error" fontSize="2xs" overflowWrap="anywhere">
+          {job.error_reason ? `${job.error_reason}: ` : ''}
+          {job.error}
+        </Text>
+      ) : null}
+      {problemParts.map((part) => {
+        const isResume = part.resume_required === true;
+        const partUrl = typeof part.url === 'string' ? part.url : undefined;
+
+        return (
+          <Stack key={part.url ?? part.source ?? partFileName(part)} bg="bg.muted" gap="0.5" p="1.5" rounded="sm">
+            <HStack gap="1.5">
+              <Icon as={TriangleAlertIcon} boxSize="3" color={isResume ? 'fg.warning' : 'fg.error'} flexShrink={0} />
+              <Text flex="1" fontSize="2xs" minW="0" title={partFileName(part)} truncate>
+                {partFileName(part)}
+              </Text>
+              <Badge
+                colorPalette={isResume ? 'orange' : 'red'}
+                flexShrink={0}
+                fontSize="2xs"
+                size="sm"
+                variant="surface"
+              >
+                {isResume ? t('models.resumeRequired') : t('common.failed')}
+              </Badge>
+              {partUrl ? (
+                <Tooltip content={t('models.restartThisFile')}>
+                  <IconButton
+                    aria-label={t('models.restartFile')}
+                    disabled={isActing}
+                    size="2xs"
+                    variant="ghost"
+                    onClick={() =>
+                      void runAction(() => restartModelInstallFile(job.id, partUrl), t('models.restartFileFailed'))
+                    }
+                  >
+                    <Icon as={RotateCcwIcon} boxSize="3" />
+                  </IconButton>
+                </Tooltip>
+              ) : null}
+            </HStack>
+            {part.resume_message ? (
+              <Text color="fg.subtle" fontSize="2xs" overflowWrap="anywhere">
+                {part.resume_message}
+              </Text>
+            ) : null}
+          </Stack>
+        );
+      })}
+    </Stack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallQueueBar.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallQueueBar.tsx
new file mode 100644
index 00000000000..5300a565535
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallQueueBar.tsx
@@ -0,0 +1,220 @@
+import type { ModelInstallJob } from '@workbench/models/types';
+
+import { Badge, Box, Collapsible, Flex, HStack, Icon, Spinner, Text } from '@chakra-ui/react';
+import { Button, IconButton, Tooltip } from '@workbench/components/ui';
+import {
+  cancelModelInstall,
+  pauseModelInstall,
+  pruneCompletedModelInstalls,
+  resumeModelInstall,
+} from '@workbench/models/api';
+import {
+  ensureInstallsLoaded,
+  isActiveInstallStatus,
+  refreshInstalls,
+  useInstallsSelector,
+} from '@workbench/models/installsStore';
+import { setQueueExpanded, useModelsUiSelector } from '@workbench/models/uiStore';
+import { useNotify } from '@workbench/useNotify';
+import { ChevronUpIcon, ListOrderedIcon, PauseIcon, PlayIcon, RefreshCcwIcon, Trash2Icon, XIcon } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { InstallQueueList } from './InstallQueueList';
+import { getInstallJobDisplayName } from './queueUtils';
+
+const TRIGGER_HOVER = { color: 'fg' } as const;
+const INDICATOR_OPEN = { transform: 'rotate(180deg)' } as const;
+
+/** Persistent, collapsible install queue footer for the model manager detail pane. */
+export const InstallQueueBar = () => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const error = useInstallsSelector((snapshot) => snapshot.error);
+  const jobs = useInstallsSelector((snapshot) => snapshot.jobs);
+  const status = useInstallsSelector((snapshot) => snapshot.status);
+  const queueExpanded = useModelsUiSelector((snapshot) => snapshot.queueExpanded);
+
+  useEffect(() => {
+    ensureInstallsLoaded();
+  }, []);
+
+  const activeJobs = useMemo(() => jobs.filter((job) => isActiveInstallStatus(job.status)), [jobs]);
+  const pausedJobs = useMemo(() => jobs.filter((job) => job.status === 'paused'), [jobs]);
+  const pausableJobs = useMemo(() => jobs.filter((job) => job.status === 'downloading'), [jobs]);
+  const cancellableJobs = useMemo(
+    () => jobs.filter((job) => isActiveInstallStatus(job.status) || job.status === 'paused'),
+    [jobs]
+  );
+  const settledCount = jobs.filter((job) => !isActiveInstallStatus(job.status) && job.status !== 'paused').length;
+
+  const [busyAction, setBusyAction] = useState<'pause' | 'resume' | 'cancel' | 'prune' | 'refresh' | null>(null);
+
+  const runBulk = useCallback(
+    async (action: 'pause' | 'resume' | 'cancel', targets: ModelInstallJob[]) => {
+      const call =
+        action === 'pause' ? pauseModelInstall : action === 'resume' ? resumeModelInstall : cancelModelInstall;
+
+      setBusyAction(action);
+
+      try {
+        await Promise.all(targets.map((job) => call(job.id)));
+        await refreshInstalls();
+      } catch (bulkError) {
+        notify.error(t('models.queueActionFailed'), bulkError instanceof Error ? bulkError.message : String(bulkError));
+        void refreshInstalls();
+      } finally {
+        setBusyAction(null);
+      }
+    },
+    [notify, t]
+  );
+
+  const handlePrune = useCallback(async () => {
+    setBusyAction('prune');
+
+    try {
+      await pruneCompletedModelInstalls();
+      await refreshInstalls();
+    } catch (pruneError) {
+      notify.error(t('models.pruneFailed'), pruneError instanceof Error ? pruneError.message : String(pruneError));
+    } finally {
+      setBusyAction(null);
+    }
+  }, [notify, t]);
+
+  const handleRefresh = useCallback(async () => {
+    setBusyAction('refresh');
+
+    try {
+      await refreshInstalls();
+    } finally {
+      setBusyAction(null);
+    }
+  }, []);
+  const handleOpenChange = useCallback((event: { open: boolean }) => setQueueExpanded(event.open), []);
+  const handlePauseAll = useCallback(() => void runBulk('pause', pausableJobs), [pausableJobs, runBulk]);
+  const handleResumeAll = useCallback(() => void runBulk('resume', pausedJobs), [pausedJobs, runBulk]);
+  const handleCancelAll = useCallback(() => void runBulk('cancel', cancellableJobs), [cancellableJobs, runBulk]);
+
+  const summary =
+    activeJobs.length > 0
+      ? `${getInstallJobDisplayName(activeJobs[0]!)}${activeJobs.length > 1 ? t('models.plusMore', { count: activeJobs.length - 1 }) : ''}`
+      : jobs.length > 0
+        ? t('models.installJobSummary', { count: jobs.length })
+        : t('models.noInstallsYet');
+
+  return (
+    <Collapsible.Root
+      bg="bg.subtle"
+      borderTopWidth={1}
+      flexShrink={0}
+      open={queueExpanded}
+      overflow="hidden"
+      onOpenChange={handleOpenChange}
+    >
+      <Collapsible.Content>
+        <Flex direction="column" h="min(22rem, 45dvh)" minH="0" overflow="hidden">
+          <HStack borderBottomWidth={1} gap="2" justify="space-between" px="3" py="1.5">
+            <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+              {t('models.installQueue')}
+            </Text>
+            <HStack gap="1">
+              <Button loading={busyAction === 'refresh'} size="2xs" variant="ghost" onClick={handleRefresh}>
+                <Icon as={RefreshCcwIcon} boxSize="3" />
+                {t('common.refresh')}
+              </Button>
+              <Button
+                disabled={settledCount === 0}
+                loading={busyAction === 'prune'}
+                size="2xs"
+                variant="ghost"
+                onClick={handlePrune}
+              >
+                <Icon as={Trash2Icon} boxSize="3" />
+                {t('models.clearFinished')}
+              </Button>
+            </HStack>
+          </HStack>
+          <Box flex="1" minH="0" overflow="hidden" p="2">
+            <InstallQueueList error={error} jobs={jobs} status={status} />
+          </Box>
+        </Flex>
+      </Collapsible.Content>
+
+      <HStack gap="1" px="3" py="2">
+        <Collapsible.Trigger
+          alignItems="center"
+          bg="transparent"
+          color="inherit"
+          display="flex"
+          flex="1"
+          gap="2"
+          minW="0"
+          textAlign="start"
+          _hover={TRIGGER_HOVER}
+        >
+          {activeJobs.length > 0 ? (
+            <Spinner borderWidth="1.5px" boxSize="3.5" color="accent.solid" flexShrink={0} />
+          ) : (
+            <Icon as={ListOrderedIcon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+          )}
+          <Text flex="1" fontSize="xs" fontWeight="600" minW="0" truncate>
+            {summary}
+          </Text>
+
+          {activeJobs.length > 0 ? (
+            <Badge colorPalette="accent" flexShrink={0} fontSize="2xs" size="sm" variant="solid">
+              {activeJobs.length}
+            </Badge>
+          ) : null}
+          <Collapsible.Indicator _open={INDICATOR_OPEN} transition="transform var(--wb-motion-duration-slow)">
+            <Icon as={ChevronUpIcon} boxSize="4" color="fg.subtle" flexShrink={0} />
+          </Collapsible.Indicator>
+        </Collapsible.Trigger>
+
+        <HStack flexShrink={0} gap="0.5">
+          {pausableJobs.length > 0 ? (
+            <Tooltip content={t('models.pauseAllDownloads')}>
+              <IconButton
+                aria-label={t('models.pauseAllInstalls')}
+                loading={busyAction === 'pause'}
+                size="2xs"
+                variant="ghost"
+                onClick={handlePauseAll}
+              >
+                <Icon as={PauseIcon} boxSize="3.5" />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+          {pausedJobs.length > 0 ? (
+            <Tooltip content={t('models.resumeAllPausedDownloads')}>
+              <IconButton
+                aria-label={t('models.resumeAllInstalls')}
+                loading={busyAction === 'resume'}
+                size="2xs"
+                variant="ghost"
+                onClick={handleResumeAll}
+              >
+                <Icon as={PlayIcon} boxSize="3.5" />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+          {cancellableJobs.length > 0 ? (
+            <Tooltip content={t('models.cancelAllInstalls')}>
+              <IconButton
+                aria-label={t('models.cancelAllInstalls')}
+                loading={busyAction === 'cancel'}
+                size="2xs"
+                variant="ghost"
+                onClick={handleCancelAll}
+              >
+                <Icon as={XIcon} boxSize="3.5" />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+        </HStack>
+      </HStack>
+    </Collapsible.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallQueueList.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallQueueList.tsx
new file mode 100644
index 00000000000..b82b2b76b17
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/InstallQueueList.tsx
@@ -0,0 +1,71 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelInstallJob } from '@workbench/models/types';
+
+import { Flex, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button, Scrollable } from '@workbench/components/ui';
+import { refreshInstalls } from '@workbench/models/installsStore';
+import { useNotify } from '@workbench/useNotify';
+import { useTranslation } from 'react-i18next';
+
+import { InstallJobRow } from './InstallJobRow';
+
+export const InstallQueueList = ({
+  error,
+  jobs,
+  status,
+}: {
+  error: string | null;
+  jobs: ModelInstallJob[];
+  status: 'idle' | 'loading' | 'loaded' | 'error';
+}) => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+
+  if (status === 'loading' || status === 'idle') {
+    return (
+      <Flex align="center" justify="center" py="6">
+        <Spinner color="fg.subtle" size="sm" />
+      </Flex>
+    );
+  }
+
+  if (status === 'error') {
+    return (
+      <Stack align="center" gap="1" py="6">
+        <Text color="fg.error" fontSize="xs" fontWeight="600">
+          {t('models.couldNotLoadInstallQueue')}
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          {error}
+        </Text>
+        <Button mt="1" size="xs" variant="outline" onClick={() => void refreshInstalls()}>
+          {t('common.retry')}
+        </Button>
+      </Stack>
+    );
+  }
+
+  if (jobs.length === 0) {
+    return (
+      <Stack align="center" gap="1" py="6">
+        <Text color="fg.muted" fontSize="xs" fontWeight="600">
+          {t('models.noInstallsYet')}
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('models.noInstallsDescription')}
+        </Text>
+      </Stack>
+    );
+  }
+
+  return (
+    <Scrollable h="full" label={t('models.installJobs')} minH="0">
+      <Stack gap="1.5">
+        {jobs.map((job) => (
+          <InstallJobRow key={job.id} job={job} onError={notify.error} />
+        ))}
+      </Stack>
+    </Scrollable>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/queueUtils.ts b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/queueUtils.ts
new file mode 100644
index 00000000000..652c00ad079
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/install-queue/queueUtils.ts
@@ -0,0 +1,17 @@
+import type { ModelInstallJob, ModelInstallStatus } from '@workbench/models/types';
+
+import { getInstallSourceLabel } from '@workbench/models/taxonomy';
+
+export const STATUS_BADGES: Record<ModelInstallStatus, { label: string; palette: string }> = {
+  cancelled: { label: 'Cancelled', palette: 'gray' },
+  completed: { label: 'Installed', palette: 'green' },
+  downloading: { label: 'Downloading', palette: 'blue' },
+  downloads_done: { label: 'Downloaded', palette: 'blue' },
+  error: { label: 'Failed', palette: 'red' },
+  paused: { label: 'Paused', palette: 'orange' },
+  running: { label: 'Installing', palette: 'blue' },
+  waiting: { label: 'Waiting', palette: 'gray' },
+};
+
+export const getInstallJobDisplayName = (job: ModelInstallJob): string =>
+  job.config_out?.name ?? getInstallSourceLabel(job.source);
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/library/MaintenanceMenu.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/MaintenanceMenu.tsx
new file mode 100644
index 00000000000..05269aefe11
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/MaintenanceMenu.tsx
@@ -0,0 +1,253 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { OrphanedModelInfo } from '@workbench/models/types';
+
+import { Checkbox, Dialog, Flex, Icon, Menu, Portal, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button, CloseButton, IconButton, MenuContent, Panel } from '@workbench/components/ui';
+import { deleteOrphanedModels, emptyModelCache, getOrphanedModels } from '@workbench/models/api';
+import { refreshModels } from '@workbench/models/modelsStore';
+import { formatBytes } from '@workbench/models/taxonomy';
+import { useNotify } from '@workbench/useNotify';
+import { BrushCleaningIcon, FolderSearchIcon, MoreHorizontalIcon, RefreshCcwIcon } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Library maintenance: refresh, clean up orphaned model folders (files on disk
+ * with no database record), and empty the in-memory model cache.
+ */
+export const MaintenanceMenu = () => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const [isSyncDialogOpen, setIsSyncDialogOpen] = useState(false);
+
+  const handleEmptyCache = async () => {
+    try {
+      await emptyModelCache();
+      notify.success(t('models.cacheEmptied'));
+    } catch (error) {
+      notify.error(t('models.failedToEmptyCache'), error instanceof Error ? error.message : String(error));
+    }
+  };
+
+  return (
+    <>
+      <Menu.Root positioning={{ placement: 'bottom-end' }}>
+        <Menu.Trigger asChild>
+          <IconButton aria-label={t('models.libraryMaintenance')} size="2xs" variant="ghost">
+            <Icon as={MoreHorizontalIcon} boxSize="4" />
+          </IconButton>
+        </Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent minW="14rem">
+              <Menu.Item value="refresh" onClick={() => void refreshModels()}>
+                <Icon as={RefreshCcwIcon} boxSize="3.5" />
+                <Menu.ItemText fontSize="xs">{t('models.refreshList')}</Menu.ItemText>
+              </Menu.Item>
+              <Menu.Item value="sync" onClick={() => setIsSyncDialogOpen(true)}>
+                <Icon as={FolderSearchIcon} boxSize="3.5" />
+                <Menu.ItemText fontSize="xs">{t('models.cleanupOrphaned')}</Menu.ItemText>
+              </Menu.Item>
+              <Menu.Item value="empty-cache" onClick={() => void handleEmptyCache()}>
+                <Icon as={BrushCleaningIcon} boxSize="3.5" />
+                <Menu.ItemText fontSize="xs">{t('models.emptyCache')}</Menu.ItemText>
+              </Menu.Item>
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      {isSyncDialogOpen ? <OrphanedModelsDialog onClose={() => setIsSyncDialogOpen(false)} /> : null}
+    </>
+  );
+};
+
+const OrphanedModelsDialog = ({ onClose }: { onClose: () => void }) => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const [orphans, setOrphans] = useState<OrphanedModelInfo[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  // Nothing pre-selected: deleting files on disk must be an explicit choice.
+  const [selectedPaths, setSelectedPaths] = useState<ReadonlySet<string>>(new Set());
+  const [isDeleting, setIsDeleting] = useState(false);
+
+  useEffect(() => {
+    let isStale = false;
+
+    getOrphanedModels()
+      .then((result) => {
+        if (!isStale) {
+          setOrphans(result);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!isStale) {
+          setLoadError(error instanceof Error ? error.message : t('models.failedToScanOrphaned'));
+        }
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [t]);
+
+  const togglePath = (path: string) => {
+    setSelectedPaths((current) => {
+      const next = new Set(current);
+
+      if (next.has(path)) {
+        next.delete(path);
+      } else {
+        next.add(path);
+      }
+
+      return next;
+    });
+  };
+
+  const handleDelete = async () => {
+    setIsDeleting(true);
+
+    try {
+      const result = await deleteOrphanedModels([...selectedPaths]);
+      const errorCount = Object.keys(result.errors).length;
+
+      if (errorCount > 0) {
+        notify.error(
+          t('models.orphanedCleanup'),
+          t('models.orphanedCleanupPartialDescription', {
+            deleted: result.deleted.length,
+            error: Object.values(result.errors)[0],
+            failed: errorCount,
+          })
+        );
+      } else {
+        notify.success(
+          t('models.orphanedCleanup'),
+          t('models.orphanedDeletedDescription', { count: result.deleted.length })
+        );
+      }
+
+      void refreshModels();
+      onClose();
+    } catch (error) {
+      notify.error(t('models.orphanedCleanupFailed'), error instanceof Error ? error.message : String(error));
+    } finally {
+      setIsDeleting(false);
+    }
+  };
+
+  const totalSelectedBytes =
+    orphans?.filter((orphan) => selectedPaths.has(orphan.path)).reduce((sum, orphan) => sum + orphan.size_bytes, 0) ??
+    0;
+
+  return (
+    <Dialog.Root
+      open
+      placement="center"
+      scrollBehavior="inside"
+      size="md"
+      onOpenChange={(event) => {
+        if (!event.open) {
+          onClose();
+        }
+      }}
+    >
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Header borderBottomWidth="1px" borderColor="border.subtle">
+              <Stack gap="0.5">
+                <Dialog.Title fontSize="sm" fontWeight="700">
+                  {t('models.orphanedTitle')}
+                </Dialog.Title>
+                <Text color="fg.subtle" fontSize="2xs">
+                  {t('models.orphanedDescription')}
+                </Text>
+              </Stack>
+            </Dialog.Header>
+            <Dialog.Body>
+              {loadError ? (
+                <Text color="fg.error" fontSize="xs" py="4">
+                  {loadError}
+                </Text>
+              ) : orphans === null ? (
+                <Flex align="center" justify="center" py="8">
+                  <Spinner color="fg.subtle" size="sm" />
+                </Flex>
+              ) : orphans.length === 0 ? (
+                <Text color="fg.muted" fontSize="xs" py="4" textAlign="center">
+                  {t('models.noOrphaned')}
+                </Text>
+              ) : (
+                <Stack gap="1.5" py="2">
+                  <Checkbox.Root
+                    checked={
+                      selectedPaths.size === 0 ? false : selectedPaths.size === orphans.length ? true : 'indeterminate'
+                    }
+                    colorPalette="accent"
+                    ps="2"
+                    size="sm"
+                    onCheckedChange={() => {
+                      setSelectedPaths(
+                        selectedPaths.size === orphans.length
+                          ? new Set()
+                          : new Set(orphans.map((orphan) => orphan.path))
+                      );
+                    }}
+                  >
+                    <Checkbox.HiddenInput />
+                    <Checkbox.Control />
+                    <Checkbox.Label color="fg.muted" fontSize="2xs">
+                      {t('models.selectAllCount', { count: orphans.length })}
+                    </Checkbox.Label>
+                  </Checkbox.Root>
+                  {orphans.map((orphan) => (
+                    <Panel key={orphan.path} alignItems="center" flexDirection="row" gap="2" p="2" tone="control">
+                      <Checkbox.Root
+                        checked={selectedPaths.has(orphan.path)}
+                        colorPalette="accent"
+                        size="sm"
+                        onCheckedChange={() => togglePath(orphan.path)}
+                      >
+                        <Checkbox.HiddenInput />
+                        <Checkbox.Control />
+                      </Checkbox.Root>
+                      <Stack flex="1" gap="0" minW="0">
+                        <Text fontSize="2xs" fontWeight="600" overflowWrap="anywhere">
+                          {orphan.path}
+                        </Text>
+                        <Text color="fg.subtle" fontSize="2xs">
+                          {t('models.fileCount', { count: orphan.files.length })} · {formatBytes(orphan.size_bytes)}
+                        </Text>
+                      </Stack>
+                    </Panel>
+                  ))}
+                </Stack>
+              )}
+            </Dialog.Body>
+            <Dialog.Footer gap="2">
+              <Button disabled={isDeleting} size="xs" variant="ghost" onClick={onClose}>
+                {t('common.close')}
+              </Button>
+              <Button
+                colorPalette="red"
+                disabled={selectedPaths.size === 0 || !orphans || orphans.length === 0}
+                loading={isDeleting}
+                size="xs"
+                variant="solid"
+                onClick={() => void handleDelete()}
+              >
+                {t('models.deleteSelectedWithBytes', { bytes: formatBytes(totalSelectedBytes) })}
+              </Button>
+            </Dialog.Footer>
+            <Dialog.CloseTrigger asChild>
+              <CloseButton color="fg.muted" size="sm" />
+            </Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelFilterBar.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelFilterBar.tsx
new file mode 100644
index 00000000000..61927e724d8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelFilterBar.tsx
@@ -0,0 +1,102 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelLibraryFilters, ModelSortField } from '@workbench/models/library';
+import type { ModelTaxonomyType } from '@workbench/models/types';
+
+import { HStack, Icon, Input, InputGroup } from '@chakra-ui/react';
+import { FilterMenuItem, ModelFilterMenu } from '@workbench/launchpad/models/shared/ModelFilterMenu';
+import { SearchIcon } from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const SORT_FIELDS: { field: ModelSortField; labelKey: string }[] = [
+  { field: 'default', labelKey: 'models.sort.default' },
+  { field: 'name', labelKey: 'models.sort.name' },
+  { field: 'base', labelKey: 'models.sort.base' },
+  { field: 'size', labelKey: 'models.sort.size' },
+  { field: 'format', labelKey: 'models.sort.format' },
+];
+
+const isFiltering = (filters: ModelLibraryFilters): boolean =>
+  filters.typeFilter !== null || filters.baseFilter !== null || filters.missingOnly;
+
+/**
+ * Search box plus a combined filter/sort menu. The menu reflects only values
+ * present in the current library so it never offers dead filters.
+ */
+export const ModelFilterBar = ({
+  availableBases,
+  availableTypes,
+  filters,
+  missingCount,
+  onChange,
+}: {
+  availableBases: string[];
+  availableTypes: ModelTaxonomyType[];
+  filters: ModelLibraryFilters;
+  missingCount: number;
+  onChange: (filters: ModelLibraryFilters) => void;
+}) => {
+  const { t } = useTranslation();
+  const handleSearchChange = useCallback(
+    (searchTerm: string) => onChange({ ...filters, searchTerm }),
+    [filters, onChange]
+  );
+  const handleMissingFilterToggle = useCallback(
+    () => onChange({ ...filters, missingOnly: !filters.missingOnly, typeFilter: null }),
+    [filters, onChange]
+  );
+  const handleBaseFilterChange = useCallback(
+    (baseFilter: string | null) => onChange({ ...filters, baseFilter }),
+    [filters, onChange]
+  );
+  const handleSortChange = useCallback(
+    (sortField: ModelSortField, sortDirection: 'asc' | 'desc') => onChange({ ...filters, sortDirection, sortField }),
+    [filters, onChange]
+  );
+  const handleTypeFilterChange = useCallback(
+    (typeFilter: ModelTaxonomyType | null) => onChange({ ...filters, missingOnly: false, typeFilter }),
+    [filters, onChange]
+  );
+  const extraTypeItems = useMemo(
+    () =>
+      missingCount > 0 ? (
+        <FilterMenuItem
+          isChecked={filters.missingOnly}
+          label={t('models.missingFilesCount', { count: missingCount })}
+          value="type-missing"
+          onSelect={handleMissingFilterToggle}
+        />
+      ) : null,
+    [filters.missingOnly, handleMissingFilterToggle, missingCount, t]
+  );
+  return (
+    <HStack gap="1.5" w="full" px="3" pt="3">
+      <InputGroup startElement={<Icon as={SearchIcon} boxSize="3.5" color="fg.subtle" />}>
+        <Input
+          aria-label={t('models.searchModels')}
+          placeholder={t('models.searchModelsPlaceholder')}
+          size="xs"
+          value={filters.searchTerm}
+          onChange={(event) => handleSearchChange(event.currentTarget.value)}
+        />
+      </InputGroup>
+      <ModelFilterMenu
+        ariaLabel={t('models.filterAndSort')}
+        availableBases={availableBases}
+        availableTypes={availableTypes}
+        baseFilter={filters.baseFilter}
+        extraTypeItems={extraTypeItems}
+        isActive={isFiltering(filters)}
+        sortDirection={filters.sortDirection}
+        sortField={filters.sortField}
+        sortFields={SORT_FIELDS}
+        typeAllChecked={filters.typeFilter === null && !filters.missingOnly}
+        typeFilter={filters.typeFilter}
+        onBaseFilterChange={handleBaseFilterChange}
+        onSortChange={handleSortChange}
+        onTypeFilterChange={handleTypeFilterChange}
+      />
+    </HStack>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelLibraryList.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelLibraryList.tsx
new file mode 100644
index 00000000000..f639f7ecb0f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelLibraryList.tsx
@@ -0,0 +1,379 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Box, Checkbox, Flex, HStack, Icon, Image, ScrollArea, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button, Row } from '@workbench/components/ui';
+import { EmptyState } from '@workbench/components/ui/EmptyState';
+import { MissingFileBadge, ModelBaseBadge, ModelFormatBadge } from '@workbench/launchpad/models/detail/ModelBadges';
+import { getModelImageUrl } from '@workbench/models/api';
+import {
+  filterModels,
+  flattenGroupsToRows,
+  groupModelsByType,
+  type ModelLibraryFilters,
+} from '@workbench/models/library';
+import { useModelsSelector } from '@workbench/models/modelsStore';
+import { formatBytes } from '@workbench/models/taxonomy';
+import { getLibraryScrollOffset, openModelManagerTab, saveLibraryScrollOffset } from '@workbench/models/uiStore';
+import { ArrowRightIcon, BoxIcon, CircleAlert } from 'lucide-react';
+import { memo, useCallback, useDeferredValue, useEffect, useMemo, useRef, useState } from 'react';
+import { useVirtualizer } from 'react-hook-tanstack-virtual';
+import { useTranslation } from 'react-i18next';
+
+import { ModelRowContextMenu, type ModelContextMenuTarget } from './ModelRowContextMenu';
+
+const HEADER_ROW_HEIGHT_PX = 30;
+const MODEL_ROW_HEIGHT_PX = 56;
+
+/**
+ * Virtualized, grouped model library. Group headers and model rows share one
+ * flat virtualized list (smooth at thousands of models). The current group's
+ * header is rendered as a pinned overlay above the scroll viewport — CSS
+ * sticky positioning is unreliable inside ScrollArea's content wrapper — and
+ * the virtual content lives in ScrollArea.Content so the scrollbar thumb is
+ * measured correctly. Rows carry a thumbnail, a right-click action menu, and —
+ * when `onToggleSelected` is provided — bulk-select checkboxes.
+ */
+export const ModelLibraryList = ({
+  activeModelKey,
+  filters,
+  instanceId,
+  onActivate,
+  onToggleSelected,
+  selectedKeys,
+}: {
+  activeModelKey: string | null;
+  filters: ModelLibraryFilters;
+  /** Identifies this list's scroll-offset slot ('panel', 'manager', ...). */
+  instanceId: string;
+  onActivate: (modelKey: string) => void;
+  /** Present in the manager library: enables bulk-select checkboxes. */
+  onToggleSelected?: (modelKey: string) => void;
+  selectedKeys?: ReadonlySet<string>;
+}) => {
+  const { t } = useTranslation();
+  const { coverImageVersions, error, missingModelKeys, models, status } = useModelsSelector(
+    (snapshot) => ({
+      coverImageVersions: snapshot.coverImageVersions,
+      error: snapshot.error,
+      missingModelKeys: snapshot.missingModelKeys,
+      models: snapshot.models,
+      status: snapshot.status,
+    }),
+    (left, right) =>
+      left.coverImageVersions === right.coverImageVersions &&
+      left.error === right.error &&
+      left.missingModelKeys === right.missingModelKeys &&
+      left.models === right.models &&
+      left.status === right.status
+  );
+  const deferredFilters = useDeferredValue(filters);
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const [contextMenuTarget, setContextMenuTarget] = useState<ModelContextMenuTarget | null>(null);
+  const openAddModels = () => {
+    openModelManagerTab('add');
+  };
+  const handleContextMenu = useCallback(
+    (modelKey: string, x: number, y: number) => setContextMenuTarget({ modelKey, x, y }),
+    []
+  );
+
+  const rows = useMemo(
+    () => flattenGroupsToRows(groupModelsByType(filterModels(models, deferredFilters, missingModelKeys))),
+    [deferredFilters, missingModelKeys, models]
+  );
+
+  const headerIndexes = useMemo(() => rows.flatMap((row, index) => (row.kind === 'header' ? [index] : [])), [rows]);
+
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    estimateSize: (index) => (rows[index]?.kind === 'header' ? HEADER_ROW_HEIGHT_PX : MODEL_ROW_HEIGHT_PX),
+    getItemKey: (index) => {
+      const row = rows[index];
+
+      return row?.kind === 'model' ? row.model.key : `header:${row?.group.type ?? index}`;
+    },
+    getScrollElement: () => scrollRef.current,
+    initialOffset: () => getLibraryScrollOffset(instanceId),
+    overscan: 8,
+  });
+  const scrollOffsetRef = useRef(virtualizer.scrollOffset ?? 0);
+
+  useEffect(() => {
+    scrollOffsetRef.current = virtualizer.scrollOffset ?? scrollOffsetRef.current;
+  }, [virtualizer.scrollOffset]);
+
+  // Persist the offset so switching tabs/regions and coming back lands here.
+  useEffect(
+    () => () => {
+      saveLibraryScrollOffset(instanceId, scrollOffsetRef.current);
+    },
+    [instanceId]
+  );
+
+  if (status === 'loading' || status === 'idle') {
+    return (
+      <Flex align="center" h="full" justify="center" py="8">
+        <Spinner color="fg.subtle" size="sm" />
+      </Flex>
+    );
+  }
+
+  if (status === 'error') {
+    return <EmptyState title={t('models.couldNotLoad')} description={error} icon={<Icon as={CircleAlert} />} danger />;
+  }
+
+  if (rows.length === 0) {
+    return (
+      <EmptyState
+        title={models.length === 0 ? t('models.noneInstalled') : t('models.noneMatchFilters')}
+        description={
+          models.length === 0 ? t('models.noneInstalledDescription') : t('models.noneMatchFiltersDescription')
+        }
+        icon={<Icon as={CircleAlert} />}
+      >
+        <Button onClick={openAddModels} size="sm">
+          {t('models.addModels')}
+          <Icon as={ArrowRightIcon} />
+        </Button>
+      </EmptyState>
+    );
+  }
+
+  const firstVisibleIndex = virtualizer.virtualItems[0]?.index ?? 0;
+  const pinnedHeaderIndex = headerIndexes.reduce<number | null>(
+    (pinnedIndex, index) => (firstVisibleIndex >= index ? index : pinnedIndex),
+    headerIndexes[0] ?? null
+  );
+  const pinnedRow = pinnedHeaderIndex === null ? null : rows[pinnedHeaderIndex];
+
+  return (
+    <Box flex="1" minH="0" position="relative" w="full">
+      <ScrollArea.Root h="full" size="xs" variant="hover" w="full">
+        <ScrollArea.Viewport ref={scrollRef} aria-label={t('models.library')} h="full" w="full">
+          <ScrollArea.Content w="full">
+            <Box h={`${virtualizer.totalSize}px`} position="relative" w="full">
+              {virtualizer.virtualItems.map((virtualRow) => {
+                const row = rows[virtualRow.index];
+
+                if (!row) {
+                  return null;
+                }
+
+                return row.kind === 'header' ? (
+                  <VirtualHeaderRow
+                    key={virtualRow.key}
+                    count={row.group.models.length}
+                    label={row.group.label}
+                    virtualStart={virtualRow.start}
+                  />
+                ) : (
+                  <VirtualModelRow
+                    key={virtualRow.key}
+                    base={row.model.base}
+                    coverImage={row.model.cover_image}
+                    fileSize={row.model.file_size}
+                    format={row.model.format}
+                    imageVersion={coverImageVersions[row.model.key]}
+                    isActive={row.model.key === activeModelKey}
+                    isMissing={missingModelKeys.has(row.model.key)}
+                    isSelected={selectedKeys?.has(row.model.key) ?? false}
+                    modelKey={row.model.key}
+                    name={row.model.name}
+                    virtualStart={virtualRow.start}
+                    onActivate={onActivate}
+                    onContextMenu={handleContextMenu}
+                    onToggleSelected={onToggleSelected}
+                  />
+                );
+              })}
+            </Box>
+          </ScrollArea.Content>
+        </ScrollArea.Viewport>
+        <ScrollArea.Scrollbar>
+          <ScrollArea.Thumb />
+        </ScrollArea.Scrollbar>
+      </ScrollArea.Root>
+      {/* Pinned copy of the current group's header, above the viewport.
+          aria-hidden: it duplicates a header already in the list. */}
+      {pinnedRow?.kind === 'header' ? (
+        <Box aria-hidden bg="bg" left="0" pointerEvents="none" position="absolute" right="0" top="0" zIndex={1} px="3">
+          <GroupHeader count={pinnedRow.group.models.length} label={pinnedRow.group.label} />
+        </Box>
+      ) : null}
+      <ModelRowContextMenu target={contextMenuTarget} onClose={() => setContextMenuTarget(null)} />
+    </Box>
+  );
+};
+
+const GroupHeader = ({ count, label }: { count: number; label: string }) => (
+  <HStack bg="bg.inset" gap="1.5" h={`${HEADER_ROW_HEIGHT_PX}px`} pt="2" w="full">
+    <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+      {label}
+    </Text>
+    <Text color="fg.subtle" fontSize="2xs">
+      {count}
+    </Text>
+  </HStack>
+);
+
+interface VirtualHeaderRowProps {
+  count: number;
+  label: string;
+  virtualStart: number;
+}
+
+const VirtualHeaderRow = memo(function VirtualHeaderRow({ count, label, virtualStart }: VirtualHeaderRowProps) {
+  return (
+    <Box left="0" position="absolute" top="0" transform={`translateY(${virtualStart}px)`} w="full" px="3">
+      <GroupHeader count={count} label={label} />
+    </Box>
+  );
+});
+
+interface ModelRowProps {
+  base: Parameters<typeof ModelBaseBadge>[0]['base'];
+  coverImage?: string | null;
+  fileSize: number;
+  format: Parameters<typeof ModelFormatBadge>[0]['format'];
+  imageVersion?: number;
+  isActive: boolean;
+  isMissing: boolean;
+  isSelected: boolean;
+  modelKey: string;
+  name: string;
+  onActivate: (modelKey: string) => void;
+  onContextMenu: (modelKey: string, x: number, y: number) => void;
+  onToggleSelected?: (modelKey: string) => void;
+}
+
+interface VirtualModelRowProps extends ModelRowProps {
+  virtualStart: number;
+}
+
+const VirtualModelRow = memo(function VirtualModelRow({ virtualStart, ...rowProps }: VirtualModelRowProps) {
+  return (
+    <Box left="0" position="absolute" top="0" transform={`translateY(${virtualStart}px)`} w="full" px="3">
+      <ModelRow {...rowProps} />
+    </Box>
+  );
+});
+
+const ModelRow = memo(function ModelRow({
+  base,
+  coverImage,
+  fileSize,
+  format,
+  imageVersion,
+  isActive,
+  isMissing,
+  isSelected,
+  modelKey,
+  name,
+  onActivate,
+  onContextMenu,
+  onToggleSelected,
+}: ModelRowProps) {
+  return (
+    <Row
+      active={isActive ? 'accent' : isSelected ? 'muted' : 'none'}
+      aria-current={isActive || undefined}
+      h={`${MODEL_ROW_HEIGHT_PX - 4}px`}
+      mb="1"
+      minW="0"
+      px="2"
+      role="button"
+      rounded="md"
+      tabIndex={0}
+      _focusVisible={{ boxShadow: 'inset 0 0 0 2px {colors.accent.solid}', outline: 'none' }}
+      onClick={() => onActivate(modelKey)}
+      onContextMenu={(event) => {
+        event.preventDefault();
+        onContextMenu(modelKey, event.clientX, event.clientY);
+      }}
+      onKeyDown={(event) => {
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.preventDefault();
+          onActivate(modelKey);
+        }
+      }}
+    >
+      {onToggleSelected ? (
+        <Checkbox.Root
+          aria-label={`Select ${name}`}
+          checked={isSelected}
+          colorPalette="accent"
+          size="xs"
+          onCheckedChange={() => onToggleSelected(modelKey)}
+          onClick={(event) => event.stopPropagation()}
+        >
+          <Checkbox.HiddenInput />
+          <Checkbox.Control />
+        </Checkbox.Root>
+      ) : null}
+      {/* Keyed by version so a stale load error clears when the image changes. */}
+      <ModelRowThumbnail
+        key={`${modelKey}:${imageVersion ?? 0}`}
+        coverImage={coverImage}
+        imageVersion={imageVersion}
+        modelKey={modelKey}
+      />
+      <Stack flex="1" gap="0.5" minW="0">
+        <Text fontSize="xs" fontWeight="600" truncate>
+          {name}
+        </Text>
+        <HStack gap="1" minW="0" wrap="wrap">
+          <ModelBaseBadge base={base} />
+          <ModelFormatBadge format={format} />
+          {isMissing ? <MissingFileBadge /> : null}
+        </HStack>
+      </Stack>
+      <Text color={isActive ? 'accent.solid' : 'fg.subtle'} flexShrink={0} fontSize="2xs">
+        {formatBytes(fileSize)}
+      </Text>
+    </Row>
+  );
+});
+
+const ModelRowThumbnail = ({
+  coverImage,
+  imageVersion,
+  modelKey,
+}: {
+  coverImage?: string | null;
+  imageVersion?: number;
+  modelKey: string;
+}) => {
+  // The cover_image marker can be stale; fall back to the icon on load error.
+  const [hasImageError, setHasImageError] = useState(false);
+
+  if (!coverImage || hasImageError) {
+    return (
+      <Flex
+        align="center"
+        bg="bg.emphasized"
+        borderColor="border.subtle"
+        borderWidth="1px"
+        boxSize="9"
+        color="fg.subtle"
+        flexShrink={0}
+        justify="center"
+        rounded="md"
+      >
+        <Icon as={BoxIcon} boxSize="4" />
+      </Flex>
+    );
+  }
+
+  return (
+    <Image
+      alt=""
+      boxSize="9"
+      fit="cover"
+      flexShrink={0}
+      loading="lazy"
+      rounded="md"
+      src={getModelImageUrl(modelKey, imageVersion ? String(imageVersion) : undefined)}
+      onError={() => setHasImageError(true)}
+    />
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelRowContextMenu.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelRowContextMenu.tsx
new file mode 100644
index 00000000000..d559d832dd1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/library/ModelRowContextMenu.tsx
@@ -0,0 +1,101 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelConfig } from '@workbench/models/types';
+
+import { Icon, Menu, Portal } from '@chakra-ui/react';
+import { ConfirmDialog, MenuContent } from '@workbench/components/ui';
+import { useModelActions } from '@workbench/launchpad/models/detail/useModelActions';
+import { isConvertibleToDiffusers } from '@workbench/models/baseIdentity';
+import { useModelsSelector } from '@workbench/models/modelsStore';
+import { RefreshCcwIcon, Trash2Icon } from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { SiHuggingface } from 'react-icons/si';
+
+export interface ModelContextMenuTarget {
+  modelKey: string;
+  x: number;
+  y: number;
+}
+
+/**
+ * Right-click menu for library rows, anchored to the cursor via a virtual
+ * rect. Mirrors the detail page's action menu (re-identify, convert, delete)
+ * through the shared `useModelActions` hook.
+ */
+export const ModelRowContextMenu = ({
+  onClose,
+  target,
+}: {
+  onClose: () => void;
+  target: ModelContextMenuTarget | null;
+}) => {
+  const { t } = useTranslation();
+  const { convert, reidentify, remove } = useModelActions();
+  const [pendingConfirm, setPendingConfirm] = useState<{ kind: 'delete' | 'convert'; model: ModelConfig } | null>(null);
+  const model = useModelsSelector((snapshot) =>
+    target ? (snapshot.models.find((candidate) => candidate.key === target.modelKey) ?? null) : null
+  );
+
+  return (
+    <>
+      <Menu.Root
+        key={target ? target.modelKey : 'closed'}
+        lazyMount
+        open={target !== null}
+        positioning={{
+          getAnchorRect: () => (target ? { height: 1, width: 1, x: target.x, y: target.y } : null),
+          placement: 'bottom-start',
+        }}
+        unmountOnExit
+        onOpenChange={(event) => {
+          if (!event.open) {
+            onClose();
+          }
+        }}
+      >
+        <Portal>
+          <Menu.Positioner>
+            {model ? (
+              <MenuContent minW="13rem">
+                <Menu.Item value="reidentify" onClick={() => void reidentify(model)}>
+                  <Icon as={RefreshCcwIcon} boxSize="3.5" />
+                  <Menu.ItemText fontSize="xs">{t('models.reidentify')}</Menu.ItemText>
+                </Menu.Item>
+                {isConvertibleToDiffusers(model) ? (
+                  <Menu.Item value="convert" onClick={() => setPendingConfirm({ kind: 'convert', model })}>
+                    <Icon as={SiHuggingface} boxSize="3.5" />
+                    <Menu.ItemText fontSize="xs">{t('models.convertToDiffusers')}</Menu.ItemText>
+                  </Menu.Item>
+                ) : null}
+                <Menu.Separator />
+                <Menu.Item color="fg.error" value="delete" onClick={() => setPendingConfirm({ kind: 'delete', model })}>
+                  <Icon as={Trash2Icon} boxSize="3.5" />
+                  <Menu.ItemText fontSize="xs">{t('models.deleteModel')}</Menu.ItemText>
+                </Menu.Item>
+              </MenuContent>
+            ) : null}
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <ConfirmDialog
+        body={
+          pendingConfirm?.kind === 'convert'
+            ? t('models.convertBody', { name: pendingConfirm.model.name })
+            : t('models.deleteBody', { name: pendingConfirm?.model.name ?? '' })
+        }
+        confirmLabel={pendingConfirm?.kind === 'convert' ? t('models.convert') : t('models.deleteModel')}
+        isOpen={pendingConfirm !== null}
+        title={pendingConfirm?.kind === 'convert' ? t('models.convertToDiffusers') : t('models.deleteModel')}
+        onClose={() => setPendingConfirm(null)}
+        onConfirm={async () => {
+          if (!pendingConfirm) {
+            return;
+          }
+
+          await (pendingConfirm.kind === 'convert' ? convert(pendingConfirm.model) : remove(pendingConfirm.model));
+        }}
+      />
+    </>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/DetailPane.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/DetailPane.tsx
new file mode 100644
index 00000000000..f6e56c08d44
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/DetailPane.tsx
@@ -0,0 +1,94 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Box, Flex, Icon, Text } from '@chakra-ui/react';
+import { Scrollable, Tabs } from '@workbench/components/ui';
+import { AddModelsView } from '@workbench/launchpad/models/add-models/AddModelsView';
+import { ApiKeysSection } from '@workbench/launchpad/models/credentials/ApiKeysSection';
+import { ModelDetail } from '@workbench/launchpad/models/detail/ModelDetail';
+import { InstallQueueBar } from '@workbench/launchpad/models/install-queue/InstallQueueBar';
+import { useModelsSelector } from '@workbench/models/modelsStore';
+import { updateModelsUi, useModelsUiSelector, type ModelManagerTab } from '@workbench/models/uiStore';
+import { BoxIcon, KeyRoundIcon, PlusIcon } from 'lucide-react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { HEADER_MIN_HEIGHT } from './layoutConstants';
+
+/** The tabbed detail pane: selected model, Add Models, API Keys, and queue footer. */
+export const DetailPane = () => {
+  const { t } = useTranslation();
+  const { activeModelKey, activeTab } = useModelsUiSelector(
+    (snapshot) => ({ activeModelKey: snapshot.activeModelKey, activeTab: snapshot.activeTab }),
+    (left, right) => left.activeModelKey === right.activeModelKey && left.activeTab === right.activeTab
+  );
+  const detailLabel = useModelsSelector(
+    (snapshot) => snapshot.models.find((model) => model.key === activeModelKey)?.name ?? t('models.details')
+  );
+
+  return (
+    <Flex direction="column" flex="1" minH="0" minW="0">
+      <Flex align="flex-end" borderBottomWidth={1} flexShrink={0} minH={HEADER_MIN_HEIGHT} px="2">
+        <Tabs.Root
+          size="sm"
+          mb="-1px"
+          value={activeTab}
+          onValueChange={(event) => updateModelsUi({ activeTab: event.value as ModelManagerTab })}
+        >
+          <Tabs.List h="full">
+            <Tabs.Trigger fontSize="xs" value="details">
+              <Icon as={BoxIcon} boxSize="3" />
+              <Text maxW="14rem" truncate>
+                {detailLabel}
+              </Text>
+            </Tabs.Trigger>
+            <Tabs.Trigger fontSize="xs" value="add">
+              <Icon as={PlusIcon} boxSize="3" />
+              {t('models.addModels')}
+            </Tabs.Trigger>
+            <Tabs.Trigger fontSize="xs" value="keys">
+              <Icon as={KeyRoundIcon} boxSize="3" />
+              {t('models.apiKeys')}
+            </Tabs.Trigger>
+          </Tabs.List>
+        </Tabs.Root>
+      </Flex>
+
+      <Box flex="1" minH="0">
+        {activeTab === 'details' ? <DetailTab modelKey={activeModelKey} /> : null}
+        {activeTab === 'add' ? <AddModelsView /> : null}
+        {activeTab === 'keys' ? (
+          <Scrollable h="full" label={t('models.apiKeys')} minH="0" p="3">
+            <ApiKeysSection />
+          </Scrollable>
+        ) : null}
+      </Box>
+
+      <InstallQueueBar />
+    </Flex>
+  );
+};
+
+const DetailTab = ({ modelKey }: { modelKey: string | null }) => {
+  const { t } = useTranslation();
+  const handleDeleted = useCallback(() => updateModelsUi({ activeModelKey: null }), []);
+
+  if (modelKey === null) {
+    return (
+      <Flex align="center" direction="column" gap="2" h="full" justify="center" p="6">
+        <Icon as={BoxIcon} boxSize="8" color="fg.subtle" />
+        <Text color="fg.muted" fontSize="sm" fontWeight="600">
+          {t('models.selectModel')}
+        </Text>
+        <Text color="fg.subtle" fontSize="xs" maxW="22rem" textAlign="center">
+          {t('models.selectModelDescription')}
+        </Text>
+      </Flex>
+    );
+  }
+
+  return (
+    <Scrollable h="full" label={t('models.details')} minH="0" p="3">
+      <ModelDetail key={modelKey} density="full" modelKey={modelKey} onDeleted={handleDeleted} />
+    </Scrollable>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/LibraryColumn.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/LibraryColumn.tsx
new file mode 100644
index 00000000000..fd9f3763651
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/LibraryColumn.tsx
@@ -0,0 +1,162 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Box, Flex, HStack, Icon, Separator, Text } from '@chakra-ui/react';
+import { Button, IconButton, ConfirmDialog } from '@workbench/components/ui';
+import { MaintenanceMenu } from '@workbench/launchpad/models/library/MaintenanceMenu';
+import { ModelFilterBar } from '@workbench/launchpad/models/library/ModelFilterBar';
+import { ModelLibraryList } from '@workbench/launchpad/models/library/ModelLibraryList';
+import { bulkDeleteModels } from '@workbench/models/api';
+import { collectBases, collectTypes } from '@workbench/models/library';
+import { refreshModels, removeModelsFromStore, useModelsSelector } from '@workbench/models/modelsStore';
+import {
+  openModelDetail,
+  pruneModelsUiKeys,
+  toggleModelSelection,
+  updateModelsUi,
+  useModelsUiSelector,
+} from '@workbench/models/uiStore';
+import { useNotify } from '@workbench/useNotify';
+import { Trash2Icon, XIcon } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { HEADER_MIN_HEIGHT, LIBRARY_WIDTH } from './layoutConstants';
+
+/** The persistent master list: header, search/filter bar, and bulk actions. */
+export const LibraryColumn = () => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const missingCount = useModelsSelector((snapshot) => snapshot.missingModelKeys.size);
+  const { activeModelKey, filters, selectedKeys } = useModelsUiSelector(
+    (snapshot) => ({
+      activeModelKey: snapshot.activeModelKey,
+      filters: snapshot.filters,
+      selectedKeys: snapshot.selectedKeys,
+    }),
+    (left, right) =>
+      left.activeModelKey === right.activeModelKey &&
+      left.filters === right.filters &&
+      left.selectedKeys === right.selectedKeys
+  );
+  const [isBulkDeleteOpen, setIsBulkDeleteOpen] = useState(false);
+
+  const availableTypes = useMemo(() => collectTypes(models), [models]);
+  const availableBases = useMemo(() => collectBases(models), [models]);
+  const handleActivate = useCallback((modelKey: string) => openModelDetail(modelKey), []);
+  const handleToggleSelected = useCallback((modelKey: string) => toggleModelSelection(modelKey), []);
+
+  const handleBulkDelete = async () => {
+    const keys = [...selectedKeys];
+
+    try {
+      const result = await bulkDeleteModels(keys);
+
+      removeModelsFromStore(result.deleted);
+      pruneModelsUiKeys(result.deleted);
+      updateModelsUi({ selectedKeys: new Set(result.failed.map((failure) => failure.key)) });
+
+      if (result.failed.length > 0) {
+        notify.error(
+          t('models.someCouldNotBeDeleted'),
+          t('models.bulkDeletePartialDescription', {
+            deleted: result.deleted.length,
+            error: result.failed[0]?.error ?? '',
+            failed: result.failed.length,
+          })
+        );
+      } else {
+        notify.success(t('models.deleted'), t('models.deletedDescription', { count: result.deleted.length }));
+      }
+    } catch (error) {
+      notify.error(t('models.bulkDeleteFailed'), error instanceof Error ? error.message : String(error));
+      void refreshModels();
+    }
+  };
+
+  return (
+    <Flex direction="column" flexShrink={0} h="full" minH="0" position="relative" w={LIBRARY_WIDTH} borderEndWidth={1}>
+      <HStack align="center" borderBottomWidth={1} flexShrink={0} gap="2" minH={HEADER_MIN_HEIGHT} px="3">
+        <Text fontSize="sm" fontWeight="700">
+          {t('models.title')}
+        </Text>
+        <Text color="fg.subtle" fontSize="xs">
+          {models.length}
+        </Text>
+        <Box ms="auto">
+          <MaintenanceMenu />
+        </Box>
+      </HStack>
+
+      <ModelFilterBar
+        availableBases={availableBases}
+        availableTypes={availableTypes}
+        filters={filters}
+        missingCount={missingCount}
+        onChange={(nextFilters) => updateModelsUi({ filters: nextFilters })}
+      />
+
+      <ModelLibraryList
+        activeModelKey={activeModelKey}
+        filters={filters}
+        instanceId="manager"
+        selectedKeys={selectedKeys}
+        onActivate={handleActivate}
+        onToggleSelected={handleToggleSelected}
+      />
+
+      {selectedKeys.size > 0 ? (
+        <HStack
+          bg="bg.muted"
+          borderColor="border.emphasized"
+          borderWidth="1px"
+          bottom="2"
+          gap="2"
+          insetX="2"
+          p="1.5"
+          position="absolute"
+          rounded="lg"
+          shadow="lg"
+          zIndex={2}
+        >
+          <Text
+            borderColor="border.subtle"
+            borderStyle="dashed"
+            borderWidth="1px"
+            color="fg.muted"
+            fontSize="2xs"
+            fontWeight="600"
+            px="2"
+            py="1"
+            rounded="md"
+          >
+            {t('models.selectedCount', { count: selectedKeys.size })}
+          </Text>
+          <Separator borderColor="border.subtle" h="5" orientation="vertical" />
+          <Button colorPalette="red" size="2xs" variant="solid" onClick={() => setIsBulkDeleteOpen(true)}>
+            <Icon as={Trash2Icon} boxSize="3" />
+            {t('common.delete')}
+          </Button>
+          <Box flex="1" />
+          <IconButton
+            aria-label={t('models.clearSelection')}
+            size="2xs"
+            variant="ghost"
+            onClick={() => updateModelsUi({ selectedKeys: new Set() })}
+          >
+            <Icon as={XIcon} boxSize="3" />
+          </IconButton>
+        </HStack>
+      ) : null}
+
+      <ConfirmDialog
+        body={t('models.bulkDeleteBody', { count: selectedKeys.size })}
+        confirmLabel={t('models.bulkDeleteConfirm', { count: selectedKeys.size })}
+        isOpen={isBulkDeleteOpen}
+        title={t('models.deleteSelectedTitle')}
+        onClose={() => setIsBulkDeleteOpen(false)}
+        onConfirm={handleBulkDelete}
+      />
+    </Flex>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/layoutConstants.ts b/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/layoutConstants.ts
new file mode 100644
index 00000000000..d749adfda43
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/manager/layoutConstants.ts
@@ -0,0 +1,5 @@
+export const LIBRARY_WIDTH = '22rem';
+
+// Both column headers share a min height so the library title bar lines up with
+// the detail tab bar.
+export const HEADER_MIN_HEIGHT = '2.75rem';
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/ModelFilterMenu.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/ModelFilterMenu.tsx
new file mode 100644
index 00000000000..0ba6de199c9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/ModelFilterMenu.tsx
@@ -0,0 +1,256 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ModelSortField } from '@workbench/models/library';
+import type { ModelTaxonomyType } from '@workbench/models/types';
+import type { ReactNode } from 'react';
+
+import { Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { IconButton, MenuContent } from '@workbench/components/ui';
+import { getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { getModelTypeLabel } from '@workbench/models/taxonomy';
+import { CheckIcon, SlidersHorizontalIcon } from 'lucide-react';
+import { memo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export interface ModelFilterSortOption {
+  field: ModelSortField;
+  labelKey: string;
+}
+
+const DEFAULT_SORT_FIELDS: ModelFilterSortOption[] = [
+  { field: 'default', labelKey: 'models.sortDefault' },
+  { field: 'name', labelKey: 'models.sortName' },
+  { field: 'base', labelKey: 'models.sortBase' },
+  { field: 'size', labelKey: 'models.sortSize' },
+  { field: 'format', labelKey: 'models.sortFormat' },
+];
+
+/** Shared taxonomy filter + sort menu for installed and starter model lists. */
+export const ModelFilterMenu = ({
+  ariaLabel,
+  availableBases,
+  availableTypes,
+  baseFilter,
+  extraTypeItems,
+  isActive,
+  onBaseFilterChange,
+  onSortChange,
+  onTypeFilterChange,
+  sortDirection,
+  sortField,
+  sortFields = DEFAULT_SORT_FIELDS,
+  typeAllChecked,
+  typeAllLabel,
+  typeFilter,
+}: {
+  ariaLabel: string;
+  availableBases: string[];
+  availableTypes: ModelTaxonomyType[];
+  baseFilter: string | null;
+  extraTypeItems?: ReactNode;
+  isActive: boolean;
+  onBaseFilterChange: (base: string | null) => void;
+  onSortChange: (field: ModelSortField, direction: 'asc' | 'desc') => void;
+  onTypeFilterChange: (type: ModelTaxonomyType | null) => void;
+  sortDirection: 'asc' | 'desc';
+  sortField: ModelSortField;
+  sortFields?: readonly ModelFilterSortOption[];
+  typeAllChecked?: boolean;
+  typeAllLabel?: string;
+  typeFilter: ModelTaxonomyType | null;
+}) => {
+  const { t } = useTranslation();
+  const resolvedTypeAllLabel = typeAllLabel ?? t('models.allModels');
+
+  return (
+    <Menu.Root closeOnSelect={false} positioning={{ placement: 'bottom-end' }}>
+      <Menu.Trigger asChild>
+        <IconButton aria-label={ariaLabel} color={isActive ? 'accent.solid' : 'fg.muted'} size="xs" variant="outline">
+          <Icon as={SlidersHorizontalIcon} boxSize="4" />
+        </IconButton>
+      </Menu.Trigger>
+      <Portal>
+        <Menu.Positioner>
+          <MenuContent maxH="70vh" minW="13rem" overflowY="auto" py="1">
+            <Menu.ItemGroup>
+              <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                {t('models.modelType')}
+              </Menu.ItemGroupLabel>
+              <AllTypesFilterMenuItem
+                isChecked={typeAllChecked ?? typeFilter === null}
+                label={resolvedTypeAllLabel}
+                onTypeFilterChange={onTypeFilterChange}
+              />
+              {extraTypeItems}
+              {availableTypes.map((type) => (
+                <TypeFilterMenuItem
+                  key={type}
+                  type={type}
+                  typeFilter={typeFilter}
+                  onTypeFilterChange={onTypeFilterChange}
+                />
+              ))}
+            </Menu.ItemGroup>
+            <Menu.Separator />
+            <Menu.ItemGroup>
+              <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                {t('models.baseArchitecture')}
+              </Menu.ItemGroupLabel>
+              <AllBasesFilterMenuItem isChecked={baseFilter === null} onBaseFilterChange={onBaseFilterChange} />
+              {availableBases.map((base) => (
+                <BaseFilterMenuItem
+                  key={base}
+                  base={base}
+                  baseFilter={baseFilter}
+                  onBaseFilterChange={onBaseFilterChange}
+                />
+              ))}
+            </Menu.ItemGroup>
+            <Menu.Separator />
+            <Menu.ItemGroup>
+              <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                {t('models.sortBy')}
+              </Menu.ItemGroupLabel>
+              {sortFields.map(({ field, labelKey }) => (
+                <SortFilterMenuItem
+                  key={field}
+                  field={field}
+                  labelKey={labelKey}
+                  sortDirection={sortDirection}
+                  sortField={sortField}
+                  onSortChange={onSortChange}
+                />
+              ))}
+            </Menu.ItemGroup>
+          </MenuContent>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
+
+/** Checkmark-style menu item shared by the model filter menus. */
+interface FilterMenuItemProps {
+  isChecked: boolean;
+  label: string;
+  onSelect: () => void;
+  trailing?: string;
+  value: string;
+}
+
+export const FilterMenuItem = memo(function FilterMenuItem({
+  isChecked,
+  label,
+  onSelect,
+  trailing,
+  value,
+}: FilterMenuItemProps) {
+  return (
+    <Menu.Item aria-checked={isChecked} closeOnSelect={false} role="menuitemcheckbox" value={value} onClick={onSelect}>
+      <Icon as={CheckIcon} boxSize="3" opacity={isChecked ? 1 : 0} />
+      <Menu.ItemText fontSize="xs">{label}</Menu.ItemText>
+      {trailing ? (
+        <Text color="fg.subtle" fontSize="2xs" ms="auto">
+          {trailing}
+        </Text>
+      ) : null}
+    </Menu.Item>
+  );
+});
+
+const AllTypesFilterMenuItem = memo(function AllTypesFilterMenuItem({
+  isChecked,
+  label,
+  onTypeFilterChange,
+}: {
+  isChecked: boolean;
+  label: string;
+  onTypeFilterChange: (type: ModelTaxonomyType | null) => void;
+}) {
+  return (
+    <FilterMenuItem isChecked={isChecked} label={label} value="type-all" onSelect={() => onTypeFilterChange(null)} />
+  );
+});
+
+const TypeFilterMenuItem = memo(function TypeFilterMenuItem({
+  type,
+  typeFilter,
+  onTypeFilterChange,
+}: {
+  type: ModelTaxonomyType;
+  typeFilter: ModelTaxonomyType | null;
+  onTypeFilterChange: (type: ModelTaxonomyType | null) => void;
+}) {
+  return (
+    <FilterMenuItem
+      isChecked={typeFilter === type}
+      label={getModelTypeLabel(type)}
+      value={`type-${type}`}
+      onSelect={() => onTypeFilterChange(typeFilter === type ? null : type)}
+    />
+  );
+});
+
+const AllBasesFilterMenuItem = memo(function AllBasesFilterMenuItem({
+  isChecked,
+  onBaseFilterChange,
+}: {
+  isChecked: boolean;
+  onBaseFilterChange: (base: string | null) => void;
+}) {
+  const { t } = useTranslation();
+
+  return (
+    <FilterMenuItem
+      isChecked={isChecked}
+      label={t('models.allBases')}
+      value="base-all"
+      onSelect={() => onBaseFilterChange(null)}
+    />
+  );
+});
+
+const BaseFilterMenuItem = memo(function BaseFilterMenuItem({
+  base,
+  baseFilter,
+  onBaseFilterChange,
+}: {
+  base: string;
+  baseFilter: string | null;
+  onBaseFilterChange: (base: string | null) => void;
+}) {
+  return (
+    <FilterMenuItem
+      isChecked={baseFilter === base}
+      label={getModelBaseLabel(base)}
+      value={`base-${base}`}
+      onSelect={() => onBaseFilterChange(baseFilter === base ? null : base)}
+    />
+  );
+});
+
+const SortFilterMenuItem = memo(function SortFilterMenuItem({
+  field,
+  labelKey,
+  sortDirection,
+  sortField,
+  onSortChange,
+}: {
+  field: ModelSortField;
+  labelKey: string;
+  sortDirection: 'asc' | 'desc';
+  sortField: ModelSortField;
+  onSortChange: (field: ModelSortField, direction: 'asc' | 'desc') => void;
+}) {
+  const { t } = useTranslation();
+
+  return (
+    <FilterMenuItem
+      isChecked={sortField === field}
+      label={t(labelKey)}
+      value={`sort-${field}`}
+      onSelect={() => onSortChange(field, sortField === field ? (sortDirection === 'asc' ? 'desc' : 'asc') : 'asc')}
+      trailing={sortField === field ? (sortDirection === 'asc' ? t('common.asc') : t('common.desc')) : undefined}
+    />
+  );
+});
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/ResultsListHeader.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/ResultsListHeader.tsx
new file mode 100644
index 00000000000..70533a75678
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/ResultsListHeader.tsx
@@ -0,0 +1,74 @@
+import { HStack, Icon, Input, InputGroup, Stack, Text } from '@chakra-ui/react';
+import { Button, IconButton } from '@workbench/components/ui';
+import { DownloadIcon, SearchIcon, XIcon } from 'lucide-react';
+import { useCallback, type ChangeEvent, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const SEARCH_ICON = <Icon as={SearchIcon} boxSize="3" color="fg.subtle" />;
+
+/**
+ * Shared header for an installable-source results panel (HuggingFace files,
+ * folder-scan results): a summary line with an optional extra control and a
+ * dismiss, over a filter box and an Install All action. Presentational only —
+ * each consumer owns its own filter state, Install All predicate, and rows.
+ */
+export const ResultsListHeader = ({
+  extra,
+  installAllDisabled,
+  installAllLabel,
+  onClear,
+  onInstallAll,
+  onSearchChange,
+  searchPlaceholder,
+  searchValue,
+  summary,
+}: {
+  extra?: ReactNode;
+  installAllDisabled: boolean;
+  installAllLabel?: string;
+  onClear: () => void;
+  onInstallAll: () => void;
+  onSearchChange: (value: string) => void;
+  searchPlaceholder?: string;
+  searchValue: string;
+  summary: ReactNode;
+}) => {
+  const { t } = useTranslation();
+  const resolvedInstallAllLabel = installAllLabel ?? t('models.installAll');
+  const resolvedSearchPlaceholder = searchPlaceholder ?? t('models.filterResults');
+  const handleSearchChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => onSearchChange(event.currentTarget.value),
+    [onSearchChange]
+  );
+
+  return (
+    <Stack gap="1.5">
+      <HStack gap="2" justify="space-between" wrap="wrap">
+        <Text color="fg.muted" fontSize="2xs">
+          {summary}
+        </Text>
+        <HStack gap="3">
+          {extra}
+          <IconButton aria-label={t('models.dismissResults')} size="2xs" variant="ghost" onClick={onClear}>
+            <Icon as={XIcon} boxSize="3" />
+          </IconButton>
+        </HStack>
+      </HStack>
+      <HStack gap="2">
+        <InputGroup flex="1" startElement={SEARCH_ICON}>
+          <Input
+            aria-label={resolvedSearchPlaceholder}
+            placeholder={resolvedSearchPlaceholder}
+            size="xs"
+            value={searchValue}
+            onChange={handleSearchChange}
+          />
+        </InputGroup>
+        <Button disabled={installAllDisabled} flexShrink={0} size="xs" variant="outline" onClick={onInstallAll}>
+          <Icon as={DownloadIcon} boxSize="3" />
+          {resolvedInstallAllLabel}
+        </Button>
+      </HStack>
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/SourceListItem.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/SourceListItem.tsx
new file mode 100644
index 00000000000..93b04aa6b5e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/models/shared/SourceListItem.tsx
@@ -0,0 +1,111 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { ReactNode } from 'react';
+
+import { Badge, HStack, Icon, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button, Panel } from '@workbench/components/ui';
+import { useActiveInstallSources } from '@workbench/models/installsStore';
+import { openInstallQueue } from '@workbench/models/uiStore';
+import { DownloadIcon } from 'lucide-react';
+
+/**
+ * The shared row used by every installable-source list (starter models,
+ * HuggingFace files, folder-scan results, related models): title + badges on
+ * top, optional description below, action on the right.
+ */
+export const SourceListItem = ({
+  badges,
+  description,
+  title,
+  titleTooltip,
+  trailing,
+}: {
+  badges?: ReactNode;
+  description?: ReactNode;
+  title: string;
+  titleTooltip?: string;
+  trailing?: ReactNode;
+}) => (
+  <Panel alignItems="center" flexDirection="row" gap="3" p="2.5">
+    <Stack flex="1" gap="0.5" minW="0">
+      <HStack gap="1.5" minW="0">
+        <Text fontSize="xs" fontWeight="600" title={titleTooltip} truncate>
+          {title}
+        </Text>
+        {badges}
+      </HStack>
+      {description ? (
+        <Text color="fg.subtle" fontSize="2xs" lineClamp={2}>
+          {description}
+        </Text>
+      ) : null}
+    </Stack>
+    {trailing}
+  </Panel>
+);
+
+/**
+ * Install action with live state: idle → Install button; queuing/active →
+ * disabled "Installing…" with a jump to the install queue; done → badge.
+ */
+export const InstallSourceButton = ({
+  isInstalled = false,
+  isPending = false,
+  onInstall,
+  source,
+}: {
+  /** Already in the library (renders a static badge). */
+  isInstalled?: boolean;
+  /** The install POST is in flight (before a job exists). */
+  isPending?: boolean;
+  onInstall: () => void;
+  /** Source string used to match an active install job. */
+  source: string;
+}) => {
+  const activeSources = useActiveInstallSources();
+  const isInstalling = isPending || activeSources.has(source);
+
+  if (isInstalled) {
+    return (
+      <Badge colorPalette="green" flexShrink={0} fontSize="2xs" size="sm" variant="surface">
+        Installed
+      </Badge>
+    );
+  }
+
+  if (isInstalling) {
+    return (
+      <HStack flexShrink={0} gap="1.5">
+        <Badge colorPalette="blue" fontSize="2xs" size="sm" variant="surface">
+          <Spinner borderWidth="1.5px" boxSize="2.5" />
+          Installing
+        </Badge>
+        <Button
+          size="2xs"
+          variant="ghost"
+          onClick={(event) => {
+            event.stopPropagation();
+            openInstallQueue();
+          }}
+        >
+          View queue
+        </Button>
+      </HStack>
+    );
+  }
+
+  return (
+    <Button
+      flexShrink={0}
+      size="2xs"
+      variant="outline"
+      onClick={(event) => {
+        event.stopPropagation();
+        onInstall();
+      }}
+    >
+      <Icon as={DownloadIcon} boxSize="3" />
+      Install
+    </Button>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/NodeManagerView.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/NodeManagerView.tsx
new file mode 100644
index 00000000000..89e7afcb640
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/NodeManagerView.tsx
@@ -0,0 +1,22 @@
+import { Flex } from '@chakra-ui/react';
+import { ensureCustomNodePacksLoaded } from '@workbench/customNodes/nodesStore';
+import { useEffect } from 'react';
+
+import { DetailPane } from './manager/DetailPane';
+import { LibraryColumn } from './manager/LibraryColumn';
+
+/** Full custom nodes manager: persistent pack library plus right-side detail pane. */
+export const NodeManagerView = () => {
+  useEffect(() => {
+    ensureCustomNodePacksLoaded();
+  }, []);
+
+  return (
+    <Flex direction="column" h="full" minH="0" w="full">
+      <Flex flex="1" minH="0" w="full">
+        <LibraryColumn />
+        <DetailPane />
+      </Flex>
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/activity/NodeActivityBar.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/activity/NodeActivityBar.tsx
new file mode 100644
index 00000000000..5abbab32d23
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/activity/NodeActivityBar.tsx
@@ -0,0 +1,88 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Badge, Box, Collapsible, Flex, HStack, Icon, Spinner, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { clearCustomNodeInstallLog, useCustomNodeInstallLog } from '@workbench/customNodes/installLogStore';
+import { setNodeActivityExpanded, useNodesUiSelector } from '@workbench/customNodes/nodesUiStore';
+import { ChevronUpIcon, ListOrderedIcon, Trash2Icon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import { NodeInstallLog } from './NodeInstallLog';
+
+/** Persistent, collapsible install activity footer for the nodes manager detail pane. */
+export const NodeActivityBar = () => {
+  const { t } = useTranslation();
+  const activityExpanded = useNodesUiSelector((snapshot) => snapshot.activityExpanded);
+  const log = useCustomNodeInstallLog();
+  const installingCount = log.filter((entry) => entry.status === 'installing').length;
+  const summary =
+    installingCount > 0
+      ? `${log.find((entry) => entry.status === 'installing')?.name ?? t('nodes.installing')}${
+          installingCount > 1 ? t('models.plusMore', { count: installingCount - 1 }) : ''
+        }`
+      : log.length > 0
+        ? t('nodes.recentActivitySummary', { count: log.length })
+        : t('nodes.noRecentActivity');
+
+  return (
+    <Collapsible.Root
+      bg="bg.subtle"
+      borderTopWidth={1}
+      flexShrink={0}
+      open={activityExpanded}
+      overflow="hidden"
+      onOpenChange={(event) => setNodeActivityExpanded(event.open)}
+    >
+      <Collapsible.Content>
+        <Flex direction="column" h="min(22rem, 45dvh)" minH="0" overflow="hidden">
+          <HStack borderBottomWidth={1} gap="2" justify="space-between" px="3" py="1.5">
+            <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+              {t('nodes.installActivity')}
+            </Text>
+            <Button disabled={log.length === 0} size="2xs" variant="ghost" onClick={clearCustomNodeInstallLog}>
+              <Icon as={Trash2Icon} boxSize="3" />
+              {t('common.clear')}
+            </Button>
+          </HStack>
+          <Box flex="1" minH="0" overflow="hidden" p="2">
+            <NodeInstallLog />
+          </Box>
+        </Flex>
+      </Collapsible.Content>
+
+      <HStack gap="1" px="3" py="2">
+        <Collapsible.Trigger
+          alignItems="center"
+          bg="transparent"
+          color="inherit"
+          display="flex"
+          flex="1"
+          gap="2"
+          minW="0"
+          textAlign="start"
+          _hover={{ color: 'fg' }}
+        >
+          {installingCount > 0 ? (
+            <Spinner borderWidth="1.5px" boxSize="3.5" color="accent.solid" flexShrink={0} />
+          ) : (
+            <Icon as={ListOrderedIcon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+          )}
+          <Text flex="1" fontSize="xs" fontWeight="600" minW="0" truncate>
+            {summary}
+          </Text>
+          {installingCount > 0 ? (
+            <Badge colorPalette="accent" flexShrink={0} fontSize="2xs" size="sm" variant="solid">
+              {installingCount}
+            </Badge>
+          ) : null}
+          <Collapsible.Indicator
+            _open={{ transform: 'rotate(180deg)' }}
+            transition="transform var(--wb-motion-duration-slow)"
+          >
+            <Icon as={ChevronUpIcon} boxSize="4" color="fg.subtle" flexShrink={0} />
+          </Collapsible.Indicator>
+        </Collapsible.Trigger>
+      </HStack>
+    </Collapsible.Root>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/activity/NodeInstallLog.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/activity/NodeInstallLog.tsx
new file mode 100644
index 00000000000..3153d4f5b0f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/activity/NodeInstallLog.tsx
@@ -0,0 +1,90 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { SystemStyleObject } from '@chakra-ui/react';
+import type { CustomNodeInstallLogEntry } from '@workbench/customNodes/installLogStore';
+
+import { Badge, Icon, Table, Text } from '@chakra-ui/react';
+import { Scrollable } from '@workbench/components/ui';
+import { EmptyState } from '@workbench/components/ui/EmptyState';
+import { useCustomNodeInstallLog } from '@workbench/customNodes/installLogStore';
+import { InboxIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+const INSTALL_LOG_TABLE_SX: SystemStyleObject = {
+  '& tbody tr:nth-of-type(odd)': { bg: 'bg.muted' },
+  '& th': { bg: 'bg.subtle', position: 'sticky', top: 0, zIndex: 1 },
+};
+
+const STATUS_BADGES: Record<CustomNodeInstallLogEntry['status'], { labelKey: string; palette: string }> = {
+  completed: { labelKey: 'common.status.completed', palette: 'green' },
+  error: { labelKey: 'common.error', palette: 'red' },
+  installing: { labelKey: 'nodes.installing', palette: 'blue' },
+  uninstalled: { labelKey: 'nodes.uninstalled', palette: 'orange' },
+};
+
+/**
+ * Session install activity for the nodes manager. Tracks install / uninstall
+ * outcomes for the current session in a sticky-header table.
+ */
+export const NodeInstallLog = () => {
+  const { t } = useTranslation();
+  const log = useCustomNodeInstallLog();
+
+  if (log.length === 0) {
+    return (
+      <EmptyState
+        description={t('nodes.noRecentActivityDescription')}
+        icon={<Icon as={InboxIcon} />}
+        title={t('nodes.noRecentActivity')}
+      />
+    );
+  }
+
+  return (
+    <Scrollable h="full" label={t('nodes.installActivity')} minH="0">
+      <Table.Root css={INSTALL_LOG_TABLE_SX} minW="36rem" size="sm">
+        <Table.Header>
+          <Table.Row>
+            <Table.ColumnHeader borderColor="border.subtle" ps="3">
+              {t('common.name')}
+            </Table.ColumnHeader>
+            <Table.ColumnHeader borderColor="border.subtle">{t('nodes.status')}</Table.ColumnHeader>
+            <Table.ColumnHeader borderColor="border.subtle" pe="3">
+              {t('nodes.message')}
+            </Table.ColumnHeader>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {log.map((entry) => (
+            <InstallLogRow key={entry.id} entry={entry} />
+          ))}
+        </Table.Body>
+      </Table.Root>
+    </Scrollable>
+  );
+};
+
+const InstallLogRow = ({ entry }: { entry: CustomNodeInstallLogEntry }) => {
+  const { t } = useTranslation();
+  const badge = STATUS_BADGES[entry.status];
+
+  return (
+    <Table.Row>
+      <Table.Cell borderColor="border.subtle" ps="3">
+        <Text fontSize="xs" title={entry.name} truncate>
+          {entry.name}
+        </Text>
+      </Table.Cell>
+      <Table.Cell borderColor="border.subtle">
+        <Badge colorPalette={badge.palette} fontSize="2xs" variant="surface">
+          {t(badge.labelKey)}
+        </Badge>
+      </Table.Cell>
+      <Table.Cell borderColor="border.subtle" pe="3">
+        <Text color="fg.subtle" fontSize="2xs" lineClamp={2} overflowWrap="anywhere">
+          {entry.message ?? ''}
+        </Text>
+      </Table.Cell>
+    </Table.Row>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/add-nodes/AddNodesView.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/add-nodes/AddNodesView.tsx
new file mode 100644
index 00000000000..b032bfd1880
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/add-nodes/AddNodesView.tsx
@@ -0,0 +1,151 @@
+import { Alert, Box, HStack, Icon, Input, Stack, Text } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, Field, Scrollable, Tabs, toaster } from '@workbench/components/ui';
+import { installCustomNodePack } from '@workbench/customNodes/api';
+import { addCustomNodeInstallLogEntry } from '@workbench/customNodes/installLogStore';
+import { refreshCustomNodePacks, useCustomNodesSelector } from '@workbench/customNodes/nodesStore';
+import { updateNodesUi, useNodesUiSelector, type AddNodesTab } from '@workbench/customNodes/nodesUiStore';
+import { FolderOpenIcon, GitBranchIcon } from 'lucide-react';
+import { useCallback, useState, type ChangeEvent, type KeyboardEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Every way to add custom nodes, one sub-tab per source — Git URL install and
+ * the scan-folder workflow. Mirrors the model manager's Add Models view; the
+ * active sub-tab lives in the nodes UI store so it survives navigation.
+ */
+export const AddNodesView = () => {
+  const { t } = useTranslation();
+  const addTab = useNodesUiSelector((snapshot) => snapshot.addTab);
+  const customNodesPath = useCustomNodesSelector((snapshot) => snapshot.customNodesPath);
+  const handleValueChange = useCallback(
+    (event: { value: string }) => updateNodesUi({ addTab: event.value as AddNodesTab }),
+    []
+  );
+
+  return (
+    <Stack gap="3" h="full" minH="0">
+      <Tabs.Root size="sm" value={addTab} onValueChange={handleValueChange}>
+        <Tabs.List>
+          <Tabs.Trigger fontSize="xs" value="git">
+            <Icon as={GitBranchIcon} boxSize="3" />
+            {t('nodes.gitUrl')}
+          </Tabs.Trigger>
+          <Tabs.Trigger fontSize="xs" value="scan">
+            <Icon as={FolderOpenIcon} boxSize="3" />
+            {t('nodes.scanFolder')}
+          </Tabs.Trigger>
+        </Tabs.List>
+      </Tabs.Root>
+      <Scrollable flex="1" label={t('nodes.addCustomNodes')} minH="0" pr="1">
+        {addTab === 'git' ? <InstallFromGitForm /> : <ScanFolderInfo customNodesPath={customNodesPath} />}
+      </Scrollable>
+    </Stack>
+  );
+};
+
+const InstallFromGitForm = () => {
+  const { t } = useTranslation();
+  const [source, setSource] = useState('');
+  const [isInstalling, setIsInstalling] = useState(false);
+  const trimmedSource = source.trim();
+
+  const handleInstall = useCallback(async () => {
+    if (!trimmedSource) {
+      return;
+    }
+
+    setIsInstalling(true);
+    addCustomNodeInstallLogEntry({ name: trimmedSource, status: 'installing' });
+
+    try {
+      const result = await installCustomNodePack(trimmedSource);
+
+      if (result.success) {
+        addCustomNodeInstallLogEntry({ message: result.message, name: result.name, status: 'completed' });
+        setSource('');
+        await refreshCustomNodePacks();
+
+        if (result.requires_dependencies) {
+          toaster.create({
+            description: t('nodes.dependenciesRequiredDescription', {
+              dependencyFile: result.dependency_file ?? 'requirements.txt',
+              name: result.name,
+            }),
+            title: t('nodes.dependenciesRequired'),
+            type: 'warning',
+          });
+        }
+      } else {
+        addCustomNodeInstallLogEntry({ message: result.message, name: result.name, status: 'error' });
+      }
+    } catch (error) {
+      addCustomNodeInstallLogEntry({
+        message: getApiErrorMessage(error, t('nodes.installFailed')),
+        name: trimmedSource,
+        status: 'error',
+      });
+    } finally {
+      setIsInstalling(false);
+    }
+  }, [t, trimmedSource]);
+  const handleSourceChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => setSource(event.currentTarget.value),
+    []
+  );
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'Enter') {
+        event.preventDefault();
+        void handleInstall();
+      }
+    },
+    [handleInstall]
+  );
+  const handleInstallClick = useCallback(() => void handleInstall(), [handleInstall]);
+
+  return (
+    <Stack gap="4" maxW="44rem">
+      <Alert.Root borderRadius="md" size="sm" status="warning" variant="surface">
+        <Alert.Indicator />
+        <Alert.Title fontSize="xs">{t('nodes.trustWarning')}</Alert.Title>
+      </Alert.Root>
+      <Field helpText={t('nodes.gitUrlHelp')} label={t('nodes.gitUrl')}>
+        <HStack align="start" gap="2">
+          <Input
+            placeholder="https://github.com/owner/invokeai-node-pack.git"
+            size="sm"
+            value={source}
+            onChange={handleSourceChange}
+            onKeyDown={handleKeyDown}
+          />
+          <Button disabled={!trimmedSource} loading={isInstalling} size="sm" onClick={handleInstallClick}>
+            {t('nodes.install')}
+          </Button>
+        </HStack>
+      </Field>
+    </Stack>
+  );
+};
+
+const ScanFolderInfo = ({ customNodesPath }: { customNodesPath: string | null }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Stack gap="3" maxW="44rem">
+      <Text color="fg.muted" fontSize="xs">
+        {t('nodes.scanFolderDescription')}
+      </Text>
+      {customNodesPath ? (
+        <Box bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" p="3" rounded="md">
+          <Text color="fg.subtle" fontSize="2xs" fontWeight="600" textTransform="uppercase">
+            {t('nodes.nodesDirectory')}
+          </Text>
+          <Text fontFamily="mono" fontSize="xs" mt="1" overflowWrap="anywhere">
+            {customNodesPath}
+          </Text>
+        </Box>
+      ) : null}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/detail/NodePackDetail.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/detail/NodePackDetail.tsx
new file mode 100644
index 00000000000..eb6e02d6986
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/detail/NodePackDetail.tsx
@@ -0,0 +1,128 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { NodePackInfo } from '@workbench/customNodes/api';
+
+import { Badge, Box, Flex, HStack, Icon, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button, ConfirmDialog } from '@workbench/components/ui';
+import { EmptyState } from '@workbench/components/ui/EmptyState';
+import { useNodePackActions } from '@workbench/launchpad/nodes/shared/useNodePackActions';
+import { ensureInvocationTemplatesLoaded, useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import { BlocksIcon, TriangleAlertIcon, Trash2Icon } from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { NodePreviewCard } from './NodePreviewCard';
+
+/**
+ * Detail pane for a selected pack: a metadata header with an uninstall action,
+ * then a live preview of every node the pack contributes. Previews are built
+ * from the invocation templates the backend parsed from its OpenAPI schema —
+ * `pack.node_types` are the exact invocation type keys, and a pack's nodes all
+ * share `template.nodePack === pack.name`.
+ */
+export const NodePackDetail = ({ onUninstalled, pack }: { onUninstalled: () => void; pack: NodePackInfo }) => {
+  const { t } = useTranslation();
+  const status = useInvocationTemplatesSelector((snapshot) => snapshot.status);
+  const templates = useInvocationTemplatesSelector((snapshot) => snapshot.templates);
+
+  useEffect(() => {
+    ensureInvocationTemplatesLoaded();
+  }, []);
+
+  const packTemplates = useMemo(
+    () => pack.node_types.map((nodeType) => templates[nodeType]).filter((template) => template !== undefined),
+    [pack.node_types, templates]
+  );
+
+  const isLoadingTemplates = (status === 'idle' || status === 'loading') && packTemplates.length === 0;
+
+  return (
+    <Stack gap="4" pb="4">
+      <HStack align="start" gap="3" justify="space-between">
+        <Stack flex="1" gap="1.5" minW="0">
+          <HStack gap="2" minW="0">
+            <Icon as={BlocksIcon} boxSize="4" color="fg.muted" flexShrink={0} />
+            <Text fontSize="sm" fontWeight="700" minW="0" truncate>
+              {pack.name}
+            </Text>
+          </HStack>
+          <Text color="fg.subtle" fontFamily="mono" fontSize="2xs" overflowWrap="anywhere">
+            {pack.path}
+          </Text>
+          <HStack gap="1.5" wrap="wrap">
+            <Badge colorPalette="blue" fontSize="2xs" variant="surface">
+              {t('nodes.nodeCount', { count: pack.node_count })}
+            </Badge>
+          </HStack>
+        </Stack>
+        <UninstallButton onUninstalled={onUninstalled} pack={pack} />
+      </HStack>
+
+      <Stack gap="2">
+        <Text color="fg.subtle" fontSize="2xs" fontWeight="600" textTransform="uppercase">
+          {t('nodes.nodesInPack')}
+        </Text>
+        {isLoadingTemplates ? (
+          <Flex align="center" justify="center" py="10">
+            <Spinner color="fg.subtle" size="sm" />
+          </Flex>
+        ) : packTemplates.length === 0 ? (
+          <EmptyState
+            description={t('nodes.noPreviewsDescription')}
+            icon={<Icon as={TriangleAlertIcon} />}
+            title={t('nodes.noPreviews')}
+          />
+        ) : (
+          <Flex gap="8" wrap="wrap" px="2">
+            {packTemplates.map((template) => (
+              <Box key={template.type} flexShrink={0} w="18rem">
+                <NodePreviewCard template={template} />
+              </Box>
+            ))}
+          </Flex>
+        )}
+      </Stack>
+    </Stack>
+  );
+};
+
+const UninstallButton = ({ onUninstalled, pack }: { onUninstalled: () => void; pack: NodePackInfo }) => {
+  const { t } = useTranslation();
+  const { uninstall } = useNodePackActions();
+  const [isConfirmOpen, setIsConfirmOpen] = useState(false);
+  const [isUninstalling, setIsUninstalling] = useState(false);
+
+  const handleUninstall = async () => {
+    setIsUninstalling(true);
+
+    try {
+      await uninstall(pack, onUninstalled);
+    } finally {
+      setIsUninstalling(false);
+    }
+  };
+
+  return (
+    <>
+      <Button
+        colorPalette="red"
+        flexShrink={0}
+        loading={isUninstalling}
+        size="xs"
+        variant="outline"
+        onClick={() => setIsConfirmOpen(true)}
+      >
+        <Icon as={Trash2Icon} boxSize="3" />
+        {t('nodes.uninstall')}
+      </Button>
+      <ConfirmDialog
+        body={t('nodes.uninstallBody')}
+        confirmLabel={t('nodes.uninstallPack')}
+        isOpen={isConfirmOpen}
+        title={t('nodes.uninstallTitle', { name: pack.name })}
+        onClose={() => setIsConfirmOpen(false)}
+        onConfirm={handleUninstall}
+      />
+    </>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/detail/NodePreviewCard.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/detail/NodePreviewCard.tsx
new file mode 100644
index 00000000000..63317ca02b4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/detail/NodePreviewCard.tsx
@@ -0,0 +1,167 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type {
+  FieldInputTemplate,
+  FieldOutputTemplate,
+  FieldType,
+  InvocationTemplate,
+} from '@workbench/workflows/types';
+
+import { Box, Flex, Icon, Stack, Text } from '@chakra-ui/react';
+import { Tooltip } from '@workbench/components/ui';
+import { getWorkflowNodeChromeProps } from '@workbench/widgets/workflow/editor/nodeChrome';
+import { getFieldTypeColor, getFieldTypeLabel, isModelFieldType } from '@workbench/workflows/fields';
+import { InfoIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * A read-only, static rendering of a single node — the same visual language as
+ * the editor's `InvocationFlowNode` (titled header, output rows above input
+ * rows, colored field handles) but with none of its editor coupling. The real
+ * node depends on ReactFlow context (`Handle`, `useStore`) and the workbench
+ * dispatch; the Launchpad mounts neither, so this previews the node's shape
+ * from just its `InvocationTemplate`. Handles are drawn as plain dots, fields
+ * are labels only (no value controls), and nothing is interactive.
+ */
+
+const sortByUiOrder = <T extends { uiOrder?: number | null }>(templates: T[]): T[] =>
+  [...templates].sort((a, b) => (a.uiOrder ?? Number.MAX_SAFE_INTEGER) - (b.uiOrder ?? Number.MAX_SAFE_INTEGER));
+
+/** A static stand-in for a ReactFlow connection handle, tinted and shaped by field type. */
+const HandleDot = ({ side, type }: { side: 'left' | 'right'; type: FieldType }) => {
+  const color = getFieldTypeColor(type);
+  const isFilled = type.cardinality === 'SINGLE';
+  const isAngular = isModelFieldType(type) || type.batch;
+
+  return (
+    <Box
+      bg={isFilled ? color : 'bg.muted'}
+      borderColor={color}
+      borderRadius={isAngular ? 'xs' : 'full'}
+      borderWidth={isFilled ? '0' : '2px'}
+      boxShadow="0 0 0 1.5px {colors.bg.muted}"
+      boxSize="3"
+      position="absolute"
+      top="50%"
+      transform={`translate(${side === 'left' ? '-50%' : '50%'}, -50%)${type.batch ? ' rotate(45deg)' : ''}`}
+      {...(side === 'left' ? { left: '0' } : { right: '0' })}
+    />
+  );
+};
+
+const FieldTooltip = ({
+  description,
+  direction,
+  template,
+}: {
+  description: string;
+  direction: 'input' | 'output';
+  template: { name: string; title: string; type: FieldType };
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <Stack gap="0.5" maxW="18rem">
+      <Text fontWeight="700">{template.title}</Text>
+      <Text color="fg.subtle">{t('nodes.fieldName', { name: template.name })}</Text>
+      <Text color="fg.subtle">{t('nodes.fieldType', { type: getFieldTypeLabel(template.type) })}</Text>
+      <Text color="fg.subtle">{t(direction === 'input' ? 'nodes.input' : 'nodes.output')}</Text>
+      {description ? <Text>{description}</Text> : null}
+    </Stack>
+  );
+};
+
+const OutputRow = ({ template }: { template: FieldOutputTemplate }) => (
+  <Box position="relative" px="3" py="1">
+    <Tooltip
+      content={<FieldTooltip description={template.description} direction="output" template={template} />}
+      positioning={{ placement: 'top-end' }}
+    >
+      <Flex justify="flex-end">
+        <Text color="fg.muted" fontSize="2xs" lineHeight="1" maxW="full" textAlign="end" truncate>
+          {template.title}
+        </Text>
+      </Flex>
+    </Tooltip>
+    <HandleDot side="right" type={template.type} />
+  </Box>
+);
+
+const InputRow = ({ template }: { template: FieldInputTemplate }) => (
+  <Box position="relative" px="3" py="1">
+    <Tooltip
+      content={<FieldTooltip description={template.description} direction="input" template={template} />}
+      positioning={{ placement: 'top-start' }}
+    >
+      <Text color="fg" fontSize="2xs" lineHeight="1" minW="0" truncate>
+        {template.title}
+        {template.required ? (
+          <Text as="span" color="fg.error">
+            {' *'}
+          </Text>
+        ) : null}
+      </Text>
+    </Tooltip>
+    {template.input !== 'direct' ? <HandleDot side="left" type={template.type} /> : null}
+  </Box>
+);
+
+const NodeInfoTooltip = ({ template }: { template: InvocationTemplate }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Stack gap="1" maxW="20rem">
+      <Text fontWeight="700">{template.title}</Text>
+      <Text color="fg.subtle">{t('nodes.nodeType', { type: template.type })}</Text>
+      <Text color="fg.subtle">{t('nodes.nodeCategory', { category: template.category })}</Text>
+      <Text color="fg.subtle">{t('nodes.nodeVersion', { version: template.version })}</Text>
+      {template.description ? <Text fontStyle="italic">{template.description}</Text> : null}
+    </Stack>
+  );
+};
+
+export const NodePreviewCard = ({ template }: { template: InvocationTemplate }) => {
+  const inputTemplates = sortByUiOrder(Object.values(template.inputs).filter((input) => !input.uiHidden));
+  const outputTemplates = Object.values(template.outputs);
+  const hasFields = inputTemplates.length > 0 || outputTemplates.length > 0;
+
+  return (
+    <Box bg="bg" fontSize="xs" rounded="lg" w="full" {...getWorkflowNodeChromeProps({ selected: false })}>
+      <Flex
+        align="center"
+        bg="bg.subtle"
+        borderBottomWidth="1px"
+        borderColor="border.subtle"
+        borderTopRadius="lg"
+        gap="2"
+        pe="2"
+        ps="2.5"
+        py="1.5"
+      >
+        <Text fontWeight="700" minW="0" title={template.title} truncate>
+          {template.title}
+        </Text>
+        <Box flex="1" />
+        <Tooltip content={<NodeInfoTooltip template={template} />} positioning={{ placement: 'top-end' }} showArrow>
+          <Icon aria-label={`Details for ${template.title}`} as={InfoIcon} boxSize="3.5" color="fg.subtle" />
+        </Tooltip>
+      </Flex>
+      <Stack bg="bg.muted" borderBottomRadius="lg" gap="0" py="1">
+        {hasFields ? (
+          <>
+            {outputTemplates.map((output) => (
+              <OutputRow key={output.name} template={output} />
+            ))}
+            {inputTemplates.map((input) => (
+              <InputRow key={input.name} template={input} />
+            ))}
+          </>
+        ) : (
+          <Text color="fg.subtle" fontSize="2xs" px="3" py="1">
+            No exposed fields.
+          </Text>
+        )}
+      </Stack>
+    </Box>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/library/NodePackContextMenu.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/library/NodePackContextMenu.tsx
new file mode 100644
index 00000000000..5e649583bc1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/library/NodePackContextMenu.tsx
@@ -0,0 +1,78 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { NodePackInfo } from '@workbench/customNodes/api';
+
+import { Icon, Menu, Portal } from '@chakra-ui/react';
+import { ConfirmDialog, MenuContent } from '@workbench/components/ui';
+import { useNodePackActions } from '@workbench/launchpad/nodes/shared/useNodePackActions';
+import { Trash2Icon } from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export interface NodePackContextMenuTarget {
+  pack: NodePackInfo;
+  x: number;
+  y: number;
+}
+
+export const NodePackContextMenu = ({
+  onClose,
+  onUninstalled,
+  target,
+}: {
+  onClose: () => void;
+  onUninstalled: (packName: string) => void;
+  target: NodePackContextMenuTarget | null;
+}) => {
+  const { t } = useTranslation();
+  const { uninstall } = useNodePackActions();
+  const [pendingUninstall, setPendingUninstall] = useState<NodePackInfo | null>(null);
+  const pack = target?.pack ?? null;
+
+  return (
+    <>
+      <Menu.Root
+        key={target ? target.pack.name : 'closed'}
+        lazyMount
+        open={target !== null}
+        positioning={{
+          getAnchorRect: () => (target ? { height: 1, width: 1, x: target.x, y: target.y } : null),
+          placement: 'bottom-start',
+        }}
+        unmountOnExit
+        onOpenChange={(event) => {
+          if (!event.open) {
+            onClose();
+          }
+        }}
+      >
+        <Portal>
+          <Menu.Positioner>
+            {pack ? (
+              <MenuContent minW="12rem">
+                <Menu.Item color="fg.error" value="uninstall" onClick={() => setPendingUninstall(pack)}>
+                  <Icon as={Trash2Icon} boxSize="3.5" />
+                  <Menu.ItemText fontSize="xs">{t('nodes.uninstall')}</Menu.ItemText>
+                </Menu.Item>
+              </MenuContent>
+            ) : null}
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <ConfirmDialog
+        body={t('nodes.uninstallBody')}
+        confirmLabel={t('nodes.uninstallPack')}
+        isOpen={pendingUninstall !== null}
+        title={t('nodes.uninstallTitle', { name: pendingUninstall?.name ?? t('nodes.nodePack') })}
+        onClose={() => setPendingUninstall(null)}
+        onConfirm={async () => {
+          if (!pendingUninstall) {
+            return;
+          }
+
+          await uninstall(pendingUninstall, onUninstalled);
+        }}
+      />
+    </>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/library/NodePackList.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/library/NodePackList.tsx
new file mode 100644
index 00000000000..adab87b4a58
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/library/NodePackList.tsx
@@ -0,0 +1,168 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { NodePackInfo } from '@workbench/customNodes/api';
+
+import { Badge, Flex, Icon, Input, InputGroup, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button, Row, Scrollable } from '@workbench/components/ui';
+import { EmptyState } from '@workbench/components/ui/EmptyState';
+import { refreshCustomNodePacks } from '@workbench/customNodes/nodesStore';
+import { BlocksIcon, PackageOpenIcon, SearchIcon, TriangleAlertIcon } from 'lucide-react';
+import { useDeferredValue, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { NodePackContextMenu, type NodePackContextMenuTarget } from './NodePackContextMenu';
+
+/**
+ * Master list for the nodes manager: a search box over a scrollable column of
+ * selectable pack rows. Mirrors the model library list — `Row` with the
+ * `accent` active variant marks the open pack, and the search filters by name
+ * or path.
+ */
+export const NodePackList = ({
+  activePackName,
+  error,
+  onSearchChange,
+  onSelect,
+  onUninstalled,
+  packs,
+  searchTerm,
+  status,
+}: {
+  activePackName: string | null;
+  error: string | null;
+  onSearchChange: (value: string) => void;
+  onSelect: (packName: string) => void;
+  onUninstalled: (packName: string) => void;
+  packs: NodePackInfo[];
+  searchTerm: string;
+  status: 'idle' | 'loading' | 'loaded' | 'error';
+}) => {
+  const { t } = useTranslation();
+  const [contextMenuTarget, setContextMenuTarget] = useState<NodePackContextMenuTarget | null>(null);
+  const deferredSearchTerm = useDeferredValue(searchTerm);
+  const filtered = useMemo(() => {
+    const query = deferredSearchTerm.trim().toLowerCase();
+
+    if (!query) {
+      return packs;
+    }
+
+    return packs.filter((pack) => pack.name.toLowerCase().includes(query) || pack.path.toLowerCase().includes(query));
+  }, [deferredSearchTerm, packs]);
+
+  if (status === 'error') {
+    return (
+      <Flex align="center" flex="1" justify="center" minH="0" p="3">
+        <EmptyState
+          danger
+          description={error}
+          icon={<Icon as={TriangleAlertIcon} />}
+          title={t('nodes.couldNotLoadPacks')}
+        >
+          <Button size="sm" variant="outline" onClick={() => void refreshCustomNodePacks()}>
+            {t('common.retry')}
+          </Button>
+        </EmptyState>
+      </Flex>
+    );
+  }
+
+  return (
+    <Stack flex="1" gap="2" minH="0" pt="3">
+      <InputGroup px="3" startElement={<Icon as={SearchIcon} boxSize="3.5" color="fg.subtle" />}>
+        <Input
+          aria-label={t('nodes.searchPacks')}
+          placeholder={t('nodes.searchPacksPlaceholder')}
+          size="xs"
+          value={searchTerm}
+          onChange={(event) => onSearchChange(event.currentTarget.value)}
+        />
+      </InputGroup>
+      <Scrollable h="full" label={t('nodes.installedPacks')} minH="0">
+        {status === 'idle' || status === 'loading' ? (
+          <Flex align="center" justify="center" py="10">
+            <Spinner color="fg.subtle" size="sm" />
+          </Flex>
+        ) : packs.length === 0 ? (
+          <EmptyState
+            description={t('nodes.noPacksDescription')}
+            icon={<Icon as={PackageOpenIcon} />}
+            title={t('nodes.noPacks')}
+          />
+        ) : filtered.length === 0 ? (
+          <EmptyState
+            description={t('nodes.tryDifferentSearch')}
+            icon={<Icon as={SearchIcon} />}
+            title={t('nodes.noPacksMatch')}
+          />
+        ) : (
+          <Stack gap="1" minW="0" p="1" px="3" w="full">
+            {filtered.map((pack) => (
+              <PackRow
+                key={pack.name}
+                isActive={pack.name === activePackName}
+                pack={pack}
+                onContextMenu={(targetPack, x, y) => setContextMenuTarget({ pack: targetPack, x, y })}
+                onSelect={() => onSelect(pack.name)}
+              />
+            ))}
+          </Stack>
+        )}
+      </Scrollable>
+      <NodePackContextMenu
+        target={contextMenuTarget}
+        onClose={() => setContextMenuTarget(null)}
+        onUninstalled={onUninstalled}
+      />
+    </Stack>
+  );
+};
+
+const PackRow = ({
+  isActive,
+  onContextMenu,
+  onSelect,
+  pack,
+}: {
+  isActive: boolean;
+  onContextMenu: (pack: NodePackInfo, x: number, y: number) => void;
+  onSelect: () => void;
+  pack: NodePackInfo;
+}) => (
+  <Row
+    active={isActive ? 'accent' : 'none'}
+    aria-current={isActive || undefined}
+    px="2"
+    py="1.5"
+    minW="0"
+    overflow="hidden"
+    role="button"
+    rounded="md"
+    tabIndex={0}
+    onClick={onSelect}
+    onContextMenu={(event) => {
+      event.preventDefault();
+      onContextMenu(pack, event.clientX, event.clientY);
+    }}
+    onKeyDown={(event) => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        onSelect();
+      }
+    }}
+  >
+    <Icon as={BlocksIcon} boxSize="4" color={isActive ? 'accent.contrast' : 'fg.subtle'} flexShrink={0} />
+    <Text fontSize="xs" fontWeight="600" maxW="full" truncate>
+      {pack.name}
+    </Text>
+    <Badge
+      colorPalette={isActive ? undefined : 'gray'}
+      flexShrink={0}
+      fontSize="2xs"
+      variant={isActive ? 'solid' : 'surface'}
+      ms="auto"
+    >
+      {pack.node_count}
+    </Badge>
+  </Row>
+);
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/DetailPane.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/DetailPane.tsx
new file mode 100644
index 00000000000..fe7beafa681
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/DetailPane.tsx
@@ -0,0 +1,82 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Box, Flex, Icon, Text } from '@chakra-ui/react';
+import { Scrollable, Tabs } from '@workbench/components/ui';
+import { useCustomNodesSelector } from '@workbench/customNodes/nodesStore';
+import { updateNodesUi, useNodesUiSelector, type NodesManagerTab } from '@workbench/customNodes/nodesUiStore';
+import { NodeActivityBar } from '@workbench/launchpad/nodes/activity/NodeActivityBar';
+import { AddNodesView } from '@workbench/launchpad/nodes/add-nodes/AddNodesView';
+import { NodePackDetail } from '@workbench/launchpad/nodes/detail/NodePackDetail';
+import { BlocksIcon, PlusIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import { HEADER_MIN_HEIGHT } from './layoutConstants';
+
+/** Right side of the nodes manager: selected pack details, Add Nodes, and activity footer. */
+export const DetailPane = () => {
+  const { t } = useTranslation();
+  const activePackName = useNodesUiSelector((snapshot) => snapshot.activePackName);
+  const activeTab = useNodesUiSelector((snapshot) => snapshot.activeTab);
+  const nodePacks = useCustomNodesSelector((snapshot) => snapshot.nodePacks);
+  const activePack = nodePacks.find((pack) => pack.name === activePackName) ?? null;
+  const detailLabel = activePack?.name ?? t('nodes.details');
+
+  return (
+    <Flex direction="column" flex="1" minH="0" minW="0">
+      <Flex align="flex-end" borderBottomWidth={1} flexShrink={0} minH={HEADER_MIN_HEIGHT} px="2">
+        <Tabs.Root
+          size="sm"
+          mb="-1px"
+          value={activeTab}
+          onValueChange={(event) => updateNodesUi({ activeTab: event.value as NodesManagerTab })}
+        >
+          <Tabs.List h="full">
+            <Tabs.Trigger fontSize="xs" value="details">
+              <Icon as={BlocksIcon} boxSize="3" />
+              <Text maxW="14rem" truncate>
+                {detailLabel}
+              </Text>
+            </Tabs.Trigger>
+            <Tabs.Trigger fontSize="xs" value="add">
+              <Icon as={PlusIcon} boxSize="3" />
+              {t('nodes.addNodes')}
+            </Tabs.Trigger>
+          </Tabs.List>
+        </Tabs.Root>
+      </Flex>
+
+      <Box flex="1" minH="0">
+        {activeTab === 'details' ? <DetailTab packName={activePackName} /> : null}
+        {activeTab === 'add' ? <AddNodesView /> : null}
+      </Box>
+
+      <NodeActivityBar />
+    </Flex>
+  );
+};
+
+const DetailTab = ({ packName }: { packName: string | null }) => {
+  const { t } = useTranslation();
+  const nodePacks = useCustomNodesSelector((snapshot) => snapshot.nodePacks);
+  const activePack = nodePacks.find((pack) => pack.name === packName) ?? null;
+
+  if (!activePack) {
+    return (
+      <Flex align="center" direction="column" gap="2" h="full" justify="center" p="6">
+        <Icon as={BlocksIcon} boxSize="8" color="fg.subtle" />
+        <Text color="fg.muted" fontSize="sm" fontWeight="600">
+          {t('nodes.selectPack')}
+        </Text>
+        <Text color="fg.subtle" fontSize="xs" maxW="22rem" textAlign="center">
+          {t('nodes.selectPackDescription')}
+        </Text>
+      </Flex>
+    );
+  }
+
+  return (
+    <Scrollable h="full" label={t('nodes.details')} minH="0" p="3">
+      <NodePackDetail pack={activePack} onUninstalled={() => updateNodesUi({ activePackName: null })} />
+    </Scrollable>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/LibraryColumn.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/LibraryColumn.tsx
new file mode 100644
index 00000000000..3fd4e0b5526
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/LibraryColumn.tsx
@@ -0,0 +1,59 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Box, Flex, HStack, Text } from '@chakra-ui/react';
+import { useCustomNodesSelector } from '@workbench/customNodes/nodesStore';
+import { openNodePackDetail, updateNodesUi, useNodesUiSelector } from '@workbench/customNodes/nodesUiStore';
+import { NodePackList } from '@workbench/launchpad/nodes/library/NodePackList';
+import { useTranslation } from 'react-i18next';
+
+import { HEADER_MIN_HEIGHT, PACK_LIBRARY_WIDTH } from './layoutConstants';
+import { ReloadNodesButton } from './ReloadNodesButton';
+
+/** Persistent custom-node pack list, matching the model manager's library column. */
+export const LibraryColumn = () => {
+  const { t } = useTranslation();
+  const activePackName = useNodesUiSelector((snapshot) => snapshot.activePackName);
+  const searchTerm = useNodesUiSelector((snapshot) => snapshot.searchTerm);
+  const error = useCustomNodesSelector((snapshot) => snapshot.error);
+  const nodePacks = useCustomNodesSelector((snapshot) => snapshot.nodePacks);
+  const status = useCustomNodesSelector((snapshot) => snapshot.status);
+
+  return (
+    <Flex
+      borderEndWidth={1}
+      direction="column"
+      flexShrink={0}
+      h="full"
+      minH="0"
+      position="relative"
+      w={PACK_LIBRARY_WIDTH}
+    >
+      <HStack align="center" borderBottomWidth={1} flexShrink={0} gap="2" minH={HEADER_MIN_HEIGHT} px="3">
+        <Text fontSize="sm" fontWeight="700">
+          {t('nodes.nodePacks')}
+        </Text>
+        <Text color="fg.subtle" fontSize="xs">
+          {nodePacks.length}
+        </Text>
+        <Box ms="auto">
+          <ReloadNodesButton />
+        </Box>
+      </HStack>
+
+      <NodePackList
+        activePackName={activePackName}
+        error={error}
+        packs={nodePacks}
+        searchTerm={searchTerm}
+        status={status}
+        onSearchChange={(value) => updateNodesUi({ searchTerm: value })}
+        onSelect={openNodePackDetail}
+        onUninstalled={(packName) => {
+          if (activePackName === packName) {
+            updateNodesUi({ activePackName: null });
+          }
+        }}
+      />
+    </Flex>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/ReloadNodesButton.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/ReloadNodesButton.tsx
new file mode 100644
index 00000000000..0e20e411108
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/ReloadNodesButton.tsx
@@ -0,0 +1,38 @@
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import { Icon } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button } from '@workbench/components/ui';
+import { reloadCustomNodes } from '@workbench/customNodes/api';
+import { refreshCustomNodePacks } from '@workbench/customNodes/nodesStore';
+import { useNotify } from '@workbench/useNotify';
+import { RefreshCwIcon } from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export const ReloadNodesButton = () => {
+  const notify = useNotify();
+  const { t } = useTranslation();
+  const [isReloading, setIsReloading] = useState(false);
+
+  const handleReload = async () => {
+    setIsReloading(true);
+
+    try {
+      await reloadCustomNodes();
+      await refreshCustomNodePacks();
+      notify.success(t('nodes.customNodesReloaded'));
+    } catch (error) {
+      notify.error(t('nodes.reloadFailed'), getApiErrorMessage(error, t('nodes.couldNotReloadCustomNodes')));
+    } finally {
+      setIsReloading(false);
+    }
+  };
+
+  return (
+    <Button loading={isReloading} size="2xs" variant="ghost" onClick={() => void handleReload()}>
+      <Icon as={RefreshCwIcon} boxSize="3.5" />
+      {isReloading ? t('nodes.reloading') : t('common.reload')}
+    </Button>
+  );
+};
+/* eslint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/layoutConstants.ts b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/layoutConstants.ts
new file mode 100644
index 00000000000..b2df20068dc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/manager/layoutConstants.ts
@@ -0,0 +1,2 @@
+export const PACK_LIBRARY_WIDTH = '22rem';
+export const HEADER_MIN_HEIGHT = '2.75rem';
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/nodes/shared/useNodePackActions.ts b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/shared/useNodePackActions.ts
new file mode 100644
index 00000000000..a87af50c853
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/nodes/shared/useNodePackActions.ts
@@ -0,0 +1,27 @@
+import type { NodePackInfo } from '@workbench/customNodes/api';
+
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { uninstallCustomNodePack } from '@workbench/customNodes/api';
+import { addCustomNodeInstallLogEntry } from '@workbench/customNodes/installLogStore';
+import { refreshCustomNodePacks, removeCustomNodePackFromStore } from '@workbench/customNodes/nodesStore';
+import { useNotify } from '@workbench/useNotify';
+
+export const useNodePackActions = () => {
+  const notify = useNotify();
+
+  const uninstall = async (pack: NodePackInfo, onUninstalled?: (packName: string) => void) => {
+    try {
+      const result = await uninstallCustomNodePack(pack.name);
+
+      removeCustomNodePackFromStore(pack.name);
+      addCustomNodeInstallLogEntry({ message: result.message, name: result.name, status: 'uninstalled' });
+      notify.success('Node pack uninstalled', 'Restart InvokeAI for node removal to take full effect.');
+      onUninstalled?.(pack.name);
+    } catch (error) {
+      notify.error('Uninstall failed', getApiErrorMessage(error, 'Could not uninstall the node pack.'));
+      await refreshCustomNodePacks();
+    }
+  };
+
+  return { uninstall };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/pages/ModelsPage.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/pages/ModelsPage.tsx
new file mode 100644
index 00000000000..3140717955f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/pages/ModelsPage.tsx
@@ -0,0 +1,29 @@
+import { Center, Spinner } from '@chakra-ui/react';
+import { lazy, Suspense } from 'react';
+
+/**
+ * The Launchpad's model manager: full library, add-models flow, credentials,
+ * and install queue. It is the widest page, so it runs full-bleed (the view owns
+ * its own padding and internal master-detail scroll).
+ *
+ * The manager pulls in ~6k lines of model UI and stores, none of which the
+ * Launchpad needs at first paint, so it is code-split: the chunk loads the
+ * first time this tab is opened (the shell's `lazyMount` keeps it off the
+ * critical path until then) and stays warm afterwards. All model state lives in
+ * external stores, so the view needs no workbench providers here.
+ */
+const ModelManagerView = lazy(() =>
+  import('@workbench/launchpad/models/ModelManagerView').then((module) => ({ default: module.ModelManagerView }))
+);
+
+const FALLBACK = (
+  <Center h="full">
+    <Spinner color="fg.muted" size="sm" />
+  </Center>
+);
+
+export const ModelsPage = () => (
+  <Suspense fallback={FALLBACK}>
+    <ModelManagerView />
+  </Suspense>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/pages/NodesPage.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/pages/NodesPage.tsx
new file mode 100644
index 00000000000..52081a89e57
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/pages/NodesPage.tsx
@@ -0,0 +1,18 @@
+import { Center, Spinner } from '@chakra-ui/react';
+import { lazy, Suspense } from 'react';
+
+const NodeManagerView = lazy(() =>
+  import('@workbench/launchpad/nodes/NodeManagerView').then((module) => ({ default: module.NodeManagerView }))
+);
+
+const FALLBACK = (
+  <Center h="full">
+    <Spinner color="fg.muted" size="sm" />
+  </Center>
+);
+
+export const NodesPage = () => (
+  <Suspense fallback={FALLBACK}>
+    <NodeManagerView />
+  </Suspense>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/pages/ProjectsPage.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/pages/ProjectsPage.tsx
new file mode 100644
index 00000000000..eaa082c9eaa
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/pages/ProjectsPage.tsx
@@ -0,0 +1,92 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+import { Flex, Heading, HStack, Stack, Text } from '@chakra-ui/react';
+import { Link, useNavigate } from '@tanstack/react-router';
+import { useAuthSession } from '@workbench/auth/session';
+import { Button, Scrollable, toaster } from '@workbench/components/ui';
+import { ProjectsGrid } from '@workbench/launchpad/ProjectsGrid';
+import { refreshProjectLibrary } from '@workbench/projects/library';
+import { importProjectFile, pickProjectFile } from '@workbench/projects/projectFile';
+import { FileUpIcon, PlusIcon } from 'lucide-react';
+import { useCallback, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * The Launchpad's home section: your project library. It keeps a comfortable
+ * centered measure (the grid reads better than full-bleed) and owns its own
+ * scroll so the rail and header stay fixed.
+ */
+const PROJECTS_PAGE_MEASURE_SX: SystemStyleObject = {
+  maxW: '6xl',
+  mx: 'auto',
+  p: { base: 4, md: 8 },
+  w: 'full',
+};
+
+const NEW_PROJECT_SEARCH = { new: true } as const;
+
+export const ProjectsPage = () => {
+  const session = useAuthSession();
+  const navigate = useNavigate();
+  const { t } = useTranslation();
+
+  useEffect(() => {
+    void refreshProjectLibrary();
+  }, []);
+
+  const displayName = session.user?.display_name?.trim();
+  const greeting = displayName
+    ? t('launchpad.projectsGreetingWithName', { name: displayName })
+    : t('launchpad.projectsGreeting');
+
+  const handleImport = useCallback(async () => {
+    const file = await pickProjectFile();
+
+    if (!file) {
+      return;
+    }
+
+    try {
+      const record = await importProjectFile(file);
+
+      await navigate({ search: { project: record.project_id }, to: '/app' });
+    } catch (error) {
+      toaster.create({
+        description: error instanceof Error ? error.message : undefined,
+        title: t('projects.importFailed'),
+        type: 'error',
+      });
+    }
+  }, [navigate, t]);
+  const handleImportClick = useCallback(() => void handleImport(), [handleImport]);
+
+  return (
+    <Scrollable h="full" label={t('launchpad.sections.projects')} minH="0">
+      <Stack css={PROJECTS_PAGE_MEASURE_SX} gap="5">
+        <Flex align="center" gap="3" justify="space-between" wrap="wrap">
+          <Stack gap="0.5">
+            <Heading fontSize="xl" fontWeight="700">
+              {greeting}
+            </Heading>
+            <Text color="fg.muted" fontSize="xs">
+              {t('launchpad.projectsSubtitle')}
+            </Text>
+          </Stack>
+          <HStack gap="2" wrap="wrap">
+            <Button size="xs" variant="outline" onClick={handleImportClick}>
+              <FileUpIcon />
+              {t('projects.importWithEllipsis')}
+            </Button>
+            <Button asChild size="xs" variant="solid">
+              <Link search={NEW_PROJECT_SEARCH} to="/app">
+                <PlusIcon />
+                {t('projects.newProject')}
+              </Link>
+            </Button>
+          </HStack>
+        </Flex>
+        <ProjectsGrid />
+      </Stack>
+    </Scrollable>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/launchpad/pages/UsersPage.tsx b/invokeai/frontend/webv2/src/workbench/launchpad/pages/UsersPage.tsx
new file mode 100644
index 00000000000..5a74d4667e9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/launchpad/pages/UsersPage.tsx
@@ -0,0 +1,29 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+import { Box } from '@chakra-ui/react';
+import { Scrollable } from '@workbench/components/ui';
+import { UsersManagementPanel } from '@workbench/users';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Admin-only section: create, edit, and remove users. Mirrors the Projects
+ * page's centered measure and self-scroll so the chrome stays put.
+ */
+const USERS_PAGE_MEASURE_SX: SystemStyleObject = {
+  maxW: '6xl',
+  mx: 'auto',
+  p: { base: 4, md: 8 },
+  w: 'full',
+};
+
+export const UsersPage = () => {
+  const { t } = useTranslation();
+
+  return (
+    <Scrollable h="full" label={t('users.management')} minH="0">
+      <Box css={USERS_PAGE_MEASURE_SX}>
+        <UsersManagementPanel />
+      </Box>
+    </Scrollable>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/layoutPresetSnapshots.ts b/invokeai/frontend/webv2/src/workbench/layoutPresetSnapshots.ts
new file mode 100644
index 00000000000..48e3d5c6f2d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/layoutPresetSnapshots.ts
@@ -0,0 +1,81 @@
+import type {
+  LayoutPreset,
+  LayoutPresetSnapshot,
+  LayoutPresetWidgetInstanceSnapshot,
+  Project,
+  WidgetInstanceId,
+  WidgetRegion,
+  WidgetRegionState,
+} from './types';
+
+const widgetRegions: WidgetRegion[] = ['left', 'right', 'bottom', 'center'];
+
+export const cloneLayoutPresetWidgetRegions = (
+  widgetRegionState: Record<WidgetRegion, WidgetRegionState>
+): Record<WidgetRegion, WidgetRegionState> => ({
+  bottom: { ...widgetRegionState.bottom, instanceIds: [...widgetRegionState.bottom.instanceIds] },
+  center: { ...widgetRegionState.center, instanceIds: [...widgetRegionState.center.instanceIds] },
+  left: { ...widgetRegionState.left, instanceIds: [...widgetRegionState.left.instanceIds] },
+  right: { ...widgetRegionState.right, instanceIds: [...widgetRegionState.right.instanceIds] },
+});
+
+export const createLayoutPresetSnapshot = (project: Project): LayoutPresetSnapshot => {
+  const referencedInstanceIds = new Set<WidgetInstanceId>();
+
+  for (const region of widgetRegions) {
+    referencedInstanceIds.add(project.widgetRegions[region].activeInstanceId);
+
+    for (const instanceId of project.widgetRegions[region].instanceIds) {
+      referencedInstanceIds.add(instanceId);
+    }
+  }
+
+  const widgetInstances: Record<WidgetInstanceId, LayoutPresetWidgetInstanceSnapshot> = {};
+
+  for (const instanceId of referencedInstanceIds) {
+    const instance = project.widgetInstances[instanceId];
+
+    if (instance) {
+      widgetInstances[instanceId] = { id: instance.id, title: instance.title, typeId: instance.typeId };
+    }
+  }
+
+  return {
+    layout: { ...project.layout, panels: { ...project.layout.panels } },
+    widgetInstances,
+    widgetRegions: cloneLayoutPresetWidgetRegions(project.widgetRegions),
+  };
+};
+
+const areArraysEqual = (left: string[], right: string[]): boolean =>
+  left.length === right.length && left.every((value, index) => value === right[index]);
+
+const areWidgetRegionsEqual = (left: WidgetRegionState, right: WidgetRegionState): boolean =>
+  left.activeInstanceId === right.activeInstanceId &&
+  left.isCollapsed === right.isCollapsed &&
+  left.sizePx === right.sizePx &&
+  areArraysEqual(left.instanceIds, right.instanceIds);
+
+const areWidgetInstanceSnapshotsEqual = (
+  left: LayoutPresetSnapshot['widgetInstances'],
+  right: LayoutPresetSnapshot['widgetInstances']
+): boolean => {
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+
+  return (
+    areArraysEqual(leftKeys, rightKeys) &&
+    leftKeys.every((key) => left[key]?.typeId === right[key]?.typeId && left[key]?.title === right[key]?.title)
+  );
+};
+
+export const areLayoutPresetSnapshotsEqual = (left: LayoutPresetSnapshot, right: LayoutPresetSnapshot): boolean =>
+  left.layout.centerViewId === right.layout.centerViewId &&
+  left.layout.panels.isBottomOpen === right.layout.panels.isBottomOpen &&
+  left.layout.panels.isLeftOpen === right.layout.panels.isLeftOpen &&
+  left.layout.panels.isRightOpen === right.layout.panels.isRightOpen &&
+  widgetRegions.every((region) => areWidgetRegionsEqual(left.widgetRegions[region], right.widgetRegions[region])) &&
+  areWidgetInstanceSnapshotsEqual(left.widgetInstances, right.widgetInstances);
+
+export const doesProjectMatchLayoutPreset = (project: Project, preset: LayoutPreset): boolean =>
+  areLayoutPresetSnapshotsEqual(createLayoutPresetSnapshot(project), preset.snapshot);
diff --git a/invokeai/frontend/webv2/src/workbench/layoutPresets.ts b/invokeai/frontend/webv2/src/workbench/layoutPresets.ts
new file mode 100644
index 00000000000..64ed692e44b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/layoutPresets.ts
@@ -0,0 +1,223 @@
+import type {
+  BuiltInLayoutPresetId,
+  CenterViewId,
+  LayoutPreset,
+  LayoutPresetSnapshot,
+  LayoutPresetWidgetInstanceSnapshot,
+  PanelState,
+  WidgetInstanceId,
+  WidgetRegion,
+  WidgetRegionState,
+  WidgetTypeId,
+} from './types';
+
+const defaultBottomInstanceIds: WidgetInstanceId[] = [
+  'server-status',
+  'diagnostics:bottom',
+  'gallery:bottom',
+  'notifications',
+  'autosave-status',
+  'version-status',
+  'workflow:bottom',
+];
+
+const defaultInstanceTypes: Record<WidgetInstanceId, WidgetTypeId> = {
+  'autosave-status': 'autosave-status',
+  canvas: 'canvas',
+  diagnostics: 'diagnostics',
+  'diagnostics:bottom': 'diagnostics',
+  gallery: 'gallery',
+  'gallery:bottom': 'gallery',
+  'gallery:center': 'gallery',
+  generate: 'generate',
+  layers: 'layers',
+  notifications: 'notifications',
+  preview: 'preview',
+  project: 'project',
+  queue: 'queue',
+  'server-status': 'server-status',
+  'version-status': 'version-status',
+  workflow: 'workflow',
+  'workflow:bottom': 'workflow',
+  'workflow:center': 'workflow',
+};
+
+const createRegion = ({
+  activeInstanceId,
+  instanceIds,
+  isCollapsed = false,
+  sizePx,
+}: {
+  activeInstanceId: WidgetInstanceId;
+  instanceIds: WidgetInstanceId[];
+  isCollapsed?: boolean;
+  sizePx: number;
+}): WidgetRegionState => ({ activeInstanceId, instanceIds, isCollapsed, sizePx });
+
+const createWidgetInstances = (
+  widgetRegions: Record<WidgetRegion, WidgetRegionState>
+): Record<WidgetInstanceId, LayoutPresetWidgetInstanceSnapshot> => {
+  const widgetInstances: Record<WidgetInstanceId, LayoutPresetWidgetInstanceSnapshot> = {};
+
+  for (const region of Object.values(widgetRegions)) {
+    const instanceIds = new Set([region.activeInstanceId, ...region.instanceIds]);
+
+    for (const instanceId of instanceIds) {
+      const typeId = defaultInstanceTypes[instanceId];
+
+      if (typeId) {
+        widgetInstances[instanceId] = { id: instanceId, typeId };
+      }
+    }
+  }
+
+  return widgetInstances;
+};
+
+const createSnapshot = ({
+  centerViewId,
+  panels,
+  presetId,
+  widgetRegions,
+}: {
+  centerViewId: CenterViewId;
+  panels: PanelState;
+  presetId: BuiltInLayoutPresetId;
+  widgetRegions: Record<WidgetRegion, WidgetRegionState>;
+}): LayoutPresetSnapshot => ({
+  layout: { centerViewId, panels, presetId },
+  widgetInstances: createWidgetInstances(widgetRegions),
+  widgetRegions,
+});
+
+const createPreset = ({
+  centerViewId,
+  id,
+  label,
+  panels,
+  widgetRegions,
+}: {
+  centerViewId: CenterViewId;
+  id: BuiltInLayoutPresetId;
+  label: string;
+  panels: PanelState;
+  widgetRegions: Record<WidgetRegion, WidgetRegionState>;
+}): LayoutPreset => ({
+  id,
+  isBuiltIn: true,
+  label,
+  snapshot: createSnapshot({ centerViewId, panels, presetId: id, widgetRegions }),
+});
+
+export const layoutPresets: LayoutPreset[] = [
+  createPreset({
+    centerViewId: 'preview',
+    id: 'canvas-default',
+    label: 'Default',
+    panels: { isBottomOpen: false, isLeftOpen: true, isRightOpen: true },
+    widgetRegions: {
+      bottom: createRegion({
+        activeInstanceId: 'gallery:bottom',
+        instanceIds: defaultBottomInstanceIds,
+        isCollapsed: true,
+        sizePx: 180,
+      }),
+      center: createRegion({
+        activeInstanceId: 'preview',
+        instanceIds: ['preview', 'canvas', 'gallery:center', 'workflow:center'],
+        sizePx: 0,
+      }),
+      left: createRegion({ activeInstanceId: 'generate', instanceIds: ['generate', 'workflow'], sizePx: 450 }),
+      right: createRegion({
+        activeInstanceId: 'gallery',
+        instanceIds: ['gallery', 'preview', 'queue', 'layers', 'diagnostics', 'project'],
+        sizePx: 450,
+      }),
+    },
+  }),
+  createPreset({
+    centerViewId: 'workflow',
+    id: 'workflow',
+    label: 'Workflow',
+    panels: { isBottomOpen: false, isLeftOpen: true, isRightOpen: true },
+    widgetRegions: {
+      bottom: createRegion({
+        activeInstanceId: 'workflow:bottom',
+        instanceIds: defaultBottomInstanceIds,
+        isCollapsed: true,
+        sizePx: 180,
+      }),
+      center: createRegion({
+        activeInstanceId: 'workflow:center',
+        instanceIds: ['workflow:center', 'canvas', 'preview', 'gallery:center'],
+        sizePx: 0,
+      }),
+      left: createRegion({ activeInstanceId: 'workflow', instanceIds: ['workflow', 'generate'], sizePx: 450 }),
+      right: createRegion({
+        activeInstanceId: 'queue',
+        instanceIds: ['queue', 'gallery', 'layers', 'preview', 'diagnostics', 'project'],
+        sizePx: 450,
+      }),
+    },
+  }),
+  createPreset({
+    centerViewId: 'canvas',
+    id: 'canvas',
+    label: 'Canvas',
+    panels: { isBottomOpen: false, isLeftOpen: true, isRightOpen: true },
+    widgetRegions: {
+      bottom: createRegion({
+        activeInstanceId: 'gallery:bottom',
+        instanceIds: defaultBottomInstanceIds,
+        isCollapsed: true,
+        sizePx: 180,
+      }),
+      center: createRegion({
+        activeInstanceId: 'canvas',
+        instanceIds: ['canvas', 'preview', 'gallery:center', 'workflow:center'],
+        sizePx: 0,
+      }),
+      left: createRegion({ activeInstanceId: 'generate', instanceIds: ['generate', 'workflow'], sizePx: 450 }),
+      right: createRegion({
+        activeInstanceId: 'layers',
+        instanceIds: ['layers', 'gallery', 'queue', 'preview', 'diagnostics', 'project'],
+        sizePx: 450,
+      }),
+    },
+  }),
+  createPreset({
+    centerViewId: 'gallery',
+    id: 'gallery',
+    label: 'Gallery',
+    panels: { isBottomOpen: false, isLeftOpen: true, isRightOpen: true },
+    widgetRegions: {
+      bottom: createRegion({
+        activeInstanceId: 'gallery:bottom',
+        instanceIds: defaultBottomInstanceIds,
+        isCollapsed: true,
+        sizePx: 180,
+      }),
+      center: createRegion({
+        activeInstanceId: 'gallery:center',
+        instanceIds: ['gallery:center', 'preview', 'canvas', 'workflow:center'],
+        sizePx: 0,
+      }),
+      left: createRegion({
+        activeInstanceId: 'generate',
+        instanceIds: ['generate', 'workflow', 'gallery'],
+        isCollapsed: true,
+        sizePx: 450,
+      }),
+      right: createRegion({
+        activeInstanceId: 'preview',
+        instanceIds: ['preview', 'gallery', 'queue', 'layers', 'diagnostics', 'project'],
+        sizePx: 450,
+      }),
+    },
+  }),
+];
+
+export const defaultLayoutPreset = layoutPresets[0];
+
+export const getLayoutPreset = (presetId: string) =>
+  layoutPresets.find((preset) => preset.id === presetId) ?? defaultLayoutPreset;
diff --git a/invokeai/frontend/webv2/src/workbench/models/ModelInstallRuntime.tsx b/invokeai/frontend/webv2/src/workbench/models/ModelInstallRuntime.tsx
new file mode 100644
index 00000000000..35e11d40089
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/ModelInstallRuntime.tsx
@@ -0,0 +1,39 @@
+import { getConnectionStatus, subscribeConnection } from '@workbench/backend/connectionStore';
+import { socketHub } from '@workbench/backend/socketHub';
+import { useEffect } from 'react';
+
+import { handleModelInstallSocketEvent, MODEL_INSTALL_SOCKET_EVENTS, refreshInstalls } from './installsStore';
+import { refreshModels } from './modelsStore';
+import { useInstallOutcomeToasts } from './useInstallOutcomeToasts';
+
+/** Admin model-manager runtime: install socket events, reconnect refresh, and outcome toasts. */
+export const ModelInstallRuntime = () => {
+  useEffect(() => {
+    const detachers = MODEL_INSTALL_SOCKET_EVENTS.map((event) =>
+      socketHub.on(event, (payload) => handleModelInstallSocketEvent(event, payload))
+    );
+
+    return () => {
+      for (const detach of detachers) {
+        detach();
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    const refreshOnConnect = () => {
+      if (getConnectionStatus().status === 'connected') {
+        void refreshModels();
+        void refreshInstalls();
+      }
+    };
+
+    refreshOnConnect();
+
+    return subscribeConnection(refreshOnConnect);
+  }, []);
+
+  useInstallOutcomeToasts();
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/models/api.test.ts b/invokeai/frontend/webv2/src/workbench/models/api.test.ts
new file mode 100644
index 00000000000..adde067b3df
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/api.test.ts
@@ -0,0 +1,39 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  apiFetchJson: vi.fn(),
+}));
+
+vi.mock('../backend/http', () => ({
+  apiFetch: vi.fn(),
+  apiFetchJson: mocks.apiFetchJson,
+  buildApiUrl: (path: string) => path,
+}));
+
+describe('installModel', () => {
+  beforeEach(() => {
+    mocks.apiFetchJson.mockReset();
+    mocks.apiFetchJson.mockResolvedValue({
+      id: 1,
+      source: 'https://example.test/model.safetensors',
+      status: 'waiting',
+    });
+  });
+
+  it('sends remote source credentials in a header instead of the URL', async () => {
+    const { installModel } = await import('./api');
+
+    await installModel({
+      accessToken: 'secret-token',
+      config: { name: 'Model' },
+      source: 'https://example.test/model',
+    });
+
+    const [url, init] = mocks.apiFetchJson.mock.calls[0] as [string, RequestInit];
+
+    expect(url).toBe('/api/v2/models/install?source=https%3A%2F%2Fexample.test%2Fmodel');
+    expect(url).not.toContain('secret-token');
+    expect(init.headers).toEqual({ 'X-Model-Source-Access-Token': 'secret-token' });
+    expect(JSON.parse(init.body as string)).toEqual({ name: 'Model' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/models/api.ts b/invokeai/frontend/webv2/src/workbench/models/api.ts
new file mode 100644
index 00000000000..f3cb4770661
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/api.ts
@@ -0,0 +1,219 @@
+import { apiFetch, apiFetchJson, buildApiUrl } from '@workbench/backend/http';
+
+import type {
+  BulkDeleteModelsResponse,
+  DeleteOrphanedModelsResponse,
+  FoundModel,
+  HFTokenStatus,
+  HuggingFaceModels,
+  ModelConfig,
+  ModelInstallJob,
+  ModelRecordChanges,
+  OrphanedModelInfo,
+  StarterModelResponse,
+} from './types';
+
+/** REST client for the backend model manager (`/api/v2/models`). */
+
+const MODELS_BASE = '/api/v2/models';
+
+export const listModels = async (): Promise<ModelConfig[]> => {
+  const body = await apiFetchJson<{ models?: ModelConfig[] }>(`${MODELS_BASE}/`);
+
+  return body.models ?? [];
+};
+
+/** Models whose database record points at a file that no longer exists. */
+export const listMissingModels = async (): Promise<ModelConfig[]> => {
+  const body = await apiFetchJson<{ models?: ModelConfig[] }>(`${MODELS_BASE}/missing`);
+
+  return body.models ?? [];
+};
+
+/** Absolute server path of the models directory; relative model `path`s resolve against it. */
+export const getModelsDir = (): Promise<string> => apiFetchJson<string>(`${MODELS_BASE}/models_dir`);
+
+export const getModel = (key: string): Promise<ModelConfig> =>
+  apiFetchJson<ModelConfig>(`${MODELS_BASE}/i/${encodeURIComponent(key)}`);
+
+export const updateModel = (key: string, changes: ModelRecordChanges): Promise<ModelConfig> =>
+  apiFetchJson<ModelConfig>(`${MODELS_BASE}/i/${encodeURIComponent(key)}`, {
+    body: JSON.stringify(changes),
+    method: 'PATCH',
+  });
+
+export const deleteModel = async (key: string): Promise<void> => {
+  await apiFetch(`${MODELS_BASE}/i/${encodeURIComponent(key)}`, { method: 'DELETE' });
+};
+
+export const bulkDeleteModels = (keys: string[]): Promise<BulkDeleteModelsResponse> =>
+  apiFetchJson<BulkDeleteModelsResponse>(`${MODELS_BASE}/i/bulk_delete`, {
+    body: JSON.stringify({ keys }),
+    headers: { 'Content-Type': 'application/json' },
+    method: 'POST',
+  });
+
+/** Re-probe the model files to refresh auto-detected base/type/format. */
+export const reidentifyModel = (key: string): Promise<ModelConfig> =>
+  apiFetchJson<ModelConfig>(`${MODELS_BASE}/i/${encodeURIComponent(key)}/reidentify`, { method: 'POST' });
+
+export const convertModelToDiffusers = (key: string): Promise<ModelConfig> =>
+  apiFetchJson<ModelConfig>(`${MODELS_BASE}/convert/${encodeURIComponent(key)}`, { method: 'PUT' });
+
+/** Stable URL for a model's cover image; cache-busted via updated marker. */
+export const getModelImageUrl = (key: string, cacheKey?: string): string =>
+  buildApiUrl(
+    `${MODELS_BASE}/i/${encodeURIComponent(key)}/image${cacheKey ? `?t=${encodeURIComponent(cacheKey)}` : ''}`
+  );
+
+export const updateModelImage = async (key: string, image: Blob): Promise<void> => {
+  const formData = new FormData();
+
+  formData.append('image', image);
+  await apiFetch(`${MODELS_BASE}/i/${encodeURIComponent(key)}/image`, { body: formData, method: 'PATCH' });
+};
+
+export const deleteModelImage = async (key: string): Promise<void> => {
+  await apiFetch(`${MODELS_BASE}/i/${encodeURIComponent(key)}/image`, { method: 'DELETE' });
+};
+
+export interface InstallModelRequest {
+  source: string;
+  inplace?: boolean;
+  /** Access token for protected remote sources (e.g. Civitai API key). */
+  accessToken?: string;
+  /** Overrides for auto-probed config fields (name, base, type, ...). */
+  config?: ModelRecordChanges;
+}
+
+export const installModel = ({
+  accessToken,
+  config,
+  inplace,
+  source,
+}: InstallModelRequest): Promise<ModelInstallJob> => {
+  const params = new URLSearchParams({ source });
+  const headers: HeadersInit = {};
+
+  if (inplace !== undefined) {
+    params.set('inplace', String(inplace));
+  }
+
+  if (accessToken) {
+    headers['X-Model-Source-Access-Token'] = accessToken;
+  }
+
+  return apiFetchJson<ModelInstallJob>(`${MODELS_BASE}/install?${params.toString()}`, {
+    body: JSON.stringify(config ?? {}),
+    headers,
+    method: 'POST',
+  });
+};
+
+export const listModelInstalls = (): Promise<ModelInstallJob[]> =>
+  apiFetchJson<ModelInstallJob[]>(`${MODELS_BASE}/install`);
+
+export const cancelModelInstall = async (id: number): Promise<void> => {
+  await apiFetch(`${MODELS_BASE}/install/${id}`, { method: 'DELETE' });
+};
+
+export const pauseModelInstall = (id: number): Promise<ModelInstallJob> =>
+  apiFetchJson<ModelInstallJob>(`${MODELS_BASE}/install/${id}/pause`, { method: 'POST' });
+
+export const resumeModelInstall = (id: number): Promise<ModelInstallJob> =>
+  apiFetchJson<ModelInstallJob>(`${MODELS_BASE}/install/${id}/resume`, { method: 'POST' });
+
+export const restartFailedModelInstall = (id: number): Promise<ModelInstallJob> =>
+  apiFetchJson<ModelInstallJob>(`${MODELS_BASE}/install/${id}/restart_failed`, { method: 'POST' });
+
+/** Restart a single download part (by its file URL) of an install job. */
+export const restartModelInstallFile = (id: number, fileSource: string): Promise<ModelInstallJob> =>
+  apiFetchJson<ModelInstallJob>(`${MODELS_BASE}/install/${id}/restart_file`, {
+    body: JSON.stringify(fileSource),
+    method: 'POST',
+  });
+
+export const pruneCompletedModelInstalls = async (): Promise<void> => {
+  await apiFetch(`${MODELS_BASE}/install`, { method: 'DELETE' });
+};
+
+export const scanFolderForModels = (scanPath: string): Promise<FoundModel[]> =>
+  apiFetchJson<FoundModel[]>(`${MODELS_BASE}/scan_folder?scan_path=${encodeURIComponent(scanPath)}`);
+
+export const getHuggingFaceModels = (repo: string): Promise<HuggingFaceModels> =>
+  apiFetchJson<HuggingFaceModels>(`${MODELS_BASE}/hugging_face?hugging_face_repo=${encodeURIComponent(repo)}`);
+
+export const getStarterModels = (): Promise<StarterModelResponse> =>
+  apiFetchJson<StarterModelResponse>(`${MODELS_BASE}/starter_models`);
+
+export const getHFTokenStatus = (): Promise<HFTokenStatus> => apiFetchJson<HFTokenStatus>(`${MODELS_BASE}/hf_login`);
+
+export const setHFToken = (token: string): Promise<HFTokenStatus> =>
+  apiFetchJson<HFTokenStatus>(`${MODELS_BASE}/hf_login`, { body: JSON.stringify({ token }), method: 'POST' });
+
+export const resetHFToken = (): Promise<HFTokenStatus> =>
+  apiFetchJson<HFTokenStatus>(`${MODELS_BASE}/hf_login`, { method: 'DELETE' });
+
+export const getOrphanedModels = (): Promise<OrphanedModelInfo[]> =>
+  apiFetchJson<OrphanedModelInfo[]>(`${MODELS_BASE}/sync/orphaned`);
+
+export const deleteOrphanedModels = (paths: string[]): Promise<DeleteOrphanedModelsResponse> =>
+  apiFetchJson<DeleteOrphanedModelsResponse>(`${MODELS_BASE}/sync/orphaned`, {
+    body: JSON.stringify({ paths }),
+    headers: { 'Content-Type': 'application/json' },
+    method: 'DELETE',
+  });
+
+export const emptyModelCache = async (): Promise<void> => {
+  await apiFetch(`${MODELS_BASE}/empty_model_cache`, { method: 'POST' });
+};
+
+/** Model relationships: bidirectional "related model" links between configs. */
+
+const RELATIONSHIPS_BASE = '/api/v1/model_relationships';
+
+export const getRelatedModelKeys = (key: string): Promise<string[]> =>
+  apiFetchJson<string[]>(`${RELATIONSHIPS_BASE}/i/${encodeURIComponent(key)}`);
+
+export const addModelRelationship = async (modelKey1: string, modelKey2: string): Promise<void> => {
+  await apiFetch(`${RELATIONSHIPS_BASE}/`, {
+    body: JSON.stringify({ model_key_1: modelKey1, model_key_2: modelKey2 }),
+    headers: { 'Content-Type': 'application/json' },
+    method: 'POST',
+  });
+};
+
+export const removeModelRelationship = async (modelKey1: string, modelKey2: string): Promise<void> => {
+  await apiFetch(`${RELATIONSHIPS_BASE}/`, {
+    body: JSON.stringify({ model_key_1: modelKey1, model_key_2: modelKey2 }),
+    headers: { 'Content-Type': 'application/json' },
+    method: 'DELETE',
+  });
+};
+
+/** External image-provider credentials (OpenAI, Gemini, ...). */
+
+const EXTERNAL_PROVIDERS_BASE = '/api/v1/app/external_providers';
+
+export interface ExternalProviderConfig {
+  provider_id: string;
+  api_key_configured: boolean;
+  base_url: string | null;
+}
+
+export const getExternalProviderConfigs = (): Promise<ExternalProviderConfig[]> =>
+  apiFetchJson<ExternalProviderConfig[]>(`${EXTERNAL_PROVIDERS_BASE}/config`);
+
+export const setExternalProviderConfig = (
+  providerId: string,
+  config: { api_key?: string; base_url?: string | null }
+): Promise<ExternalProviderConfig> =>
+  apiFetchJson<ExternalProviderConfig>(`${EXTERNAL_PROVIDERS_BASE}/config/${encodeURIComponent(providerId)}`, {
+    body: JSON.stringify(config),
+    method: 'POST',
+  });
+
+export const resetExternalProviderConfig = (providerId: string): Promise<ExternalProviderConfig> =>
+  apiFetchJson<ExternalProviderConfig>(`${EXTERNAL_PROVIDERS_BASE}/config/${encodeURIComponent(providerId)}`, {
+    method: 'DELETE',
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/models/apiKeys.ts b/invokeai/frontend/webv2/src/workbench/models/apiKeys.ts
new file mode 100644
index 00000000000..ab7a5d66aee
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/apiKeys.ts
@@ -0,0 +1,51 @@
+import { getUserStorageScope } from '@workbench/auth/session';
+
+/**
+ * Client-side API key storage for remote model sources. The HuggingFace token
+ * lives on the backend (`/api/v2/models/hf_login`); the Civitai key has no
+ * backend home, so it is kept in this browser's localStorage and passed as the
+ * `access_token` query param when installing from a matching URL. The key is
+ * personal, so it is scoped per signed-in user on multi-user backends.
+ */
+
+const CIVITAI_KEY_BASE_STORAGE_KEY = 'invokeai-webv2-civitai-api-key';
+
+const getStorageKey = (): string => `${CIVITAI_KEY_BASE_STORAGE_KEY}${getUserStorageScope()}`;
+
+export const getCivitaiApiKey = (): string | null => {
+  try {
+    return window.localStorage.getItem(getStorageKey());
+  } catch {
+    return null;
+  }
+};
+
+export const setCivitaiApiKey = (key: string): void => {
+  try {
+    window.localStorage.setItem(getStorageKey(), key);
+  } catch {
+    // Storage unavailable (private mode/quota) — the key just is not persisted.
+  }
+};
+
+export const clearCivitaiApiKey = (): void => {
+  try {
+    window.localStorage.removeItem(getStorageKey());
+  } catch {
+    // Ignore: nothing to clear if storage is unavailable.
+  }
+};
+
+export const isCivitaiUrl = (source: string): boolean => {
+  try {
+    const host = new URL(source).hostname;
+
+    return host === 'civitai.com' || host.endsWith('.civitai.com');
+  } catch {
+    return false;
+  }
+};
+
+/** The access token to use for a given install source, if any is saved. */
+export const getAccessTokenForSource = (source: string): string | undefined =>
+  isCivitaiUrl(source) ? (getCivitaiApiKey() ?? undefined) : undefined;
diff --git a/invokeai/frontend/webv2/src/workbench/models/baseIdentity.test.ts b/invokeai/frontend/webv2/src/workbench/models/baseIdentity.test.ts
new file mode 100644
index 00000000000..e67c588cf18
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/baseIdentity.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ModelBase, ModelConfig } from './types';
+
+import {
+  getModelBaseColorPalette,
+  getModelBaseInfo,
+  getModelBaseLabel,
+  isConvertibleToDiffusers,
+  KNOWN_MODEL_BASES,
+  MODEL_BASES,
+} from './baseIdentity';
+
+const createModel = (overrides: Partial<ModelConfig>): ModelConfig => ({
+  base: 'sdxl',
+  file_size: 1024,
+  format: 'checkpoint',
+  hash: 'hash',
+  key: 'key',
+  name: 'Model',
+  path: '/models/model.safetensors',
+  source: '/models/model.safetensors',
+  source_type: 'path',
+  type: 'main',
+  ...overrides,
+});
+
+describe('MODEL_BASES', () => {
+  it('matches known base labels, colors, and conversion support', () => {
+    expect(getModelBaseInfo('sd-1')).toMatchObject({
+      label: 'SD 1.x',
+      colorPalette: 'green',
+      supportsDiffusersConversion: true,
+    });
+    expect(getModelBaseInfo('sd-2')).toMatchObject({
+      label: 'SD 2.x',
+      colorPalette: 'teal',
+      supportsDiffusersConversion: true,
+    });
+    expect(getModelBaseInfo('sdxl')).toMatchObject({
+      label: 'SDXL',
+      colorPalette: 'blue',
+      supportsDiffusersConversion: true,
+    });
+    expect(getModelBaseInfo('flux2')).toMatchObject({ label: 'FLUX.2', colorPalette: 'cyan' });
+    expect(getModelBaseInfo('qwen-image')).toMatchObject({ label: 'Qwen Image', colorPalette: 'cyan' });
+    expect(isConvertibleToDiffusers(createModel({ base: 'sdxl', format: 'checkpoint', type: 'main' }))).toBe(true);
+    expect(isConvertibleToDiffusers(createModel({ base: 'flux', format: 'checkpoint', type: 'main' }))).toBe(false);
+  });
+
+  it('falls back safely for unknown bases', () => {
+    const base = 'made-up' as ModelBase;
+
+    expect(getModelBaseInfo(base)).toEqual({ base, label: 'Made Up', colorPalette: 'gray' });
+    expect(getModelBaseLabel(base)).toBe('Made Up');
+    expect(getModelBaseColorPalette(base)).toBe('gray');
+  });
+
+  it('does not include generation fields', () => {
+    for (const info of Object.values(MODEL_BASES)) {
+      expect(info).not.toHaveProperty('defaults');
+      expect(info).not.toHaveProperty('schedulerSet');
+      expect(info).not.toHaveProperty('negativePrompt');
+      expect(info).not.toHaveProperty('ui');
+    }
+  });
+
+  it('covers all known ModelBase literals', () => {
+    expect(KNOWN_MODEL_BASES).toEqual([
+      'sd-1',
+      'sd-2',
+      'sdxl',
+      'sdxl-refiner',
+      'sd-3',
+      'flux',
+      'flux2',
+      'cogview4',
+      'qwen-image',
+      'z-image',
+      'anima',
+      'any',
+      'external',
+      'unknown',
+    ]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/models/baseIdentity.ts b/invokeai/frontend/webv2/src/workbench/models/baseIdentity.ts
new file mode 100644
index 00000000000..d21ab9b71ef
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/baseIdentity.ts
@@ -0,0 +1,116 @@
+import type { ColorPalette } from '@chakra-ui/react';
+
+import type { ModelBase, ModelConfig } from './types';
+
+// Model-base identity registry: labels, colors, and scalar display facts only.
+// Generation behavior keyed by base lives in @workbench/generation/baseGenerationPolicies.
+
+export interface ModelBaseInfo {
+  base: ModelBase;
+  label: string;
+  colorPalette: ColorPalette;
+  description?: string;
+  supportsDiffusersConversion?: boolean;
+}
+
+export const MODEL_BASES = {
+  'sd-1': {
+    base: 'sd-1',
+    label: 'SD 1.x',
+    colorPalette: 'green',
+    supportsDiffusersConversion: true,
+  },
+  'sd-2': {
+    base: 'sd-2',
+    label: 'SD 2.x',
+    colorPalette: 'teal',
+    supportsDiffusersConversion: true,
+  },
+  sdxl: {
+    base: 'sdxl',
+    label: 'SDXL',
+    colorPalette: 'blue',
+    supportsDiffusersConversion: true,
+  },
+  'sdxl-refiner': {
+    base: 'sdxl-refiner',
+    label: 'SDXL Refiner',
+    colorPalette: 'blue',
+  },
+  'sd-3': {
+    base: 'sd-3',
+    label: 'SD 3.x',
+    colorPalette: 'purple',
+  },
+  flux: {
+    base: 'flux',
+    label: 'FLUX',
+    colorPalette: 'teal',
+  },
+  flux2: {
+    base: 'flux2',
+    label: 'FLUX.2',
+    colorPalette: 'cyan',
+  },
+  cogview4: {
+    base: 'cogview4',
+    label: 'CogView4',
+    colorPalette: 'red',
+  },
+  'qwen-image': {
+    base: 'qwen-image',
+    label: 'Qwen Image',
+    colorPalette: 'cyan',
+  },
+  'z-image': {
+    base: 'z-image',
+    label: 'Z-Image',
+    colorPalette: 'orange',
+  },
+  anima: {
+    base: 'anima',
+    label: 'Anima',
+    colorPalette: 'pink',
+  },
+  any: {
+    base: 'any',
+    label: 'Any',
+    colorPalette: 'gray',
+  },
+  external: {
+    base: 'external',
+    label: 'External',
+    colorPalette: 'gray',
+  },
+  unknown: {
+    base: 'unknown',
+    label: 'Unknown',
+    colorPalette: 'gray',
+  },
+} satisfies Record<string, ModelBaseInfo>;
+
+export type KnownModelBase = keyof typeof MODEL_BASES;
+
+export const KNOWN_MODEL_BASES = Object.keys(MODEL_BASES) as KnownModelBase[];
+
+const toTitleCase = (value: string): string =>
+  value.replaceAll(/[_-]+/g, ' ').replace(/\w\S*/g, (word) => word[0].toUpperCase() + word.slice(1));
+
+// Unknown bases are display-safe here, but generation support is decided in baseGenerationPolicies.ts.
+export const getModelBaseInfo = (base: ModelBase): ModelBaseInfo =>
+  (MODEL_BASES as Record<string, ModelBaseInfo>)[base] ?? {
+    base,
+    label: toTitleCase(base),
+    colorPalette: 'gray',
+  };
+
+export const getModelBaseLabel = (base: ModelBase): string => getModelBaseInfo(base).label;
+
+export const getModelBaseColorPalette = (base: ModelBase): string => getModelBaseInfo(base).colorPalette;
+
+export const isKnownModelBase = (base: ModelBase): base is KnownModelBase => base in MODEL_BASES;
+
+export const isConvertibleToDiffusers = (model: Pick<ModelConfig, 'base' | 'format' | 'type'>): boolean =>
+  model.format === 'checkpoint' &&
+  model.type === 'main' &&
+  Boolean(getModelBaseInfo(model.base).supportsDiffusersConversion);
diff --git a/invokeai/frontend/webv2/src/workbench/models/components/ModelSelect.tsx b/invokeai/frontend/webv2/src/workbench/models/components/ModelSelect.tsx
new file mode 100644
index 00000000000..2fe22b3742e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/components/ModelSelect.tsx
@@ -0,0 +1,488 @@
+/* eslint-disable react/react-compiler, react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type { ModelConfig, ModelTaxonomyType } from '@workbench/models/types';
+
+import {
+  Badge,
+  Box,
+  HStack,
+  Icon,
+  Input,
+  InputGroup,
+  Popover,
+  Portal,
+  ScrollArea,
+  Spacer,
+  Stack,
+  Text,
+} from '@chakra-ui/react';
+import { Link } from '@tanstack/react-router';
+import { Button, CloseButton, IconButton, Tooltip } from '@workbench/components/ui';
+import { getModelBaseColorPalette, getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { getModelPickerGroups } from '@workbench/models/library';
+import { ensureModelsLoaded, useModelsSelector } from '@workbench/models/modelsStore';
+import { formatBytes, getModelTypePluralLabel } from '@workbench/models/taxonomy';
+import { useWorkbenchPreferenceSelector } from '@workbench/settings/store';
+import { BoxIcon, CheckIcon, ChevronDownIcon, RotateCcwIcon, SearchIcon, XIcon } from 'lucide-react';
+import { useDeferredValue, useEffect, useMemo, useRef, useState } from 'react';
+
+const EMPTY_BASES: ReadonlySet<string> = new Set();
+
+/**
+ * Universal single-model picker: a button-triggered searchable list over the
+ * installed library. Scope it with `modelTypes` — one type for dedicated
+ * pickers (a LoRA picker, a main-model picker) or several for cross-type
+ * pickers, in which case results are grouped by type.
+ */
+export const ModelSelect = ({
+  className,
+  disabled,
+  excludeKeys,
+  filter,
+  id,
+  invalid,
+  isClearable = false,
+  modelTypes,
+  onChange,
+  placeholder,
+  showManagerButton = true,
+  size = 'sm',
+  value,
+}: {
+  className?: string;
+  disabled?: boolean;
+  /** Hide specific models (e.g. the current model and already-linked ones). */
+  excludeKeys?: ReadonlySet<string>;
+  /** Extra predicate, e.g. base-architecture compatibility. */
+  filter?: (model: ModelConfig) => boolean;
+  id?: string;
+  invalid?: boolean;
+  isClearable?: boolean;
+  /** The model types this instance searches. */
+  modelTypes: ModelTaxonomyType[];
+  onChange: (model: ModelConfig | null) => void;
+  placeholder?: string;
+  /** Show the shortcut to the model manager. Hide it inside the manager itself. */
+  showManagerButton?: boolean;
+  size?: 'xs' | 'sm' | 'md';
+  /** Selected model key, or null. */
+  value: string | null;
+}) => {
+  const enableModelDescriptions = useWorkbenchPreferenceSelector((preferences) => preferences.enableModelDescriptions);
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const [isOpen, setIsOpen] = useState(false);
+  const [searchTerm, setSearchTerm] = useState('');
+  const [selectedBases, setSelectedBases] = useState<ReadonlySet<string>>(EMPTY_BASES);
+  const deferredSearchTerm = useDeferredValue(searchTerm);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const optionRefs = useRef<HTMLElement[]>([]);
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  const { availableBases, candidates, groups } = useMemo(
+    () =>
+      isOpen
+        ? getModelPickerGroups(models, {
+            baseFilter: selectedBases,
+            excludeKeys,
+            filter,
+            modelTypes,
+            searchTerm: deferredSearchTerm,
+          })
+        : { availableBases: [], candidates: [], groups: [] },
+    [deferredSearchTerm, excludeKeys, filter, isOpen, modelTypes, models, selectedBases]
+  );
+
+  const selectedModel = useMemo(() => models.find((model) => model.key === value) ?? null, [models, value]);
+
+  const scopeLabel =
+    modelTypes.length === 1 ? getModelTypePluralLabel(modelTypes[0] ?? 'main').toLowerCase() : 'models';
+  const closeAndReset = () => {
+    setIsOpen(false);
+    setSearchTerm('');
+    setSelectedBases(EMPTY_BASES);
+  };
+
+  useEffect(() => {
+    if (disabled) {
+      closeAndReset();
+    }
+  }, [disabled]);
+
+  const toggleBase = (base: string) => {
+    setSelectedBases((prev) => {
+      const next = new Set(prev);
+
+      if (next.has(base)) {
+        next.delete(base);
+      } else {
+        next.add(base);
+      }
+
+      return next;
+    });
+  };
+  const resetBases = () => {
+    setSelectedBases(EMPTY_BASES);
+  };
+  const selectModel = (model: ModelConfig) => {
+    onChange(model);
+    closeAndReset();
+  };
+  const clearSelection = () => {
+    onChange(null);
+    closeAndReset();
+  };
+  const focusSearchInput = () => {
+    window.requestAnimationFrame(() => searchInputRef.current?.focus());
+  };
+  const focusOption = (edge: 'first' | 'last') => {
+    const options = optionRefs.current.filter(Boolean);
+
+    options[edge === 'first' ? 0 : options.length - 1]?.focus();
+  };
+  const focusAdjacentOption = (currentIndex: number, direction: 1 | -1) => {
+    const options = optionRefs.current.filter(Boolean);
+    const nextIndex = currentIndex + direction;
+
+    if (nextIndex < 0) {
+      searchInputRef.current?.focus();
+      return;
+    }
+
+    options[nextIndex]?.focus();
+  };
+
+  optionRefs.current = [];
+  let optionIndex = 0;
+  const canClear = isClearable && Boolean(value);
+
+  return (
+    <Box className={className} minW="0" w="full">
+      <Popover.Root
+        ids={id ? { trigger: id } : undefined}
+        open={isOpen}
+        positioning={{
+          fitViewport: true,
+          gutter: 4,
+          hideWhenDetached: true,
+          overflowPadding: 8,
+          placement: 'bottom-start',
+          sameWidth: true,
+          strategy: 'fixed',
+        }}
+        onOpenChange={(event) => {
+          if (disabled) {
+            setIsOpen(false);
+            return;
+          }
+
+          if (event.open) {
+            setSearchTerm('');
+            setSelectedBases(EMPTY_BASES);
+            setIsOpen(true);
+            focusSearchInput();
+            return;
+          }
+
+          closeAndReset();
+        }}
+      >
+        <Box minW="0" position="relative" w="full">
+          <Popover.Trigger asChild>
+            <Button
+              aria-invalid={invalid ? true : undefined}
+              aria-haspopup="listbox"
+              className={className}
+              colorPalette={invalid ? 'red' : isOpen ? 'accent' : 'bg'}
+              disabled={disabled}
+              justifyContent="space-between"
+              minW="0"
+              pe={canClear ? '7' : '2'}
+              ps="2"
+              size={size}
+              variant="outline"
+              w="full"
+            >
+              {selectedModel ? (
+                <ModelButtonContent model={selectedModel} />
+              ) : (
+                <Text as="span" color="fg.subtle" fontSize="xs" minW="0" truncate>
+                  {placeholder ?? `Select ${scopeLabel}…`}
+                </Text>
+              )}
+              {canClear ? null : <Icon as={ChevronDownIcon} boxSize="3" flexShrink={0} />}
+            </Button>
+          </Popover.Trigger>
+          {canClear ? (
+            <CloseButton
+              aria-label="Clear selected model"
+              disabled={disabled}
+              insetEnd="1"
+              position="absolute"
+              size="2xs"
+              top="50%"
+              transform="translateY(-50%)"
+              zIndex="1"
+              onClick={(event) => {
+                event.stopPropagation();
+                clearSelection();
+              }}
+              onMouseDown={(event) => {
+                event.stopPropagation();
+              }}
+            >
+              <XIcon />
+            </CloseButton>
+          ) : null}
+        </Box>
+        <Portal>
+          <Popover.Positioner>
+            <Popover.Content
+              bg="bg.muted"
+              borderColor="border.emphasized"
+              borderRadius="lg"
+              borderWidth="1px"
+              boxShadow="lg"
+              color="fg"
+              maxH="min(18rem, var(--available-height))"
+              minW="min(18rem, calc(100vw - 1rem))"
+              overflow="hidden"
+              p="0"
+            >
+              <Stack gap="2" p="2">
+                <HStack gap="1">
+                  <InputGroup flex="1" minW="0" startElement={<Icon as={SearchIcon} size="xs" />}>
+                    <Input
+                      ref={searchInputRef}
+                      aria-label={`Search ${scopeLabel}`}
+                      placeholder={`Search ${scopeLabel}...`}
+                      size="xs"
+                      value={searchTerm}
+                      onChange={(event) => setSearchTerm(event.currentTarget.value)}
+                      onKeyDown={(event) => {
+                        event.stopPropagation();
+
+                        if (event.key === 'Escape') {
+                          event.preventDefault();
+                          closeAndReset();
+                          return;
+                        }
+
+                        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                          event.preventDefault();
+                          focusOption(event.key === 'ArrowDown' ? 'first' : 'last');
+                        }
+                      }}
+                    />
+                  </InputGroup>
+                  {showManagerButton ? <ModelManagerLinkButton /> : null}
+                </HStack>
+                {availableBases.length >= 2 ? (
+                  <HStack alignItems="center" flexWrap="wrap" gap="1">
+                    {availableBases.map((base) => (
+                      <BaseChip key={base} base={base} isSelected={selectedBases.has(base)} onToggle={toggleBase} />
+                    ))}
+                    <Spacer />
+                    <IconButton
+                      aria-label="Reset base filters"
+                      flexShrink={0}
+                      opacity={selectedBases.size === 0 ? 0.5 : undefined}
+                      pointerEvents={selectedBases.size === 0 ? 'none' : undefined}
+                      size="2xs"
+                      variant="ghost"
+                      onClick={resetBases}
+                    >
+                      <Icon as={RotateCcwIcon} boxSize="3" />
+                    </IconButton>
+                  </HStack>
+                ) : null}
+              </Stack>
+              <HStack borderTopWidth="1px" borderColor="border.subtle" />
+              <ScrollArea.Root maxH="14rem" size="xs" variant="hover" w="full">
+                <ScrollArea.Viewport maxH="inherit" w="full">
+                  <ScrollArea.Content py="1" role="listbox" aria-label={`Available ${scopeLabel}`}>
+                    {groups.length === 0 ? (
+                      <Text color="fg.subtle" fontSize="2xs" p="2">
+                        {candidates.length === 0
+                          ? `No compatible ${scopeLabel} installed.`
+                          : !deferredSearchTerm.trim() && selectedBases.size > 0
+                            ? `No ${scopeLabel} match the selected bases.`
+                            : `No ${scopeLabel} match your search.`}
+                      </Text>
+                    ) : null}
+                    {groups.map((group) => (
+                      <Stack key={group.type} gap="0">
+                        {modelTypes.length > 1 ? (
+                          <Text
+                            color="fg.subtle"
+                            fontSize="2xs"
+                            fontWeight="600"
+                            letterSpacing="0.02em"
+                            px="2"
+                            py="1"
+                            textTransform="uppercase"
+                          >
+                            {group.label}
+                          </Text>
+                        ) : null}
+                        {group.models.map((model) => {
+                          const currentOptionIndex = optionIndex;
+                          optionIndex += 1;
+
+                          return (
+                            <Button
+                              key={model.key}
+                              ref={(element) => {
+                                if (element) {
+                                  optionRefs.current[currentOptionIndex] = element;
+                                }
+                              }}
+                              aria-selected={value === model.key}
+                              borderRadius="0"
+                              gap="2"
+                              justifyContent="start"
+                              truncate
+                              role="option"
+                              size="2xs"
+                              variant="ghost"
+                              w="full"
+                              _highlighted={{ bg: 'bg.subtle' }}
+                              _focusVisible={{
+                                outline: '2px solid',
+                                outlineColor: 'accent.solid',
+                                outlineOffset: '-2px',
+                              }}
+                              onClick={() => selectModel(model)}
+                              onKeyDown={(event) => {
+                                if (event.key === 'Escape') {
+                                  event.preventDefault();
+                                  closeAndReset();
+                                  return;
+                                }
+
+                                if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                                  event.preventDefault();
+                                  focusAdjacentOption(currentOptionIndex, event.key === 'ArrowDown' ? 1 : -1);
+                                }
+                              }}
+                              transitionDuration="faster"
+                            >
+                              <Icon
+                                as={CheckIcon}
+                                aria-hidden
+                                boxSize="3"
+                                color="accent.solid"
+                                flexShrink={0}
+                                opacity={value === model.key ? 1 : 0}
+                              />
+                              <ModelOptionContent enableDescription={enableModelDescriptions} model={model} />
+                            </Button>
+                          );
+                        })}
+                      </Stack>
+                    ))}
+                  </ScrollArea.Content>
+                </ScrollArea.Viewport>
+                <ScrollArea.Scrollbar>
+                  <ScrollArea.Thumb />
+                </ScrollArea.Scrollbar>
+              </ScrollArea.Root>
+            </Popover.Content>
+          </Popover.Positioner>
+        </Portal>
+      </Popover.Root>
+    </Box>
+  );
+};
+
+const ModelManagerLinkButton = () => (
+  <Tooltip content="Manage models" showArrow>
+    <IconButton aria-label="Manage models" asChild flexShrink={0} size="xs" variant="ghost">
+      <Link to="/models">
+        <BoxIcon />
+      </Link>
+    </IconButton>
+  </Tooltip>
+);
+
+const BaseChip = ({
+  base,
+  isSelected,
+  onToggle,
+}: {
+  base: string;
+  isSelected: boolean;
+  onToggle: (base: string) => void;
+}) => (
+  <Badge
+    aria-pressed={isSelected}
+    colorPalette={getModelBaseColorPalette(base)}
+    cursor="pointer"
+    fontSize="2xs"
+    role="button"
+    size="sm"
+    tabIndex={0}
+    userSelect="none"
+    variant={isSelected ? 'solid' : 'surface'}
+    onClick={(event) => {
+      event.stopPropagation();
+      onToggle(base);
+    }}
+    onKeyDown={(event) => {
+      event.stopPropagation();
+
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        onToggle(base);
+      }
+    }}
+  >
+    {getModelBaseLabel(base)}
+  </Badge>
+);
+
+const ModelButtonContent = ({ model }: { model: ModelConfig }) => (
+  <HStack as="span" flex="1" gap="2" minW="0">
+    <Text as="span" fontSize="xs" minW="0" truncate>
+      {model.name}
+    </Text>
+    <Badge
+      colorPalette={getModelBaseColorPalette(model.base)}
+      flexShrink={0}
+      fontSize="2xs"
+      size="sm"
+      variant="surface"
+    >
+      {getModelBaseLabel(model.base)}
+    </Badge>
+  </HStack>
+);
+
+const ModelOptionContent = ({ enableDescription, model }: { enableDescription: boolean; model: ModelConfig }) => (
+  <HStack flex="1" gap="2" minW="0" textAlign="left" w="full">
+    <Stack flex="1" gap="0" minW="0">
+      <Text fontSize="xs" minW="0" truncate>
+        {model.name}
+      </Text>
+      {enableDescription && model.description ? (
+        <Text color="fg.subtle" fontSize="2xs" truncate>
+          {model.description}
+        </Text>
+      ) : null}
+    </Stack>
+    <Text color="fg.subtle" flexShrink={0} fontSize="2xs">
+      {formatBytes(model.file_size)}
+    </Text>
+    <Badge
+      colorPalette={getModelBaseColorPalette(model.base)}
+      flexShrink={0}
+      fontSize="2xs"
+      size="xs"
+      variant="surface"
+    >
+      {getModelBaseLabel(model.base)}
+    </Badge>
+  </HStack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/models/components/index.ts b/invokeai/frontend/webv2/src/workbench/models/components/index.ts
new file mode 100644
index 00000000000..6b8e8f883e7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/components/index.ts
@@ -0,0 +1 @@
+export { ModelSelect } from './ModelSelect';
diff --git a/invokeai/frontend/webv2/src/workbench/models/installsStore.ts b/invokeai/frontend/webv2/src/workbench/models/installsStore.ts
new file mode 100644
index 00000000000..581d839f603
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/installsStore.ts
@@ -0,0 +1,249 @@
+import { createExternalStore, createKeyedTransientStore } from '@workbench/externalStore';
+
+import type { ModelInstallJob, ModelInstallStatus } from './types';
+
+import { listModelInstalls } from './api';
+import { refreshModels } from './modelsStore';
+import { refreshStartersIfLoaded } from './startersStore';
+
+/**
+ * Live store for model install jobs. The job list itself is REST-owned
+ * (`/api/v2/models/install`) and refreshed on lifecycle socket events;
+ * download progress is high-frequency transient data that bypasses the list
+ * (and the workbench reducer) entirely — each queue row subscribes to its own
+ * job id and only re-renders when that job's bytes move. This mirrors the
+ * generation `progressStore` pattern.
+ */
+
+export interface InstallsSnapshot {
+  jobs: ModelInstallJob[];
+  status: 'idle' | 'loading' | 'loaded' | 'error';
+  error: string | null;
+}
+
+export interface InstallDownloadProgress {
+  bytes: number;
+  totalBytes: number;
+}
+
+/** A just-settled install, surfaced so the UI can toast success/failure. */
+export interface InstallOutcome {
+  id: number;
+  jobId: number;
+  kind: 'completed' | 'error' | 'cancelled';
+  modelName: string | null;
+  source: string;
+  error: string | null;
+}
+
+const REFRESH_COALESCE_MS = 250;
+const OUTCOME_LIMIT = 16;
+
+const store = createExternalStore<InstallsSnapshot>({ error: null, jobs: [], status: 'idle' });
+const outcomesStore = createExternalStore<{ outcomes: InstallOutcome[] }>({ outcomes: [] });
+let nextOutcomeId = 1;
+
+const progressByJobId = createKeyedTransientStore<number, InstallDownloadProgress>();
+
+let inflightRefresh: Promise<void> | null = null;
+let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+export const refreshInstalls = (): Promise<void> => {
+  if (inflightRefresh) {
+    return inflightRefresh;
+  }
+
+  store.patchSnapshot({ status: store.getSnapshot().status === 'loaded' ? 'loaded' : 'loading' });
+
+  inflightRefresh = listModelInstalls()
+    .then((jobs) => {
+      const activeJobIds = new Set(jobs.map((job) => job.id));
+
+      for (const [jobId] of progressByJobId.entries()) {
+        if (!activeJobIds.has(jobId)) {
+          progressByJobId.delete(jobId);
+        }
+      }
+
+      store.patchSnapshot({ error: null, jobs, status: 'loaded' });
+    })
+    .catch((error: unknown) => {
+      store.patchSnapshot({
+        error: error instanceof Error ? error.message : 'Failed to load install queue.',
+        status: store.getSnapshot().jobs.length > 0 ? 'loaded' : 'error',
+      });
+    })
+    .finally(() => {
+      inflightRefresh = null;
+    });
+
+  return inflightRefresh;
+};
+
+export const ensureInstallsLoaded = (): void => {
+  if (store.getSnapshot().status === 'idle') {
+    void refreshInstalls();
+  }
+};
+
+const scheduleRefresh = (): void => {
+  if (refreshTimer !== null) {
+    return;
+  }
+
+  refreshTimer = setTimeout(() => {
+    refreshTimer = null;
+    void refreshInstalls();
+  }, REFRESH_COALESCE_MS);
+};
+
+/** Optimistically replace one job (e.g. after pause/resume API calls). */
+export const replaceInstallJob = (job: ModelInstallJob): void => {
+  store.patchSnapshot({
+    jobs: store.getSnapshot().jobs.map((existing) => (existing.id === job.id ? job : existing)),
+  });
+};
+
+/** Optimistically add a freshly created job so the queue updates instantly. */
+export const addInstallJob = (job: ModelInstallJob): void => {
+  if (store.getSnapshot().jobs.some((existing) => existing.id === job.id)) {
+    replaceInstallJob(job);
+    return;
+  }
+
+  store.patchSnapshot({ jobs: [job, ...store.getSnapshot().jobs], status: 'loaded' });
+};
+
+const recordOutcome = (outcome: Omit<InstallOutcome, 'id'>): void => {
+  outcomesStore.patchSnapshot({
+    outcomes: [{ ...outcome, id: nextOutcomeId }, ...outcomesStore.getSnapshot().outcomes].slice(0, OUTCOME_LIMIT),
+  });
+  nextOutcomeId += 1;
+};
+
+interface ModelInstallSocketPayload {
+  id: number;
+  bytes?: number;
+  total_bytes?: number;
+  source?: unknown;
+  error?: string | null;
+  error_type?: string | null;
+  config?: { name?: string } | null;
+}
+
+const describeSource = (source: unknown): string => {
+  if (typeof source === 'string') {
+    return source;
+  }
+
+  if (source && typeof source === 'object') {
+    const record = source as Record<string, unknown>;
+
+    for (const field of ['repo_id', 'url', 'path']) {
+      if (typeof record[field] === 'string') {
+        return record[field];
+      }
+    }
+  }
+
+  return 'model';
+};
+
+export const MODEL_INSTALL_SOCKET_EVENTS = [
+  'model_install_started',
+  'model_install_download_started',
+  'model_install_download_progress',
+  'model_install_downloads_complete',
+  'model_install_complete',
+  'model_install_error',
+  'model_install_cancelled',
+] as const;
+
+export type ModelInstallSocketEvent = (typeof MODEL_INSTALL_SOCKET_EVENTS)[number];
+
+/** Socket sink — wired into the backend socket by the queue coordinator. */
+export const handleModelInstallSocketEvent = (event: ModelInstallSocketEvent, payload: unknown): void => {
+  const data = payload as ModelInstallSocketPayload;
+
+  if (typeof data?.id !== 'number') {
+    return;
+  }
+
+  if (event === 'model_install_download_progress') {
+    progressByJobId.set(data.id, { bytes: data.bytes ?? 0, totalBytes: data.total_bytes ?? 0 });
+
+    const job = store.getSnapshot().jobs.find((candidate) => candidate.id === data.id);
+
+    if (!job) {
+      // The first progress tick may arrive for a job created in another
+      // client; make sure the row exists without refetching on every tick.
+      scheduleRefresh();
+    } else if (job.status === 'waiting') {
+      // Bytes are flowing, so the REST snapshot's `waiting` is stale. Patch
+      // locally so download controls (pause/cancel) appear immediately.
+      replaceInstallJob({ ...job, status: 'downloading' });
+    }
+
+    return;
+  }
+
+  if (event === 'model_install_complete') {
+    recordOutcome({
+      error: null,
+      jobId: data.id,
+      kind: 'completed',
+      modelName: data.config?.name ?? null,
+      source: describeSource(data.source),
+    });
+    void refreshModels();
+    refreshStartersIfLoaded();
+  } else if (event === 'model_install_error') {
+    recordOutcome({
+      error: data.error ?? data.error_type ?? 'Unknown install error.',
+      jobId: data.id,
+      kind: 'error',
+      modelName: null,
+      source: describeSource(data.source),
+    });
+  } else if (event === 'model_install_cancelled') {
+    recordOutcome({
+      error: null,
+      jobId: data.id,
+      kind: 'cancelled',
+      modelName: null,
+      source: describeSource(data.source),
+    });
+  }
+
+  scheduleRefresh();
+};
+
+const ACTIVE_STATUSES: ModelInstallStatus[] = ['waiting', 'downloading', 'downloads_done', 'running'];
+
+export const isActiveInstallStatus = (status: ModelInstallStatus): boolean => ACTIVE_STATUSES.includes(status);
+
+export const useInstallsSelector = store.useSelector;
+
+export const useInstallsSnapshot = (): InstallsSnapshot => store.useSnapshot();
+
+/**
+ * Source strings (URL, repo id, or path) of jobs currently in flight, cached
+ * per jobs-array so list rows can show an "installing" state by source.
+ */
+const areSetsEqual = <Value>(left: ReadonlySet<Value>, right: ReadonlySet<Value>): boolean =>
+  left.size === right.size && Array.from(left).every((value) => right.has(value));
+
+const getActiveInstallSources = (jobs: ModelInstallJob[]): ReadonlySet<string> =>
+  new Set(
+    jobs
+      .filter((job) => isActiveInstallStatus(job.status) || job.status === 'paused')
+      .map((job) => describeSource(job.source))
+  );
+
+export const useActiveInstallSources = (): ReadonlySet<string> =>
+  store.useSelector((snapshot) => getActiveInstallSources(snapshot.jobs), areSetsEqual);
+
+export const useInstallProgress = (jobId: number): InstallDownloadProgress | null =>
+  progressByJobId.useValue(jobId) ?? null;
+
+export const useInstallOutcomes = (): InstallOutcome[] => outcomesStore.useSelector((snapshot) => snapshot.outcomes);
diff --git a/invokeai/frontend/webv2/src/workbench/models/library.test.ts b/invokeai/frontend/webv2/src/workbench/models/library.test.ts
new file mode 100644
index 00000000000..97a8d1a6817
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/library.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ModelConfig } from './types';
+
+import {
+  collectBases,
+  collectBasesForDisplay,
+  collectTypes,
+  DEFAULT_LIBRARY_FILTERS,
+  filterModels,
+  flattenGroupsToRows,
+  getModelPickerGroups,
+  groupModelsByType,
+} from './library';
+
+const createModel = (overrides: Partial<ModelConfig>): ModelConfig => ({
+  base: 'sdxl',
+  file_size: 1024,
+  format: 'checkpoint',
+  hash: 'hash',
+  key: 'key',
+  name: 'Model',
+  path: '/models/model.safetensors',
+  source: '/models/model.safetensors',
+  source_type: 'path',
+  type: 'main',
+  ...overrides,
+});
+
+const library: ModelConfig[] = [
+  createModel({ base: 'sdxl', file_size: 300, key: 'a', name: 'Juggernaut XL', type: 'main' }),
+  createModel({ base: 'flux', file_size: 100, key: 'b', name: 'FLUX dev', type: 'main' }),
+  createModel({
+    base: 'sd-1',
+    file_size: 200,
+    key: 'c',
+    name: 'Detail Tweaker',
+    trigger_phrases: ['detail'],
+    type: 'lora',
+  }),
+  createModel({ base: 'any', file_size: 50, key: 'd', name: 'Some VAE', type: 'vae' }),
+];
+
+const NO_MISSING: ReadonlySet<string> = new Set();
+
+describe('filterModels', () => {
+  it('matches search terms against name, taxonomy, and trigger phrases', () => {
+    expect(
+      filterModels(library, { ...DEFAULT_LIBRARY_FILTERS, searchTerm: 'flux' }, NO_MISSING).map((m) => m.key)
+    ).toEqual(['b']);
+    expect(
+      filterModels(library, { ...DEFAULT_LIBRARY_FILTERS, searchTerm: 'detail' }, NO_MISSING).map((m) => m.key)
+    ).toEqual(['c']);
+  });
+
+  it('filters by type and base independently', () => {
+    expect(
+      filterModels(library, { ...DEFAULT_LIBRARY_FILTERS, typeFilter: 'lora' }, NO_MISSING).map((m) => m.key)
+    ).toEqual(['c']);
+    expect(
+      filterModels(library, { ...DEFAULT_LIBRARY_FILTERS, baseFilter: 'sdxl' }, NO_MISSING).map((m) => m.key)
+    ).toEqual(['a']);
+  });
+
+  it('filters to missing models only', () => {
+    const missing = new Set(['d']);
+
+    expect(filterModels(library, { ...DEFAULT_LIBRARY_FILTERS, missingOnly: true }, missing).map((m) => m.key)).toEqual(
+      ['d']
+    );
+  });
+
+  it('sorts by size descending', () => {
+    const sorted = filterModels(
+      library,
+      { ...DEFAULT_LIBRARY_FILTERS, sortDirection: 'desc', sortField: 'size' },
+      NO_MISSING
+    );
+
+    expect(sorted.map((m) => m.key)).toEqual(['a', 'c', 'b', 'd']);
+  });
+});
+
+describe('groupModelsByType', () => {
+  it('groups in canonical category order with headers flattened for virtualization', () => {
+    const groups = groupModelsByType(filterModels(library, DEFAULT_LIBRARY_FILTERS, NO_MISSING));
+
+    expect(groups.map((group) => group.type)).toEqual(['main', 'lora', 'vae']);
+
+    const rows = flattenGroupsToRows(groups);
+
+    expect(rows[0]).toMatchObject({ kind: 'header' });
+    expect(rows).toHaveLength(groups.length + library.length);
+  });
+});
+
+describe('getModelPickerGroups', () => {
+  it('filters by allowed type, exclusions, custom predicate, and multi-term search', () => {
+    const result = getModelPickerGroups(library, {
+      excludeKeys: new Set(['b']),
+      filter: (model) => model.base !== 'any',
+      modelTypes: ['main', 'lora', 'vae'],
+      searchTerm: 'sd detail',
+    });
+
+    expect(result.candidates.map((m) => m.key)).toEqual(['a', 'c']);
+    expect(result.groups.map((group) => group.type)).toEqual(['lora']);
+    expect(result.groups[0]?.models.map((m) => m.key)).toEqual(['c']);
+  });
+
+  it('sorts picker results by taxonomy rank then name', () => {
+    const result = getModelPickerGroups(library, {
+      modelTypes: ['main', 'lora', 'vae'],
+      searchTerm: '',
+    });
+
+    expect(result.groups.map((group) => [group.type, group.models.map((m) => m.key)])).toEqual([
+      ['main', ['b', 'a']],
+      ['lora', ['c']],
+      ['vae', ['d']],
+    ]);
+  });
+
+  it('filters visible models by the selected bases, empty set showing all', () => {
+    const onlySdxl = getModelPickerGroups(library, {
+      baseFilter: new Set(['sdxl']),
+      modelTypes: ['main', 'lora', 'vae'],
+      searchTerm: '',
+    });
+
+    expect(onlySdxl.groups.flatMap((group) => group.models.map((m) => m.key))).toEqual(['a']);
+
+    const all = getModelPickerGroups(library, {
+      baseFilter: new Set(),
+      modelTypes: ['main', 'lora', 'vae'],
+      searchTerm: '',
+    });
+
+    expect(all.groups.flatMap((group) => group.models.map((m) => m.key))).toEqual(['b', 'a', 'c', 'd']);
+  });
+
+  it('exposes availableBases that stay stable across search and base filtering', () => {
+    const expected = ['sd-1', 'sdxl', 'flux', 'any'];
+
+    const base = getModelPickerGroups(library, { modelTypes: ['main', 'lora', 'vae'], searchTerm: '' });
+    expect(base.availableBases).toEqual(expected);
+
+    const searched = getModelPickerGroups(library, { modelTypes: ['main', 'lora', 'vae'], searchTerm: 'flux' });
+    expect(searched.availableBases).toEqual(expected);
+
+    const filtered = getModelPickerGroups(library, {
+      baseFilter: new Set(['flux']),
+      modelTypes: ['main', 'lora', 'vae'],
+      searchTerm: '',
+    });
+    expect(filtered.availableBases).toEqual(expected);
+  });
+
+  it('drops bases removed by excludeKeys or the custom predicate from availableBases', () => {
+    const result = getModelPickerGroups(library, {
+      excludeKeys: new Set(['b']),
+      filter: (model) => model.base !== 'any',
+      modelTypes: ['main', 'lora', 'vae'],
+      searchTerm: '',
+    });
+
+    expect(result.availableBases).toEqual(['sd-1', 'sdxl']);
+  });
+});
+
+describe('collect helpers', () => {
+  it('collects distinct bases alphabetically and types in category order', () => {
+    expect(collectBases(library)).toEqual(['any', 'flux', 'sd-1', 'sdxl']);
+    expect(collectTypes(library)).toEqual(['main', 'lora', 'vae']);
+  });
+
+  it('orders bases for display by registry order with any/external/unknown last', () => {
+    expect(collectBasesForDisplay(library)).toEqual(['sd-1', 'sdxl', 'flux', 'any']);
+    expect(
+      collectBasesForDisplay([{ base: 'unknown' }, { base: 'flux' }, { base: 'external' }, { base: 'sd-1' }])
+    ).toEqual(['sd-1', 'flux', 'external', 'unknown']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/models/library.ts b/invokeai/frontend/webv2/src/workbench/models/library.ts
new file mode 100644
index 00000000000..1cdf50d94c6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/library.ts
@@ -0,0 +1,203 @@
+import type { ModelConfig, ModelTaxonomyType } from './types';
+
+import { getModelBaseLabel, KNOWN_MODEL_BASES } from './baseIdentity';
+import { getModelCategoryRank, getModelTypePluralLabel } from './taxonomy';
+
+/**
+ * Pure filtering/grouping/sorting for the model library. Kept free of React so
+ * the list views stay thin and this logic is unit-testable.
+ */
+
+export type ModelSortField = 'default' | 'name' | 'base' | 'size' | 'format';
+
+export interface ModelLibraryFilters {
+  searchTerm: string;
+  /** null = all types. */
+  typeFilter: ModelTaxonomyType | null;
+  /** null = all bases. */
+  baseFilter: string | null;
+  /** Only models whose files are missing on disk. */
+  missingOnly: boolean;
+  sortField: ModelSortField;
+  sortDirection: 'asc' | 'desc';
+}
+
+export const DEFAULT_LIBRARY_FILTERS: ModelLibraryFilters = {
+  baseFilter: null,
+  missingOnly: false,
+  searchTerm: '',
+  sortDirection: 'asc',
+  sortField: 'default',
+  typeFilter: null,
+};
+
+export interface ModelGroup {
+  type: ModelTaxonomyType;
+  label: string;
+  models: ModelConfig[];
+}
+
+export interface ModelPickerOptions {
+  /** Multi-select base filter; empty/undefined = all bases. */
+  baseFilter?: ReadonlySet<string>;
+  /** Hide specific models, e.g. the current model or already-linked choices. */
+  excludeKeys?: ReadonlySet<string>;
+  /** Extra predicate supplied by the owning form, e.g. base compatibility. */
+  filter?: (model: ModelConfig) => boolean;
+  modelTypes: ModelTaxonomyType[];
+  searchTerm: string;
+}
+
+export interface ModelPickerResult {
+  /** Distinct bases among candidates (pre-search, pre-base-filter), for chips. */
+  availableBases: string[];
+  /** Models available before text search, used for empty-state copy. */
+  candidates: ModelConfig[];
+  groups: ModelGroup[];
+}
+
+const matchesSearch = (model: ModelConfig, searchTerm: string): boolean => {
+  if (!searchTerm) {
+    return true;
+  }
+
+  const haystack =
+    `${model.name} ${model.description ?? ''} ${model.base} ${model.type} ${model.format} ${(model.trigger_phrases ?? []).join(' ')}`.toLowerCase();
+
+  return searchTerm
+    .toLowerCase()
+    .split(/\s+/)
+    .every((term) => haystack.includes(term));
+};
+
+const compareBySortField = (a: ModelConfig, b: ModelConfig, field: ModelSortField): number => {
+  switch (field) {
+    case 'name':
+    case 'default':
+      return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+    case 'base':
+      return getModelBaseLabel(a.base).localeCompare(getModelBaseLabel(b.base));
+    case 'size':
+      return a.file_size - b.file_size;
+    case 'format':
+      return String(a.format).localeCompare(String(b.format));
+  }
+};
+
+export const filterModels = (
+  models: ModelConfig[],
+  filters: ModelLibraryFilters,
+  missingModelKeys: ReadonlySet<string>
+): ModelConfig[] => {
+  const searchTerm = filters.searchTerm.trim();
+  const directionFactor = filters.sortDirection === 'desc' ? -1 : 1;
+
+  return models
+    .filter(
+      (model) =>
+        (!filters.missingOnly || missingModelKeys.has(model.key)) &&
+        (filters.typeFilter === null || model.type === filters.typeFilter) &&
+        (filters.baseFilter === null || model.base === filters.baseFilter) &&
+        matchesSearch(model, searchTerm)
+    )
+    .sort((a, b) => compareBySortField(a, b, filters.sortField) * directionFactor);
+};
+
+/** Group filtered models by category in canonical category order. */
+export const groupModelsByType = (models: ModelConfig[]): ModelGroup[] => {
+  const groupsByType = new Map<ModelTaxonomyType, ModelConfig[]>();
+
+  for (const model of models) {
+    const group = groupsByType.get(model.type);
+
+    if (group) {
+      group.push(model);
+    } else {
+      groupsByType.set(model.type, [model]);
+    }
+  }
+
+  return [...groupsByType.entries()]
+    .sort(([a], [b]) => getModelCategoryRank(a) - getModelCategoryRank(b))
+    .map(([type, groupModels]) => ({ label: getModelTypePluralLabel(type), models: groupModels, type }));
+};
+
+const matchesPickerSearch = (model: ModelConfig, searchTerm: string): boolean => {
+  const terms = searchTerm.trim().toLowerCase().split(/\s+/).filter(Boolean);
+
+  if (terms.length === 0) {
+    return true;
+  }
+
+  const haystack = `${model.name} ${model.base} ${model.type}`.toLowerCase();
+
+  return terms.every((term) => haystack.includes(term));
+};
+
+/** Candidate, search, sort, and grouping rules shared by every model picker instance. */
+export const getModelPickerGroups = (models: ModelConfig[], options: ModelPickerOptions): ModelPickerResult => {
+  const allowedTypes = new Set(options.modelTypes);
+  const candidates = models.filter(
+    (model) =>
+      allowedTypes.has(model.type) &&
+      !options.excludeKeys?.has(model.key) &&
+      (options.filter ? options.filter(model) : true)
+  );
+  // Chips are derived from candidates — before text search and the base filter —
+  // so the chip row stays stable while the user types or toggles chips.
+  const availableBases = collectBasesForDisplay(candidates);
+  const { baseFilter } = options;
+  const visibleModels = candidates
+    .filter(
+      (model) =>
+        matchesPickerSearch(model, options.searchTerm) &&
+        (!baseFilter || baseFilter.size === 0 || baseFilter.has(String(model.base)))
+    )
+    .sort(
+      (a, b) =>
+        getModelCategoryRank(a.type) - getModelCategoryRank(b.type) ||
+        a.name.localeCompare(b.name, undefined, { sensitivity: 'base' })
+    );
+
+  return { availableBases, candidates, groups: groupModelsByType(visibleModels) };
+};
+
+/** Distinct bases present in a model list, for base filter menus. */
+export const collectBases = (models: Pick<ModelConfig, 'base'>[]): string[] =>
+  [...new Set(models.map((model) => String(model.base)))].sort();
+
+/** Bases that exist but carry no architecture meaning, sorted after the rest. */
+const DEPRIORITIZED_BASES: ReadonlySet<string> = new Set(['any', 'external', 'unknown']);
+
+/**
+ * Distinct bases present, ordered for display: known bases follow the
+ * registry order from `baseIdentity`, unknown bases come next, and the
+ * meaningless `any`/`external`/`unknown` bases are pushed to the very end.
+ */
+export const collectBasesForDisplay = (models: Pick<ModelConfig, 'base'>[]): string[] => {
+  const bases = [...new Set(models.map((model) => String(model.base)))];
+  const rank = (base: string): number => {
+    if (DEPRIORITIZED_BASES.has(base)) {
+      return KNOWN_MODEL_BASES.length + 1;
+    }
+
+    const index = KNOWN_MODEL_BASES.indexOf(base as (typeof KNOWN_MODEL_BASES)[number]);
+
+    return index === -1 ? KNOWN_MODEL_BASES.length : index;
+  };
+
+  return bases.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+};
+
+/** Distinct types present in a model list, in canonical order. */
+export const collectTypes = (models: Pick<ModelConfig, 'type'>[]): ModelTaxonomyType[] =>
+  [...new Set(models.map((model) => model.type))].sort((a, b) => getModelCategoryRank(a) - getModelCategoryRank(b));
+
+/** Rows for a virtualized flat list: group headers interleaved with models. */
+export type LibraryRow = { kind: 'header'; group: ModelGroup } | { kind: 'model'; model: ModelConfig };
+
+export const flattenGroupsToRows = (groups: ModelGroup[]): LibraryRow[] =>
+  groups.flatMap<LibraryRow>((group) => [
+    { group, kind: 'header' },
+    ...group.models.map<LibraryRow>((model) => ({ kind: 'model', model })),
+  ]);
diff --git a/invokeai/frontend/webv2/src/workbench/models/modelsStore.ts b/invokeai/frontend/webv2/src/workbench/models/modelsStore.ts
new file mode 100644
index 00000000000..fdd31a69ee3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/modelsStore.ts
@@ -0,0 +1,123 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+import type { ModelConfig } from './types';
+
+import { getModelsDir, listMissingModels, listModels } from './api';
+
+/**
+ * Shared library store for installed model configs. Lives outside the
+ * workbench reducer because the list is backend-owned server state shared by
+ * every model surface (manager, detail views, pickers); a single
+ * module store keeps them consistent and avoids re-fetch storms. Mutations go
+ * through the API layer and then either patch the snapshot in place (fast
+ * path) or trigger a refresh.
+ */
+
+export interface ModelsSnapshot {
+  models: ModelConfig[];
+  /** Keys of models whose files are missing on disk. */
+  missingModelKeys: ReadonlySet<string>;
+  /** Bumped when a model's cover image changes; cache-busts thumbnail URLs. */
+  coverImageVersions: Readonly<Record<string, number>>;
+  /** Absolute server path of the models directory (resolves relative model paths). */
+  modelsDir: string | null;
+  status: 'idle' | 'loading' | 'loaded' | 'error';
+  error: string | null;
+}
+
+const EMPTY_MISSING_KEYS: ReadonlySet<string> = new Set<string>();
+
+const store = createExternalStore<ModelsSnapshot>({
+  coverImageVersions: {},
+  error: null,
+  missingModelKeys: EMPTY_MISSING_KEYS,
+  models: [],
+  modelsDir: null,
+  status: 'idle',
+});
+
+let inflightRefresh: Promise<void> | null = null;
+
+/** Re-fetch the library; concurrent calls share one request. */
+export const refreshModels = (): Promise<void> => {
+  if (inflightRefresh) {
+    return inflightRefresh;
+  }
+
+  store.patchSnapshot({ status: store.getSnapshot().status === 'loaded' ? 'loaded' : 'loading' });
+
+  inflightRefresh = Promise.all([
+    listModels(),
+    // Missing-file detection is best-effort; never fail the whole library.
+    listMissingModels().catch(() => [] as ModelConfig[]),
+    // Static server config: fetched once, best-effort.
+    store.getSnapshot().modelsDir ?? getModelsDir().catch(() => null),
+  ])
+    .then(([models, missingModels, modelsDir]) => {
+      store.patchSnapshot({
+        error: null,
+        missingModelKeys:
+          missingModels.length > 0 ? new Set(missingModels.map((model) => model.key)) : EMPTY_MISSING_KEYS,
+        models,
+        modelsDir,
+        status: 'loaded',
+      });
+    })
+    .catch((error: unknown) => {
+      store.patchSnapshot({
+        error: error instanceof Error ? error.message : 'Failed to load models.',
+        status: store.getSnapshot().models.length > 0 ? 'loaded' : 'error',
+      });
+    })
+    .finally(() => {
+      inflightRefresh = null;
+    });
+
+  return inflightRefresh;
+};
+
+/** Fetch once on first use; later callers get the cached snapshot. */
+export const ensureModelsLoaded = (): void => {
+  if (store.getSnapshot().status === 'idle') {
+    void refreshModels();
+  }
+};
+
+export const getModelsSnapshot = (): ModelsSnapshot => store.getSnapshot();
+
+/** Patch one model in place after a successful update/convert. */
+export const replaceModelInStore = (model: ModelConfig): void => {
+  store.patchSnapshot({
+    models: store.getSnapshot().models.map((existing) => (existing.key === model.key ? model : existing)),
+  });
+};
+
+export const removeModelsFromStore = (keys: string[]): void => {
+  const removed = new Set(keys);
+
+  store.patchSnapshot({ models: store.getSnapshot().models.filter((model) => !removed.has(model.key)) });
+};
+
+/**
+ * Record a cover image upload/removal without refetching: keeps the truthy
+ * `cover_image` marker in sync for thumbnails and bumps the version that
+ * cache-busts their URLs (the backend serves the image at a stable URL).
+ */
+export const markCoverImageChanged = (key: string, hasImage: boolean): void => {
+  const { coverImageVersions, models } = store.getSnapshot();
+
+  store.patchSnapshot({
+    coverImageVersions: { ...coverImageVersions, [key]: (coverImageVersions[key] ?? 0) + 1 },
+    models: models.map((model) =>
+      model.key === key ? { ...model, cover_image: hasImage ? (model.cover_image ?? 'present') : null } : model
+    ),
+  });
+};
+
+export const setModelsSnapshotForTests = (next: Partial<ModelsSnapshot>): void => {
+  store.patchSnapshot(next);
+};
+
+export const useModelsSelector = store.useSelector;
+
+export const useModelsSnapshot = (): ModelsSnapshot => store.useSnapshot();
diff --git a/invokeai/frontend/webv2/src/workbench/models/schemas.ts b/invokeai/frontend/webv2/src/workbench/models/schemas.ts
new file mode 100644
index 00000000000..c6c1f4ae3ab
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/schemas.ts
@@ -0,0 +1,102 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas backing every model-manager form. All user input is validated
+ * through these before touching the API, so error states are consistent and
+ * the API layer can assume well-formed values.
+ */
+
+const trimmed = z.string().trim();
+
+/** URL, HuggingFace repo id, or absolute local path. */
+export const installSourceSchema = z.object({
+  accessToken: trimmed.optional(),
+  inplace: z.boolean(),
+  source: trimmed
+    .min(1, 'Enter a URL, HuggingFace repo id, or local path.')
+    .refine(
+      (value) => !value.includes(' ') || value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value),
+      'URLs and repo ids cannot contain spaces.'
+    ),
+});
+
+export type InstallSourceFormValues = z.infer<typeof installSourceSchema>;
+
+/** `owner/name` with optional `:variant[:path]` qualifiers. */
+export const huggingFaceRepoSchema = z.object({
+  repo: trimmed
+    .min(1, 'Enter a HuggingFace repo id.')
+    .regex(/^[\w.-]+\/[\w.-]+(:[\w./-]*)*$/, 'Expected an owner/repo id, e.g. black-forest-labs/FLUX.1-dev.'),
+});
+
+export type HuggingFaceRepoFormValues = z.infer<typeof huggingFaceRepoSchema>;
+
+export const scanFolderSchema = z.object({
+  path: trimmed.min(1, 'Enter an absolute folder path on the server.'),
+});
+
+export type ScanFolderFormValues = z.infer<typeof scanFolderSchema>;
+
+export const hfTokenSchema = z.object({
+  token: trimmed.min(1, 'Paste a HuggingFace access token.'),
+});
+
+export type HFTokenFormValues = z.infer<typeof hfTokenSchema>;
+
+export const civitaiKeySchema = z.object({
+  key: trimmed.min(1, 'Paste a Civitai API key.'),
+});
+
+export type CivitaiKeyFormValues = z.infer<typeof civitaiKeySchema>;
+
+export const modelEditSchema = z.object({
+  base: trimmed.min(1, 'Base architecture is required.'),
+  description: trimmed.max(2000, 'Keep the description under 2000 characters.'),
+  name: trimmed.min(1, 'Name is required.').max(200, 'Keep the name under 200 characters.'),
+  predictionType: z.union([z.literal(''), z.enum(['epsilon', 'v_prediction', 'sample'])]),
+  sourceUrl: z.union([z.literal(''), z.url({ error: 'Must be a valid http(s) URL.' })]),
+  type: trimmed.min(1, 'Model type is required.'),
+  variant: trimmed,
+});
+
+export type ModelEditFormValues = z.infer<typeof modelEditSchema>;
+
+const optionalBoundedNumber = (min: number, max: number, label: string) =>
+  z
+    .number({ message: `${label} must be a number.` })
+    .min(min, `${label} must be at least ${min}.`)
+    .max(max, `${label} must be at most ${max}.`)
+    .nullable();
+
+/**
+ * Per-model generation defaults. Every field is nullable — null means "no
+ * default, use the app-level setting" and maps to an unchecked toggle.
+ */
+export const mainDefaultSettingsSchema = z.object({
+  cfgRescaleMultiplier: optionalBoundedNumber(0, 0.99, 'CFG rescale multiplier'),
+  cfgScale: optionalBoundedNumber(1, 200, 'CFG scale'),
+  guidance: optionalBoundedNumber(1, 20, 'Guidance'),
+  height: optionalBoundedNumber(64, 8192, 'Height').refine(
+    (value) => value === null || value % 8 === 0,
+    'Height must be a multiple of 8.'
+  ),
+  scheduler: trimmed.nullable(),
+  steps: optionalBoundedNumber(1, 10000, 'Steps'),
+  vaePrecision: z.enum(['fp16', 'fp32']).nullable(),
+  width: optionalBoundedNumber(64, 8192, 'Width').refine(
+    (value) => value === null || value % 8 === 0,
+    'Width must be a multiple of 8.'
+  ),
+});
+
+export type MainDefaultSettingsFormValues = z.infer<typeof mainDefaultSettingsSchema>;
+
+export const loraDefaultSettingsSchema = z.object({
+  weight: optionalBoundedNumber(-10, 10, 'Weight'),
+});
+
+export type LoraDefaultSettingsFormValues = z.infer<typeof loraDefaultSettingsSchema>;
+
+export const triggerPhraseSchema = trimmed
+  .min(1, 'Trigger phrase cannot be empty.')
+  .max(200, 'Keep trigger phrases under 200 characters.');
diff --git a/invokeai/frontend/webv2/src/workbench/models/startersStore.ts b/invokeai/frontend/webv2/src/workbench/models/startersStore.ts
new file mode 100644
index 00000000000..df668c72620
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/startersStore.ts
@@ -0,0 +1,62 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+import type { StarterModelResponse } from './types';
+
+import { getStarterModels } from './api';
+
+/**
+ * Cached starter-models catalog. The list is large and rarely changes, so it
+ * is fetched once and served from memory on revisits; installs revalidate it
+ * in the background (the `is_installed` flags shift) without blanking the UI.
+ */
+
+export interface StartersSnapshot {
+  response: StarterModelResponse | null;
+  status: 'idle' | 'loading' | 'loaded' | 'error';
+  error: string | null;
+}
+
+const store = createExternalStore<StartersSnapshot>({ error: null, response: null, status: 'idle' });
+
+let inflightRefresh: Promise<void> | null = null;
+
+export const refreshStarters = (): Promise<void> => {
+  if (inflightRefresh) {
+    return inflightRefresh;
+  }
+
+  store.patchSnapshot({ status: store.getSnapshot().response ? 'loaded' : 'loading' });
+
+  inflightRefresh = getStarterModels()
+    .then((response) => {
+      store.patchSnapshot({ error: null, response, status: 'loaded' });
+    })
+    .catch((error: unknown) => {
+      store.patchSnapshot({
+        error: error instanceof Error ? error.message : 'Failed to load starter models.',
+        status: store.getSnapshot().response ? 'loaded' : 'error',
+      });
+    })
+    .finally(() => {
+      inflightRefresh = null;
+    });
+
+  return inflightRefresh;
+};
+
+export const ensureStartersLoaded = (): void => {
+  if (store.getSnapshot().status === 'idle') {
+    void refreshStarters();
+  }
+};
+
+/** Revalidate installed flags after an install lands, if already loaded. */
+export const refreshStartersIfLoaded = (): void => {
+  if (store.getSnapshot().status === 'loaded') {
+    void refreshStarters();
+  }
+};
+
+export const useStartersSelector = store.useSelector;
+
+export const useStartersSnapshot = (): StartersSnapshot => store.useSnapshot();
diff --git a/invokeai/frontend/webv2/src/workbench/models/taxonomy.ts b/invokeai/frontend/webv2/src/workbench/models/taxonomy.ts
new file mode 100644
index 00000000000..82c337b4c31
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/taxonomy.ts
@@ -0,0 +1,105 @@
+import type { ModelFileFormat, ModelInstallJob, ModelTaxonomyType } from './types';
+
+/**
+ * Display metadata for the model taxonomy. Open-union friendly: unknown bases,
+ * types, and formats fall back to readable generic labels so a backend that
+ * ships a new architecture never renders a blank or broken library.
+ */
+
+interface CategoryDefinition {
+  type: ModelTaxonomyType;
+  label: string;
+  pluralLabel: string;
+}
+
+/** Library grouping order — most-used categories first, mirroring legacy web. */
+export const MODEL_CATEGORIES: CategoryDefinition[] = [
+  { label: 'Main Model', pluralLabel: 'Main Models', type: 'main' },
+  { label: 'LoRA', pluralLabel: 'LoRAs', type: 'lora' },
+  { label: 'Embedding', pluralLabel: 'Embeddings', type: 'embedding' },
+  { label: 'ControlNet', pluralLabel: 'ControlNets', type: 'controlnet' },
+  { label: 'Control LoRA', pluralLabel: 'Control LoRAs', type: 'control_lora' },
+  { label: 'IP Adapter', pluralLabel: 'IP Adapters', type: 'ip_adapter' },
+  { label: 'T2I Adapter', pluralLabel: 'T2I Adapters', type: 't2i_adapter' },
+  { label: 'VAE', pluralLabel: 'VAEs', type: 'vae' },
+  { label: 'T5 Encoder', pluralLabel: 'T5 Encoders', type: 't5_encoder' },
+  { label: 'Qwen3 Encoder', pluralLabel: 'Qwen3 Encoders', type: 'qwen3_encoder' },
+  { label: 'Qwen VL Encoder', pluralLabel: 'Qwen VL Encoders', type: 'qwen_vl_encoder' },
+  { label: 'CLIP Embed', pluralLabel: 'CLIP Embeds', type: 'clip_embed' },
+  { label: 'CLIP Vision', pluralLabel: 'CLIP Visions', type: 'clip_vision' },
+  { label: 'SigLIP', pluralLabel: 'SigLIPs', type: 'siglip' },
+  { label: 'FLUX Redux', pluralLabel: 'FLUX Reduxes', type: 'flux_redux' },
+  { label: 'Image-to-Image', pluralLabel: 'Image-to-Image Models', type: 'spandrel_image_to_image' },
+  { label: 'LLaVA OneVision', pluralLabel: 'LLaVA OneVision Models', type: 'llava_onevision' },
+  { label: 'Text LLM', pluralLabel: 'Text LLMs', type: 'text_llm' },
+  { label: 'External Generator', pluralLabel: 'External Generators', type: 'external_image_generator' },
+  { label: 'ONNX', pluralLabel: 'ONNX Models', type: 'onnx' },
+  { label: 'Unknown', pluralLabel: 'Unknown Models', type: 'unknown' },
+];
+
+const categoryByType = new Map(MODEL_CATEGORIES.map((category) => [category.type, category]));
+
+const toTitleCase = (value: string): string =>
+  value.replaceAll(/[_-]+/g, ' ').replace(/\w\S*/g, (word) => word.charAt(0).toUpperCase() + word.slice(1));
+
+export const getModelTypeLabel = (type: ModelTaxonomyType): string =>
+  categoryByType.get(type)?.label ?? toTitleCase(type);
+
+export const getModelTypePluralLabel = (type: ModelTaxonomyType): string =>
+  categoryByType.get(type)?.pluralLabel ?? `${toTitleCase(type)} Models`;
+
+/** Sort rank of a category for grouped views; unknown types sort last. */
+export const getModelCategoryRank = (type: ModelTaxonomyType): number => {
+  const index = MODEL_CATEGORIES.findIndex((category) => category.type === type);
+
+  return index === -1 ? MODEL_CATEGORIES.length : index;
+};
+
+const FORMAT_LABELS: Record<string, string> = {
+  bnb_quantized_int8b: 'BnB int8',
+  bnb_quantized_nf4b: 'BnB nf4',
+  checkpoint: 'Checkpoint',
+  diffusers: 'Diffusers',
+  embedding_file: 'Embedding File',
+  embedding_folder: 'Embedding Folder',
+  external_api: 'External API',
+  gguf_quantized: 'GGUF',
+  invokeai: 'InvokeAI',
+  lycoris: 'LyCORIS',
+  olive: 'Olive',
+  omi: 'OMI',
+  onnx: 'ONNX',
+  qwen3_encoder: 'Qwen3 Encoder',
+  qwen_vl_encoder: 'Qwen VL Encoder',
+  t5_encoder: 'T5 Encoder',
+  unknown: 'Unknown',
+};
+
+export const getModelFormatLabel = (format: ModelFileFormat): string => FORMAT_LABELS[format] ?? toTitleCase(format);
+
+const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;
+
+export const formatBytes = (bytes: number | null | undefined): string => {
+  if (bytes === null || bytes === undefined || !Number.isFinite(bytes) || bytes < 0) {
+    return '—';
+  }
+
+  let value = bytes;
+  let unitIndex = 0;
+
+  while (value >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+
+  return `${unitIndex === 0 ? value : value.toFixed(1)} ${BYTE_UNITS[unitIndex]}`;
+};
+
+/** Human-readable source for an install job (string or structured source). */
+export const getInstallSourceLabel = (source: ModelInstallJob['source']): string => {
+  if (typeof source === 'string') {
+    return source;
+  }
+
+  return source.repo_id ?? source.url ?? source.path ?? JSON.stringify(source);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/models/types.ts b/invokeai/frontend/webv2/src/workbench/models/types.ts
new file mode 100644
index 00000000000..c0f3ac985d2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/types.ts
@@ -0,0 +1,242 @@
+/**
+ * Contracts for the backend model manager (`/api/v2/models/*`). Shapes mirror
+ * the pydantic models in `invokeai/backend/model_manager` and
+ * `invokeai/app/services/model_install` (serialized as snake_case). Unions are
+ * kept open (`| (string & {})`) so new backend architectures appear in the UI
+ * without a frontend release — unknown values fall back to generic labels.
+ */
+
+/** Known model base architectures. Open union: new bases still render. */
+export type ModelBase =
+  | 'any'
+  | 'sd-1'
+  | 'sd-2'
+  | 'sd-3'
+  | 'sdxl'
+  | 'sdxl-refiner'
+  | 'flux'
+  | 'flux2'
+  | 'cogview4'
+  | 'qwen-image'
+  | 'z-image'
+  | 'anima'
+  | 'external'
+  | 'unknown'
+  | (string & {});
+
+/** Known model types. Open union: new types still render. */
+export type ModelTaxonomyType =
+  | 'main'
+  | 'vae'
+  | 'lora'
+  | 'control_lora'
+  | 'controlnet'
+  | 't2i_adapter'
+  | 'ip_adapter'
+  | 'embedding'
+  | 'clip_embed'
+  | 'clip_vision'
+  | 't5_encoder'
+  | 'qwen3_encoder'
+  | 'qwen_vl_encoder'
+  | 'siglip'
+  | 'spandrel_image_to_image'
+  | 'flux_redux'
+  | 'llava_onevision'
+  | 'text_llm'
+  | 'external_image_generator'
+  | 'onnx'
+  | 'unknown'
+  | (string & {});
+
+export type ModelFileFormat =
+  | 'checkpoint'
+  | 'diffusers'
+  | 'lycoris'
+  | 'omi'
+  | 'onnx'
+  | 'olive'
+  | 'embedding_file'
+  | 'embedding_folder'
+  | 'invokeai'
+  | 't5_encoder'
+  | 'qwen3_encoder'
+  | 'qwen_vl_encoder'
+  | 'bnb_quantized_int8b'
+  | 'bnb_quantized_nf4b'
+  | 'gguf_quantized'
+  | 'external_api'
+  | 'unknown'
+  | (string & {});
+
+export type PredictionType = 'epsilon' | 'v_prediction' | 'sample';
+
+/** Per-model defaults that Generate can apply explicitly. */
+export interface MainModelDefaultSettings {
+  vae?: string | null;
+  vae_precision?: 'fp16' | 'fp32' | null;
+  scheduler?: string | null;
+  steps?: number | null;
+  cfg_scale?: number | null;
+  cfg_rescale_multiplier?: number | null;
+  width?: number | null;
+  height?: number | null;
+  guidance?: number | null;
+  fp8_storage?: boolean | null;
+}
+
+export interface LoraModelDefaultSettings {
+  weight?: number | null;
+}
+
+export interface ControlAdapterDefaultSettings {
+  preprocessor?: string | null;
+  fp8_storage?: boolean | null;
+}
+
+export type AnyModelDefaultSettings = MainModelDefaultSettings &
+  LoraModelDefaultSettings &
+  ControlAdapterDefaultSettings;
+
+/**
+ * A model config record. This is the union of fields across all backend config
+ * classes; fields not applicable to a given type/format are absent.
+ */
+export interface ModelConfig {
+  key: string;
+  hash: string;
+  path: string;
+  file_size: number;
+  name: string;
+  description?: string | null;
+  source: string;
+  source_type: 'path' | 'url' | 'hf_repo_id' | (string & {});
+  source_url?: string | null;
+  cover_image?: string | null;
+  base: ModelBase;
+  type: ModelTaxonomyType;
+  format: ModelFileFormat;
+  variant?: string | null;
+  prediction_type?: PredictionType | null;
+  upcast_attention?: boolean;
+  config_path?: string | null;
+  trigger_phrases?: string[] | null;
+  default_settings?: AnyModelDefaultSettings | null;
+  submodels?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+
+/** Body for PATCH `/api/v2/models/i/{key}` — all fields optional. */
+export interface ModelRecordChanges {
+  name?: string;
+  description?: string | null;
+  source_url?: string | null;
+  base?: ModelBase;
+  type?: ModelTaxonomyType;
+  format?: ModelFileFormat;
+  variant?: string | null;
+  prediction_type?: PredictionType | null;
+  upcast_attention?: boolean;
+  config_path?: string | null;
+  trigger_phrases?: string[] | null;
+  default_settings?: AnyModelDefaultSettings | null;
+}
+
+export type ModelInstallStatus =
+  | 'waiting'
+  | 'downloading'
+  | 'downloads_done'
+  | 'running'
+  | 'paused'
+  | 'completed'
+  | 'error'
+  | 'cancelled';
+
+export interface ModelInstallDownloadPart {
+  source?: string;
+  url?: string;
+  local_path?: string;
+  bytes: number;
+  total_bytes: number;
+  status?: string;
+  /** Server refused to resume this part; it must be restarted from scratch. */
+  resume_required?: boolean;
+  /** Why a resume was refused, when known. */
+  resume_message?: string | null;
+  /** The part was silently restarted from the beginning after a failed resume. */
+  resume_from_scratch?: boolean;
+}
+
+/** A model install job as returned by `/api/v2/models/install`. */
+export interface ModelInstallJob {
+  id: number;
+  status: ModelInstallStatus;
+  /** Local path, URL, or HF repo id — may be a string or a structured source. */
+  source: string | { repo_id?: string; url?: string; path?: string; type?: string; [key: string]: unknown };
+  error?: string | null;
+  error_reason?: string | null;
+  error_traceback?: string | null;
+  bytes?: number;
+  total_bytes?: number;
+  local_path?: string | null;
+  inplace?: boolean;
+  config_in?: ModelRecordChanges | null;
+  config_out?: ModelConfig | null;
+  download_parts?: ModelInstallDownloadPart[];
+  [key: string]: unknown;
+}
+
+/** A model file found by `/api/v2/models/scan_folder`. */
+export interface FoundModel {
+  path: string;
+  is_installed: boolean;
+}
+
+/** Result of `/api/v2/models/hugging_face` metadata lookup. */
+export interface HuggingFaceModels {
+  urls: string[] | null;
+  is_diffusers: boolean;
+}
+
+export interface StarterModel {
+  name: string;
+  description: string;
+  source: string;
+  base: ModelBase;
+  type: ModelTaxonomyType;
+  format?: ModelFileFormat | null;
+  variant?: string | null;
+  is_installed: boolean;
+  dependencies?: Omit<StarterModel, 'dependencies'>[] | null;
+  previous_names?: string[];
+}
+
+export interface StarterModelBundle {
+  name: string;
+  models: StarterModel[];
+}
+
+export interface StarterModelResponse {
+  starter_models: StarterModel[];
+  starter_bundles: Record<string, StarterModelBundle>;
+}
+
+export type HFTokenStatus = 'valid' | 'invalid' | 'unknown';
+
+/** A model directory on disk with no matching database record. */
+export interface OrphanedModelInfo {
+  path: string;
+  absolute_path: string;
+  files: string[];
+  size_bytes: number;
+}
+
+export interface BulkDeleteModelsResponse {
+  deleted: string[];
+  failed: { key: string; error: string }[];
+}
+
+export interface DeleteOrphanedModelsResponse {
+  deleted: string[];
+  errors: Record<string, string>;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/models/uiStore.ts b/invokeai/frontend/webv2/src/workbench/models/uiStore.ts
new file mode 100644
index 00000000000..57b2c52667d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/uiStore.ts
@@ -0,0 +1,117 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+import type { FoundModel } from './types';
+
+import { DEFAULT_LIBRARY_FILTERS, type ModelLibraryFilters } from './library';
+
+/**
+ * Session-lived UI state for the model manager. Views unmount whenever the user
+ * switches launchpad tabs or detail tabs; keeping selection,
+ * filters, and in-progress source forms here means nothing is forgotten when
+ * they come back. Deliberately not persisted to localStorage — it resets with
+ * the page, like a scroll position.
+ */
+
+/**
+ * The detail-pane tabs. The library list is now a persistent left column, so it
+ * is no longer a tab; the install queue is a persistent detail-pane footer. What
+ * remains is the selected model's detail, the unified Add Models search, and API
+ * keys.
+ */
+export type ModelManagerTab = 'details' | 'add' | 'keys';
+
+/** A resolved HuggingFace checkpoint-repo lookup, kept across tab switches. */
+export interface HFLookupState {
+  repo: string;
+  urls: string[];
+}
+
+export interface ModelsUiSnapshot {
+  activeTab: ModelManagerTab;
+  /** Model focused in the manager library's detail pane. */
+  activeModelKey: string | null;
+  selectedKeys: ReadonlySet<string>;
+  filters: ModelLibraryFilters;
+  /** Last folder-scan query and its results, kept across tab switches. */
+  scan: { path: string; results: FoundModel[] } | null;
+  /** Last HuggingFace repo lookup, kept across tab switches. */
+  hfLookup: HFLookupState | null;
+  /** Whether the always-visible install queue footer is expanded. */
+  queueExpanded: boolean;
+  /** Scroll offsets per library-list instance, restored on remount. */
+  libraryScrollOffsets: Record<string, number>;
+}
+
+const store = createExternalStore<ModelsUiSnapshot>({
+  activeModelKey: null,
+  activeTab: 'add',
+  filters: DEFAULT_LIBRARY_FILTERS,
+  hfLookup: null,
+  libraryScrollOffsets: {},
+  queueExpanded: false,
+  scan: null,
+  selectedKeys: new Set(),
+});
+
+export const updateModelsUi = (next: Partial<ModelsUiSnapshot>): void => {
+  store.patchSnapshot(next);
+};
+
+export const toggleModelSelection = (key: string): void => {
+  const selectedKeys = new Set(store.getSnapshot().selectedKeys);
+
+  if (selectedKeys.has(key)) {
+    selectedKeys.delete(key);
+  } else {
+    selectedKeys.add(key);
+  }
+
+  updateModelsUi({ selectedKeys });
+};
+
+/** Drop deleted models from selection/active slots so stale keys never linger. */
+export const pruneModelsUiKeys = (deletedKeys: string[]): void => {
+  const { activeModelKey, selectedKeys } = store.getSnapshot();
+  const deleted = new Set(deletedKeys);
+
+  updateModelsUi({
+    activeModelKey: activeModelKey !== null && deleted.has(activeModelKey) ? null : activeModelKey,
+    selectedKeys: new Set([...selectedKeys].filter((key) => !deleted.has(key))),
+  });
+};
+
+/** Jump the model manager's detail pane to a specific tab. */
+export const openModelManagerTab = (activeTab: ModelManagerTab): void => {
+  updateModelsUi({ activeTab });
+};
+
+/** Focus a model and reveal it in the detail tab (e.g. from a library row). */
+export const openModelDetail = (modelKey: string): void => {
+  updateModelsUi({ activeModelKey: modelKey, activeTab: 'details' });
+};
+
+/** Expand the always-visible install queue footer (e.g. from a "View queue" link). */
+export const openInstallQueue = (): void => {
+  updateModelsUi({ queueExpanded: true });
+};
+
+export const setQueueExpanded = (queueExpanded: boolean): void => {
+  updateModelsUi({ queueExpanded });
+};
+
+export const saveLibraryScrollOffset = (instanceId: string, offset: number): void => {
+  const snapshot = store.getSnapshot();
+
+  // Silent: scroll offsets are read on mount, never subscribed to.
+  store.setSnapshotSilently({
+    ...snapshot,
+    libraryScrollOffsets: { ...snapshot.libraryScrollOffsets, [instanceId]: offset },
+  });
+};
+
+export const getLibraryScrollOffset = (instanceId: string): number =>
+  store.getSnapshot().libraryScrollOffsets[instanceId] ?? 0;
+
+export const useModelsUiSelector = store.useSelector;
+
+export const useModelsUi = (): ModelsUiSnapshot => store.useSnapshot();
diff --git a/invokeai/frontend/webv2/src/workbench/models/useInstallOutcomeToasts.ts b/invokeai/frontend/webv2/src/workbench/models/useInstallOutcomeToasts.ts
new file mode 100644
index 00000000000..1279c2b00fc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/useInstallOutcomeToasts.ts
@@ -0,0 +1,39 @@
+import { useNotify } from '@workbench/useNotify';
+import { useEffect, useRef } from 'react';
+
+import { useInstallOutcomes } from './installsStore';
+
+/**
+ * Turns settled install outcomes (completed/failed/cancelled) into notifications,
+ * while the model manager is mounted. Provider-free: `useNotify` falls back to
+ * global toasts off-workbench. Mounted by `ModelInstallRuntime`.
+ */
+export const useInstallOutcomeToasts = (): void => {
+  const notify = useNotify();
+  const outcomes = useInstallOutcomes();
+  const seenOutcomeIdsRef = useRef<Set<number> | null>(null);
+
+  useEffect(() => {
+    if (seenOutcomeIdsRef.current === null) {
+      seenOutcomeIdsRef.current = new Set(outcomes.map((outcome) => outcome.id));
+
+      return;
+    }
+
+    for (const outcome of [...outcomes].reverse()) {
+      if (seenOutcomeIdsRef.current.has(outcome.id)) {
+        continue;
+      }
+
+      seenOutcomeIdsRef.current.add(outcome.id);
+
+      if (outcome.kind === 'completed') {
+        notify.success('Model installed', outcome.modelName ?? outcome.source);
+      } else if (outcome.kind === 'error') {
+        notify.error('Model install failed', `${outcome.source}: ${outcome.error ?? 'Unknown error.'}`);
+      } else {
+        notify.info('Model install cancelled', outcome.source);
+      }
+    }
+  }, [notify, outcomes]);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/models/useZodForm.ts b/invokeai/frontend/webv2/src/workbench/models/useZodForm.ts
new file mode 100644
index 00000000000..d69af0de9b5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/models/useZodForm.ts
@@ -0,0 +1,120 @@
+import type { z } from 'zod';
+
+import { useCallback, useRef, useState } from 'react';
+
+/**
+ * Minimal zod-backed form state. Validation runs on submit; editing a field
+ * that shows an error clears that error immediately (optimistic — the next
+ * submit re-validates), so users are not nagged mid-correction.
+ */
+
+export interface ZodFormField<Value> {
+  value: Value;
+  error: string | null;
+}
+
+export interface ZodForm<Schema extends z.ZodType<Record<string, unknown>>> {
+  values: z.infer<Schema>;
+  errors: Partial<Record<keyof z.infer<Schema>, string>>;
+  /** Form-level error (refinements that do not map to a single field). */
+  formError: string | null;
+  isSubmitting: boolean;
+  setValue: <Key extends keyof z.infer<Schema>>(key: Key, value: z.infer<Schema>[Key]) => void;
+  setValues: (values: z.infer<Schema>) => void;
+  /** Validate and run `onValid`; submission errors land in `formError`. */
+  handleSubmit: (onValid: (values: z.infer<Schema>) => Promise<void> | void) => Promise<void>;
+  reset: (values?: z.infer<Schema>) => void;
+}
+
+export const useZodForm = <Schema extends z.ZodType<Record<string, unknown>>>(
+  schema: Schema,
+  initialValues: z.infer<Schema>
+): ZodForm<Schema> => {
+  type Values = z.infer<Schema>;
+
+  const [values, setValuesState] = useState<Values>(initialValues);
+  const initialValuesRef = useRef(initialValues);
+  const [errors, setErrors] = useState<Partial<Record<keyof Values, string>>>({});
+  const [formError, setFormError] = useState<string | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const validate = useCallback(
+    (candidate: Values): { ok: true; data: Values } | { ok: false } => {
+      const result = schema.safeParse(candidate);
+
+      if (result.success) {
+        setErrors({});
+        setFormError(null);
+
+        return { data: result.data as Values, ok: true };
+      }
+
+      const nextErrors: Partial<Record<keyof Values, string>> = {};
+      let nextFormError: string | null = null;
+
+      for (const issue of result.error.issues) {
+        const key = issue.path[0];
+
+        if (typeof key === 'string' && nextErrors[key as keyof Values] === undefined) {
+          nextErrors[key as keyof Values] = issue.message;
+        } else if (issue.path.length === 0 && nextFormError === null) {
+          nextFormError = issue.message;
+        }
+      }
+
+      setErrors(nextErrors);
+      setFormError(nextFormError);
+
+      return { ok: false };
+    },
+    [schema]
+  );
+
+  const setValue = useCallback(<Key extends keyof Values>(key: Key, value: Values[Key]) => {
+    setValuesState((currentValues) => ({ ...currentValues, [key]: value }));
+    // Editing an errored field clears its error; the next submit re-validates.
+    setErrors((currentErrors) => {
+      if (currentErrors[key] === undefined) {
+        return currentErrors;
+      }
+
+      const { [key]: _removed, ...rest } = currentErrors;
+
+      return rest as Partial<Record<keyof Values, string>>;
+    });
+  }, []);
+
+  const setValues = useCallback((nextValues: Values) => {
+    setValuesState(nextValues);
+  }, []);
+
+  const reset = useCallback((nextValues?: Values) => {
+    setValuesState(nextValues ?? initialValuesRef.current);
+    setErrors({});
+    setFormError(null);
+  }, []);
+
+  const handleSubmit = useCallback(
+    async (onValid: (validValues: Values) => Promise<void> | void) => {
+      const result = validate(values);
+
+      if (!result.ok) {
+        return;
+      }
+
+      setIsSubmitting(true);
+      setFormError(null);
+
+      try {
+        await onValid(result.data);
+      } catch (error) {
+        setFormError(error instanceof Error ? error.message : 'Something went wrong.');
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [validate, values]
+  );
+
+  return { errors, formError, handleSubmit, isSubmitting, reset, setValue, setValues, values };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/performanceMarks.test.ts b/invokeai/frontend/webv2/src/workbench/performanceMarks.test.ts
new file mode 100644
index 00000000000..e9ec506a917
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/performanceMarks.test.ts
@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearProjectDiagnostics, configureDiagnostics, getProjectDiagnostics } from './diagnostics/logger';
+import { markWorkbenchPerf, measureWorkbenchPerf, timeWorkbenchPerf } from './performanceMarks';
+
+beforeEach(() => {
+  clearProjectDiagnostics('project-a');
+  configureDiagnostics({
+    enabled: true,
+    level: 'trace',
+    namespaces: [],
+    performanceTimingsEnabled: true,
+  });
+  vi.spyOn(performance, 'mark').mockImplementation((name: string) => ({ name }) as PerformanceMark);
+  vi.spyOn(performance, 'measure').mockImplementation(
+    (name: string) => ({ duration: 12.34, name }) as PerformanceMeasure
+  );
+  vi.clearAllMocks();
+});
+
+describe('performanceMarks', () => {
+  it('does nothing when no diagnostic source is provided', () => {
+    markWorkbenchPerf('workflow:test');
+    measureWorkbenchPerf('workflow:measure', 'workflow:test');
+
+    expect(performance.mark).not.toHaveBeenCalled();
+    expect(performance.measure).not.toHaveBeenCalled();
+    expect(getProjectDiagnostics('project-a')).toEqual([]);
+  });
+
+  it('marks, measures and records timings for the provided diagnostic source', () => {
+    const source = { area: 'test', kind: 'workbench' as const, projectId: 'project-a' };
+    const result = timeWorkbenchPerf('workflow:build', source, () => 42);
+
+    expect(result).toBe(42);
+    expect(performance.mark).toHaveBeenCalledWith('workflow:build:start');
+    expect(performance.mark).toHaveBeenCalledWith('workflow:build:end');
+    expect(performance.measure).toHaveBeenCalledWith('workflow:build', 'workflow:build:start', 'workflow:build:end');
+    expect(getProjectDiagnostics('project-a')).toMatchObject([
+      { durationMs: 12.34, message: 'workflow:build completed in 12.3ms', namespace: 'performance', source },
+    ]);
+  });
+
+  it('does not call the Performance API when timing collection is disabled', () => {
+    configureDiagnostics({
+      enabled: true,
+      level: 'trace',
+      namespaces: [],
+      performanceTimingsEnabled: false,
+    });
+
+    const source = { area: 'test', kind: 'workbench' as const, projectId: 'project-a' };
+
+    timeWorkbenchPerf('workflow:build', source, () => 42);
+
+    expect(performance.mark).not.toHaveBeenCalled();
+    expect(performance.measure).not.toHaveBeenCalled();
+    expect(getProjectDiagnostics('project-a')).toEqual([]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/performanceMarks.ts b/invokeai/frontend/webv2/src/workbench/performanceMarks.ts
new file mode 100644
index 00000000000..5cd9d59a6fc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/performanceMarks.ts
@@ -0,0 +1,57 @@
+import { canRecordDiagnosticTiming, recordDiagnosticTiming, type DiagnosticSource } from './diagnostics/logger';
+
+const hasPerformanceApi = (): boolean => typeof performance !== 'undefined' && typeof performance.mark === 'function';
+
+const canMeasurePerf = (source?: DiagnosticSource): source is DiagnosticSource =>
+  hasPerformanceApi() && canRecordDiagnosticTiming(source);
+
+export const markWorkbenchPerf = (name: string, source?: DiagnosticSource): void => {
+  if (!canMeasurePerf(source)) {
+    return;
+  }
+
+  performance.mark(name);
+};
+
+export const measureWorkbenchPerf = (
+  name: string,
+  startMark: string,
+  source?: DiagnosticSource,
+  endMark?: string
+): void => {
+  if (!canMeasurePerf(source)) {
+    return;
+  }
+
+  try {
+    const measure = endMark ? performance.measure(name, startMark, endMark) : performance.measure(name, startMark);
+
+    recordDiagnosticTiming(source, measure.name, measure.duration);
+
+    performance.clearMeasures?.(name);
+    performance.clearMarks?.(startMark);
+    if (endMark) {
+      performance.clearMarks?.(endMark);
+    }
+  } catch {
+    // A missing mark should never affect workflow behavior.
+  }
+};
+
+export const timeWorkbenchPerf = <T>(name: string, source: DiagnosticSource | undefined, callback: () => T): T => {
+  if (!canMeasurePerf(source)) {
+    return callback();
+  }
+
+  const startMark = `${name}:start`;
+  const endMark = `${name}:end`;
+
+  markWorkbenchPerf(startMark, source);
+
+  try {
+    return callback();
+  } finally {
+    markWorkbenchPerf(endMark, source);
+    measureWorkbenchPerf(name, startMark, source, endMark);
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/persistence.test.ts b/invokeai/frontend/webv2/src/workbench/persistence.test.ts
new file mode 100644
index 00000000000..f8f1949cc53
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/persistence.test.ts
@@ -0,0 +1,129 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { localStorageWorkbenchPersistence, migrateWorkbenchPersistenceSnapshot } from './persistence';
+import { createInitialWorkbenchState, workbenchReducer } from './workbenchState';
+
+const storage = new Map<string, string>();
+
+vi.stubGlobal('window', {
+  localStorage: {
+    getItem: (key: string): string | null => storage.get(key) ?? null,
+    removeItem: (key: string): void => {
+      storage.delete(key);
+    },
+    setItem: (key: string, value: string): void => {
+      storage.set(key, value);
+    },
+  },
+});
+
+beforeEach(() => {
+  storage.clear();
+});
+
+describe('workbench persistence migration', () => {
+  it('accepts current versioned workbench snapshots', () => {
+    const state = createInitialWorkbenchState();
+    const snapshot = migrateWorkbenchPersistenceSnapshot({ savedAt: '2026-06-09T00:00:00.000Z', state, version: 1 });
+
+    expect(snapshot).toEqual({ savedAt: '2026-06-09T00:00:00.000Z', state, version: 1 });
+  });
+
+  it('migrates legacy schemaVersion snapshots to the authoritative version field', () => {
+    const state = createInitialWorkbenchState();
+    const snapshot = migrateWorkbenchPersistenceSnapshot({
+      savedAt: '2026-06-09T00:00:00.000Z',
+      schemaVersion: 1,
+      state,
+    });
+
+    expect(snapshot?.version).toBe(1);
+    expect(snapshot?.state.projects).toHaveLength(1);
+  });
+
+  it('drops legacy error logs from persisted snapshots', () => {
+    const state = { ...createInitialWorkbenchState(), errorLog: ['old error'] };
+    const snapshot = migrateWorkbenchPersistenceSnapshot({ savedAt: '2026-06-09T00:00:00.000Z', state, version: 1 });
+
+    expect(snapshot?.state).not.toHaveProperty('errorLog');
+  });
+
+  it('rejects unsupported persistence snapshots', () => {
+    expect(migrateWorkbenchPersistenceSnapshot({ state: createInitialWorkbenchState(), version: 999 })).toBeNull();
+    expect(migrateWorkbenchPersistenceSnapshot({ state: { projects: [] }, version: 1 })).toBeNull();
+  });
+
+  it('drops corrupt localStorage snapshots instead of throwing', async () => {
+    storage.set('invokeai:v7:webv2:workbench', '{not json');
+
+    await expect(localStorageWorkbenchPersistence.loadWorkbench()).resolves.toBeNull();
+    expect(storage.has('invokeai:v7:webv2:workbench')).toBe(false);
+  });
+
+  it('does not persist transient toast notifications', async () => {
+    const state = workbenchReducer(createInitialWorkbenchState(), {
+      kind: 'success',
+      message: 'Old toast',
+      title: 'Saved before reload',
+      type: 'recordNotice',
+    });
+
+    const snapshot = await localStorageWorkbenchPersistence.saveWorkbench(state);
+
+    expect(state.notifications).toHaveLength(1);
+    expect(snapshot.state.notifications).toEqual([]);
+
+    const raw = storage.get('invokeai:v7:webv2:workbench');
+    const persisted = JSON.parse(raw ?? 'null') as { state: { notifications: unknown[] } };
+
+    expect(persisted.state.notifications).toEqual([]);
+  });
+
+  it('treats localStorage quota failures as cache misses, not save failures', async () => {
+    const originalSet = window.localStorage.setItem;
+
+    try {
+      window.localStorage.setItem = (key: string, value: string): void => {
+        if (key === 'invokeai:v7:webv2:workbench') {
+          throw new DOMException('Quota exceeded', 'QuotaExceededError');
+        }
+
+        originalSet.call(window.localStorage, key, value);
+      };
+
+      await expect(
+        localStorageWorkbenchPersistence.saveWorkbench(createInitialWorkbenchState())
+      ).resolves.toMatchObject({
+        version: 1,
+      });
+    } finally {
+      window.localStorage.setItem = originalSet;
+    }
+  });
+
+  it('still attempts localStorage cache writes for large open workflow projects', async () => {
+    const state = createInitialWorkbenchState();
+    const project = state.projects[0]!;
+    const largeState = {
+      ...state,
+      projects: [
+        {
+          ...project,
+          projectGraph: {
+            ...project.projectGraph,
+            nodes: Array.from({ length: 300 }, (_, index) => ({
+              data: { label: '', notes: '' },
+              id: `node-${index}`,
+              position: { x: 0, y: 0 },
+              type: 'notes' as const,
+            })),
+          },
+        },
+      ],
+    };
+
+    await localStorageWorkbenchPersistence.saveWorkbench(largeState);
+
+    expect(storage.has('invokeai:v7:webv2:workbench')).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/persistence.ts b/invokeai/frontend/webv2/src/workbench/persistence.ts
new file mode 100644
index 00000000000..ebbb5c6cc81
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/persistence.ts
@@ -0,0 +1,119 @@
+import type { WorkbenchPersistenceSnapshot, WorkbenchState } from './types';
+
+import { getUserStorageScope } from './auth/session';
+import { timeWorkbenchPerf } from './performanceMarks';
+
+const BASE_STORAGE_KEY = 'invokeai:v7:webv2:workbench';
+const WORKBENCH_SCHEMA_VERSION = 1;
+
+/**
+ * Projects and the editor session are account-owned on multi-user backends, so
+ * each signed-in user gets their own storage bucket on this browser.
+ * Single-user mode keeps the unscoped key, so existing data is untouched.
+ */
+const getStorageKey = (): string => `${BASE_STORAGE_KEY}${getUserStorageScope()}`;
+
+export interface WorkbenchPersistenceService {
+  loadWorkbench(): Promise<WorkbenchPersistenceSnapshot | null>;
+  saveWorkbench(state: WorkbenchState): Promise<WorkbenchPersistenceSnapshot>;
+  clearWorkbench(): Promise<void>;
+}
+
+const isBrowser = (): boolean => typeof window !== 'undefined' && typeof window.localStorage !== 'undefined';
+
+export const stripTransientWorkbenchState = (state: WorkbenchState): WorkbenchState => {
+  const { errorLog: _legacyErrorLog, ...nextState } = state as WorkbenchState & { errorLog?: string[] };
+
+  return {
+    ...nextState,
+    notifications: [],
+  };
+};
+
+const createSnapshot = (state: WorkbenchState): WorkbenchPersistenceSnapshot => ({
+  savedAt: new Date().toISOString(),
+  state: stripTransientWorkbenchState(state),
+  version: WORKBENCH_SCHEMA_VERSION,
+});
+
+const isWorkbenchState = (value: unknown): value is WorkbenchState => {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  return Array.isArray(record.projects) && typeof record.activeProjectId === 'string';
+};
+
+export const migrateWorkbenchPersistenceSnapshot = (value: unknown): WorkbenchPersistenceSnapshot | null => {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+
+  const record = value as Partial<WorkbenchPersistenceSnapshot> & { schemaVersion?: number };
+  const version = record.version ?? record.schemaVersion;
+
+  if (version !== WORKBENCH_SCHEMA_VERSION || !isWorkbenchState(record.state)) {
+    return null;
+  }
+
+  return {
+    savedAt: typeof record.savedAt === 'string' ? record.savedAt : new Date().toISOString(),
+    state: stripTransientWorkbenchState(record.state),
+    version: WORKBENCH_SCHEMA_VERSION,
+  };
+};
+
+export const localStorageWorkbenchPersistence: WorkbenchPersistenceService = {
+  clearWorkbench() {
+    if (!isBrowser()) {
+      return Promise.resolve();
+    }
+
+    window.localStorage.removeItem(getStorageKey());
+
+    return Promise.resolve();
+  },
+  loadWorkbench() {
+    if (!isBrowser()) {
+      return Promise.resolve(null);
+    }
+
+    const value = window.localStorage.getItem(getStorageKey());
+
+    if (!value) {
+      return Promise.resolve(null);
+    }
+
+    try {
+      return Promise.resolve(migrateWorkbenchPersistenceSnapshot(JSON.parse(value)));
+    } catch {
+      window.localStorage.removeItem(getStorageKey());
+
+      return Promise.resolve(null);
+    }
+  },
+  saveWorkbench(state) {
+    const snapshot = createSnapshot(state);
+
+    if (!isBrowser()) {
+      return Promise.resolve(snapshot);
+    }
+
+    try {
+      window.localStorage.setItem(
+        getStorageKey(),
+        timeWorkbenchPerf(
+          'workbench:persistence-localstorage-stringify',
+          { area: 'persistence', kind: 'workbench', projectId: state.activeProjectId },
+          () => JSON.stringify(snapshot)
+        )
+      );
+    } catch {
+      // The backend remains the source of truth; localStorage is only an offline cache.
+    }
+
+    return Promise.resolve(snapshot);
+  },
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/api.ts b/invokeai/frontend/webv2/src/workbench/projects/api.ts
new file mode 100644
index 00000000000..22dc8c55fe3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/api.ts
@@ -0,0 +1,74 @@
+import { ApiError, apiFetch, apiFetchJson } from '@workbench/backend/http';
+
+/**
+ * REST surface for server-side project persistence (`/api/v1/projects`) and
+ * the per-user client-state KV (`/api/v1/client_state`) that holds the small
+ * account-scoped workbench blob. Both work in single-user mode too — the
+ * backend scopes them to the system user.
+ */
+
+const PROJECTS_BASE = '/api/v1/projects';
+// The path's queue segment is ignored by the backend (kept for compatibility).
+const CLIENT_STATE_BASE = '/api/v1/client_state/default';
+
+export interface ProjectSummaryDTO {
+  project_id: string;
+  name: string;
+  revision: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ProjectRecordDTO extends ProjectSummaryDTO {
+  data: Record<string, unknown>;
+}
+
+export interface ProjectCreateRequest {
+  project_id?: string;
+  name: string;
+  data: Record<string, unknown>;
+}
+
+export interface ProjectUpdateRequest {
+  name: string;
+  data: Record<string, unknown>;
+  expected_revision: number;
+}
+
+export const listProjects = (): Promise<ProjectSummaryDTO[]> => apiFetchJson<ProjectSummaryDTO[]>(`${PROJECTS_BASE}/`);
+
+export const getProject = (projectId: string): Promise<ProjectRecordDTO> =>
+  apiFetchJson<ProjectRecordDTO>(`${PROJECTS_BASE}/${encodeURIComponent(projectId)}`);
+
+export const createProject = (request: ProjectCreateRequest): Promise<ProjectRecordDTO> =>
+  apiFetchJson<ProjectRecordDTO>(`${PROJECTS_BASE}/`, { body: JSON.stringify(request), method: 'POST' });
+
+export const updateProject = (projectId: string, request: ProjectUpdateRequest): Promise<ProjectRecordDTO> =>
+  apiFetchJson<ProjectRecordDTO>(`${PROJECTS_BASE}/${encodeURIComponent(projectId)}`, {
+    body: JSON.stringify(request),
+    method: 'PUT',
+  });
+
+export const deleteProject = async (projectId: string): Promise<void> => {
+  await apiFetch(`${PROJECTS_BASE}/${encodeURIComponent(projectId)}`, { method: 'DELETE' });
+};
+
+/** A save was based on a stale revision — another tab or device saved first. */
+export const isProjectConflictError = (error: unknown): boolean => error instanceof ApiError && error.status === 409;
+
+export const isProjectNotFoundError = (error: unknown): boolean => error instanceof ApiError && error.status === 404;
+
+export const getClientStateValue = (key: string): Promise<string | null> =>
+  apiFetchJson<string | null>(`${CLIENT_STATE_BASE}/get_by_key?key=${encodeURIComponent(key)}`);
+
+/** The endpoint takes a JSON-encoded string body, hence the stringify of a string. */
+export const setClientStateValue = async (key: string, value: string): Promise<void> => {
+  await apiFetchJson<string>(`${CLIENT_STATE_BASE}/set_by_key?key=${encodeURIComponent(key)}`, {
+    body: JSON.stringify(value),
+    method: 'POST',
+  });
+};
+
+export const deleteClientStateValue = async (key: string): Promise<void> => {
+  await apiFetch(`${CLIENT_STATE_BASE}/delete_by_key?key=${encodeURIComponent(key)}`, { method: 'POST' });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/components/OpenProjectDialog.tsx b/invokeai/frontend/webv2/src/workbench/projects/components/OpenProjectDialog.tsx
new file mode 100644
index 00000000000..d5d4ef07b59
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/components/OpenProjectDialog.tsx
@@ -0,0 +1,178 @@
+import { Dialog, Icon, Portal, Spinner, Stack, Text } from '@chakra-ui/react';
+import { Button, CloseButton, Row, Scrollable } from '@workbench/components/ui';
+import { formatRelativeTime } from '@workbench/launchpad/formatRelativeTime';
+import { refreshProjectLibrary, useProjectLibrarySelector, type ProjectSummary } from '@workbench/projects/library';
+import { importProjectFile, pickProjectFile } from '@workbench/projects/projectFile';
+import { adoptProjectRecord, hydrateProjectFromServer } from '@workbench/projects/syncedPersistence';
+import { useNotify } from '@workbench/useNotify';
+import { flushGenerateDrafts } from '@workbench/widgets/generate/generateDraftRegistry';
+import { useWorkbenchDispatch, useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { areArraysEqual } from '@workbench/workbenchSelectors';
+import { ArrowRightIcon, FileUpIcon } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const disabledRowStyles = { opacity: 0.6 } as const;
+
+/**
+ * "Open project…" from the tab bar: the saved projects that are not already
+ * open as tabs, plus import. Selecting one hydrates its document from the
+ * library and opens it in place — no navigation, the editor stays mounted.
+ */
+export const OpenProjectDialog = ({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) => {
+  const projectIds = useWorkbenchSelector(
+    (snapshot) => snapshot.state.projects.map((project) => project.id),
+    areArraysEqual
+  );
+  const dispatch = useWorkbenchDispatch();
+  const notify = useNotify();
+  const { t } = useTranslation();
+  const summaries = useProjectLibrarySelector((snapshot) => snapshot.summaries);
+  const [busyProjectId, setBusyProjectId] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      void refreshProjectLibrary();
+    }
+  }, [isOpen]);
+
+  const openProjectIds = useMemo(() => new Set(projectIds), [projectIds]);
+  const available = useMemo(
+    () => summaries.filter((summary) => !openProjectIds.has(summary.id)),
+    [openProjectIds, summaries]
+  );
+
+  const openProject = useCallback(
+    async (summary: ProjectSummary) => {
+      setBusyProjectId(summary.id);
+
+      const project = await hydrateProjectFromServer(summary.id);
+
+      setBusyProjectId(null);
+
+      if (!project) {
+        notify.error(t('projects.couldNotOpen'), t('projects.couldNotOpenDescription', { name: summary.name }));
+        void refreshProjectLibrary();
+
+        return;
+      }
+
+      flushGenerateDrafts();
+      dispatch({ project, type: 'openProject' });
+      onClose();
+    },
+    [dispatch, notify, onClose, t]
+  );
+
+  const handleImport = useCallback(async () => {
+    const file = await pickProjectFile();
+
+    if (!file) {
+      return;
+    }
+
+    try {
+      const record = await importProjectFile(file);
+      const project = adoptProjectRecord(record);
+
+      if (project) {
+        flushGenerateDrafts();
+        dispatch({ project, type: 'openProject' });
+        onClose();
+      }
+    } catch (error) {
+      notify.error(t('projects.importFailed'), error instanceof Error ? error.message : undefined);
+    }
+  }, [dispatch, notify, onClose, t]);
+
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  const startImport = useCallback(() => void handleImport(), [handleImport]);
+
+  return (
+    <Dialog.Root lazyMount open={isOpen} placement="center" size="sm" unmountOnExit onOpenChange={handleOpenChange}>
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Header>
+              <Dialog.Title fontSize="sm" fontWeight="700">
+                {t('projects.openProject')}
+              </Dialog.Title>
+            </Dialog.Header>
+            <Dialog.Body>
+              <Scrollable maxH="72">
+                <Stack gap="1">
+                  {available.map((summary) => (
+                    <OpenProjectRow
+                      key={summary.id}
+                      isBusy={busyProjectId === summary.id}
+                      isDisabled={busyProjectId !== null}
+                      summary={summary}
+                      onOpen={openProject}
+                    />
+                  ))}
+                  {available.length === 0 ? (
+                    <Text color="fg.muted" fontSize="xs" px="2.5" py="4" textAlign="center">
+                      {summaries.length === 0 ? t('projects.noSavedProjects') : t('projects.allSavedAlreadyOpen')}
+                    </Text>
+                  ) : null}
+                </Stack>
+              </Scrollable>
+            </Dialog.Body>
+            <Dialog.Footer gap="2" justifyContent="space-between">
+              <Button size="xs" variant="outline" onClick={startImport}>
+                <FileUpIcon />
+                {t('projects.importWithEllipsis')}
+              </Button>
+              <Button size="xs" variant="ghost" onClick={onClose}>
+                {t('common.cancel')}
+              </Button>
+            </Dialog.Footer>
+            <Dialog.CloseTrigger asChild>
+              <CloseButton color="fg.muted" size="sm" />
+            </Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
+
+const OpenProjectRow = ({
+  isBusy,
+  isDisabled,
+  onOpen,
+  summary,
+}: {
+  isBusy: boolean;
+  isDisabled: boolean;
+  onOpen: (summary: ProjectSummary) => Promise<void>;
+  summary: ProjectSummary;
+}) => {
+  const open = useCallback(() => void onOpen(summary), [onOpen, summary]);
+  const { t } = useTranslation();
+
+  return (
+    <Row asChild gap="2.5" px="2.5" py="2" rounded="md" _disabled={disabledRowStyles}>
+      <button disabled={isDisabled} type="button" onClick={open}>
+        <Stack flex="1" gap="0" minW="0">
+          <Text fontSize="xs" fontWeight="600" truncate>
+            {summary.name}
+          </Text>
+          <Text color="fg.muted" fontSize="2xs">
+            {t('projects.editedRelative', { time: formatRelativeTime(summary.updatedAt) })}
+          </Text>
+        </Stack>
+        {isBusy ? <Spinner color="fg.muted" size="xs" /> : <Icon as={ArrowRightIcon} boxSize="3.5" color="fg.muted" />}
+      </button>
+    </Row>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/components/ProjectTabs.tsx b/invokeai/frontend/webv2/src/workbench/projects/components/ProjectTabs.tsx
new file mode 100644
index 00000000000..ed03ba995c1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/components/ProjectTabs.tsx
@@ -0,0 +1,440 @@
+/* eslint-disable react/react-compiler */
+import type { Project, QueueItem, WidgetRegion } from '@workbench/types';
+
+import { Icon, Menu, Portal, Separator } from '@chakra-ui/react';
+import { useModelLoads } from '@workbench/backend/modelLoadStore';
+import { useQueueItemProgress } from '@workbench/backend/progressStore';
+import { QueueCircularProgress } from '@workbench/components/QueueProgressIndicator';
+import {
+  CloseButton,
+  IconButton,
+  ConfirmDialog,
+  MenuContent,
+  RenameDialog,
+  Tabs,
+  Tooltip,
+} from '@workbench/components/ui';
+import { exportOpenProject } from '@workbench/projects/projectFile';
+import { useProjectActions } from '@workbench/projects/useProjectActions';
+import { getProjectQueueIndicatorState } from '@workbench/queueSummary';
+import { useOpenWorkbenchWidget } from '@workbench/useOpenWorkbenchWidget';
+import { flushGenerateDrafts } from '@workbench/widgets/generate/generateDraftRegistry';
+import {
+  useActiveProjectSelector,
+  useWorkbenchDispatch,
+  useWorkbenchSelector,
+  useWorkbenchStore,
+} from '@workbench/WorkbenchContext';
+import {
+  FileDownIcon,
+  FolderCogIcon,
+  FolderIcon,
+  FolderOpenIcon,
+  PencilIcon,
+  PlusIcon,
+  Trash2Icon,
+  XIcon,
+} from 'lucide-react';
+import { useCallback, useMemo, useRef, useState, type MouseEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { OpenProjectDialog } from './OpenProjectDialog';
+
+interface ProjectTabSummary {
+  id: string;
+  name: string;
+  queueItems: QueueItem[];
+}
+
+const areProjectTabSummariesEqual = (
+  left: readonly ProjectTabSummary[],
+  right: readonly ProjectTabSummary[]
+): boolean =>
+  left.length === right.length &&
+  left.every(
+    (summary, index) =>
+      summary.id === right[index]?.id &&
+      summary.name === right[index]?.name &&
+      summary.queueItems === right[index]?.queueItems
+  );
+
+const selectProjectTabSummaries = (projects: readonly Project[]): ProjectTabSummary[] =>
+  projects.map(({ id, name, queue }) => ({ id, name, queueItems: queue.items }));
+
+const deleteMenuItemHover = { bg: 'bg.error', color: 'fg.error' } as const;
+
+/**
+ * Document-style tabs for the open projects (the session), immediately right
+ * of the Invoke control. Tabs are not the library: closing one only removes
+ * it from the session — the project stays saved and reopens through the
+ * folder button's Open Project dialog. Closing the last tab lands on Home.
+ *
+ * Each tab is a container with two real buttons (select + close) rather than
+ * the prototype's invalid button-nested-in-button, so keyboard focus and
+ * click targets behave correctly. Right-clicking a tab opens a context menu
+ * with rename, details, export, close, and delete.
+ */
+export const ProjectTabs = () => {
+  const { t } = useTranslation();
+  const projectTabSummaries = useWorkbenchSelector(
+    (snapshot) => selectProjectTabSummaries(snapshot.state.projects),
+    areProjectTabSummariesEqual
+  );
+  const activeProjectId = useActiveProjectSelector((project) => project.id);
+  const backendConnectionStatus = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status);
+  const modelLoads = useModelLoads();
+  const store = useWorkbenchStore();
+  const dispatch = useWorkbenchDispatch();
+  const { closeProject, deleteProject } = useProjectActions();
+  const [menuTarget, setMenuTarget] = useState<{ project: ProjectTabSummary; x: number; y: number } | null>(null);
+  const [renameTarget, setRenameTarget] = useState<ProjectTabSummary | null>(null);
+  const [deleteTarget, setDeleteTarget] = useState<ProjectTabSummary | null>(null);
+  const [isOpenDialogVisible, setIsOpenDialogVisible] = useState(false);
+
+  const getProject = useCallback(
+    (projectId: string): Project | null =>
+      store.getState().projects.find((project) => project.id === projectId) ?? null,
+    [store]
+  );
+
+  const onSwitchProject = useCallback(
+    (projectId: string) => {
+      flushGenerateDrafts();
+      dispatch({ projectId, type: 'switchProject' });
+    },
+    [dispatch]
+  );
+
+  const openContextMenu = useCallback((project: ProjectTabSummary, event: MouseEvent) => {
+    event.preventDefault();
+    setMenuTarget({ project, x: event.clientX, y: event.clientY });
+  }, []);
+
+  const createProject = useCallback(() => {
+    flushGenerateDrafts();
+    dispatch({ type: 'createProject' });
+  }, [dispatch]);
+
+  const showOpenDialog = useCallback(() => setIsOpenDialogVisible(true), []);
+  const hideOpenDialog = useCallback(() => setIsOpenDialogVisible(false), []);
+
+  const closeMenu = useCallback(() => setMenuTarget(null), []);
+  const closeRenameDialog = useCallback(() => setRenameTarget(null), []);
+  const closeDeleteDialog = useCallback(() => setDeleteTarget(null), []);
+
+  const startRename = useCallback((project: ProjectTabSummary) => setRenameTarget(project), []);
+  const startDelete = useCallback((project: ProjectTabSummary) => setDeleteTarget(project), []);
+
+  const closeProjectBySummary = useCallback(
+    (project: ProjectTabSummary) => {
+      const currentProject = getProject(project.id);
+
+      if (currentProject) {
+        closeProject(currentProject);
+      }
+    },
+    [closeProject, getProject]
+  );
+
+  const renameProject = useCallback(
+    (name: string) => {
+      if (renameTarget) {
+        dispatch({ name, projectId: renameTarget.id, type: 'renameProject' });
+      }
+    },
+    [dispatch, renameTarget]
+  );
+
+  const confirmDeleteProject = useCallback(async () => {
+    if (deleteTarget) {
+      const currentProject = getProject(deleteTarget.id);
+
+      if (currentProject) {
+        await deleteProject(currentProject);
+      }
+    }
+  }, [deleteProject, deleteTarget, getProject]);
+
+  return (
+    <>
+      <Tabs.Root minW="max-content" variant="subtle" value={activeProjectId} h="full" w="full">
+        <Tabs.List flex="1 1 auto" h="full" py="1">
+          {projectTabSummaries.map((project) => (
+            <ProjectTab
+              key={project.id}
+              backendConnectionStatus={backendConnectionStatus}
+              isActive={project.id === activeProjectId}
+              loadingModelsCount={modelLoads.length}
+              project={project}
+              onCloseProject={closeProjectBySummary}
+              onContextMenu={openContextMenu}
+              onSwitchProject={onSwitchProject}
+            />
+          ))}
+
+          <Separator orientation="vertical" h={5} mx="1" alignSelf="center" />
+
+          <Tooltip content={t('projects.createNewProject')} showArrow>
+            <IconButton
+              aria-label={t('projects.createNewProject')}
+              flexShrink={0}
+              size="xs"
+              variant="ghost"
+              alignSelf="center"
+              onClick={createProject}
+            >
+              <PlusIcon />
+            </IconButton>
+          </Tooltip>
+
+          <Tooltip content={t('projects.openProject')} showArrow>
+            <IconButton
+              aria-label={t('projects.openProject')}
+              flexShrink={0}
+              size="xs"
+              variant="ghost"
+              alignSelf="center"
+              onClick={showOpenDialog}
+            >
+              <FolderOpenIcon />
+            </IconButton>
+          </Tooltip>
+        </Tabs.List>
+      </Tabs.Root>
+
+      <ProjectTabContextMenu
+        target={menuTarget}
+        onClose={closeMenu}
+        onCloseProject={closeProjectBySummary}
+        onDelete={startDelete}
+        onRename={startRename}
+      />
+      <RenameDialog
+        initialName={renameTarget?.name ?? ''}
+        isOpen={renameTarget !== null}
+        onClose={closeRenameDialog}
+        onSubmit={renameProject}
+      />
+      <ConfirmDialog
+        body={t('projects.deleteProjectTabBody', { name: deleteTarget?.name ?? '' })}
+        confirmLabel={t('projects.deleteProject')}
+        isOpen={deleteTarget !== null}
+        title={t('projects.deleteProjectQuestion')}
+        onClose={closeDeleteDialog}
+        onConfirm={confirmDeleteProject}
+      />
+      {isOpenDialogVisible ? <OpenProjectDialog isOpen onClose={hideOpenDialog} /> : null}
+    </>
+  );
+};
+
+const ProjectTab = ({
+  backendConnectionStatus,
+  isActive,
+  loadingModelsCount,
+  onCloseProject,
+  onContextMenu,
+  onSwitchProject,
+  project,
+}: {
+  backendConnectionStatus: string;
+  isActive: boolean;
+  loadingModelsCount: number;
+  onCloseProject: (project: ProjectTabSummary) => void;
+  onContextMenu: (project: ProjectTabSummary, event: MouseEvent) => void;
+  onSwitchProject: (projectId: string) => void;
+  project: ProjectTabSummary;
+}) => {
+  const baseIndicatorState = getProjectQueueIndicatorState({
+    isConnected: backendConnectionStatus === 'connected',
+    loadingModelsCount,
+    progress: null,
+    queueItems: project.queueItems,
+  });
+  const progress = useQueueItemProgress(baseIndicatorState.runningQueueItemId ?? '');
+  const { progressState } = getProjectQueueIndicatorState({
+    isConnected: backendConnectionStatus === 'connected',
+    loadingModelsCount,
+    progress,
+    queueItems: project.queueItems,
+  });
+  const switchProject = useCallback(() => onSwitchProject(project.id), [onSwitchProject, project.id]);
+  const { t } = useTranslation();
+  const openContextMenu = useCallback((event: MouseEvent) => onContextMenu(project, event), [onContextMenu, project]);
+
+  const closeProject = useCallback(
+    (event: MouseEvent) => {
+      event.stopPropagation();
+      onCloseProject(project);
+    },
+    [onCloseProject, project]
+  );
+
+  return (
+    <Tabs.Trigger value={project.id} onClick={switchProject} onContextMenu={openContextMenu} fontSize="xs" h="full">
+      {progressState.kind === 'idle' ? (
+        <Icon as={isActive ? FolderOpenIcon : FolderIcon} boxSize="4" />
+      ) : (
+        <QueueCircularProgress size="2xs" state={progressState} />
+      )}
+
+      {project.name}
+
+      <CloseButton
+        size="2xs"
+        me="-2"
+        as="span"
+        role="button"
+        aria-label={t('projects.closeProjectLabel', { name: project.name })}
+        onClick={closeProject}
+      />
+    </Tabs.Trigger>
+  );
+};
+
+const ProjectTabContextMenu = ({
+  onClose,
+  onCloseProject,
+  onDelete,
+  onRename,
+  target,
+}: {
+  onClose: () => void;
+  onCloseProject: (project: ProjectTabSummary) => void;
+  onDelete: (project: ProjectTabSummary) => void;
+  onRename: (project: ProjectTabSummary) => void;
+  target: { project: ProjectTabSummary; x: number; y: number } | null;
+}) => {
+  const dispatch = useWorkbenchDispatch();
+  const store = useWorkbenchStore();
+  const openWorkbenchWidget = useOpenWorkbenchWidget();
+  const targetRef = useRef(target);
+  const { t } = useTranslation();
+
+  targetRef.current = target;
+
+  const positioning = useMemo(
+    () => ({
+      getAnchorRect: () => {
+        const currentTarget = targetRef.current;
+
+        return currentTarget ? { height: 1, width: 1, x: currentTarget.x, y: currentTarget.y } : null;
+      },
+      placement: 'bottom-start' as const,
+    }),
+    []
+  );
+
+  const openProjectDetails = useCallback(
+    (projectSummary: ProjectTabSummary) => {
+      const project = store.getState().projects.find((candidate) => candidate.id === projectSummary.id);
+
+      if (!project) {
+        return;
+      }
+
+      flushGenerateDrafts();
+      dispatch({ projectId: project.id, type: 'switchProject' });
+
+      // Reveal the Project panel wherever the project already shows it; default
+      // to enabling it in the right rail. Both actions operate on the active
+      // project, which the switch above just made this one.
+      const { left, right } = project.widgetRegions;
+      const region = right.instanceIds.some((instanceId) => project.widgetInstances[instanceId]?.typeId === 'project')
+        ? 'right'
+        : left.instanceIds.some((instanceId) => project.widgetInstances[instanceId]?.typeId === 'project')
+          ? 'left'
+          : null;
+      const preferredRegions: WidgetRegion[] = [region ?? 'right'];
+
+      openWorkbenchWidget('project', { preferredRegions });
+    },
+    [dispatch, openWorkbenchWidget, store]
+  );
+
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  const renameTarget = useCallback(() => {
+    if (targetRef.current) {
+      onRename(targetRef.current.project);
+    }
+  }, [onRename]);
+
+  const showDetails = useCallback(() => {
+    if (targetRef.current) {
+      openProjectDetails(targetRef.current.project);
+    }
+  }, [openProjectDetails]);
+
+  const exportProject = useCallback(() => {
+    const currentTarget = targetRef.current;
+    const project = currentTarget
+      ? store.getState().projects.find((candidate) => candidate.id === currentTarget.project.id)
+      : null;
+
+    if (project) {
+      exportOpenProject(project);
+    }
+  }, [store]);
+
+  const closeTargetProject = useCallback(() => {
+    if (targetRef.current) {
+      onCloseProject(targetRef.current.project);
+    }
+  }, [onCloseProject]);
+
+  const deleteTargetProject = useCallback(() => {
+    if (targetRef.current) {
+      onDelete(targetRef.current.project);
+    }
+  }, [onDelete]);
+
+  return (
+    <Menu.Root
+      key={target?.project.id ?? 'closed'}
+      lazyMount
+      open={target !== null}
+      positioning={positioning}
+      unmountOnExit
+      onOpenChange={handleOpenChange}
+    >
+      <Portal>
+        <Menu.Positioner>
+          {target ? (
+            <MenuContent minW="44">
+              <Menu.Item value="rename" onClick={renameTarget}>
+                <Icon as={PencilIcon} boxSize="3.5" />
+                {t('projects.renameWithEllipsis')}
+              </Menu.Item>
+              <Menu.Item value="details" onClick={showDetails}>
+                <Icon as={FolderCogIcon} boxSize="3.5" />
+                {t('projects.projectDetails')}
+              </Menu.Item>
+              <Menu.Item value="export" onClick={exportProject}>
+                <Icon as={FileDownIcon} boxSize="3.5" />
+                {t('common.export')}
+              </Menu.Item>
+              <Menu.Separator />
+              <Menu.Item value="close" onClick={closeTargetProject}>
+                <Icon as={XIcon} boxSize="3.5" />
+                {t('common.close')}
+              </Menu.Item>
+              <Menu.Separator />
+              <Menu.Item color="fg.error" value="delete" _hover={deleteMenuItemHover} onClick={deleteTargetProject}>
+                <Icon as={Trash2Icon} boxSize="3.5" />
+                {t('projects.deleteProjectWithEllipsis')}
+              </Menu.Item>
+            </MenuContent>
+          ) : null}
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/components/index.ts b/invokeai/frontend/webv2/src/workbench/projects/components/index.ts
new file mode 100644
index 00000000000..178087dfee3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/components/index.ts
@@ -0,0 +1,2 @@
+export { OpenProjectDialog } from './OpenProjectDialog';
+export { ProjectTabs } from './ProjectTabs';
diff --git a/invokeai/frontend/webv2/src/workbench/projects/ids.ts b/invokeai/frontend/webv2/src/workbench/projects/ids.ts
new file mode 100644
index 00000000000..aa49a5051c7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/ids.ts
@@ -0,0 +1,8 @@
+/**
+ * Client-generated project ids. The backend treats `(user_id, project_id)` as
+ * the primary key and never mints ids itself, so uniqueness only has to hold
+ * per user; the timestamp+entropy shape keeps ids unique across devices and
+ * across deleted-then-recreated projects.
+ */
+export const createProjectId = (): string =>
+  `project-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
diff --git a/invokeai/frontend/webv2/src/workbench/projects/library.test.ts b/invokeai/frontend/webv2/src/workbench/projects/library.test.ts
new file mode 100644
index 00000000000..4d6d7d321d8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/library.test.ts
@@ -0,0 +1,143 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type * as libraryModule from './library';
+
+/**
+ * The project library store: summaries normalized at the boundary, sorted by
+ * recency, and the explicit mutations (delete, rename, duplicate) that are
+ * the only paths off the server.
+ */
+
+const api = vi.hoisted(() => ({
+  createProject: vi.fn(),
+  deleteProject: vi.fn(),
+  getProject: vi.fn(),
+  listProjects: vi.fn(),
+  updateProject: vi.fn(),
+}));
+
+vi.mock('./api', () => api);
+
+let library: typeof libraryModule;
+
+const summaryDto = (id: string, name: string, updatedAt: string) => ({
+  created_at: '2026-06-01 08:00:00.000',
+  name,
+  project_id: id,
+  revision: 1,
+  updated_at: updatedAt,
+});
+
+beforeEach(async () => {
+  vi.resetModules();
+  api.createProject.mockReset();
+  api.deleteProject.mockReset();
+  api.getProject.mockReset();
+  api.listProjects.mockReset();
+  api.updateProject.mockReset();
+
+  library = await import('./library');
+});
+
+describe('refreshProjectLibrary', () => {
+  it('normalizes SQLite timestamps to ISO and sorts newest first', async () => {
+    api.listProjects.mockResolvedValue([
+      summaryDto('older', 'Older', '2026-06-09 10:00:00.000'),
+      summaryDto('newer', 'Newer', '2026-06-10 10:00:00.000'),
+    ]);
+
+    await library.refreshProjectLibrary();
+
+    const { status, summaries } = library.getProjectLibrary();
+
+    expect(status).toBe('ready');
+    expect(summaries.map((summary) => summary.id)).toEqual(['newer', 'older']);
+    expect(summaries[0].updatedAt).toBe('2026-06-10T10:00:00.000Z');
+  });
+
+  it('keeps the previous summaries and reports the failure on error', async () => {
+    api.listProjects.mockResolvedValue([summaryDto('kept', 'Kept', '2026-06-10 10:00:00.000')]);
+    await library.refreshProjectLibrary();
+
+    api.listProjects.mockRejectedValue(new Error('offline'));
+    await library.refreshProjectLibrary();
+
+    const { error, status, summaries } = library.getProjectLibrary();
+
+    expect(status).toBe('error');
+    expect(error).toBe('offline');
+    expect(summaries.map((summary) => summary.id)).toEqual(['kept']);
+  });
+});
+
+describe('upsertProjectSummary', () => {
+  it('inserts new entries and moves updated ones to the front', async () => {
+    api.listProjects.mockResolvedValue([
+      summaryDto('a', 'A', '2026-06-09 10:00:00.000'),
+      summaryDto('b', 'B', '2026-06-10 10:00:00.000'),
+    ]);
+    await library.refreshProjectLibrary();
+
+    library.upsertProjectSummary({ id: 'a', name: 'A renamed', revision: 2 });
+
+    const { summaries } = library.getProjectLibrary();
+
+    expect(summaries[0].id).toBe('a');
+    expect(summaries[0].name).toBe('A renamed');
+    expect(summaries[0].revision).toBe(2);
+  });
+});
+
+describe('library mutations', () => {
+  it('deleteLibraryProject removes from server and store', async () => {
+    api.listProjects.mockResolvedValue([summaryDto('doomed', 'Doomed', '2026-06-10 10:00:00.000')]);
+    await library.refreshProjectLibrary();
+    api.deleteProject.mockResolvedValue(undefined);
+
+    await library.deleteLibraryProject('doomed');
+
+    expect(api.deleteProject).toHaveBeenCalledWith('doomed');
+    expect(library.getProjectLibrary().summaries).toHaveLength(0);
+  });
+
+  it('renameLibraryProject updates name in both the record and its document', async () => {
+    api.getProject.mockResolvedValue({
+      ...summaryDto('p1', 'Old name', '2026-06-10 10:00:00.000'),
+      data: { id: 'p1', layout: {}, name: 'Old name' },
+    });
+    api.updateProject.mockResolvedValue({
+      ...summaryDto('p1', 'New name', '2026-06-10 11:00:00.000'),
+      data: { id: 'p1', layout: {}, name: 'New name' },
+      revision: 2,
+    });
+
+    await library.renameLibraryProject('p1', 'New name');
+
+    expect(api.updateProject).toHaveBeenCalledWith('p1', {
+      data: { id: 'p1', layout: {}, name: 'New name' },
+      expected_revision: 1,
+      name: 'New name',
+    });
+    expect(library.getProjectLibrary().summaries[0]?.name).toBe('New name');
+  });
+
+  it('duplicateLibraryProject copies under a fresh id', async () => {
+    api.getProject.mockResolvedValue({
+      ...summaryDto('source', 'Source', '2026-06-10 10:00:00.000'),
+      data: { id: 'source', layout: {}, name: 'Source' },
+    });
+    api.createProject.mockImplementation((request: { project_id?: string; name: string }) =>
+      Promise.resolve({ ...summaryDto(request.project_id ?? '', request.name, '2026-06-10 11:00:00.000'), data: {} })
+    );
+
+    const copy = await library.duplicateLibraryProject('source');
+
+    expect(copy.id).not.toBe('source');
+    expect(copy.name).toBe('Source copy');
+
+    const createRequest = api.createProject.mock.calls[0][0] as { data: Record<string, unknown>; project_id: string };
+
+    expect(createRequest.data.id).toBe(createRequest.project_id);
+    expect(createRequest.data.name).toBe('Source copy');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/projects/library.ts b/invokeai/frontend/webv2/src/workbench/projects/library.ts
new file mode 100644
index 00000000000..1c3654d7006
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/library.ts
@@ -0,0 +1,162 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+import {
+  createProject as apiCreateProject,
+  deleteProject as apiDeleteProject,
+  getProject as apiGetProject,
+  listProjects,
+  updateProject as apiUpdateProject,
+  type ProjectSummaryDTO,
+} from './api';
+import { createProjectId } from './ids';
+
+/**
+ * The project library: every project saved on the server for the current
+ * user, as lightweight summaries (no documents). The Home screen, the Open
+ * Project dialog, and the editor's save pass all read and patch this one
+ * store, so "what projects exist" has a single answer everywhere.
+ *
+ * The library is intentionally separate from the workbench session: open tabs
+ * hold hydrated documents in workbench state, while the library only knows
+ * metadata. Deleting through the library is the only way a project leaves the
+ * server — closing a tab never does.
+ */
+
+export interface ProjectSummary {
+  id: string;
+  name: string;
+  revision: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type ProjectLibraryStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+export interface ProjectLibrarySnapshot {
+  status: ProjectLibraryStatus;
+  summaries: ProjectSummary[];
+  error?: string;
+}
+
+const store = createExternalStore<ProjectLibrarySnapshot>({ status: 'idle', summaries: [] });
+
+/**
+ * The backend stamps timestamps via SQLite ("2026-06-11 09:21:04.123") —
+ * UTC, but with no timezone marker, which `Date` would misread as local
+ * time. Normalize to ISO once, here at the boundary.
+ */
+const normalizeServerTimestamp = (value: string): string => {
+  if (!/^\d{4}-\d{2}-\d{2} /.test(value)) {
+    return value;
+  }
+
+  const date = new Date(`${value.replace(' ', 'T')}Z`);
+
+  return Number.isNaN(date.getTime()) ? value : date.toISOString();
+};
+
+const toSummary = (dto: ProjectSummaryDTO): ProjectSummary => ({
+  createdAt: normalizeServerTimestamp(dto.created_at),
+  id: dto.project_id,
+  name: dto.name,
+  revision: dto.revision,
+  updatedAt: normalizeServerTimestamp(dto.updated_at),
+});
+
+/** Most recently edited first — the order Home and the Open dialog present. */
+const sortSummaries = (summaries: ProjectSummary[]): ProjectSummary[] =>
+  [...summaries].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+
+export const useProjectLibrary = (): ProjectLibrarySnapshot => store.useSnapshot();
+
+export const useProjectLibrarySelector = store.useSelector;
+
+export const getProjectLibrary = (): ProjectLibrarySnapshot => store.getSnapshot();
+
+/** Adopt summaries already fetched elsewhere (the workbench boot pass). */
+export const seedProjectLibrary = (dtos: ProjectSummaryDTO[]): void => {
+  store.setSnapshot({ status: 'ready', summaries: sortSummaries(dtos.map(toSummary)) });
+};
+
+let pendingRefresh: Promise<void> | null = null;
+
+/** Re-list from the server; concurrent calls share one request. */
+export const refreshProjectLibrary = (): Promise<void> => {
+  pendingRefresh ??= listProjects()
+    .then((dtos) => {
+      seedProjectLibrary(dtos);
+    })
+    .catch((error: unknown) => {
+      store.patchSnapshot({
+        error: error instanceof Error ? error.message : 'Failed to load projects.',
+        status: 'error',
+      });
+    })
+    .finally(() => {
+      pendingRefresh = null;
+    });
+
+  return pendingRefresh;
+};
+
+/**
+ * Reflect a save the editor just pushed, so the library stays current without
+ * a refetch. `updatedAt` is stamped locally; the next refresh replaces it
+ * with the server's value.
+ */
+export const upsertProjectSummary = (entry: { id: string; name: string; revision: number | null }): void => {
+  const { summaries } = store.getSnapshot();
+  const existing = summaries.find((summary) => summary.id === entry.id);
+  const updatedAt = new Date().toISOString();
+  const next: ProjectSummary = {
+    createdAt: existing?.createdAt ?? updatedAt,
+    id: entry.id,
+    name: entry.name,
+    revision: entry.revision ?? existing?.revision ?? 0,
+    updatedAt,
+  };
+
+  store.patchSnapshot({
+    status: 'ready',
+    summaries: sortSummaries([...summaries.filter((summary) => summary.id !== entry.id), next]),
+  });
+};
+
+/** Permanently remove a project from the server. The only deletion path. */
+export const deleteLibraryProject = async (projectId: string): Promise<void> => {
+  await apiDeleteProject(projectId);
+  store.patchSnapshot({ summaries: store.getSnapshot().summaries.filter((summary) => summary.id !== projectId) });
+};
+
+/**
+ * Rename a project that is not open in the editor. Open projects rename
+ * through the workbench reducer instead, so their document and the autosave
+ * revision chain stay consistent.
+ */
+export const renameLibraryProject = async (projectId: string, name: string): Promise<void> => {
+  const record = await apiGetProject(projectId);
+  const updated = await apiUpdateProject(projectId, {
+    data: { ...record.data, name },
+    expected_revision: record.revision,
+    name,
+  });
+
+  upsertProjectSummary({ id: updated.project_id, name: updated.name, revision: updated.revision });
+};
+
+/** Copy a project under a fresh id; returns the new summary. */
+export const duplicateLibraryProject = async (projectId: string): Promise<ProjectSummary> => {
+  const record = await apiGetProject(projectId);
+  const newId = createProjectId();
+  const name = `${record.name} copy`;
+  const created = await apiCreateProject({
+    data: { ...record.data, id: newId, name },
+    name,
+    project_id: newId,
+  });
+  const summary = toSummary(created);
+
+  upsertProjectSummary({ id: summary.id, name: summary.name, revision: summary.revision });
+
+  return summary;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/projectFile.test.ts b/invokeai/frontend/webv2/src/workbench/projects/projectFile.test.ts
new file mode 100644
index 00000000000..fadadd5b8d8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/projectFile.test.ts
@@ -0,0 +1,92 @@
+import { createDraftProject } from '@workbench/workbenchState';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type * as projectFileModule from './projectFile';
+import type * as persistenceModule from './syncedPersistence';
+
+/**
+ * The portable project file format: versioned envelope, defensive parsing,
+ * and the import rule that a file can never overwrite an existing project
+ * because it always lands under a fresh id.
+ */
+
+const api = vi.hoisted(() => ({
+  createProject: vi.fn(),
+  getProject: vi.fn(),
+}));
+
+vi.mock('./api', () => api);
+
+let projectFile: typeof projectFileModule;
+let persistence: typeof persistenceModule;
+
+beforeEach(async () => {
+  vi.resetModules();
+  api.createProject.mockReset();
+  api.getProject.mockReset();
+
+  projectFile = await import('./projectFile');
+  persistence = await import('./syncedPersistence');
+});
+
+describe('project file envelope', () => {
+  it('round-trips a serialized project document', () => {
+    const project = createDraftProject([]);
+    const document = persistence.serializeProjectDocument(project);
+    const file = projectFile.buildProjectFile(document);
+    const parsed = projectFile.parseProjectFile(JSON.stringify(file));
+
+    expect(parsed).toEqual(document);
+  });
+
+  it('rejects files that are not project exports', () => {
+    expect(projectFile.parseProjectFile('not json')).toBeNull();
+    expect(projectFile.parseProjectFile('{}')).toBeNull();
+    expect(projectFile.parseProjectFile(JSON.stringify({ document: {}, kind: 'other', version: 1 }))).toBeNull();
+    expect(
+      projectFile.parseProjectFile(JSON.stringify({ document: {}, kind: 'invokeai-project', version: 99 }))
+    ).toBeNull();
+    expect(projectFile.parseProjectFile(JSON.stringify({ kind: 'invokeai-project', version: 1 }))).toBeNull();
+  });
+});
+
+describe('importProjectFile', () => {
+  const fileFor = (contents: unknown): File => new File([JSON.stringify(contents)], 'export.invokeproject.json');
+
+  it('creates the project under a fresh id, never the id in the file', async () => {
+    const project = { ...createDraftProject([]), name: 'Exported project' };
+    const document = persistence.serializeProjectDocument(project);
+
+    api.createProject.mockImplementation((request: { project_id?: string; name: string }) =>
+      Promise.resolve({
+        created_at: '2026-06-10 10:00:00.000',
+        data: {},
+        name: request.name,
+        project_id: request.project_id ?? '',
+        revision: 1,
+        updated_at: '2026-06-10 10:00:00.000',
+      })
+    );
+
+    const record = await projectFile.importProjectFile(fileFor(projectFile.buildProjectFile(document)));
+
+    expect(record.project_id).not.toBe(project.id);
+    expect(record.name).toBe('Exported project');
+
+    const createRequest = api.createProject.mock.calls[0][0] as { data: Record<string, unknown>; project_id: string };
+
+    expect(createRequest.data.id).toBe(createRequest.project_id);
+  });
+
+  it('rejects files whose document is not a usable project', async () => {
+    const file = fileFor(projectFile.buildProjectFile({ name: 'No layout' }));
+
+    await expect(projectFile.importProjectFile(file)).rejects.toThrow('damaged');
+    expect(api.createProject).not.toHaveBeenCalled();
+  });
+
+  it('rejects non-project files before touching the server', async () => {
+    await expect(projectFile.importProjectFile(fileFor({ some: 'json' }))).rejects.toThrow('not an Invoke project');
+    expect(api.createProject).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/projects/projectFile.ts b/invokeai/frontend/webv2/src/workbench/projects/projectFile.ts
new file mode 100644
index 00000000000..5d5ece1a399
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/projectFile.ts
@@ -0,0 +1,120 @@
+import type { Project } from '@workbench/types';
+
+import { createProject as apiCreateProject, getProject as apiGetProject, type ProjectRecordDTO } from './api';
+import { createProjectId } from './ids';
+import { upsertProjectSummary } from './library';
+import { deserializeProjectDocument, serializeProjectDocument } from './syncedPersistence';
+
+/**
+ * The portable project file: a versioned envelope around the same document
+ * shape the server stores. Export and import both reuse the sync layer's
+ * serialize/deserialize pair, so the file format inherits its healing of
+ * partial documents and there is exactly one definition of "a project
+ * document" in the app.
+ */
+
+export const PROJECT_FILE_KIND = 'invokeai-project';
+export const PROJECT_FILE_VERSION = 1;
+
+export interface ProjectFile {
+  kind: typeof PROJECT_FILE_KIND;
+  version: typeof PROJECT_FILE_VERSION;
+  exportedAt: string;
+  document: Record<string, unknown>;
+}
+
+export const buildProjectFile = (projectDocument: Record<string, unknown>): ProjectFile => ({
+  document: projectDocument,
+  exportedAt: new Date().toISOString(),
+  kind: PROJECT_FILE_KIND,
+  version: PROJECT_FILE_VERSION,
+});
+
+/** Returns the embedded document, or null when the text is not a project file. */
+export const parseProjectFile = (text: string): Record<string, unknown> | null => {
+  try {
+    const parsed = JSON.parse(text) as Partial<ProjectFile> | null;
+
+    if (
+      !parsed ||
+      parsed.kind !== PROJECT_FILE_KIND ||
+      parsed.version !== PROJECT_FILE_VERSION ||
+      !parsed.document ||
+      typeof parsed.document !== 'object' ||
+      Array.isArray(parsed.document)
+    ) {
+      return null;
+    }
+
+    return parsed.document as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+};
+
+const sanitizeFileName = (name: string): string => name.replace(/[^\w\- ]+/gu, '').trim() || 'project';
+
+const downloadProjectFile = (name: string, projectDocument: Record<string, unknown>): void => {
+  const blob = new Blob([JSON.stringify(buildProjectFile(projectDocument), null, 2)], { type: 'application/json' });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+
+  anchor.href = url;
+  anchor.download = `${sanitizeFileName(name)}.invokeproject.json`;
+  anchor.click();
+  URL.revokeObjectURL(url);
+};
+
+/** Export a closed project straight from its server record. */
+export const exportLibraryProject = async (projectId: string): Promise<void> => {
+  const record = await apiGetProject(projectId);
+
+  downloadProjectFile(record.name, record.data);
+};
+
+/** Export an open project from its live in-memory document. */
+export const exportOpenProject = (project: Project): void => {
+  downloadProjectFile(project.name, serializeProjectDocument(project));
+};
+
+/**
+ * Import a project file as a new server project. The document gets a fresh
+ * id — never the one in the file — so an import can never collide with (and
+ * overwrite) an existing project. Throws with a user-readable message.
+ */
+export const importProjectFile = async (file: File): Promise<ProjectRecordDTO> => {
+  const projectDocument = parseProjectFile(await file.text());
+
+  if (!projectDocument) {
+    throw new Error('This file is not an Invoke project export.');
+  }
+
+  const id = createProjectId();
+  const name =
+    typeof projectDocument.name === 'string' && projectDocument.name.trim()
+      ? projectDocument.name.trim()
+      : 'Imported project';
+  const document = { ...projectDocument, id, name };
+
+  if (!deserializeProjectDocument(document)) {
+    throw new Error('The project file is damaged and cannot be opened.');
+  }
+
+  const record = await apiCreateProject({ data: document, name, project_id: id });
+
+  upsertProjectSummary({ id: record.project_id, name: record.name, revision: record.revision });
+
+  return record;
+};
+
+/** Open the browser's file picker for a project file; null when dismissed. */
+export const pickProjectFile = (): Promise<File | null> =>
+  new Promise((resolve) => {
+    const input = document.createElement('input');
+
+    input.type = 'file';
+    input.accept = 'application/json,.json';
+    input.onchange = () => resolve(input.files?.[0] ?? null);
+    input.oncancel = () => resolve(null);
+    input.click();
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/projects/projectSync.test.ts b/invokeai/frontend/webv2/src/workbench/projects/projectSync.test.ts
new file mode 100644
index 00000000000..6f16c27f6b7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/projectSync.test.ts
@@ -0,0 +1,212 @@
+import type { Project } from '@workbench/types';
+
+import { createInitialWorkbenchState, workbenchReducer } from '@workbench/workbenchState';
+import { describe, expect, it } from 'vitest';
+
+import { createRecoveredDocument, deserializeProjectDocument, serializeProjectDocument } from './syncedPersistence';
+
+const getProject = (overrides: Partial<Project> = {}): Project => {
+  const state = createInitialWorkbenchState();
+
+  return { ...state.projects[0], ...overrides };
+};
+
+describe('project document serialization', () => {
+  it('strips undo/redo history and restores it empty on deserialize', () => {
+    const project = getProject();
+
+    project.undoRedo.past.push({
+      createdAt: 'now',
+      id: 'undo-1',
+      label: 'test',
+      project: {
+        invocation: project.invocation,
+        layout: project.layout,
+        projectGraph: project.projectGraph,
+        widgetGraphs: {},
+        widgetInstances: project.widgetInstances,
+        widgetRegions: project.widgetRegions,
+      },
+    });
+
+    const document = serializeProjectDocument(project);
+
+    expect('undoRedo' in document).toBe(false);
+
+    const roundTripped = deserializeProjectDocument(document);
+
+    expect(roundTripped).not.toBeNull();
+    expect(roundTripped?.undoRedo).toEqual({ future: [], past: [] });
+    expect(roundTripped?.id).toBe(project.id);
+    expect(roundTripped?.widgetInstances).toEqual(project.widgetInstances);
+  });
+
+  it('rejects documents that do not look like projects', () => {
+    expect(deserializeProjectDocument({})).toBeNull();
+    expect(deserializeProjectDocument({ id: 'x' })).toBeNull();
+    expect(deserializeProjectDocument({ id: 'x', layout: null, name: 'y' })).toBeNull();
+  });
+
+  it('normalizes legacy project-graph invocation sources to workflow', () => {
+    const base = getProject();
+    const project = getProject({
+      invocation: { destination: 'gallery', destinationLocked: false, sourceId: 'workflow', sourceLocked: false },
+      queue: {
+        items: [
+          {
+            cancellable: true,
+            id: 'legacy-queue-item',
+            snapshot: {
+              canvas: base.canvas,
+              destination: 'gallery',
+              graph: { edges: [], id: 'graph', label: 'Graph', nodes: [], updatedAt: 'now', version: 1 },
+              sourceId: 'workflow',
+              submittedAt: 'now',
+              widgetInstances: {},
+              widgetStates: {},
+            },
+            status: 'pending',
+          },
+        ],
+      },
+    });
+    const document = serializeProjectDocument(project);
+
+    document.invocation = {
+      destination: 'gallery',
+      destinationLocked: false,
+      sourceId: 'project-graph',
+      sourceLocked: false,
+    };
+    document.queue = {
+      items: [
+        {
+          ...(project.queue.items[0] as object),
+          snapshot: { ...project.queue.items[0]?.snapshot, sourceId: 'project-graph' },
+        },
+      ],
+    };
+
+    const deserialized = deserializeProjectDocument(document);
+
+    expect(deserialized?.invocation.sourceId).toBe('workflow');
+    expect(deserialized?.queue.items[0]?.snapshot.sourceId).toBe('workflow');
+  });
+});
+
+describe('createRecoveredDocument', () => {
+  it('keys the fork to the original and stamps the recovery time', () => {
+    const project = getProject({ name: 'My Project' });
+    const { recoveredDocument, recoveredId, recoveredName } = createRecoveredDocument(
+      project,
+      serializeProjectDocument(project)
+    );
+
+    expect(recoveredDocument.recoveryOf).toBe(project.id);
+    expect(recoveredId.startsWith(`${project.id}-recovered-`)).toBe(true);
+    expect(recoveredName).toBe('My Project (recovered)');
+    expect(typeof recoveredDocument.recoveredAt).toBe('string');
+  });
+
+  it('collapses recovery chains to the root and never stacks name suffixes', () => {
+    const root = getProject({ name: 'My Project' });
+    const recovery = getProject({
+      id: `${root.id}-recovered-abc`,
+      name: 'My Project (recovered)',
+      recoveryOf: root.id,
+    });
+
+    const { recoveredDocument, recoveredName } = createRecoveredDocument(recovery, serializeProjectDocument(recovery));
+
+    expect(recoveredDocument.recoveryOf).toBe(root.id);
+    expect(recoveredName).toBe('My Project (recovered)');
+  });
+
+  it('cleans up legacy stacked suffixes', () => {
+    const project = getProject({ name: 'Project Name #1 (Recovered) (Recovered)' });
+    const { recoveredName } = createRecoveredDocument(project, serializeProjectDocument(project));
+
+    expect(recoveredName).toBe('Project Name #1 (recovered)');
+  });
+});
+
+describe('openProject', () => {
+  it('appends the hydrated project and makes it active', () => {
+    const state = createInitialWorkbenchState();
+    const opened = getProject({ id: 'project-from-library', name: 'Reopened' });
+
+    const next = workbenchReducer(state, { project: opened, type: 'openProject' });
+
+    expect(next.projects.map((project) => project.id)).toEqual([state.projects[0].id, opened.id]);
+    expect(next.activeProjectId).toBe(opened.id);
+  });
+
+  it('focuses an already-open project instead of duplicating it', () => {
+    const state = createInitialWorkbenchState();
+    const existing = state.projects[0];
+    const background = getProject({ id: 'project-background' });
+    const withTwo = workbenchReducer(state, { project: background, type: 'openProject' });
+
+    const next = workbenchReducer(withTwo, { project: existing, type: 'openProject' });
+
+    expect(next.projects).toHaveLength(2);
+    expect(next.activeProjectId).toBe(existing.id);
+  });
+});
+
+describe('renameProject', () => {
+  it('renames the target project and ignores blank names', () => {
+    const state = createInitialWorkbenchState();
+    const target = state.projects[0];
+
+    const renamed = workbenchReducer(state, { name: '  New Name  ', projectId: target.id, type: 'renameProject' });
+
+    expect(renamed.projects[0].name).toBe('New Name');
+
+    const blank = workbenchReducer(renamed, { name: '   ', projectId: target.id, type: 'renameProject' });
+
+    expect(blank.projects[0].name).toBe('New Name');
+  });
+});
+
+describe('reconcileProjectConflict', () => {
+  it('adopts the server version and continues local work in the recovered fork', () => {
+    const state = createInitialWorkbenchState();
+    const original = state.projects[0];
+    const serverProject = getProject({ id: original.id, name: 'Server version' });
+    const recoveredProject = getProject({ id: `${original.id}-recovered-abc`, name: 'Server version (recovered)' });
+    const withActiveOriginal = { ...state, activeProjectId: original.id };
+
+    const next = workbenchReducer(withActiveOriginal, {
+      projectId: original.id,
+      recoveredProject,
+      serverProject,
+      type: 'reconcileProjectConflict',
+    });
+
+    const ids = next.projects.map((project) => project.id);
+
+    expect(ids).toContain(original.id);
+    expect(ids).toContain(recoveredProject.id);
+    expect(next.projects.find((project) => project.id === original.id)?.name).toBe('Server version');
+    // The user keeps looking at their own latest edits.
+    expect(next.activeProjectId).toBe(recoveredProject.id);
+    expect(next.notifications[0]?.title).toBe('Project recovered');
+  });
+
+  it('leaves the active project alone when the conflicted project is in the background', () => {
+    const state = createInitialWorkbenchState();
+    const first = state.projects[0];
+    const second = getProject({ id: 'project-background-test' });
+    const withActiveSecond = { ...state, activeProjectId: second.id, projects: [...state.projects, second] };
+
+    const next = workbenchReducer(withActiveSecond, {
+      projectId: first.id,
+      recoveredProject: getProject({ id: `${first.id}-recovered-abc`, name: 'Recovered' }),
+      serverProject: getProject({ id: first.id, name: 'Server version' }),
+      type: 'reconcileProjectConflict',
+    });
+
+    expect(next.activeProjectId).toBe(second.id);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/projects/session.ts b/invokeai/frontend/webv2/src/workbench/projects/session.ts
new file mode 100644
index 00000000000..0c2ce3cd14e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/session.ts
@@ -0,0 +1,87 @@
+import type { AccountState, WorkbenchPreferences, WorkbenchState } from '@workbench/types';
+
+import { getClientStateValue } from './api';
+
+/**
+ * The per-user session blob in the client-state KV: the editor session — which
+ * projects are open as tabs and which is active — plus a legacy account snapshot
+ * for older installs. Current settings live in `settings.ts` so Home can load
+ * them without mounting the workbench provider.
+ *
+ * `openProjectIds` arrived with the library/session split. Blobs written
+ * before it have no open set; `undefined` there means "unknown — open every
+ * project", which is exactly what those versions did, so old sessions migrate
+ * without anything visibly changing.
+ */
+
+export const SESSION_STATE_KEY = 'webv2:workbench-account';
+
+/**
+ * Search params understood by the /app route: `project` deep-links a library
+ * project into the session; `new` opens the editor with a fresh draft.
+ */
+export interface WorkbenchSearch {
+  new?: true;
+  project?: string;
+}
+
+export interface WorkbenchSessionBlob {
+  account: AccountState & {
+    /** Written by builds that kept preferences in the account; read once as a migration source. */
+    preferences?: Partial<WorkbenchPreferences>;
+  };
+  activeProjectId: string;
+  openProjectIds?: string[];
+}
+
+export const parseSessionBlob = (raw: string | null): WorkbenchSessionBlob | null => {
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as Partial<WorkbenchSessionBlob>;
+
+    if (!parsed.account || typeof parsed.activeProjectId !== 'string') {
+      return null;
+    }
+
+    return {
+      account: parsed.account,
+      activeProjectId: parsed.activeProjectId,
+      openProjectIds: Array.isArray(parsed.openProjectIds)
+        ? parsed.openProjectIds.filter((id): id is string => typeof id === 'string')
+        : undefined,
+    };
+  } catch {
+    return null;
+  }
+};
+
+/** The open set is derived from workbench state: open tabs are the session. */
+export const serializeSessionBlob = (state: WorkbenchState): string =>
+  JSON.stringify({
+    account: state.account,
+    activeProjectId: state.activeProjectId,
+    openProjectIds: state.projects.map((project) => project.id),
+  } satisfies WorkbenchSessionBlob);
+
+export const fetchSessionBlob = async (): Promise<WorkbenchSessionBlob | null> => {
+  try {
+    return parseSessionBlob(await getClientStateValue(SESSION_STATE_KEY));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Cheap pre-mount peek for the /app route guard: would any tabs open?
+ * `null` means "could not tell" (no blob yet, a pre-split blob, or the
+ * backend is unreachable) — the guard must not redirect on null, only on a
+ * definite empty session.
+ */
+export const peekOpenProjectIds = async (): Promise<string[] | null> => {
+  const blob = await fetchSessionBlob();
+
+  return blob?.openProjectIds ?? null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/syncStore.ts b/invokeai/frontend/webv2/src/workbench/projects/syncStore.ts
new file mode 100644
index 00000000000..1ab80c4f767
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/syncStore.ts
@@ -0,0 +1,37 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+/**
+ * Read-only window into the project sync layer for shell surfaces (the
+ * Project panel's debug section). Written exclusively by `syncedPersistence`
+ * after each load/save pass; everything here is informational.
+ */
+
+export interface ProjectSyncInfo {
+  /** Server revision the next save is based on; null = never reached the server. */
+  revision: number | null;
+  /** True when the local document differs from what the server acknowledged. */
+  isPendingPush: boolean;
+}
+
+export interface ProjectSyncSnapshot {
+  projects: Record<string, ProjectSyncInfo>;
+  hasPendingChanges: boolean;
+  lastSyncedAt: string | null;
+}
+
+const store = createExternalStore<ProjectSyncSnapshot>({
+  hasPendingChanges: false,
+  lastSyncedAt: null,
+  projects: {},
+});
+
+export const useProjectSync = (): ProjectSyncSnapshot => store.useSnapshot();
+
+export const useProjectSyncSelector = store.useSelector;
+
+export const reportProjectSync = (update: Omit<ProjectSyncSnapshot, 'lastSyncedAt'>): void => {
+  store.setSnapshot({
+    ...update,
+    lastSyncedAt: update.hasPendingChanges ? store.getSnapshot().lastSyncedAt : new Date().toISOString(),
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/syncedPersistence.test.ts b/invokeai/frontend/webv2/src/workbench/projects/syncedPersistence.test.ts
new file mode 100644
index 00000000000..6ef2beeaf24
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/syncedPersistence.test.ts
@@ -0,0 +1,366 @@
+import type { Project, WorkbenchState } from '@workbench/types';
+
+import { createDraftProject, createInitialWorkbenchState } from '@workbench/workbenchState';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type * as libraryModule from './library';
+import type * as persistenceModule from './syncedPersistence';
+
+/**
+ * Service-level tests for the library/session split: the open set drives
+ * hydration, saving never deletes, and explicit deletes cannot be undone by
+ * racing autosaves. The REST module is replaced by an in-memory server.
+ */
+
+const api = vi.hoisted(() => {
+  interface MockRecord {
+    project_id: string;
+    name: string;
+    revision: number;
+    created_at: string;
+    updated_at: string;
+    data: Record<string, unknown>;
+  }
+
+  const records = new Map<string, MockRecord>();
+  const clientState = new Map<string, string>();
+
+  const conflictError = (): Error => Object.assign(new Error('conflict'), { __status: 409 });
+  const notFoundError = (): Error => Object.assign(new Error('not found'), { __status: 404 });
+  const toSummary = (record: MockRecord) => ({
+    created_at: record.created_at,
+    name: record.name,
+    project_id: record.project_id,
+    revision: record.revision,
+    updated_at: record.updated_at,
+  });
+  const clone = (record: MockRecord): MockRecord => structuredClone(record);
+
+  const mock = {
+    __clientState: clientState,
+    __records: records,
+    __seed: (data: Record<string, unknown>): void => {
+      const id = data.id as string;
+
+      records.set(id, {
+        created_at: '2026-06-10 08:00:00.000',
+        data: structuredClone(data),
+        name: data.name as string,
+        project_id: id,
+        revision: 1,
+        updated_at: '2026-06-10 08:00:00.000',
+      });
+    },
+    createProject: vi.fn((request: { project_id?: string; name: string; data: Record<string, unknown> }) => {
+      const id = request.project_id ?? `generated-${records.size}`;
+
+      if (records.has(id)) {
+        return Promise.reject(conflictError());
+      }
+
+      const record: MockRecord = {
+        created_at: '2026-06-10 09:00:00.000',
+        data: structuredClone(request.data),
+        name: request.name,
+        project_id: id,
+        revision: 1,
+        updated_at: '2026-06-10 09:00:00.000',
+      };
+
+      records.set(id, record);
+
+      return Promise.resolve(clone(record));
+    }),
+    deleteClientStateValue: vi.fn((key: string) => {
+      clientState.delete(key);
+
+      return Promise.resolve();
+    }),
+    deleteProject: vi.fn((projectId: string) => {
+      records.delete(projectId);
+
+      return Promise.resolve();
+    }),
+    getClientStateValue: vi.fn((key: string) => Promise.resolve(clientState.get(key) ?? null)),
+    getProject: vi.fn((projectId: string) => {
+      const record = records.get(projectId);
+
+      return record ? Promise.resolve(clone(record)) : Promise.reject(notFoundError());
+    }),
+    isProjectConflictError: (error: unknown): boolean => (error as { __status?: number }).__status === 409,
+    isProjectNotFoundError: (error: unknown): boolean => (error as { __status?: number }).__status === 404,
+    listProjects: vi.fn(() => Promise.resolve([...records.values()].map(toSummary))),
+    setClientStateValue: vi.fn((key: string, value: string) => {
+      clientState.set(key, value);
+
+      return Promise.resolve();
+    }),
+    updateProject: vi.fn(
+      (projectId: string, request: { name: string; data: Record<string, unknown>; expected_revision: number }) => {
+        const record = records.get(projectId);
+
+        if (!record) {
+          return Promise.reject(notFoundError());
+        }
+
+        if (record.revision !== request.expected_revision) {
+          return Promise.reject(conflictError());
+        }
+
+        const updated: MockRecord = {
+          ...record,
+          data: structuredClone(request.data),
+          name: request.name,
+          revision: record.revision + 1,
+          updated_at: '2026-06-10 10:00:00.000',
+        };
+
+        records.set(projectId, updated);
+
+        return Promise.resolve(clone(updated));
+      }
+    ),
+  };
+
+  return mock;
+});
+
+vi.mock('./api', () => api);
+
+const storage = new Map<string, string>();
+
+vi.stubGlobal('window', {
+  localStorage: {
+    getItem: (key: string): string | null => storage.get(key) ?? null,
+    removeItem: (key: string): void => {
+      storage.delete(key);
+    },
+    setItem: (key: string, value: string): void => {
+      storage.set(key, value);
+    },
+  },
+});
+
+const SESSION_KEY = 'webv2:workbench-account';
+
+let persistence: typeof persistenceModule;
+let library: typeof libraryModule;
+
+const seedSessionBlob = (blob: Record<string, unknown>): void => {
+  api.__clientState.set(SESSION_KEY, JSON.stringify(blob));
+};
+
+const seedServerProject = (name: string): Project => {
+  const draft = { ...createDraftProject([]), name };
+
+  api.__seed(persistence.serializeProjectDocument(draft));
+
+  return draft;
+};
+
+const stateWithProjects = (projects: Project[], activeProjectId = projects[0]?.id ?? ''): WorkbenchState => ({
+  ...createInitialWorkbenchState(),
+  activeProjectId,
+  projects,
+});
+
+beforeEach(async () => {
+  vi.resetModules();
+  api.__records.clear();
+  api.__clientState.clear();
+  storage.clear();
+  api.createProject.mockClear();
+  api.deleteProject.mockClear();
+  api.getProject.mockClear();
+  api.listProjects.mockClear();
+  api.updateProject.mockClear();
+
+  persistence = await import('./syncedPersistence');
+  library = await import('./library');
+});
+
+describe('loadWorkbench session hydration', () => {
+  it('hydrates only the open set and seeds the full library', async () => {
+    const first = seedServerProject('First');
+    const second = seedServerProject('Second');
+    const third = seedServerProject('Third');
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: second.id, openProjectIds: [second.id] });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench();
+
+    expect(snapshot?.state.projects.map((project) => project.id)).toEqual([second.id]);
+    expect(snapshot?.state.activeProjectId).toBe(second.id);
+    expect(api.getProject).toHaveBeenCalledTimes(1);
+    expect(persistence.syncedWorkbenchPersistence.hasPendingChanges()).toBe(false);
+
+    const libraryIds = library.getProjectLibrary().summaries.map((summary) => summary.id);
+
+    expect(libraryIds).toHaveLength(3);
+    expect(libraryIds).toEqual(expect.arrayContaining([first.id, second.id, third.id]));
+  });
+
+  it('opens every project for sessions from before the split (no open set in the blob)', async () => {
+    seedServerProject('First');
+    seedServerProject('Second');
+
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: 'missing' });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench();
+
+    expect(snapshot?.state.projects).toHaveLength(2);
+  });
+
+  it('ignores a corrupt local cache and still hydrates from the backend', async () => {
+    seedServerProject('Backend Project');
+    storage.set('invokeai:v7:webv2:workbench', '{not json');
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench();
+
+    expect(snapshot?.state.projects.map((project) => project.name)).toEqual(['Backend Project']);
+  });
+
+  it('boots a fresh draft when the session is empty', async () => {
+    const existing = seedServerProject('Closed project');
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: '', openProjectIds: [] });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench();
+
+    expect(snapshot?.state.projects).toHaveLength(1);
+    expect(snapshot?.state.projects[0].id).not.toBe(existing.id);
+    expect(snapshot?.state.activeProjectId).toBe(snapshot?.state.projects[0].id);
+    expect(persistence.syncedWorkbenchPersistence.hasPendingChanges()).toBe(true);
+  });
+
+  it('joins a deep-linked project into the open set and focuses it', async () => {
+    const first = seedServerProject('First');
+    const second = seedServerProject('Second');
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: first.id, openProjectIds: [first.id] });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench({ openProjectId: second.id });
+
+    expect(snapshot?.state.projects.map((project) => project.id)).toEqual([first.id, second.id]);
+    expect(snapshot?.state.activeProjectId).toBe(second.id);
+    expect(persistence.syncedWorkbenchPersistence.hasPendingChanges()).toBe(true);
+  });
+
+  it('appends and activates a draft when a new project is requested', async () => {
+    const first = seedServerProject('First');
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: first.id, openProjectIds: [first.id] });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench({ createNew: true });
+
+    expect(snapshot?.state.projects).toHaveLength(2);
+    expect(snapshot?.state.activeProjectId).not.toBe(first.id);
+    expect(persistence.syncedWorkbenchPersistence.hasPendingChanges()).toBe(true);
+  });
+});
+
+describe('saveWorkbench', () => {
+  it('never deletes server projects that are absent from state', async () => {
+    const first = seedServerProject('First');
+    const second = seedServerProject('Second');
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: first.id, openProjectIds: [first.id, second.id] });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench();
+    const open = snapshot?.state.projects ?? [];
+
+    expect(open).toHaveLength(2);
+
+    // Close the second tab: it leaves state, but must stay on the server.
+    const closed = stateWithProjects(
+      open.filter((project) => project.id !== second.id),
+      first.id
+    );
+
+    await persistence.syncedWorkbenchPersistence.saveWorkbench(closed);
+
+    expect(api.deleteProject).not.toHaveBeenCalled();
+    expect(api.__records.has(second.id)).toBe(true);
+  });
+
+  it('persists the open set in the session blob', async () => {
+    const first = seedServerProject('First');
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: first.id, openProjectIds: [first.id] });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench();
+    const open = snapshot?.state.projects ?? [];
+    const draft = createDraftProject(open);
+
+    await persistence.syncedWorkbenchPersistence.saveWorkbench(stateWithProjects([...open, draft], draft.id));
+
+    const blob = JSON.parse(api.__clientState.get(SESSION_KEY) ?? '{}') as {
+      activeProjectId?: string;
+      openProjectIds?: string[];
+    };
+
+    expect(blob.openProjectIds).toEqual([first.id, draft.id]);
+    expect(blob.activeProjectId).toBe(draft.id);
+  });
+
+  it('skips pushes for projects marked deleted, so a racing autosave cannot resurrect them', async () => {
+    const project = createDraftProject([]);
+    const state = stateWithProjects([project]);
+
+    persistence.markProjectDeleted(project.id);
+    await persistence.syncedWorkbenchPersistence.saveWorkbench(state);
+
+    expect(api.createProject).not.toHaveBeenCalled();
+    expect(api.updateProject).not.toHaveBeenCalled();
+    expect(api.__records.has(project.id)).toBe(false);
+  });
+});
+
+describe('persistEmptySession', () => {
+  it('writes an empty open set without touching project records', async () => {
+    const first = seedServerProject('First');
+    const account = createInitialWorkbenchState().account;
+
+    seedSessionBlob({ account, activeProjectId: first.id, openProjectIds: [first.id] });
+
+    const snapshot = await persistence.syncedWorkbenchPersistence.loadWorkbench();
+
+    await persistence.persistEmptySession(snapshot?.state ?? createInitialWorkbenchState());
+
+    const blob = JSON.parse(api.__clientState.get(SESSION_KEY) ?? '{}') as { openProjectIds?: string[] };
+
+    expect(blob.openProjectIds).toEqual([]);
+    expect(api.__records.has(first.id)).toBe(true);
+    expect(api.deleteProject).not.toHaveBeenCalled();
+  });
+});
+
+describe('hydrateProjectFromServer', () => {
+  it('returns an openable project and registers its revision for future saves', async () => {
+    const project = seedServerProject('Closed project');
+    const hydrated = await persistence.hydrateProjectFromServer(project.id);
+
+    expect(hydrated?.id).toBe(project.id);
+    expect(hydrated?.undoRedo).toEqual({ future: [], past: [] });
+
+    // A subsequent save updates in place rather than re-creating.
+    const renamed = { ...hydrated!, name: 'Renamed after reopen' };
+
+    await persistence.syncedWorkbenchPersistence.saveWorkbench(stateWithProjects([renamed]));
+
+    expect(api.createProject).not.toHaveBeenCalled();
+    expect(api.__records.get(project.id)?.name).toBe('Renamed after reopen');
+  });
+
+  it('returns null for unknown projects', async () => {
+    expect(await persistence.hydrateProjectFromServer('nope')).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/projects/syncedPersistence.ts b/invokeai/frontend/webv2/src/workbench/projects/syncedPersistence.ts
new file mode 100644
index 00000000000..92bb472fe6d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/syncedPersistence.ts
@@ -0,0 +1,750 @@
+import type { Project, WorkbenchPersistenceSnapshot, WorkbenchState } from '@workbench/types';
+
+import { getUserStorageScope } from '@workbench/auth/session';
+import { timeWorkbenchPerf } from '@workbench/performanceMarks';
+import { localStorageWorkbenchPersistence, stripTransientWorkbenchState } from '@workbench/persistence';
+import { createDraftProject, createInitialWorkbenchState } from '@workbench/workbenchState';
+
+import {
+  createProject as apiCreateProject,
+  deleteClientStateValue,
+  deleteProject as apiDeleteProject,
+  getProject as apiGetProject,
+  isProjectConflictError,
+  isProjectNotFoundError,
+  listProjects,
+  setClientStateValue,
+  updateProject as apiUpdateProject,
+  type ProjectRecordDTO,
+} from './api';
+import { seedProjectLibrary, upsertProjectSummary } from './library';
+import { fetchSessionBlob, serializeSessionBlob, SESSION_STATE_KEY } from './session';
+import { reportProjectSync, type ProjectSyncInfo } from './syncStore';
+
+/**
+ * Backend-first workbench persistence (spec: Persistence Model).
+ *
+ * The backend database is the source of truth: each project is one
+ * revision-versioned document on the server, and the small session blob
+ * (open tabs + active project, with legacy account data) lives in the per-user
+ * client-state KV. The user-scoped localStorage snapshot is kept as a
+ * write-through cache so the workbench still loads and autosaves while the
+ * backend is unreachable; un-pushed changes are replayed on the next save or
+ * reconnect.
+ *
+ * Workbench state only ever holds the open projects (the session); the full
+ * set of saved projects lives in the project library as summaries. Saving
+ * pushes what is open and never deletes — projects leave the server only
+ * through the library's explicit delete.
+ *
+ * Conflicts never lose work: when a save is based on a stale revision, the
+ * server version wins for that project id and the local version is forked
+ * into a "(recovered)" project beside it.
+ */
+
+const SYNC_MAP_BASE_KEY = 'invokeai:v7:webv2:workbench-sync';
+
+interface SyncEntry {
+  /** The server revision our next save is based on. */
+  revision: number;
+  /** Serialized form of the last document the server acknowledged. */
+  pushedDoc: string | null;
+}
+
+export interface ProjectConflictResolution {
+  projectId: string;
+  /** The newer version that won on the server, now adopted locally. */
+  serverProject: Project;
+  /** The forked copy carrying the local edits that lost the race. */
+  recoveredProject: Project;
+}
+
+export interface WorkbenchSaveResult {
+  snapshot: WorkbenchPersistenceSnapshot;
+  conflicts: ProjectConflictResolution[];
+  /** True when changes are cached locally but could not reach the backend. */
+  hasPendingChanges: boolean;
+}
+
+export interface WorkbenchLoadOptions {
+  /** Deep-linked project (/app?project=…) to include in the open set. */
+  openProjectId?: string;
+  /** Append a fresh draft project to the session (/app?new=1). */
+  createNew?: boolean;
+}
+
+/** Server-known projects, keyed by project id. */
+const syncEntries = new Map<string, SyncEntry>();
+/**
+ * Ids deleted this page session. An autosave that raced the delete must not
+ * resurrect the project through the not-found-recreate path.
+ */
+const deletedProjectIds = new Set<string>();
+let lastPushedAccount: string | null = null;
+let hasPending = false;
+const projectDocumentJsonCache = new WeakMap<Project, { document: Record<string, unknown>; json: string }>();
+
+/**
+ * Undo/redo stacks are session-only (each entry is a full project snapshot,
+ * far too heavy to autosave); everything else in the project document is the
+ * project, verbatim.
+ */
+export const serializeProjectDocument = (project: Project): Record<string, unknown> => {
+  const { undoRedo: _undoRedo, ...document } = project;
+
+  return document;
+};
+
+const getSerializedProjectDocument = (project: Project): { document: Record<string, unknown>; json: string } => {
+  const cached = projectDocumentJsonCache.get(project);
+
+  if (cached) {
+    return cached;
+  }
+
+  const document = serializeProjectDocument(project);
+  const json = timeWorkbenchPerf(
+    'workbench:project-document-stringify',
+    { area: 'project-sync', kind: 'workbench', projectId: project.id },
+    () => JSON.stringify(document)
+  );
+  const serialized = { document, json };
+
+  projectDocumentJsonCache.set(project, serialized);
+
+  return serialized;
+};
+
+const normalizeInvocationSourceId = (sourceId: unknown): unknown => {
+  if (sourceId === 'project-graph') {
+    return 'workflow';
+  }
+
+  if (sourceId === 'canvas-fill') {
+    return 'canvas';
+  }
+
+  return sourceId;
+};
+
+const normalizeLegacyProjectDocument = (data: Record<string, unknown>): Record<string, unknown> => {
+  const invocation = data.invocation;
+  const queue = data.queue;
+
+  return {
+    ...data,
+    invocation:
+      invocation && typeof invocation === 'object'
+        ? { ...invocation, sourceId: normalizeInvocationSourceId((invocation as { sourceId?: unknown }).sourceId) }
+        : invocation,
+    queue:
+      queue && typeof queue === 'object' && Array.isArray((queue as { items?: unknown }).items)
+        ? {
+            ...queue,
+            items: (queue as { items: unknown[] }).items.map((item) => {
+              if (!item || typeof item !== 'object') {
+                return item;
+              }
+
+              const snapshot = (item as { snapshot?: unknown }).snapshot;
+
+              return {
+                ...item,
+                snapshot:
+                  snapshot && typeof snapshot === 'object'
+                    ? {
+                        ...snapshot,
+                        sourceId: normalizeInvocationSourceId((snapshot as { sourceId?: unknown }).sourceId),
+                      }
+                    : snapshot,
+              };
+            }),
+          }
+        : queue,
+  };
+};
+
+export const deserializeProjectDocument = (data: Record<string, unknown>): Project | null => {
+  const normalizedData = normalizeLegacyProjectDocument(data);
+
+  if (
+    typeof normalizedData.id !== 'string' ||
+    typeof normalizedData.name !== 'string' ||
+    typeof normalizedData.layout !== 'object' ||
+    normalizedData.layout === null
+  ) {
+    return null;
+  }
+
+  return { ...normalizedData, undoRedo: { future: [], past: [] } } as unknown as Project;
+};
+
+const getSyncMapStorageKey = (): string => `${SYNC_MAP_BASE_KEY}${getUserStorageScope()}`;
+
+/**
+ * The revision map survives reloads so that, while offline, we can still tell
+ * "this local project was synced before but is gone from the server (deleted
+ * elsewhere — drop it)" apart from "this local project was created offline
+ * (push it)".
+ */
+const persistSyncMap = (): void => {
+  try {
+    const revisions: Record<string, number> = {};
+
+    for (const [projectId, entry] of syncEntries) {
+      revisions[projectId] = entry.revision;
+    }
+
+    window.localStorage.setItem(getSyncMapStorageKey(), JSON.stringify({ revisions }));
+  } catch {
+    // Cache only; sync still works for this session.
+  }
+};
+
+const loadPersistedRevisions = (): Record<string, number> => {
+  try {
+    const raw = window.localStorage.getItem(getSyncMapStorageKey());
+    const parsed = raw ? (JSON.parse(raw) as { revisions?: Record<string, number> }) : null;
+
+    return parsed?.revisions ?? {};
+  } catch {
+    return {};
+  }
+};
+
+const createSnapshot = (state: WorkbenchState): WorkbenchPersistenceSnapshot => ({
+  savedAt: new Date().toISOString(),
+  state: stripTransientWorkbenchState(state),
+  version: 1,
+});
+
+/** Import a never-synced project to the server; returns false when it could not reach it. */
+const pushNewProject = async (project: Project): Promise<boolean> => {
+  const document = serializeProjectDocument(project);
+
+  try {
+    const created = await apiCreateProject({ data: document, name: project.name, project_id: project.id });
+
+    syncEntries.set(project.id, { pushedDoc: JSON.stringify(document), revision: created.revision });
+
+    return true;
+  } catch (error) {
+    if (isProjectConflictError(error)) {
+      // The id already exists server-side (e.g. a previous import raced a
+      // reload). Adopt the server revision; the regular save path will PUT.
+      try {
+        const existing = await apiGetProject(project.id);
+
+        syncEntries.set(project.id, { pushedDoc: JSON.stringify(existing.data), revision: existing.revision });
+
+        return true;
+      } catch {
+        return false;
+      }
+    }
+
+    return false;
+  }
+};
+
+/** Strip any number of stacked "(recovered)" suffixes left by older recoveries. */
+const getRecoveryBaseName = (name: string): string => name.replace(/(\s*\((?:r|R)ecovered\))+$/u, '').trim() || name;
+
+/**
+ * Build the fork document for a conflicted project: lineage always points at
+ * the root original (a recovery of a recovery still keys to the first
+ * project), and the name never stacks suffixes.
+ */
+export const createRecoveredDocument = (
+  project: Project,
+  document: Record<string, unknown>
+): { recoveredId: string; recoveredName: string; recoveredDocument: Record<string, unknown> } => {
+  const recoveryOf = project.recoveryOf ?? project.id;
+  const recoveredId = `${recoveryOf}-recovered-${Date.now().toString(36)}`;
+  const recoveredName = `${getRecoveryBaseName(project.name)} (recovered)`;
+
+  return {
+    recoveredDocument: {
+      ...document,
+      id: recoveredId,
+      name: recoveredName,
+      recoveredAt: new Date().toISOString(),
+      recoveryOf,
+    },
+    recoveredId,
+    recoveredName,
+  };
+};
+
+type ConflictOutcome =
+  | { kind: 'adopted' }
+  | { kind: 'retry' }
+  | { kind: 'forked'; resolution: ProjectConflictResolution }
+  | { kind: 'failed' };
+
+/**
+ * A save lost the revision race. Forking is the last resort — it only happens
+ * when content actually diverged:
+ *
+ * - server content == what we tried to push → adopt the revision, done
+ * - server content == the base this edit started from → revisions drifted
+ *   without divergence (e.g. crash between an acknowledged PUT and the
+ *   revision write); adopt the revision and retry the edit
+ * - anything else → the server version keeps the id, the local edits fork
+ *   into a "(recovered)" project so nothing is lost
+ */
+const recoverConflictingProject = async (
+  project: Project,
+  document: Record<string, unknown>,
+  documentJson: string,
+  basePushedDoc: string | null
+): Promise<ConflictOutcome> => {
+  try {
+    const server = await apiGetProject(project.id);
+    const serverDocJson = JSON.stringify(server.data);
+
+    syncEntries.set(project.id, { pushedDoc: serverDocJson, revision: server.revision });
+
+    if (serverDocJson === documentJson) {
+      return { kind: 'adopted' };
+    }
+
+    if (basePushedDoc !== null && serverDocJson === basePushedDoc) {
+      return { kind: 'retry' };
+    }
+
+    const serverProject = deserializeProjectDocument(server.data);
+
+    if (!serverProject) {
+      return { kind: 'failed' };
+    }
+
+    const { recoveredDocument, recoveredId, recoveredName } = createRecoveredDocument(project, document);
+    const recoveredProject = deserializeProjectDocument(recoveredDocument);
+
+    if (!recoveredProject) {
+      return { kind: 'failed' };
+    }
+
+    const created = await apiCreateProject({ data: recoveredDocument, name: recoveredName, project_id: recoveredId });
+
+    syncEntries.set(recoveredId, { pushedDoc: JSON.stringify(recoveredDocument), revision: created.revision });
+
+    return { kind: 'forked', resolution: { projectId: project.id, recoveredProject, serverProject } };
+  } catch {
+    return { kind: 'failed' };
+  }
+};
+
+const pushProject = async (project: Project, conflicts: ProjectConflictResolution[]): Promise<string> => {
+  const { document, json: documentJson } = getSerializedProjectDocument(project);
+  const entry = syncEntries.get(project.id);
+
+  if (deletedProjectIds.has(project.id) || entry?.pushedDoc === documentJson) {
+    return documentJson;
+  }
+
+  if (!entry) {
+    if (!(await pushNewProject(project))) {
+      hasPending = true;
+    }
+
+    return documentJson;
+  }
+
+  try {
+    const updated = await apiUpdateProject(project.id, {
+      data: document,
+      expected_revision: entry.revision,
+      name: project.name,
+    });
+
+    syncEntries.set(project.id, { pushedDoc: documentJson, revision: updated.revision });
+  } catch (error) {
+    if (isProjectConflictError(error)) {
+      const outcome = await recoverConflictingProject(project, document, documentJson, entry.pushedDoc);
+
+      if (outcome.kind === 'retry') {
+        try {
+          const baseRevision = syncEntries.get(project.id)?.revision ?? entry.revision;
+          const retried = await apiUpdateProject(project.id, {
+            data: document,
+            expected_revision: baseRevision,
+            name: project.name,
+          });
+
+          syncEntries.set(project.id, { pushedDoc: documentJson, revision: retried.revision });
+        } catch {
+          // A genuinely concurrent writer; the next save re-evaluates.
+          hasPending = true;
+        }
+      } else if (outcome.kind === 'forked') {
+        conflicts.push(outcome.resolution);
+      } else if (outcome.kind === 'failed') {
+        hasPending = true;
+      }
+    } else if (isProjectNotFoundError(error)) {
+      // Deleted on another device while we held local edits: recreate rather
+      // than drop the user's work.
+      syncEntries.delete(project.id);
+
+      if (!(await pushNewProject(project))) {
+        hasPending = true;
+      }
+    } else {
+      hasPending = true;
+    }
+  }
+
+  return documentJson;
+};
+
+const pushSessionState = async (state: WorkbenchState): Promise<void> => {
+  const blob = serializeSessionBlob(state);
+
+  if (blob === lastPushedAccount) {
+    return;
+  }
+
+  try {
+    await setClientStateValue(SESSION_STATE_KEY, blob);
+    lastPushedAccount = blob;
+  } catch {
+    hasPending = true;
+  }
+};
+
+const loadFromBackend = async (
+  local: WorkbenchPersistenceSnapshot | null,
+  options?: WorkbenchLoadOptions
+): Promise<WorkbenchPersistenceSnapshot> => {
+  const [summaries, sessionBlob] = await Promise.all([listProjects(), fetchSessionBlob()]);
+  const persistedRevisions = loadPersistedRevisions();
+
+  seedProjectLibrary(summaries);
+
+  // First contact: a backend with no projects adopts the browser's existing
+  // workbench (one-time import of the pre-backend localStorage data).
+  if (summaries.length === 0 && local && local.state.projects.length > 0) {
+    for (const project of local.state.projects) {
+      if (!(await pushNewProject(project))) {
+        hasPending = true;
+      }
+
+      const entry = syncEntries.get(project.id);
+
+      upsertProjectSummary({ id: project.id, name: project.name, revision: entry?.revision ?? null });
+    }
+
+    await pushSessionState(local.state);
+    persistSyncMap();
+
+    return local;
+  }
+
+  // The session blob says which projects are open as tabs; blobs from before
+  // the library/session split have no open set, and for those every project
+  // opens (exactly what that version of the app did). A deep-linked project
+  // joins the set.
+  const summaryIds = new Set(summaries.map((summary) => summary.project_id));
+  const requestedIds = sessionBlob?.openProjectIds ?? summaries.map((summary) => summary.project_id);
+  const openIds: string[] = [];
+
+  for (const id of [...requestedIds, ...(options?.openProjectId ? [options.openProjectId] : [])]) {
+    if (summaryIds.has(id) && !openIds.includes(id)) {
+      openIds.push(id);
+    }
+  }
+
+  // Only the open set is hydrated into full documents; everything else stays
+  // a summary in the library. A project deleted between list and get is
+  // simply dropped from the session.
+  const records = await Promise.all(openIds.map((id) => apiGetProject(id).catch(() => null)));
+  const serverProjects: Project[] = [];
+
+  for (const record of records) {
+    if (!record) {
+      continue;
+    }
+
+    const project = deserializeProjectDocument(record.data);
+
+    if (project) {
+      serverProjects.push(project);
+      syncEntries.set(record.project_id, { pushedDoc: JSON.stringify(record.data), revision: record.revision });
+    }
+  }
+
+  // Local projects the server does not have: keep the ones never synced
+  // (created offline; the next save pushes them) and drop the ones with a
+  // recorded revision (synced before, so they were deleted elsewhere).
+  const serverIds = new Set(serverProjects.map((project) => project.id));
+  const offlineCreated = (local?.state.projects ?? []).filter(
+    (project) => !serverIds.has(project.id) && persistedRevisions[project.id] === undefined
+  );
+
+  if (offlineCreated.length > 0) {
+    hasPending = true;
+  }
+
+  let projects = [...serverProjects, ...offlineCreated];
+
+  if (sessionBlob) {
+    lastPushedAccount = JSON.stringify(sessionBlob);
+  }
+
+  const base = local?.state ?? createInitialWorkbenchState();
+  let activeProjectId =
+    options?.openProjectId && projects.some((project) => project.id === options.openProjectId)
+      ? options.openProjectId
+      : sessionBlob && projects.some((project) => project.id === sessionBlob.activeProjectId)
+        ? sessionBlob.activeProjectId
+        : projects.some((project) => project.id === base.activeProjectId)
+          ? base.activeProjectId
+          : (projects[0]?.id ?? '');
+
+  // An explicit "new project" request, or a session with nothing to open
+  // (first run, or /app reached directly with an empty session): start a
+  // fresh draft. The first autosave creates it server-side.
+  if (options?.createNew || projects.length === 0) {
+    const draft = createDraftProject(projects);
+
+    projects = [...projects, draft];
+    activeProjectId = draft.id;
+  }
+
+  const state: WorkbenchState = {
+    ...base,
+    account: sessionBlob?.account ?? base.account,
+    activeProjectId,
+    autosave: { status: 'idle' },
+    backendConnection: { status: 'connecting' },
+    notifications: [],
+    projects,
+  };
+
+  if (serializeSessionBlob(state) !== lastPushedAccount) {
+    hasPending = true;
+  }
+
+  reportProjectSync({
+    hasPendingChanges: hasPending,
+    projects: Object.fromEntries(
+      projects.map((project) => {
+        const entry = syncEntries.get(project.id);
+
+        return [project.id, { isPendingPush: entry === undefined, revision: entry?.revision ?? null }];
+      })
+    ),
+  });
+
+  persistSyncMap();
+
+  const snapshot = createSnapshot(state);
+
+  // Refresh the offline cache with what the server gave us.
+  await localStorageWorkbenchPersistence.saveWorkbench(state);
+
+  return snapshot;
+};
+
+export const syncedWorkbenchPersistence = {
+  /**
+   * Load from the backend, falling back to the localStorage cache when it is
+   * unreachable. Returns null when there is nothing anywhere (first run with
+   * no backend); the caller then keeps its default boot state.
+   */
+  async loadWorkbench(options?: WorkbenchLoadOptions): Promise<WorkbenchPersistenceSnapshot | null> {
+    let local: WorkbenchPersistenceSnapshot | null = null;
+
+    try {
+      local = await localStorageWorkbenchPersistence.loadWorkbench();
+    } catch {
+      local = null;
+    }
+
+    try {
+      return await loadFromBackend(local, options);
+    } catch {
+      // Backend unreachable: run from the cache; saves queue up locally and
+      // replay on reconnect.
+      hasPending = true;
+
+      const persistedRevisions = loadPersistedRevisions();
+
+      for (const [projectId, revision] of Object.entries(persistedRevisions)) {
+        syncEntries.set(projectId, { pushedDoc: null, revision });
+      }
+
+      reportProjectSync({
+        hasPendingChanges: true,
+        projects: Object.fromEntries(
+          (local?.state.projects ?? []).map((project) => [
+            project.id,
+            { isPendingPush: true, revision: persistedRevisions[project.id] ?? null },
+          ])
+        ),
+      });
+
+      // A cache holding an empty session (last tab closed offline) cannot
+      // hydrate the editor; boot a fresh draft instead.
+      return local && local.state.projects.length > 0 ? local : null;
+    }
+  },
+
+  /**
+   * Write-through save: localStorage cache always, then every dirty open
+   * project and the session blob to the backend. Revision conflicts come
+   * back as resolutions for the caller to apply to workbench state. Saving
+   * never deletes anything: a project absent from state is merely closed,
+   * and removal happens only through the library's explicit delete.
+   */
+  async saveWorkbench(state: WorkbenchState): Promise<WorkbenchSaveResult> {
+    const snapshot = createSnapshot(state);
+
+    await localStorageWorkbenchPersistence.saveWorkbench(state);
+
+    hasPending = false;
+
+    const conflicts: ProjectConflictResolution[] = [];
+    const projectSyncInfos: Record<string, ProjectSyncInfo> = {};
+
+    await pushSessionState(state);
+
+    for (const project of state.projects) {
+      const lastAckedDoc = syncEntries.get(project.id)?.pushedDoc ?? null;
+      const documentJson = await pushProject(project, conflicts);
+      const entry = syncEntries.get(project.id);
+
+      projectSyncInfos[project.id] = {
+        isPendingPush: entry?.pushedDoc !== documentJson,
+        revision: entry?.revision ?? null,
+      };
+
+      // The server acknowledged new content for this project — keep the
+      // library summary current without a refetch.
+      if (entry && entry.pushedDoc === documentJson && lastAckedDoc !== documentJson) {
+        upsertProjectSummary({ id: project.id, name: project.name, revision: entry.revision });
+      }
+    }
+
+    persistSyncMap();
+    reportProjectSync({ hasPendingChanges: hasPending, projects: projectSyncInfos });
+
+    return { conflicts, hasPendingChanges: hasPending, snapshot };
+  },
+
+  /** True when local changes have not reached the backend yet. */
+  hasPendingChanges(): boolean {
+    return hasPending;
+  },
+
+  /** Clear everywhere: server projects + session blob, local cache, sync map. */
+  async clearWorkbench(): Promise<void> {
+    try {
+      const summaries = await listProjects();
+
+      await Promise.all(summaries.map((summary) => apiDeleteProject(summary.project_id)));
+      await deleteClientStateValue(SESSION_STATE_KEY);
+    } catch {
+      // Backend unreachable; at least reset this browser.
+    }
+
+    syncEntries.clear();
+    deletedProjectIds.clear();
+    seedProjectLibrary([]);
+    lastPushedAccount = null;
+    hasPending = false;
+
+    try {
+      window.localStorage.removeItem(getSyncMapStorageKey());
+    } catch {
+      // Nothing to clear if storage is unavailable.
+    }
+
+    await localStorageWorkbenchPersistence.clearWorkbench();
+  },
+};
+
+/**
+ * Adopt a full project record fetched (or just created) on the server into
+ * the sync layer, returning the hydrated project ready to open as a tab.
+ */
+export const adoptProjectRecord = (record: ProjectRecordDTO): Project | null => {
+  const project = deserializeProjectDocument(record.data);
+
+  if (!project) {
+    return null;
+  }
+
+  syncEntries.set(record.project_id, { pushedDoc: JSON.stringify(record.data), revision: record.revision });
+  persistSyncMap();
+
+  return project;
+};
+
+/** Hydrate one library project into an openable document; null when it cannot be fetched. */
+export const hydrateProjectFromServer = async (projectId: string): Promise<Project | null> => {
+  try {
+    return adoptProjectRecord(await apiGetProject(projectId));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Push one project's document immediately — used when its tab closes, so the
+ * final edits land on the server even though the project is about to leave
+ * the autosaved state.
+ */
+export const flushProjectToServer = async (project: Project): Promise<void> => {
+  const conflicts: ProjectConflictResolution[] = [];
+
+  await pushProject(project, conflicts);
+  persistSyncMap();
+};
+
+/** Forget a project's sync entry once its tab is closed. */
+export const releaseProjectSync = (projectId: string): void => {
+  syncEntries.delete(projectId);
+  persistSyncMap();
+};
+
+/**
+ * Make an explicit delete safe against in-flight autosaves: pushes for this
+ * id become no-ops, so a save that started before the delete cannot recreate
+ * the project on the server.
+ */
+export const markProjectDeleted = (projectId: string): void => {
+  deletedProjectIds.add(projectId);
+  syncEntries.delete(projectId);
+  persistSyncMap();
+};
+
+/**
+ * The delete failed server-side: let pushes flow again. The dropped sync
+ * entry rebuilds itself on the next save (create → conflict → adopt), so no
+ * edits are lost.
+ */
+export const unmarkProjectDeleted = (projectId: string): void => {
+  deletedProjectIds.delete(projectId);
+};
+
+/**
+ * Persist "no tabs open" — the last tab was closed and the editor is about
+ * to navigate Home, unmounting the autosave loop before it could run.
+ */
+export const persistEmptySession = async (state: WorkbenchState): Promise<void> => {
+  const emptied: WorkbenchState = { ...state, activeProjectId: '', projects: [] };
+
+  await localStorageWorkbenchPersistence.saveWorkbench(emptied);
+
+  try {
+    const blob = serializeSessionBlob(emptied);
+
+    await setClientStateValue(SESSION_STATE_KEY, blob);
+    lastPushedAccount = blob;
+  } catch {
+    hasPending = true;
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/projects/useProjectActions.ts b/invokeai/frontend/webv2/src/workbench/projects/useProjectActions.ts
new file mode 100644
index 00000000000..8e7640d2269
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/projects/useProjectActions.ts
@@ -0,0 +1,91 @@
+import type { Project } from '@workbench/types';
+
+import { useNavigate } from '@tanstack/react-router';
+import { useNotify } from '@workbench/useNotify';
+import { flushGenerateDrafts } from '@workbench/widgets/generate/generateDraftRegistry';
+import { useWorkbenchDispatch, useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useTranslation } from 'react-i18next';
+
+import { deleteLibraryProject } from './library';
+import {
+  flushProjectToServer,
+  markProjectDeleted,
+  persistEmptySession,
+  releaseProjectSync,
+  unmarkProjectDeleted,
+} from './syncedPersistence';
+
+/**
+ * Close and delete for projects that are open in the editor, shared by the
+ * tab bar and the Project panel so the semantics stay in one place:
+ *
+ * - Close flushes the document, drops the tab, and keeps the project in the
+ *   library. Closing the last tab persists the empty session and lands on
+ *   Home — an editor with no documents is the Home screen.
+ * - Delete removes the project from the server (the only path that does, for
+ *   open projects) and then closes its tab.
+ */
+export const useProjectActions = (): {
+  closeProject: (project: Project) => void;
+  deleteProject: (project: Project) => Promise<void>;
+} => {
+  const store = useWorkbenchStore();
+  const dispatch = useWorkbenchDispatch();
+  const navigate = useNavigate();
+  const notify = useNotify();
+  const { t } = useTranslation();
+
+  /** When the last tab goes, the session empties and Home takes over. */
+  const leaveEditorIfLast = (projectId: string): boolean => {
+    const state = store.getState();
+
+    if (state.projects.some((project) => project.id !== projectId)) {
+      return false;
+    }
+
+    void persistEmptySession(state);
+    void navigate({ to: '/' });
+
+    return true;
+  };
+
+  const closeProject = (project: Project): void => {
+    flushGenerateDrafts();
+
+    const projectToFlush = store.getState().projects.find((candidate) => candidate.id === project.id) ?? project;
+
+    void flushProjectToServer(projectToFlush).finally(() => {
+      releaseProjectSync(project.id);
+    });
+
+    if (leaveEditorIfLast(project.id)) {
+      return;
+    }
+
+    dispatch({ projectId: project.id, type: 'closeProject' });
+  };
+
+  const deleteProject = async (project: Project): Promise<void> => {
+    flushGenerateDrafts();
+    // Marked before the request so an in-flight autosave cannot recreate the
+    // project server-side between the DELETE and the tab closing.
+    markProjectDeleted(project.id);
+
+    try {
+      await deleteLibraryProject(project.id);
+    } catch (error) {
+      unmarkProjectDeleted(project.id);
+      notify.error(t('projects.deleteFailed'), error instanceof Error ? error.message : undefined);
+
+      return;
+    }
+
+    if (leaveEditorIfLast(project.id)) {
+      return;
+    }
+
+    dispatch({ projectId: project.id, type: 'closeProject' });
+  };
+
+  return { closeProject, deleteProject };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/queueSubmission.test.ts b/invokeai/frontend/webv2/src/workbench/queueSubmission.test.ts
new file mode 100644
index 00000000000..454a5b79b72
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/queueSubmission.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import type { InvocationSourceId, QueueItem, QueueItemStatus } from './types';
+
+import {
+  BACKEND_SUBMITTABLE_SOURCE_IDS,
+  isBackendSubmittableSourceId,
+  shouldSubmitPendingQueueItem,
+} from './queueSubmission';
+
+/** Minimal queue item whose submission gate only reads `status` + `snapshot.sourceId`. */
+const makeQueueItem = (sourceId: InvocationSourceId, status: QueueItemStatus): QueueItem =>
+  ({
+    id: 'queue-item-1',
+    status,
+    cancellable: true,
+    snapshot: { sourceId },
+  }) as unknown as QueueItem;
+
+describe('isBackendSubmittableSourceId', () => {
+  it('includes canvas so canvas invocations are actually enqueued (regression: canvas→canvas stall)', () => {
+    // The bug: canvas snapshots carry sourceId 'canvas'; the runtime allow-list
+    // only had 'generate'/'workflow', so canvas items stacked as local pending
+    // rows forever and nothing generated.
+    expect(isBackendSubmittableSourceId('canvas')).toBe(true);
+  });
+
+  it('includes generate and workflow', () => {
+    expect(isBackendSubmittableSourceId('generate')).toBe(true);
+    expect(isBackendSubmittableSourceId('workflow')).toBe(true);
+  });
+
+  it('excludes upscale (not yet an available source)', () => {
+    expect(isBackendSubmittableSourceId('upscale')).toBe(false);
+  });
+
+  it('exposes canvas in the exported allow-list', () => {
+    expect(BACKEND_SUBMITTABLE_SOURCE_IDS).toContain('canvas');
+  });
+});
+
+describe('shouldSubmitPendingQueueItem', () => {
+  it('submits a pending canvas item', () => {
+    expect(shouldSubmitPendingQueueItem(makeQueueItem('canvas', 'pending'))).toBe(true);
+  });
+
+  it('submits a pending generate item', () => {
+    expect(shouldSubmitPendingQueueItem(makeQueueItem('generate', 'pending'))).toBe(true);
+  });
+
+  it('does not submit a non-pending canvas item', () => {
+    expect(shouldSubmitPendingQueueItem(makeQueueItem('canvas', 'running'))).toBe(false);
+    expect(shouldSubmitPendingQueueItem(makeQueueItem('canvas', 'completed'))).toBe(false);
+    expect(shouldSubmitPendingQueueItem(makeQueueItem('canvas', 'cancelled'))).toBe(false);
+  });
+
+  it('does not submit a pending item whose source is not submittable', () => {
+    expect(shouldSubmitPendingQueueItem(makeQueueItem('upscale', 'pending'))).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/queueSubmission.ts b/invokeai/frontend/webv2/src/workbench/queueSubmission.ts
new file mode 100644
index 00000000000..c3d1a2f13fc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/queueSubmission.ts
@@ -0,0 +1,46 @@
+/**
+ * Which pending queue items the {@link import('./WorkbenchRuntime').WorkbenchRuntime}
+ * submission bridge is allowed to POST to the backend queue.
+ *
+ * This is the gate that decides whether a locally-enqueued `pending` queue item
+ * gets handed to the coordinator (`submitGenerate` / `submitWorkflow`). It lives
+ * in its own pure module — separate from the React effect that consumes it — so
+ * it can be unit-tested under node-env vitest (the runtime component cannot).
+ *
+ * ## Why `canvas` MUST be here
+ * Every Invoke — generate, workflow, AND canvas — first lands an optimistic local
+ * `pending` queue item (see `enqueueCompiledSnapshot`). The runtime loop then
+ * enqueues each pending item to the backend exactly once. If a source id is
+ * missing from this set, its items are created locally but **never POSTed**, so
+ * they stack in the queue as `pending` forever and nothing ever generates. That
+ * was the canvas→canvas stall: canvas snapshots carry `sourceId: 'canvas'`, which
+ * was absent from the loop's allow-list, so each Invoke only produced a dead
+ * local row. Canvas items use the generate-style backend submission path: the
+ * graph is compiled ahead of time, but prompt/seed batch data still has to ride
+ * along so repeated invokes are not silently run with backend primitive defaults.
+ *
+ * `upscale` is intentionally excluded: it is not yet an available source
+ * (`invocation.ts` marks it `available: false`), so it never produces a snapshot.
+ */
+
+import type { InvocationSourceId, QueueItem } from './types';
+
+/** Source kinds whose pending queue items the runtime enqueues to the backend. */
+export const BACKEND_SUBMITTABLE_SOURCE_IDS = [
+  'generate',
+  'workflow',
+  'canvas',
+] as const satisfies readonly InvocationSourceId[];
+
+const BACKEND_SUBMITTABLE_SOURCE_ID_SET: ReadonlySet<InvocationSourceId> = new Set(BACKEND_SUBMITTABLE_SOURCE_IDS);
+
+/** Whether a queue item's source is one the runtime knows how to enqueue. */
+export const isBackendSubmittableSourceId = (sourceId: InvocationSourceId): boolean =>
+  BACKEND_SUBMITTABLE_SOURCE_ID_SET.has(sourceId);
+
+/**
+ * Whether a queue item is a fresh, backend-submittable `pending` item — the
+ * runtime still applies its own "already started this id" dedupe on top of this.
+ */
+export const shouldSubmitPendingQueueItem = (queueItem: QueueItem): boolean =>
+  queueItem.status === 'pending' && isBackendSubmittableSourceId(queueItem.snapshot.sourceId);
diff --git a/invokeai/frontend/webv2/src/workbench/queueSummary.test.ts b/invokeai/frontend/webv2/src/workbench/queueSummary.test.ts
new file mode 100644
index 00000000000..a57843d032a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/queueSummary.test.ts
@@ -0,0 +1,282 @@
+import { describe, expect, it } from 'vitest';
+
+import type { QueueItemProgress } from './backend/progressStore';
+import type { QueueItem } from './types';
+
+import {
+  getProjectQueueIndicatorState,
+  getQueueProgressBarState,
+  getQueueProgressBarValue,
+  getQueueSummary,
+} from './queueSummary';
+
+const createQueueItem = ({
+  backendItemIds,
+  batchCount = 1,
+  id,
+  sourceId = 'generate',
+  status = 'pending',
+  submittedAt,
+}: {
+  backendItemIds?: number[];
+  batchCount?: number;
+  id: string;
+  sourceId?: QueueItem['snapshot']['sourceId'];
+  status?: QueueItem['status'];
+  submittedAt: string;
+}): QueueItem => ({
+  backendItemIds,
+  cancellable: true,
+  id,
+  snapshot: {
+    canvas: {
+      document: {
+        background: 'transparent',
+        bbox: { height: 1024, width: 1024, x: 0, y: 0 },
+        height: 1024,
+        layers: [],
+        selectedLayerId: null,
+        version: 2,
+        width: 1024,
+      },
+      documentRevision: 0,
+      snapshots: [],
+      stagingArea: {
+        areThumbnailsVisible: false,
+        autoSwitchMode: 'off',
+        isVisible: false,
+        pendingImageIds: [],
+        pendingImages: [],
+        selectedImageIndex: 0,
+      },
+      version: 2,
+    },
+    destination: 'gallery',
+    graph: { edges: [], id: 'graph-1', label: 'Graph', nodes: [], updatedAt: submittedAt, version: 1 },
+    sourceId,
+    submittedAt,
+    widgetInstances: {},
+    widgetStates: {
+      generate: { id: 'generate', label: 'Generate', values: { batchCount }, version: 1 },
+    } as unknown as QueueItem['snapshot']['widgetStates'],
+  },
+  status,
+});
+
+describe('getQueueSummary', () => {
+  it('counts image slots inside the running batch', () => {
+    const summary = getQueueSummary([
+      createQueueItem({
+        backendItemIds: [1, 2, 3, 4],
+        batchCount: 4,
+        id: 'batch-1',
+        status: 'running',
+        submittedAt: '2026-06-10T00:00:00.000Z',
+      }),
+    ]);
+
+    expect(summary).toEqual({ current: 1, runningQueueItemId: 'batch-1', total: 4 });
+  });
+
+  it('keeps the running ordinal stable when newer work is queued', () => {
+    const summary = getQueueSummary([
+      createQueueItem({
+        batchCount: 4,
+        id: 'batch-2',
+        status: 'pending',
+        submittedAt: '2026-06-10T00:01:00.000Z',
+      }),
+      createQueueItem({
+        backendItemIds: [1, 2, 3, 4],
+        batchCount: 4,
+        id: 'batch-1',
+        status: 'running',
+        submittedAt: '2026-06-10T00:00:00.000Z',
+      }),
+    ]);
+
+    expect(summary).toEqual({ current: 1, runningQueueItemId: 'batch-1', total: 8 });
+  });
+
+  it('uses live progress to advance within a batch', () => {
+    const progress: QueueItemProgress = {
+      activeItemIndex: 2,
+      completedItemCount: 1,
+      message: '',
+      percentage: null,
+      totalItemCount: 4,
+    };
+    const summary = getQueueSummary(
+      [
+        createQueueItem({
+          backendItemIds: [1, 2, 3, 4],
+          batchCount: 4,
+          id: 'batch-1',
+          status: 'running',
+          submittedAt: '2026-06-10T00:00:00.000Z',
+        }),
+        createQueueItem({
+          batchCount: 4,
+          id: 'batch-2',
+          status: 'pending',
+          submittedAt: '2026-06-10T00:01:00.000Z',
+        }),
+      ],
+      progress
+    );
+
+    expect(summary).toEqual({ current: 2, runningQueueItemId: 'batch-1', total: 8 });
+  });
+
+  it('returns zeroes when all batches are terminal', () => {
+    const summary = getQueueSummary([
+      createQueueItem({ batchCount: 4, id: 'batch-1', status: 'completed', submittedAt: '2026-06-10T00:00:00.000Z' }),
+    ]);
+
+    expect(summary).toEqual({ current: 0, runningQueueItemId: null, total: 0 });
+  });
+
+  it('uses the global batch count for workflow-sourced queue items', () => {
+    const summary = getQueueSummary([
+      createQueueItem({
+        batchCount: 2,
+        id: 'workflow-batch',
+        sourceId: 'workflow',
+        status: 'pending',
+        submittedAt: '2026-06-10T00:00:00.000Z',
+      }),
+    ]);
+
+    expect(summary).toEqual({ current: 0, runningQueueItemId: null, total: 2 });
+  });
+
+  it('does not cap oversized batch counts', () => {
+    const summary = getQueueSummary([
+      createQueueItem({
+        batchCount: 10_000,
+        id: 'oversized-batch',
+        status: 'pending',
+        submittedAt: '2026-06-10T00:00:00.000Z',
+      }),
+    ]);
+
+    expect(summary).toEqual({ current: 0, runningQueueItemId: null, total: 10_000 });
+  });
+});
+
+describe('getProjectQueueIndicatorState', () => {
+  it('returns idle state for projects without open queue work', () => {
+    expect(
+      getProjectQueueIndicatorState({ isConnected: true, loadingModelsCount: 0, progress: null, queueItems: [] })
+    ).toEqual({ hasOpenQueueWork: false, progressState: { kind: 'idle', value: 0 }, runningQueueItemId: null });
+  });
+
+  it('returns indeterminate state for running work without percentage progress', () => {
+    const queueItems = [createQueueItem({ id: 'running', status: 'running', submittedAt: '2026-06-10T00:00:00.000Z' })];
+
+    expect(
+      getProjectQueueIndicatorState({ isConnected: true, loadingModelsCount: 0, progress: null, queueItems })
+    ).toEqual({
+      hasOpenQueueWork: true,
+      progressState: { kind: 'indeterminate', value: null },
+      runningQueueItemId: 'running',
+    });
+  });
+
+  it('returns determinate state for running work with percentage progress', () => {
+    const queueItems = [createQueueItem({ id: 'running', status: 'running', submittedAt: '2026-06-10T00:00:00.000Z' })];
+    const progress: QueueItemProgress = { message: 'Denoising', percentage: 0.42 };
+
+    expect(getProjectQueueIndicatorState({ isConnected: true, loadingModelsCount: 0, progress, queueItems })).toEqual({
+      hasOpenQueueWork: true,
+      progressState: { kind: 'determinate', value: 0.42 },
+      runningQueueItemId: 'running',
+    });
+  });
+
+  it('uses indeterminate state while models load for pending work', () => {
+    const queueItems = [createQueueItem({ id: 'pending', status: 'pending', submittedAt: '2026-06-10T00:00:00.000Z' })];
+
+    expect(
+      getProjectQueueIndicatorState({ isConnected: true, loadingModelsCount: 1, progress: null, queueItems })
+    ).toEqual({
+      hasOpenQueueWork: true,
+      progressState: { kind: 'indeterminate', value: null },
+      runningQueueItemId: null,
+    });
+  });
+});
+
+describe('getQueueProgressBarValue', () => {
+  it('returns an idle state when there is no active work', () => {
+    expect(
+      getQueueProgressBarState({ isConnected: true, isRunning: false, loadingModelsCount: 0, progress: null })
+    ).toEqual({ kind: 'idle', value: 0 });
+  });
+
+  it('matches legacy indeterminate conditions', () => {
+    expect(
+      getQueueProgressBarState({ isConnected: true, isRunning: false, loadingModelsCount: 1, progress: null })
+    ).toEqual({ kind: 'indeterminate', value: null });
+    expect(
+      getQueueProgressBarValue({ isConnected: true, isRunning: false, loadingModelsCount: 1, progress: null })
+    ).toBeNull();
+    expect(
+      getQueueProgressBarValue({ isConnected: true, isRunning: true, loadingModelsCount: 0, progress: null })
+    ).toBeNull();
+    expect(
+      getQueueProgressBarValue({
+        isConnected: true,
+        isRunning: true,
+        loadingModelsCount: 0,
+        progress: { message: '', percentage: null },
+      })
+    ).toBeNull();
+    expect(
+      getQueueProgressBarValue({
+        isConnected: true,
+        isRunning: true,
+        loadingModelsCount: 0,
+        progress: { message: '', percentage: 0 },
+      })
+    ).toBeNull();
+  });
+
+  it('returns determinate progress when backend reports a non-zero percentage', () => {
+    expect(
+      getQueueProgressBarState({
+        isConnected: true,
+        isRunning: true,
+        loadingModelsCount: 0,
+        progress: { message: 'Denoising', percentage: 0.42 },
+      })
+    ).toEqual({ kind: 'determinate', value: 0.42 });
+    expect(
+      getQueueProgressBarValue({
+        isConnected: true,
+        isRunning: true,
+        loadingModelsCount: 0,
+        progress: { message: 'Denoising', percentage: 0.42 },
+      })
+    ).toBe(0.42);
+  });
+
+  it('resets to zero while disconnected', () => {
+    expect(
+      getQueueProgressBarState({
+        isConnected: false,
+        isRunning: true,
+        loadingModelsCount: 1,
+        progress: { message: 'Denoising', percentage: 0.42 },
+      })
+    ).toEqual({ kind: 'idle', value: 0 });
+    expect(
+      getQueueProgressBarValue({
+        isConnected: false,
+        isRunning: true,
+        loadingModelsCount: 1,
+        progress: { message: 'Denoising', percentage: 0.42 },
+      })
+    ).toBe(0);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/queueSummary.ts b/invokeai/frontend/webv2/src/workbench/queueSummary.ts
new file mode 100644
index 00000000000..ca0c642f8e4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/queueSummary.ts
@@ -0,0 +1,133 @@
+import type { QueueItemProgress } from './backend/progressStore';
+import type { QueueItem } from './types';
+
+import { sanitizeBatchCount } from './generation/batch';
+
+export interface QueueSummary {
+  current: number;
+  runningQueueItemId: string | null;
+  total: number;
+}
+
+export interface ProjectQueueIndicatorState {
+  hasOpenQueueWork: boolean;
+  progressState: QueueProgressBarState;
+  runningQueueItemId: string | null;
+}
+
+export type QueueProgressBarState =
+  | { kind: 'determinate'; value: number }
+  | { kind: 'idle'; value: 0 }
+  | { kind: 'indeterminate'; value: null };
+
+export const getQueueProgressBarState = ({
+  isConnected,
+  isRunning,
+  loadingModelsCount,
+  progress,
+}: {
+  isConnected: boolean;
+  isRunning: boolean;
+  loadingModelsCount: number;
+  progress: QueueItemProgress | null;
+}): QueueProgressBarState => {
+  if (!isConnected) {
+    return { kind: 'idle', value: 0 };
+  }
+
+  if (loadingModelsCount > 0) {
+    return { kind: 'indeterminate', value: null };
+  }
+
+  if (isRunning && (!progress || progress.percentage === null || progress.percentage === 0)) {
+    return { kind: 'indeterminate', value: null };
+  }
+
+  if (isRunning) {
+    return { kind: 'determinate', value: progress?.percentage ?? 0 };
+  }
+
+  return { kind: 'idle', value: 0 };
+};
+
+export const getQueueProgressBarValue = (params: Parameters<typeof getQueueProgressBarState>[0]): number | null =>
+  getQueueProgressBarState(params).value;
+
+export const isOpenQueueItem = (item: QueueItem): boolean => item.status === 'pending' || item.status === 'running';
+
+export const getQueueItemExpectedImageCount = (item: QueueItem): number => {
+  if (item.backendItemIds?.length) {
+    return item.backendItemIds.length;
+  }
+
+  const batchCount = item.snapshot.widgetStates.generate?.values.batchCount;
+
+  return sanitizeBatchCount(batchCount);
+};
+
+const compareQueuePosition = (a: QueueItem, b: QueueItem): number => {
+  const aTime = Date.parse(a.snapshot.submittedAt);
+  const bTime = Date.parse(b.snapshot.submittedAt);
+
+  return (Number.isFinite(aTime) ? aTime : 0) - (Number.isFinite(bTime) ? bTime : 0);
+};
+
+const getRunningImageOrdinal = (item: QueueItem, progress: QueueItemProgress | null): number => {
+  const expectedCount = getQueueItemExpectedImageCount(item);
+  const completedCount = progress?.completedItemCount ?? 0;
+  const activeIndex = progress?.activeItemIndex ?? completedCount + 1;
+
+  return Math.min(expectedCount, Math.max(1, activeIndex));
+};
+
+export const getQueueSummary = (items: QueueItem[], progress: QueueItemProgress | null = null): QueueSummary => {
+  const openItems = items.filter(isOpenQueueItem).sort(compareQueuePosition);
+  const total = openItems.reduce((sum, item) => sum + getQueueItemExpectedImageCount(item), 0);
+
+  if (total === 0) {
+    return { current: 0, runningQueueItemId: null, total: 0 };
+  }
+
+  const runningItem = openItems.find((item) => item.status === 'running');
+
+  if (!runningItem) {
+    return { current: 0, runningQueueItemId: null, total };
+  }
+
+  let current = 0;
+
+  for (const item of openItems) {
+    if (item.id === runningItem.id) {
+      current += getRunningImageOrdinal(item, progress);
+      break;
+    }
+
+    current += getQueueItemExpectedImageCount(item);
+  }
+
+  return { current: Math.min(current, total), runningQueueItemId: runningItem.id, total };
+};
+
+export const getProjectQueueIndicatorState = ({
+  isConnected,
+  loadingModelsCount,
+  progress,
+  queueItems,
+}: {
+  isConnected: boolean;
+  loadingModelsCount: number;
+  progress: QueueItemProgress | null;
+  queueItems: QueueItem[];
+}): ProjectQueueIndicatorState => {
+  const summary = getQueueSummary(queueItems, progress);
+  const hasOpenQueueWork = summary.total > 0;
+  const isRunning = summary.runningQueueItemId !== null;
+
+  return {
+    hasOpenQueueWork,
+    progressState: hasOpenQueueWork
+      ? getQueueProgressBarState({ isConnected, isRunning, loadingModelsCount, progress })
+      : { kind: 'idle', value: 0 },
+    runningQueueItemId: summary.runningQueueItemId,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/settings/HotkeysSettingsSection.tsx b/invokeai/frontend/webv2/src/workbench/settings/HotkeysSettingsSection.tsx
new file mode 100644
index 00000000000..240dd1a34f4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/settings/HotkeysSettingsSection.tsx
@@ -0,0 +1,604 @@
+import type { HotkeyCategory, HotkeyDefinition } from '@workbench/hotkeys';
+
+import { Badge, Box, Flex, HStack, Icon, Input, InputGroup, Kbd, ScrollArea, Stack, Text } from '@chakra-ui/react';
+import { Button, IconButton } from '@workbench/components/ui';
+import {
+  firstPartyHotkeyCatalog,
+  formatHotkeyForPlatform,
+  normalizeHotkeyString,
+  eventToHotkeyString,
+  useExtensionHotkeyDefinitions,
+} from '@workbench/hotkeys';
+import { patchWorkbenchPreferences, useWorkbenchPreferences } from '@workbench/settings/store';
+import { CheckIcon, PlusIcon, RotateCcwIcon, SearchIcon, Trash2Icon, XIcon } from 'lucide-react';
+import { Fragment, useCallback, useDeferredValue, useEffect, useMemo, useRef, useState } from 'react';
+import { useVirtualizer } from 'react-hook-tanstack-virtual';
+import { useTranslation } from 'react-i18next';
+
+type HotkeyConflict = { hotkey: HotkeyDefinition; title: string };
+
+type HotkeyRow =
+  | { kind: 'category'; category: HotkeyCategory; title: string }
+  | { kind: 'hotkey'; hotkey: HotkeyDefinition; effectiveKeys: string[]; isCustomized: boolean };
+
+const CATEGORY_LABEL_KEYS: Record<HotkeyCategory, string> = {
+  app: 'hotkeys.categories.app',
+  canvas: 'hotkeys.categories.canvas',
+  gallery: 'hotkeys.categories.gallery',
+  viewer: 'hotkeys.categories.viewer',
+  workflows: 'hotkeys.categories.workflows',
+};
+
+const CATEGORY_ORDER: HotkeyCategory[] = ['app', 'canvas', 'workflows', 'viewer', 'gallery'];
+
+const SEARCH_START_ELEMENT = <Icon as={SearchIcon} boxSize="3.5" />;
+
+const normalizeKeys = (keys: string[]): string[] => keys.map(normalizeHotkeyString).filter(Boolean);
+
+const titleFromId = (id: string): string =>
+  id
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replaceAll('.', ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+
+const getHotkeyTitle = (hotkey: HotkeyDefinition): string => hotkey.title || titleFromId(hotkey.id);
+
+const getScopeRank = (hotkey: HotkeyDefinition): number => {
+  if (hotkey.scope.kind === 'instance') {
+    return 400;
+  }
+
+  if (hotkey.scope.kind === 'widget') {
+    return 300;
+  }
+
+  if (hotkey.scope.kind === 'focused-region') {
+    return 200;
+  }
+
+  return 100;
+};
+
+const canScopesOverlap = (left: HotkeyDefinition, right: HotkeyDefinition): boolean => {
+  if (getScopeRank(left) !== getScopeRank(right)) {
+    return false;
+  }
+
+  if (left.scope.kind === 'global' && right.scope.kind === 'global') {
+    return true;
+  }
+
+  if (left.scope.kind === 'widget' && right.scope.kind === 'widget') {
+    return left.scope.typeId === right.scope.typeId;
+  }
+
+  if (left.scope.kind === 'instance' && right.scope.kind === 'instance') {
+    return left.scope.instanceId === right.scope.instanceId;
+  }
+
+  if (left.scope.kind === 'focused-region' && right.scope.kind === 'focused-region') {
+    return !left.scope.region || !right.scope.region || left.scope.region === right.scope.region;
+  }
+
+  return false;
+};
+
+const buildConflictMap = (
+  catalog: HotkeyDefinition[],
+  customHotkeys: Record<string, string[]>
+): Map<string, HotkeyConflict[]> => {
+  const conflicts = new Map<string, HotkeyConflict[]>();
+
+  for (const hotkey of catalog) {
+    if (hotkey.implemented === false) {
+      continue;
+    }
+
+    const effectiveKeys = normalizeKeys(customHotkeys[hotkey.id] ?? hotkey.defaultKeys);
+
+    for (const key of effectiveKeys) {
+      const entries = conflicts.get(key) ?? [];
+
+      entries.push({ hotkey, title: getHotkeyTitle(hotkey) });
+      conflicts.set(key, entries);
+    }
+  }
+
+  return conflicts;
+};
+
+const isHotkeyCustomized = (hotkey: HotkeyDefinition, customHotkeys: Record<string, string[]>): boolean =>
+  Object.prototype.hasOwnProperty.call(customHotkeys, hotkey.id);
+
+const buildRows = ({
+  catalog,
+  customHotkeys,
+  searchTerm,
+}: {
+  catalog: HotkeyDefinition[];
+  customHotkeys: Record<string, string[]>;
+  searchTerm: string;
+}): HotkeyRow[] => {
+  const needle = searchTerm.trim().toLowerCase();
+  const rows: HotkeyRow[] = [];
+
+  for (const category of CATEGORY_ORDER) {
+    const hotkeys = catalog
+      .filter((hotkey) => hotkey.category === category)
+      .filter((hotkey) => {
+        if (!needle) {
+          return true;
+        }
+
+        const haystack = [getHotkeyTitle(hotkey), hotkey.description, hotkey.id, hotkey.defaultKeys.join(' ')]
+          .filter(Boolean)
+          .join(' ')
+          .toLowerCase();
+
+        return haystack.includes(needle);
+      });
+
+    if (hotkeys.length === 0) {
+      continue;
+    }
+
+    rows.push({ category, kind: 'category', title: CATEGORY_LABEL_KEYS[category] });
+
+    for (const hotkey of hotkeys) {
+      rows.push({
+        effectiveKeys: normalizeKeys(customHotkeys[hotkey.id] ?? hotkey.defaultKeys),
+        hotkey,
+        isCustomized: isHotkeyCustomized(hotkey, customHotkeys),
+        kind: 'hotkey',
+      });
+    }
+  }
+
+  return rows;
+};
+
+export const HotkeysSettingsSection = () => {
+  const { t } = useTranslation();
+  const { customHotkeys } = useWorkbenchPreferences();
+  const extensionHotkeys = useExtensionHotkeyDefinitions();
+  const [searchTerm, setSearchTerm] = useState('');
+  const deferredSearchTerm = useDeferredValue(searchTerm);
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const catalog = useMemo(() => [...firstPartyHotkeyCatalog, ...extensionHotkeys], [extensionHotkeys]);
+  const rows = useMemo(
+    () => buildRows({ catalog, customHotkeys, searchTerm: deferredSearchTerm }),
+    [catalog, customHotkeys, deferredSearchTerm]
+  );
+  const conflictMap = useMemo(() => buildConflictMap(catalog, customHotkeys), [catalog, customHotkeys]);
+  const modifiedCount = Object.keys(customHotkeys).length;
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    estimateSize: (index) => (rows[index]?.kind === 'category' ? 36 : 86),
+    getScrollElement: () => scrollRef.current,
+    measureElement: (element) => element.getBoundingClientRect().height,
+    overscan: 8,
+  });
+
+  const saveHotkey = useCallback(
+    (hotkeyId: string, keys: string[]) => {
+      void patchWorkbenchPreferences({ customHotkeys: { ...customHotkeys, [hotkeyId]: normalizeKeys(keys) } });
+    },
+    [customHotkeys]
+  );
+
+  const resetHotkey = useCallback(
+    (hotkeyId: string) => {
+      const next = { ...customHotkeys };
+
+      delete next[hotkeyId];
+      void patchWorkbenchPreferences({ customHotkeys: next });
+    },
+    [customHotkeys]
+  );
+
+  const resetAll = useCallback(() => {
+    void patchWorkbenchPreferences({ customHotkeys: {} });
+  }, []);
+  const handleSearchChange = useCallback((event: { currentTarget: { value: string } }) => {
+    setSearchTerm(event.currentTarget.value);
+  }, []);
+
+  const virtualRows = virtualizer.virtualItems;
+
+  return (
+    <Stack h="full" minH="0">
+      <HStack justify="space-between" gap="3">
+        <Stack gap="0.5">
+          <Text color="fg" fontSize="sm" fontWeight="600">
+            {t('hotkeys.title')}
+          </Text>
+          <Text color="fg.subtle" fontSize="xs">
+            {t('hotkeys.description')}
+          </Text>
+        </Stack>
+        <Button disabled={modifiedCount === 0} size="xs" variant="outline" onClick={resetAll}>
+          <RotateCcwIcon />
+          {t('hotkeys.resetAll')}
+        </Button>
+      </HStack>
+
+      <InputGroup startElement={SEARCH_START_ELEMENT}>
+        <Input
+          placeholder={t('hotkeys.searchPlaceholder')}
+          size="xs"
+          value={searchTerm}
+          onChange={handleSearchChange}
+        />
+      </InputGroup>
+
+      <ScrollArea.Root flex="1" minH="0" rounded="md" size="xs" variant="hover" w="full">
+        <ScrollArea.Viewport ref={scrollRef} aria-label={t('hotkeys.bindings')} h="full" w="full">
+          <ScrollArea.Content w="full">
+            <Box h={`${virtualizer.totalSize}px`} position="relative" w="full">
+              {virtualRows.map((row) => {
+                const item = rows[row.index];
+
+                if (!item) {
+                  return null;
+                }
+
+                return (
+                  <Box
+                    key={row.key}
+                    ref={virtualizer.measureElement}
+                    data-index={row.index}
+                    position="absolute"
+                    top="0"
+                    transform={`translateY(${row.start}px)`}
+                    w="full"
+                  >
+                    <VirtualHotkeyRow
+                      conflictMap={conflictMap}
+                      item={item}
+                      resetHotkey={resetHotkey}
+                      saveHotkey={saveHotkey}
+                    />
+                  </Box>
+                );
+              })}
+            </Box>
+          </ScrollArea.Content>
+        </ScrollArea.Viewport>
+        <ScrollArea.Scrollbar>
+          <ScrollArea.Thumb />
+        </ScrollArea.Scrollbar>
+      </ScrollArea.Root>
+    </Stack>
+  );
+};
+
+const CategoryRow = ({ title }: { title: string }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Flex align="center" borderBottomWidth="1px" pb="2" pt="4">
+      <Text color="fg.muted" fontSize="2xs" fontWeight="800" letterSpacing="0.08em" textTransform="uppercase">
+        {t(title)}
+      </Text>
+    </Flex>
+  );
+};
+
+const VirtualHotkeyRow = ({
+  conflictMap,
+  item,
+  resetHotkey,
+  saveHotkey,
+}: {
+  conflictMap: Map<string, HotkeyConflict[]>;
+  item: HotkeyRow;
+  resetHotkey: (hotkeyId: string) => void;
+  saveHotkey: (hotkeyId: string, keys: string[]) => void;
+}) => {
+  const handleReset = useCallback(() => {
+    if (item.kind === 'hotkey') {
+      resetHotkey(item.hotkey.id);
+    }
+  }, [item, resetHotkey]);
+  const handleSave = useCallback(
+    (keys: string[]) => {
+      if (item.kind === 'hotkey') {
+        saveHotkey(item.hotkey.id, keys);
+      }
+    },
+    [item, saveHotkey]
+  );
+
+  if (item.kind === 'category') {
+    return <CategoryRow title={item.title} />;
+  }
+
+  return (
+    <HotkeyListRow
+      key={item.effectiveKeys.join('\n')}
+      conflictMap={conflictMap}
+      effectiveKeys={item.effectiveKeys}
+      hotkey={item.hotkey}
+      isCustomized={item.isCustomized}
+      onReset={handleReset}
+      onSave={handleSave}
+    />
+  );
+};
+
+const HotkeyListRow = ({
+  conflictMap,
+  effectiveKeys,
+  hotkey,
+  isCustomized,
+  onReset,
+  onSave,
+}: {
+  conflictMap: Map<string, HotkeyConflict[]>;
+  effectiveKeys: string[];
+  hotkey: HotkeyDefinition;
+  isCustomized: boolean;
+  onReset: () => void;
+  onSave: (keys: string[]) => void;
+}) => {
+  const { t } = useTranslation();
+  const [draftKeys, setDraftKeys] = useState(effectiveKeys);
+  const [editingIndex, setEditingIndex] = useState<number | null>(null);
+  const isEditing = editingIndex !== null;
+  const isDirty = draftKeys.join('\n') !== effectiveKeys.join('\n');
+  const hasDuplicate = new Set(draftKeys).size !== draftKeys.length;
+  const conflict =
+    hotkey.implemented === false
+      ? undefined
+      : draftKeys
+          .flatMap((key) => conflictMap.get(key) ?? [])
+          .find((entry) => entry.hotkey.id !== hotkey.id && canScopesOverlap(hotkey, entry.hotkey));
+  const canSave = !hasDuplicate && !conflict && (isDirty || isEditing);
+
+  const updateDraftKey = useCallback((index: number, key: string) => {
+    setDraftKeys((current) => current.map((candidate, candidateIndex) => (candidateIndex === index ? key : candidate)));
+  }, []);
+
+  const deleteDraftKey = useCallback((index: number) => {
+    setDraftKeys((current) => current.filter((_key, candidateIndex) => candidateIndex !== index));
+    setEditingIndex(null);
+  }, []);
+
+  const addDraftKey = useCallback(() => {
+    setDraftKeys((current) => [...current, '']);
+    setEditingIndex(draftKeys.length);
+  }, [draftKeys.length]);
+
+  const cancelEdit = useCallback(() => {
+    setDraftKeys(effectiveKeys);
+    setEditingIndex(null);
+  }, [effectiveKeys]);
+
+  const saveEdit = useCallback(() => {
+    if (!canSave) {
+      return;
+    }
+
+    onSave(draftKeys);
+    setEditingIndex(null);
+  }, [canSave, draftKeys, onSave]);
+
+  const disableHotkey = useCallback(() => {
+    onSave([]);
+    setEditingIndex(null);
+  }, [onSave]);
+
+  const cancelChipEdit = useCallback(() => setEditingIndex(null), []);
+
+  return (
+    <Flex borderBottomWidth="1px" gap="3" py="2.5">
+      <Stack flex="1" gap="1" minW="0">
+        <HStack gap="2">
+          <Text color="fg" fontSize="sm" fontWeight="600" truncate>
+            {getHotkeyTitle(hotkey)}
+          </Text>
+          {hotkey.implemented === false ? (
+            <Badge colorPalette="gray" size="xs" variant="surface">
+              {t('hotkeys.pending')}
+            </Badge>
+          ) : null}
+          {isCustomized ? (
+            <Badge colorPalette="blue" size="xs" variant="surface">
+              {t('hotkeys.custom')}
+            </Badge>
+          ) : null}
+        </HStack>
+        <Text color="fg.subtle" fontSize="2xs" truncate>
+          {hotkey.description ?? hotkey.id}
+        </Text>
+        {conflict ? (
+          <Text color="fg.error" fontSize="2xs">
+            {t('hotkeys.conflictsWith', { title: conflict.title })}
+          </Text>
+        ) : hasDuplicate ? (
+          <Text color="fg.error" fontSize="2xs">
+            {t('hotkeys.duplicateBinding')}
+          </Text>
+        ) : null}
+      </Stack>
+      <Stack align="end" gap="1.5" maxW="58%">
+        <HStack gap="1.5" justify="end" wrap="wrap">
+          {draftKeys.length > 0 ? (
+            draftKeys.map((key, index) => (
+              <HotkeyChipItem
+                key={`${index}:${key}`}
+                cancelChipEdit={cancelChipEdit}
+                deleteDraftKey={deleteDraftKey}
+                editingIndex={editingIndex}
+                hotkey={key}
+                index={index}
+                setEditingIndex={setEditingIndex}
+                updateDraftKey={updateDraftKey}
+              />
+            ))
+          ) : (
+            <Text color="fg.subtle" fontSize="2xs">
+              {t('hotkeys.disabled')}
+            </Text>
+          )}
+          <IconButton aria-label={t('hotkeys.addHotkey')} size="xs" variant="ghost" onClick={addDraftKey}>
+            <PlusIcon />
+          </IconButton>
+        </HStack>
+        <HStack gap="1">
+          {isEditing || isDirty ? (
+            <>
+              <IconButton aria-label={t('hotkeys.cancelEdit')} size="xs" variant="ghost" onClick={cancelEdit}>
+                <XIcon />
+              </IconButton>
+              <IconButton
+                aria-label={t('hotkeys.saveEdit')}
+                disabled={!canSave}
+                size="xs"
+                variant="ghost"
+                onClick={saveEdit}
+              >
+                <CheckIcon />
+              </IconButton>
+            </>
+          ) : null}
+          {effectiveKeys.length > 0 ? (
+            <Button size="xs" variant="ghost" onClick={disableHotkey}>
+              {t('hotkeys.disable')}
+            </Button>
+          ) : null}
+          {isCustomized ? (
+            <IconButton aria-label={t('hotkeys.resetHotkey')} size="xs" variant="ghost" onClick={onReset}>
+              <RotateCcwIcon />
+            </IconButton>
+          ) : null}
+        </HStack>
+      </Stack>
+    </Flex>
+  );
+};
+
+const HotkeyChip = ({
+  editing,
+  hotkey,
+  onCancel,
+  onDelete,
+  onEdit,
+  onRecord,
+}: {
+  editing: boolean;
+  hotkey: string;
+  onCancel: () => void;
+  onDelete: () => void;
+  onEdit: () => void;
+  onRecord: (hotkey: string) => void;
+}) => {
+  const { t } = useTranslation();
+  useEffect(() => {
+    if (!editing) {
+      return;
+    }
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+
+      if (event.key === 'Escape') {
+        onCancel();
+        return;
+      }
+
+      const nextHotkey = eventToHotkeyString(event);
+
+      if (nextHotkey) {
+        onRecord(nextHotkey);
+        onCancel();
+      }
+    };
+    const blockKeyUp = (event: KeyboardEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+
+    window.addEventListener('keydown', onKeyDown, true);
+    window.addEventListener('keyup', blockKeyUp, true);
+
+    return () => {
+      window.removeEventListener('keydown', onKeyDown, true);
+      window.removeEventListener('keyup', blockKeyUp, true);
+    };
+  }, [editing, onCancel, onRecord]);
+
+  if (editing) {
+    return (
+      <HStack borderColor="accent.solid" borderWidth="1px" gap="1" px="2" py="1" rounded="md">
+        <Text color="accent.solid" fontSize="2xs" fontStyle="italic">
+          {t('hotkeys.pressKeys')}
+        </Text>
+        <IconButton
+          aria-label={t('hotkeys.deleteHotkey')}
+          colorPalette="red"
+          size="2xs"
+          variant="ghost"
+          onClick={onDelete}
+        >
+          <Trash2Icon />
+        </IconButton>
+      </HStack>
+    );
+  }
+
+  return (
+    <Button type="button" onClick={onEdit} variant="outline" size="xs">
+      {formatHotkeyForPlatform(hotkey).map((part, index, parts) => (
+        <Fragment key={`${part}:${index}`}>
+          <Kbd size="sm" textTransform="lowercase">
+            {part}
+          </Kbd>
+          {index < parts.length - 1 ? (
+            <Text color="fg.subtle" fontSize="2xs">
+              +
+            </Text>
+          ) : null}
+        </Fragment>
+      ))}
+    </Button>
+  );
+};
+
+const HotkeyChipItem = ({
+  cancelChipEdit,
+  deleteDraftKey,
+  editingIndex,
+  hotkey,
+  index,
+  setEditingIndex,
+  updateDraftKey,
+}: {
+  cancelChipEdit: () => void;
+  deleteDraftKey: (index: number) => void;
+  editingIndex: number | null;
+  hotkey: string;
+  index: number;
+  setEditingIndex: (index: number) => void;
+  updateDraftKey: (index: number, key: string) => void;
+}) => {
+  const handleDelete = useCallback(() => deleteDraftKey(index), [deleteDraftKey, index]);
+  const handleEdit = useCallback(() => setEditingIndex(index), [index, setEditingIndex]);
+  const handleRecord = useCallback((nextKey: string) => updateDraftKey(index, nextKey), [index, updateDraftKey]);
+
+  return (
+    <HotkeyChip
+      editing={editingIndex === index}
+      hotkey={hotkey}
+      onCancel={cancelChipEdit}
+      onDelete={handleDelete}
+      onEdit={handleEdit}
+      onRecord={handleRecord}
+    />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/settings/SettingsDialog.tsx b/invokeai/frontend/webv2/src/workbench/settings/SettingsDialog.tsx
new file mode 100644
index 00000000000..f3bcebd1ae1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/settings/SettingsDialog.tsx
@@ -0,0 +1,875 @@
+import type {
+  DeveloperLogLevel,
+  DeveloperLogNamespace,
+  ProjectSettings,
+  Project,
+  SettingsSectionId,
+  WorkbenchLanguage,
+  WorkbenchPreferences,
+  WorkbenchThemeId,
+} from '@workbench/types';
+
+import {
+  Box,
+  chakra,
+  Checkbox,
+  Dialog,
+  Flex,
+  HStack,
+  Icon,
+  NativeSelect,
+  Portal,
+  SimpleGrid,
+  Stack,
+  Switch,
+  Text,
+  Field,
+  useSlotRecipe,
+} from '@chakra-ui/react';
+import { themeCardRecipe } from '@theme/recipes';
+import { previewSwatches, THEMES, type ThemeDefinition } from '@theme/system';
+import { Button, CloseButton, IconButton, ConfirmDialog, Tabs, Tooltip } from '@workbench/components/ui';
+import { registerHotkeyModalLayer } from '@workbench/hotkeys';
+import { WORKBENCH_LANGUAGE_OPTIONS } from '@workbench/i18n';
+import { syncedWorkbenchPersistence } from '@workbench/projects/syncedPersistence';
+import {
+  shallowEqual,
+  useOptionalWorkbenchDispatch,
+  useOptionalWorkbenchSelector,
+  useOptionalWorkbenchStore,
+} from '@workbench/WorkbenchContext';
+import {
+  CheckIcon,
+  Code2Icon,
+  DatabaseIcon,
+  FolderIcon,
+  KeyboardIcon,
+  ListOrderedIcon,
+  PaletteIcon,
+  RotateCcwIcon,
+  SettingsIcon,
+  SlidersHorizontalIcon,
+  Trash2Icon,
+  WorkflowIcon,
+  type LucideIcon,
+} from 'lucide-react';
+import { useCallback, useEffect, useId, useMemo, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { HotkeysSettingsSection } from './HotkeysSettingsSection';
+import {
+  closeWorkbenchSettings,
+  openWorkbenchSettings,
+  setWorkbenchSettingsSection,
+  settingsDialogStore,
+} from './settingsDialogStore';
+import {
+  clearWorkbenchSettings,
+  DEVELOPER_LOG_LEVELS,
+  DEVELOPER_LOG_NAMESPACES,
+  patchWorkbenchPreferences,
+  useWorkbenchPreferences,
+  useWorkbenchSettings,
+} from './store';
+
+interface SettingsTabDefinition {
+  value: SettingsSectionId;
+  label: string;
+  icon: LucideIcon;
+  condition?: boolean;
+  children: ReactNode;
+}
+
+const updatePreferences = (patch: Partial<WorkbenchPreferences>): void => {
+  void patchWorkbenchPreferences(patch);
+};
+
+const SETTINGS_TAB_LIST_WIDTH = { base: '40', md: '52' };
+const SETTINGS_CONTENT_PADDING = { base: '4', md: '5' };
+const THEME_GRID_COLUMNS = { base: 2, md: 3 };
+const DEVELOPER_GRID_COLUMNS = { base: 1, md: 2 };
+const DANGER_BUTTON_HOVER_STYLES = { bg: 'fg.error', color: 'bg.subtle' };
+const SWITCH_CHECKED_STYLES = { bg: 'accent.solid' };
+const FIELD_ALIGN_ITEMS = { base: 'stretch', md: 'center' };
+const FIELD_FLEX_DIRECTION = { base: 'column', md: 'row' };
+const SELECT_MAX_WIDTH = { base: 'full', md: '56' };
+
+/**
+ * The top bar's settings entry point. It also hosts the dialog itself, driven
+ * by `settingsDialogStore` so any surface can deep-link into a section via
+ * `openWorkbenchSettings('workflow')`.
+ */
+export const SettingsButton = () => {
+  const isOpen = settingsDialogStore.useSelector((snapshot) => snapshot.isOpen);
+  const handleOpen = useCallback(() => openWorkbenchSettings(), []);
+
+  return (
+    <>
+      <Tooltip content="Settings">
+        <IconButton aria-label="Settings" size="sm" variant="ghost" onClick={handleOpen}>
+          <SettingsIcon />
+        </IconButton>
+      </Tooltip>
+      <SettingsDialog isOpen={isOpen} onClose={closeWorkbenchSettings} />
+    </>
+  );
+};
+
+export const SettingsDialog = ({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) => {
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    return registerHotkeyModalLayer('settings');
+  }, [isOpen]);
+
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  return (
+    <Dialog.Root
+      closeOnInteractOutside={false}
+      lazyMount
+      open={isOpen}
+      placement="center"
+      scrollBehavior="inside"
+      size="xl"
+      unmountOnExit
+      onOpenChange={handleOpenChange}
+    >
+      <SettingsDialogContent onClose={onClose} />
+    </Dialog.Root>
+  );
+};
+
+const SettingsDialogContent = ({ onClose }: { onClose: () => void }) => {
+  const { t } = useTranslation();
+  const { error, scope, status } = useWorkbenchSettings();
+  const handlePositionerClick = useCallback(
+    (event: { target: EventTarget; currentTarget: EventTarget }) => {
+      if (event.target === event.currentTarget) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  return (
+    <Portal>
+      <Dialog.Backdrop pointerEvents="auto" />
+      <Dialog.Positioner pointerEvents="auto" onClick={handlePositionerClick}>
+        <Dialog.Content h="min(46rem, calc(100dvh - 4rem))" maxW="4xl">
+          <Dialog.Header borderBottomWidth="1px" borderColor="border.subtle">
+            <Flex alignItems="start" gap="2">
+              <Icon as={SettingsIcon} boxSize="5" />
+              <Stack gap="1">
+                <Dialog.Title fontSize="md" fontWeight="700" mt="0.5" lineHeight={1}>
+                  {t('settings.title')}
+                </Dialog.Title>
+                <Text color="fg.subtle" fontSize="xs">
+                  {scope === 'user' ? t('settings.descriptionUser') : t('settings.descriptionGlobal')}
+                </Text>
+                {status === 'error' && error ? (
+                  <Text color="fg.error" fontSize="2xs">
+                    {error}
+                  </Text>
+                ) : null}
+              </Stack>
+            </Flex>
+          </Dialog.Header>
+          <Dialog.Body minH="0" p="0">
+            <SettingsTabs />
+          </Dialog.Body>
+          <Dialog.CloseTrigger asChild>
+            <CloseButton size="sm" />
+          </Dialog.CloseTrigger>
+        </Dialog.Content>
+      </Dialog.Positioner>
+    </Portal>
+  );
+};
+
+const SettingsTabs = () => {
+  const { t } = useTranslation();
+  const hasWorkbench = useOptionalWorkbenchStore() !== null;
+  const settingsTabs: SettingsTabDefinition[] = useMemo(
+    () => [
+      {
+        children: <AppearanceSection />,
+        icon: PaletteIcon,
+        label: t('settings.tabs.appearance'),
+        value: 'appearance',
+      },
+      {
+        children: <BehaviorSection />,
+        icon: SlidersHorizontalIcon,
+        label: t('settings.tabs.behavior'),
+        value: 'behavior',
+      },
+      {
+        children: <HotkeysSettingsSection />,
+        icon: KeyboardIcon,
+        label: t('settings.tabs.hotkeys'),
+        value: 'hotkeys',
+      },
+      {
+        children: <ProjectSection />,
+        condition: hasWorkbench,
+        icon: FolderIcon,
+        label: t('settings.tabs.project'),
+        value: 'project',
+      },
+      {
+        children: <QueueSection />,
+        icon: ListOrderedIcon,
+        label: t('settings.tabs.queue'),
+        value: 'queue',
+      },
+      {
+        children: <WorkflowSection />,
+        icon: WorkflowIcon,
+        label: t('settings.tabs.workflow'),
+        value: 'workflow',
+      },
+      {
+        children: <DeveloperSection />,
+        icon: Code2Icon,
+        label: t('settings.tabs.developer'),
+        value: 'developer',
+      },
+      {
+        children: <WorkspaceSection />,
+        icon: DatabaseIcon,
+        label: t('settings.tabs.workspace'),
+        value: 'workspace',
+      },
+    ],
+    [hasWorkbench, t]
+  );
+  const tabs = settingsTabs.filter((tab) => tab.condition !== false);
+  const sectionId = settingsDialogStore.useSelector((snapshot) => snapshot.sectionId);
+  const activeSectionId = tabs.some((tab) => tab.value === sectionId) ? sectionId : 'appearance';
+  const handleValueChange = useCallback((event: { value: string }) => {
+    setWorkbenchSettingsSection(event.value as SettingsSectionId);
+  }, []);
+
+  return (
+    <Tabs.Root
+      display="flex"
+      h="full"
+      minH="0"
+      orientation="vertical"
+      value={activeSectionId}
+      variant="subtle"
+      onValueChange={handleValueChange}
+    >
+      <Tabs.List
+        alignItems="stretch"
+        bg="bg"
+        borderColor="border.subtle"
+        borderRightWidth="1px"
+        flexShrink={0}
+        p="2"
+        w={SETTINGS_TAB_LIST_WIDTH}
+      >
+        {tabs.map((tab) => (
+          <SettingsTabTrigger key={tab.value} icon={tab.icon} label={tab.label} value={tab.value} />
+        ))}
+      </Tabs.List>
+      <Box flex="1" minW="0" overflowY="auto" p={SETTINGS_CONTENT_PADDING}>
+        {tabs.map((tab) => (
+          <Tabs.Content key={tab.value} m="0" p="0" value={tab.value}>
+            {tab.children}
+          </Tabs.Content>
+        ))}
+      </Box>
+    </Tabs.Root>
+  );
+};
+
+const SettingsTabTrigger = ({ icon, label, value }: { icon: LucideIcon; label: string; value: string }) => (
+  <Tabs.Trigger justifyContent="flex-start" textAlign="start" value={value} w="full">
+    <Icon as={icon} boxSize="3.5" flexShrink={0} />
+    <Text truncate>{label}</Text>
+  </Tabs.Trigger>
+);
+
+const SettingsSection = ({
+  children,
+  description,
+  title,
+}: {
+  children: ReactNode;
+  description: string;
+  title: string;
+}) => (
+  <Stack gap="3">
+    <Stack gap="0.5">
+      <Text color="fg" fontSize="sm" fontWeight="600">
+        {title}
+      </Text>
+      <Text color="fg.subtle" fontSize="xs">
+        {description}
+      </Text>
+    </Stack>
+    {children}
+  </Stack>
+);
+
+const AppearanceSection = () => {
+  const { t } = useTranslation();
+  const { language, reduceMotion, showFocusRegionHighlight, themeId } = useWorkbenchPreferences();
+
+  const selectTheme = useCallback((nextThemeId: WorkbenchThemeId) => {
+    updatePreferences({ themeId: nextThemeId });
+  }, []);
+  const updateLanguage = useCallback((value: string) => {
+    updatePreferences({ language: value as WorkbenchLanguage });
+  }, []);
+  const updateReduceMotion = useCallback((checked: boolean) => {
+    updatePreferences({ reduceMotion: checked });
+  }, []);
+  const updateShowFocusRegionHighlight = useCallback((checked: boolean) => {
+    updatePreferences({ showFocusRegionHighlight: checked });
+  }, []);
+
+  return (
+    <SettingsSection description="Choose a theme, language, and motion behavior." title="Appearance">
+      <SimpleGrid columns={THEME_GRID_COLUMNS} gap="3">
+        {THEMES.map((theme) => (
+          <ThemeCard key={theme.id} selected={theme.id === themeId} theme={theme} onSelect={selectTheme} />
+        ))}
+      </SimpleGrid>
+      <SettingSelect
+        description={t('settings.languageDescription')}
+        label={t('settings.language')}
+        value={language}
+        onChange={updateLanguage}
+      >
+        {WORKBENCH_LANGUAGE_OPTIONS.map((option) => (
+          <option key={option.value} value={option.value}>
+            {option.label}
+          </option>
+        ))}
+      </SettingSelect>
+      <SettingToggle
+        checked={reduceMotion}
+        description="Disable transitions and animations across the workbench."
+        label="Reduce motion"
+        onChange={updateReduceMotion}
+      />
+      <SettingToggle
+        checked={showFocusRegionHighlight}
+        label={t('settings.enableHighlightFocusedRegions')}
+        onChange={updateShowFocusRegionHighlight}
+      />
+    </SettingsSection>
+  );
+};
+
+const ThemeCard = ({
+  onSelect,
+  selected,
+  theme,
+}: {
+  onSelect: (themeId: WorkbenchThemeId) => void;
+  selected: boolean;
+  theme: ThemeDefinition;
+}) => {
+  const recipe = useSlotRecipe({ recipe: themeCardRecipe });
+  const styles = recipe({ selected });
+  const [surface, control, brandColor, accentColor] = previewSwatches(theme);
+  const handleSelect = useCallback(() => onSelect(theme.id), [onSelect, theme.id]);
+
+  return (
+    <chakra.button type="button" aria-pressed={selected} css={styles.root} onClick={handleSelect}>
+      <Flex css={styles.preview}>
+        <Box css={styles.swatch} bg={surface} />
+        <Box css={styles.swatch} bg={control} />
+        <Box css={styles.swatch} bg={brandColor} />
+        <Box css={styles.swatch} bg={accentColor} />
+      </Flex>
+      <Box css={styles.body}>
+        <HStack justify="space-between" w="full">
+          <Text css={styles.name}>{theme.label}</Text>
+          <Box css={styles.indicator}>
+            <Icon as={CheckIcon} boxSize="3" />
+          </Box>
+        </HStack>
+        <Text css={styles.description}>{theme.description}</Text>
+      </Box>
+    </chakra.button>
+  );
+};
+
+const BehaviorSection = () => {
+  const { confirmImageDeletion, enableInformationalPopovers, enableModelDescriptions } = useWorkbenchPreferences();
+  const updateConfirmImageDeletion = useCallback((checked: boolean) => {
+    updatePreferences({ confirmImageDeletion: checked });
+  }, []);
+  const updateEnableInformationalPopovers = useCallback((checked: boolean) => {
+    updatePreferences({ enableInformationalPopovers: checked });
+  }, []);
+  const updateEnableModelDescriptions = useCallback((checked: boolean) => {
+    updatePreferences({ enableModelDescriptions: checked });
+  }, []);
+
+  return (
+    <SettingsSection description="Safety checks and user-assistance behavior." title="Behavior">
+      <SettingToggle
+        checked={confirmImageDeletion}
+        description="Ask for confirmation before permanently deleting images."
+        label="Confirm image deletion"
+        onChange={updateConfirmImageDeletion}
+      />
+      <SettingToggle
+        checked={enableInformationalPopovers}
+        comingSoon
+        description="Show educational popovers on controls that have extra guidance."
+        label="Enable informational popovers"
+        onChange={updateEnableInformationalPopovers}
+      />
+      <SettingToggle
+        checked={enableModelDescriptions}
+        description="Include model descriptions in model dropdowns where available."
+        label="Enable model descriptions in dropdowns"
+        onChange={updateEnableModelDescriptions}
+      />
+    </SettingsSection>
+  );
+};
+
+const ProjectSection = () => {
+  const activeProject = useOptionalWorkbenchSelector<Pick<Project, 'name' | 'settings'> | null>(
+    (snapshot) => ({ name: snapshot.activeProject.name, settings: snapshot.activeProject.settings }),
+    null,
+    shallowEqual
+  );
+  const dispatch = useOptionalWorkbenchDispatch();
+  const updateProjectSettings = useCallback(
+    (patch: Partial<ProjectSettings>) => {
+      dispatch?.({ settings: patch, type: 'setActiveProjectSettings' });
+    },
+    [dispatch]
+  );
+  const updateUseCpuNoise = useCallback(
+    (checked: boolean) => {
+      updateProjectSettings({ useCpuNoise: checked });
+    },
+    [updateProjectSettings]
+  );
+  const updateShowProgressDetails = useCallback(
+    (checked: boolean) => {
+      updateProjectSettings({ showProgressDetails: checked });
+    },
+    [updateProjectSettings]
+  );
+  const updateAntialiasProgressImages = useCallback(
+    (checked: boolean) => {
+      updateProjectSettings({ antialiasProgressImages: checked });
+    },
+    [updateProjectSettings]
+  );
+  const updateShowProgressImagesInViewer = useCallback(
+    (checked: boolean) => {
+      updateProjectSettings({ showProgressImagesInViewer: checked });
+    },
+    [updateProjectSettings]
+  );
+  const updatePreferNumericAttentionStyle = useCallback(
+    (checked: boolean) => {
+      updateProjectSettings({ preferNumericAttentionStyle: checked });
+    },
+    [updateProjectSettings]
+  );
+  const updateShowPromptSyntaxHighlighting = useCallback(
+    (checked: boolean) => {
+      updateProjectSettings({ showPromptSyntaxHighlighting: checked });
+    },
+    [updateProjectSettings]
+  );
+
+  if (!activeProject || !dispatch) {
+    return null;
+  }
+
+  const settings = activeProject.settings;
+
+  return (
+    <SettingsSection
+      description={`Settings saved with ${activeProject.name}. Future project-only settings can live here without becoming user preferences.`}
+      title="Project"
+    >
+      <SettingToggle
+        checked={settings.useCpuNoise}
+        description="Use CPU noise generation for deterministic legacy-compatible outputs."
+        label="Use CPU noise"
+        onChange={updateUseCpuNoise}
+      />
+      <SettingToggle
+        checked={settings.showProgressDetails}
+        comingSoon
+        description="Show detailed invocation progress when the backend reports it."
+        label="Show progress details"
+        onChange={updateShowProgressDetails}
+      />
+      <SettingToggle
+        checked={settings.antialiasProgressImages}
+        description="Smooth progress previews instead of rendering them pixelated."
+        label="Antialias progress images"
+        onChange={updateAntialiasProgressImages}
+      />
+      <SettingToggle
+        checked={settings.showProgressImagesInViewer}
+        description="Show progress images in the viewer when an image is still generating."
+        label="Show progress images in viewer"
+        onChange={updateShowProgressImagesInViewer}
+      />
+      <SettingToggle
+        checked={settings.preferNumericAttentionStyle}
+        description="Prefer numeric prompt attention syntax when controls insert attention weights."
+        label="Prefer numeric attention style"
+        onChange={updatePreferNumericAttentionStyle}
+      />
+      <SettingToggle
+        checked={settings.showPromptSyntaxHighlighting}
+        description="Experimental. Color prompt syntax in prompt fields without changing the prompt text or validation behavior."
+        label="Highlight prompt syntax (experimental)"
+        onChange={updateShowPromptSyntaxHighlighting}
+      />
+    </SettingsSection>
+  );
+};
+
+const WorkflowSection = () => {
+  const { workflowEdgeStyle, workflowShowMinimap, workflowSnapToGrid, workflowValidateConnections } =
+    useWorkbenchPreferences();
+  const updateWorkflowEdgeStyle = useCallback((value: string) => {
+    updatePreferences({ workflowEdgeStyle: value === 'square' ? 'square' : 'curved' });
+  }, []);
+  const updateWorkflowSnapToGrid = useCallback((checked: boolean) => {
+    updatePreferences({ workflowSnapToGrid: checked });
+  }, []);
+  const updateWorkflowShowMinimap = useCallback((checked: boolean) => {
+    updatePreferences({ workflowShowMinimap: checked });
+  }, []);
+  const updateWorkflowValidateConnections = useCallback((checked: boolean) => {
+    updatePreferences({ workflowValidateConnections: checked });
+  }, []);
+
+  return (
+    <SettingsSection description="Editing behavior for the project graph workflow editor." title="Workflow">
+      <SettingSelect
+        description="How connections between nodes are drawn in the editor."
+        label="Connection style"
+        value={workflowEdgeStyle}
+        onChange={updateWorkflowEdgeStyle}
+      >
+        <option value="curved">Curved</option>
+        <option value="square">Square</option>
+      </SettingSelect>
+      <SettingToggle
+        checked={workflowSnapToGrid}
+        description="Snap nodes to the grid while dragging. When off, hold Ctrl to snap temporarily."
+        label="Always snap to grid"
+        onChange={updateWorkflowSnapToGrid}
+      />
+      <SettingToggle
+        checked={workflowShowMinimap}
+        description="Show the minimap overview in the corner of the workflow editor."
+        label="Show minimap"
+        onChange={updateWorkflowShowMinimap}
+      />
+      <SettingToggle
+        checked={workflowValidateConnections}
+        description="Reject connections between incompatible field types while wiring nodes. Turn off to wire anything (runs may fail)."
+        label="Validate connections"
+        onChange={updateWorkflowValidateConnections}
+      />
+    </SettingsSection>
+  );
+};
+
+const QueueSection = () => {
+  const { queueJobsScope } = useWorkbenchPreferences();
+  const updateQueueJobsScope = useCallback((value: string) => {
+    updatePreferences({ queueJobsScope: value === 'active-project' ? 'active-project' : 'all' });
+  }, []);
+
+  return (
+    <SettingsSection description="Choose which jobs the Queue widget includes in its counts and lists." title="Queue">
+      <SettingSelect
+        description="Show jobs from only the active project, or all queue jobs visible to you."
+        label="Show jobs from"
+        value={queueJobsScope}
+        onChange={updateQueueJobsScope}
+      >
+        <option value="active-project">Active project</option>
+        <option value="all">All</option>
+      </SettingSelect>
+    </SettingsSection>
+  );
+};
+
+const DeveloperSection = () => {
+  const { developerLogEnabled, developerLogLevel, developerLogNamespaces, developerPerformanceTimingsEnabled } =
+    useWorkbenchPreferences();
+  const enabledNamespaces = useMemo(() => new Set(developerLogNamespaces), [developerLogNamespaces]);
+
+  const toggleNamespace = useCallback(
+    (namespace: DeveloperLogNamespace, checked: boolean) => {
+      const next = checked
+        ? [...developerLogNamespaces, namespace]
+        : developerLogNamespaces.filter((candidate) => candidate !== namespace);
+
+      updatePreferences({
+        developerLogNamespaces: DEVELOPER_LOG_NAMESPACES.filter((candidate) => next.includes(candidate)),
+      });
+    },
+    [developerLogNamespaces]
+  );
+  const updateDeveloperLogEnabled = useCallback((checked: boolean) => {
+    updatePreferences({ developerLogEnabled: checked });
+  }, []);
+  const updateDeveloperLogLevel = useCallback((value: string) => {
+    updatePreferences({ developerLogLevel: value as DeveloperLogLevel });
+  }, []);
+  const updateDeveloperPerformanceTimingsEnabled = useCallback((checked: boolean) => {
+    updatePreferences({ developerPerformanceTimingsEnabled: checked });
+  }, []);
+
+  return (
+    <SettingsSection
+      description="Current-user diagnostics settings. Entries are still grouped by project and kept in memory only."
+      title="Developer"
+    >
+      <SettingToggle
+        checked={developerLogEnabled}
+        description="Record selected diagnostic log events in the Diagnostics widget."
+        label="Record diagnostic logs"
+        onChange={updateDeveloperLogEnabled}
+      />
+      <SettingSelect
+        description="Minimum log level recorded in the Diagnostics widget."
+        label="Log level"
+        value={developerLogLevel}
+        onChange={updateDeveloperLogLevel}
+      >
+        {DEVELOPER_LOG_LEVELS.map((value) => (
+          <option key={value} value={value}>
+            {formatSettingLabel(value)}
+          </option>
+        ))}
+      </SettingSelect>
+      <SettingToggle
+        checked={developerPerformanceTimingsEnabled}
+        description="Record performance measurements such as workflow editor timing and project serialization costs."
+        label="Collect performance timings"
+        onChange={updateDeveloperPerformanceTimingsEnabled}
+      />
+      <Stack gap="2">
+        <Text color="fg" fontSize="sm" fontWeight="500">
+          Log namespaces
+        </Text>
+        <SimpleGrid columns={DEVELOPER_GRID_COLUMNS} gap="2">
+          {DEVELOPER_LOG_NAMESPACES.map((namespace) => (
+            <DeveloperNamespaceCheckbox
+              key={namespace}
+              checked={enabledNamespaces.has(namespace)}
+              namespace={namespace}
+              toggleNamespace={toggleNamespace}
+            />
+          ))}
+        </SimpleGrid>
+      </Stack>
+    </SettingsSection>
+  );
+};
+
+const DeveloperNamespaceCheckbox = ({
+  checked,
+  namespace,
+  toggleNamespace,
+}: {
+  checked: boolean;
+  namespace: DeveloperLogNamespace;
+  toggleNamespace: (namespace: DeveloperLogNamespace, checked: boolean) => void;
+}) => {
+  const handleCheckedChange = useCallback(
+    (event: { checked: boolean | 'indeterminate' }) => toggleNamespace(namespace, event.checked === true),
+    [namespace, toggleNamespace]
+  );
+
+  return (
+    <Checkbox.Root checked={checked} size="sm" onCheckedChange={handleCheckedChange}>
+      <Checkbox.HiddenInput />
+      <Checkbox.Control />
+      <Checkbox.Label color="fg.muted" fontSize="xs">
+        {formatSettingLabel(namespace)}
+      </Checkbox.Label>
+    </Checkbox.Root>
+  );
+};
+
+const WorkspaceSection = () => {
+  const dispatch = useOptionalWorkbenchDispatch();
+  const { scope } = useWorkbenchSettings();
+  const [isClearConfirmOpen, setIsClearConfirmOpen] = useState(false);
+
+  const clearSavedData = useCallback(async () => {
+    await Promise.all([syncedWorkbenchPersistence.clearWorkbench(), clearWorkbenchSettings()]);
+    window.location.reload();
+  }, []);
+  const resetLayout = useCallback(() => dispatch?.({ type: 'resetActiveLayout' }), [dispatch]);
+  const openClearConfirm = useCallback(() => setIsClearConfirmOpen(true), []);
+  const closeClearConfirm = useCallback(() => setIsClearConfirmOpen(false), []);
+
+  return (
+    <SettingsSection
+      description="Reset the layout, or permanently delete saved projects and settings."
+      title="Workspace"
+    >
+      <HStack gap="2" wrap="wrap">
+        {dispatch ? (
+          <Button size="sm" variant="outline" onClick={resetLayout}>
+            <RotateCcwIcon />
+            Reset layout
+          </Button>
+        ) : null}
+        <Button
+          borderColor="border.emphasized"
+          color="fg.error"
+          size="sm"
+          variant="outline"
+          _hover={DANGER_BUTTON_HOVER_STYLES}
+          onClick={openClearConfirm}
+        >
+          <Trash2Icon />
+          Clear saved data…
+        </Button>
+      </HStack>
+      <ConfirmDialog
+        body={
+          scope === 'user'
+            ? 'This permanently deletes all projects and settings for your account on this server. It cannot be undone.'
+            : 'This permanently deletes all projects and settings for this install. It cannot be undone.'
+        }
+        confirmLabel="Delete everything"
+        isOpen={isClearConfirmOpen}
+        title="Clear saved data?"
+        onClose={closeClearConfirm}
+        onConfirm={clearSavedData}
+      />
+    </SettingsSection>
+  );
+};
+
+const SettingToggle = ({
+  checked,
+  comingSoon,
+  description,
+  label,
+  onChange,
+}: {
+  checked: boolean;
+  comingSoon?: boolean;
+  description?: string;
+  label: string;
+  onChange: (checked: boolean) => void;
+}) => {
+  const descriptionId = useId();
+  const handleCheckedChange = useCallback(
+    (event: { checked: boolean | 'indeterminate' }) => onChange(event.checked === true),
+    [onChange]
+  );
+
+  return (
+    <Switch.Root
+      alignItems="center"
+      checked={checked}
+      disabled={comingSoon}
+      display="flex"
+      gap="4"
+      justifyContent="space-between"
+      w="full"
+      onCheckedChange={handleCheckedChange}
+    >
+      <Stack gap="0.5">
+        <Switch.Label color="fg" fontSize="sm" fontWeight="500" m="0">
+          {label}
+        </Switch.Label>
+        {description && (
+          <Text color="fg.subtle" fontSize="xs" id={descriptionId}>
+            {description}
+          </Text>
+        )}
+      </Stack>
+      <Switch.HiddenInput aria-describedby={descriptionId} />
+      <Switch.Control flexShrink={0} _checked={SWITCH_CHECKED_STYLES}>
+        <Switch.Thumb />
+      </Switch.Control>
+    </Switch.Root>
+  );
+};
+
+const SettingSelect = ({
+  children,
+  comingSoon,
+  description,
+  label,
+  onChange,
+  value,
+}: {
+  children: ReactNode;
+  comingSoon?: boolean;
+  description?: string;
+  label: string;
+  onChange: (value: string) => void;
+  value: string;
+}) => {
+  const handleChange = useCallback(
+    (event: { currentTarget: { value: string } }) => onChange(event.currentTarget.value),
+    [onChange]
+  );
+
+  return (
+    <Field.Root
+      alignItems={FIELD_ALIGN_ITEMS}
+      disabled={comingSoon}
+      display="flex"
+      flexDirection={FIELD_FLEX_DIRECTION}
+      gap="3"
+      justifyContent="space-between"
+    >
+      <Stack gap="0.5">
+        <Field.Label color="fg" fontSize="sm" fontWeight="500" m="0">
+          {label}
+        </Field.Label>
+        {description && (
+          <Field.HelperText color="fg.subtle" fontSize="xs" m="0">
+            {description}
+          </Field.HelperText>
+        )}
+      </Stack>
+      <NativeSelect.Root flexShrink={0} maxW={SELECT_MAX_WIDTH} size="sm" w="full">
+        <NativeSelect.Field value={value} onChange={handleChange}>
+          {children}
+        </NativeSelect.Field>
+        <NativeSelect.Indicator />
+      </NativeSelect.Root>
+    </Field.Root>
+  );
+};
+
+const formatSettingLabel = (value: string): string =>
+  value
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
diff --git a/invokeai/frontend/webv2/src/workbench/settings/index.ts b/invokeai/frontend/webv2/src/workbench/settings/index.ts
new file mode 100644
index 00000000000..b82f03b9d7c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/settings/index.ts
@@ -0,0 +1,3 @@
+export * from './SettingsDialog';
+export * from './settingsDialogStore';
+export * from './store';
diff --git a/invokeai/frontend/webv2/src/workbench/settings/settingsDialogStore.ts b/invokeai/frontend/webv2/src/workbench/settings/settingsDialogStore.ts
new file mode 100644
index 00000000000..5806ffa4913
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/settings/settingsDialogStore.ts
@@ -0,0 +1,33 @@
+import type { SettingsSectionId } from '@workbench/types';
+
+import { createExternalStore } from '@workbench/externalStore';
+
+/**
+ * Open/close state for the workbench settings dialog, addressable from
+ * anywhere: widget frames, menus, and commands call `openWorkbenchSettings`
+ * with the section they want. The dialog itself is hosted by the top bar's
+ * `SettingsButton`, which subscribes to this store.
+ */
+
+interface SettingsDialogSnapshot {
+  isOpen: boolean;
+  sectionId: SettingsSectionId;
+}
+
+export const settingsDialogStore = createExternalStore<SettingsDialogSnapshot>({
+  isOpen: false,
+  sectionId: 'appearance',
+});
+
+/** Open the workbench settings dialog, optionally at a specific section. */
+export const openWorkbenchSettings = (sectionId: SettingsSectionId = 'appearance'): void => {
+  settingsDialogStore.setSnapshot({ isOpen: true, sectionId });
+};
+
+export const closeWorkbenchSettings = (): void => {
+  settingsDialogStore.patchSnapshot({ isOpen: false });
+};
+
+export const setWorkbenchSettingsSection = (sectionId: SettingsSectionId): void => {
+  settingsDialogStore.patchSnapshot({ sectionId });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/settings/store.test.ts b/invokeai/frontend/webv2/src/workbench/settings/store.test.ts
new file mode 100644
index 00000000000..6d8b4beb100
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/settings/store.test.ts
@@ -0,0 +1,273 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type * as storeModule from './store';
+
+/**
+ * The settings store's load/patch contract: backend-first with legacy
+ * migration, resolved once per account scope, and offline edits replay
+ * instead of being reverted by a stale server copy.
+ */
+
+const api = vi.hoisted(() => {
+  const clientState = new Map<string, string>();
+
+  return {
+    __clientState: clientState,
+    deleteClientStateValue: vi.fn((key: string) => {
+      clientState.delete(key);
+
+      return Promise.resolve();
+    }),
+    getClientStateValue: vi.fn((key: string) => Promise.resolve(clientState.get(key) ?? null)),
+    setClientStateValue: vi.fn((key: string, value: string) => {
+      clientState.set(key, value);
+
+      return Promise.resolve();
+    }),
+  };
+});
+
+const auth = vi.hoisted(() => ({ scope: '' }));
+
+vi.mock('../projects/api', () => api);
+vi.mock('../auth/session', () => ({ getUserStorageScope: () => auth.scope }));
+
+const storage = new Map<string, string>();
+
+vi.stubGlobal('window', {
+  localStorage: {
+    getItem: (key: string): string | null => storage.get(key) ?? null,
+    removeItem: (key: string): void => {
+      storage.delete(key);
+    },
+    setItem: (key: string, value: string): void => {
+      storage.set(key, value);
+    },
+  },
+});
+
+const SETTINGS_KEY = 'webv2:workbench-settings';
+const SESSION_KEY = 'webv2:workbench-account';
+
+let store: typeof storeModule;
+
+const seedBackendPreferences = (preferences: Record<string, unknown>): void => {
+  api.__clientState.set(SETTINGS_KEY, JSON.stringify(preferences));
+};
+
+const readBackendPreferences = (): Record<string, unknown> =>
+  JSON.parse(api.__clientState.get(SETTINGS_KEY) ?? 'null') as Record<string, unknown>;
+
+beforeEach(async () => {
+  vi.resetModules();
+  api.__clientState.clear();
+  api.deleteClientStateValue.mockClear();
+  api.getClientStateValue.mockClear();
+  api.setClientStateValue.mockClear();
+  auth.scope = '';
+  storage.clear();
+
+  store = await import('./store');
+});
+
+describe('loadWorkbenchSettings', () => {
+  it('adopts backend preferences without writing them back', async () => {
+    seedBackendPreferences({ themeId: 'forest' });
+
+    const preferences = await store.loadWorkbenchSettings();
+
+    expect(preferences.themeId).toBe('forest');
+    expect(api.setClientStateValue).not.toHaveBeenCalled();
+    expect(store.useWorkbenchSettings).toBeDefined();
+    expect(store.getWorkbenchPreferences().themeId).toBe('forest');
+  });
+
+  it('migrates legacy session-blob preferences once when the settings key is missing', async () => {
+    api.__clientState.set(
+      SESSION_KEY,
+      JSON.stringify({
+        account: { activeLayoutPresetId: 'gallery', preferences: { themeId: 'mono' } },
+        activeProjectId: 'p1',
+      })
+    );
+
+    const preferences = await store.loadWorkbenchSettings();
+
+    expect(preferences.themeId).toBe('mono');
+    expect(readBackendPreferences().themeId).toBe('mono');
+    expect(api.setClientStateValue).toHaveBeenCalledTimes(1);
+  });
+
+  it('resolves once per scope and reloads when the scope changes', async () => {
+    seedBackendPreferences({ themeId: 'forest' });
+    await store.loadWorkbenchSettings();
+    await store.loadWorkbenchSettings();
+
+    expect(api.getClientStateValue.mock.calls.filter(([key]) => key === SETTINGS_KEY)).toHaveLength(1);
+
+    auth.scope = ':user:u2';
+    seedBackendPreferences({ themeId: 'light' });
+
+    const preferences = await store.loadWorkbenchSettings();
+
+    expect(preferences.themeId).toBe('light');
+  });
+
+  it('heals invalid stored values to defaults', async () => {
+    seedBackendPreferences({ developerLogLevel: 'shout', themeId: 'dark' });
+
+    const preferences = await store.loadWorkbenchSettings();
+
+    expect(preferences.themeId).toBe('classic');
+    expect(preferences.developerLogLevel).toBe('warn');
+  });
+
+  it('serves the local copy when the backend is unreachable and retries next time', async () => {
+    seedBackendPreferences({ themeId: 'forest' });
+    await store.loadWorkbenchSettings();
+
+    vi.resetModules();
+    store = await import('./store');
+    api.getClientStateValue.mockRejectedValueOnce(new Error('offline'));
+
+    const offline = await store.loadWorkbenchSettings();
+
+    expect(offline.themeId).toBe('forest');
+    expect(store.useWorkbenchSettings).toBeDefined();
+
+    const recovered = await store.loadWorkbenchSettings();
+
+    expect(recovered.themeId).toBe('forest');
+  });
+
+  it('reports an error with defaults when nothing is available anywhere', async () => {
+    api.getClientStateValue.mockRejectedValueOnce(new Error('offline'));
+
+    const preferences = await store.loadWorkbenchSettings();
+
+    expect(preferences.themeId).toBe('classic');
+  });
+});
+
+describe('patchWorkbenchPreferences', () => {
+  it('persists to the backend and localStorage', async () => {
+    seedBackendPreferences({ themeId: 'forest' });
+    await store.loadWorkbenchSettings();
+
+    await store.patchWorkbenchPreferences({ reduceMotion: true });
+
+    expect(readBackendPreferences().reduceMotion).toBe(true);
+    expect(readBackendPreferences().themeId).toBe('forest');
+    expect(store.getWorkbenchPreferences().reduceMotion).toBe(true);
+    expect(store.getWorkbenchReduceMotion()).toBe(true);
+  });
+
+  it('persists account-bound custom hotkeys', async () => {
+    seedBackendPreferences({ themeId: 'forest' });
+    await store.loadWorkbenchSettings();
+
+    await store.patchWorkbenchPreferences({ customHotkeys: { 'app.invoke': ['mod+shift+enter'] } });
+
+    expect(readBackendPreferences().customHotkeys).toEqual({ 'app.invoke': ['mod+shift+enter'] });
+    expect(store.getWorkbenchPreferences().customHotkeys).toEqual({ 'app.invoke': ['mod+shift+enter'] });
+  });
+
+  it('persists empty custom hotkeys as disabled bindings', async () => {
+    await store.loadWorkbenchSettings();
+
+    await store.patchWorkbenchPreferences({ customHotkeys: { 'app.invoke': [] } });
+
+    expect(readBackendPreferences().customHotkeys).toEqual({ 'app.invoke': [] });
+    expect(store.getWorkbenchPreferences().customHotkeys).toEqual({ 'app.invoke': [] });
+  });
+
+  it('replays an offline edit on the next load instead of reverting to the server copy', async () => {
+    seedBackendPreferences({ themeId: 'forest' });
+    await store.loadWorkbenchSettings();
+
+    api.setClientStateValue.mockRejectedValueOnce(new Error('offline'));
+    await store.patchWorkbenchPreferences({ themeId: 'light' });
+
+    expect(readBackendPreferences().themeId).toBe('forest');
+
+    vi.resetModules();
+    store = await import('./store');
+
+    const preferences = await store.loadWorkbenchSettings();
+
+    expect(preferences.themeId).toBe('light');
+    expect(readBackendPreferences().themeId).toBe('light');
+  });
+});
+
+describe('clearWorkbenchSettings', () => {
+  it('resets to defaults locally and deletes the backend key', async () => {
+    seedBackendPreferences({ themeId: 'forest' });
+    await store.loadWorkbenchSettings();
+
+    await store.clearWorkbenchSettings();
+
+    expect(store.getWorkbenchPreferences().themeId).toBe('classic');
+    expect(api.__clientState.has(SETTINGS_KEY)).toBe(false);
+  });
+});
+
+describe('normalizeProjectSettings', () => {
+  it('defaults prompt syntax highlighting off for older project payloads', () => {
+    expect(store.normalizeProjectSettings({}).showPromptSyntaxHighlighting).toBe(false);
+    expect(store.normalizeProjectSettings({ showPromptSyntaxHighlighting: true }).showPromptSyntaxHighlighting).toBe(
+      true
+    );
+    expect(store.normalizeProjectSettings({ showPromptSyntaxHighlighting: false }).showPromptSyntaxHighlighting).toBe(
+      false
+    );
+  });
+});
+
+describe('normalizeWorkbenchPreferences diagnostics', () => {
+  it('heals invalid diagnostics preferences to defaults', () => {
+    expect(
+      store.normalizeWorkbenchPreferences({
+        developerLogEnabled: true,
+        developerLogLevel: 'shout' as never,
+        developerLogNamespaces: ['system', 'missing'] as never,
+        developerPerformanceTimingsEnabled: true,
+      })
+    ).toMatchObject({
+      developerLogEnabled: true,
+      developerLogLevel: 'warn',
+      developerLogNamespaces: ['system'],
+      developerPerformanceTimingsEnabled: true,
+    });
+  });
+});
+
+describe('normalizeWorkbenchPreferences queue scope', () => {
+  it('defaults queue jobs to all jobs for older preferences', () => {
+    expect(store.normalizeWorkbenchPreferences({}).queueJobsScope).toBe('all');
+  });
+
+  it('accepts only supported queue job scopes', () => {
+    expect(store.normalizeWorkbenchPreferences({ queueJobsScope: 'active-project' }).queueJobsScope).toBe(
+      'active-project'
+    );
+    expect(store.normalizeWorkbenchPreferences({ queueJobsScope: 'all' }).queueJobsScope).toBe('all');
+    expect(store.normalizeWorkbenchPreferences({ queueJobsScope: 'all-projects' }).queueJobsScope).toBe('all');
+    expect(store.normalizeWorkbenchPreferences({ queueJobsScope: 'current-project' }).queueJobsScope).toBe('all');
+  });
+});
+
+describe('normalizeWorkbenchPreferences language', () => {
+  it('accepts locale files that were migrated from the legacy web app', () => {
+    expect(store.normalizeWorkbenchPreferences({ language: 'uk' }).language).toBe('uk');
+    expect(store.normalizeWorkbenchPreferences({ language: 'en-GB' }).language).toBe('en-GB');
+  });
+
+  it('migrates legacy ua preferences to the uk locale file', () => {
+    expect(store.normalizeWorkbenchPreferences({ language: 'ua' as never }).language).toBe('uk');
+  });
+
+  it('heals unsupported languages to the default', () => {
+    expect(store.normalizeWorkbenchPreferences({ language: 'missing' as never }).language).toBe('en');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/settings/store.ts b/invokeai/frontend/webv2/src/workbench/settings/store.ts
new file mode 100644
index 00000000000..f96f4a9febc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/settings/store.ts
@@ -0,0 +1,437 @@
+import type { DeveloperLogLevel, DeveloperLogNamespace, ProjectSettings, WorkbenchPreferences } from '@workbench/types';
+
+import { DEFAULT_THEME_ID, isWorkbenchThemeId } from '@theme/themes';
+import { getUserStorageScope } from '@workbench/auth/session';
+import { createExternalStore } from '@workbench/externalStore';
+import { normalizeWorkbenchLanguage } from '@workbench/i18n/languages';
+import { deleteClientStateValue, getClientStateValue, setClientStateValue } from '@workbench/projects/api';
+import { fetchSessionBlob } from '@workbench/projects/session';
+
+export { WORKBENCH_LANGUAGES } from '@workbench/i18n/languages';
+
+const SETTINGS_BASE_STORAGE_KEY = 'invokeai:v7:webv2:settings';
+const LEGACY_WORKBENCH_BASE_STORAGE_KEY = 'invokeai:v7:webv2:workbench';
+const SETTINGS_CLIENT_STATE_KEY = 'webv2:workbench-settings';
+
+export const DEVELOPER_LOG_LEVELS: DeveloperLogLevel[] = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+
+export const DEVELOPER_LOG_NAMESPACES: DeveloperLogNamespace[] = [
+  'canvas',
+  'canvas-workflow-integration',
+  'config',
+  'dnd',
+  'events',
+  'gallery',
+  'generation',
+  'metadata',
+  'models',
+  'system',
+  'queue',
+  'workflows',
+];
+
+export const DEFAULT_PROJECT_SETTINGS: ProjectSettings = {
+  antialiasProgressImages: false,
+  preferNumericAttentionStyle: false,
+  showPromptSyntaxHighlighting: false,
+  showProgressDetails: false,
+  showProgressImagesInViewer: true,
+  useCpuNoise: true,
+};
+
+export const DEFAULT_PREFERENCES: WorkbenchPreferences = {
+  confirmImageDeletion: true,
+  customHotkeys: {},
+  developerLogEnabled: true,
+  developerLogLevel: 'warn',
+  developerLogNamespaces: ['system', 'queue', 'workflows'],
+  developerPerformanceTimingsEnabled: false,
+  enableInformationalPopovers: true,
+  enableModelDescriptions: true,
+  language: 'en',
+  queueJobsScope: 'all',
+  reduceMotion: false,
+  showFocusRegionHighlight: true,
+  themeId: DEFAULT_THEME_ID,
+  workflowEdgeStyle: 'curved',
+  workflowShowMinimap: true,
+  workflowSnapToGrid: false,
+  workflowValidateConnections: true,
+};
+
+interface WorkbenchSettingsSnapshot {
+  preferences: WorkbenchPreferences;
+  scope: 'global' | 'user';
+  status: 'idle' | 'loading' | 'ready' | 'error';
+  error?: string;
+}
+
+const store = createExternalStore<WorkbenchSettingsSnapshot>({
+  preferences: DEFAULT_PREFERENCES,
+  scope: 'global',
+  status: 'idle',
+});
+
+const isBrowser = (): boolean => typeof window !== 'undefined' && typeof window.localStorage !== 'undefined';
+
+const getSettingsStorageKey = (): string => `${SETTINGS_BASE_STORAGE_KEY}${getUserStorageScope()}`;
+
+const getLegacyWorkbenchStorageKey = (): string => `${LEGACY_WORKBENCH_BASE_STORAGE_KEY}${getUserStorageScope()}`;
+
+const getSettingsScope = (): WorkbenchSettingsSnapshot['scope'] => (getUserStorageScope() ? 'user' : 'global');
+
+const isDeveloperLogLevel = (value: unknown): value is DeveloperLogLevel =>
+  typeof value === 'string' && DEVELOPER_LOG_LEVELS.includes(value as DeveloperLogLevel);
+
+const normalizeDeveloperLogNamespaces = (values: unknown): DeveloperLogNamespace[] => {
+  if (!Array.isArray(values)) {
+    return [...DEFAULT_PREFERENCES.developerLogNamespaces];
+  }
+
+  const enabled = new Set(
+    values.filter(
+      (value): value is DeveloperLogNamespace =>
+        typeof value === 'string' && DEVELOPER_LOG_NAMESPACES.includes(value as DeveloperLogNamespace)
+    )
+  );
+
+  return DEVELOPER_LOG_NAMESPACES.filter((namespace) => enabled.has(namespace));
+};
+
+const normalizeCustomHotkeys = (values: unknown): Record<string, string[]> => {
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(values)
+      .filter(
+        (entry): entry is [string, string[]] =>
+          typeof entry[0] === 'string' &&
+          Array.isArray(entry[1]) &&
+          entry[1].every((hotkey) => typeof hotkey === 'string')
+      )
+      .map(([id, hotkeys]) => [id, hotkeys])
+  );
+};
+
+export const normalizeProjectSettings = (settings?: Partial<ProjectSettings>): ProjectSettings => ({
+  antialiasProgressImages:
+    typeof settings?.antialiasProgressImages === 'boolean'
+      ? settings.antialiasProgressImages
+      : DEFAULT_PROJECT_SETTINGS.antialiasProgressImages,
+  preferNumericAttentionStyle:
+    typeof settings?.preferNumericAttentionStyle === 'boolean'
+      ? settings.preferNumericAttentionStyle
+      : DEFAULT_PROJECT_SETTINGS.preferNumericAttentionStyle,
+  showPromptSyntaxHighlighting:
+    typeof settings?.showPromptSyntaxHighlighting === 'boolean'
+      ? settings.showPromptSyntaxHighlighting
+      : DEFAULT_PROJECT_SETTINGS.showPromptSyntaxHighlighting,
+  showProgressDetails:
+    typeof settings?.showProgressDetails === 'boolean'
+      ? settings.showProgressDetails
+      : DEFAULT_PROJECT_SETTINGS.showProgressDetails,
+  showProgressImagesInViewer:
+    typeof settings?.showProgressImagesInViewer === 'boolean'
+      ? settings.showProgressImagesInViewer
+      : DEFAULT_PROJECT_SETTINGS.showProgressImagesInViewer,
+  useCpuNoise: typeof settings?.useCpuNoise === 'boolean' ? settings.useCpuNoise : DEFAULT_PROJECT_SETTINGS.useCpuNoise,
+});
+
+type WorkbenchPreferencesInput = Omit<Partial<WorkbenchPreferences>, 'queueJobsScope' | 'workflowEdgeStyle'> & {
+  queueJobsScope?: unknown;
+  workflowEdgeStyle?: unknown;
+};
+
+export const normalizeWorkbenchPreferences = (preferences?: WorkbenchPreferencesInput): WorkbenchPreferences => ({
+  confirmImageDeletion:
+    typeof preferences?.confirmImageDeletion === 'boolean'
+      ? preferences.confirmImageDeletion
+      : DEFAULT_PREFERENCES.confirmImageDeletion,
+  customHotkeys: normalizeCustomHotkeys(preferences?.customHotkeys),
+  developerLogEnabled:
+    typeof preferences?.developerLogEnabled === 'boolean'
+      ? preferences.developerLogEnabled
+      : DEFAULT_PREFERENCES.developerLogEnabled,
+  developerLogLevel: isDeveloperLogLevel(preferences?.developerLogLevel)
+    ? preferences.developerLogLevel
+    : DEFAULT_PREFERENCES.developerLogLevel,
+  developerLogNamespaces: normalizeDeveloperLogNamespaces(preferences?.developerLogNamespaces),
+  developerPerformanceTimingsEnabled:
+    typeof preferences?.developerPerformanceTimingsEnabled === 'boolean'
+      ? preferences.developerPerformanceTimingsEnabled
+      : DEFAULT_PREFERENCES.developerPerformanceTimingsEnabled,
+  enableInformationalPopovers:
+    typeof preferences?.enableInformationalPopovers === 'boolean'
+      ? preferences.enableInformationalPopovers
+      : DEFAULT_PREFERENCES.enableInformationalPopovers,
+  enableModelDescriptions:
+    typeof preferences?.enableModelDescriptions === 'boolean'
+      ? preferences.enableModelDescriptions
+      : DEFAULT_PREFERENCES.enableModelDescriptions,
+  language: normalizeWorkbenchLanguage(preferences?.language) ?? DEFAULT_PREFERENCES.language,
+  queueJobsScope:
+    preferences?.queueJobsScope === 'all-projects'
+      ? 'all'
+      : preferences?.queueJobsScope === 'active-project' || preferences?.queueJobsScope === 'all'
+        ? preferences.queueJobsScope
+        : DEFAULT_PREFERENCES.queueJobsScope,
+  reduceMotion:
+    typeof preferences?.reduceMotion === 'boolean' ? preferences.reduceMotion : DEFAULT_PREFERENCES.reduceMotion,
+  showFocusRegionHighlight:
+    typeof preferences?.showFocusRegionHighlight === 'boolean'
+      ? preferences.showFocusRegionHighlight
+      : DEFAULT_PREFERENCES.showFocusRegionHighlight,
+  themeId: isWorkbenchThemeId(preferences?.themeId) ? preferences.themeId : DEFAULT_PREFERENCES.themeId,
+  workflowEdgeStyle:
+    preferences?.workflowEdgeStyle === 'square' || preferences?.workflowEdgeStyle === 'straight'
+      ? 'square'
+      : preferences?.workflowEdgeStyle === 'curved'
+        ? preferences.workflowEdgeStyle
+        : DEFAULT_PREFERENCES.workflowEdgeStyle,
+  workflowShowMinimap:
+    typeof preferences?.workflowShowMinimap === 'boolean'
+      ? preferences.workflowShowMinimap
+      : DEFAULT_PREFERENCES.workflowShowMinimap,
+  workflowSnapToGrid:
+    typeof preferences?.workflowSnapToGrid === 'boolean'
+      ? preferences.workflowSnapToGrid
+      : DEFAULT_PREFERENCES.workflowSnapToGrid,
+  workflowValidateConnections:
+    typeof preferences?.workflowValidateConnections === 'boolean'
+      ? preferences.workflowValidateConnections
+      : DEFAULT_PREFERENCES.workflowValidateConnections,
+});
+
+const parsePreferences = (raw: string | null): WorkbenchPreferences | null => {
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    return normalizeWorkbenchPreferences(JSON.parse(raw) as Partial<WorkbenchPreferences>);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The localStorage payload: preferences plus a dirty marker for edits that
+ * never reached the backend. A pending local copy outranks the server at the
+ * next load, so going offline cannot silently revert a change.
+ */
+interface StoredSettings {
+  preferences: WorkbenchPreferences;
+  pendingPush?: boolean;
+}
+
+const readLocalSettings = (): StoredSettings | null => {
+  if (!isBrowser()) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(window.localStorage.getItem(getSettingsStorageKey()) ?? 'null') as
+      | (Partial<StoredSettings> & Partial<WorkbenchPreferences>)
+      | null;
+
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    // Early builds stored the bare preferences object.
+    if (!parsed.preferences) {
+      return { preferences: normalizeWorkbenchPreferences(parsed) };
+    }
+
+    return {
+      pendingPush: parsed.pendingPush === true || undefined,
+      preferences: normalizeWorkbenchPreferences(parsed.preferences),
+    };
+  } catch {
+    return null;
+  }
+};
+
+const writeLocalSettings = (preferences: WorkbenchPreferences, pendingPush?: boolean): void => {
+  if (!isBrowser()) {
+    return;
+  }
+
+  const payload: StoredSettings = pendingPush ? { pendingPush, preferences } : { preferences };
+
+  window.localStorage.setItem(getSettingsStorageKey(), JSON.stringify(payload));
+};
+
+const removeLocalSettings = (): void => {
+  if (!isBrowser()) {
+    return;
+  }
+
+  window.localStorage.removeItem(getSettingsStorageKey());
+};
+
+const readLegacyLocalPreferences = (): WorkbenchPreferences | null => {
+  if (!isBrowser()) {
+    return null;
+  }
+
+  try {
+    const raw = window.localStorage.getItem(getLegacyWorkbenchStorageKey());
+    const parsed = raw ? (JSON.parse(raw) as { state?: { account?: { preferences?: unknown } } }) : null;
+
+    return parsed?.state?.account?.preferences
+      ? normalizeWorkbenchPreferences(parsed.state.account.preferences as Partial<WorkbenchPreferences>)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const loadLegacySessionPreferences = async (): Promise<WorkbenchPreferences | null> => {
+  const blob = await fetchSessionBlob();
+
+  return blob?.account.preferences ? normalizeWorkbenchPreferences(blob.account.preferences) : null;
+};
+
+const replaceSnapshot = (preferences: WorkbenchPreferences, status: WorkbenchSettingsSnapshot['status']): void => {
+  store.setSnapshot({ preferences, scope: getSettingsScope(), status });
+};
+
+const pushPreferences = (preferences: WorkbenchPreferences): Promise<void> =>
+  setClientStateValue(SETTINGS_CLIENT_STATE_KEY, JSON.stringify(preferences));
+
+const resolveSettings = async (local: StoredSettings | null): Promise<WorkbenchPreferences> => {
+  if (local?.pendingPush) {
+    await pushPreferences(local.preferences);
+
+    return local.preferences;
+  }
+
+  const backendPreferences = parsePreferences(await getClientStateValue(SETTINGS_CLIENT_STATE_KEY));
+
+  if (backendPreferences) {
+    return backendPreferences;
+  }
+
+  // First contact for this account: adopt whatever the legacy locations
+  // hold and write the new backend key once.
+  const preferences =
+    (await loadLegacySessionPreferences()) ??
+    local?.preferences ??
+    readLegacyLocalPreferences() ??
+    normalizeWorkbenchPreferences();
+
+  await pushPreferences(preferences);
+
+  return preferences;
+};
+
+let pendingLoad: Promise<WorkbenchPreferences> | null = null;
+let pendingLoadStorageKey = '';
+let loadedStorageKey: string | null = null;
+
+/**
+ * Resolve settings once per account scope (a sign-in/out switches scope and
+ * reloads); later calls return the snapshot. Offline, the local copy serves
+ * and the next load retries the backend.
+ */
+export const loadWorkbenchSettings = (): Promise<WorkbenchPreferences> => {
+  const storageKey = getSettingsStorageKey();
+
+  if (pendingLoad && pendingLoadStorageKey === storageKey) {
+    return pendingLoad;
+  }
+
+  if (loadedStorageKey === storageKey) {
+    return Promise.resolve(getWorkbenchPreferences());
+  }
+
+  pendingLoadStorageKey = storageKey;
+  store.patchSnapshot({ scope: getSettingsScope(), status: 'loading' });
+
+  pendingLoad = (async () => {
+    const local = readLocalSettings();
+
+    try {
+      const preferences = await resolveSettings(local);
+
+      writeLocalSettings(preferences);
+      replaceSnapshot(preferences, 'ready');
+      loadedStorageKey = storageKey;
+
+      return preferences;
+    } catch (error) {
+      const fallback = local?.preferences ?? readLegacyLocalPreferences();
+      const preferences = fallback ?? normalizeWorkbenchPreferences();
+
+      writeLocalSettings(preferences, local?.pendingPush);
+      store.setSnapshot({
+        error: error instanceof Error ? error.message : 'Failed to load settings from the backend.',
+        preferences,
+        scope: getSettingsScope(),
+        status: fallback ? 'ready' : 'error',
+      });
+
+      return preferences;
+    }
+  })().finally(() => {
+    pendingLoad = null;
+  });
+
+  return pendingLoad;
+};
+
+export const useWorkbenchSettings = (): WorkbenchSettingsSnapshot => store.useSnapshot();
+
+export const useWorkbenchPreferences = (): WorkbenchPreferences =>
+  store.useSelector((snapshot) => snapshot.preferences);
+
+type EqualityFn<T> = (left: T, right: T) => boolean;
+
+export const useWorkbenchSettingsSelector = <Selected>(
+  selector: (snapshot: WorkbenchSettingsSnapshot) => Selected,
+  isEqual: EqualityFn<Selected> = Object.is
+): Selected => store.useSelector(selector, isEqual);
+
+export const useWorkbenchPreferenceSelector = <Selected>(
+  selector: (preferences: WorkbenchPreferences) => Selected,
+  isEqual?: EqualityFn<Selected>
+): Selected => useWorkbenchSettingsSelector((snapshot) => selector(snapshot.preferences), isEqual);
+
+export const getWorkbenchPreferences = (): WorkbenchPreferences => store.getSnapshot().preferences;
+
+export const getWorkbenchReduceMotion = (): boolean => store.getSnapshot().preferences.reduceMotion;
+
+export const useWorkbenchReduceMotion = (): boolean =>
+  store.useSelector((snapshot) => snapshot.preferences.reduceMotion);
+
+export const patchWorkbenchPreferences = async (preferences: Partial<WorkbenchPreferences>): Promise<void> => {
+  const next = normalizeWorkbenchPreferences({ ...store.getSnapshot().preferences, ...preferences });
+
+  replaceSnapshot(next, 'ready');
+  writeLocalSettings(next, true);
+
+  try {
+    await pushPreferences(next);
+    writeLocalSettings(next);
+  } catch (error) {
+    store.patchSnapshot({
+      error: error instanceof Error ? error.message : 'Failed to save settings.',
+      status: 'error',
+    });
+  }
+};
+
+export const clearWorkbenchSettings = async (): Promise<void> => {
+  removeLocalSettings();
+  replaceSnapshot(normalizeWorkbenchPreferences(), 'ready');
+  loadedStorageKey = getSettingsStorageKey();
+
+  try {
+    await deleteClientStateValue(SETTINGS_CLIENT_STATE_KEY);
+  } catch {
+    // Backend persistence is best-effort; the local reset should still complete.
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/BottomPanel.tsx b/invokeai/frontend/webv2/src/workbench/shell/BottomPanel.tsx
new file mode 100644
index 00000000000..0adf0588cd6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/BottomPanel.tsx
@@ -0,0 +1,39 @@
+import { MissingWidgetFrame, WidgetRendererById } from '@workbench/widget-frame';
+import { areWidgetRenderInstancesEqual } from '@workbench/widget-frame/widgetRenderInstance';
+import { resolveWidgetLabel } from '@workbench/widgetLabels';
+import { getWidgetById } from '@workbench/widgetRegistry';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useTranslation } from 'react-i18next';
+
+export const BottomPanel = () => {
+  const { t } = useTranslation();
+  const panels = useActiveProjectSelector((project) => project.layout.panels);
+  const bottomRegion = useActiveProjectSelector((project) => project.widgetRegions.bottom);
+  const instance = useActiveProjectSelector(
+    (project) => project.widgetInstances[bottomRegion.activeInstanceId],
+    areWidgetRenderInstancesEqual
+  );
+  const widget = instance ? getWidgetById(instance.typeId) : undefined;
+  const View = widget?.manifest.view;
+  const canShowBottomPanel =
+    panels.isBottomOpen &&
+    !bottomRegion.isCollapsed &&
+    bottomRegion.instanceIds.includes(bottomRegion.activeInstanceId) &&
+    widget?.status === 'enabled' &&
+    widget.manifest.bottomPanel !== 'tooltip';
+
+  if (!canShowBottomPanel) {
+    return null;
+  }
+
+  if (!instance || !widget || !View) {
+    return (
+      <MissingWidgetFrame
+        label={widget ? resolveWidgetLabel(widget.manifest, t) : bottomRegion.activeInstanceId}
+        region="bottom"
+      />
+    );
+  }
+
+  return <WidgetRendererById instanceId={instance.id} widget={widget} presentation="expanded" region="bottom" />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/CenterArea.tsx b/invokeai/frontend/webv2/src/workbench/shell/CenterArea.tsx
new file mode 100644
index 00000000000..88865de6b5c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/CenterArea.tsx
@@ -0,0 +1,308 @@
+import type { WidgetRegionDropState } from '@workbench/widgetDnd';
+import type {
+  PlacedWidgetRegionItem,
+  WidgetPlacementInstanceMeta,
+  WidgetRegionItem,
+} from '@workbench/widgetRegionViewModel';
+
+import { Box, Flex, Text } from '@chakra-ui/react';
+import { horizontalListSortingStrategy } from '@dnd-kit/sortable';
+import { useModelLoads } from '@workbench/backend/modelLoadStore';
+import { useQueueItemProgress } from '@workbench/backend/progressStore';
+import { QueueTabBackgroundProgress } from '@workbench/components/QueueProgressIndicator';
+import { Tabs } from '@workbench/components/ui';
+import { useFocusRegionProps } from '@workbench/focusRegions';
+import { WidgetIcon } from '@workbench/iconResolver';
+import { getProjectQueueIndicatorState, type QueueProgressBarState } from '@workbench/queueSummary';
+import {
+  WidgetEnableMenu,
+  WidgetInstanceContextMenu,
+  WidgetRendererById,
+  WidgetStrip,
+  useWidgetSortable,
+  type WidgetEnableMenuItem,
+  type WidgetInstanceContextMenuTarget,
+} from '@workbench/widget-frame';
+import { resolveWidgetLabel } from '@workbench/widgetLabels';
+import { closeWidgetPlacement, openWidgetPlacement, revealWidgetPlacement } from '@workbench/widgetPlacementCommands';
+import { areWidgetPlacementProjectsEqual, getWidgetPlacementProject } from '@workbench/widgetPlacementMeta';
+import {
+  createWidgetRegionViewModelFromState,
+  getWidgetRegionItems,
+  isRequiredCenterView,
+} from '@workbench/widgetRegionViewModel';
+import { getWidgetById, getWidgetsForRegion } from '@workbench/widgetRegistry';
+import { useActiveProjectSelector, useWorkbenchDispatch, useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { type MouseEvent, useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+type CenterWidgetItem = PlacedWidgetRegionItem<WidgetPlacementInstanceMeta>;
+
+const CENTER_MENU_POSITIONING = { placement: 'bottom-end' } as const;
+const CENTER_MENU_TRIGGER = { kind: 'center' } as const;
+const CENTER_PREFERRED_REGIONS = ['center'] as const;
+
+/** Center work area: the view tab strip plus the active registered center view. */
+export const CenterArea = ({ dropState }: { dropState: WidgetRegionDropState }) => {
+  const { t } = useTranslation();
+  const placementProject = useActiveProjectSelector(getWidgetPlacementProject, areWidgetPlacementProjectsEqual);
+  const centerRegion = useActiveProjectSelector((project) => project.widgetRegions.center);
+  const invocation = useActiveProjectSelector((project) => project.invocation);
+  const queueItems = useActiveProjectSelector((project) => project.queue.items);
+  const backendConnectionStatus = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status);
+  const modelLoads = useModelLoads();
+  const dispatch = useWorkbenchDispatch();
+  const [enableMenuTarget, setEnableMenuTarget] = useState<{
+    x: number;
+    y: number;
+  } | null>(null);
+  const [instanceMenuTarget, setInstanceMenuTarget] = useState<WidgetInstanceContextMenuTarget | null>(null);
+  const focusRegionProps = useFocusRegionProps('center');
+  const getWidgetLabel = useCallback(
+    (manifest: Parameters<typeof resolveWidgetLabel>[0]) => resolveWidgetLabel(manifest, t),
+    [t]
+  );
+
+  const centerRegionViewModel = createWidgetRegionViewModelFromState({
+    getWidgetLabel,
+    region: 'center',
+    regionState: centerRegion,
+    widgetInstances: placementProject.widgetInstances,
+    widgets: getWidgetsForRegion('center'),
+  });
+
+  const centerWidgetMenuItems = useMemo(() => getWidgetRegionItems(centerRegionViewModel), [centerRegionViewModel]);
+
+  const enabledCenterWidgetItems = useMemo(
+    () => centerRegionViewModel.placedItems.filter((item) => item.status === 'enabled'),
+    [centerRegionViewModel.placedItems]
+  );
+
+  const centerViewItems = useMemo(
+    () => enabledCenterWidgetItems.filter((item) => item.widget.manifest.centerPlacement !== 'toolbar'),
+    [enabledCenterWidgetItems]
+  );
+
+  const centerToolbarItems = useMemo(
+    () => enabledCenterWidgetItems.filter((item) => item.widget.manifest.centerPlacement === 'toolbar'),
+    [enabledCenterWidgetItems]
+  );
+
+  const activeCenterViewId = centerViewItems.some((item) => item.id === centerRegion.activeInstanceId)
+    ? centerRegion.activeInstanceId
+    : centerViewItems[0]?.id;
+
+  const centerSortableInstanceIds = useMemo(
+    () =>
+      centerRegionViewModel.sortableInstanceIds.filter((instanceId) =>
+        centerViewItems.some((item) => item.id === instanceId)
+      ),
+    [centerRegionViewModel.sortableInstanceIds, centerViewItems]
+  );
+
+  const openEnableMenu = useCallback((event: MouseEvent) => {
+    event.preventDefault();
+    setEnableMenuTarget({ x: event.clientX, y: event.clientY });
+  }, []);
+
+  const openInstanceMenu = useCallback((item: CenterWidgetItem, event: MouseEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
+    setInstanceMenuTarget({ item, x: event.clientX, y: event.clientY });
+  }, []);
+
+  const toggleCenterWidget = useCallback(
+    (item: WidgetEnableMenuItem) =>
+      item.isEnabled
+        ? closeWidgetPlacement({
+            dispatch,
+            getWidgetById,
+            instanceId: item.id,
+            project: placementProject,
+            region: 'center',
+          })
+        : openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: {
+              createNew: item.allowMultiple,
+              preferredRegions: CENTER_PREFERRED_REGIONS,
+            },
+            typeId: item.typeId,
+          }),
+    [dispatch, placementProject]
+  );
+
+  const handleCenterTabChange = useCallback(
+    (event: { value: string }) =>
+      revealWidgetPlacement({
+        dispatch,
+        instanceId: event.value as CenterWidgetItem['id'],
+        project: placementProject,
+        region: 'center',
+      }),
+    [dispatch, placementProject]
+  );
+
+  const handleContextClose = useCallback(() => setEnableMenuTarget(null), []);
+  const handleInstanceClose = useCallback(() => setInstanceMenuTarget(null), []);
+
+  const getItemMeta = useCallback(
+    (item: WidgetEnableMenuItem) =>
+      isRequiredCenterView(item as WidgetRegionItem, centerViewItems.length) ? 'Required' : null,
+    [centerViewItems.length]
+  );
+
+  const isItemDisabled = useCallback(
+    (item: WidgetEnableMenuItem) => isRequiredCenterView(item as WidgetRegionItem, centerViewItems.length),
+    [centerViewItems.length]
+  );
+
+  const baseIndicatorState = getProjectQueueIndicatorState({
+    isConnected: backendConnectionStatus === 'connected',
+    loadingModelsCount: modelLoads.length,
+    progress: null,
+    queueItems,
+  });
+
+  const progress = useQueueItemProgress(baseIndicatorState.runningQueueItemId ?? '');
+
+  const indicatorState = getProjectQueueIndicatorState({
+    isConnected: backendConnectionStatus === 'connected',
+    loadingModelsCount: modelLoads.length,
+    progress,
+    queueItems,
+  });
+
+  return (
+    <Flex as="section" bg="bg" direction="column" flex="1" minH="0" minW="0" {...focusRegionProps}>
+      <WidgetStrip
+        align="center"
+        bg="bg.subtle"
+        borderBottomWidth="1px"
+        borderColor="border.subtle"
+        dropState={dropState}
+        h="10"
+        px="1.5"
+        region="center"
+        sortableInstanceIds={centerSortableInstanceIds}
+        strategy={horizontalListSortingStrategy}
+        onContextMenu={openEnableMenu}
+      >
+        <Tabs.Root value={activeCenterViewId} h="full" w="full" onValueChange={handleCenterTabChange}>
+          <Tabs.List>
+            {centerViewItems.map((item) => (
+              <SortableCenterTab
+                key={item.id}
+                item={item}
+                progressState={indicatorState.progressState}
+                showProgress={indicatorState.hasOpenQueueWork && item.typeId === invocation.sourceId}
+                onContextMenu={openInstanceMenu}
+              />
+            ))}
+          </Tabs.List>
+        </Tabs.Root>
+
+        <Box flex="1" />
+
+        {centerToolbarItems.map((item) => (
+          <Flex key={item.id} align="center" h="full">
+            <WidgetRendererById instanceId={item.id} widget={item.widget} presentation="compact" region="center" />
+          </Flex>
+        ))}
+
+        <WidgetEnableMenu
+          contextTarget={enableMenuTarget}
+          getItemMeta={getItemMeta}
+          groupLabel="Center Widgets"
+          isItemDisabled={isItemDisabled}
+          items={centerWidgetMenuItems}
+          positioning={CENTER_MENU_POSITIONING}
+          trigger={CENTER_MENU_TRIGGER}
+          triggerLabel="Center widget menu"
+          onContextClose={handleContextClose}
+          onToggle={toggleCenterWidget}
+        />
+
+        <WidgetInstanceContextMenu
+          isRemoveDisabled={isItemDisabled}
+          target={instanceMenuTarget}
+          onClose={handleInstanceClose}
+          onRemove={toggleCenterWidget}
+        />
+      </WidgetStrip>
+
+      <Box flex="1" minH="0" position="relative">
+        <CenterViewSlot activeWidgetId={activeCenterViewId} items={centerViewItems} />
+      </Box>
+    </Flex>
+  );
+};
+
+const SortableCenterTab = ({
+  item,
+  onContextMenu,
+  progressState,
+  showProgress,
+}: {
+  item: CenterWidgetItem;
+  onContextMenu: (item: CenterWidgetItem, event: MouseEvent) => void;
+  progressState: QueueProgressBarState;
+  showProgress: boolean;
+}) => {
+  const { dragHandleProps, setNodeRef, style } = useWidgetSortable({
+    disabled: item.status === 'disabled',
+    instanceId: item.id,
+    region: 'center',
+    typeId: item.instance.typeId,
+  });
+  const handleContextMenu = useCallback((event: MouseEvent) => onContextMenu(item, event), [item, onContextMenu]);
+
+  return (
+    <Tabs.Trigger
+      ref={setNodeRef}
+      value={item.id}
+      disabled={item.status === 'disabled'}
+      fontSize="xs"
+      overflow="hidden"
+      position="relative"
+      px="3"
+      style={style}
+      {...dragHandleProps}
+      onContextMenu={handleContextMenu}
+    >
+      {showProgress ? <QueueTabBackgroundProgress state={progressState} zIndex="-1" /> : null}
+
+      <Box alignItems="center" display="inline-flex" gap="2" position="relative" zIndex="1">
+        <WidgetIcon icon={item.widget.manifest.icon} boxSize="3.5" />
+        {item.label}
+      </Box>
+    </Tabs.Trigger>
+  );
+};
+
+const CenterViewSlot = ({
+  activeWidgetId,
+  items,
+}: {
+  activeWidgetId: string | undefined;
+  items: CenterWidgetItem[];
+}) => {
+  const widget = items.find((item) => item.id === activeWidgetId)?.widget;
+  const instance = items.find((item) => item.id === activeWidgetId)?.instance;
+  const View = widget?.manifest.view;
+
+  if (!instance || !widget || widget.status !== 'enabled' || !View) {
+    return <FallbackCenterView label="Center widget unavailable" />;
+  }
+
+  return <WidgetRendererById instanceId={instance.id} widget={widget} region="center" />;
+};
+
+const FallbackCenterView = ({ label }: { label: string }) => (
+  <Flex align="center" h="full" justify="center" w="full">
+    <Text color="fg.subtle" fontSize="sm" textTransform="capitalize">
+      {label} view
+    </Text>
+  </Flex>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/shell/Panels.tsx b/invokeai/frontend/webv2/src/workbench/shell/Panels.tsx
new file mode 100644
index 00000000000..f16aef41ccc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/Panels.tsx
@@ -0,0 +1,40 @@
+import type { WidgetInstanceId, WorkbenchRegion } from '@workbench/types';
+
+import { MissingWidgetFrame, WidgetRendererById } from '@workbench/widget-frame';
+import { areWidgetRenderInstancesEqual } from '@workbench/widget-frame/widgetRenderInstance';
+import { resolveWidgetLabel } from '@workbench/widgetLabels';
+import { getWidgetById } from '@workbench/widgetRegistry';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useTranslation } from 'react-i18next';
+
+/** Left panel — hosts the active registered widget panel view. */
+export const LeftPanel = ({ instanceId }: { instanceId: WidgetInstanceId }) => (
+  <WidgetPanelSlot instanceId={instanceId} panel="leftPanel" />
+);
+
+/** Right panel — hosts the active registered widget panel view. */
+export const RightPanel = ({ instanceId }: { instanceId: WidgetInstanceId }) => (
+  <WidgetPanelSlot instanceId={instanceId} panel="rightPanel" />
+);
+
+const panelRegions = {
+  leftPanel: 'left',
+  rightPanel: 'right',
+} as const satisfies Record<string, WorkbenchRegion>;
+
+const WidgetPanelSlot = ({ instanceId, panel }: { instanceId: WidgetInstanceId; panel: keyof typeof panelRegions }) => {
+  const { t } = useTranslation();
+  const instance = useActiveProjectSelector(
+    (project) => project.widgetInstances[instanceId],
+    areWidgetRenderInstancesEqual
+  );
+  const widget = instance ? getWidgetById(instance.typeId) : undefined;
+  const View = widget?.manifest.view;
+  const region = panelRegions[panel];
+
+  if (!instance || !widget || widget.status !== 'enabled' || !View) {
+    return <MissingWidgetFrame label={widget ? resolveWidgetLabel(widget.manifest, t) : instanceId} region={region} />;
+  }
+
+  return <WidgetRendererById instanceId={instance.id} widget={widget} region={region} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/StatusBar.tsx b/invokeai/frontend/webv2/src/workbench/shell/StatusBar.tsx
new file mode 100644
index 00000000000..c5c46e7722c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/StatusBar.tsx
@@ -0,0 +1,247 @@
+import type { WidgetInstanceId } from '@workbench/types';
+import type { WidgetRegionDropState } from '@workbench/widgetDnd';
+import type { PlacedWidgetRegionItem, WidgetPlacementInstanceMeta } from '@workbench/widgetRegionViewModel';
+
+import { Box } from '@chakra-ui/react';
+import { horizontalListSortingStrategy } from '@dnd-kit/sortable';
+import { Row, Tooltip } from '@workbench/components/ui';
+import {
+  WidgetEnableMenu,
+  WidgetInstanceContextMenu,
+  WidgetRendererById,
+  WidgetStrip,
+  useWidgetSortable,
+  type WidgetEnableMenuItem,
+  type WidgetInstanceContextMenuTarget,
+} from '@workbench/widget-frame';
+import { resolveWidgetLabel } from '@workbench/widgetLabels';
+import { closeWidgetPlacement, openWidgetPlacement, revealWidgetPlacement } from '@workbench/widgetPlacementCommands';
+import { areWidgetPlacementProjectsEqual, getWidgetPlacementProject } from '@workbench/widgetPlacementMeta';
+import {
+  createWidgetRegionViewModelFromState,
+  getWidgetRegionItems,
+  isCompactBottomItem,
+  isExpandableBottomItem,
+} from '@workbench/widgetRegionViewModel';
+import { getWidgetById, getWidgetsForRegion } from '@workbench/widgetRegistry';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { type KeyboardEvent, type MouseEvent, useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+interface BottomWidgetItem extends PlacedWidgetRegionItem<WidgetPlacementInstanceMeta> {
+  isExpandable: boolean;
+}
+
+const BOTTOM_MENU_POSITIONING = { placement: 'top-end' } as const;
+const BOTTOM_MENU_TRIGGER = { kind: 'bottom' } as const;
+const COMPACT_ROW_HOVER_PROPS = { color: 'fg' };
+const COMPACT_ROW_ACTIVE_HOVER_PROPS = { color: 'accent.contrast' };
+const TOOLTIP_POSITIONING = { placement: 'top-start' } as const;
+
+export const StatusBar = ({ dropState }: { dropState: WidgetRegionDropState }) => {
+  const { t } = useTranslation();
+  const placementProject = useActiveProjectSelector(getWidgetPlacementProject, areWidgetPlacementProjectsEqual);
+  const bottomRegion = useActiveProjectSelector((project) => project.widgetRegions.bottom);
+  const dispatch = useWorkbenchDispatch();
+  const [enableMenuTarget, setEnableMenuTarget] = useState<{ x: number; y: number } | null>(null);
+  const [instanceMenuTarget, setInstanceMenuTarget] = useState<WidgetInstanceContextMenuTarget | null>(null);
+  const getWidgetLabel = useCallback(
+    (manifest: Parameters<typeof resolveWidgetLabel>[0]) => resolveWidgetLabel(manifest, t),
+    [t]
+  );
+  const bottomRegionViewModel = createWidgetRegionViewModelFromState({
+    getWidgetLabel,
+    region: 'bottom',
+    regionState: bottomRegion,
+    widgetInstances: placementProject.widgetInstances,
+    widgets: getWidgetsForRegion('bottom'),
+  });
+  const items = getWidgetRegionItems(bottomRegionViewModel);
+  const compactItems = items.flatMap((item): BottomWidgetItem[] => {
+    if (!isCompactBottomItem(item)) {
+      return [];
+    }
+
+    return [{ ...item, isExpandable: isExpandableBottomItem(item) }];
+  });
+  const sortableInstanceIds = useMemo(() => compactItems.map((item) => item.id), [compactItems]);
+  const openEnableMenu = useCallback((event: MouseEvent) => {
+    event.preventDefault();
+    setEnableMenuTarget({ x: event.clientX, y: event.clientY });
+  }, []);
+  const openInstanceMenu = useCallback((item: BottomWidgetItem, event: MouseEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
+    setInstanceMenuTarget({ item, x: event.clientX, y: event.clientY });
+  }, []);
+  const toggleBottomWidget = useCallback(
+    (item: WidgetEnableMenuItem) =>
+      item.isEnabled
+        ? closeWidgetPlacement({
+            dispatch,
+            getWidgetById,
+            instanceId: item.id,
+            project: placementProject,
+            region: 'bottom',
+          })
+        : openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { createNew: item.allowMultiple, preferredRegions: ['bottom'] },
+            typeId: item.typeId,
+          }),
+    [dispatch, placementProject]
+  );
+  const handleSelect = useCallback(
+    (instanceId: WidgetInstanceId) =>
+      revealWidgetPlacement({ dispatch, instanceId, project: placementProject, region: 'bottom' }),
+    [dispatch, placementProject]
+  );
+  const handleContextClose = useCallback(() => setEnableMenuTarget(null), []);
+  const handleInstanceClose = useCallback(() => setInstanceMenuTarget(null), []);
+
+  return (
+    <WidgetStrip
+      align="center"
+      as="footer"
+      bg="bg.subtle"
+      borderTopWidth="1px"
+      borderColor="border.subtle"
+      color="fg.muted"
+      dropState={dropState}
+      flexShrink={0}
+      h="6"
+      px="2"
+      region="bottom"
+      sortableInstanceIds={sortableInstanceIds}
+      strategy={horizontalListSortingStrategy}
+      w="full"
+      onContextMenu={openEnableMenu}
+    >
+      {compactItems.map((item) => (
+        <CompactBottomWidget
+          key={item.id}
+          item={item}
+          isActive={item.isExpandable && item.id === bottomRegion.activeInstanceId && !bottomRegion.isCollapsed}
+          onContextMenu={openInstanceMenu}
+          onSelect={handleSelect}
+        />
+      ))}
+
+      <Box flex="1" />
+
+      <WidgetEnableMenu
+        contextTarget={enableMenuTarget}
+        groupLabel="Bottom Widgets"
+        items={items}
+        positioning={BOTTOM_MENU_POSITIONING}
+        trigger={BOTTOM_MENU_TRIGGER}
+        triggerLabel="Bottom widget visibility"
+        onContextClose={handleContextClose}
+        onToggle={toggleBottomWidget}
+      />
+      <WidgetInstanceContextMenu
+        target={instanceMenuTarget}
+        onClose={handleInstanceClose}
+        onRemove={toggleBottomWidget}
+      />
+    </WidgetStrip>
+  );
+};
+
+const CompactBottomWidget = ({
+  isActive,
+  item,
+  onContextMenu,
+  onSelect,
+}: {
+  isActive: boolean;
+  item: BottomWidgetItem;
+  onContextMenu: (item: BottomWidgetItem, event: MouseEvent) => void;
+  onSelect: (widgetId: WidgetInstanceId) => void;
+}) => {
+  const View = item.widget.manifest.view;
+  const { dragHandleProps, isDragging, setNodeRef, style } = useWidgetSortable({
+    instanceId: item.id,
+    region: 'bottom',
+    typeId: item.typeId,
+  });
+  const rowDragHandleProps = item.isExpandable
+    ? Object.fromEntries(Object.entries(dragHandleProps).filter(([key]) => key !== 'onKeyDown'))
+    : dragHandleProps;
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        onSelect(item.id);
+      }
+    },
+    [item.id, onSelect]
+  );
+  const activationProps = useMemo(
+    () =>
+      item.isExpandable
+        ? {
+            role: 'button' as const,
+            tabIndex: 0,
+            onKeyDown: handleKeyDown,
+          }
+        : {},
+    [handleKeyDown, item.isExpandable]
+  );
+  const handleClick = useCallback(() => {
+    if (item.isExpandable) {
+      onSelect(item.id);
+    }
+  }, [item.id, item.isExpandable, onSelect]);
+  const handleContextMenu = useCallback((event: MouseEvent) => onContextMenu(item, event), [item, onContextMenu]);
+  const tooltipContent = useMemo(() => (item.instance ? <BottomWidgetTooltipContent item={item} /> : null), [item]);
+
+  if (!View) {
+    return null;
+  }
+
+  const content = (
+    <Box ref={setNodeRef} h="full" style={style}>
+      <Row
+        {...rowDragHandleProps}
+        active={isActive ? 'accent' : 'none'}
+        aria-label={item.label}
+        aria-pressed={isActive}
+        cursor={isDragging ? 'grabbing' : item.isExpandable ? 'pointer' : 'default'}
+        h="full"
+        w="auto"
+        _hover={isActive ? COMPACT_ROW_ACTIVE_HOVER_PROPS : COMPACT_ROW_HOVER_PROPS}
+        {...activationProps}
+        onClick={handleClick}
+        onContextMenu={handleContextMenu}
+      >
+        {item.instance ? (
+          <WidgetRendererById instanceId={item.id} widget={item.widget} presentation="compact" region="bottom" />
+        ) : null}
+      </Row>
+    </Box>
+  );
+  if (item.isExpandable) {
+    return (
+      <Tooltip
+        closeDelay={80}
+        content={item.failureMessage ? `${item.label}: ${item.failureMessage}` : item.label}
+        openDelay={250}
+        positioning={TOOLTIP_POSITIONING}
+      >
+        {content}
+      </Tooltip>
+    );
+  }
+
+  return (
+    <Tooltip closeDelay={80} content={tooltipContent} openDelay={250} positioning={TOOLTIP_POSITIONING}>
+      {content}
+    </Tooltip>
+  );
+};
+
+const BottomWidgetTooltipContent = ({ item }: { item: BottomWidgetItem }) => (
+  <WidgetRendererById instanceId={item.id} widget={item.widget} presentation="tooltip" region="bottom" />
+);
diff --git a/invokeai/frontend/webv2/src/workbench/shell/WorkbenchShell.tsx b/invokeai/frontend/webv2/src/workbench/shell/WorkbenchShell.tsx
new file mode 100644
index 00000000000..3150eb75de4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/WorkbenchShell.tsx
@@ -0,0 +1,277 @@
+import { Flex, HStack, Text } from '@chakra-ui/react';
+import {
+  DndContext,
+  DragOverlay,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+  type DragStartEvent,
+} from '@dnd-kit/core';
+import { restrictToWindowEdges } from '@dnd-kit/modifiers';
+import { sortableKeyboardCoordinates } from '@dnd-kit/sortable';
+import { FocusRegionProvider } from '@workbench/focusRegions';
+import { WidgetIcon } from '@workbench/iconResolver';
+import { WidgetBar } from '@workbench/widget-frame';
+import {
+  getRegionDropState,
+  isWidgetDndData,
+  isWidgetInstanceDragData,
+  resolveWidgetDragEnd,
+  type ActiveWidgetDrag,
+  widgetCollisionDetection,
+} from '@workbench/widgetDnd';
+import { resolveWidgetLabel } from '@workbench/widgetLabels';
+import {
+  closeWidgetPlacement,
+  dispatchWidgetDragEndPlacement,
+  openWidgetPlacement,
+  revealWidgetPlacement,
+} from '@workbench/widgetPlacementCommands';
+import { areWidgetPlacementProjectsEqual, getWidgetPlacementProject } from '@workbench/widgetPlacementMeta';
+import { createWidgetRegionViewModelFromState, getWidgetRegionItems } from '@workbench/widgetRegionViewModel';
+import { getWidgetById, getWidgetsForRegion, widgetRegistrationFailures } from '@workbench/widgetRegistry';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { WorkbenchWidgetRegistryProvider } from '@workbench/WorkbenchWidgetRegistryContext';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { BottomPanel } from './BottomPanel';
+import { CenterArea } from './CenterArea';
+import { WorkbenchNotificationToaster } from './notifications';
+import { LeftPanel, RightPanel } from './Panels';
+import { StatusBar } from './StatusBar';
+import { TopBar } from './topbar';
+
+const DND_MODIFIERS = [restrictToWindowEdges];
+
+export const WorkbenchShell = () => {
+  const dispatch = useWorkbenchDispatch();
+  const { t } = useTranslation();
+  const panels = useActiveProjectSelector((project) => project.layout.panels);
+  const leftRegion = useActiveProjectSelector((project) => project.widgetRegions.left);
+  const rightRegion = useActiveProjectSelector((project) => project.widgetRegions.right);
+  const placementProject = useActiveProjectSelector(getWidgetPlacementProject, areWidgetPlacementProjectsEqual);
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 6 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
+  );
+  const [activeDrag, setActiveDrag] = useState<ActiveWidgetDrag | null>(null);
+  const getWidgetLabel = useCallback(
+    (manifest: Parameters<typeof resolveWidgetLabel>[0]) => resolveWidgetLabel(manifest, t),
+    [t]
+  );
+  const leftRegionViewModel = useMemo(
+    () =>
+      createWidgetRegionViewModelFromState({
+        region: 'left',
+        regionState: leftRegion,
+        widgetInstances: placementProject.widgetInstances,
+        widgets: getWidgetsForRegion('left'),
+        getWidgetLabel,
+      }),
+    [getWidgetLabel, leftRegion, placementProject.widgetInstances]
+  );
+  const rightRegionViewModel = useMemo(
+    () =>
+      createWidgetRegionViewModelFromState({
+        region: 'right',
+        regionState: rightRegion,
+        widgetInstances: placementProject.widgetInstances,
+        widgets: getWidgetsForRegion('right'),
+        getWidgetLabel,
+      }),
+    [getWidgetLabel, placementProject.widgetInstances, rightRegion]
+  );
+  const leftMenuItems = useMemo(() => getWidgetRegionItems(leftRegionViewModel), [leftRegionViewModel]);
+  const rightMenuItems = useMemo(() => getWidgetRegionItems(rightRegionViewModel), [rightRegionViewModel]);
+  const leftRailItems = useMemo(
+    () => leftRegionViewModel.placedItems.filter((item) => item.status !== 'disabled'),
+    [leftRegionViewModel]
+  );
+  const rightRailItems = useMemo(
+    () => rightRegionViewModel.placedItems.filter((item) => item.status !== 'disabled'),
+    [rightRegionViewModel]
+  );
+  const canShowLeftPanel = leftRailItems.some((item) => item.id === leftRegion.activeInstanceId);
+  const canShowRightPanel = rightRailItems.some((item) => item.id === rightRegion.activeInstanceId);
+  const leftDropState = useMemo(
+    () => getRegionDropState(placementProject, activeDrag, 'left', getWidgetById),
+    [activeDrag, placementProject]
+  );
+  const rightDropState = useMemo(
+    () => getRegionDropState(placementProject, activeDrag, 'right', getWidgetById),
+    [activeDrag, placementProject]
+  );
+  const centerDropState = useMemo(
+    () => getRegionDropState(placementProject, activeDrag, 'center', getWidgetById),
+    [activeDrag, placementProject]
+  );
+  const bottomDropState = useMemo(
+    () => getRegionDropState(placementProject, activeDrag, 'bottom', getWidgetById),
+    [activeDrag, placementProject]
+  );
+
+  useEffect(() => {
+    for (const failure of widgetRegistrationFailures) {
+      dispatch({ failure, type: 'recordWidgetFailure' });
+    }
+  }, [dispatch]);
+
+  const handleDragStart = useCallback(
+    (event: DragStartEvent) => {
+      const activeData = event.active.data.current;
+
+      if (!isWidgetInstanceDragData(activeData)) {
+        return;
+      }
+
+      const instance = placementProject.widgetInstances[activeData.instanceId];
+      const widget = instance ? getWidgetById(instance.typeId) : undefined;
+
+      if (!instance || !widget) {
+        return;
+      }
+
+      setActiveDrag({
+        fromRegion: activeData.region,
+        icon: widget.manifest.icon,
+        instanceId: activeData.instanceId,
+        label: instance.title ?? getWidgetLabel(widget.manifest),
+        typeId: instance.typeId,
+      });
+    },
+    [getWidgetLabel, placementProject.widgetInstances]
+  );
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const activeData = event.active.data.current;
+      const overData = event.over?.data.current ?? null;
+
+      setActiveDrag(null);
+
+      if (!isWidgetInstanceDragData(activeData) || !isWidgetDndData(overData)) {
+        return;
+      }
+
+      const resolution = resolveWidgetDragEnd(placementProject, activeData, overData, getWidgetById);
+
+      if (!resolution) {
+        return;
+      }
+
+      dispatchWidgetDragEndPlacement({ dispatch, resolution });
+    },
+    [dispatch, placementProject]
+  );
+  const handleDragCancel = useCallback(() => setActiveDrag(null), []);
+  const handleSelectLeft = useCallback(
+    (instanceId: string) => revealWidgetPlacement({ dispatch, instanceId, project: placementProject, region: 'left' }),
+    [dispatch, placementProject]
+  );
+  const handleSelectRight = useCallback(
+    (instanceId: string) => revealWidgetPlacement({ dispatch, instanceId, project: placementProject, region: 'right' }),
+    [dispatch, placementProject]
+  );
+  const handleToggleLeft = useCallback(
+    (item: (typeof leftMenuItems)[number]) =>
+      item.isEnabled
+        ? closeWidgetPlacement({
+            dispatch,
+            getWidgetById,
+            instanceId: item.id,
+            project: placementProject,
+            region: 'left',
+          })
+        : openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { createNew: item.allowMultiple, preferredRegions: ['left'] },
+            typeId: item.typeId,
+          }),
+    [dispatch, placementProject]
+  );
+  const handleToggleRight = useCallback(
+    (item: (typeof rightMenuItems)[number]) =>
+      item.isEnabled
+        ? closeWidgetPlacement({
+            dispatch,
+            getWidgetById,
+            instanceId: item.id,
+            project: placementProject,
+            region: 'right',
+          })
+        : openWidgetPlacement({
+            dispatch,
+            getWidgetsForRegion,
+            options: { createNew: item.allowMultiple, preferredRegions: ['right'] },
+            typeId: item.typeId,
+          }),
+    [dispatch, placementProject]
+  );
+
+  return (
+    <WorkbenchWidgetRegistryProvider getWidgetById={getWidgetById} getWidgetsForRegion={getWidgetsForRegion}>
+      <FocusRegionProvider>
+        <DndContext
+          collisionDetection={widgetCollisionDetection}
+          modifiers={DND_MODIFIERS}
+          sensors={sensors}
+          onDragCancel={handleDragCancel}
+          onDragEnd={handleDragEnd}
+          onDragStart={handleDragStart}
+        >
+          <Flex direction="column" h="100vh" w="100vw">
+            <WorkbenchNotificationToaster />
+            <TopBar />
+
+            <Flex as="main" flex="1" minH="0" overflow="hidden">
+              <WidgetBar
+                activeId={panels.isLeftOpen && !leftRegion.isCollapsed ? leftRegion.activeInstanceId : null}
+                dropState={leftDropState}
+                menuItems={leftMenuItems}
+                railItems={leftRailItems}
+                region="left"
+                side="left"
+                onSelect={handleSelectLeft}
+                onToggle={handleToggleLeft}
+              />
+              {panels.isLeftOpen && !leftRegion.isCollapsed && canShowLeftPanel ? (
+                <LeftPanel instanceId={leftRegion.activeInstanceId} />
+              ) : null}
+              <CenterArea dropState={centerDropState} />
+              {panels.isRightOpen && !rightRegion.isCollapsed && canShowRightPanel ? (
+                <RightPanel instanceId={rightRegion.activeInstanceId} />
+              ) : null}
+              <WidgetBar
+                activeId={panels.isRightOpen && !rightRegion.isCollapsed ? rightRegion.activeInstanceId : null}
+                dropState={rightDropState}
+                menuItems={rightMenuItems}
+                railItems={rightRailItems}
+                region="right"
+                side="right"
+                onSelect={handleSelectRight}
+                onToggle={handleToggleRight}
+              />
+            </Flex>
+
+            <BottomPanel />
+            <StatusBar dropState={bottomDropState} />
+          </Flex>
+          <DragOverlay>{activeDrag ? <WidgetDragPreview activeDrag={activeDrag} /> : null}</DragOverlay>
+        </DndContext>
+      </FocusRegionProvider>
+    </WorkbenchWidgetRegistryProvider>
+  );
+};
+
+const WidgetDragPreview = ({ activeDrag }: { activeDrag: ActiveWidgetDrag }) => (
+  <HStack bg="bg" borderWidth="1px" gap="2" px="3" py="2" rounded="md" shadow="lg">
+    <WidgetIcon icon={activeDrag.icon} boxSize="4" />
+    <Text fontSize="xs" fontWeight="700">
+      {activeDrag.label}
+    </Text>
+  </HStack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/shell/index.ts b/invokeai/frontend/webv2/src/workbench/shell/index.ts
new file mode 100644
index 00000000000..6793a6b4f7d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/index.ts
@@ -0,0 +1,7 @@
+export { WorkbenchShell } from './WorkbenchShell';
+export { BottomPanel } from './BottomPanel';
+export { CenterArea } from './CenterArea';
+export { LeftPanel, RightPanel } from './Panels';
+export { StatusBar } from './StatusBar';
+export { TopBar } from './topbar';
+export { WorkbenchNotificationToaster } from './notifications';
diff --git a/invokeai/frontend/webv2/src/workbench/shell/notifications/WorkbenchNotificationToaster.tsx b/invokeai/frontend/webv2/src/workbench/shell/notifications/WorkbenchNotificationToaster.tsx
new file mode 100644
index 00000000000..f148ebeb83b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/notifications/WorkbenchNotificationToaster.tsx
@@ -0,0 +1,40 @@
+import type { WorkbenchNotificationKind } from '@workbench/types';
+
+import { toaster } from '@workbench/components/ui';
+import { useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { useEffect, useRef } from 'react';
+
+const notificationToastType: Record<WorkbenchNotificationKind, 'error' | 'info' | 'success'> = {
+  error: 'error',
+  info: 'info',
+  success: 'success',
+};
+
+export const WorkbenchNotificationToaster = () => {
+  const notifications = useWorkbenchSelector((snapshot) => snapshot.state.notifications);
+  const toastedNotificationIdsRef = useRef<Set<string> | null>(null);
+
+  useEffect(() => {
+    if (toastedNotificationIdsRef.current === null) {
+      toastedNotificationIdsRef.current = new Set(notifications.map((notification) => notification.id));
+      return;
+    }
+
+    for (const notification of [...notifications].reverse()) {
+      if (toastedNotificationIdsRef.current.has(notification.id)) {
+        continue;
+      }
+
+      toastedNotificationIdsRef.current.add(notification.id);
+      queueMicrotask(() => {
+        toaster.create({
+          description: notification.message,
+          title: notification.title,
+          type: notificationToastType[notification.kind],
+        });
+      });
+    }
+  }, [notifications]);
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/notifications/index.ts b/invokeai/frontend/webv2/src/workbench/shell/notifications/index.ts
new file mode 100644
index 00000000000..ded90207494
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/notifications/index.ts
@@ -0,0 +1 @@
+export { WorkbenchNotificationToaster } from './WorkbenchNotificationToaster';
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/BatchCountField.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/BatchCountField.tsx
new file mode 100644
index 00000000000..30048849f5a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/BatchCountField.tsx
@@ -0,0 +1,38 @@
+import { NumberInput } from '@chakra-ui/react';
+import { MIN_BATCH_COUNT, sanitizeBatchCount } from '@workbench/generation/batch';
+import { useWidgetValuesSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useCallback } from 'react';
+
+const getBatchCount = (values: Record<string, unknown>): number => {
+  const batchCount = values.batchCount;
+
+  return sanitizeBatchCount(batchCount);
+};
+
+export const BatchCountField = () => {
+  const batchCount = useWidgetValuesSelector('generate', getBatchCount);
+  const dispatch = useWorkbenchDispatch();
+  const handleValueChange = useCallback(
+    ({ valueAsNumber }: { valueAsNumber: number }) => {
+      if (Number.isFinite(valueAsNumber)) {
+        dispatch({ batchCount: valueAsNumber, type: 'setGenerateBatchCount' });
+      }
+    },
+    [dispatch]
+  );
+
+  return (
+    <NumberInput.Root
+      allowMouseWheel
+      flexShrink={0}
+      min={MIN_BATCH_COUNT}
+      size="sm"
+      value={String(batchCount)}
+      w="14"
+      onValueChange={handleValueChange}
+    >
+      <NumberInput.Control />
+      <NumberInput.Input paddingStart="2.5" aria-label="Batch count" />
+    </NumberInput.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/InvokeControl.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/InvokeControl.tsx
new file mode 100644
index 00000000000..2d5ec9d74a3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/InvokeControl.tsx
@@ -0,0 +1,281 @@
+/* eslint-disable react/react-compiler */
+import type { InvocationRoute, InvocationSourceId, ResultDestination } from '@workbench/types';
+
+import { Flex, Group, HStack, Icon, Menu, Portal, Separator, Stack, Text, VStack } from '@chakra-ui/react';
+import { Button, IconButton, Tooltip } from '@workbench/components/ui';
+import { sanitizeBatchCount } from '@workbench/generation/batch';
+import {
+  formatRoute,
+  createInvocationRouteInputSelector,
+  getDestinationLabel,
+  invocationSources,
+  isInvocationRouteValid,
+  resolveInvocationRoute,
+  resolveInvocationRouteInput,
+  resultDestinations,
+} from '@workbench/invocation';
+import { submitResolvedInvocation } from '@workbench/invocationSubmit';
+import { ensureModelsLoaded, useModelsSelector } from '@workbench/models/modelsStore';
+import { prepareCanvasInvocation } from '@workbench/widgets/canvas/invoke/prepareCanvasInvocation';
+import { flushGenerateDrafts } from '@workbench/widgets/generate/generateDraftRegistry';
+import {
+  useActiveProjectSelector,
+  useWorkbenchDispatch,
+  useWorkbenchSelector,
+  useWorkbenchStore,
+} from '@workbench/WorkbenchContext';
+import { useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import { CheckIcon, ChevronDownIcon, LockKeyholeIcon, SparklesIcon } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+const CONTROL_WIDTH = '10rem';
+const selectInvocationRouteInput = createInvocationRouteInputSelector();
+const MENU_POSITIONING = { placement: 'bottom-end' } as const;
+const TOOLTIP_CONTENT_PROPS = { p: '0' };
+const DISABLED_PROPS = { opacity: 0.4 };
+
+const getBatchCount = (values: Record<string, unknown>): number => {
+  const batchCount = values.batchCount;
+
+  return sanitizeBatchCount(batchCount);
+};
+
+const compactBlockingReason = (reason: string): string => {
+  if (reason === 'The project graph has no nodes. Add nodes in the Workflow view.') {
+    return 'No nodes in graph';
+  }
+
+  return reason.replace(/^The /, '').replace(/project graph/i, 'workflow');
+};
+
+const InvokeTooltipContent = ({
+  blockingReasons,
+  generateValues,
+  invocation,
+  isValid,
+}: {
+  blockingReasons: string[];
+  generateValues: Record<string, unknown>;
+  invocation: InvocationRoute;
+  isValid: boolean;
+}) => {
+  const batchCount = getBatchCount(generateValues);
+  const destination = getDestinationLabel(invocation.destination);
+  const summary =
+    invocation.sourceId === 'generate'
+      ? `1 prompt × ${batchCount} iteration${batchCount === 1 ? '' : 's'} → ${batchCount} generation${batchCount === 1 ? '' : 's'}`
+      : `Workflow × ${batchCount} run${batchCount === 1 ? '' : 's'} → ${batchCount} generation${batchCount === 1 ? '' : 's'}`;
+
+  return (
+    <Stack gap="1.5" minW="14rem" p="2">
+      <Text fontSize="xs" fontWeight="800">
+        {isValid ? 'Add to Queue' : 'Unable to Queue'}
+      </Text>
+      <Text color="fg.muted" fontSize="xs">
+        {summary}
+      </Text>
+      {blockingReasons.length > 0 ? (
+        <>
+          <Separator borderColor="border.subtle" />
+          <Stack gap="1">
+            {blockingReasons.map((reason) => (
+              <HStack key={reason} align="start" gap="1.5">
+                <Text color="fg.subtle" fontSize="xs" lineHeight="1.35">
+                  •
+                </Text>
+                <Text color="fg.muted" fontSize="xs" lineHeight="1.35">
+                  {compactBlockingReason(reason)}
+                </Text>
+              </HStack>
+            ))}
+          </Stack>
+        </>
+      ) : (
+        <>
+          <Separator borderColor="border.subtle" />
+          <Text color="fg.muted" fontSize="xs">
+            Adding images to {destination}
+          </Text>
+        </>
+      )}
+    </Stack>
+  );
+};
+
+export const InvokeControl = () => {
+  const routeInput = useActiveProjectSelector(selectInvocationRouteInput);
+  const dispatch = useWorkbenchDispatch();
+  const store = useWorkbenchStore();
+  const backendConnectionStatus = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status);
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const modelsStatus = useModelsSelector((snapshot) => snapshot.status);
+  const availabilityModels = modelsStatus === 'loaded' ? models : undefined;
+  const { invocation } = routeInput;
+
+  // Project-graph route validation reads the invocation templates imperatively;
+  // subscribing here keeps the resolved route live while they load.
+  useInvocationTemplatesSelector((snapshot) => snapshot.status);
+
+  const resolvedRoute = resolveInvocationRouteInput(routeInput, 'global', routeInput.invocation, availabilityModels);
+  const isLocked = invocation.sourceLocked || invocation.destinationLocked;
+  const isConnected = backendConnectionStatus === 'connected';
+
+  const blockingReasons = useMemo(
+    () => [...(isConnected ? [] : ['The backend is disconnected.']), ...resolvedRoute.validationReasons],
+    [isConnected, resolvedRoute.validationReasons]
+  );
+  const isValid = isInvocationRouteValid(resolvedRoute) && isConnected;
+  const routeLabel = isValid ? formatRoute(resolvedRoute) : (blockingReasons[0] ?? formatRoute(resolvedRoute));
+  const modelsRef = useRef(availabilityModels);
+
+  modelsRef.current = availabilityModels;
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  const onInvoke = useCallback(() => {
+    flushGenerateDrafts();
+    const snapshot = store.getSnapshot();
+    const postFlushRoute = resolveInvocationRoute(
+      snapshot.activeProject,
+      'global',
+      snapshot.activeProject.invocation,
+      modelsRef.current
+    );
+
+    if (!isInvocationRouteValid(postFlushRoute) || snapshot.state.backendConnection.status !== 'connected') {
+      return;
+    }
+
+    submitResolvedInvocation({
+      dispatch,
+      models: modelsRef.current,
+      prepareCanvasInvocation,
+      project: snapshot.activeProject,
+      route: postFlushRoute,
+    });
+  }, [dispatch, store]);
+  const tooltipContent = useMemo(
+    () => (
+      <InvokeTooltipContent
+        blockingReasons={blockingReasons}
+        generateValues={routeInput.generateValues}
+        invocation={invocation}
+        isValid={isValid}
+      />
+    ),
+    [blockingReasons, invocation, isValid, routeInput.generateValues]
+  );
+  const handleSourceChange = useCallback(
+    (event: { value: string }) =>
+      dispatch({ sourceId: event.value as InvocationSourceId, type: 'setInvocationSource' }),
+    [dispatch]
+  );
+  const handleDestinationChange = useCallback(
+    (event: { value: string }) =>
+      dispatch({ destination: event.value as ResultDestination, type: 'setInvocationDestination' }),
+    [dispatch]
+  );
+  const handleToggleSourceLock = useCallback(() => dispatch({ type: 'toggleSourceLock' }), [dispatch]);
+  const handleToggleDestinationLock = useCallback(() => dispatch({ type: 'toggleDestinationLock' }), [dispatch]);
+
+  return (
+    <Flex>
+      <Menu.Root positioning={MENU_POSITIONING}>
+        <Group attached>
+          <Tooltip content={tooltipContent} contentProps={TOOLTIP_CONTENT_PROPS} openDelay={200} showArrow>
+            <Button
+              aria-disabled={!isValid}
+              colorPalette="brand"
+              cursor={isValid ? undefined : 'not-allowed'}
+              opacity={isValid ? undefined : 0.6}
+              size="sm"
+              roundedEnd="none"
+              onClick={onInvoke}
+              w={CONTROL_WIDTH}
+              minW="0"
+              justifyContent="start"
+            >
+              <Icon as={SparklesIcon} boxSize="4" flexShrink={0} />
+              <VStack align="start" gap="0" minW="0">
+                <Text fontSize="sm" fontWeight="700" lineHeight="1">
+                  Invoke
+                </Text>
+                <HStack gap="1" maxW="full" mb="-0.5">
+                  <Text fontSize="0.58rem" lineHeight="1.1" opacity="0.85" truncate>
+                    {routeLabel}
+                  </Text>
+                  {isLocked ? <Icon as={LockKeyholeIcon} boxSize="2.5" flexShrink={0} /> : null}
+                </HStack>
+              </VStack>
+            </Button>
+          </Tooltip>
+          <Menu.Trigger asChild>
+            <IconButton colorPalette="brand" size="sm" minW="0" w="7">
+              <ChevronDownIcon />
+            </IconButton>
+          </Menu.Trigger>
+        </Group>
+        <Portal>
+          <Menu.Positioner>
+            <Menu.Content minW="14rem">
+              <Menu.RadioItemGroup value={invocation.sourceId} onValueChange={handleSourceChange}>
+                <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                  Source
+                </Menu.ItemGroupLabel>
+                {invocationSources.map((source) => (
+                  <Menu.RadioItem
+                    key={source.id}
+                    value={source.id}
+                    disabled={!source.available}
+                    _disabled={DISABLED_PROPS}
+                  >
+                    <Menu.ItemText>{source.label}</Menu.ItemText>
+                    {source.available ? null : (
+                      <Text color="fg.subtle" fontSize="2xs" ms="auto">
+                        Soon
+                      </Text>
+                    )}
+                    <Menu.ItemIndicator>
+                      <Icon as={CheckIcon} boxSize="3" />
+                    </Menu.ItemIndicator>
+                  </Menu.RadioItem>
+                ))}
+              </Menu.RadioItemGroup>
+
+              <Menu.Separator borderColor="border.subtle" />
+
+              <Menu.RadioItemGroup value={invocation.destination} onValueChange={handleDestinationChange}>
+                <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                  Destination
+                </Menu.ItemGroupLabel>
+                {resultDestinations.map((destination) => (
+                  <Menu.RadioItem key={destination.id} value={destination.id}>
+                    <Menu.ItemText>{destination.label}</Menu.ItemText>
+                    <Menu.ItemIndicator>
+                      <Icon as={CheckIcon} boxSize="3" />
+                    </Menu.ItemIndicator>
+                  </Menu.RadioItem>
+                ))}
+              </Menu.RadioItemGroup>
+
+              <Menu.Separator borderColor="border.subtle" />
+
+              <Menu.Item value="lock-source" closeOnSelect={false} onClick={handleToggleSourceLock}>
+                <Icon as={LockKeyholeIcon} boxSize="3" opacity={invocation.sourceLocked ? 1 : 0.35} />
+                <Menu.ItemText>{invocation.sourceLocked ? 'Unlock source' : 'Lock source'}</Menu.ItemText>
+              </Menu.Item>
+              <Menu.Item value="lock-destination" closeOnSelect={false} onClick={handleToggleDestinationLock}>
+                <Icon as={LockKeyholeIcon} boxSize="3" opacity={invocation.destinationLocked ? 1 : 0.35} />
+                <Menu.ItemText>
+                  {invocation.destinationLocked ? 'Unlock destination' : 'Lock destination'}
+                </Menu.ItemText>
+              </Menu.Item>
+            </Menu.Content>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/LayoutPresetMenu.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/LayoutPresetMenu.tsx
new file mode 100644
index 00000000000..124818bc334
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/LayoutPresetMenu.tsx
@@ -0,0 +1,367 @@
+import type { LayoutPreset } from '@workbench/types';
+import type { MouseEvent } from 'react';
+
+import { HStack, Icon, Menu, Portal, Stack, Text } from '@chakra-ui/react';
+import { Button, ConfirmDialog, IconButton, MenuContent, RenameDialog } from '@workbench/components/ui';
+import { layoutPresets } from '@workbench/layoutPresets';
+import { areLayoutPresetSnapshotsEqual, createLayoutPresetSnapshot } from '@workbench/layoutPresetSnapshots';
+import { useActiveProjectSelector, useWorkbenchDispatch, useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { CheckIcon, ChevronDownIcon, EllipsisVerticalIcon, PencilIcon, PlusIcon, Trash2Icon } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+
+interface PresetActionTarget {
+  preset: LayoutPreset;
+  x?: number;
+  y?: number;
+}
+
+const getDefaultCustomPresetName = (presets: LayoutPreset[]): string => `Custom layout ${presets.length + 1}`;
+
+const createCustomPresetId = (): string =>
+  `custom-layout-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const MENU_POSITIONING = { placement: 'bottom-end' } as const;
+const TRIGGER_HOVER_PROPS = { bg: 'bg.muted' };
+const DISABLED_PROPS = { opacity: 0.45 };
+
+/** Global layout preset registry surfaced as a menu. */
+export const LayoutPresetMenu = () => {
+  const activeLayoutSnapshot = useActiveProjectSelector(createLayoutPresetSnapshot, areLayoutPresetSnapshotsEqual);
+  const customPresets = useWorkbenchSelector((snapshot) => snapshot.state.account.customLayoutPresets ?? []);
+  const dispatch = useWorkbenchDispatch();
+  const [isAddOpen, setIsAddOpen] = useState(false);
+  const [renameTarget, setRenameTarget] = useState<LayoutPreset | null>(null);
+  const [deleteTarget, setDeleteTarget] = useState<LayoutPreset | null>(null);
+  const [actionTarget, setActionTarget] = useState<PresetActionTarget | null>(null);
+  const allPresets = useMemo(() => [...layoutPresets, ...customPresets], [customPresets]);
+  const matchingPreset = allPresets.find((preset) =>
+    areLayoutPresetSnapshotsEqual(activeLayoutSnapshot, preset.snapshot)
+  );
+  const canAddCurrentLayout = !matchingPreset;
+  const triggerLabel = matchingPreset?.label ?? 'Custom';
+
+  const addPreset = useCallback(
+    (label: string) => {
+      dispatch({ label, presetId: createCustomPresetId(), type: 'addLayoutPreset' });
+    },
+    [dispatch]
+  );
+
+  const renamePreset = useCallback(
+    (preset: LayoutPreset, label: string) => {
+      dispatch({ label, presetId: preset.id, type: 'renameLayoutPreset' });
+    },
+    [dispatch]
+  );
+
+  const deletePreset = useCallback(
+    (preset: LayoutPreset) => {
+      dispatch({ presetId: preset.id, type: 'deleteLayoutPreset' });
+    },
+    [dispatch]
+  );
+  const applyPreset = useCallback(
+    (preset: LayoutPreset) => dispatch({ presetId: preset.id, type: 'applyPreset' }),
+    [dispatch]
+  );
+  const openActionMenu = useCallback((preset: LayoutPreset, event: MouseEvent<HTMLElement>) => {
+    event.preventDefault();
+    event.stopPropagation();
+    setActionTarget({ preset, x: event.clientX, y: event.clientY });
+  }, []);
+  const handleAddCurrentLayout = useCallback(() => {
+    if (canAddCurrentLayout) {
+      setIsAddOpen(true);
+    }
+  }, [canAddCurrentLayout]);
+  const closeActionMenu = useCallback(() => setActionTarget(null), []);
+  const openDeleteDialog = useCallback((preset: LayoutPreset) => setDeleteTarget(preset), []);
+  const openRenameDialog = useCallback((preset: LayoutPreset) => setRenameTarget(preset), []);
+  const closeAddDialog = useCallback(() => setIsAddOpen(false), []);
+  const closeRenameDialog = useCallback(() => setRenameTarget(null), []);
+  const submitRename = useCallback(
+    (label: string) => {
+      if (renameTarget) {
+        renamePreset(renameTarget, label);
+      }
+    },
+    [renamePreset, renameTarget]
+  );
+  const closeDeleteDialog = useCallback(() => setDeleteTarget(null), []);
+  const confirmDelete = useCallback(() => {
+    if (deleteTarget) {
+      deletePreset(deleteTarget);
+    }
+  }, [deletePreset, deleteTarget]);
+
+  return (
+    <>
+      <Menu.Root positioning={MENU_POSITIONING}>
+        <Menu.Trigger asChild>
+          <Button
+            bg="bg.subtle"
+            borderWidth="1px"
+            borderColor="border.emphasized"
+            color="fg"
+            fontSize="xs"
+            fontWeight="500"
+            justifyContent="space-between"
+            size="xs"
+            variant="outline"
+            w="9rem"
+            _hover={TRIGGER_HOVER_PROPS}
+          >
+            {triggerLabel}
+            <Icon as={ChevronDownIcon} boxSize="3" />
+          </Button>
+        </Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent maxW="20rem" minW="18rem">
+              <PresetGroup
+                label="Built-in presets"
+                matchingPreset={matchingPreset}
+                presets={layoutPresets}
+                onApply={applyPreset}
+              />
+              {customPresets.length ? (
+                <>
+                  <Menu.Separator />
+                  <PresetGroup
+                    isCustom
+                    label="Custom presets"
+                    matchingPreset={matchingPreset}
+                    presets={customPresets}
+                    onAction={openActionMenu}
+                    onApply={applyPreset}
+                    onContextMenu={openActionMenu}
+                  />
+                </>
+              ) : null}
+              <Menu.Separator />
+              <Menu.Item
+                value="add-current-layout"
+                disabled={!canAddCurrentLayout}
+                _disabled={DISABLED_PROPS}
+                onClick={handleAddCurrentLayout}
+              >
+                <Icon as={PlusIcon} boxSize="3.5" />
+                <Menu.ItemText>Add current layout...</Menu.ItemText>
+                {!canAddCurrentLayout ? (
+                  <Text color="fg.subtle" fontSize="2xs" ms="auto">
+                    Saved
+                  </Text>
+                ) : null}
+              </Menu.Item>
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <PresetActionMenu
+        target={actionTarget}
+        onClose={closeActionMenu}
+        onDelete={openDeleteDialog}
+        onRename={openRenameDialog}
+      />
+      <RenameDialog
+        initialName={getDefaultCustomPresetName(customPresets)}
+        isOpen={isAddOpen}
+        label="Preset name"
+        submitLabel="Add preset"
+        submitUnchanged
+        title="Add layout preset"
+        onClose={closeAddDialog}
+        onSubmit={addPreset}
+      />
+      {renameTarget ? (
+        <RenameDialog
+          initialName={renameTarget.label}
+          isOpen={renameTarget !== null}
+          label="Preset name"
+          title="Rename layout preset"
+          onClose={closeRenameDialog}
+          onSubmit={submitRename}
+        />
+      ) : null}
+      <ConfirmDialog
+        body={`Delete "${deleteTarget?.label ?? 'this layout preset'}"? This only removes the saved preset.`}
+        confirmLabel="Delete preset"
+        isOpen={deleteTarget !== null}
+        title="Delete layout preset?"
+        onClose={closeDeleteDialog}
+        onConfirm={confirmDelete}
+      />
+    </>
+  );
+};
+
+const PresetGroup = ({
+  isCustom = false,
+  label,
+  matchingPreset,
+  onAction,
+  onApply,
+  onContextMenu,
+  presets,
+}: {
+  isCustom?: boolean;
+  label: string;
+  matchingPreset?: LayoutPreset;
+  onAction?: (preset: LayoutPreset, event: MouseEvent<HTMLElement>) => void;
+  onApply: (preset: LayoutPreset) => void;
+  onContextMenu?: (preset: LayoutPreset, event: MouseEvent<HTMLElement>) => void;
+  presets: LayoutPreset[];
+}) => (
+  <Menu.ItemGroup>
+    <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+      {label}
+    </Menu.ItemGroupLabel>
+    {presets.map((preset) => (
+      <PresetMenuItem
+        key={preset.id}
+        isCustom={isCustom}
+        isSelected={preset.id === matchingPreset?.id}
+        preset={preset}
+        onAction={onAction}
+        onApply={onApply}
+        onContextMenu={onContextMenu}
+      />
+    ))}
+  </Menu.ItemGroup>
+);
+
+const PresetMenuItem = ({
+  isCustom,
+  isSelected,
+  onAction,
+  onApply,
+  onContextMenu,
+  preset,
+}: {
+  isCustom: boolean;
+  isSelected: boolean;
+  preset: LayoutPreset;
+  onAction?: (preset: LayoutPreset, event: MouseEvent<HTMLElement>) => void;
+  onApply: (preset: LayoutPreset) => void;
+  onContextMenu?: (preset: LayoutPreset, event: MouseEvent<HTMLElement>) => void;
+}) => {
+  const handleApply = useCallback(() => onApply(preset), [onApply, preset]);
+  const handleContextMenu = useCallback(
+    (event: MouseEvent<HTMLElement>) => onContextMenu?.(preset, event),
+    [onContextMenu, preset]
+  );
+  const handleAction = useCallback((event: MouseEvent<HTMLElement>) => onAction?.(preset, event), [onAction, preset]);
+
+  return (
+    <Menu.Item value={preset.id} onClick={handleApply} onContextMenu={handleContextMenu}>
+      <Stack gap="0" flex="1" minW="0">
+        <Text fontSize="xs" fontWeight="600">
+          {preset.label}
+        </Text>
+      </Stack>
+      <HStack flexShrink={0} gap="1">
+        {isSelected ? <Icon as={CheckIcon} boxSize="3" color="accent.solid" /> : null}
+        {isCustom ? (
+          <IconButton
+            aria-label={`Actions for ${preset.label}`}
+            color="fg.muted"
+            size="2xs"
+            variant="ghost"
+            onClick={handleAction}
+          >
+            <EllipsisVerticalIcon />
+          </IconButton>
+        ) : null}
+      </HStack>
+    </Menu.Item>
+  );
+};
+
+const PresetActionMenu = ({
+  onClose,
+  onDelete,
+  onRename,
+  target,
+}: {
+  target: PresetActionTarget | null;
+  onClose: () => void;
+  onDelete: (preset: LayoutPreset) => void;
+  onRename: (preset: LayoutPreset) => void;
+}) => {
+  const positioning = useMemo(
+    () =>
+      target?.x !== undefined && target.y !== undefined
+        ? {
+            getAnchorRect: () => ({ height: 1, width: 1, x: target.x as number, y: target.y as number }),
+            placement: 'bottom-start' as const,
+          }
+        : MENU_POSITIONING,
+    [target]
+  );
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  return (
+    <Menu.Root
+      key={target?.preset.id ?? 'closed'}
+      lazyMount
+      open={target !== null}
+      positioning={positioning}
+      unmountOnExit
+      onOpenChange={handleOpenChange}
+    >
+      <Portal>
+        <Menu.Positioner>
+          {target ? (
+            <MenuContent minW="12rem">
+              <PresetActionMenuItem action="rename" preset={target.preset} onDelete={onDelete} onRename={onRename} />
+              <PresetActionMenuItem action="delete" preset={target.preset} onDelete={onDelete} onRename={onRename} />
+            </MenuContent>
+          ) : null}
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
+
+const PresetActionMenuItem = ({
+  action,
+  onDelete,
+  onRename,
+  preset,
+}: {
+  action: 'delete' | 'rename';
+  preset: LayoutPreset;
+  onDelete: (preset: LayoutPreset) => void;
+  onRename: (preset: LayoutPreset) => void;
+}) => {
+  const handleClick = useCallback(() => {
+    if (action === 'rename') {
+      onRename(preset);
+    } else {
+      onDelete(preset);
+    }
+  }, [action, onDelete, onRename, preset]);
+
+  if (action === 'rename') {
+    return (
+      <Menu.Item value="rename-preset" onClick={handleClick}>
+        <Icon as={PencilIcon} boxSize="3.5" />
+        <Menu.ItemText>Rename...</Menu.ItemText>
+      </Menu.Item>
+    );
+  }
+
+  return (
+    <Menu.Item color="fg.error" value="delete-preset" onClick={handleClick}>
+      <Icon as={Trash2Icon} boxSize="3.5" />
+      <Menu.ItemText>Delete...</Menu.ItemText>
+    </Menu.Item>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/ModelManagerButton.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/ModelManagerButton.tsx
new file mode 100644
index 00000000000..3cab1806beb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/ModelManagerButton.tsx
@@ -0,0 +1,18 @@
+import { Link } from '@tanstack/react-router';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { BoxIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+export const ModelManagerButton = () => {
+  const { t } = useTranslation();
+
+  return (
+    <Tooltip content={t('models.manager')} showArrow>
+      <IconButton aria-label={t('models.manager')} asChild size="sm" variant="ghost">
+        <Link to="/models">
+          <BoxIcon />
+        </Link>
+      </IconButton>
+    </Tooltip>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/NodeManagerButton.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/NodeManagerButton.tsx
new file mode 100644
index 00000000000..cfdd52b52da
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/NodeManagerButton.tsx
@@ -0,0 +1,19 @@
+import { Icon } from '@chakra-ui/react';
+import { Link } from '@tanstack/react-router';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { BlocksIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+export const NodesManagerButton = () => {
+  const { t } = useTranslation();
+
+  return (
+    <Tooltip content={t('nodes.manager')} showArrow>
+      <IconButton aria-label={t('nodes.manager')} asChild size="sm" variant="ghost">
+        <Link to="/nodes">
+          <Icon as={BlocksIcon} />
+        </Link>
+      </IconButton>
+    </Tooltip>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/QueueActions.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/QueueActions.tsx
new file mode 100644
index 00000000000..338a3981e8c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/QueueActions.tsx
@@ -0,0 +1,52 @@
+import { Group, Menu, Portal } from '@chakra-ui/react';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { QueueMenuItems, useQueueMenuActions } from '@workbench/widgets/queue/queueMenuActions';
+import { ChevronDownIcon, XIcon } from 'lucide-react';
+
+/** Queue cancel cluster and processor actions. */
+export const QueueActions = () => {
+  const actions = useQueueMenuActions();
+  const cancelCurrent = actions[0];
+
+  return (
+    <Menu.Root>
+      <Group attached>
+        <Tooltip content="Cancel current item" showArrow>
+          <IconButton
+            aria-label="Cancel current queue item"
+            disabled={cancelCurrent?.disabled}
+            variant="outline"
+            size="sm"
+            roundedEnd="none"
+            borderColor="border.subtle"
+            onClick={cancelCurrent?.onClick}
+          >
+            <XIcon />
+          </IconButton>
+        </Tooltip>
+        <Menu.Trigger asChild>
+          <IconButton
+            aria-label="Queue actions"
+            variant="outline"
+            size="sm"
+            roundedStart="none"
+            borderStartWidth="0"
+            aspectRatio="unset"
+            minW="0"
+            w="6"
+            borderColor="border.subtle"
+          >
+            <ChevronDownIcon />
+          </IconButton>
+        </Menu.Trigger>
+      </Group>
+      <Portal>
+        <Menu.Positioner>
+          <Menu.Content>
+            <QueueMenuItems actions={actions} />
+          </Menu.Content>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/QueueInfo.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/QueueInfo.tsx
new file mode 100644
index 00000000000..bc6120d1456
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/QueueInfo.tsx
@@ -0,0 +1,218 @@
+/* eslint-disable react/react-compiler */
+import type { QueueItem } from '@workbench/types';
+
+import { Badge, HStack, Icon, Progress, Stack, Text } from '@chakra-ui/react';
+import { useModelLoads, type ModelLoadInfo } from '@workbench/backend/modelLoadStore';
+import { useQueueItemProgress, type QueueItemProgress } from '@workbench/backend/progressStore';
+import { Button, Tooltip } from '@workbench/components/ui';
+import { getDestinationLabel, getSourceLabel } from '@workbench/invocation';
+import { getQueueItemExpectedImageCount, getQueueProgressBarState, getQueueSummary } from '@workbench/queueSummary';
+import { useOpenWorkbenchWidget } from '@workbench/useOpenWorkbenchWidget';
+import { useActiveProjectSelector, useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { ListOrderedIcon } from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+
+const TOOLTIP_CONTENT_PROPS = { maxW: '22rem', p: '0' };
+
+export const QueueInfo = () => {
+  const queueItems = useActiveProjectSelector((project) => project.queue.items);
+  const backendConnectionStatus = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status);
+  const modelLoads = useModelLoads();
+  const openWorkbenchWidget = useOpenWorkbenchWidget();
+  const baseSummary = getQueueSummary(queueItems);
+  const runningProgress = useQueueItemProgress(baseSummary.runningQueueItemId ?? '');
+  const summary = getQueueSummary(queueItems, runningProgress);
+  const runningItem = summary.runningQueueItemId
+    ? queueItems.find((item) => item.id === summary.runningQueueItemId)
+    : undefined;
+
+  const progressState = getQueueProgressBarState({
+    isConnected: backendConnectionStatus === 'connected',
+    isRunning: Boolean(runningItem),
+    loadingModelsCount: modelLoads.length,
+    progress: runningProgress,
+  });
+
+  const tooltipContent = useMemo(
+    () => (
+      <QueueInfoTooltip
+        item={runningItem}
+        modelLoads={modelLoads}
+        progress={runningProgress}
+        total={summary.total}
+        current={summary.current}
+      />
+    ),
+    [modelLoads, runningItem, runningProgress, summary]
+  );
+
+  const handleOpenQueue = useCallback(() => openWorkbenchWidget('queue'), [openWorkbenchWidget]);
+
+  return (
+    <Tooltip content={tooltipContent} contentProps={TOOLTIP_CONTENT_PROPS} openDelay={200} showArrow>
+      <Button
+        aria-label={`Queue progress ${summary.current} of ${summary.total}`}
+        variant="outline"
+        h="9"
+        borderColor="border.subtle"
+        fontSize="xs"
+        fontWeight="700"
+        gap="1"
+        overflow="hidden"
+        position="relative"
+        px="2"
+        onClick={handleOpenQueue}
+      >
+        <Icon as={ListOrderedIcon} boxSize="4" flexShrink="0" />
+        {summary.current}/{summary.total}
+        <QueueBadgeProgressBar state={progressState} />
+      </Button>
+    </Tooltip>
+  );
+};
+
+const QueueBadgeProgressBar = ({ state }: { state: ReturnType<typeof getQueueProgressBarState> }) => {
+  const isIdle = state.kind === 'idle';
+
+  return (
+    <Progress.Root
+      aria-label={isIdle ? 'Invoke progress idle' : 'Invoke progress'}
+      bottom="0"
+      colorPalette="accent"
+      h={1}
+      insetInline={0}
+      max={1}
+      pointerEvents="none"
+      position="absolute"
+      value={state.value}
+      visibility={state.kind !== 'idle' ? 'visible' : 'hidden'}
+    >
+      <Progress.Track bg={isIdle ? 'border.subtle' : 'bg.emphasized'} h="full">
+        <Progress.Range bg="accent.solid" />
+      </Progress.Track>
+    </Progress.Root>
+  );
+};
+
+const QueueInfoTooltip = ({
+  current,
+  item,
+  modelLoads,
+  progress,
+  total,
+}: {
+  current: number;
+  item?: QueueItem;
+  modelLoads: ModelLoadInfo[];
+  progress: QueueItemProgress | null;
+  total: number;
+}) => {
+  if (modelLoads.length > 0 && total === 0) {
+    return <ModelLoadsTooltipContent modelLoads={modelLoads} />;
+  }
+
+  if (total === 0) {
+    return (
+      <Stack gap="1" p="3">
+        <Text fontSize="xs" fontWeight="800">
+          Queue idle
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          No active or pending generation batches.
+        </Text>
+      </Stack>
+    );
+  }
+
+  if (!item) {
+    return (
+      <Stack gap="2" p="3">
+        <Text fontSize="xs" fontWeight="800">
+          {modelLoads.length ? 'Loading models' : 'Waiting to start'}
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          {total} image{total === 1 ? '' : 's'} queued.
+        </Text>
+        {modelLoads.length ? <ModelLoadList modelLoads={modelLoads} /> : null}
+      </Stack>
+    );
+  }
+
+  const generateValues = item.snapshot.widgetStates.generate.values;
+  const prompt = typeof generateValues.positivePrompt === 'string' ? generateValues.positivePrompt.trim() : '';
+  const expectedCount = getQueueItemExpectedImageCount(item);
+  const activeItemIndex = Math.min(expectedCount, Math.max(1, progress?.activeItemIndex ?? 1));
+  const activeBackendItemId = item.backendItemIds?.[activeItemIndex - 1];
+  const progressLabel = modelLoads.length
+    ? `Loading ${modelLoads.length} model${modelLoads.length === 1 ? '' : 's'}.`
+    : progress?.message?.trim() || 'Backend accepted batch; waiting for progress event.';
+
+  return (
+    <Stack gap="2" p="3" minW="18rem">
+      <HStack justify="space-between" gap="3">
+        <Text fontSize="xs" fontWeight="800">
+          Loading image {current}/{total}
+        </Text>
+        <Badge colorPalette="blue" fontSize="2xs">
+          {item.status}
+        </Badge>
+      </HStack>
+      <Stack gap="1">
+        <Text color="fg.subtle" fontSize="2xs">
+          {progressLabel}
+        </Text>
+        {modelLoads.length ? <ModelLoadList modelLoads={modelLoads} /> : null}
+        {progress?.percentage !== null && progress?.percentage !== undefined ? (
+          <Progress.Root aria-label="Current image progress" max={1} size="xs" value={progress.percentage}>
+            <Progress.Track>
+              <Progress.Range />
+            </Progress.Track>
+          </Progress.Root>
+        ) : null}
+      </Stack>
+      <Stack gap="1" color="fg.subtle" fontSize="2xs">
+        <Text>
+          Batch image {activeItemIndex}/{expectedCount}
+          {activeBackendItemId !== undefined ? ` · backend item ${activeBackendItemId}` : ''}
+        </Text>
+        <Text fontFamily="mono" truncate>
+          Queue item {item.id}
+        </Text>
+        {item.backendBatchId ? (
+          <Text fontFamily="mono" truncate>
+            Backend batch {item.backendBatchId}
+          </Text>
+        ) : null}
+        <Text truncate>
+          {getSourceLabel(item.snapshot.sourceId)} to {getDestinationLabel(item.snapshot.destination)} ·{' '}
+          {item.snapshot.graph.label || item.snapshot.graph.id}
+        </Text>
+      </Stack>
+      {prompt ? (
+        <Text color="fg.muted" fontSize="2xs" lineClamp={2}>
+          {prompt}
+        </Text>
+      ) : null}
+    </Stack>
+  );
+};
+
+const ModelLoadsTooltipContent = ({ modelLoads }: { modelLoads: ModelLoadInfo[] }) => (
+  <Stack gap="2" p="3" minW="18rem">
+    <Text fontSize="xs" fontWeight="800">
+      Loading {modelLoads.length} model{modelLoads.length === 1 ? '' : 's'}
+    </Text>
+    <ModelLoadList modelLoads={modelLoads} />
+  </Stack>
+);
+
+const ModelLoadList = ({ modelLoads }: { modelLoads: ModelLoadInfo[] }) => (
+  <Stack gap="0.5" color="fg.muted" fontSize="2xs">
+    {modelLoads.slice(0, 3).map((modelLoad, index) => (
+      <Text key={`${modelLoad.label}:${index}`} truncate>
+        {modelLoad.label}
+      </Text>
+    ))}
+    {modelLoads.length > 3 ? <Text>{modelLoads.length - 3} more...</Text> : null}
+  </Stack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/TopBar.tsx b/invokeai/frontend/webv2/src/workbench/shell/topbar/TopBar.tsx
new file mode 100644
index 00000000000..ada53902ff3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/TopBar.tsx
@@ -0,0 +1,64 @@
+import { Flex, HStack, Separator } from '@chakra-ui/react';
+import { Link } from '@tanstack/react-router';
+import { useCapabilities } from '@workbench/auth/capabilities';
+import { AccountMenu } from '@workbench/auth/components/AccountMenu';
+import { ProjectTabs } from '@workbench/projects/components';
+
+import { InvokeMark } from '@/workbench/components/InvokeMark';
+import { SettingsButton } from '@/workbench/settings';
+
+import { BatchCountField } from './BatchCountField';
+import { InvokeControl } from './InvokeControl';
+import { LayoutPresetMenu } from './LayoutPresetMenu';
+import { ModelManagerButton } from './ModelManagerButton';
+import { NodesManagerButton } from './NodeManagerButton';
+import { QueueActions } from './QueueActions';
+import { QueueInfo } from './QueueInfo';
+
+const HOME_LINK_STYLE = {
+  alignItems: 'center',
+  aspectRatio: '1/1',
+  display: 'flex',
+  flexShrink: 0,
+  height: '100%',
+  justifyContent: 'center',
+};
+
+/** Workbench top bar: brand, global Invoke command cluster, project tabs, layout + account controls. */
+export const TopBar = () => {
+  const { canManageModels, canManageNodes } = useCapabilities();
+
+  return (
+    <Flex
+      align="center"
+      as="header"
+      bg="bg.subtle"
+      borderBottomWidth="1px"
+      borderColor="border.subtle"
+      flexShrink={0}
+      gap="2"
+      h="12"
+      ps="0.5"
+      pe="1.5"
+      w="full"
+    >
+      <Link to="/" style={HOME_LINK_STYLE}>
+        <InvokeMark size={20} />
+      </Link>
+      <Separator orientation="vertical" h={5} ms="-2" />
+      <InvokeControl />
+      <BatchCountField />
+      <QueueInfo />
+      <QueueActions />
+      <Separator orientation="vertical" h={5} />
+      <ProjectTabs />
+      <LayoutPresetMenu />
+      <HStack gap="0.5">
+        {canManageNodes ? <NodesManagerButton /> : null}
+        {canManageModels ? <ModelManagerButton /> : null}
+        <SettingsButton />
+      </HStack>
+      <AccountMenu />
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/shell/topbar/index.ts b/invokeai/frontend/webv2/src/workbench/shell/topbar/index.ts
new file mode 100644
index 00000000000..40f2ccdd93d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/shell/topbar/index.ts
@@ -0,0 +1 @@
+export { TopBar } from './TopBar';
diff --git a/invokeai/frontend/webv2/src/workbench/types.ts b/invokeai/frontend/webv2/src/workbench/types.ts
new file mode 100644
index 00000000000..b3d9be0fb3c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/types.ts
@@ -0,0 +1,950 @@
+import type { TFunction } from 'i18next';
+import type { ComponentType, ExoticComponent, JSXElementConstructor, SVGProps } from 'react';
+
+// `generation/types.ts` imports value-less (`import type`) symbols back from this
+// module; both sides are type-only so this doesn't create a runtime cycle.
+import type { GenerateReferenceImage, GenerateWidgetValues } from './generation/types';
+import type { WorkbenchLanguage } from './i18n/languages';
+import type { ProjectGraphState } from './workflows/types';
+
+export type { WorkbenchLanguage } from './i18n/languages';
+
+export type BuiltInLayoutPresetId = 'canvas-default' | 'gallery' | 'workflow' | 'canvas';
+export type LayoutPresetId = BuiltInLayoutPresetId | (string & {});
+
+export type CenterViewId = 'canvas' | 'gallery' | 'preview' | 'workflow';
+
+export type GraphId = string;
+
+export type FirstPartyWidgetTypeId =
+  | 'autosave-status'
+  | 'canvas'
+  | 'diagnostics'
+  | 'gallery'
+  | 'generate'
+  | 'history-controls'
+  | 'layers'
+  | 'notifications'
+  | 'preview'
+  | 'project'
+  | 'queue'
+  | 'server-status'
+  | 'users'
+  | 'version-status'
+  | 'workflow';
+
+export type WidgetTypeId = FirstPartyWidgetTypeId | (string & {});
+export type WidgetInstanceId = string;
+export type WidgetId = WidgetTypeId;
+
+export type WorkbenchRegion = 'left' | 'right' | 'center' | 'bottom' | 'dialog' | 'popover';
+
+export type QueueItemStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+export type ProjectEventType =
+  | 'project-created'
+  | 'layout-updated'
+  | 'invocation-updated'
+  | 'queue-submitted'
+  | 'canvas-layer-accepted'
+  | 'graph-replaced'
+  | 'graph-snapshot-saved';
+
+export interface GraphNodeContract {
+  id: string;
+  type: string;
+  inputs: Record<string, unknown>;
+}
+
+export interface GraphEdgeContract {
+  id: string;
+  sourceNodeId: string;
+  sourceField: string;
+  targetNodeId: string;
+  targetField: string;
+}
+
+export interface GraphContract {
+  id: GraphId;
+  version: 1;
+  label: string;
+  nodes: GraphNodeContract[];
+  edges: GraphEdgeContract[];
+  updatedAt: string;
+  backendGraph?: BackendGraphContract;
+}
+
+export interface BackendInvocationContract {
+  id: string;
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface BackendGraphEdgeContract {
+  source: {
+    node_id: string;
+    field: string;
+  };
+  destination: {
+    node_id: string;
+    field: string;
+  };
+}
+
+export interface BackendGraphContract {
+  id: string;
+  nodes: Record<string, BackendInvocationContract>;
+  edges: BackendGraphEdgeContract[];
+}
+
+export interface WidgetStateContract {
+  id: WidgetTypeId;
+  label: string;
+  version: 1;
+  values: Record<string, unknown>;
+  graphId?: GraphId;
+}
+
+export type WidgetStateMap = Record<string, WidgetStateContract>;
+
+export interface WidgetInstanceContract {
+  id: WidgetInstanceId;
+  typeId: WidgetTypeId;
+  title?: string;
+  state: WidgetStateContract;
+  createdAt: string;
+}
+
+export interface WidgetInstanceRuntimeMeta {
+  id: WidgetInstanceId;
+  typeId: WidgetTypeId;
+  title?: string;
+  createdAt: string;
+}
+
+export interface GraphBearingSurfaceContract {
+  surfaceId: string;
+  widgetId: WidgetId;
+  label: string;
+  sourceId: InvocationSourceId;
+  graphId: GraphId;
+  region: WorkbenchRegion;
+  canSetSource: boolean;
+  canPreviewGraph: boolean;
+}
+
+export interface WidgetViewProps {
+  region: WorkbenchRegion;
+  manifest: WidgetManifest;
+  /** Chrome metadata only. Read reactive widget values through `runtime.state`. */
+  instance: WidgetInstanceRuntimeMeta;
+  runtime: WidgetRuntimeApi;
+  presentation?: 'compact' | 'expanded' | 'tooltip';
+}
+
+export type WidgetView = ComponentType<WidgetViewProps>;
+
+export type WidgetHeaderActions = ComponentType<WidgetViewProps>;
+export type WidgetHeaderMenu = ComponentType<WidgetViewProps>;
+export type WidgetFooter = ComponentType<WidgetViewProps>;
+export type WidgetHost = ComponentType;
+
+export interface WidgetLabelProps {
+  region: WorkbenchRegion;
+  presentation?: 'compact' | 'expanded' | 'tooltip';
+}
+
+export type WidgetLabel = string | ((t: TFunction) => string);
+export type WidgetHeaderLabel = ComponentType<WidgetLabelProps>;
+
+export type WidgetIconComponent =
+  | JSXElementConstructor<SVGProps<SVGSVGElement>>
+  | ExoticComponent<SVGProps<SVGSVGElement>>;
+
+export interface WidgetStateRegistration<State extends Record<string, unknown> = Record<string, unknown>> {
+  version: 1;
+  createInitial: () => State;
+  migrate?: (state: unknown, fromVersion: number) => State;
+  persistence?: 'project' | 'workspace' | 'session' | 'none';
+}
+
+export interface WidgetRuntimeApi<State extends Record<string, unknown> = Record<string, unknown>> {
+  instanceId: WidgetInstanceId;
+  typeId: WidgetTypeId;
+  region: WorkbenchRegion;
+  state: WidgetRuntimeStateApi<State>;
+  diagnostics: WidgetDiagnosticsApi;
+  commands: WidgetCommandApi;
+  hotkeys: WidgetHotkeyApi;
+  menus: WidgetMenuApi;
+  palette: WidgetCommandPaletteApi;
+  search: WidgetSearchApi;
+  toolbars: WidgetToolbarApi;
+  workbench: WidgetWorkbenchApi;
+}
+
+export interface WidgetDiagnosticsApi {
+  logger: (namespace: DeveloperLogNamespace) => {
+    debug: (messageOrContext: string | Record<string, unknown>, message?: string) => void;
+    error: (messageOrContext: string | Record<string, unknown>, message?: string) => void;
+    fatal: (messageOrContext: string | Record<string, unknown>, message?: string) => void;
+    info: (messageOrContext: string | Record<string, unknown>, message?: string) => void;
+    trace: (messageOrContext: string | Record<string, unknown>, message?: string) => void;
+    warn: (messageOrContext: string | Record<string, unknown>, message?: string) => void;
+  };
+}
+
+export interface WidgetRuntimeStateApi<State extends Record<string, unknown> = Record<string, unknown>> {
+  getSnapshot: () => Readonly<State>;
+  useSelector: <Selected>(
+    selector: (state: Readonly<State>) => Selected,
+    isEqual?: (left: Selected, right: Selected) => boolean
+  ) => Selected;
+  patch: (values: Partial<State>) => void;
+  set: (values: State) => void;
+}
+
+export interface WidgetContributionSource {
+  instanceId: WidgetInstanceId;
+  projectId: string;
+  region: WorkbenchRegion;
+  typeId: WidgetTypeId;
+}
+
+export interface WidgetCommandApi {
+  execute: (commandId: string, ...args: unknown[]) => Promise<unknown>;
+  executeForSource: (
+    commandId: string,
+    source: WidgetContributionSource | null,
+    ...args: unknown[]
+  ) => Promise<unknown>;
+  register: (command: WidgetCommandContribution) => () => void;
+}
+
+export interface WidgetCommandContribution {
+  id: string;
+  title: string;
+  handler: (...args: unknown[]) => unknown | Promise<unknown>;
+  source?: WidgetContributionSource;
+}
+
+export interface WidgetHotkeyApi {
+  register: (hotkey: WidgetHotkeyContribution) => () => void;
+}
+
+export interface WidgetHotkeyContribution {
+  id: string;
+  commandId: string;
+  defaultKeys: string[];
+  title: string;
+  description?: string;
+  scope?: 'focused-region' | 'global' | 'instance' | 'widget';
+  source?: WidgetContributionSource;
+  preventDefault?: boolean;
+  allowInEditable?: boolean;
+}
+
+export interface WidgetMenuApi {
+  register: (menu: WidgetMenuContribution) => () => void;
+}
+
+export interface WidgetMenuContribution {
+  id: string;
+  items: Array<{ commandId: string; group?: string }>;
+  source?: WidgetContributionSource;
+}
+
+export interface WidgetCommandPaletteApi {
+  register: (entry: WidgetCommandPaletteContribution) => () => void;
+}
+
+export interface WidgetCommandPaletteContribution {
+  commandId: string;
+  title: string;
+  keywords?: string[];
+}
+
+export interface WidgetSearchApi {
+  registerProvider: (provider: WidgetSearchProvider) => () => void;
+}
+
+export interface WidgetSearchProvider {
+  id: string;
+  label: string;
+  search: (query: string) => Promise<WidgetSearchResult[]> | WidgetSearchResult[];
+}
+
+export interface WidgetSearchResult {
+  id: string;
+  title: string;
+  subtitle?: string;
+  commandId?: string;
+}
+
+export interface WidgetToolbarApi {
+  register: (toolbar: WidgetToolbarContribution) => () => void;
+}
+
+export interface WidgetToolbarContribution {
+  id: string;
+  location: 'center.tabs.trailing' | 'status.left' | 'status.right';
+  items: Array<{
+    commandId: string;
+    icon?: WidgetIconComponent;
+    label?: string;
+  }>;
+}
+
+export interface OpenWorkbenchWidgetOptions {
+  createNew?: boolean;
+  preferredRegions?: ReadonlyArray<WidgetRegion>;
+  requireCenterView?: boolean;
+}
+
+export type WidgetWorkbenchApiResult =
+  | { ok: true; region?: WidgetRegion }
+  | { ok: false; reason: 'unavailable' | 'unsupported' | 'not-found' };
+
+export interface WidgetWorkbenchApi {
+  openWidget: (typeId: WidgetTypeId, options?: OpenWorkbenchWidgetOptions) => WidgetWorkbenchApiResult;
+  revealWidgetInstance: (instanceId: WidgetInstanceId) => WidgetWorkbenchApiResult;
+  closeWidgetInstance: (instanceId: WidgetInstanceId) => WidgetWorkbenchApiResult;
+}
+
+/** Sections of the workbench settings dialog, addressable via `openWorkbenchSettings`. */
+export type SettingsSectionId =
+  | 'appearance'
+  | 'behavior'
+  | 'hotkeys'
+  | 'project'
+  | 'queue'
+  | 'workflow'
+  | 'developer'
+  | 'workspace';
+
+export interface WidgetManifest {
+  /** Widget runtime API contract version. Defaults to 1 during registry normalization. */
+  apiVersion?: 1;
+  id: WidgetTypeId;
+  label: WidgetLabel;
+  headerLabel?: WidgetHeaderLabel;
+  version: 1;
+  allowedRegions: WidgetRegion[];
+  allowMultiple: boolean;
+  icon: WidgetIconComponent;
+  bottomPanel?: 'expandable' | 'tooltip';
+  centerPlacement?: 'toolbar' | 'view';
+  /** Only offered while an admin is signed in to a multi-user backend. */
+  requiresAdmin?: boolean;
+  chrome?: {
+    header?: 'hidden' | 'visible';
+  };
+  view?: WidgetView;
+  /**
+   * Stable singleton UI owned by the widget but not by any widget instance.
+   * Use for dialogs, file inputs, and other portals driven by widget-level
+   * stores. Mounted once under WorkbenchProvider, independent of widget chrome.
+   */
+  host?: WidgetHost;
+  headerActions?: WidgetHeaderActions;
+  /**
+   * Extra entries for the widget's shared header actions menu. Rendered inside
+   * the same menu as the universal graph actions, so widgets extend the frame
+   * menu instead of stacking their own. Render `Menu.Item`/`Menu.ItemGroup`
+   * children only; use `host` for stable dialogs or file inputs.
+   */
+  headerMenu?: WidgetHeaderMenu;
+  /** When set, the frame header shows a gear that opens this settings dialog section. */
+  settingsSection?: SettingsSectionId;
+  footer?: WidgetFooter;
+  state?: WidgetStateRegistration;
+  graphBearing?: {
+    sourceId: InvocationSourceId;
+    defaultGraphId: GraphId;
+    surfaces: WorkbenchRegion[];
+  };
+  failurePolicy: {
+    onRegistrationFailure: 'disable' | 'hide';
+    isolateRenderFailure: boolean;
+  };
+}
+
+export interface NormalizedWidgetManifest extends Omit<WidgetManifest, 'apiVersion' | 'state'> {
+  apiVersion: 1;
+  state: WidgetStateRegistration;
+}
+
+export interface RegisteredWidget {
+  manifest: NormalizedWidgetManifest;
+  status: 'enabled' | 'disabled' | 'hidden';
+  failure?: WidgetFailure;
+}
+
+export interface WidgetFailure {
+  widgetId: WidgetTypeId;
+  message: string;
+  details: string;
+  occurredAt: string;
+}
+
+export interface GeneratedImageContract {
+  imageName: string;
+  imageUrl: string;
+  thumbnailUrl: string;
+  width: number;
+  height: number;
+  queuedAt: string;
+  sourceQueueItemId: string;
+}
+
+export interface CanvasPlacementContract {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  opacity: number;
+}
+
+export interface CanvasStagingCandidateContract extends GeneratedImageContract {
+  placement: CanvasPlacementContract;
+  sourceBackendItemId?: number;
+}
+
+export interface CanvasRasterLayerContract extends GeneratedImageContract {
+  id: string;
+  acceptedAt: string;
+  label: string;
+  placement: CanvasPlacementContract;
+}
+
+export interface CanvasDocumentContract {
+  version: 1;
+  width: number;
+  height: number;
+  layers: CanvasRasterLayerContract[];
+}
+
+/** @deprecated legacy v1 shape, superseded by {@link CanvasStagingAreaContractV2}. Extracted so v1 and v2 canvas state can share its structure. */
+export interface CanvasStagingAreaContract {
+  sourceQueueItemId?: string;
+  selectedLayerId?: string;
+  pendingImageIds: string[];
+  pendingImages: CanvasStagingCandidateContract[];
+  selectedImageIndex: number;
+  isVisible: boolean;
+  areThumbnailsVisible: boolean;
+}
+
+/** @deprecated legacy v1 shape, superseded by {@link CanvasStateContractV2}. Kept for migration input typing and the still-v1-shaped staging area. */
+export interface CanvasStateContract {
+  version: 1;
+  document: CanvasDocumentContract;
+  stagingArea: CanvasStagingAreaContract;
+}
+
+// ---------------------------------------------------------------------------
+// Canvas v2 document contracts
+//
+// The canvas document is being rebuilt as a full photo editor: a layer stack
+// supporting raster, control, regional-guidance, and inpaint-mask layers, each
+// with its own transform/opacity/blend-mode. `CanvasStateContract` (v1) only
+// ever produced single-image raster layers positioned by `placement`; v2
+// layers are positioned by `transform` and reference bitmaps by `imageName`
+// (via `CanvasImageRef`) rather than by resolved URLs, since URLs are
+// ephemeral/backend-derived while the document is persisted. The staging
+// area (pending queue results awaiting placement onto the canvas) keeps its
+// v1 shape unchanged — only the accepted document evolves.
+// ---------------------------------------------------------------------------
+
+export type CanvasBlendMode =
+  | 'normal'
+  | 'multiply'
+  | 'screen'
+  | 'overlay'
+  | 'darken'
+  | 'lighten'
+  | 'color-dodge'
+  | 'color-burn'
+  | 'hard-light'
+  | 'soft-light'
+  | 'difference'
+  | 'exclusion'
+  | 'hue'
+  | 'saturation'
+  | 'color'
+  | 'luminosity';
+
+/** A reference to a persisted image asset by name, not by resolved URL. */
+export interface CanvasImageRef {
+  imageName: string;
+  width: number;
+  height: number;
+  contentHash?: string;
+}
+
+export type CanvasLayerSourceContract =
+  | {
+      type: 'paint';
+      bitmap: CanvasImageRef | null;
+      /**
+       * The layer-local origin of `bitmap`'s top-left pixel. Paint layers are
+       * content-sized: the persisted bitmap covers only the painted region, and
+       * this offset records where that region sits in the layer's local space
+       * (it can be negative). Absent (or `{ x: 0, y: 0 }`) for legacy documents
+       * whose paint bitmaps were document-sized at the origin — they load
+       * identically.
+       */
+      offset?: { x: number; y: number };
+    }
+  | { type: 'image'; image: CanvasImageRef }
+  | {
+      type: 'text';
+      content: string;
+      fontFamily: string;
+      fontSize: number;
+      fontWeight: number;
+      lineHeight: number;
+      align: 'left' | 'center' | 'right';
+      color: string;
+    }
+  | {
+      type: 'shape';
+      kind: 'rect' | 'ellipse' | 'polygon';
+      points?: { x: number; y: number }[];
+      width: number;
+      height: number;
+      fill: string | null;
+      stroke: string | null;
+      strokeWidth: number;
+    }
+  | {
+      type: 'gradient';
+      kind: 'linear' | 'radial';
+      angle: number;
+      stops: { offset: number; color: string }[];
+      /**
+       * The gradient's explicit content extent (layer-local pixels). Gradient
+       * layers are content-sized like every other layer: the extent is set at
+       * creation (bbox-sized) and preserved across angle edits. Absent for legacy
+       * documents whose gradients were document-sized by construction — they
+       * default to the document dimensions on load (see `getSourceContentRect`).
+       */
+      width?: number;
+      height?: number;
+    };
+
+export interface CanvasLayerBaseContract {
+  id: string;
+  name: string;
+  isEnabled: boolean;
+  isLocked: boolean;
+  opacity: number;
+  blendMode: CanvasBlendMode;
+  transform: { x: number; y: number; scaleX: number; scaleY: number; rotation: number };
+}
+
+export interface CanvasAdjustmentsContract {
+  brightness: number;
+  contrast: number;
+  saturation: number;
+  curves?: { r: [number, number][]; g: [number, number][]; b: [number, number][] };
+}
+
+export interface CanvasControlAdapterContract {
+  kind: 'controlnet' | 't2i_adapter' | 'control_lora' | 'z_image_control';
+  model: string | null;
+  weight: number;
+  beginEndStepPct: [number, number];
+  controlMode: 'balanced' | 'more_prompt' | 'more_control' | 'unbalanced' | null;
+}
+
+export interface CanvasMaskFillContract {
+  style: 'solid' | 'grid' | 'crosshatch' | 'diagonal' | 'horizontal' | 'vertical';
+  color: string;
+}
+
+export interface CanvasMaskContract {
+  bitmap: CanvasImageRef | null;
+  fill: CanvasMaskFillContract;
+  /**
+   * The layer-local origin of `bitmap`'s top-left pixel. Mask layers are
+   * content-sized exactly like paint layers: the persisted mask bitmap covers
+   * only the painted region, and this offset records where that region sits in
+   * the layer's local space (it can be negative). Absent (or `{ x: 0, y: 0 }`)
+   * for legacy documents whose mask bitmaps were document-sized at the origin —
+   * they load identically. Mirrors {@link CanvasLayerSourceContract} `paint`.
+   */
+  offset?: { x: number; y: number };
+}
+
+export interface CanvasRasterLayerContractV2 extends CanvasLayerBaseContract {
+  type: 'raster';
+  source: CanvasLayerSourceContract;
+  adjustments?: CanvasAdjustmentsContract;
+  isTransparencyLocked?: boolean;
+  filter?: { type: string; settings: Record<string, unknown> };
+}
+
+export interface CanvasControlLayerContract extends CanvasLayerBaseContract {
+  type: 'control';
+  source: CanvasLayerSourceContract;
+  adapter: CanvasControlAdapterContract;
+  withTransparencyEffect: boolean;
+  filter?: { type: string; settings: Record<string, unknown> };
+}
+
+export interface CanvasRegionalGuidanceLayerContract extends CanvasLayerBaseContract {
+  type: 'regional_guidance';
+  mask: CanvasMaskContract;
+  positivePrompt: string | null;
+  negativePrompt: string | null;
+  autoNegative: boolean;
+  referenceImages: GenerateReferenceImage[];
+}
+
+export interface CanvasInpaintMaskLayerContract extends CanvasLayerBaseContract {
+  type: 'inpaint_mask';
+  mask: CanvasMaskContract;
+  noiseLevel?: number;
+  denoiseLimit?: number;
+}
+
+export type CanvasLayerContract =
+  | CanvasRasterLayerContractV2
+  | CanvasControlLayerContract
+  | CanvasRegionalGuidanceLayerContract
+  | CanvasInpaintMaskLayerContract;
+
+export interface CanvasDocumentContractV2 {
+  version: 2;
+  width: number;
+  height: number;
+  background: 'transparent' | { color: string };
+  /** Index 0 is the top-most layer. */
+  layers: CanvasLayerContract[];
+  bbox: { x: number; y: number; width: number; height: number };
+  selectedLayerId: string | null;
+}
+
+export interface CanvasSnapshotContract {
+  id: string;
+  name: string;
+  createdAt: string;
+  document: CanvasDocumentContractV2;
+}
+
+export interface CanvasStagingAreaContractV2 extends CanvasStagingAreaContract {
+  autoSwitchMode: 'off' | 'latest' | 'progress';
+}
+
+export interface CanvasStateContractV2 {
+  version: 2;
+  document: CanvasDocumentContractV2;
+  /**
+   * Monotonic counter bumped whenever the document is swapped wholesale
+   * (snapshot restore, `replaceCanvasDocument`) rather than incrementally
+   * edited. The document mirror treats any change to this value as a full
+   * document replacement (clearing engine pixel history), even when the new
+   * document keeps the same dimensions and reuses layer ids — the case a
+   * reference/dimension diff alone cannot distinguish from an ordinary edit.
+   */
+  documentRevision: number;
+  snapshots: CanvasSnapshotContract[];
+  stagingArea: CanvasStagingAreaContractV2;
+}
+
+export type InvocationSourceId = 'generate' | 'workflow' | 'upscale' | 'canvas';
+
+export type InvocationMode = 'global' | 'dialog';
+
+export type ResultDestination = 'canvas' | 'gallery';
+
+export interface InvocationRoute {
+  sourceId: InvocationSourceId;
+  destination: ResultDestination;
+  sourceLocked: boolean;
+  destinationLocked: boolean;
+}
+
+export interface ResolvedInvocationRoute extends InvocationRoute {
+  mode: InvocationMode;
+  sourceValid: boolean;
+  destinationValid: boolean;
+  /** The top validation issue, shown on the fixed Invoke control's secondary line. */
+  validationMessage?: string;
+  /** Every reason the route cannot run right now (legacy `reasonsWhyCannotEnqueue` equivalent). */
+  validationReasons: string[];
+}
+
+export interface InvocationControllerState extends InvocationRoute {
+  lastSubmittedRunId?: string;
+}
+
+export interface PanelState {
+  isLeftOpen: boolean;
+  isRightOpen: boolean;
+  isBottomOpen: boolean;
+}
+
+export type WidgetRegion = 'left' | 'right' | 'bottom' | 'center';
+
+export interface WidgetRegionState {
+  activeInstanceId: WidgetInstanceId;
+  instanceIds: WidgetInstanceId[];
+  isCollapsed: boolean;
+  sizePx: number;
+}
+
+export interface ProjectLayoutState {
+  presetId: LayoutPresetId;
+  centerViewId: CenterViewId;
+  panels: PanelState;
+}
+
+export interface LayoutPresetWidgetInstanceSnapshot {
+  id: WidgetInstanceId;
+  typeId: WidgetTypeId;
+  title?: string;
+}
+
+export interface LayoutPresetSnapshot {
+  layout: ProjectLayoutState;
+  widgetInstances: Record<WidgetInstanceId, LayoutPresetWidgetInstanceSnapshot>;
+  widgetRegions: Record<WidgetRegion, WidgetRegionState>;
+}
+
+export interface Project {
+  id: string;
+  name: string;
+  /**
+   * Set on recovery forks created when a save loses a revision race: the id
+   * of the root project this recovered from (chains collapse to the root, so
+   * a recovery of a recovery still points at the original).
+   */
+  recoveryOf?: string;
+  recoveredAt?: string;
+  settings: ProjectSettings;
+  layout: ProjectLayoutState;
+  invocation: InvocationControllerState;
+  /** The one active project graph: an editable workflow document, compiled to a `GraphContract` at invoke time. */
+  projectGraph: ProjectGraphState;
+  widgetInstances: Record<WidgetInstanceId, WidgetInstanceContract>;
+  widgetRegions: Record<WidgetRegion, WidgetRegionState>;
+  widgetGraphs: Partial<Record<WidgetTypeId, GraphContract>>;
+  canvas: CanvasStateContractV2;
+  graphHistory: GraphHistorySnapshot[];
+  promptHistory: PromptHistoryItem[];
+  undoRedo: UndoRedoHistory;
+  queue: QueueState;
+  events: ProjectEvent[];
+}
+
+export interface LayoutPreset {
+  id: LayoutPresetId;
+  label: string;
+  isBuiltIn?: boolean;
+  snapshot: LayoutPresetSnapshot;
+}
+
+export interface WorkbenchState {
+  projects: Project[];
+  activeProjectId: string;
+  backendConnection: BackendConnectionState;
+  notifications: WorkbenchNotification[];
+  autosave: AutosaveState;
+  account: AccountState;
+  widgetFailures: WidgetFailure[];
+}
+
+export type BackendConnectionStatus = 'connecting' | 'connected' | 'disconnected';
+
+export interface BackendConnectionState {
+  status: BackendConnectionStatus;
+  error?: string;
+  lastConnectedAt?: string;
+  lastDisconnectedAt?: string;
+}
+
+export type WorkbenchNotificationKind = 'error' | 'success' | 'info';
+
+export interface WorkbenchNotification {
+  id: string;
+  kind: WorkbenchNotificationKind;
+  title: string;
+  message?: string;
+  createdAt: string;
+  projectId?: string;
+  isRead: boolean;
+}
+
+/**
+ * One entry of the project's graph history. Queue submissions record the
+ * compiled `graph`; workflow snapshots (manual save, pre-replacement) record
+ * the editable `document`, which is what makes them restorable.
+ */
+export interface GraphHistorySnapshot {
+  id: string;
+  createdAt: string;
+  label: string;
+  graph?: GraphContract;
+  document?: ProjectGraphState;
+}
+
+export interface PromptHistoryItem {
+  positivePrompt: string;
+  negativePrompt: string | null;
+}
+
+export interface UndoRedoEntry {
+  id: string;
+  createdAt: string;
+  label: string;
+  project: ProjectUndoSnapshot;
+}
+
+/**
+ * Project-level undo snapshot. Deliberately excludes `canvas`: the canvas
+ * rendering engine owns its own pixel-patch history, so project undo/redo
+ * passes the live `project.canvas` through untouched (see `restoreUndoSnapshot`).
+ */
+export interface ProjectUndoSnapshot {
+  layout: ProjectLayoutState;
+  invocation: InvocationControllerState;
+  projectGraph: ProjectGraphState;
+  widgetInstances: Record<WidgetInstanceId, WidgetInstanceContract>;
+  widgetRegions: Record<WidgetRegion, WidgetRegionState>;
+  widgetGraphs: Partial<Record<WidgetTypeId, GraphContract>>;
+}
+
+export interface UndoRedoHistory {
+  past: UndoRedoEntry[];
+  future: UndoRedoEntry[];
+}
+
+export interface QueueSubmissionSnapshot {
+  sourceId: InvocationSourceId;
+  destination: ResultDestination;
+  graph: GraphContract;
+  generate?: {
+    values: GenerateWidgetValues;
+    negativePromptNodeId: string;
+    positivePromptNodeId: string;
+    seedNodeId: string;
+  };
+  widgetInstances: Record<WidgetInstanceId, WidgetInstanceContract>;
+  widgetStates: WidgetStateMap;
+  canvas: CanvasStateContractV2;
+  submittedAt: string;
+}
+
+export interface QueueItem {
+  id: string;
+  status: QueueItemStatus;
+  cancellable: boolean;
+  snapshot: QueueSubmissionSnapshot;
+  backendItemIds?: number[];
+  completedBackendItemIds?: number[];
+  cancelledBackendItemIds?: number[];
+  backendBatchId?: string;
+  error?: string;
+  resultImages?: GeneratedImageContract[];
+}
+
+export interface QueueState {
+  items: QueueItem[];
+}
+
+export interface ProjectEvent {
+  id: string;
+  type: ProjectEventType;
+  createdAt: string;
+  summary: string;
+  runId?: string;
+}
+
+export interface RunRecord {
+  id: string;
+  projectId: string;
+  queueItemId: string;
+  sourceId: InvocationSourceId;
+  destination: ResultDestination;
+  graphSnapshotId: string;
+  status: QueueItemStatus;
+  submittedAt: string;
+  completedAt?: string;
+}
+
+export interface AutosaveState {
+  status: 'idle' | 'saving' | 'saved' | 'error';
+  lastSavedAt?: string;
+  error?: string;
+}
+
+/**
+ * Identifier for a workbench color theme. The matching palette lives in
+ * `theme/themes.ts`; the active id is applied to `<html data-theme>` so the
+ * semantic-token conditions in `theme/system.ts` resolve to the right colors.
+ */
+export type WorkbenchThemeId = 'classic' | 'light' | 'forest' | 'mono' | 'ultradark';
+
+export type DeveloperLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+export type DeveloperLogNamespace =
+  | 'canvas'
+  | 'canvas-workflow-integration'
+  | 'config'
+  | 'dnd'
+  | 'events'
+  | 'gallery'
+  | 'generation'
+  | 'metadata'
+  | 'models'
+  | 'system'
+  | 'queue'
+  | 'workflows';
+
+export interface ProjectSettings {
+  useCpuNoise: boolean;
+  showProgressDetails: boolean;
+  antialiasProgressImages: boolean;
+  showProgressImagesInViewer: boolean;
+  preferNumericAttentionStyle: boolean;
+  showPromptSyntaxHighlighting: boolean;
+}
+
+/** User-tunable appearance + behavior preferences surfaced in the Settings modal. */
+export interface WorkbenchPreferences {
+  themeId: WorkbenchThemeId;
+  reduceMotion: boolean;
+  showFocusRegionHighlight: boolean;
+  confirmImageDeletion: boolean;
+  queueJobsScope: 'active-project' | 'all';
+  language: WorkbenchLanguage;
+  enableInformationalPopovers: boolean;
+  enableModelDescriptions: boolean;
+  developerLogEnabled: boolean;
+  developerLogLevel: DeveloperLogLevel;
+  developerLogNamespaces: DeveloperLogNamespace[];
+  developerPerformanceTimingsEnabled: boolean;
+  /** Always snap workflow nodes to the grid (Ctrl snaps temporarily when off). */
+  workflowSnapToGrid: boolean;
+  /** Show the minimap in the workflow editor. */
+  workflowShowMinimap: boolean;
+  /** Reject workflow connections with incompatible field types. */
+  workflowValidateConnections: boolean;
+  /** Connection line rendering in the workflow editor. */
+  workflowEdgeStyle: 'curved' | 'square';
+  /** Account-bound overrides keyed by hotkey id (`app.invoke`, `gallery.galleryNavLeft`, etc.). */
+  customHotkeys: Record<string, string[]>;
+}
+
+export interface AccountState {
+  activeLayoutPresetId: LayoutPresetId;
+  customLayoutPresets?: LayoutPreset[];
+}
+
+export interface WorkbenchPersistenceSnapshot {
+  version: 1;
+  savedAt: string;
+  state: WorkbenchState;
+}
diff --git a/invokeai/frontend/webv2/src/workbench/useCanvasProjectMutationDispatch.ts b/invokeai/frontend/webv2/src/workbench/useCanvasProjectMutationDispatch.ts
new file mode 100644
index 00000000000..69bba034d7b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/useCanvasProjectMutationDispatch.ts
@@ -0,0 +1,24 @@
+import { useCallback } from 'react';
+
+import type { CanvasProjectMutation } from './canvasProjectMutations';
+
+import { useActiveProjectId, useWorkbenchStore } from './WorkbenchContext';
+
+export type CanvasProjectMutationDispatch = (mutation: CanvasProjectMutation) => boolean;
+
+export const useCanvasProjectMutationDispatch = (): CanvasProjectMutationDispatch => {
+  const projectId = useActiveProjectId();
+  const store = useWorkbenchStore();
+
+  return useCallback(
+    (mutation: CanvasProjectMutation) => {
+      const before = store.getState().projects.find((project) => project.id === projectId)?.canvas;
+      if (!before) {
+        return false;
+      }
+      store.dispatch({ mutation, projectId, type: 'applyCanvasProjectMutation' });
+      return store.getState().projects.find((project) => project.id === projectId)?.canvas !== before;
+    },
+    [projectId, store]
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/useModifierHeld.ts b/invokeai/frontend/webv2/src/workbench/useModifierHeld.ts
new file mode 100644
index 00000000000..4ce595deab8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/useModifierHeld.ts
@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Tracks whether a keyboard modifier is currently held, event-driven (no
+ * polling). Shared across widgets: the workflow editor's Control-snap and the
+ * canvas settings popover's Shift-revealed Debug section both key off it.
+ */
+export const useModifierHeld = (key: 'Alt' | 'Control' | 'Meta' | 'Shift'): boolean => {
+  const [isHeld, setIsHeld] = useState(false);
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === key) {
+        setIsHeld(true);
+      }
+    };
+    const onKeyUp = (event: KeyboardEvent) => {
+      if (event.key === key) {
+        setIsHeld(false);
+      }
+    };
+    // Releasing the key outside the window would otherwise leave it stuck on.
+    const onBlur = () => setIsHeld(false);
+
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+    window.addEventListener('blur', onBlur);
+
+    return () => {
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('keyup', onKeyUp);
+      window.removeEventListener('blur', onBlur);
+    };
+  }, [key]);
+
+  return isHeld;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/useNotify.ts b/invokeai/frontend/webv2/src/workbench/useNotify.ts
new file mode 100644
index 00000000000..48e0903f2f5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/useNotify.ts
@@ -0,0 +1,40 @@
+import { toaster } from '@workbench/components/ui';
+import { useMemo } from 'react';
+
+import type { WorkbenchNotificationKind } from './types';
+
+import { useOptionalWorkbenchDispatch } from './WorkbenchContext';
+
+/**
+ * Notification helper: records into the workbench shell when present, and
+ * falls back to global toasts for project-independent surfaces like Home.
+ */
+export interface Notify {
+  success: (title: string, message?: string) => void;
+  error: (title: string, message?: string) => void;
+  info: (title: string, message?: string) => void;
+}
+
+const notificationToastType: Record<WorkbenchNotificationKind, 'error' | 'info' | 'success'> = {
+  error: 'error',
+  info: 'info',
+  success: 'success',
+};
+
+export const useNotify = (): Notify => {
+  const dispatch = useOptionalWorkbenchDispatch();
+
+  return useMemo(() => {
+    const record =
+      (kind: WorkbenchNotificationKind) =>
+      (title: string, message?: string): void => {
+        if (dispatch) {
+          dispatch({ kind, message, title, type: 'recordNotice' });
+        } else {
+          toaster.create({ description: message, title, type: notificationToastType[kind] });
+        }
+      };
+
+    return { error: record('error'), info: record('info'), success: record('success') };
+  }, [dispatch]);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/useOpenWorkbenchWidget.ts b/invokeai/frontend/webv2/src/workbench/useOpenWorkbenchWidget.ts
new file mode 100644
index 00000000000..b27fd5ab7ee
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/useOpenWorkbenchWidget.ts
@@ -0,0 +1,48 @@
+import { useCallback, type Dispatch } from 'react';
+
+import type { OpenWorkbenchWidgetOptions, RegisteredWidget, WidgetRegion, WidgetTypeId } from './types';
+import type { WorkbenchAction } from './workbenchState';
+
+import { openWidgetPlacement } from './widgetPlacementCommands';
+import { useOptionalWorkbenchDispatch, useWorkbenchDispatch } from './WorkbenchContext';
+import { useOptionalWorkbenchWidgetRegistry, useWorkbenchWidgetRegistry } from './WorkbenchWidgetRegistryContext';
+
+export type OpenWorkbenchWidgetResult = { ok: true; region: WidgetRegion } | { ok: false; reason: 'unavailable' };
+
+export const openWorkbenchWidget = (
+  dispatch: Dispatch<WorkbenchAction>,
+  getWidgetsForRegion: (region: WidgetRegion) => RegisteredWidget[],
+  widgetId: WidgetTypeId,
+  options?: OpenWorkbenchWidgetOptions
+): OpenWorkbenchWidgetResult => {
+  const result = openWidgetPlacement({ dispatch, getWidgetsForRegion, options, typeId: widgetId });
+
+  return result.ok ? { ok: true, region: result.region as WidgetRegion } : { ok: false, reason: 'unavailable' };
+};
+
+export const useOpenWorkbenchWidget = () => {
+  const dispatch = useWorkbenchDispatch();
+  const { getWidgetsForRegion } = useWorkbenchWidgetRegistry();
+
+  return useCallback(
+    (widgetId: WidgetTypeId, options?: OpenWorkbenchWidgetOptions): OpenWorkbenchWidgetResult =>
+      openWorkbenchWidget(dispatch, getWidgetsForRegion, widgetId, options),
+    [dispatch, getWidgetsForRegion]
+  );
+};
+
+export const useOptionalOpenWorkbenchWidget = () => {
+  const dispatch = useOptionalWorkbenchDispatch();
+  const registry = useOptionalWorkbenchWidgetRegistry();
+
+  return useCallback(
+    (widgetId: WidgetTypeId, options?: OpenWorkbenchWidgetOptions): OpenWorkbenchWidgetResult => {
+      if (!dispatch || !registry) {
+        return { ok: false, reason: 'unavailable' };
+      }
+
+      return openWorkbenchWidget(dispatch, registry.getWidgetsForRegion, widgetId, options);
+    },
+    [dispatch, registry]
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/users/UserFormDialog.tsx b/invokeai/frontend/webv2/src/workbench/users/UserFormDialog.tsx
new file mode 100644
index 00000000000..04527fd1f0d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/users/UserFormDialog.tsx
@@ -0,0 +1,277 @@
+import { Dialog, HStack, Input, Portal, Stack, Switch, Text } from '@chakra-ui/react';
+import { createUser, generatePassword, updateUser, type UserDTO, type UserUpdateRequest } from '@workbench/auth/api';
+import { AuthFormAlert } from '@workbench/auth/components/AuthScreen';
+import { PasswordInput, PasswordStrengthMeter } from '@workbench/auth/components/PasswordInput';
+import { createUserFormSchema, PASSWORD_RULES_HINT, type UserFormValues } from '@workbench/auth/schemas';
+import { useAuthSession } from '@workbench/auth/session';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, CloseButton, Field } from '@workbench/components/ui';
+import { useZodForm } from '@workbench/models/useZodForm';
+import { useNotify } from '@workbench/useNotify';
+import { WandSparklesIcon } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export type UserFormTarget = { mode: 'create' } | { mode: 'edit'; user: UserDTO };
+
+const getTargetKey = (target: UserFormTarget): string => (target.mode === 'edit' ? target.user.user_id : 'create');
+
+const SWITCH_CHECKED_STYLES = { bg: 'accent.solid' };
+
+/**
+ * Create/edit user form for the users widget. The dialog root stays mounted
+ * and is driven by `target` (null = closed); the inner form is keyed by the
+ * target so each open starts from a fresh state.
+ */
+export const UserFormDialog = ({
+  onClose,
+  onSaved,
+  target,
+}: {
+  onClose: () => void;
+  onSaved: () => void;
+  target: UserFormTarget | null;
+}) => {
+  const { t } = useTranslation();
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  return (
+    <Dialog.Root
+      lazyMount
+      open={target !== null}
+      placement="center"
+      scrollBehavior="inside"
+      size="sm"
+      unmountOnExit
+      onOpenChange={handleOpenChange}
+    >
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            {target ? (
+              <>
+                <Dialog.Header borderBottomWidth="1px" borderColor="border.subtle">
+                  <Stack gap="0.5">
+                    <Dialog.Title fontSize="md" fontWeight="700">
+                      {target.mode === 'create' ? t('users.addUser') : t('users.editUser')}
+                    </Dialog.Title>
+                    {target.mode === 'edit' ? (
+                      <Text color="fg.subtle" fontSize="xs">
+                        {target.user.email}
+                      </Text>
+                    ) : null}
+                  </Stack>
+                </Dialog.Header>
+                <UserForm key={getTargetKey(target)} target={target} onClose={onClose} onSaved={onSaved} />
+              </>
+            ) : null}
+            <Dialog.CloseTrigger asChild>
+              <CloseButton color="fg.muted" size="sm" />
+            </Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
+
+const UserForm = ({
+  onClose,
+  onSaved,
+  target,
+}: {
+  onClose: () => void;
+  onSaved: () => void;
+  target: UserFormTarget;
+}) => {
+  const { t } = useTranslation();
+  const session = useAuthSession();
+  const notify = useNotify();
+  const [isGenerating, setIsGenerating] = useState(false);
+  const isCreate = target.mode === 'create';
+  const editedUser = target.mode === 'edit' ? target.user : null;
+  const isSelf = editedUser !== null && editedUser.user_id === session.user?.user_id;
+
+  const schema = useMemo(
+    () => createUserFormSchema(session.strictPasswordChecking, isCreate),
+    [isCreate, session.strictPasswordChecking]
+  );
+  const initialValues: UserFormValues = useMemo(
+    () => ({
+      displayName: editedUser?.display_name ?? '',
+      email: '',
+      isAdmin: editedUser?.is_admin ?? false,
+      password: '',
+    }),
+    [editedUser]
+  );
+  const form = useZodForm(schema, initialValues);
+
+  const fillGeneratedPassword = useCallback(async () => {
+    setIsGenerating(true);
+
+    try {
+      form.setValue('password', await generatePassword());
+      notify.info(t('users.passwordGenerated'), t('users.passwordGeneratedDescription'));
+    } catch (error) {
+      notify.error(t('users.couldNotGeneratePassword'), getApiErrorMessage(error, t('users.backendRejectedRequest')));
+    } finally {
+      setIsGenerating(false);
+    }
+  }, [form, notify, t]);
+
+  const submit = useCallback(
+    () =>
+      form.handleSubmit(async (values) => {
+        try {
+          if (isCreate) {
+            await createUser({
+              display_name: values.displayName.trim() || null,
+              email: values.email,
+              is_admin: values.isAdmin,
+              password: values.password,
+            });
+          } else if (editedUser) {
+            const changes: UserUpdateRequest = {};
+            const displayName = values.displayName.trim();
+
+            if (displayName !== (editedUser.display_name ?? '')) {
+              changes.display_name = displayName;
+            }
+
+            if (values.password !== '') {
+              changes.password = values.password;
+            }
+
+            if (values.isAdmin !== editedUser.is_admin) {
+              changes.is_admin = values.isAdmin;
+            }
+
+            if (Object.keys(changes).length === 0) {
+              onClose();
+              return;
+            }
+
+            await updateUser(editedUser.user_id, changes);
+          }
+        } catch (error) {
+          throw new Error(getApiErrorMessage(error, isCreate ? t('users.couldNotCreate') : t('users.couldNotUpdate')));
+        }
+
+        notify.success(isCreate ? t('users.created') : t('users.updated'));
+        onSaved();
+        onClose();
+      }),
+    [editedUser, form, isCreate, notify, onClose, onSaved, t]
+  );
+
+  const handleEmailChange = useCallback(
+    (event: { target: { value: string } }) => form.setValue('email', event.target.value),
+    [form]
+  );
+  const handleDisplayNameChange = useCallback(
+    (event: { target: { value: string } }) => form.setValue('displayName', event.target.value),
+    [form]
+  );
+  const handlePasswordChange = useCallback(
+    (event: { target: { value: string } }) => form.setValue('password', event.target.value),
+    [form]
+  );
+  const handleGeneratedPasswordClick = useCallback(() => void fillGeneratedPassword(), [fillGeneratedPassword]);
+  const handleAdminCheckedChange = useCallback(
+    (event: { checked: boolean }) => form.setValue('isAdmin', event.checked),
+    [form]
+  );
+  const handleSubmitClick = useCallback(() => void submit(), [submit]);
+
+  return (
+    <>
+      <Dialog.Body>
+        <Stack gap="4" py="2">
+          {form.formError ? <AuthFormAlert message={form.formError} tone="error" /> : null}
+          {isCreate ? (
+            <Field error={form.errors.email} label={t('users.email')}>
+              <Input
+                aria-invalid={form.errors.email ? true : undefined}
+                autoComplete="off"
+                autoFocus
+                placeholder="user@example.com"
+                value={form.values.email}
+                onChange={handleEmailChange}
+              />
+            </Field>
+          ) : null}
+          <Field helpText={t('users.displayNameHelp')} label={t('users.displayName')}>
+            <Input autoComplete="off" value={form.values.displayName} onChange={handleDisplayNameChange} />
+          </Field>
+          <Field
+            error={form.errors.password}
+            helpText={
+              isCreate
+                ? session.strictPasswordChecking
+                  ? PASSWORD_RULES_HINT
+                  : undefined
+                : t('users.leaveBlankPassword')
+            }
+            label={isCreate ? t('users.password') : t('users.newPassword')}
+          >
+            <Stack gap="1.5">
+              <HStack gap="2">
+                <PasswordInput
+                  aria-invalid={form.errors.password ? true : undefined}
+                  autoComplete="new-password"
+                  flex="1"
+                  value={form.values.password}
+                  onChange={handlePasswordChange}
+                />
+                <Button loading={isGenerating} size="xs" variant="outline" onClick={handleGeneratedPasswordClick}>
+                  <WandSparklesIcon />
+                  {t('users.generate')}
+                </Button>
+              </HStack>
+              <PasswordStrengthMeter password={form.values.password} />
+            </Stack>
+          </Field>
+          <Switch.Root
+            alignItems="center"
+            checked={form.values.isAdmin}
+            disabled={isSelf}
+            display="flex"
+            justifyContent="space-between"
+            w="full"
+            onCheckedChange={handleAdminCheckedChange}
+          >
+            <Stack gap="0.5">
+              <Switch.Label color="fg" fontSize="sm" fontWeight="500" m="0">
+                {t('users.administrator')}
+              </Switch.Label>
+              <Text color="fg.subtle" fontSize="xs">
+                {isSelf ? t('users.cannotChangeSelfRole') : t('users.administratorHelp')}
+              </Text>
+            </Stack>
+            <Switch.HiddenInput />
+            <Switch.Control _checked={SWITCH_CHECKED_STYLES}>
+              <Switch.Thumb />
+            </Switch.Control>
+          </Switch.Root>
+        </Stack>
+      </Dialog.Body>
+      <Dialog.Footer gap="2">
+        <Button size="xs" variant="ghost" onClick={onClose}>
+          {t('common.cancel')}
+        </Button>
+        <Button loading={form.isSubmitting} size="xs" variant="solid" onClick={handleSubmitClick}>
+          {isCreate ? t('users.createUser') : t('users.saveChanges')}
+        </Button>
+      </Dialog.Footer>
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/users/UserManagement.tsx b/invokeai/frontend/webv2/src/workbench/users/UserManagement.tsx
new file mode 100644
index 00000000000..661fb92b396
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/users/UserManagement.tsx
@@ -0,0 +1,301 @@
+/* eslint-disable react/react-compiler */
+import { Avatar, Badge, Box, Center, Flex, HStack, Spinner, Stack, Switch, Table, Text } from '@chakra-ui/react';
+import { deleteUser, listUsers, updateUser, type UserDTO } from '@workbench/auth/api';
+import { useAuthSession } from '@workbench/auth/session';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, IconButton, ConfirmDialog, Scrollable, Tooltip } from '@workbench/components/ui';
+import { useNotify } from '@workbench/useNotify';
+import { PencilIcon, Trash2Icon, UserPlusIcon } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { UserFormDialog, type UserFormTarget } from './UserFormDialog';
+
+const ROW_HOVER_STYLES = { bg: 'bg.muted' };
+const SWITCH_CHECKED_STYLES = { bg: 'accent.solid' };
+const DELETE_BUTTON_HOVER_STYLES = { color: 'fg.error' };
+
+/**
+ * Admin-only center view: the workspace user directory with create, edit,
+ * activate/deactivate, and delete. The widget is already hidden for
+ * non-admins via `requiresAdmin`; the inline guard covers stale persisted
+ * layouts that still point at it.
+ */
+export const UserManagement = () => {
+  const { t } = useTranslation();
+
+  return (
+    <Scrollable flex="1" h="full" label={t('users.management')}>
+      <UsersManagementPanel />
+    </Scrollable>
+  );
+};
+
+export const UsersManagementPanel = () => {
+  const { t } = useTranslation();
+  const session = useAuthSession();
+
+  if (!session.multiuserEnabled || session.user?.is_admin !== true) {
+    return (
+      <Center h="full" w="full">
+        <Text color="fg.subtle" fontSize="sm">
+          {t('users.adminOnly')}
+        </Text>
+      </Center>
+    );
+  }
+
+  return <UsersDirectory currentUserId={session.user.user_id} />;
+};
+
+const UsersDirectory = ({ currentUserId }: { currentUserId: string }) => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const [users, setUsers] = useState<UserDTO[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [formTarget, setFormTarget] = useState<UserFormTarget | null>(null);
+  const [deleteTarget, setDeleteTarget] = useState<UserDTO | null>(null);
+
+  const refresh = useCallback(async () => {
+    try {
+      setUsers(await listUsers());
+      setLoadError(null);
+    } catch (error) {
+      setLoadError(getApiErrorMessage(error, t('users.couldNotLoad')));
+    }
+  }, [t]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const setUserActive = useCallback(
+    async (user: UserDTO, isActive: boolean) => {
+      try {
+        await updateUser(user.user_id, { is_active: isActive });
+        await refresh();
+      } catch (error) {
+        notify.error(
+          isActive ? t('users.couldNotActivate') : t('users.couldNotDeactivate'),
+          getApiErrorMessage(error, t('users.backendRejectedChange'))
+        );
+      }
+    },
+    [notify, refresh, t]
+  );
+
+  const confirmDelete = useCallback(async () => {
+    if (!deleteTarget) {
+      return;
+    }
+
+    try {
+      await deleteUser(deleteTarget.user_id);
+      notify.success(t('users.deleted'));
+      await refresh();
+    } catch (error) {
+      notify.error(t('users.couldNotDelete'), getApiErrorMessage(error, t('users.backendRejectedRequest')));
+    }
+  }, [deleteTarget, notify, refresh, t]);
+
+  const openCreateForm = useCallback(() => setFormTarget({ mode: 'create' }), []);
+  const closeForm = useCallback(() => setFormTarget(null), []);
+  const refreshAfterSave = useCallback(() => void refresh(), [refresh]);
+  const closeDeleteConfirm = useCallback(() => setDeleteTarget(null), []);
+  const retryLoad = useCallback(() => void refresh(), [refresh]);
+
+  return (
+    <>
+      <Flex justify="center" px="4" py="6" w="full">
+        <Stack gap="4" w="full">
+          <HStack align="flex-start" justify="space-between">
+            <Stack gap="0.5">
+              <Text fontSize="md" fontWeight="700">
+                {t('users.title')}
+              </Text>
+              <Text color="fg.subtle" fontSize="xs">
+                {users ? t('users.accountCount', { count: users.length }) : t('users.description')}
+              </Text>
+            </Stack>
+            <Button size="xs" variant="solid" onClick={openCreateForm}>
+              <UserPlusIcon />
+              {t('users.addUser')}
+            </Button>
+          </HStack>
+          <Box bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" overflowX="auto" rounded="lg">
+            {users === null ? (
+              <Center minH="40">
+                {loadError ? (
+                  <Stack align="center" gap="2" p="4">
+                    <Text color="fg.error" fontSize="xs" textAlign="center">
+                      {loadError}
+                    </Text>
+                    <Button size="xs" variant="outline" onClick={retryLoad}>
+                      {t('common.retry')}
+                    </Button>
+                  </Stack>
+                ) : (
+                  <Spinner color="fg.muted" size="sm" />
+                )}
+              </Center>
+            ) : (
+              <Table.Root minW="42rem" size="sm">
+                <Table.Header>
+                  <Table.Row bg="bg.muted">
+                    <Table.ColumnHeader borderColor="border.subtle" color="fg.muted" ps="4">
+                      {t('users.user')}
+                    </Table.ColumnHeader>
+                    <Table.ColumnHeader borderColor="border.subtle" color="fg.muted">
+                      {t('users.role')}
+                    </Table.ColumnHeader>
+                    <Table.ColumnHeader borderColor="border.subtle" color="fg.muted">
+                      {t('users.lastSignIn')}
+                    </Table.ColumnHeader>
+                    <Table.ColumnHeader borderColor="border.subtle" color="fg.muted">
+                      {t('common.active')}
+                    </Table.ColumnHeader>
+                    <Table.ColumnHeader borderColor="border.subtle" pe="4" />
+                  </Table.Row>
+                </Table.Header>
+                <Table.Body>
+                  {users.map((user) => (
+                    <UserRow
+                      key={user.user_id}
+                      isSelf={user.user_id === currentUserId}
+                      setDeleteTarget={setDeleteTarget}
+                      setFormTarget={setFormTarget}
+                      setUserActive={setUserActive}
+                      user={user}
+                    />
+                  ))}
+                </Table.Body>
+              </Table.Root>
+            )}
+          </Box>
+        </Stack>
+      </Flex>
+      <UserFormDialog target={formTarget} onClose={closeForm} onSaved={refreshAfterSave} />
+      <ConfirmDialog
+        body={t('users.deleteBody', { name: deleteTarget ? getUserLabel(deleteTarget) : t('users.thisUser') })}
+        confirmLabel={t('users.deleteUser')}
+        isOpen={deleteTarget !== null}
+        title={t('users.deleteTitle')}
+        onClose={closeDeleteConfirm}
+        onConfirm={confirmDelete}
+      />
+    </>
+  );
+};
+
+const getUserLabel = (user: UserDTO): string => user.display_name?.trim() || user.email;
+
+const formatLastSignIn = (lastLoginAt: string | null, neverLabel: string): string => {
+  if (!lastLoginAt) {
+    return neverLabel;
+  }
+
+  const date = new Date(lastLoginAt);
+
+  return Number.isNaN(date.getTime()) ? neverLabel : date.toLocaleString();
+};
+
+const UserRow = ({
+  isSelf,
+  setDeleteTarget,
+  setFormTarget,
+  setUserActive,
+  user,
+}: {
+  isSelf: boolean;
+  setDeleteTarget: (user: UserDTO) => void;
+  setFormTarget: (target: UserFormTarget) => void;
+  setUserActive: (user: UserDTO, isActive: boolean) => void;
+  user: UserDTO;
+}) => {
+  const { t } = useTranslation();
+  const handleDelete = useCallback(() => setDeleteTarget(user), [setDeleteTarget, user]);
+  const handleEdit = useCallback(() => setFormTarget({ mode: 'edit', user }), [setFormTarget, user]);
+  const handleSetActive = useCallback(
+    (event: { checked: boolean }) => void setUserActive(user, event.checked),
+    [setUserActive, user]
+  );
+
+  return (
+    <Table.Row bg="transparent" _hover={ROW_HOVER_STYLES}>
+      <Table.Cell borderColor="border.subtle" ps="4">
+        <HStack gap="2.5">
+          <Avatar.Root bg="accent.subtle" color="fg" size="2xs">
+            <Avatar.Fallback fontSize="2xs" name={getUserLabel(user)} />
+          </Avatar.Root>
+          <Stack gap="0">
+            <HStack gap="1.5">
+              <Text fontSize="xs" fontWeight="600">
+                {getUserLabel(user)}
+              </Text>
+              {isSelf ? (
+                <Badge fontSize="2xs" variant="surface">
+                  {t('users.you')}
+                </Badge>
+              ) : null}
+            </HStack>
+            <Text color="fg.muted" fontSize="2xs">
+              {user.email}
+            </Text>
+          </Stack>
+        </HStack>
+      </Table.Cell>
+      <Table.Cell borderColor="border.subtle">
+        <Badge colorPalette={user.is_admin ? 'purple' : 'gray'} fontSize="2xs" variant="surface">
+          {user.is_admin ? t('users.admin') : t('users.user')}
+        </Badge>
+      </Table.Cell>
+      <Table.Cell borderColor="border.subtle">
+        <Text color="fg.muted" fontSize="2xs">
+          {formatLastSignIn(user.last_login_at, t('users.never'))}
+        </Text>
+      </Table.Cell>
+      <Table.Cell borderColor="border.subtle">
+        <Tooltip content={t('users.cannotDeactivateSelf')} disabled={!isSelf} showArrow>
+          <Switch.Root
+            aria-label={t('users.activeLabel', { name: getUserLabel(user) })}
+            checked={user.is_active}
+            disabled={isSelf}
+            size="sm"
+            onCheckedChange={handleSetActive}
+          >
+            <Switch.HiddenInput />
+            <Switch.Control _checked={SWITCH_CHECKED_STYLES}>
+              <Switch.Thumb />
+            </Switch.Control>
+          </Switch.Root>
+        </Tooltip>
+      </Table.Cell>
+      <Table.Cell borderColor="border.subtle" pe="4" textAlign="end">
+        <HStack gap="0.5" justify="flex-end">
+          <IconButton
+            aria-label={t('users.editUserNamed', { name: getUserLabel(user) })}
+            color="fg.muted"
+            size="2xs"
+            variant="ghost"
+            onClick={handleEdit}
+          >
+            <PencilIcon />
+          </IconButton>
+          <Tooltip content={t('users.cannotDeleteSelf')} disabled={!isSelf} showArrow>
+            <IconButton
+              aria-label={t('users.deleteUserNamed', { name: getUserLabel(user) })}
+              color="fg.muted"
+              disabled={isSelf}
+              size="2xs"
+              variant="ghost"
+              _hover={DELETE_BUTTON_HOVER_STYLES}
+              onClick={handleDelete}
+            >
+              <Trash2Icon />
+            </IconButton>
+          </Tooltip>
+        </HStack>
+      </Table.Cell>
+    </Table.Row>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/users/index.ts b/invokeai/frontend/webv2/src/workbench/users/index.ts
new file mode 100644
index 00000000000..1d4eea72293
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/users/index.ts
@@ -0,0 +1,2 @@
+export * from './UserFormDialog';
+export * from './UserManagement';
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetActionsMenu.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetActionsMenu.tsx
new file mode 100644
index 00000000000..ce0677675de
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetActionsMenu.tsx
@@ -0,0 +1,165 @@
+import type {
+  GraphBearingSurfaceContract,
+  GraphContract,
+  Project,
+  WidgetInstanceRuntimeMeta,
+  WidgetManifest,
+  WidgetRuntimeApi,
+  WorkbenchRegion,
+} from '@workbench/types';
+
+import { Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { IconButton } from '@workbench/components/ui';
+import { GraphPreviewDialog } from '@workbench/graph-preview';
+import { createGraphBearingSurface } from '@workbench/graphSurfaces';
+import { resolveWidgetLabel } from '@workbench/widgetLabels';
+import { shallowEqual, useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { compileProjectGraph } from '@workbench/workflows/buildGraph';
+import { getInvocationTemplatesSnapshot } from '@workbench/workflows/templates';
+import { GitBranchIcon, MoreHorizontalIcon, TargetIcon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * The widget frame's shared header actions menu. It hosts the universal
+ * graph-bearing actions (`Set Source`, `View Graph`) and any extra entries the
+ * widget's manifest contributes via `headerMenu` — one menu per widget, so
+ * widgets extend the frame instead of stacking their own menus and toolbars.
+ */
+
+const getPreviewGraph = (project: Project, surface: GraphBearingSurfaceContract): GraphContract | null => {
+  // The project graph compiles fresh for preview so `View Graph` always shows
+  // what Invoke would run right now; widget graphs keep their last compile.
+  if (surface.sourceId === 'workflow') {
+    const templatesSnapshot = getInvocationTemplatesSnapshot();
+
+    if (templatesSnapshot.status !== 'loaded') {
+      return null;
+    }
+
+    try {
+      return compileProjectGraph(project.projectGraph, templatesSnapshot.templates);
+    } catch {
+      return null;
+    }
+  }
+
+  return project.widgetGraphs[surface.widgetId] ?? null;
+};
+
+const MENU_POSITIONING = { placement: 'bottom-end' } as const;
+const DISABLED_PROPS = { opacity: 0.4 };
+
+const GraphSurfaceMenuItems = ({
+  surface,
+  onPreview,
+}: {
+  surface: GraphBearingSurfaceContract;
+  onPreview: () => void;
+}) => {
+  const { t } = useTranslation();
+  const activeSourceId = useActiveProjectSelector((project) => project.invocation.sourceId);
+  const dispatch = useWorkbenchDispatch();
+  const isActiveSource = activeSourceId === surface.sourceId;
+  const handleSetSource = useCallback(
+    () => dispatch({ sourceId: surface.sourceId, type: 'setInvocationSource' }),
+    [dispatch, surface.sourceId]
+  );
+
+  return (
+    <Menu.ItemGroup>
+      <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+        {t('common.graph')}
+      </Menu.ItemGroupLabel>
+      <Menu.Item
+        value="set-source"
+        disabled={isActiveSource || !surface.canSetSource}
+        _disabled={DISABLED_PROPS}
+        onClick={handleSetSource}
+      >
+        <Icon as={TargetIcon} boxSize="3.5" />
+        <Menu.ItemText>{t('widgets.graph.setSource')}</Menu.ItemText>
+        {isActiveSource ? (
+          <Text color="fg.subtle" fontSize="2xs" ms="auto">
+            {t('common.active')}
+          </Text>
+        ) : null}
+      </Menu.Item>
+      <Menu.Item value="view-graph" disabled={!surface.canPreviewGraph} onClick={onPreview}>
+        <Icon as={GitBranchIcon} boxSize="3.5" />
+        <Menu.ItemText>{t('widgets.graph.viewGraph')}</Menu.ItemText>
+      </Menu.Item>
+    </Menu.ItemGroup>
+  );
+};
+
+export const WidgetActionsMenu = ({
+  instance,
+  manifest,
+  region,
+  runtime,
+}: {
+  instance: WidgetInstanceRuntimeMeta;
+  manifest: WidgetManifest;
+  region: WorkbenchRegion;
+  runtime: WidgetRuntimeApi;
+}) => {
+  const { t } = useTranslation();
+  const activeProject = useActiveProjectSelector(
+    (project) => ({ projectGraph: project.projectGraph, widgetGraphs: project.widgetGraphs }),
+    shallowEqual
+  ) as Project;
+  const [isPreviewOpen, setIsPreviewOpen] = useState(false);
+  const HeaderMenu = manifest.headerMenu;
+  const label = resolveWidgetLabel(manifest, t);
+  const surface = manifest.graphBearing?.surfaces.includes(region)
+    ? createGraphBearingSurface(manifest, region, label)
+    : null;
+  const surfaceSourceId = surface?.sourceId;
+  const handlePreview = useCallback(() => setIsPreviewOpen(true), []);
+  const positionHints =
+    isPreviewOpen && surfaceSourceId === 'workflow'
+      ? Object.fromEntries(activeProject.projectGraph.nodes.map((node) => [node.id, node.position]))
+      : undefined;
+
+  if (!surface && !HeaderMenu) {
+    return null;
+  }
+
+  const previewGraph = surface && isPreviewOpen ? getPreviewGraph(activeProject, surface) : null;
+  // The project graph mirrors the editable document, so the preview can reuse
+  // the editor's node positions instead of auto-layouting.
+  return (
+    <>
+      <Menu.Root positioning={MENU_POSITIONING}>
+        <Menu.Trigger asChild>
+          <IconButton aria-label={t('widgets.actionsLabel', { label })} color="fg.muted" size="2xs" variant="ghost">
+            <MoreHorizontalIcon />
+          </IconButton>
+        </Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>
+            <Menu.Content minW="13rem">
+              {surface ? <GraphSurfaceMenuItems surface={surface} onPreview={handlePreview} /> : null}
+              {surface && HeaderMenu ? <Menu.Separator borderColor="border.subtle" /> : null}
+              {HeaderMenu ? (
+                <HeaderMenu instance={instance} manifest={manifest} region={region} runtime={runtime} />
+              ) : null}
+            </Menu.Content>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      {surface && isPreviewOpen ? (
+        <GraphPreviewDialog
+          graph={previewGraph}
+          graphId={surface.graphId}
+          isOpen={isPreviewOpen}
+          positionHints={positionHints}
+          sourceId={surface.sourceId}
+          title={surface.label}
+          onOpenChange={setIsPreviewOpen}
+        />
+      ) : null}
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetBar.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetBar.tsx
new file mode 100644
index 00000000000..ac6eb4f4434
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetBar.tsx
@@ -0,0 +1,195 @@
+import type { WidgetInstanceId, WidgetRegion } from '@workbench/types';
+import type { WidgetRegionDropState } from '@workbench/widgetDnd';
+import type { WidgetPlacementInstanceMeta, WidgetRegionItem } from '@workbench/widgetRegionViewModel';
+
+import { Box, type SystemStyleObject } from '@chakra-ui/react';
+import { verticalListSortingStrategy } from '@dnd-kit/sortable';
+import { Row, Tooltip } from '@workbench/components/ui';
+import { WidgetIcon } from '@workbench/iconResolver';
+import { type MouseEvent, useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useWidgetSortable } from './useWidgetSortable';
+import { WidgetEnableMenu, type WidgetEnableMenuItem } from './WidgetEnableMenu';
+import { WidgetInstanceContextMenu, type WidgetInstanceContextMenuTarget } from './WidgetInstanceContextMenu';
+import { WidgetStrip } from './WidgetStrip';
+
+export type WidgetBarItem = WidgetRegionItem<WidgetPlacementInstanceMeta>;
+
+const WIDGET_SLOT_DISABLED_PROPS = { opacity: 0.4 };
+
+interface WidgetBarProps {
+  side: 'left' | 'right';
+  region: Exclude<WidgetRegion, 'bottom' | 'center'>;
+  activeId: WidgetInstanceId | null;
+  dropState: WidgetRegionDropState;
+  railItems: WidgetBarItem[];
+  menuItems: WidgetBarItem[];
+  onSelect: (instanceId: WidgetInstanceId) => void;
+  onToggle: (item: WidgetBarItem) => void;
+}
+
+export const WidgetBar = ({
+  activeId,
+  dropState,
+  menuItems,
+  onSelect,
+  onToggle,
+  railItems,
+  region,
+  side,
+}: WidgetBarProps) => {
+  const { t } = useTranslation();
+  const [enableMenuTarget, setEnableMenuTarget] = useState<{
+    x: number;
+    y: number;
+  } | null>(null);
+  const [instanceMenuTarget, setInstanceMenuTarget] = useState<WidgetInstanceContextMenuTarget | null>(null);
+
+  const openEnableMenu = useCallback((event: MouseEvent) => {
+    event.preventDefault();
+    setEnableMenuTarget({ x: event.clientX, y: event.clientY });
+  }, []);
+
+  const openInstanceMenu = useCallback((item: WidgetBarItem, event: MouseEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
+    setInstanceMenuTarget({ item, x: event.clientX, y: event.clientY });
+  }, []);
+
+  const sortableInstanceIds = useMemo(() => railItems.map((item) => item.id), [railItems]);
+
+  const positioning = useMemo(
+    () =>
+      ({
+        placement: region === 'left' ? 'right-start' : 'left-start',
+      }) as const,
+    [region]
+  );
+
+  const trigger = useMemo(() => ({ kind: 'rail', region }) as const, [region]);
+  const handleContextClose = useCallback(() => setEnableMenuTarget(null), []);
+  const handleMenuToggle = useCallback((item: WidgetEnableMenuItem) => onToggle(item as WidgetBarItem), [onToggle]);
+  const handleInstanceClose = useCallback(() => setInstanceMenuTarget(null), []);
+
+  return (
+    <WidgetStrip
+      align="center"
+      as="nav"
+      bg="bg.subtle"
+      borderColor="border.subtle"
+      borderRightWidth={side === 'left' ? '1px' : '0'}
+      borderLeftWidth={side === 'right' ? '1px' : '0'}
+      direction="column"
+      dropState={dropState}
+      flexShrink={0}
+      pt="1.5"
+      region={region}
+      sortableInstanceIds={sortableInstanceIds}
+      strategy={verticalListSortingStrategy}
+      w="12"
+      onContextMenu={openEnableMenu}
+    >
+      {railItems.map((item) => (
+        <WidgetSlot
+          key={item.id}
+          item={item}
+          isActive={item.id === activeId}
+          region={region}
+          tooltipPlacement={side === 'left' ? 'right' : 'left'}
+          onContextMenu={openInstanceMenu}
+          onSelect={onSelect}
+        />
+      ))}
+
+      <Box mt="1.5">
+        <WidgetEnableMenu
+          contextTarget={enableMenuTarget}
+          groupLabel={t('widgets.groupLabel')}
+          items={menuItems}
+          positioning={positioning}
+          trigger={trigger}
+          triggerLabel={t('widgets.visibilityLabel', { region: region === 'left' ? 'Left' : 'Right' })}
+          onContextClose={handleContextClose}
+          onToggle={handleMenuToggle}
+        />
+      </Box>
+
+      <WidgetInstanceContextMenu
+        target={instanceMenuTarget}
+        onClose={handleInstanceClose}
+        onRemove={handleMenuToggle}
+      />
+    </WidgetStrip>
+  );
+};
+
+const WIDGET_ITEM_SX: SystemStyleObject = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  rounded: 'md',
+  h: 9,
+  w: 9,
+  '&[aria-pressed="false"]:hover': {
+    bg: 'bg.emphasized',
+  },
+  _disabled: WIDGET_SLOT_DISABLED_PROPS,
+};
+
+const WidgetSlot = ({
+  item,
+  isActive,
+  onContextMenu,
+  onSelect,
+  region,
+  tooltipPlacement,
+}: {
+  item: WidgetBarItem;
+  isActive: boolean;
+  onContextMenu: (item: WidgetBarItem, event: MouseEvent) => void;
+  onSelect: (instanceId: WidgetInstanceId) => void;
+  region: WidgetRegion;
+  tooltipPlacement: 'left' | 'right';
+}) => {
+  const tooltipLabel = item.failureMessage ? `${item.label}: ${item.failureMessage}` : item.label;
+  const isDisabled = item.status === 'disabled';
+  const positioning = useMemo(() => ({ placement: tooltipPlacement }) as const, [tooltipPlacement]);
+
+  const handleClick = useCallback(() => {
+    if (!isDisabled) {
+      onSelect(item.id);
+    }
+  }, [isDisabled, item.id, onSelect]);
+
+  const handleContextMenu = useCallback((event: MouseEvent) => onContextMenu(item, event), [item, onContextMenu]);
+
+  const { dragHandleProps, setNodeRef, style } = useWidgetSortable({
+    disabled: isDisabled,
+    instanceId: item.id,
+    region,
+    typeId: item.typeId,
+  });
+
+  return (
+    <Tooltip showArrow closeDelay={80} content={tooltipLabel} openDelay={250} positioning={positioning}>
+      <Box ref={setNodeRef} pb="1.5" style={style}>
+        <Row
+          {...dragHandleProps}
+          css={WIDGET_ITEM_SX}
+          active={isActive ? 'accent' : 'none'}
+          aria-label={item.label}
+          aria-disabled={isDisabled}
+          aria-pressed={isActive}
+          as="button"
+          data-disabled={isDisabled ? '' : undefined}
+          tabIndex={isDisabled ? -1 : undefined}
+          onClick={handleClick}
+          onContextMenu={handleContextMenu}
+        >
+          <WidgetIcon icon={item.icon} boxSize="5" />
+        </Row>
+      </Box>
+    </Tooltip>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetEnableMenu.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetEnableMenu.tsx
new file mode 100644
index 00000000000..e381197c94f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetEnableMenu.tsx
@@ -0,0 +1,179 @@
+import type {
+  RegisteredWidget,
+  WidgetIconComponent,
+  WidgetInstanceId,
+  WidgetRegion,
+  WidgetTypeId,
+} from '@workbench/types';
+
+import { Flex, Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { IconButton } from '@workbench/components/ui';
+import { WidgetIcon } from '@workbench/iconResolver';
+import { CheckIcon, MoreHorizontalIcon } from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export interface WidgetEnableMenuItem {
+  allowMultiple: boolean;
+  failureMessage?: string;
+  icon: WidgetIconComponent;
+  id: WidgetInstanceId;
+  isEnabled: boolean;
+  label: string;
+  status?: RegisteredWidget['status'];
+  typeId: WidgetTypeId;
+  widget: RegisteredWidget;
+}
+
+type WidgetEnableMenuTrigger =
+  | { kind: 'rail'; region: Exclude<WidgetRegion, 'bottom' | 'center'> }
+  | { kind: 'bottom' }
+  | { kind: 'center' };
+
+interface WidgetEnableMenuProps {
+  groupLabel: string;
+  items: WidgetEnableMenuItem[];
+  positioning: NonNullable<Menu.RootProps['positioning']>;
+  trigger: WidgetEnableMenuTrigger;
+  triggerLabel: string;
+  contextTarget?: { x: number; y: number } | null;
+  getItemMeta?: (item: WidgetEnableMenuItem) => string | null;
+  isItemDisabled?: (item: WidgetEnableMenuItem) => boolean;
+  onContextClose?: () => void;
+  onToggle: (item: WidgetEnableMenuItem) => void;
+}
+
+const TRIGGER_HOVER_PROPS = { bg: 'bg.muted' };
+const MENU_ITEM_DISABLED_PROPS = { opacity: 0.4 };
+
+const getWidgetEnableMenuTriggerButton = (label: string, trigger: WidgetEnableMenuTrigger) => {
+  if (trigger.kind === 'center') {
+    return (
+      <IconButton aria-label={label} size="xs" variant="ghost">
+        <Icon as={MoreHorizontalIcon} boxSize="4" />
+      </IconButton>
+    );
+  }
+
+  const isBottom = trigger.kind === 'bottom';
+
+  return (
+    <Flex
+      align="center"
+      aria-label={label}
+      as="button"
+      color="fg"
+      h={isBottom ? '5' : '9'}
+      justify="center"
+      rounded={isBottom ? 'sm' : 'md'}
+      transition="background var(--wb-motion-duration-fast) ease, color var(--wb-motion-duration-fast) ease"
+      w={isBottom ? '5' : '9'}
+      _hover={TRIGGER_HOVER_PROPS}
+    >
+      <Icon as={MoreHorizontalIcon} boxSize={isBottom ? '4' : '5'} />
+    </Flex>
+  );
+};
+
+export const WidgetEnableMenu = ({
+  contextTarget,
+  getItemMeta,
+  groupLabel,
+  isItemDisabled,
+  items,
+  onContextClose,
+  onToggle,
+  positioning,
+  trigger,
+  triggerLabel,
+}: WidgetEnableMenuProps) => {
+  const { t } = useTranslation();
+  const content = (
+    <Menu.Content minW="12rem">
+      <Menu.ItemGroup>
+        <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+          {groupLabel}
+        </Menu.ItemGroupLabel>
+        {items.map((item) => {
+          const meta = getItemMeta?.(item) ?? (item.failureMessage ? t('common.failed') : null);
+          const disabled = item.status === 'disabled' || isItemDisabled?.(item) === true;
+
+          return <WidgetEnableMenuRow key={item.id} disabled={disabled} item={item} meta={meta} onToggle={onToggle} />;
+        })}
+      </Menu.ItemGroup>
+    </Menu.Content>
+  );
+
+  const contextPositioning = useMemo(
+    () => ({
+      ...positioning,
+      getAnchorRect: () => (contextTarget ? { height: 1, width: 1, x: contextTarget.x, y: contextTarget.y } : null),
+    }),
+    [contextTarget, positioning]
+  );
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onContextClose?.();
+      }
+    },
+    [onContextClose]
+  );
+
+  return (
+    <>
+      <Menu.Root positioning={positioning}>
+        <Menu.Trigger asChild>{getWidgetEnableMenuTriggerButton(triggerLabel, trigger)}</Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>{content}</Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <Menu.Root
+        lazyMount
+        open={contextTarget !== null && contextTarget !== undefined}
+        positioning={contextPositioning}
+        unmountOnExit
+        onOpenChange={handleOpenChange}
+      >
+        <Portal>
+          <Menu.Positioner>{content}</Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+    </>
+  );
+};
+
+const WidgetEnableMenuRow = ({
+  disabled,
+  item,
+  meta,
+  onToggle,
+}: {
+  disabled: boolean;
+  item: WidgetEnableMenuItem;
+  meta: string | null;
+  onToggle: (item: WidgetEnableMenuItem) => void;
+}) => {
+  const handleClick = useCallback(() => onToggle(item), [item, onToggle]);
+
+  return (
+    <Menu.Item
+      role="menuitemcheckbox"
+      aria-checked={item.isEnabled}
+      value={item.id}
+      closeOnSelect={false}
+      disabled={disabled}
+      _disabled={MENU_ITEM_DISABLED_PROPS}
+      onClick={handleClick}
+    >
+      <Icon as={CheckIcon} boxSize="3" opacity={item.isEnabled ? 1 : 0} />
+      <WidgetIcon icon={item.icon} boxSize="3.5" />
+      <Menu.ItemText>{item.label}</Menu.ItemText>
+      {meta ? (
+        <Text color="fg.subtle" fontSize="2xs" ms="auto">
+          {meta}
+        </Text>
+      ) : null}
+    </Menu.Item>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetFailureBoundary.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetFailureBoundary.tsx
new file mode 100644
index 00000000000..739369f0856
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetFailureBoundary.tsx
@@ -0,0 +1,95 @@
+import type { WidgetId } from '@workbench/types';
+
+import { Code, ScrollArea, Stack, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+interface WidgetFailureBoundaryProps {
+  widgetId: WidgetId;
+  resetKey: string;
+  children: ReactNode;
+}
+
+interface WidgetFailureBoundaryState {
+  error?: Error;
+  details?: string;
+  resetKey: string;
+}
+
+export class WidgetFailureBoundary extends Component<WidgetFailureBoundaryProps, WidgetFailureBoundaryState> {
+  state: WidgetFailureBoundaryState = { resetKey: this.props.resetKey };
+
+  private handleRetry = () => {
+    this.setState({ details: undefined, error: undefined, resetKey: this.props.resetKey });
+  };
+
+  private handleCopyError = () => {
+    const { details, error } = this.state;
+
+    if (error) {
+      void navigator.clipboard?.writeText(details ?? error.message);
+    }
+  };
+
+  static getDerivedStateFromProps(
+    props: WidgetFailureBoundaryProps,
+    state: WidgetFailureBoundaryState
+  ): Partial<WidgetFailureBoundaryState> | null {
+    if (props.resetKey !== state.resetKey) {
+      return { details: undefined, error: undefined, resetKey: props.resetKey };
+    }
+
+    return null;
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<WidgetFailureBoundaryState> {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    this.setState({ details: errorInfo.componentStack ?? error.stack ?? error.message });
+  }
+
+  render() {
+    const { children, widgetId } = this.props;
+    const { details, error } = this.state;
+
+    if (!error) {
+      return children;
+    }
+
+    const copyableDetails = details ?? error.message;
+
+    return (
+      <Stack bg="bg.muted" borderColor="border.error" borderWidth="1px" gap="2" p="3" rounded="md">
+        <Text color="fg.error" fontSize="xs" fontWeight="700">
+          Widget failed: {widgetId}
+        </Text>
+        <ScrollArea.Root maxH="8rem" size="xs" variant="hover">
+          <ScrollArea.Viewport maxH="8rem">
+            <ScrollArea.Content>
+              <Code display="block" p="2" whiteSpace="pre-wrap">
+                {copyableDetails}
+              </Code>
+            </ScrollArea.Content>
+          </ScrollArea.Viewport>
+          <ScrollArea.Scrollbar>
+            <ScrollArea.Thumb />
+          </ScrollArea.Scrollbar>
+          <ScrollArea.Scrollbar orientation="horizontal">
+            <ScrollArea.Thumb />
+          </ScrollArea.Scrollbar>
+          <ScrollArea.Corner />
+        </ScrollArea.Root>
+        <Stack direction="row" gap="2">
+          <Button alignSelf="start" size="2xs" variant="outline" onClick={this.handleRetry}>
+            Retry
+          </Button>
+          <Button alignSelf="start" size="2xs" variant="outline" onClick={this.handleCopyError}>
+            Copy Error
+          </Button>
+        </Stack>
+      </Stack>
+    );
+  }
+}
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetFrames.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetFrames.tsx
new file mode 100644
index 00000000000..8e25fd9b82c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetFrames.tsx
@@ -0,0 +1,277 @@
+/* eslint-disable react/react-compiler */
+import type {
+  WidgetInstanceId,
+  WidgetInstanceRuntimeMeta,
+  WidgetManifest,
+  WidgetRegion,
+  WidgetRuntimeApi,
+  WidgetTypeId,
+  WorkbenchRegion,
+} from '@workbench/types';
+
+import { Box, Flex, HStack, Icon, Stack, Text, type RecipeVariantProps, useRecipe } from '@chakra-ui/react';
+import { chipRecipe } from '@theme/recipes';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { useFocusRegionProps } from '@workbench/focusRegions';
+import { openWorkbenchSettings } from '@workbench/settings/settingsDialogStore';
+import { resolveWidgetLabel } from '@workbench/widgetLabels';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { SettingsIcon, type LucideIcon } from 'lucide-react';
+import {
+  useCallback,
+  useMemo,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { WidgetActionsMenu } from './WidgetActionsMenu';
+
+const PANEL_SIZE_STEP_PX = 16;
+const MIN_PANEL_SIZE_PX = 180;
+const MAX_PANEL_SIZE_PX = 520;
+const MIN_BOTTOM_PANEL_SIZE_PX = 96;
+const MAX_BOTTOM_PANEL_SIZE_PX = 420;
+const RESIZE_HANDLE_HOVER_PROPS = { bg: 'accent.solid', opacity: 0.45 };
+const RESIZE_HANDLE_FOCUS_PROPS = { bg: 'accent.solid', opacity: 0.65, outline: '2px solid {colors.accent.solid}' };
+
+const getPanelSizeBounds = (region: WidgetRegion): { max: number; min: number } => {
+  if (region === 'bottom') {
+    return { max: MAX_BOTTOM_PANEL_SIZE_PX, min: MIN_BOTTOM_PANEL_SIZE_PX };
+  }
+
+  return { max: MAX_PANEL_SIZE_PX, min: MIN_PANEL_SIZE_PX };
+};
+
+const clampSize = (region: WidgetRegion, sizePx: number): number => {
+  const { max, min } = getPanelSizeBounds(region);
+
+  return Math.min(max, Math.max(min, sizePx));
+};
+
+export const WidgetPanelFrame = ({
+  children,
+  instanceId,
+  region,
+  typeId,
+}: {
+  children: ReactNode;
+  instanceId?: WidgetInstanceId;
+  region: Exclude<WidgetRegion, 'center'>;
+  typeId?: WidgetTypeId;
+}) => {
+  const regionState = useActiveProjectSelector((project) => project.widgetRegions[region]);
+  const dispatch = useWorkbenchDispatch();
+  const [dragSizePx, setDragSizePx] = useState<number | null>(null);
+  const isLeft = region === 'left';
+  const isBottom = region === 'bottom';
+  const displaySizePx = dragSizePx ?? regionState.sizePx;
+  const sizeBounds = getPanelSizeBounds(region);
+  const focusRegionProps = useFocusRegionProps(region);
+
+  const commitSize = useCallback(
+    (sizePx: number) => {
+      const nextSizePx = clampSize(region, sizePx);
+
+      if (nextSizePx !== regionState.sizePx) {
+        dispatch({ region, sizePx: nextSizePx, type: 'setRegionWidgetSize' });
+      }
+    },
+    [dispatch, region, regionState.sizePx]
+  );
+
+  const handlePointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      event.preventDefault();
+
+      const startX = event.clientX;
+      const startY = event.clientY;
+      const startSizePx = regionState.sizePx;
+      let nextSizePx = startSizePx;
+      const direction = isLeft ? 1 : -1;
+
+      const handlePointerMove = (moveEvent: PointerEvent) => {
+        const deltaPx = isBottom ? startY - moveEvent.clientY : (moveEvent.clientX - startX) * direction;
+
+        nextSizePx = clampSize(region, startSizePx + deltaPx);
+        setDragSizePx(nextSizePx);
+      };
+
+      const handlePointerUp = () => {
+        window.removeEventListener('pointermove', handlePointerMove);
+        window.removeEventListener('pointerup', handlePointerUp);
+        window.removeEventListener('pointercancel', handlePointerUp);
+        setDragSizePx(null);
+        commitSize(nextSizePx);
+      };
+
+      window.addEventListener('pointermove', handlePointerMove);
+      window.addEventListener('pointerup', handlePointerUp);
+      window.addEventListener('pointercancel', handlePointerUp);
+    },
+    [commitSize, isBottom, isLeft, region, regionState.sizePx]
+  );
+
+  const handleKeyDown = useCallback(
+    (event: ReactKeyboardEvent<HTMLDivElement>) => {
+      const step = event.shiftKey ? PANEL_SIZE_STEP_PX * 2 : PANEL_SIZE_STEP_PX;
+      const sizeChanges: Partial<Record<string, number>> = isBottom
+        ? { ArrowDown: -step, ArrowUp: step, End: sizeBounds.max - displaySizePx, Home: sizeBounds.min - displaySizePx }
+        : {
+            ArrowLeft: isLeft ? -step : step,
+            ArrowRight: isLeft ? step : -step,
+            End: sizeBounds.max - displaySizePx,
+            Home: sizeBounds.min - displaySizePx,
+          };
+      const sizeChange = sizeChanges[event.key];
+
+      if (sizeChange === undefined) {
+        return;
+      }
+
+      event.preventDefault();
+      commitSize(displaySizePx + sizeChange);
+    },
+    [commitSize, displaySizePx, isBottom, isLeft, sizeBounds.max, sizeBounds.min]
+  );
+  const panelSizeProps = useMemo(
+    () => (isBottom ? { h: `${displaySizePx}px`, w: 'full' } : { h: 'full', w: `${displaySizePx}px` }),
+    [displaySizePx, isBottom]
+  );
+  const resizeOrientationProps = useMemo(
+    () => (isBottom ? { h: '2', left: '0', right: '0', top: '-1' } : { bottom: '0', top: '0', w: '2' }),
+    [isBottom]
+  );
+  const resizeSideProps = useMemo(
+    () => (!isBottom ? (isLeft ? { right: '-1' } : { left: '-1' }) : {}),
+    [isBottom, isLeft]
+  );
+
+  return (
+    <Flex
+      as="aside"
+      bg="bg.subtle"
+      borderColor="border.subtle"
+      borderRightWidth={isLeft ? '1px' : '0'}
+      borderLeftWidth={!isLeft && !isBottom ? '1px' : '0'}
+      borderTopWidth={isBottom ? '1px' : '0'}
+      direction="column"
+      flexShrink={0}
+      overflow="hidden"
+      minW="0"
+      data-hotkey-widget-instance-id={instanceId}
+      data-hotkey-widget-region={region}
+      data-hotkey-widget-type-id={typeId}
+      {...focusRegionProps}
+      {...panelSizeProps}
+    >
+      {children}
+      <Box
+        aria-label={`Resize ${region} widget panel`}
+        aria-orientation={isBottom ? 'horizontal' : 'vertical'}
+        aria-valuemax={sizeBounds.max}
+        aria-valuemin={sizeBounds.min}
+        aria-valuenow={displaySizePx}
+        as="div"
+        cursor={isBottom ? 'ns-resize' : 'ew-resize'}
+        opacity="0"
+        position="absolute"
+        role="separator"
+        tabIndex={0}
+        transition="opacity var(--wb-motion-duration-fast) ease, background var(--wb-motion-duration-fast) ease"
+        zIndex="1"
+        {...resizeOrientationProps}
+        {...resizeSideProps}
+        _hover={RESIZE_HANDLE_HOVER_PROPS}
+        _focusVisible={RESIZE_HANDLE_FOCUS_PROPS}
+        onKeyDown={handleKeyDown}
+        onPointerDown={handlePointerDown}
+      />
+    </Flex>
+  );
+};
+
+export const WidgetHeader = ({
+  actions,
+  instance,
+  manifest,
+  region,
+  runtime,
+}: {
+  actions?: ReactNode;
+  instance: WidgetInstanceRuntimeMeta;
+  manifest: WidgetManifest;
+  region: WorkbenchRegion;
+  runtime: WidgetRuntimeApi;
+}) => {
+  const { t } = useTranslation();
+  // Manifests may provide a component label (e.g. Workflow's editable
+  // `Workflow / [name]`); plain strings render as the standard title.
+  const HeaderLabel = manifest.headerLabel;
+  const label = resolveWidgetLabel(manifest, t);
+  const handleSettingsClick = useCallback(
+    () => openWorkbenchSettings(manifest.settingsSection),
+    [manifest.settingsSection]
+  );
+
+  return (
+    <HStack justify="space-between" borderBottomWidth={1} h={10} ps="3" pe="2">
+      <HStack flex="1" gap="1.5" minW="0">
+        {HeaderLabel ? (
+          <HeaderLabel region={region} />
+        ) : (
+          <Text fontSize="xs" fontWeight="700">
+            {label}
+          </Text>
+        )}
+      </HStack>
+      <HStack flexShrink={0} gap="1.5">
+        {actions}
+        {manifest.settingsSection ? (
+          <Tooltip content={t('widgets.settingsLabel', { label })}>
+            <IconButton
+              aria-label={t('widgets.settingsLabel', { label })}
+              color="fg.muted"
+              size="2xs"
+              variant="ghost"
+              onClick={handleSettingsClick}
+            >
+              <Icon as={SettingsIcon} boxSize="3.5" />
+            </IconButton>
+          </Tooltip>
+        ) : null}
+        <WidgetActionsMenu instance={instance} manifest={manifest} region={region} runtime={runtime} />
+      </HStack>
+    </HStack>
+  );
+};
+
+export const FieldPlaceholder = ({ label, h }: { label: string; h: string }) => (
+  <Stack gap="1">
+    <Text color="fg.muted" fontSize="2xs" fontWeight="600" textTransform="uppercase">
+      {label}
+    </Text>
+    <Box bg="bg.subtle" borderWidth="1px" borderColor="border.subtle" h={h} rounded="md" w="full" />
+  </Stack>
+);
+
+export const StatusWidgetChip = ({
+  children,
+  icon,
+  tone,
+}: {
+  children: ReactNode;
+  icon: LucideIcon;
+  tone?: NonNullable<RecipeVariantProps<typeof chipRecipe>>['tone'];
+}) => {
+  const recipe = useRecipe({ recipe: chipRecipe });
+
+  return (
+    <HStack css={recipe({ tone })}>
+      <Icon as={icon} boxSize="3" />
+      <Text whiteSpace="nowrap">{children}</Text>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetHosts.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetHosts.tsx
new file mode 100644
index 00000000000..29bf828f632
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetHosts.tsx
@@ -0,0 +1,11 @@
+import { getWidgetHosts } from '@workbench/widgetRegistry';
+
+export const WidgetHosts = () => (
+  <>
+    {getWidgetHosts().map((widget) => {
+      const Host = widget.manifest.host;
+
+      return Host ? <Host key={widget.manifest.id} /> : null;
+    })}
+  </>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetInstanceContextMenu.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetInstanceContextMenu.tsx
new file mode 100644
index 00000000000..5ca0c0b4361
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetInstanceContextMenu.tsx
@@ -0,0 +1,87 @@
+import { Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { XIcon } from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { WidgetEnableMenuItem } from './WidgetEnableMenu';
+
+export interface WidgetInstanceContextMenuTarget {
+  item: WidgetEnableMenuItem;
+  x: number;
+  y: number;
+}
+
+interface WidgetInstanceContextMenuProps {
+  target: WidgetInstanceContextMenuTarget | null;
+  isRemoveDisabled?: (item: WidgetEnableMenuItem) => boolean;
+  removeDisabledLabel?: string;
+  onClose: () => void;
+  onRemove: (item: WidgetEnableMenuItem) => void;
+}
+
+const REMOVE_DISABLED_PROPS = { opacity: 0.4 };
+
+export const WidgetInstanceContextMenu = ({
+  isRemoveDisabled,
+  onClose,
+  onRemove,
+  removeDisabledLabel = 'Required',
+  target,
+}: WidgetInstanceContextMenuProps) => {
+  const { t } = useTranslation();
+  const positioning = useMemo(
+    () => ({
+      getAnchorRect: () => (target ? { height: 1, width: 1, x: target.x, y: target.y } : null),
+      placement: 'bottom-start' as const,
+    }),
+    [target]
+  );
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+  const isDisabled = target ? isRemoveDisabled?.(target.item) === true : false;
+  const handleRemove = useCallback(() => {
+    if (target && isRemoveDisabled?.(target.item) !== true) {
+      onRemove(target.item);
+    }
+  }, [isRemoveDisabled, onRemove, target]);
+
+  return (
+    <Menu.Root
+      key={target?.item.id ?? 'closed'}
+      lazyMount
+      open={target !== null}
+      positioning={positioning}
+      unmountOnExit
+      onOpenChange={handleOpenChange}
+    >
+      <Portal>
+        <Menu.Positioner>
+          {target ? (
+            <Menu.Content minW="12rem">
+              <Menu.Item
+                value="remove-widget"
+                disabled={isDisabled}
+                _disabled={REMOVE_DISABLED_PROPS}
+                onClick={handleRemove}
+              >
+                <Icon as={XIcon} boxSize="3.5" />
+                <Menu.ItemText>{t('widgets.removeWidget', { label: target.item.label })}</Menu.ItemText>
+                {isDisabled ? (
+                  <Text color="fg.subtle" fontSize="2xs" ms="auto">
+                    {removeDisabledLabel}
+                  </Text>
+                ) : null}
+              </Menu.Item>
+            </Menu.Content>
+          ) : null}
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetLoadingFallback.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetLoadingFallback.tsx
new file mode 100644
index 00000000000..001e5a3693d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetLoadingFallback.tsx
@@ -0,0 +1,23 @@
+import type { WidgetViewProps } from '@workbench/types';
+
+import { Flex, HStack, Spinner, Text } from '@chakra-ui/react';
+
+export const WidgetLoadingFallback = ({ presentation }: { presentation: WidgetViewProps['presentation'] }) => {
+  if (presentation === 'compact' || presentation === 'tooltip') {
+    return (
+      <HStack color="fg.subtle" gap="1.5" px="2">
+        <Spinner size="xs" />
+        <Text fontSize="2xs">Loading</Text>
+      </HStack>
+    );
+  }
+
+  return (
+    <Flex align="center" color="fg.subtle" gap="2" h="full" justify="center" minH="8rem" w="full">
+      <Spinner size="sm" />
+      <Text fontSize="sm" fontWeight="600">
+        Loading widget
+      </Text>
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetRegionDropOverlay.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetRegionDropOverlay.tsx
new file mode 100644
index 00000000000..b3ef3c0bfff
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetRegionDropOverlay.tsx
@@ -0,0 +1,29 @@
+import type { WidgetRegionDropState } from '@workbench/widgetDnd';
+
+import { Box } from '@chakra-ui/react';
+
+export const WidgetRegionDropOverlay = ({
+  dropState,
+  isOver,
+}: {
+  dropState: WidgetRegionDropState;
+  isOver: boolean;
+}) => (
+  <Box
+    bg={dropState.isAllowed ? (isOver ? 'accent.subtle' : 'transparent') : 'bg.muted'}
+    borderColor={dropState.isAllowed ? 'accent.solid' : 'border.subtle'}
+    borderStyle="dashed"
+    borderWidth="2px"
+    bottom="0"
+    left="0"
+    opacity={dropState.isAllowed ? 0.96 : 0.5}
+    pointerEvents="none"
+    position="absolute"
+    right="0"
+    rounded="sm"
+    shadow={dropState.isAllowed && isOver ? '0 0 0 1px {colors.accent.solid}' : undefined}
+    top="0"
+    transition="background var(--wb-motion-duration-fast) ease, border-color var(--wb-motion-duration-fast) ease, opacity var(--wb-motion-duration-fast) ease, box-shadow var(--wb-motion-duration-fast) ease"
+    zIndex="2"
+  />
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetRenderer.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetRenderer.tsx
new file mode 100644
index 00000000000..bc1c786ac0f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetRenderer.tsx
@@ -0,0 +1,287 @@
+import type {
+  RegisteredWidget,
+  WidgetInstanceContract,
+  WidgetInstanceRuntimeMeta,
+  WidgetRuntimeApi,
+  WidgetViewProps,
+} from '@workbench/types';
+
+import { Box, Flex, Text } from '@chakra-ui/react';
+import { areWidgetPlacementProjectsEqual, getWidgetPlacementProject } from '@workbench/widgetPlacementMeta';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useWorkbenchWidgetRegistry } from '@workbench/WorkbenchWidgetRegistryContext';
+import { memo, Suspense, useMemo } from 'react';
+
+import { useWidgetRuntime } from './createWidgetRuntime';
+import { WidgetFailureBoundary } from './WidgetFailureBoundary';
+import { WidgetHeader, WidgetPanelFrame } from './WidgetFrames';
+import { WidgetLoadingFallback } from './WidgetLoadingFallback';
+import { areProjectWidgetRenderInstancesEqual } from './widgetRenderInstance';
+
+interface WidgetRendererProps extends Omit<WidgetViewProps, 'manifest' | 'runtime'> {
+  instance: WidgetInstanceContract;
+  widget: RegisteredWidget;
+}
+
+interface WidgetRendererByIdProps extends Omit<WidgetViewProps, 'instance' | 'manifest' | 'runtime'> {
+  instanceId: string;
+  widget: RegisteredWidget;
+}
+
+export const WidgetRendererById = ({ instanceId, widget, ...props }: WidgetRendererByIdProps) => {
+  const selection = useActiveProjectSelector(
+    (project) => ({ instance: project.widgetInstances[instanceId], projectId: project.id }),
+    areProjectWidgetRenderInstancesEqual
+  );
+
+  return selection.instance ? <WidgetRenderer instance={selection.instance} widget={widget} {...props} /> : null;
+};
+
+export const WidgetRenderer = ({ instance, presentation, region, widget }: WidgetRendererProps) => {
+  const dispatch = useWorkbenchDispatch();
+  const { getWidgetById, getWidgetsForRegion } = useWorkbenchWidgetRegistry();
+  const project = useActiveProjectSelector(getWidgetPlacementProject, areWidgetPlacementProjectsEqual);
+  const View = widget.manifest.view;
+  const instanceMeta: WidgetInstanceRuntimeMeta = useMemo(
+    () => ({
+      createdAt: instance.createdAt,
+      id: instance.id,
+      title: instance.title,
+      typeId: instance.typeId,
+    }),
+    [instance.createdAt, instance.id, instance.title, instance.typeId]
+  );
+  const runtime = useWidgetRuntime({
+    dispatch,
+    getWidgetById,
+    getWidgetsForRegion,
+    instance: instanceMeta,
+    project,
+    region,
+  });
+  const loadingFallback = useMemo(() => <WidgetLoadingFallback presentation={presentation} />, [presentation]);
+
+  if (!View) {
+    return null;
+  }
+
+  const content = (
+    <Suspense fallback={loadingFallback}>
+      <View
+        instance={instanceMeta}
+        manifest={widget.manifest}
+        presentation={presentation}
+        region={region}
+        runtime={runtime}
+      />
+    </Suspense>
+  );
+
+  return (
+    <WidgetShellFrame
+      instance={instanceMeta}
+      presentation={presentation}
+      region={region}
+      runtime={runtime}
+      widget={widget}
+    >
+      {content}
+    </WidgetShellFrame>
+  );
+};
+
+const WidgetShellFrame = ({
+  children,
+  instance,
+  presentation,
+  region,
+  runtime,
+  widget,
+}: {
+  children: React.ReactNode;
+  instance: WidgetInstanceRuntimeMeta;
+  presentation: WidgetViewProps['presentation'];
+  region: WidgetViewProps['region'];
+  runtime: WidgetRuntimeApi;
+  widget: RegisteredWidget;
+}) => {
+  const safeContent = (
+    <RenderFailureSlot instance={instance} widget={widget}>
+      {children}
+    </RenderFailureSlot>
+  );
+
+  if (region === 'popover' || region === 'dialog' || presentation === 'compact' || presentation === 'tooltip') {
+    return safeContent;
+  }
+
+  if (region === 'left' || region === 'right' || region === 'bottom') {
+    return (
+      <WidgetPanelFrame instanceId={instance.id} region={region} typeId={instance.typeId}>
+        <HeaderSlot instance={instance} presentation={presentation} region={region} runtime={runtime} widget={widget} />
+        <PanelBodySlot>{safeContent}</PanelBodySlot>
+        <FooterSlot instance={instance} presentation={presentation} region={region} runtime={runtime} widget={widget} />
+      </WidgetPanelFrame>
+    );
+  }
+
+  return (
+    <Flex
+      bg="bg.inset"
+      data-hotkey-widget-instance-id={instance.id}
+      data-hotkey-widget-region={region}
+      data-hotkey-widget-type-id={instance.typeId}
+      direction="column"
+      h="full"
+      minH="0"
+      w="full"
+    >
+      <HeaderSlot instance={instance} presentation={presentation} region={region} runtime={runtime} widget={widget} />
+      <Box flex="1" minH="0" overflow="hidden" position="relative">
+        {safeContent}
+      </Box>
+      <FooterSlot instance={instance} presentation={presentation} region={region} runtime={runtime} widget={widget} />
+    </Flex>
+  );
+};
+
+const RenderFailureSlot = ({
+  children,
+  instance,
+  widget,
+}: {
+  children: React.ReactNode;
+  instance: WidgetInstanceRuntimeMeta;
+  widget: RegisteredWidget;
+}) => {
+  if (!widget.manifest.failurePolicy.isolateRenderFailure) {
+    return children;
+  }
+
+  return (
+    <WidgetFailureBoundary resetKey={instance.id} widgetId={widget.manifest.id}>
+      {children}
+    </WidgetFailureBoundary>
+  );
+};
+
+const areWidgetChromeInstancesEqual = (left: WidgetInstanceRuntimeMeta, right: WidgetInstanceRuntimeMeta): boolean =>
+  left.id === right.id && left.typeId === right.typeId && left.title === right.title;
+
+const areSlotPropsEqual = (
+  left: {
+    instance: WidgetInstanceRuntimeMeta;
+    presentation: WidgetViewProps['presentation'];
+    region: WidgetViewProps['region'];
+    runtime: WidgetRuntimeApi;
+    widget: RegisteredWidget;
+  },
+  right: {
+    instance: WidgetInstanceRuntimeMeta;
+    presentation: WidgetViewProps['presentation'];
+    region: WidgetViewProps['region'];
+    runtime: WidgetRuntimeApi;
+    widget: RegisteredWidget;
+  }
+): boolean =>
+  left.presentation === right.presentation &&
+  left.region === right.region &&
+  left.widget === right.widget &&
+  left.runtime === right.runtime &&
+  areWidgetChromeInstancesEqual(left.instance, right.instance);
+
+const HeaderSlot = memo(function HeaderSlot({
+  instance,
+  presentation,
+  region,
+  runtime,
+  widget,
+}: {
+  instance: WidgetInstanceRuntimeMeta;
+  presentation: WidgetViewProps['presentation'];
+  region: WidgetViewProps['region'];
+  runtime: WidgetRuntimeApi;
+  widget: RegisteredWidget;
+}) {
+  const HeaderActions = widget.manifest.headerActions;
+  const actions = useMemo(
+    () =>
+      HeaderActions ? (
+        <HeaderActions
+          instance={instance}
+          manifest={widget.manifest}
+          presentation={presentation}
+          region={region}
+          runtime={runtime}
+        />
+      ) : null,
+    [HeaderActions, instance, presentation, region, runtime, widget.manifest]
+  );
+
+  if (widget.manifest.chrome?.header === 'hidden') {
+    return null;
+  }
+  const bg = region === 'center' ? 'bg' : 'bg.subtle';
+
+  return (
+    <Box bg={bg} flexShrink={0}>
+      <WidgetHeader
+        actions={actions}
+        instance={instance}
+        manifest={widget.manifest}
+        region={region}
+        runtime={runtime}
+      />
+    </Box>
+  );
+}, areSlotPropsEqual);
+
+const PanelBodySlot = ({ children }: { children: React.ReactNode }) => (
+  <Flex direction="column" flex="1" minH="0" minW="0" overflowX="hidden" overflowY="auto">
+    {children}
+  </Flex>
+);
+
+const FooterSlot = memo(function FooterSlot({
+  instance,
+  presentation,
+  region,
+  runtime,
+  widget,
+}: {
+  instance: WidgetInstanceRuntimeMeta;
+  presentation: WidgetViewProps['presentation'];
+  region: WidgetViewProps['region'];
+  runtime: WidgetRuntimeApi;
+  widget: RegisteredWidget;
+}) {
+  const Footer = widget.manifest.footer;
+
+  if (!Footer) {
+    return null;
+  }
+  const bg = region === 'center' ? 'bg.inset' : 'bg.subtle';
+
+  return (
+    <Box bg={bg} flexShrink={0}>
+      <Footer
+        instance={instance}
+        manifest={widget.manifest}
+        presentation={presentation}
+        region={region}
+        runtime={runtime}
+      />
+    </Box>
+  );
+}, areSlotPropsEqual);
+
+export const MissingWidgetFrame = ({ label, region }: { label: string; region: 'bottom' | 'left' | 'right' }) => (
+  <WidgetPanelFrame region={region}>
+    <Text fontSize="xs" fontWeight="700">
+      {label}
+    </Text>
+    <Text color="fg.subtle" fontSize="2xs">
+      Widget view unavailable.
+    </Text>
+  </WidgetPanelFrame>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetStrip.tsx b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetStrip.tsx
new file mode 100644
index 00000000000..c7b880d831d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/WidgetStrip.tsx
@@ -0,0 +1,46 @@
+import type { WidgetInstanceId, WidgetRegion } from '@workbench/types';
+import type { WidgetRegionDropState } from '@workbench/widgetDnd';
+
+import { Flex, type FlexProps } from '@chakra-ui/react';
+import { useDroppable } from '@dnd-kit/core';
+import { SortableContext, type SortingStrategy } from '@dnd-kit/sortable';
+import { getWidgetInstanceDragId, getWidgetRegionDropData, getWidgetRegionDropId } from '@workbench/widgetDnd';
+import { useMemo, type ReactNode } from 'react';
+
+import { WidgetRegionDropOverlay } from './WidgetRegionDropOverlay';
+
+interface WidgetStripProps extends FlexProps {
+  children: ReactNode;
+  dropState: WidgetRegionDropState;
+  region: WidgetRegion;
+  sortableInstanceIds: WidgetInstanceId[];
+  strategy: SortingStrategy;
+}
+
+export const WidgetStrip = ({
+  children,
+  dropState,
+  region,
+  sortableInstanceIds,
+  strategy,
+  ...props
+}: WidgetStripProps) => {
+  const { isOver, setNodeRef } = useDroppable({
+    data: getWidgetRegionDropData(region),
+    disabled: !dropState.isActive || !dropState.isAllowed,
+    id: getWidgetRegionDropId(region),
+  });
+  const sortableItems = useMemo(
+    () => sortableInstanceIds.map((id) => getWidgetInstanceDragId(region, id)),
+    [region, sortableInstanceIds]
+  );
+
+  return (
+    <Flex ref={setNodeRef} position="relative" {...props}>
+      <SortableContext items={sortableItems} strategy={strategy}>
+        {children}
+      </SortableContext>
+      {dropState.isActive ? <WidgetRegionDropOverlay dropState={dropState} isOver={isOver} /> : null}
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/createWidgetRuntime.test.ts b/invokeai/frontend/webv2/src/workbench/widget-frame/createWidgetRuntime.test.ts
new file mode 100644
index 00000000000..a677dfbdad1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/createWidgetRuntime.test.ts
@@ -0,0 +1,333 @@
+import type {
+  Project,
+  NormalizedWidgetManifest,
+  RegisteredWidget,
+  WidgetInstanceContract,
+  WidgetRegion,
+  WidgetTypeId,
+} from '@workbench/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import { clearProjectDiagnostics, configureDiagnostics, getProjectDiagnostics } from '@workbench/diagnostics/logger';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { cloneWidgetRuntimeState, createWidgetRuntime, getProjectWidgetRuntimeState } from './createWidgetRuntime';
+
+const TestIcon = () => null;
+const TestView = () => null;
+
+const createWidget = (
+  overrides: Partial<NormalizedWidgetManifest> & Pick<NormalizedWidgetManifest, 'id' | 'label'>
+): RegisteredWidget => ({
+  manifest: {
+    apiVersion: 1,
+    allowMultiple: false,
+    allowedRegions: ['left', 'right', 'center', 'bottom'],
+    bottomPanel: 'expandable',
+    centerPlacement: 'view',
+    failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+    icon: TestIcon,
+    state: { createInitial: () => ({}), persistence: 'project', version: 1 },
+    version: 1,
+    view: TestView,
+    ...overrides,
+  },
+  status: 'enabled',
+});
+
+const createInstance = (id = 'alpha', typeId: WidgetTypeId = 'alpha'): WidgetInstanceContract => ({
+  createdAt: '2026-01-01T00:00:00.000Z',
+  id,
+  state: { id: typeId, label: typeId, values: { current: true }, version: 1 },
+  typeId,
+});
+
+const createDispatch = () => {
+  const actions: WorkbenchAction[] = [];
+  const dispatch = (action: WorkbenchAction): void => {
+    actions.push(action);
+  };
+
+  return { actions, dispatch };
+};
+
+const createStateApi = () => ({
+  getSnapshot: () => ({ current: true }),
+  patch: vi.fn(),
+  set: vi.fn(),
+  useSelector: vi.fn(),
+});
+
+const createRegistry =
+  (widgetsByRegion: Partial<Record<WidgetRegion, RegisteredWidget[]>>) =>
+  (region: WidgetRegion): RegisteredWidget[] =>
+    widgetsByRegion[region] ?? [];
+
+const createPlacementProject = (
+  overrides: Partial<Pick<Project, 'widgetInstances' | 'widgetRegions'>> = {}
+): Pick<Project, 'widgetInstances' | 'widgetRegions'> & { projectId: string } => ({
+  projectId: 'project-1',
+  widgetInstances: {
+    alpha: createInstance('alpha'),
+    beta: createInstance('beta', 'beta'),
+    ...overrides.widgetInstances,
+  },
+  widgetRegions: {
+    bottom: { activeInstanceId: 'alpha', instanceIds: [], isCollapsed: false, sizePx: 240 },
+    center: { activeInstanceId: 'alpha', instanceIds: [], isCollapsed: false, sizePx: 240 },
+    left: { activeInstanceId: 'alpha', instanceIds: [], isCollapsed: false, sizePx: 240 },
+    right: { activeInstanceId: 'alpha', instanceIds: ['alpha'], isCollapsed: false, sizePx: 240 },
+    ...overrides.widgetRegions,
+  },
+});
+
+describe('createWidgetRuntime', () => {
+  beforeEach(() => {
+    clearProjectDiagnostics('project-1');
+    configureDiagnostics({
+      enabled: true,
+      level: 'trace',
+      namespaces: ['workflows'],
+      performanceTimingsEnabled: false,
+    });
+  });
+
+  it('deep clones runtime state snapshots', () => {
+    const values = { nested: { mutable: 'before' }, tags: ['before'] };
+    const snapshot = cloneWidgetRuntimeState(values);
+
+    values.nested.mutable = 'after';
+    values.tags[0] = 'after';
+
+    expect(snapshot).toEqual({ nested: { mutable: 'before' }, tags: ['before'] });
+  });
+
+  it('returns an empty runtime state snapshot when the scoped project is missing', () => {
+    expect(getProjectWidgetRuntimeState([], 'missing-project', 'generate')).toEqual({});
+  });
+
+  it('exposes widget state reads and writes through the state namespace', () => {
+    const { actions, dispatch } = createDispatch();
+    const state = createStateApi();
+    const runtime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance(),
+      project: createPlacementProject(),
+      region: 'right',
+      state,
+    });
+
+    runtime.state.patch({ next: true });
+    runtime.state.set({ replaced: true });
+
+    expect(actions).toEqual([]);
+    expect(state.getSnapshot()).toEqual({ current: true });
+    expect(state.patch).toHaveBeenCalledWith({ next: true });
+    expect(state.set).toHaveBeenCalledWith({ replaced: true });
+  });
+
+  it('binds diagnostics to the current widget source', () => {
+    const { dispatch } = createDispatch();
+    const runtime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance('workflow:center', 'workflow'),
+      project: createPlacementProject(),
+      region: 'center',
+      state: createStateApi(),
+    });
+
+    runtime.diagnostics.logger('workflows').info('Widget rendered');
+
+    expect(getProjectDiagnostics('project-1')).toMatchObject([
+      {
+        level: 'info',
+        message: 'Widget rendered',
+        namespace: 'workflows',
+        source: {
+          instanceId: 'workflow:center',
+          kind: 'widget',
+          projectId: 'project-1',
+          region: 'center',
+          typeId: 'workflow',
+        },
+      },
+    ]);
+  });
+
+  it('opens widgets through canonical validation and seeded initial values', () => {
+    const { actions, dispatch } = createDispatch();
+    const createInitial = vi.fn(() => ({ seeded: true }));
+    const runtime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({
+        bottom: [createWidget({ bottomPanel: 'tooltip', id: 'tooltip-widget', label: 'Tooltip Widget' })],
+        center: [createWidget({ centerPlacement: 'toolbar', id: 'toolbar-widget', label: 'Toolbar Widget' })],
+        right: [
+          createWidget({
+            id: 'panel-widget',
+            label: 'Panel Widget',
+            state: { createInitial, persistence: 'project', version: 1 },
+          }),
+        ],
+      }),
+      instance: createInstance(),
+      project: createPlacementProject(),
+      region: 'right',
+      state: createStateApi(),
+    });
+
+    expect(runtime.workbench.openWidget('panel-widget', { preferredRegions: ['right'] })).toEqual({
+      ok: true,
+      region: 'right',
+    });
+    expect(runtime.workbench.openWidget('tooltip-widget', { preferredRegions: ['bottom'] })).toEqual({
+      ok: false,
+      reason: 'unavailable',
+    });
+    expect(runtime.workbench.openWidget('toolbar-widget', { preferredRegions: ['center'] })).toEqual({
+      ok: false,
+      reason: 'unavailable',
+    });
+    expect(runtime.workbench.openWidget('missing-widget', { preferredRegions: ['right'] })).toEqual({
+      ok: false,
+      reason: 'unavailable',
+    });
+
+    expect(createInitial).toHaveBeenCalledTimes(1);
+    expect(actions).toEqual([
+      {
+        createNew: undefined,
+        initialValues: { seeded: true },
+        projectId: 'project-1',
+        region: 'right',
+        type: 'openRegionWidget',
+        widgetId: 'panel-widget',
+      },
+    ]);
+  });
+
+  it('dispatches own-region close and reveal actions', () => {
+    const { actions, dispatch } = createDispatch();
+    const runtime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: (typeId) => createWidget({ id: typeId, label: typeId }),
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance(),
+      project: createPlacementProject({
+        widgetRegions: {
+          bottom: { activeInstanceId: 'alpha', instanceIds: ['alpha', 'beta'], isCollapsed: false, sizePx: 240 },
+          center: { activeInstanceId: 'alpha', instanceIds: [], isCollapsed: false, sizePx: 240 },
+          left: { activeInstanceId: 'alpha', instanceIds: [], isCollapsed: false, sizePx: 240 },
+          right: { activeInstanceId: 'alpha', instanceIds: [], isCollapsed: false, sizePx: 240 },
+        },
+      }),
+      region: 'bottom',
+      state: createStateApi(),
+    });
+
+    expect(runtime.workbench.revealWidgetInstance('beta')).toEqual({ ok: true, region: 'bottom' });
+    expect(runtime.workbench.closeWidgetInstance('beta')).toEqual({ ok: true, region: 'bottom' });
+    expect(actions).toEqual([
+      { projectId: 'project-1', region: 'bottom', type: 'selectRegionWidget', widgetId: 'beta' },
+      { projectId: 'project-1', region: 'bottom', type: 'toggleRegionWidget', widgetId: 'beta' },
+    ]);
+  });
+
+  it('returns unsupported for cross-region close and reveal', () => {
+    const { actions, dispatch } = createDispatch();
+    const runtime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance(),
+      project: createPlacementProject(),
+      region: 'right',
+      state: createStateApi(),
+    });
+
+    expect(runtime.workbench.revealWidgetInstance('beta')).toEqual({ ok: false, reason: 'unsupported' });
+    expect(runtime.workbench.closeWidgetInstance('beta')).toEqual({ ok: false, reason: 'unsupported' });
+    expect(actions).toEqual([]);
+  });
+
+  it('executes commands registered by the current widget source', async () => {
+    const { dispatch } = createDispatch();
+    const alphaRuntime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance('alpha', 'test-widget'),
+      project: createPlacementProject(),
+      region: 'right',
+      state: createStateApi(),
+    });
+    const betaRuntime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance('beta', 'test-widget'),
+      project: createPlacementProject(),
+      region: 'right',
+      state: createStateApi(),
+    });
+    const disposeAlpha = alphaRuntime.commands.register({
+      handler: () => 'alpha',
+      id: 'test-widget.shared-command',
+      title: 'Shared command',
+    });
+    const disposeBeta = betaRuntime.commands.register({
+      handler: () => 'beta',
+      id: 'test-widget.shared-command',
+      title: 'Shared command',
+    });
+
+    await expect(alphaRuntime.commands.execute('test-widget.shared-command')).resolves.toBe('alpha');
+    await expect(betaRuntime.commands.execute('test-widget.shared-command')).resolves.toBe('beta');
+
+    disposeAlpha();
+    disposeBeta();
+  });
+
+  it('does not execute commands registered by the same widget instance in another project', async () => {
+    const { dispatch } = createDispatch();
+    const projectOneRuntime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance('alpha', 'test-widget'),
+      project: createPlacementProject({}),
+      region: 'right',
+      state: createStateApi(),
+    });
+    const projectTwoRuntime = createWidgetRuntime({
+      dispatch,
+      getWidgetById: () => undefined,
+      getWidgetsForRegion: createRegistry({}),
+      instance: createInstance('alpha', 'test-widget'),
+      project: { ...createPlacementProject({}), projectId: 'project-2' },
+      region: 'right',
+      state: createStateApi(),
+    });
+    const disposeOne = projectOneRuntime.commands.register({
+      handler: () => 'project-1',
+      id: 'test-widget.project-command',
+      title: 'Project command',
+    });
+    const disposeTwo = projectTwoRuntime.commands.register({
+      handler: () => 'project-2',
+      id: 'test-widget.project-command',
+      title: 'Project command',
+    });
+
+    await expect(projectOneRuntime.commands.execute('test-widget.project-command')).resolves.toBe('project-1');
+    await expect(projectTwoRuntime.commands.execute('test-widget.project-command')).resolves.toBe('project-2');
+
+    disposeOne();
+    disposeTwo();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/createWidgetRuntime.ts b/invokeai/frontend/webv2/src/workbench/widget-frame/createWidgetRuntime.ts
new file mode 100644
index 00000000000..9eb3e095af0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/createWidgetRuntime.ts
@@ -0,0 +1,199 @@
+/* eslint-disable react/react-compiler */
+import type {
+  Project,
+  WidgetHotkeyApi,
+  OpenWorkbenchWidgetOptions,
+  RegisteredWidget,
+  WidgetContributionSource,
+  WidgetInstanceRuntimeMeta,
+  WidgetRegion,
+  WidgetRuntimeStateApi,
+  WidgetRuntimeApi,
+  WidgetTypeId,
+  WorkbenchRegion,
+} from '@workbench/types';
+import type { WidgetPlacementProject } from '@workbench/widgetPlacementCommands';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import { createProjectLogger } from '@workbench/diagnostics/logger';
+import {
+  commandApi as sharedCommandApi,
+  commandPaletteApi,
+  hotkeyApi,
+  menuApi,
+  searchApi,
+  toolbarApi,
+} from '@workbench/extensions/extensionApi';
+import { closeWidgetPlacement, openWidgetPlacement, revealWidgetPlacement } from '@workbench/widgetPlacementCommands';
+import { useProjectWidgetInstanceValuesSelector, useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useMemo, type Dispatch } from 'react';
+
+const WIDGET_REGIONS = new Set<WidgetRegion>(['bottom', 'center', 'left', 'right']);
+
+const isWidgetRegion = (region: WorkbenchRegion): region is WidgetRegion => WIDGET_REGIONS.has(region as WidgetRegion);
+
+const cloneWidgetRuntimeValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(cloneWidgetRuntimeValue);
+  }
+
+  if (value instanceof Map) {
+    return new Map(Array.from(value, ([key, item]) => [key, cloneWidgetRuntimeValue(item)]));
+  }
+
+  if (value instanceof Set) {
+    return new Set(Array.from(value, cloneWidgetRuntimeValue));
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, cloneWidgetRuntimeValue(item)])
+    );
+  }
+
+  return value;
+};
+
+export const cloneWidgetRuntimeState = <State extends Record<string, unknown>>(state: State): State => {
+  try {
+    return structuredClone(state) as State;
+  } catch {
+    return cloneWidgetRuntimeValue(state) as State;
+  }
+};
+
+export const getProjectWidgetRuntimeState = <State extends Record<string, unknown>>(
+  projects: readonly Project[],
+  projectId: string,
+  instanceId: string
+): State =>
+  cloneWidgetRuntimeState(
+    (projects.find((project) => project.id === projectId)?.widgetInstances[instanceId]?.state.values ?? {}) as State
+  );
+
+export const createWidgetRuntime = ({
+  dispatch,
+  getWidgetsForRegion,
+  getWidgetById,
+  instance,
+  project,
+  region,
+  state,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  getWidgetById: (typeId: WidgetTypeId) => RegisteredWidget | undefined;
+  getWidgetsForRegion: (region: WidgetRegion) => RegisteredWidget[];
+  instance: WidgetInstanceRuntimeMeta;
+  project: WidgetPlacementProject;
+  region: WorkbenchRegion;
+  state: WidgetRuntimeStateApi;
+}): WidgetRuntimeApi => {
+  const sourceProjectId = project.projectId ?? '';
+  const source: WidgetContributionSource = {
+    instanceId: instance.id,
+    projectId: sourceProjectId,
+    region,
+    typeId: instance.typeId,
+  };
+  const commands = {
+    execute: (commandId, ...args) => sharedCommandApi.executeForSource(commandId, source, ...args),
+    executeForSource: sharedCommandApi.executeForSource,
+    register: (command) => sharedCommandApi.register({ ...command, source }),
+  } satisfies WidgetRuntimeApi['commands'];
+  const hotkeys: WidgetHotkeyApi = {
+    register: (hotkey) =>
+      hotkeyApi.register({
+        ...hotkey,
+        scope: hotkey.scope ?? 'widget',
+        source,
+      }),
+  };
+  const menus = {
+    register: (menu) => menuApi.register({ ...menu, source }),
+  } satisfies WidgetRuntimeApi['menus'];
+  const diagnostics = {
+    logger: (namespace) => createProjectLogger(namespace, { ...source, kind: 'widget' }),
+  } satisfies WidgetRuntimeApi['diagnostics'];
+
+  return {
+    commands,
+    diagnostics,
+    hotkeys,
+    instanceId: instance.id,
+    menus,
+    palette: commandPaletteApi,
+    region,
+    search: searchApi,
+    state,
+    toolbars: toolbarApi,
+    typeId: instance.typeId,
+    workbench: {
+      closeWidgetInstance: (instanceId) => {
+        if (!isWidgetRegion(region)) {
+          return { ok: false, reason: 'unsupported' };
+        }
+
+        return closeWidgetPlacement({ dispatch, getWidgetById, instanceId, project, region });
+      },
+      openWidget: (typeId: WidgetTypeId, options?: OpenWorkbenchWidgetOptions) =>
+        openWidgetPlacement({ dispatch, getWidgetsForRegion, options, projectId: project.projectId, typeId }),
+      revealWidgetInstance: (instanceId) => {
+        if (!isWidgetRegion(region)) {
+          return { ok: false, reason: 'unsupported' };
+        }
+
+        return revealWidgetPlacement({ dispatch, instanceId, project, region });
+      },
+    },
+  };
+};
+
+export const useWidgetRuntime = ({
+  dispatch,
+  getWidgetsForRegion,
+  getWidgetById,
+  instance,
+  project,
+  region,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  getWidgetById: (typeId: WidgetTypeId) => RegisteredWidget | undefined;
+  getWidgetsForRegion: (region: WidgetRegion) => RegisteredWidget[];
+  instance: WidgetInstanceRuntimeMeta;
+  project: WidgetPlacementProject;
+  region: WorkbenchRegion;
+}): WidgetRuntimeApi => {
+  const store = useWorkbenchStore();
+  const projectId = project.projectId ?? store.getSnapshot().activeProject.id;
+  const state = useMemo<WidgetRuntimeStateApi>(
+    () => ({
+      getSnapshot: () => getProjectWidgetRuntimeState(store.getState().projects, projectId, instance.id),
+      patch: (values) =>
+        dispatch({
+          instanceId: instance.id,
+          projectId,
+          type: 'patchWidgetInstanceValues',
+          values: cloneWidgetRuntimeState(values),
+        }),
+      set: (values) =>
+        dispatch({
+          instanceId: instance.id,
+          projectId,
+          type: 'setWidgetInstanceValues',
+          values: cloneWidgetRuntimeState(values),
+        }),
+      useSelector<Selected>(
+        selector: (state: Record<string, unknown>) => Selected,
+        isEqual?: (left: Selected, right: Selected) => boolean
+      ): Selected {
+        return useProjectWidgetInstanceValuesSelector(projectId, instance.id, selector, isEqual);
+      },
+    }),
+    [dispatch, instance.id, projectId, store]
+  );
+
+  return useMemo(
+    () => createWidgetRuntime({ dispatch, getWidgetById, getWidgetsForRegion, instance, project, region, state }),
+    [dispatch, getWidgetById, getWidgetsForRegion, instance, project, region, state]
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/index.ts b/invokeai/frontend/webv2/src/workbench/widget-frame/index.ts
new file mode 100644
index 00000000000..c0536106a36
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/index.ts
@@ -0,0 +1,10 @@
+export { WidgetActionsMenu } from './WidgetActionsMenu';
+export { WidgetBar, type WidgetBarItem } from './WidgetBar';
+export { WidgetEnableMenu, type WidgetEnableMenuItem } from './WidgetEnableMenu';
+export { WidgetFailureBoundary } from './WidgetFailureBoundary';
+export { FieldPlaceholder, StatusWidgetChip, WidgetHeader, WidgetPanelFrame } from './WidgetFrames';
+export { WidgetInstanceContextMenu, type WidgetInstanceContextMenuTarget } from './WidgetInstanceContextMenu';
+export { WidgetRegionDropOverlay } from './WidgetRegionDropOverlay';
+export { WidgetStrip } from './WidgetStrip';
+export { MissingWidgetFrame, WidgetRenderer, WidgetRendererById } from './WidgetRenderer';
+export { useWidgetSortable } from './useWidgetSortable';
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/useWidgetSortable.ts b/invokeai/frontend/webv2/src/workbench/widget-frame/useWidgetSortable.ts
new file mode 100644
index 00000000000..89ec5f76b76
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/useWidgetSortable.ts
@@ -0,0 +1,36 @@
+import type { WidgetInstanceId, WidgetRegion, WidgetTypeId } from '@workbench/types';
+import type { CSSProperties } from 'react';
+
+import { useSortable } from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import { getWidgetInstanceDragData, getWidgetInstanceDragId } from '@workbench/widgetDnd';
+
+export const useWidgetSortable = ({
+  disabled,
+  instanceId,
+  region,
+  typeId,
+}: {
+  region: WidgetRegion;
+  instanceId: WidgetInstanceId;
+  typeId: WidgetTypeId;
+  disabled?: boolean;
+}): {
+  setNodeRef: ReturnType<typeof useSortable>['setNodeRef'];
+  style: CSSProperties;
+  dragHandleProps: Record<string, unknown>;
+  isDragging: boolean;
+} => {
+  const { attributes, isDragging, listeners, setNodeRef, transform, transition } = useSortable({
+    data: getWidgetInstanceDragData(region, instanceId, typeId),
+    disabled,
+    id: getWidgetInstanceDragId(region, instanceId),
+  });
+
+  return {
+    dragHandleProps: { ...attributes, ...listeners },
+    isDragging,
+    setNodeRef,
+    style: { transform: CSS.Transform.toString(transform), transition },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/widgetRenderInstance.test.ts b/invokeai/frontend/webv2/src/workbench/widget-frame/widgetRenderInstance.test.ts
new file mode 100644
index 00000000000..9ea057e5b82
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/widgetRenderInstance.test.ts
@@ -0,0 +1,24 @@
+import type { WidgetInstanceContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { areProjectWidgetRenderInstancesEqual } from './widgetRenderInstance';
+
+const instance: WidgetInstanceContract = {
+  createdAt: '2026-01-01T00:00:00.000Z',
+  id: 'generate',
+  state: { id: 'generate', label: 'Generate', values: {}, version: 1 },
+  title: 'Generate',
+  typeId: 'generate',
+};
+
+describe('areProjectWidgetRenderInstancesEqual', () => {
+  it('treats same instance metadata in different projects as different render inputs', () => {
+    expect(
+      areProjectWidgetRenderInstancesEqual(
+        { instance, projectId: 'project-a' },
+        { instance: { ...instance }, projectId: 'project-b' }
+      )
+    ).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widget-frame/widgetRenderInstance.ts b/invokeai/frontend/webv2/src/workbench/widget-frame/widgetRenderInstance.ts
new file mode 100644
index 00000000000..4e4b613a776
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widget-frame/widgetRenderInstance.ts
@@ -0,0 +1,23 @@
+import type { WidgetInstanceContract } from '@workbench/types';
+
+export interface ProjectWidgetRenderInstance {
+  instance: WidgetInstanceContract | undefined;
+  projectId: string;
+}
+
+export const areWidgetRenderInstancesEqual = (
+  left: WidgetInstanceContract | undefined,
+  right: WidgetInstanceContract | undefined
+): boolean =>
+  left === right ||
+  (left !== undefined &&
+    right !== undefined &&
+    left.id === right.id &&
+    left.typeId === right.typeId &&
+    left.title === right.title &&
+    left.createdAt === right.createdAt);
+
+export const areProjectWidgetRenderInstancesEqual = (
+  left: ProjectWidgetRenderInstance,
+  right: ProjectWidgetRenderInstance
+): boolean => left.projectId === right.projectId && areWidgetRenderInstancesEqual(left.instance, right.instance);
diff --git a/invokeai/frontend/webv2/src/workbench/widgetDnd.test.ts b/invokeai/frontend/webv2/src/workbench/widgetDnd.test.ts
new file mode 100644
index 00000000000..2f7a0dd7e37
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetDnd.test.ts
@@ -0,0 +1,341 @@
+import type { CollisionDetection, DroppableContainer } from '@dnd-kit/core';
+
+import { describe, expect, it } from 'vitest';
+
+import type { Project, WidgetTypeId, WorkbenchState } from './types';
+
+import {
+  getRegionDropState,
+  getWidgetInstanceDragData,
+  getWidgetInstanceDragId,
+  getWidgetRegionDropData,
+  resolveWidgetDragEnd,
+  widgetCollisionDetection,
+} from './widgetDnd';
+import { getCanvasImageDropData } from './widgets/canvas/canvasImageDnd';
+import { getGalleryImageDragData } from './widgets/gallery/galleryDnd';
+import { createInitialWorkbenchState } from './workbenchState';
+
+type CollisionArgs = Parameters<CollisionDetection>[0];
+
+const getRect = (left: number, top: number, width: number, height: number) => ({
+  bottom: top + height,
+  height,
+  left,
+  right: left + width,
+  top,
+  width,
+});
+
+const createDroppable = (id: string, data: object, rect: ReturnType<typeof getRect>): DroppableContainer => ({
+  data: { current: data as Record<string, unknown> },
+  disabled: false,
+  id,
+  key: id,
+  node: { current: null },
+  rect: { current: rect },
+});
+
+const createCollisionArgs = (options: {
+  activeData: object;
+  collisionRect?: ReturnType<typeof getRect>;
+  droppables: Array<{ data: object; id: string; rect: ReturnType<typeof getRect> }>;
+  pointerCoordinates: { x: number; y: number } | null;
+}): CollisionArgs => {
+  const collisionRect = options.collisionRect ?? getRect(45, 45, 10, 10);
+
+  return {
+    active: {
+      data: { current: options.activeData as Record<string, unknown> },
+      id: 'active',
+      rect: { current: { initial: collisionRect, translated: collisionRect } },
+    },
+    collisionRect,
+    droppableContainers: options.droppables.map(({ data, id, rect }) => createDroppable(id, data, rect)),
+    droppableRects: new Map(options.droppables.map(({ id, rect }) => [id, rect])),
+    pointerCoordinates: options.pointerCoordinates,
+  };
+};
+
+const getWidget = (typeId: WidgetTypeId) => {
+  const widgets: Partial<
+    Record<
+      WidgetTypeId,
+      { manifest: { allowedRegions: Array<'left' | 'right' | 'center' | 'bottom'>; allowMultiple: boolean } }
+    >
+  > = {
+    canvas: { manifest: { allowedRegions: ['center'], allowMultiple: false } },
+    preview: { manifest: { allowedRegions: ['center', 'right'], allowMultiple: false } },
+  };
+
+  return widgets[typeId];
+};
+
+const getActiveProject = (state: WorkbenchState): Project => {
+  const project = state.projects.find((candidate) => candidate.id === state.activeProjectId);
+
+  expect(project).toBeDefined();
+
+  return project as Project;
+};
+
+const createProjectWithPreviewInCenterAndRight = (): Project => {
+  const project = getActiveProject(createInitialWorkbenchState());
+
+  return {
+    ...project,
+    widgetRegions: {
+      ...project.widgetRegions,
+      center: { ...project.widgetRegions.center, activeInstanceId: 'preview', instanceIds: ['canvas', 'preview'] },
+      right: { ...project.widgetRegions.right, activeInstanceId: 'preview', instanceIds: ['preview', 'layers'] },
+    },
+  };
+};
+
+describe('widget dnd helpers', () => {
+  it('uses region-scoped draggable ids for duplicated widget instances', () => {
+    expect(getWidgetInstanceDragId('center', 'preview')).not.toBe(getWidgetInstanceDragId('right', 'preview'));
+  });
+
+  it('does not treat a duplicate instance in another region as a same-region reorder', () => {
+    const project = createProjectWithPreviewInCenterAndRight();
+    const resolution = resolveWidgetDragEnd(
+      project,
+      getWidgetInstanceDragData('center', 'preview', 'preview'),
+      getWidgetInstanceDragData('right', 'preview', 'preview'),
+      getWidget
+    );
+
+    expect(resolution).toBeNull();
+  });
+
+  it('reorders only within the active source region', () => {
+    const project = createProjectWithPreviewInCenterAndRight();
+    const resolution = resolveWidgetDragEnd(
+      project,
+      getWidgetInstanceDragData('center', 'preview', 'preview'),
+      getWidgetInstanceDragData('center', 'canvas', 'canvas'),
+      getWidget
+    );
+
+    expect(resolution).toEqual({
+      activeInstanceId: 'preview',
+      instanceIds: ['preview', 'canvas'],
+      region: 'center',
+      type: 'reorder',
+    });
+  });
+
+  it('disables a non-source region that already contains the dragged singleton instance', () => {
+    const project = createProjectWithPreviewInCenterAndRight();
+    const dropState = getRegionDropState(
+      project,
+      {
+        fromRegion: 'center',
+        icon: () => null,
+        instanceId: 'preview',
+        label: 'Preview',
+        typeId: 'preview',
+      },
+      'right',
+      getWidget
+    );
+
+    expect(dropState).toMatchObject({ helperText: 'Already placed', isActive: true, isAllowed: false });
+  });
+
+  it('ignores source region bar collisions so sorting only reacts to widget items', () => {
+    const project = createProjectWithPreviewInCenterAndRight();
+    const resolution = resolveWidgetDragEnd(
+      project,
+      getWidgetInstanceDragData('center', 'canvas', 'canvas'),
+      getWidgetRegionDropData('center'),
+      getWidget
+    );
+
+    expect(resolution).toBeNull();
+  });
+
+  it('moves to another eligible region when dropped on that region bar', () => {
+    const project = getActiveProject(createInitialWorkbenchState());
+    const projectWithoutRightPreview = {
+      ...project,
+      widgetRegions: {
+        ...project.widgetRegions,
+        right: {
+          ...project.widgetRegions.right,
+          instanceIds: project.widgetRegions.right.instanceIds.filter((instanceId) => instanceId !== 'preview'),
+        },
+      },
+    };
+    const resolution = resolveWidgetDragEnd(
+      projectWithoutRightPreview,
+      getWidgetInstanceDragData('center', 'preview', 'preview'),
+      getWidgetRegionDropData('right'),
+      getWidget
+    );
+
+    expect(resolution).toEqual({
+      fromRegion: 'center',
+      instanceId: 'preview',
+      toIndex: projectWithoutRightPreview.widgetRegions.right.instanceIds.length,
+      toRegion: 'right',
+      type: 'move',
+    });
+  });
+});
+
+describe('widget collision detection', () => {
+  const outerRect = getRect(0, 0, 100, 100);
+  const innerRect = getRect(25, 25, 50, 50);
+  const pointerCoordinates = { x: 50, y: 50 };
+
+  it('routes a gallery image drag to an inner canvas target instead of its enclosing widget', () => {
+    const collisions = widgetCollisionDetection(
+      createCollisionArgs({
+        activeData: getGalleryImageDragData([{ boardId: 'none', imageName: 'image.png' }]),
+        droppables: [
+          {
+            data: getWidgetInstanceDragData('center', 'canvas', 'canvas'),
+            id: 'canvas-widget',
+            rect: outerRect,
+          },
+          { data: getWidgetRegionDropData('center'), id: 'center-region', rect: outerRect },
+          { data: getCanvasImageDropData('raster'), id: 'canvas-raster-target', rect: innerRect },
+          { data: { kind: 'future-target' }, id: 'future-target', rect: innerRect },
+        ],
+        pointerCoordinates,
+      })
+    );
+
+    expect(collisions.map(({ id }) => id)).toEqual(['canvas-raster-target', 'future-target']);
+  });
+
+  it('keeps widget instances ahead of overlapping non-widget targets for widget drags', () => {
+    const activeData = getWidgetInstanceDragData('center', 'preview', 'preview');
+    const collisions = widgetCollisionDetection(
+      createCollisionArgs({
+        activeData,
+        droppables: [
+          { data: getWidgetInstanceDragData('center', 'canvas', 'canvas'), id: 'canvas-widget', rect: outerRect },
+          { data: getCanvasImageDropData('raster'), id: 'canvas-raster-target', rect: innerRect },
+        ],
+        pointerCoordinates,
+      })
+    );
+
+    expect(collisions.map(({ id }) => id)).toEqual(['canvas-widget']);
+  });
+
+  it('keeps widget regions ahead of overlapping non-widget targets for widget drags', () => {
+    const activeData = getWidgetInstanceDragData('center', 'preview', 'preview');
+    const collisions = widgetCollisionDetection(
+      createCollisionArgs({
+        activeData,
+        droppables: [
+          { data: getWidgetRegionDropData('right'), id: 'right-region', rect: outerRect },
+          { data: getCanvasImageDropData('raster'), id: 'canvas-raster-target', rect: innerRect },
+        ],
+        pointerCoordinates,
+      })
+    );
+
+    expect(collisions.map(({ id }) => id)).toEqual(['right-region']);
+  });
+
+  it('uses same-region widget geometry instead of the source-region bar', () => {
+    const activeData = getWidgetInstanceDragData('center', 'preview', 'preview');
+    const collisions = widgetCollisionDetection(
+      createCollisionArgs({
+        activeData,
+        collisionRect: getRect(90, 90, 20, 20),
+        droppables: [
+          { data: activeData, id: 'active-widget', rect: getRect(0, 0, 20, 20) },
+          {
+            data: getWidgetInstanceDragData('center', 'canvas', 'canvas'),
+            id: 'other-center-widget',
+            rect: getRect(100, 100, 20, 20),
+          },
+          { data: getWidgetRegionDropData('center'), id: 'center-region', rect: getRect(40, 40, 20, 20) },
+        ],
+        pointerCoordinates,
+      })
+    );
+
+    expect(collisions.map(({ id }) => id)).toEqual(['other-center-widget']);
+  });
+
+  it('treats malformed widget active data as a non-widget drag', () => {
+    const collisions = widgetCollisionDetection(
+      createCollisionArgs({
+        activeData: { instanceId: 'preview', kind: 'widget-instance', region: 'center' },
+        droppables: [
+          { data: getWidgetInstanceDragData('center', 'canvas', 'canvas'), id: 'canvas-widget', rect: outerRect },
+          { data: getCanvasImageDropData('raster'), id: 'canvas-raster-target', rect: innerRect },
+        ],
+        pointerCoordinates,
+      })
+    );
+
+    expect(collisions.map(({ id }) => id)).toEqual(['canvas-raster-target']);
+  });
+
+  it('excludes widget droppables from the no-pointer closest-center fallback for non-widget drags', () => {
+    const collisions = widgetCollisionDetection(
+      createCollisionArgs({
+        activeData: getGalleryImageDragData([{ boardId: 'none', imageName: 'image.png' }]),
+        collisionRect: getRect(0, 0, 20, 20),
+        droppables: [
+          {
+            data: getWidgetInstanceDragData('center', 'canvas', 'canvas'),
+            id: 'canvas-widget',
+            rect: getRect(0, 0, 20, 20),
+          },
+          {
+            data: getWidgetRegionDropData('center'),
+            id: 'center-region',
+            rect: getRect(20, 20, 20, 20),
+          },
+          {
+            data: getCanvasImageDropData('raster'),
+            id: 'canvas-raster-target',
+            rect: getRect(100, 100, 20, 20),
+          },
+          { data: { kind: 'future-target' }, id: 'future-target', rect: getRect(100, 100, 20, 20) },
+        ],
+        pointerCoordinates: null,
+      })
+    );
+
+    expect(collisions.map(({ id }) => id)).toEqual(['canvas-raster-target', 'future-target']);
+  });
+
+  it('keeps the existing no-pointer closest-center behavior for widget drags', () => {
+    const collisions = widgetCollisionDetection(
+      createCollisionArgs({
+        activeData: getWidgetInstanceDragData('center', 'preview', 'preview'),
+        collisionRect: getRect(0, 0, 20, 20),
+        droppables: [
+          {
+            data: getWidgetInstanceDragData('center', 'canvas', 'canvas'),
+            id: 'canvas-widget',
+            rect: getRect(0, 0, 20, 20),
+          },
+          {
+            data: getWidgetRegionDropData('right'),
+            id: 'right-region',
+            rect: getRect(20, 20, 20, 20),
+          },
+          {
+            data: getCanvasImageDropData('raster'),
+            id: 'canvas-raster-target',
+            rect: getRect(100, 100, 20, 20),
+          },
+        ],
+        pointerCoordinates: null,
+      })
+    );
+
+    expect(collisions.map(({ id }) => id)).toEqual(['canvas-widget', 'right-region', 'canvas-raster-target']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgetDnd.ts b/invokeai/frontend/webv2/src/workbench/widgetDnd.ts
new file mode 100644
index 00000000000..184b3f17896
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetDnd.ts
@@ -0,0 +1,277 @@
+import { closestCenter, pointerWithin, type CollisionDetection } from '@dnd-kit/core';
+import { arrayMove } from '@dnd-kit/sortable';
+
+import type { WidgetIconComponent, WidgetInstanceId, WidgetRegion, WidgetRegionState, WidgetTypeId } from './types';
+
+export interface WidgetDndProject {
+  widgetInstances: Record<WidgetInstanceId, { typeId: WidgetTypeId; title?: string }>;
+  widgetRegions: Record<WidgetRegion, Pick<WidgetRegionState, 'activeInstanceId' | 'instanceIds'>>;
+}
+
+export interface ActiveWidgetDrag {
+  fromRegion: WidgetRegion;
+  icon: WidgetIconComponent;
+  instanceId: WidgetInstanceId;
+  label: string;
+  typeId: WidgetTypeId;
+}
+
+export interface WidgetInstanceDragData {
+  kind: 'widget-instance';
+  instanceId: WidgetInstanceId;
+  region: WidgetRegion;
+  typeId: WidgetTypeId;
+}
+
+export interface WidgetRegionDropData {
+  kind: 'widget-region';
+  region: WidgetRegion;
+}
+
+export type WidgetDndData = WidgetInstanceDragData | WidgetRegionDropData;
+
+export interface WidgetDndManifestLookupResult {
+  manifest: {
+    allowedRegions: WidgetRegion[];
+    allowMultiple: boolean;
+  };
+}
+
+export type GetWidgetDndManifest = (typeId: WidgetTypeId) => WidgetDndManifestLookupResult | undefined;
+
+export interface WidgetRegionDropState {
+  helperText: string;
+  isActive: boolean;
+  isAllowed: boolean;
+}
+
+export type WidgetDragEndResolution =
+  | {
+      activeInstanceId: WidgetInstanceId;
+      instanceIds: WidgetInstanceId[];
+      region: WidgetRegion;
+      type: 'reorder';
+    }
+  | {
+      fromRegion: WidgetRegion;
+      instanceId: WidgetInstanceId;
+      toIndex: number;
+      toRegion: WidgetRegion;
+      type: 'move';
+    };
+
+export const getWidgetInstanceDragId = (region: WidgetRegion, instanceId: WidgetInstanceId): string =>
+  `widget-instance:${region}:${instanceId}`;
+
+export const getWidgetRegionDropId = (region: WidgetRegion): string => `widget-region:${region}`;
+
+export const getWidgetInstanceDragData = (
+  region: WidgetRegion,
+  instanceId: WidgetInstanceId,
+  typeId: WidgetTypeId
+): WidgetInstanceDragData => ({ kind: 'widget-instance', instanceId, region, typeId });
+
+export const getWidgetRegionDropData = (region: WidgetRegion): WidgetRegionDropData => ({
+  kind: 'widget-region',
+  region,
+});
+
+export const isWidgetInstanceDragData = (data: unknown): data is WidgetInstanceDragData =>
+  isRecord(data) &&
+  data.kind === 'widget-instance' &&
+  typeof data.instanceId === 'string' &&
+  isWidgetRegion(data.region) &&
+  typeof data.typeId === 'string';
+
+export const isWidgetRegionDropData = (data: unknown): data is WidgetRegionDropData =>
+  isRecord(data) && data.kind === 'widget-region' && isWidgetRegion(data.region);
+
+export const isWidgetDndData = (data: unknown): data is WidgetDndData =>
+  isWidgetInstanceDragData(data) || isWidgetRegionDropData(data);
+
+export const regionHasWidgetType = (
+  project: WidgetDndProject,
+  region: WidgetRegion,
+  typeId: WidgetTypeId,
+  excludedInstanceId?: WidgetInstanceId
+): boolean =>
+  project.widgetRegions[region].instanceIds.some(
+    (instanceId) => instanceId !== excludedInstanceId && project.widgetInstances[instanceId]?.typeId === typeId
+  );
+
+export const canMoveWidgetToRegion = (
+  project: WidgetDndProject,
+  region: WidgetRegion,
+  typeId: WidgetTypeId,
+  instanceId: WidgetInstanceId,
+  getWidget: GetWidgetDndManifest
+): boolean => {
+  const widget = getWidget(typeId);
+
+  if (
+    !widget ||
+    !widget.manifest.allowedRegions.includes(region) ||
+    project.widgetRegions[region].instanceIds.includes(instanceId)
+  ) {
+    return false;
+  }
+
+  return widget.manifest.allowMultiple || !regionHasWidgetType(project, region, typeId);
+};
+
+export const getRegionDropState = (
+  project: WidgetDndProject,
+  activeDrag: ActiveWidgetDrag | null,
+  region: WidgetRegion,
+  getWidget: GetWidgetDndManifest
+): WidgetRegionDropState => {
+  const widget = activeDrag ? getWidget(activeDrag.typeId) : null;
+
+  if (!activeDrag || !widget) {
+    return { helperText: 'Unavailable', isActive: false, isAllowed: false };
+  }
+
+  if (!widget.manifest.allowedRegions.includes(region)) {
+    return { helperText: 'Unavailable', isActive: true, isAllowed: false };
+  }
+
+  if (activeDrag.fromRegion !== region && project.widgetRegions[region].instanceIds.includes(activeDrag.instanceId)) {
+    return { helperText: 'Already placed', isActive: true, isAllowed: false };
+  }
+
+  const excludedInstanceId = region === activeDrag.fromRegion ? activeDrag.instanceId : undefined;
+
+  if (!widget.manifest.allowMultiple && regionHasWidgetType(project, region, activeDrag.typeId, excludedInstanceId)) {
+    return { helperText: 'Already placed', isActive: true, isAllowed: false };
+  }
+
+  return { helperText: 'Drop here', isActive: true, isAllowed: true };
+};
+
+export const resolveWidgetDragEnd = (
+  project: WidgetDndProject,
+  activeData: WidgetInstanceDragData | null,
+  overData: WidgetDndData | null,
+  getWidget: GetWidgetDndManifest
+): WidgetDragEndResolution | null => {
+  if (!activeData || !overData) {
+    return null;
+  }
+
+  const activeInstance = project.widgetInstances[activeData.instanceId];
+  const widget = activeInstance ? getWidget(activeInstance.typeId) : undefined;
+  const fromRegion = activeData.region;
+  const overRegion = overData.region;
+
+  if (
+    !activeInstance ||
+    !widget ||
+    activeInstance.typeId !== activeData.typeId ||
+    !project.widgetRegions[fromRegion].instanceIds.includes(activeData.instanceId) ||
+    !widget.manifest.allowedRegions.includes(overRegion)
+  ) {
+    return null;
+  }
+
+  if (fromRegion === overRegion) {
+    if (overData.kind !== 'widget-instance') {
+      return null;
+    }
+
+    const overRegionState = project.widgetRegions[overRegion];
+    const oldIndex = overRegionState.instanceIds.indexOf(activeData.instanceId);
+    const toIndex = Math.max(0, overRegionState.instanceIds.indexOf(overData.instanceId));
+
+    if (oldIndex === -1 || overData.instanceId === activeData.instanceId) {
+      return null;
+    }
+
+    return {
+      activeInstanceId: activeData.instanceId,
+      instanceIds: arrayMove(overRegionState.instanceIds, oldIndex, toIndex),
+      region: overRegion,
+      type: 'reorder',
+    };
+  }
+
+  if (!canMoveWidgetToRegion(project, overRegion, activeInstance.typeId, activeData.instanceId, getWidget)) {
+    return null;
+  }
+
+  const overRegionState = project.widgetRegions[overRegion];
+  const toIndex =
+    overData.kind === 'widget-region'
+      ? overRegionState.instanceIds.length
+      : Math.max(0, overRegionState.instanceIds.indexOf(overData.instanceId));
+
+  return {
+    fromRegion,
+    instanceId: activeData.instanceId,
+    toIndex,
+    toRegion: overRegion,
+    type: 'move',
+  };
+};
+
+export const widgetCollisionDetection: CollisionDetection = (args) => {
+  const activeData = args.active.data.current;
+  const collisionArgs = isWidgetInstanceDragData(activeData)
+    ? args
+    : {
+        ...args,
+        droppableContainers: args.droppableContainers.filter((container) => !isWidgetDndData(container.data.current)),
+      };
+  const pointerCollisions = pointerWithin(collisionArgs);
+
+  if (pointerCollisions.length > 0) {
+    const widgetItemCollisions = pointerCollisions.filter((collision) => {
+      return isWidgetInstanceDragData(getCollisionData(args, collision.id));
+    });
+
+    if (widgetItemCollisions.length > 0) {
+      return widgetItemCollisions;
+    }
+
+    if (isWidgetInstanceDragData(activeData)) {
+      const widgetRegionCollisions = pointerCollisions.filter((collision) => {
+        return isWidgetRegionDropData(getCollisionData(args, collision.id));
+      });
+      const nonSourceRegionCollisions = widgetRegionCollisions.filter((collision) => {
+        const data = getCollisionData(args, collision.id);
+
+        return isWidgetRegionDropData(data) && data.region !== activeData.region;
+      });
+
+      if (nonSourceRegionCollisions.length > 0) {
+        return nonSourceRegionCollisions;
+      }
+
+      if (widgetRegionCollisions.length > 0) {
+        return closestCenter({
+          ...args,
+          droppableContainers: args.droppableContainers.filter((container) => {
+            const data = container.data.current;
+
+            return (
+              isWidgetInstanceDragData(data) &&
+              data.region === activeData.region &&
+              data.instanceId !== activeData.instanceId
+            );
+          }),
+        });
+      }
+    }
+
+    return pointerCollisions;
+  }
+
+  return args.pointerCoordinates ? [] : closestCenter(collisionArgs);
+};
+
+const getCollisionData = (args: Parameters<CollisionDetection>[0], id: unknown): unknown =>
+  args.droppableContainers.find((container) => container.id === id)?.data.current;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+const isWidgetRegion = (value: unknown): value is WidgetRegion =>
+  value === 'left' || value === 'right' || value === 'center' || value === 'bottom';
diff --git a/invokeai/frontend/webv2/src/workbench/widgetLabels.ts b/invokeai/frontend/webv2/src/workbench/widgetLabels.ts
new file mode 100644
index 00000000000..89091541896
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetLabels.ts
@@ -0,0 +1,11 @@
+import type { TFunction } from 'i18next';
+
+import type { WidgetManifest, WidgetTypeId } from './types';
+
+type WidgetLabelSource = Pick<WidgetManifest, 'id' | 'label'>;
+
+export const resolveWidgetLabel = (manifest: WidgetLabelSource, t: TFunction): string =>
+  typeof manifest.label === 'function' ? manifest.label(t) : manifest.label;
+
+export const getWidgetFallbackLabel = (manifest: { id: WidgetTypeId; label: WidgetManifest['label'] }): string =>
+  typeof manifest.label === 'string' ? manifest.label : manifest.id;
diff --git a/invokeai/frontend/webv2/src/workbench/widgetPlacementCommands.test.ts b/invokeai/frontend/webv2/src/workbench/widgetPlacementCommands.test.ts
new file mode 100644
index 00000000000..ebbfc547d2c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetPlacementCommands.test.ts
@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest';
+
+import type { NormalizedWidgetManifest, Project, RegisteredWidget, WidgetRegion, WorkbenchState } from './types';
+import type { WorkbenchAction } from './workbenchState';
+
+import { closeWidgetPlacement, openWidgetPlacement, revealWidgetPlacement } from './widgetPlacementCommands';
+import { createInitialWorkbenchState, workbenchReducer } from './workbenchState';
+
+const TestIcon = () => null;
+const TestView = () => null;
+
+const getActiveProject = (state: WorkbenchState): Project => {
+  const project = state.projects.find((candidate) => candidate.id === state.activeProjectId);
+
+  expect(project).toBeDefined();
+
+  return project as Project;
+};
+
+const createWidget = (
+  overrides: Partial<NormalizedWidgetManifest> & Pick<NormalizedWidgetManifest, 'id' | 'label'>
+): RegisteredWidget => ({
+  manifest: {
+    apiVersion: 1,
+    allowMultiple: false,
+    allowedRegions: ['left', 'right', 'center', 'bottom'],
+    bottomPanel: 'expandable',
+    centerPlacement: 'view',
+    failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+    icon: TestIcon,
+    state: { createInitial: () => ({}), persistence: 'project', version: 1 },
+    version: 1,
+    view: TestView,
+    ...overrides,
+  },
+  status: 'enabled',
+});
+
+const createRegistry =
+  (widgetsByRegion: Partial<Record<WidgetRegion, RegisteredWidget[]>>) =>
+  (region: WidgetRegion): RegisteredWidget[] =>
+    widgetsByRegion[region] ?? [];
+
+const applyCommand = (
+  state: WorkbenchState,
+  command: (dispatch: (action: WorkbenchAction) => void) => void
+): WorkbenchState => {
+  let nextState = state;
+  const dispatch = (action: WorkbenchAction): void => {
+    nextState = workbenchReducer(nextState, action);
+  };
+
+  command(dispatch);
+
+  return nextState;
+};
+
+describe('widget placement commands', () => {
+  it('opens a singleton already in the target region without duplicating it', () => {
+    const state = createInitialWorkbenchState();
+    const widget = createWidget({ id: 'queue', label: 'Queue' });
+    const nextState = applyCommand(state, (dispatch) => {
+      expect(
+        openWidgetPlacement({
+          dispatch,
+          getWidgetsForRegion: createRegistry({ right: [widget] }),
+          options: { preferredRegions: ['right'] },
+          typeId: 'queue',
+        })
+      ).toEqual({ ok: true, region: 'right' });
+    });
+    const rightRegion = getActiveProject(nextState).widgetRegions.right;
+
+    expect(rightRegion.instanceIds.filter((instanceId) => instanceId === 'queue')).toHaveLength(1);
+    expect(rightRegion.activeInstanceId).toBe('queue');
+  });
+
+  it('opens an existing singleton instance from another region', () => {
+    const state = createInitialWorkbenchState();
+    const widget = createWidget({ id: 'preview', label: 'Preview' });
+    const nextState = applyCommand(state, (dispatch) => {
+      openWidgetPlacement({
+        dispatch,
+        getWidgetsForRegion: createRegistry({ right: [widget] }),
+        options: { preferredRegions: ['right'] },
+        typeId: 'preview',
+      });
+    });
+    const rightRegion = getActiveProject(nextState).widgetRegions.right;
+
+    expect(rightRegion.instanceIds).toContain('preview');
+    expect(rightRegion.activeInstanceId).toBe('preview');
+  });
+
+  it('passes allowMultiple through as createNew', () => {
+    const actions: WorkbenchAction[] = [];
+    const widget = createWidget({ allowMultiple: true, id: 'queue', label: 'Queue' });
+
+    openWidgetPlacement({
+      dispatch: (action) => actions.push(action),
+      getWidgetsForRegion: createRegistry({ right: [widget] }),
+      options: { createNew: true, preferredRegions: ['right'] },
+      typeId: 'queue',
+    });
+
+    expect(actions).toMatchObject([{ createNew: true, region: 'right', type: 'openRegionWidget', widgetId: 'queue' }]);
+  });
+
+  it('does not create a new instance for singleton widgets even when requested', () => {
+    const actions: WorkbenchAction[] = [];
+    const widget = createWidget({ allowMultiple: false, id: 'queue', label: 'Queue' });
+
+    openWidgetPlacement({
+      dispatch: (action) => actions.push(action),
+      getWidgetsForRegion: createRegistry({ right: [widget] }),
+      options: { createNew: true, preferredRegions: ['right'] },
+      typeId: 'queue',
+    });
+
+    expect(actions).toMatchObject([
+      { createNew: undefined, region: 'right', type: 'openRegionWidget', widgetId: 'queue' },
+    ]);
+  });
+
+  it('rejects invalid regions and unrenderable placements', () => {
+    const actions: WorkbenchAction[] = [];
+    const dispatch = (action: WorkbenchAction): void => {
+      actions.push(action);
+    };
+
+    expect(
+      openWidgetPlacement({
+        dispatch,
+        getWidgetsForRegion: createRegistry({
+          left: [createWidget({ allowedRegions: ['center'], id: 'models', label: 'Models' })],
+        }),
+        options: { preferredRegions: ['left'] },
+        typeId: 'models',
+      })
+    ).toEqual({ ok: false, reason: 'unavailable' });
+    expect(
+      openWidgetPlacement({
+        dispatch,
+        getWidgetsForRegion: createRegistry({
+          bottom: [createWidget({ bottomPanel: 'tooltip', id: 'diagnostics', label: 'Diagnostics' })],
+        }),
+        options: { preferredRegions: ['bottom'] },
+        typeId: 'diagnostics',
+      })
+    ).toEqual({ ok: false, reason: 'unavailable' });
+    expect(
+      openWidgetPlacement({
+        dispatch,
+        getWidgetsForRegion: createRegistry({
+          center: [createWidget({ centerPlacement: 'toolbar', id: 'toolbar-tools', label: 'Toolbar Tools' })],
+        }),
+        options: { preferredRegions: ['center'] },
+        typeId: 'toolbar-tools',
+      })
+    ).toEqual({ ok: false, reason: 'unavailable' });
+    expect(actions).toEqual([]);
+  });
+
+  it('prevents removing the last center view', () => {
+    const actions: WorkbenchAction[] = [];
+    const project = getActiveProject(createInitialWorkbenchState());
+
+    expect(
+      closeWidgetPlacement({
+        dispatch: (action) => actions.push(action),
+        getWidgetById: (typeId) => createWidget({ id: typeId, label: typeId }),
+        instanceId: 'canvas',
+        project: {
+          ...project,
+          widgetRegions: {
+            ...project.widgetRegions,
+            center: { ...project.widgetRegions.center, activeInstanceId: 'canvas', instanceIds: ['canvas'] },
+          },
+        },
+        region: 'center',
+      })
+    ).toEqual({ ok: false, reason: 'unsupported' });
+    expect(actions).toEqual([]);
+  });
+
+  it('reveals a placement and uncollapses its region', () => {
+    const state = createInitialWorkbenchState();
+    const project = getActiveProject(state);
+    const collapsedState: WorkbenchState = {
+      ...state,
+      projects: state.projects.map((candidate) =>
+        candidate.id === project.id
+          ? {
+              ...candidate,
+              widgetRegions: {
+                ...candidate.widgetRegions,
+                right: { ...candidate.widgetRegions.right, activeInstanceId: 'layers', isCollapsed: true },
+              },
+            }
+          : candidate
+      ),
+    };
+    const nextState = applyCommand(collapsedState, (dispatch) => {
+      revealWidgetPlacement({
+        dispatch,
+        instanceId: 'queue',
+        project: getActiveProject(collapsedState),
+        region: 'right',
+      });
+    });
+
+    expect(getActiveProject(nextState).widgetRegions.right).toMatchObject({
+      activeInstanceId: 'queue',
+      isCollapsed: false,
+    });
+  });
+
+  it('closes a placement and preserves reducer fallback active item behavior', () => {
+    const state = createInitialWorkbenchState();
+    const nextState = applyCommand(state, (dispatch) => {
+      closeWidgetPlacement({
+        dispatch,
+        getWidgetById: (typeId) => createWidget({ id: typeId, label: typeId }),
+        instanceId: 'layers',
+        project: getActiveProject(state),
+        region: 'right',
+      });
+    });
+    const rightRegion = getActiveProject(nextState).widgetRegions.right;
+
+    expect(rightRegion.instanceIds).not.toContain('layers');
+    expect(rightRegion.activeInstanceId).toBe('gallery');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgetPlacementCommands.ts b/invokeai/frontend/webv2/src/workbench/widgetPlacementCommands.ts
new file mode 100644
index 00000000000..f12e9b62b4c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetPlacementCommands.ts
@@ -0,0 +1,200 @@
+import type { Dispatch } from 'react';
+
+import type {
+  OpenWorkbenchWidgetOptions,
+  RegisteredWidget,
+  WidgetInstanceId,
+  WidgetRegion,
+  WidgetRegionState,
+  WidgetTypeId,
+  WidgetWorkbenchApiResult,
+} from './types';
+import type { WidgetDragEndResolution } from './widgetDnd';
+import type { WidgetPlacementMeta } from './widgetRegionViewModel';
+import type { WorkbenchAction } from './workbenchState';
+
+export interface WidgetPlacementProject {
+  projectId?: string;
+  widgetInstances: WidgetPlacementMeta;
+  widgetRegions: Record<WidgetRegion, Pick<WidgetRegionState, 'activeInstanceId' | 'instanceIds'>>;
+}
+
+const DEFAULT_OPEN_REGIONS: ReadonlyArray<WidgetRegion> = ['center', 'right', 'left', 'bottom'];
+
+export type WidgetPlacementCommandResult = WidgetWorkbenchApiResult;
+
+export const canRenderWidgetInRegion = (widget: RegisteredWidget, region: WidgetRegion): boolean => {
+  if (widget.status !== 'enabled' || !widget.manifest.view || !widget.manifest.allowedRegions.includes(region)) {
+    return false;
+  }
+
+  if (region === 'center') {
+    return widget.manifest.centerPlacement !== 'toolbar';
+  }
+
+  if (region === 'bottom') {
+    return widget.manifest.bottomPanel !== 'tooltip';
+  }
+
+  return true;
+};
+
+export const getOpenableWidgetPlacement = ({
+  getWidgetsForRegion,
+  options = {},
+  typeId,
+}: {
+  getWidgetsForRegion: (region: WidgetRegion) => RegisteredWidget[];
+  typeId: WidgetTypeId;
+  options?: OpenWorkbenchWidgetOptions;
+}): { region: WidgetRegion; widget: RegisteredWidget } | null => {
+  const preferredRegions = options.preferredRegions ?? DEFAULT_OPEN_REGIONS;
+  const seenRegions = new Set<WidgetRegion>();
+
+  for (const region of preferredRegions) {
+    if (seenRegions.has(region) || (options.requireCenterView && region !== 'center')) {
+      continue;
+    }
+
+    seenRegions.add(region);
+
+    const widget = getWidgetsForRegion(region).find((candidate) => candidate.manifest.id === typeId);
+
+    if (widget && canRenderWidgetInRegion(widget, region)) {
+      return { region, widget };
+    }
+  }
+
+  return null;
+};
+
+export const openWidgetPlacement = ({
+  dispatch,
+  getWidgetsForRegion,
+  options,
+  projectId,
+  typeId,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  getWidgetsForRegion: (region: WidgetRegion) => RegisteredWidget[];
+  projectId?: string;
+  typeId: WidgetTypeId;
+  options?: OpenWorkbenchWidgetOptions;
+}): WidgetPlacementCommandResult => {
+  const target = getOpenableWidgetPlacement({ getWidgetsForRegion, options, typeId });
+
+  if (!target) {
+    return { ok: false, reason: 'unavailable' };
+  }
+
+  dispatch({
+    createNew: target.widget.manifest.allowMultiple ? options?.createNew : undefined,
+    initialValues: target.widget.manifest.state?.createInitial(),
+    projectId,
+    region: target.region,
+    type: 'openRegionWidget',
+    widgetId: typeId,
+  });
+
+  return { ok: true, region: target.region };
+};
+
+const getEnabledCenterViewCount = (
+  project: WidgetPlacementProject,
+  getWidgetById: (typeId: WidgetTypeId) => RegisteredWidget | undefined
+): number =>
+  project.widgetRegions.center.instanceIds.filter((instanceId) => {
+    const instance = project.widgetInstances[instanceId];
+    const widget = instance ? getWidgetById(instance.typeId) : undefined;
+
+    return widget?.status === 'enabled' && widget.manifest.centerPlacement !== 'toolbar';
+  }).length;
+
+export const closeWidgetPlacement = ({
+  dispatch,
+  getWidgetById,
+  instanceId,
+  project,
+  region,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  getWidgetById: (typeId: WidgetTypeId) => RegisteredWidget | undefined;
+  project: WidgetPlacementProject;
+  region: WidgetRegion;
+  instanceId: WidgetInstanceId;
+}): WidgetPlacementCommandResult => {
+  if (!project.widgetInstances[instanceId]) {
+    return { ok: false, reason: 'not-found' };
+  }
+
+  if (!project.widgetRegions[region].instanceIds.includes(instanceId)) {
+    return { ok: false, reason: 'unsupported' };
+  }
+
+  if (region === 'center') {
+    const instance = project.widgetInstances[instanceId];
+    const widget = getWidgetById(instance.typeId);
+    const isCenterView = widget?.manifest.centerPlacement !== 'toolbar';
+
+    if (isCenterView && getEnabledCenterViewCount(project, getWidgetById) === 1) {
+      return { ok: false, reason: 'unsupported' };
+    }
+  }
+
+  dispatch({ projectId: project.projectId, region, type: 'toggleRegionWidget', widgetId: instanceId });
+
+  return { ok: true, region };
+};
+
+export const revealWidgetPlacement = ({
+  dispatch,
+  instanceId,
+  project,
+  region,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  project: WidgetPlacementProject;
+  region: WidgetRegion;
+  instanceId: WidgetInstanceId;
+}): WidgetPlacementCommandResult => {
+  if (!project.widgetInstances[instanceId]) {
+    return { ok: false, reason: 'not-found' };
+  }
+
+  if (!project.widgetRegions[region].instanceIds.includes(instanceId)) {
+    return { ok: false, reason: 'unsupported' };
+  }
+
+  dispatch({ projectId: project.projectId, region, type: 'selectRegionWidget', widgetId: instanceId });
+
+  return { ok: true, region };
+};
+
+export const dispatchWidgetDragEndPlacement = ({
+  dispatch,
+  resolution,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  resolution: WidgetDragEndResolution;
+}): WidgetPlacementCommandResult => {
+  if (resolution.type === 'reorder') {
+    dispatch({
+      activeInstanceId: resolution.activeInstanceId,
+      instanceIds: resolution.instanceIds,
+      region: resolution.region,
+      type: 'reorderWidgetInstances',
+    });
+
+    return { ok: true, region: resolution.region };
+  }
+
+  dispatch({
+    fromRegion: resolution.fromRegion,
+    instanceId: resolution.instanceId,
+    toIndex: resolution.toIndex,
+    toRegion: resolution.toRegion,
+    type: 'moveWidgetInstance',
+  });
+
+  return { ok: true, region: resolution.toRegion };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgetPlacementMeta.ts b/invokeai/frontend/webv2/src/workbench/widgetPlacementMeta.ts
new file mode 100644
index 00000000000..0bda7b4666b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetPlacementMeta.ts
@@ -0,0 +1,68 @@
+import type { Project, WidgetInstanceId, WidgetRegion, WidgetRegionState } from './types';
+import type { WidgetPlacementProject } from './widgetPlacementCommands';
+import type { WidgetPlacementMeta } from './widgetRegionViewModel';
+
+export type WidgetPlacementRegionState = Pick<WidgetRegionState, 'activeInstanceId' | 'instanceIds' | 'isCollapsed'>;
+
+export const getWidgetPlacementMeta = (
+  project: Pick<Project, 'widgetInstances' | 'widgetRegions'>
+): WidgetPlacementMeta => {
+  const placedInstanceIds = new Set<WidgetInstanceId>();
+
+  for (const region of Object.values(project.widgetRegions)) {
+    for (const instanceId of region.instanceIds) {
+      placedInstanceIds.add(instanceId);
+    }
+  }
+
+  return Object.fromEntries(
+    [...placedInstanceIds].flatMap((instanceId) => {
+      const instance = project.widgetInstances[instanceId];
+
+      return instance ? [[instanceId, { id: instance.id, title: instance.title, typeId: instance.typeId }]] : [];
+    })
+  );
+};
+
+export const getWidgetPlacementProject = (
+  project: Pick<Project, 'id' | 'widgetInstances' | 'widgetRegions'>
+): WidgetPlacementProject => ({
+  projectId: project.id,
+  widgetInstances: getWidgetPlacementMeta(project),
+  widgetRegions: project.widgetRegions,
+});
+
+export const areWidgetPlacementMetaEqual = (left: WidgetPlacementMeta, right: WidgetPlacementMeta): boolean => {
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((key) => {
+      const leftMeta = left[key];
+      const rightMeta = right[key];
+
+      return (
+        rightMeta !== undefined &&
+        leftMeta.id === rightMeta.id &&
+        leftMeta.typeId === rightMeta.typeId &&
+        leftMeta.title === rightMeta.title
+      );
+    })
+  );
+};
+
+export const areWidgetPlacementProjectsEqual = (left: WidgetPlacementProject, right: WidgetPlacementProject): boolean =>
+  left.projectId === right.projectId &&
+  areWidgetPlacementMetaEqual(left.widgetInstances, right.widgetInstances) &&
+  (Object.keys(left.widgetRegions) as WidgetRegion[]).every((region) => {
+    const leftRegion = left.widgetRegions[region];
+    const rightRegion = right.widgetRegions[region];
+
+    return (
+      rightRegion !== undefined &&
+      leftRegion.activeInstanceId === rightRegion.activeInstanceId &&
+      leftRegion.instanceIds.length === rightRegion.instanceIds.length &&
+      leftRegion.instanceIds.every((instanceId, index) => instanceId === rightRegion.instanceIds[index])
+    );
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/widgetRegionItems.ts b/invokeai/frontend/webv2/src/workbench/widgetRegionItems.ts
new file mode 100644
index 00000000000..3184db93f38
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetRegionItems.ts
@@ -0,0 +1,12 @@
+export {
+  createWidgetRegionViewModel,
+  createWidgetRegionViewModelFromState,
+  getWidgetRegionItems,
+  isPlacedWidgetRegionItem,
+  type AvailableWidgetTypeItem,
+  type PlacedWidgetRegionItem,
+  type WidgetPlacementInstanceMeta,
+  type WidgetPlacementMeta,
+  type WidgetRegionItem,
+  type WidgetRegionViewModel,
+} from './widgetRegionViewModel';
diff --git a/invokeai/frontend/webv2/src/workbench/widgetRegionViewModel.test.ts b/invokeai/frontend/webv2/src/workbench/widgetRegionViewModel.test.ts
new file mode 100644
index 00000000000..dedec0f91f5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetRegionViewModel.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { NormalizedWidgetManifest, RegisteredWidget, WidgetInstanceContract, WidgetTypeId } from './types';
+
+import {
+  canRemoveItem,
+  createWidgetRegionViewModel,
+  getWidgetRegionItems,
+  isRequiredCenterView,
+} from './widgetRegionViewModel';
+
+const TestIcon = () => null;
+const TestView = () => null;
+
+const createWidget = (
+  overrides: Partial<NormalizedWidgetManifest> & Pick<NormalizedWidgetManifest, 'id' | 'label'>
+): RegisteredWidget => ({
+  manifest: {
+    apiVersion: 1,
+    allowMultiple: false,
+    allowedRegions: ['left', 'center', 'bottom'],
+    failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+    icon: TestIcon,
+    state: { createInitial: () => ({}), persistence: 'project', version: 1 },
+    version: 1,
+    view: TestView,
+    ...overrides,
+  },
+  status: 'enabled',
+});
+
+const createInstance = (id: string, typeId: WidgetTypeId): WidgetInstanceContract => ({
+  createdAt: '2026-01-01T00:00:00.000Z',
+  id,
+  state: { id: typeId, label: typeId, values: {}, version: 1 },
+  typeId,
+});
+
+describe('widget region view model', () => {
+  it('separates placed items from available items', () => {
+    const viewModel = createWidgetRegionViewModel({
+      activeInstanceId: 'alpha',
+      instanceIds: ['alpha'],
+      region: 'left',
+      widgetInstances: { alpha: createInstance('alpha', 'alpha') },
+      widgets: [createWidget({ id: 'alpha', label: 'Alpha' }), createWidget({ id: 'beta', label: 'Beta' })],
+    });
+
+    expect(viewModel.placedItems.map((item) => item.id)).toEqual(['alpha']);
+    expect(viewModel.availableItems.map((item) => item.typeId)).toEqual(['beta']);
+    expect(viewModel.activeItem?.id).toBe('alpha');
+    expect(viewModel.sortableInstanceIds).toEqual(['alpha']);
+    expect(getWidgetRegionItems(viewModel).map((item) => item.label)).toEqual(['Alpha', 'Beta']);
+  });
+
+  it('filters already placed singleton widget types from available items', () => {
+    const viewModel = createWidgetRegionViewModel({
+      instanceIds: ['alpha'],
+      region: 'left',
+      widgetInstances: { alpha: createInstance('alpha', 'alpha') },
+      widgets: [createWidget({ id: 'alpha', label: 'Alpha' })],
+    });
+
+    expect(viewModel.availableItems).toEqual([]);
+  });
+
+  it('keeps allowMultiple widget types available after one placement', () => {
+    const viewModel = createWidgetRegionViewModel({
+      instanceIds: ['alpha'],
+      region: 'left',
+      widgetInstances: { alpha: createInstance('alpha', 'alpha') },
+      widgets: [createWidget({ allowMultiple: true, id: 'alpha', label: 'Alpha' })],
+    });
+
+    expect(viewModel.availableItems).toHaveLength(1);
+    expect(viewModel.availableItems[0]).toMatchObject({ allowMultiple: true, isEnabled: false, typeId: 'alpha' });
+  });
+
+  it('identifies the last enabled center view as required', () => {
+    const viewModel = createWidgetRegionViewModel({
+      instanceIds: ['canvas', 'toolbar-tools'],
+      region: 'center',
+      widgetInstances: {
+        canvas: createInstance('canvas', 'canvas'),
+        'toolbar-tools': createInstance('toolbar-tools', 'toolbar-tools'),
+      },
+      widgets: [
+        createWidget({ centerPlacement: 'view', id: 'canvas', label: 'Canvas' }),
+        createWidget({ centerPlacement: 'toolbar', id: 'toolbar-tools', label: 'Toolbar Tools' }),
+      ],
+    });
+    const canvas = viewModel.placedItems.find((item) => item.id === 'canvas');
+    const toolbar = viewModel.placedItems.find((item) => item.id === 'toolbar-tools');
+
+    expect(canvas).toBeDefined();
+    expect(toolbar).toBeDefined();
+    expect(isRequiredCenterView(canvas!, 1)).toBe(true);
+    expect(canRemoveItem(canvas!, viewModel)).toBe(false);
+    expect(canRemoveItem(toolbar!, viewModel)).toBe(true);
+  });
+
+  it('does not call createInitial while deriving available items', () => {
+    const createInitial = vi.fn(() => ({ seeded: true }));
+    const viewModel = createWidgetRegionViewModel({
+      instanceIds: [],
+      region: 'left',
+      widgetInstances: {},
+      widgets: [
+        createWidget({
+          id: 'alpha',
+          label: 'Alpha',
+          state: { createInitial, persistence: 'project', version: 1 },
+        }),
+      ],
+    });
+
+    expect(createInitial).not.toHaveBeenCalled();
+    expect(viewModel.availableItems[0]).not.toHaveProperty('initialValues');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgetRegionViewModel.ts b/invokeai/frontend/webv2/src/workbench/widgetRegionViewModel.ts
new file mode 100644
index 00000000000..08886fcb2f2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetRegionViewModel.ts
@@ -0,0 +1,173 @@
+import type {
+  NormalizedWidgetManifest,
+  RegisteredWidget,
+  WidgetIconComponent,
+  WidgetInstanceContract,
+  WidgetInstanceId,
+  WidgetRegion,
+  WidgetRegionState,
+  WidgetTypeId,
+} from './types';
+
+export interface WidgetPlacementInstanceMeta {
+  id: WidgetInstanceId;
+  typeId: WidgetTypeId;
+  title?: string;
+}
+
+export type WidgetPlacementMeta = Record<WidgetInstanceId, WidgetPlacementInstanceMeta>;
+
+interface BaseWidgetRegionItem {
+  failureMessage?: string;
+  allowMultiple: boolean;
+  icon: WidgetIconComponent;
+  id: string;
+  label: string;
+  status: RegisteredWidget['status'];
+  typeId: WidgetTypeId;
+  widget: RegisteredWidget;
+}
+
+export interface PlacedWidgetRegionItem<
+  Instance extends WidgetPlacementInstanceMeta = WidgetInstanceContract,
+> extends BaseWidgetRegionItem {
+  instance: Instance;
+  isEnabled: true;
+}
+
+export interface AvailableWidgetTypeItem extends BaseWidgetRegionItem {
+  instance?: undefined;
+  isEnabled: false;
+}
+
+export type WidgetRegionItem<Instance extends WidgetPlacementInstanceMeta = WidgetInstanceContract> =
+  | PlacedWidgetRegionItem<Instance>
+  | AvailableWidgetTypeItem;
+
+export interface WidgetRegionViewModel<Instance extends WidgetPlacementInstanceMeta = WidgetInstanceContract> {
+  region: WidgetRegion;
+  placedItems: PlacedWidgetRegionItem<Instance>[];
+  availableItems: AvailableWidgetTypeItem[];
+  activeItem?: PlacedWidgetRegionItem<Instance>;
+  sortableInstanceIds: WidgetInstanceId[];
+}
+
+export const createWidgetRegionViewModel = <Instance extends WidgetPlacementInstanceMeta>({
+  activeInstanceId,
+  instanceIds,
+  region,
+  widgetInstances,
+  widgets,
+  getWidgetLabel = (manifest) => (typeof manifest.label === 'string' ? manifest.label : manifest.id),
+}: {
+  activeInstanceId?: WidgetInstanceId;
+  instanceIds: WidgetInstanceId[];
+  region: WidgetRegion;
+  widgetInstances: Record<string, Instance>;
+  widgets: RegisteredWidget[];
+  getWidgetLabel?: (manifest: NormalizedWidgetManifest) => string;
+}): WidgetRegionViewModel<Instance> => {
+  const widgetsByType = new Map(widgets.map((widget) => [widget.manifest.id, widget]));
+  const placedItems = instanceIds.flatMap((instanceId): PlacedWidgetRegionItem<Instance>[] => {
+    const instance = widgetInstances[instanceId];
+    const widget = instance ? widgetsByType.get(instance.typeId) : undefined;
+
+    if (!instance || !widget) {
+      return [];
+    }
+
+    return [
+      {
+        failureMessage: widget.failure?.message,
+        allowMultiple: widget.manifest.allowMultiple,
+        icon: widget.manifest.icon,
+        id: instance.id,
+        instance,
+        isEnabled: true,
+        label: instance.title ?? getWidgetLabel(widget.manifest),
+        status: widget.status,
+        typeId: instance.typeId,
+        widget,
+      },
+    ];
+  });
+  const placedTypeIds = new Set(placedItems.map((item) => item.typeId));
+  const availableItems: AvailableWidgetTypeItem[] = widgets
+    .filter((widget) => widget.manifest.allowMultiple || !placedTypeIds.has(widget.manifest.id))
+    .map((widget) => ({
+      failureMessage: widget.failure?.message,
+      allowMultiple: widget.manifest.allowMultiple,
+      icon: widget.manifest.icon,
+      id: `${region}:new:${widget.manifest.id}`,
+      isEnabled: false,
+      label: getWidgetLabel(widget.manifest),
+      status: widget.status,
+      typeId: widget.manifest.id,
+      widget,
+    }));
+  const activeItem = placedItems.find((item) => item.id === activeInstanceId);
+
+  return {
+    activeItem,
+    availableItems,
+    placedItems,
+    region,
+    sortableInstanceIds: placedItems.map((item) => item.id),
+  };
+};
+
+export const createWidgetRegionViewModelFromState = <Instance extends WidgetPlacementInstanceMeta>({
+  region,
+  regionState,
+  widgetInstances,
+  widgets,
+  getWidgetLabel,
+}: {
+  region: WidgetRegion;
+  regionState: WidgetRegionState;
+  widgetInstances: Record<string, Instance>;
+  widgets: RegisteredWidget[];
+  getWidgetLabel?: (manifest: NormalizedWidgetManifest) => string;
+}): WidgetRegionViewModel<Instance> =>
+  createWidgetRegionViewModel({
+    activeInstanceId: regionState.activeInstanceId,
+    getWidgetLabel,
+    instanceIds: regionState.instanceIds,
+    region,
+    widgetInstances,
+    widgets,
+  });
+
+export const getWidgetRegionItems = <Instance extends WidgetPlacementInstanceMeta>(
+  viewModel: WidgetRegionViewModel<Instance>
+): WidgetRegionItem<Instance>[] => [...viewModel.placedItems, ...viewModel.availableItems];
+
+export const isPlacedWidgetRegionItem = <Instance extends WidgetPlacementInstanceMeta>(
+  item: WidgetRegionItem<Instance>
+): item is PlacedWidgetRegionItem<Instance> => item.isEnabled;
+
+export const isRequiredCenterView = (item: WidgetRegionItem, enabledCenterViewCount: number): boolean => {
+  const isView = item.widget.manifest.centerPlacement !== 'toolbar';
+
+  return isView && item.isEnabled && enabledCenterViewCount === 1;
+};
+
+export const isCompactBottomItem = <Instance extends WidgetPlacementInstanceMeta>(
+  item: WidgetRegionItem<Instance>
+): item is PlacedWidgetRegionItem<Instance> => item.isEnabled && item.status === 'enabled';
+
+export const isExpandableBottomItem = <Instance extends WidgetPlacementInstanceMeta>(
+  item: WidgetRegionItem<Instance>
+): boolean => item.widget.manifest.bottomPanel !== 'tooltip';
+
+export const canRemoveItem = (item: WidgetRegionItem, viewModel: WidgetRegionViewModel): boolean => {
+  if (viewModel.region !== 'center') {
+    return item.isEnabled;
+  }
+
+  const enabledCenterViewCount = viewModel.placedItems.filter(
+    (placedItem) => placedItem.status === 'enabled' && placedItem.widget.manifest.centerPlacement !== 'toolbar'
+  ).length;
+
+  return !isRequiredCenterView(item, enabledCenterViewCount);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgetRegistry.test.ts b/invokeai/frontend/webv2/src/workbench/widgetRegistry.test.ts
new file mode 100644
index 00000000000..f84cce1af4c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetRegistry.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+
+import type { WidgetManifest } from './types';
+
+import { getWidgetHosts, registerFirstPartyWidgets, registerWidgets } from './widgetRegistry';
+
+const TestIcon = () => null;
+const TestView = () => null;
+
+const createManifest = (overrides: Partial<WidgetManifest> = {}): WidgetManifest => ({
+  allowMultiple: false,
+  allowedRegions: ['right'],
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  icon: TestIcon,
+  id: 'vendor.widget',
+  label: 'Test Widget',
+  version: 1,
+  view: TestView,
+  ...overrides,
+});
+
+describe('widget registry', () => {
+  it('registers first-party widget manifests without icon validation failures', () => {
+    const widgets = registerFirstPartyWidgets();
+
+    expect(widgets).toHaveLength(13);
+    expect(widgets.flatMap((widget) => widget.failure ?? [])).toEqual([]);
+    expect(widgets.every((widget) => widget.status === 'enabled')).toBe(true);
+  });
+
+  it('normalizes default state and api version', () => {
+    const [widget] = registerWidgets([createManifest({ state: undefined })]);
+
+    expect(widget.status).toBe('enabled');
+    expect(widget.manifest.apiVersion).toBe(1);
+    expect(widget.manifest.state).toMatchObject({ persistence: 'project', version: 1 });
+    expect(widget.manifest.state.createInitial()).toEqual({});
+  });
+
+  it('exposes enabled widget singleton hosts', () => {
+    expect(getWidgetHosts().map((widget) => widget.manifest.id)).toContain('workflow');
+  });
+
+  it('disables invalid icon manifests', () => {
+    const [widget] = registerWidgets([createManifest({ icon: 'invalid' as unknown as WidgetManifest['icon'] })]);
+
+    expect(widget.status).toBe('disabled');
+    expect(widget.failure?.message).toContain('must provide an icon component');
+  });
+
+  it('fails closed for empty regions', () => {
+    const [widget] = registerWidgets([createManifest({ allowedRegions: [] })]);
+
+    expect(widget.status).toBe('disabled');
+    expect(widget.failure?.message).toContain('must declare at least one allowed region');
+  });
+
+  it('fails closed for renderable regions without a view', () => {
+    const [widget] = registerWidgets([createManifest({ view: undefined })]);
+
+    expect(widget.status).toBe('disabled');
+    expect(widget.failure?.message).toContain('does not include manifest.view');
+  });
+
+  it('honors hidden failure policy for invalid manifests', () => {
+    const [widget] = registerWidgets([
+      createManifest({
+        failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'hide' },
+        view: undefined,
+      }),
+    ]);
+
+    expect(widget.status).toBe('hidden');
+    expect(widget.failure).toBeDefined();
+  });
+
+  it('rejects unstable ids and unsupported api versions', () => {
+    const [badId, badApiVersion] = registerWidgets([
+      createManifest({ id: 'bad id' }),
+      createManifest({ apiVersion: 2 as unknown as WidgetManifest['apiVersion'], id: 'vendor.bad-api' }),
+    ]);
+
+    expect(badId.status).toBe('disabled');
+    expect(badId.failure?.message).toContain('stable non-empty string id');
+    expect(badApiVersion.status).toBe('disabled');
+    expect(badApiVersion.failure?.message).toContain('unsupported apiVersion');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgetRegistry.ts b/invokeai/frontend/webv2/src/workbench/widgetRegistry.ts
new file mode 100644
index 00000000000..2bc727239d2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetRegistry.ts
@@ -0,0 +1,139 @@
+import type {
+  NormalizedWidgetManifest,
+  RegisteredWidget,
+  WidgetFailure,
+  WidgetManifest,
+  WidgetRegion,
+  WidgetTypeId,
+} from './types';
+
+import { getAuthSession } from './auth/session';
+import { autosaveStatusWidgetManifest } from './widgets/autosave-status';
+import { canvasWidgetManifest } from './widgets/canvas';
+import { diagnosticsWidgetManifest } from './widgets/diagnostics';
+import { galleryWidgetManifest } from './widgets/gallery';
+import { generateWidgetManifest } from './widgets/generate';
+import { layersWidgetManifest } from './widgets/layers';
+import { notificationsWidgetManifest } from './widgets/notifications';
+import { previewWidgetManifest } from './widgets/preview';
+import { projectWidgetManifest } from './widgets/project';
+import { queueWidgetManifest } from './widgets/queue';
+import { serverStatusWidgetManifest } from './widgets/server-status';
+import { versionStatusWidgetManifest } from './widgets/version-status';
+import { workflowWidgetManifest } from './widgets/workflow';
+
+export const firstPartyWidgetManifests: WidgetManifest[] = [
+  generateWidgetManifest,
+  workflowWidgetManifest,
+  canvasWidgetManifest,
+  diagnosticsWidgetManifest,
+  galleryWidgetManifest,
+  previewWidgetManifest,
+  projectWidgetManifest,
+  layersWidgetManifest,
+  queueWidgetManifest,
+  notificationsWidgetManifest,
+  serverStatusWidgetManifest,
+  autosaveStatusWidgetManifest,
+  versionStatusWidgetManifest,
+];
+
+const createFailure = (widgetId: WidgetTypeId, error: unknown): WidgetFailure => ({
+  details: error instanceof Error ? (error.stack ?? error.message) : String(error),
+  message: error instanceof Error ? error.message : `Failed to register ${widgetId}.`,
+  occurredAt: new Date().toISOString(),
+  widgetId,
+});
+
+const renderableRegions = new Set<WidgetRegion>(['bottom', 'center', 'left', 'right']);
+
+const isWidgetIconComponent = (value: WidgetManifest['icon']): boolean =>
+  typeof value === 'function' || (typeof value === 'object' && value !== null && '$$typeof' in value);
+
+const validateManifest = (manifest: NormalizedWidgetManifest): void => {
+  if (typeof manifest.id !== 'string' || manifest.id.trim().length === 0 || /\s/.test(manifest.id)) {
+    throw new Error('Widget manifest must provide a stable non-empty string id without whitespace.');
+  }
+
+  if (manifest.apiVersion !== 1) {
+    throw new Error(`Widget ${manifest.id} declares unsupported apiVersion ${String(manifest.apiVersion)}.`);
+  }
+
+  if (manifest.allowedRegions.length === 0) {
+    throw new Error(`Widget ${manifest.id} must declare at least one allowed region.`);
+  }
+
+  for (const region of manifest.allowedRegions) {
+    if (!renderableRegions.has(region)) {
+      throw new Error(`Widget ${manifest.id} declares unsupported region ${String(region)}.`);
+    }
+  }
+
+  if (!isWidgetIconComponent(manifest.icon)) {
+    throw new TypeError(`Widget ${manifest.id} must provide an icon component.`);
+  }
+
+  if (manifest.allowedRegions.some((region) => renderableRegions.has(region)) && !manifest.view) {
+    throw new Error(`Widget ${manifest.id} declares a renderable region but does not include manifest.view.`);
+  }
+};
+
+export const normalizeWidgetManifest = (manifest: WidgetManifest): NormalizedWidgetManifest => ({
+  ...manifest,
+  apiVersion: manifest.apiVersion ?? 1,
+  state: manifest.state ?? { createInitial: () => ({}), persistence: 'project', version: 1 },
+});
+
+export const registerWidgets = (manifests: WidgetManifest[]): RegisteredWidget[] =>
+  manifests.map((rawManifest) => {
+    const manifest = normalizeWidgetManifest(rawManifest);
+
+    try {
+      validateManifest(manifest);
+
+      return { manifest, status: 'enabled' as const };
+    } catch (error) {
+      const failure = createFailure(manifest.id, error);
+      const status = manifest.failurePolicy.onRegistrationFailure === 'hide' ? 'hidden' : 'disabled';
+
+      return { failure, manifest, status };
+    }
+  });
+
+export const registerFirstPartyWidgets = (): RegisteredWidget[] => registerWidgets(firstPartyWidgetManifests);
+
+export const registeredWidgets = registerFirstPartyWidgets();
+
+/**
+ * Admin-only widgets are offered only while an admin is signed in to a
+ * multi-user backend. The imperative session read is safe here: the route
+ * guard resolves the session before the workbench mounts, and a user change
+ * remounts the workbench route.
+ */
+const isWidgetAvailable = (widget: RegisteredWidget): boolean => {
+  if (!widget.manifest.requiresAdmin) {
+    return true;
+  }
+
+  const session = getAuthSession();
+
+  return session.multiuserEnabled && session.user?.is_admin === true;
+};
+
+export const getWidgetsForRegion = (region: WidgetRegion): RegisteredWidget[] =>
+  registeredWidgets.filter(
+    (widget) =>
+      widget.status !== 'hidden' && widget.manifest.allowedRegions.includes(region) && isWidgetAvailable(widget)
+  );
+
+export const getWidgetHosts = (): RegisteredWidget[] =>
+  registeredWidgets.filter(
+    (widget) => widget.status === 'enabled' && widget.manifest.host && isWidgetAvailable(widget)
+  );
+
+export const getWidgetById = (widgetId: WidgetTypeId): RegisteredWidget | undefined =>
+  registeredWidgets.find((widget) => widget.manifest.id === widgetId);
+
+export const widgetRegistrationFailures = registeredWidgets.flatMap((widget) =>
+  widget.failure ? [widget.failure] : []
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgetState.ts b/invokeai/frontend/webv2/src/workbench/widgetState.ts
new file mode 100644
index 00000000000..63c14a7ef66
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgetState.ts
@@ -0,0 +1,21 @@
+import type { Project, WidgetInstanceContract, WidgetStateContract, WidgetTypeId } from './types';
+
+const emptyWidgetState = (widgetId: WidgetTypeId): WidgetStateContract => ({
+  id: widgetId,
+  label: widgetId,
+  values: {},
+  version: 1,
+});
+
+export const getProjectWidgetInstance = (
+  project: Project,
+  widgetId: WidgetTypeId
+): WidgetInstanceContract | undefined =>
+  project.widgetInstances[widgetId] ??
+  Object.values(project.widgetInstances).find((instance) => instance.typeId === widgetId);
+
+export const getProjectWidgetState = (project: Project, widgetId: WidgetTypeId): WidgetStateContract =>
+  getProjectWidgetInstance(project, widgetId)?.state ?? emptyWidgetState(widgetId);
+
+export const getProjectWidgetValues = (project: Project, widgetId: WidgetTypeId): Record<string, unknown> =>
+  getProjectWidgetState(project, widgetId).values;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/autosave-status/AutosaveStatusWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/autosave-status/AutosaveStatusWidgetView.tsx
new file mode 100644
index 00000000000..0fe18d913bf
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/autosave-status/AutosaveStatusWidgetView.tsx
@@ -0,0 +1,39 @@
+import type { WidgetViewProps } from '@workbench/types';
+
+import { Stack, Text } from '@chakra-ui/react';
+import { StatusWidgetChip } from '@workbench/widget-frame';
+import { useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { CloudAlertIcon, CloudCheckIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+export const AutosaveStatusWidgetView = ({ presentation }: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const autosave = useWorkbenchSelector((snapshot) => snapshot.state.autosave);
+  const icon = autosave.status === 'error' ? CloudAlertIcon : CloudCheckIcon;
+  const label = autosave.status === 'saved' ? t('common.saved') : autosave.status;
+
+  if (presentation === 'tooltip') {
+    return (
+      <Stack gap="2">
+        <Text fontSize="xs" fontWeight="700">
+          {t('widgets.autosaveStatus.label')}
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('widgets.autosaveStatus.status', { status: label })}
+        </Text>
+        {autosave.lastSavedAt ? (
+          <Text color="fg.subtle" fontSize="2xs">
+            {t('widgets.autosaveStatus.lastSaved', { time: autosave.lastSavedAt })}
+          </Text>
+        ) : null}
+        {autosave.error ? (
+          <Text color="fg.error" fontSize="2xs">
+            {autosave.error}
+          </Text>
+        ) : null}
+      </Stack>
+    );
+  }
+
+  return <StatusWidgetChip icon={icon}>{t('widgets.autosaveStatus.chipLabel', { status: label })}</StatusWidgetChip>;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/autosave-status/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/autosave-status/index.ts
new file mode 100644
index 00000000000..5c6bdea35e0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/autosave-status/index.ts
@@ -0,0 +1,17 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { CloudCheckIcon } from 'lucide-react';
+
+import { AutosaveStatusWidgetView } from './AutosaveStatusWidgetView';
+
+export const autosaveStatusWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['bottom'],
+  bottomPanel: 'tooltip',
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  icon: CloudCheckIcon,
+  id: 'autosave-status',
+  label: (t) => t('widgets.labels.autosaveStatus'),
+  version: 1,
+  view: AutosaveStatusWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/BboxDetailsBar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/BboxDetailsBar.tsx
new file mode 100644
index 00000000000..80397c23db5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/BboxDetailsBar.tsx
@@ -0,0 +1,86 @@
+import type { NumberInput as ChakraNumberInput } from '@chakra-ui/react';
+import type { BboxEditorEngine } from '@workbench/widgets/canvas/tool-options/useBboxEditor';
+
+import { HStack, NumberInput, Text } from '@chakra-ui/react';
+import { useBboxEditor } from '@workbench/widgets/canvas/tool-options/useBboxEditor';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export const BboxDetailsBar = ({ engine }: { engine: BboxEditorEngine }) => {
+  const { t } = useTranslation();
+  const { bbox, setHeight, setWidth, setX, setY } = useBboxEditor(engine);
+
+  const onWidthChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setWidth(valueAsNumber);
+      }
+    },
+    [setWidth]
+  );
+  const onHeightChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setHeight(valueAsNumber);
+      }
+    },
+    [setHeight]
+  );
+  const onXChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setX(valueAsNumber);
+      }
+    },
+    [setX]
+  );
+  const onYChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setY(valueAsNumber);
+      }
+    },
+    [setY]
+  );
+
+  return (
+    <HStack align="center" gap="3">
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.frameWidth')}
+        </Text>
+        <NumberInput.Root min={1} size="xs" value={String(bbox.width)} w="5rem" onValueChange={onWidthChange}>
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.frameWidth')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.frameHeight')}
+        </Text>
+        <NumberInput.Root min={1} size="xs" value={String(bbox.height)} w="5rem" onValueChange={onHeightChange}>
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.frameHeight')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.positionX')}
+        </Text>
+        <NumberInput.Root size="xs" value={String(bbox.x)} w="5rem" onValueChange={onXChange}>
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.positionX')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.positionY')}
+        </Text>
+        <NumberInput.Root size="xs" value={String(bbox.y)} w="5rem" onValueChange={onYChange}>
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.positionY')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomControls.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomControls.test.tsx
new file mode 100644
index 00000000000..f0cfabf63d5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomControls.test.tsx
@@ -0,0 +1,92 @@
+import type { ReactNode } from 'react';
+
+import {
+  getLayerPropertiesRequest,
+  requestLayerProperties,
+} from '@workbench/widgets/layers/layerPropertiesRequestStore';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  CanvasBottomControlsPresentation,
+  clearLayerPropertiesForOperationPresentation,
+  resolveBottomControlSlots,
+} from './CanvasBottomControls';
+
+const REGULAR_CONTENT = <span>regular</span>;
+const renderOperation = vi.fn((locked: boolean): ReactNode => <span data-locked={locked}>operation</span>);
+
+describe('canvas bottom controls', () => {
+  it('consumes any programmatic layer-properties request at the operation presentation boundary', () => {
+    requestLayerProperties('other-layer', 'filter');
+
+    clearLayerPropertiesForOperationPresentation();
+
+    expect(getLayerPropertiesRequest()).toBeNull();
+  });
+
+  it.each([
+    { externalLock: false, operationKind: null, expected: { operation: false, regular: true }, scenario: 'idle' },
+    { externalLock: true, operationKind: null, expected: { operation: false, regular: false }, scenario: 'staging' },
+    { externalLock: true, operationKind: null, expected: { operation: false, regular: false }, scenario: 'generation' },
+    {
+      externalLock: false,
+      operationKind: 'filter' as const,
+      expected: { operation: true, regular: false },
+      scenario: 'active Filter',
+    },
+    {
+      externalLock: true,
+      operationKind: 'filter' as const,
+      expected: { operation: true, regular: false },
+      scenario: 'active Filter plus staging and temporary View',
+    },
+    {
+      externalLock: false,
+      operationKind: 'select-object' as const,
+      expected: { operation: true, regular: false },
+      scenario: 'active SAM',
+    },
+    {
+      externalLock: true,
+      operationKind: 'select-object' as const,
+      expected: { operation: true, regular: false },
+      scenario: 'active SAM plus generation and temporary View',
+    },
+  ])('resolves $scenario bottom controls', ({ expected, externalLock, operationKind }) => {
+    expect(resolveBottomControlSlots({ isExternalInteractionLocked: externalLock, operationKind })).toEqual(expected);
+  });
+
+  it('mounts active operation content while locked, forwards the lock, and hides regular content', () => {
+    renderOperation.mockClear();
+    const output = renderToStaticMarkup(
+      <CanvasBottomControlsPresentation
+        isExternalInteractionLocked
+        operationKind="filter"
+        regularContent={REGULAR_CONTENT}
+        renderOperation={renderOperation}
+      />
+    );
+
+    expect(output).toContain('data-locked="true"');
+    expect(output).toContain('operation');
+    expect(output).not.toContain('regular');
+    expect(renderOperation).toHaveBeenCalledWith(true);
+  });
+
+  it.each([
+    { externalLock: false, expected: '<span>regular</span>', operationKind: null },
+    { externalLock: true, expected: '', operationKind: null },
+  ])('mounts idle content for externalLock=$externalLock', ({ expected, externalLock, operationKind }) => {
+    expect(
+      renderToStaticMarkup(
+        <CanvasBottomControlsPresentation
+          isExternalInteractionLocked={externalLock}
+          operationKind={operationKind}
+          regularContent={REGULAR_CONTENT}
+          renderOperation={renderOperation}
+        />
+      )
+    ).toBe(expected);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomControls.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomControls.tsx
new file mode 100644
index 00000000000..686daa07018
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomControls.tsx
@@ -0,0 +1,82 @@
+/* oxlint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-function-as-prop */
+import type { CanvasOperationState } from '@workbench/canvas-operations/operationController';
+import type { ReactNode } from 'react';
+
+import { Box } from '@chakra-ui/react';
+import { clearLayerPropertiesRequest } from '@workbench/widgets/layers/layerPropertiesRequestStore';
+import { useCallback } from 'react';
+
+import { CanvasOperationBar } from './tool-options/CanvasOperationBar';
+import { ToolOptionsBar, type CanvasToolOptionsEngine } from './tool-options/ToolOptionsBar';
+
+export const resolveBottomControlSlots = ({
+  isExternalInteractionLocked,
+  operationKind,
+}: {
+  isExternalInteractionLocked: boolean;
+  operationKind: 'filter' | 'select-object' | null;
+}): { operation: boolean; regular: boolean } => ({
+  operation: operationKind !== null,
+  regular: operationKind === null && !isExternalInteractionLocked,
+});
+
+export const clearLayerPropertiesForOperationPresentation = (): void => clearLayerPropertiesRequest();
+
+export const CanvasBottomControlsPresentation = ({
+  isExternalInteractionLocked,
+  operationKind,
+  regularContent,
+  renderOperation,
+}: {
+  isExternalInteractionLocked: boolean;
+  operationKind: 'filter' | 'select-object' | null;
+  regularContent: ReactNode;
+  renderOperation(isExternalInteractionLocked: boolean): ReactNode;
+}) => {
+  const slots = resolveBottomControlSlots({ isExternalInteractionLocked, operationKind });
+  if (slots.operation) {
+    return renderOperation(isExternalInteractionLocked);
+  }
+  return slots.regular ? regularContent : null;
+};
+
+export const CanvasBottomControls = ({
+  documentHeight,
+  documentWidth,
+  engine,
+  isExternalInteractionLocked,
+  operation,
+}: {
+  documentHeight: number | null;
+  documentWidth: number | null;
+  engine: CanvasToolOptionsEngine | null;
+  isExternalInteractionLocked: boolean;
+  operation: CanvasOperationState | null;
+}) => {
+  const operationKind = operation?.status === 'active' ? operation.identity.kind : null;
+  const consumeLayerPropertiesRef = useCallback((node: HTMLDivElement | null) => {
+    if (node) {
+      clearLayerPropertiesForOperationPresentation();
+    }
+  }, []);
+  if (!engine) {
+    return null;
+  }
+  const regularContent = (
+    <ToolOptionsBar documentHeight={documentHeight} documentWidth={documentWidth} engine={engine} />
+  );
+  const renderOperation = (locked: boolean): ReactNode =>
+    operation?.status === 'active' ? (
+      <Box ref={consumeLayerPropertiesRef} display="contents">
+        <CanvasOperationBar engine={engine} isExternalInteractionLocked={locked} operation={operation} />
+      </Box>
+    ) : null;
+  return (
+    <CanvasBottomControlsPresentation
+      isExternalInteractionLocked={isExternalInteractionLocked}
+      operationKind={operationKind}
+      regularContent={regularContent}
+      renderOperation={renderOperation}
+    />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomOverlay.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomOverlay.test.tsx
new file mode 100644
index 00000000000..0094cd6cde4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomOverlay.test.tsx
@@ -0,0 +1,44 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import {
+  BOTTOM_CONTROLS_SLOT_LAYOUT,
+  BOTTOM_OVERLAY_LAYOUT,
+  BOTTOM_OVERLAY_STACK_LAYOUT,
+  CanvasBottomOverlay,
+} from './CanvasBottomOverlay';
+
+describe('CanvasBottomOverlay', () => {
+  it('allocates only the canvas widget inset and allows the stack to shrink', () => {
+    expect(BOTTOM_OVERLAY_LAYOUT).toMatchObject({ bottom: '2', minH: '0', overflow: 'hidden', top: '2' });
+    expect(BOTTOM_OVERLAY_STACK_LAYOUT).toMatchObject({ h: 'full', minH: '0', overflow: 'hidden' });
+    expect(BOTTOM_CONTROLS_SLOT_LAYOUT).toMatchObject({ flex: '0 1 auto', minH: '0', overflow: 'hidden' });
+  });
+
+  it('server-renders staging above controls inside the bounded layout', () => {
+    const markup = renderToStaticMarkup(
+      <ChakraProvider value={system}>
+        <CanvasBottomOverlay.Root>
+          <CanvasBottomOverlay.Staging>Staging</CanvasBottomOverlay.Staging>
+          <CanvasBottomOverlay.Controls>Operation</CanvasBottomOverlay.Controls>
+        </CanvasBottomOverlay.Root>
+      </ChakraProvider>
+    );
+
+    expect(markup.indexOf('Staging')).toBeLessThan(markup.indexOf('Operation'));
+  });
+
+  it('forwards root props and ref-compatible attributes', () => {
+    const markup = renderToStaticMarkup(
+      <ChakraProvider value={system}>
+        <CanvasBottomOverlay.Root aria-label="Bottom chrome" data-forwarded="yes" id="bottom-overlay" />
+      </ChakraProvider>
+    );
+
+    expect(markup).toContain('aria-label="Bottom chrome"');
+    expect(markup).toContain('data-forwarded="yes"');
+    expect(markup).toContain('id="bottom-overlay"');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomOverlay.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomOverlay.tsx
new file mode 100644
index 00000000000..646e8bee2ce
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasBottomOverlay.tsx
@@ -0,0 +1,49 @@
+import type { BoxProps, FlexProps, StackProps } from '@chakra-ui/react';
+
+import { Box, Flex, Stack } from '@chakra-ui/react';
+import { forwardRef } from 'react';
+
+export const BOTTOM_OVERLAY_LAYOUT = {
+  bottom: '2',
+  left: '2',
+  minH: '0',
+  overflow: 'hidden',
+  pointerEvents: 'none',
+  position: 'absolute',
+  right: '2',
+  top: '2',
+  zIndex: '3',
+} satisfies BoxProps;
+
+export const BOTTOM_OVERLAY_STACK_LAYOUT = {
+  align: 'center',
+  h: 'full',
+  justifyContent: 'flex-end',
+  minH: '0',
+  overflow: 'hidden',
+} satisfies StackProps;
+
+export const BOTTOM_CONTROLS_SLOT_LAYOUT = {
+  align: 'center',
+  flex: '0 1 auto',
+  justify: 'center',
+  minH: '0',
+  minW: '0',
+  overflow: 'hidden',
+  w: 'full',
+} satisfies FlexProps;
+
+const Root = forwardRef<HTMLDivElement, BoxProps>(({ children, ...props }, ref) => (
+  <Box ref={ref} {...BOTTOM_OVERLAY_LAYOUT} {...props}>
+    <Stack {...BOTTOM_OVERLAY_STACK_LAYOUT} gap="2">
+      {children}
+    </Stack>
+  </Box>
+));
+Root.displayName = 'CanvasBottomOverlay.Root';
+
+const Staging = (props: BoxProps) => <Box flexShrink="0" {...props} />;
+
+const Controls = (props: FlexProps) => <Flex {...BOTTOM_CONTROLS_SLOT_LAYOUT} {...props} />;
+
+export const CanvasBottomOverlay = { Controls, Root, Staging };
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasFloatingBar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasFloatingBar.tsx
new file mode 100644
index 00000000000..e14c986857b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasFloatingBar.tsx
@@ -0,0 +1,26 @@
+import type { PanelProps } from '@workbench/components/ui';
+
+import { Box } from '@chakra-ui/react';
+import { Panel } from '@workbench/components/ui';
+
+/**
+ * Shared floating-panel chrome for the canvas: the raised, rounded, shadowed
+ * surface that the tool options bar, the staging bar, and (later) the text-tool
+ * / layer-selection quick bars all sit on. It supplies only the *look* and
+ * re-enables pointer events (its parent group is click-through); positioning
+ * over the surface is the parent's job.
+ *
+ * Composition-friendly: consumers lay out their own sections inside — an
+ * `HStack` of controls, `{@link CanvasFloatingBarDivider}` between groups — so
+ * no per-consumer boolean props accrete here.
+ */
+export const CanvasFloatingBar = ({ children, ...rest }: PanelProps) => (
+  <Panel density="sm" pointerEvents="auto" rounded="lg" shadow="lg" p="1" tone="surface" {...rest}>
+    {children}
+  </Panel>
+);
+
+/** A thin vertical rule separating groups of controls inside a {@link CanvasFloatingBar}. */
+export const CanvasFloatingBarDivider = () => (
+  <Box alignSelf="stretch" bg="border.subtle" flexShrink="0" my="0.5" w="1px" />
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasGlobalContextMenu.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasGlobalContextMenu.test.tsx
new file mode 100644
index 00000000000..42823e6faa4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasGlobalContextMenu.test.tsx
@@ -0,0 +1,40 @@
+import { ChakraProvider, Menu } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createInstance } from 'i18next';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { I18nextProvider } from 'react-i18next';
+import { describe, expect, it } from 'vitest';
+
+import { CanvasGlobalContextMenu } from './CanvasGlobalContextMenu';
+
+const englishCatalogModules = import.meta.glob('../../../../public/locales/en.json', {
+  eager: true,
+  import: 'default',
+});
+const enCatalog = Object.values(englishCatalogModules)[0] as Record<string, unknown>;
+const testI18n = createInstance();
+await testI18n.init({
+  initImmediate: false,
+  lng: 'en',
+  resources: { en: { translation: enCatalog } },
+});
+const target = { layerId: null, x: 10, y: 20 } as const;
+const noop = () => undefined;
+
+describe('CanvasGlobalContextMenu', () => {
+  it('labels empty-canvas actions as Canvas', () => {
+    const markup = renderToStaticMarkup(
+      <ChakraProvider value={system}>
+        <I18nextProvider i18n={testI18n}>
+          <CanvasGlobalContextMenu target={target} onClose={noop}>
+            <Menu.Item value="test-action">Test action</Menu.Item>
+          </CanvasGlobalContextMenu>
+        </I18nextProvider>
+      </ChakraProvider>
+    );
+
+    expect(markup).toContain('Test action');
+    expect(markup).toContain('>Canvas<');
+    expect(markup.indexOf('>Canvas<')).toBeLessThan(markup.indexOf('Test action'));
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasGlobalContextMenu.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasGlobalContextMenu.tsx
new file mode 100644
index 00000000000..52ef142c292
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasGlobalContextMenu.tsx
@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+
+import { Menu, Portal } from '@chakra-ui/react';
+import { MenuContent } from '@workbench/components/ui';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { CanvasContextMenuTarget } from './canvasContextMenu';
+
+export const CanvasGlobalContextMenu = ({
+  children,
+  onClose,
+  target,
+}: {
+  children: ReactNode;
+  onClose: () => void;
+  target: CanvasContextMenuTarget;
+}) => {
+  const { t } = useTranslation();
+  const positioning = useMemo(
+    () => ({
+      getAnchorRect: () => ({ height: 1, width: 1, x: target.x, y: target.y }),
+      placement: 'bottom-start' as const,
+    }),
+    [target.x, target.y]
+  );
+  const onOpenChange = useCallback(
+    (details: { open: boolean }) => {
+      if (!details.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  return (
+    <Menu.Root lazyMount open positioning={positioning} unmountOnExit onOpenChange={onOpenChange}>
+      <Portal>
+        <Menu.Positioner>
+          <MenuContent minW="14rem" py="1">
+            <Menu.ItemGroup>
+              <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                {t('widgets.labels.canvas')}
+              </Menu.ItemGroupLabel>
+              {children}
+            </Menu.ItemGroup>
+          </MenuContent>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasHeaderActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasHeaderActions.tsx
new file mode 100644
index 00000000000..10a7108f7ac
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasHeaderActions.tsx
@@ -0,0 +1,377 @@
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { Project, WidgetViewProps } from '@workbench/types';
+/* oxlint-disable react-perf/jsx-no-new-function-as-prop */
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+
+import { Box, HStack, Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { createNewCanvasStateV2 } from '@workbench/canvasMigration';
+import { ConfirmDialog, IconButton, MenuContent, Tooltip } from '@workbench/components/ui';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { useModifierHeld } from '@workbench/useModifierHeld';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import {
+  BugIcon,
+  CheckIcon,
+  ChevronDownIcon,
+  DatabaseIcon,
+  FilePlusIcon,
+  FrameIcon,
+  MaximizeIcon,
+  Redo2Icon,
+  SettingsIcon,
+  SquareDashedBottomIcon,
+  Trash2Icon,
+  Undo2Icon,
+} from 'lucide-react';
+import { Fragment, useCallback, useEffect, useEffectEvent, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { CanvasBooleanSetting, ResolvedCanvasSettings } from './canvasSettings';
+
+import { gridSizeForModelBase } from './bboxGrid';
+import {
+  CANVAS_SETTING_SECTIONS,
+  CANVAS_SETTINGS,
+  CANVAS_SNAP_TO_GRID_KEY,
+  canvasSettingsEqual,
+  resolveCanvasSettings,
+} from './canvasSettings';
+import { useCanvasCanRedo, useCanvasCanUndo, useCanvasDocumentEditingLocked, useCanvasZoom } from './engineStoreHooks';
+import { computeFitBboxToLayers, computeFitBboxToMasks } from './fitBbox';
+import { useCanvasEngine } from './useCanvasEngine';
+import { formatZoomPercent, zoomMenuOptions } from './zoomOptions';
+
+type CanvasHeaderEngine = Pick<CanvasEngineHandle, 'diagnostics' | 'history' | 'layers' | 'stores' | 'viewport'>;
+
+const ZOOM_OPTIONS = zoomMenuOptions();
+const MENU_POSITIONING = { placement: 'bottom-end' } as const;
+
+/** Reads the persisted, default-applied canvas settings for the active project. */
+const selectCanvasSettings = (project: Project): ResolvedCanvasSettings =>
+  resolveCanvasSettings(getProjectWidgetValues(project, 'canvas'));
+
+/** Reads the active generate model's base, so fit-bbox snaps to the same grid the bbox tool uses. */
+const selectModelBase = (project: Project): string | null => {
+  const values = getProjectWidgetValues(project, 'generate') as { model?: { base?: unknown } } | undefined;
+  return typeof values?.model?.base === 'string' ? values.model.base : null;
+};
+
+/**
+ * Canvas widget header actions, in legacy toolbar order: the zoom-percent menu, a
+ * reset-view (fit content to view) button, fit-bbox-to-layers / fit-bbox-to-masks,
+ * undo / redo, a new-session menu, and the sectioned settings popover. Rendered in
+ * the widget frame's header slot; resolves the shared engine like the layers header
+ * does, and renders nothing until it is available.
+ *
+ * Excluded per product decision: the project (save/load) menu, a save-to-gallery
+ * button (its command/hotkey stays), and the snapshot menu.
+ */
+export const CanvasHeaderActions = ({ runtime }: WidgetViewProps) => {
+  const engine = useCanvasEngine();
+  return engine ? <CanvasHeaderActionsInner engine={engine} runtime={runtime} /> : null;
+};
+
+const CanvasHeaderActionsInner = ({
+  engine,
+  runtime,
+}: {
+  engine: CanvasHeaderEngine;
+  runtime: WidgetViewProps['runtime'];
+}) => {
+  const { t } = useTranslation();
+  const dispatch = useCanvasProjectMutationDispatch();
+  const zoom = useCanvasZoom(engine);
+  const canUndo = useCanvasCanUndo(engine);
+  const canRedo = useCanvasCanRedo(engine);
+  const editingLocked = useCanvasDocumentEditingLocked(engine);
+  const document = useActiveProjectSelector((project) => project.canvas.document);
+  const modelBase = useActiveProjectSelector(selectModelBase);
+  const settings = useActiveProjectSelector(selectCanvasSettings, canvasSettingsEqual);
+
+  const [isNewCanvasOpen, setIsNewCanvasOpen] = useState(false);
+  const closeNewCanvas = useCallback(() => setIsNewCanvasOpen(false), []);
+  const openNewCanvas = useCallback(() => {
+    if (!editingLocked) {
+      setIsNewCanvasOpen(true);
+    }
+  }, [editingLocked]);
+
+  const setZoom = (value: number) => {
+    const viewport = engine.viewport.getViewport();
+    const size = viewport.getViewportSize();
+    viewport.zoomAtPoint(value, { x: size.width / 2, y: size.height / 2 });
+  };
+
+  // Fit-bbox honors the snap-to-grid setting: snapping off ⇒ grid 1 (a plain round).
+  const gridSize = settings[CANVAS_SNAP_TO_GRID_KEY] ? gridSizeForModelBase(modelBase) : 1;
+  const fitLayersRect = useMemo(() => computeFitBboxToLayers(document, gridSize), [document, gridSize]);
+  const fitMasksRect = useMemo(() => computeFitBboxToMasks(document, gridSize), [document, gridSize]);
+
+  // One undoable `setCanvasBbox` (inverse restores the current bbox) — exactly how a
+  // manual bbox-tool edit commits. `refit` re-centers the view afterward (legacy
+  // re-fits the stage after fit-to-layers, but not after fit-to-masks).
+  const applyFit = (rect: Rect | null, refit: boolean) => {
+    if (editingLocked || !rect) {
+      return;
+    }
+    engine.layers.commitStructural(
+      t('widgets.canvas.commands.fitBbox'),
+      { bbox: rect, type: 'setCanvasBbox' },
+      { bbox: document.bbox, type: 'setCanvasBbox' }
+    );
+    if (refit) {
+      engine.viewport.fitToView();
+    }
+  };
+
+  const confirmNewCanvas = useCallback(() => {
+    if (editingLocked) {
+      return;
+    }
+    // A wholesale document replace (seeded with one empty inpaint mask, matching
+    // Task 42's new-canvas init) at the current dimensions. The engine's mirror
+    // treats this as a document swap and clears the canvas history by design, so
+    // this is intentionally NOT undoable — the confirm dialog is the safety net.
+    dispatch({
+      document: createNewCanvasStateV2(document.width, document.height).document,
+      type: 'replaceCanvasDocument',
+    });
+  }, [dispatch, document.height, document.width, editingLocked]);
+
+  // Commands (hotkey-assignable; catalog ids `canvas.fitBboxToLayers` /
+  // `canvas.fitBboxToMasks` / `canvas.newSession`). `useEffectEvent` reads the
+  // latest fit rects / dialog opener without re-registering per document change.
+  // The new-session command routes through the SAME confirm dialog as the button.
+  const executeHeaderCommand = useEffectEvent((commandId: string) => {
+    if (commandId === 'canvas.fitBboxToLayers') {
+      applyFit(fitLayersRect, true);
+    } else if (commandId === 'canvas.fitBboxToMasks') {
+      applyFit(fitMasksRect, false);
+    } else if (commandId === 'canvas.newSession') {
+      openNewCanvas();
+    }
+  });
+  useEffect(() => {
+    const entries = [
+      ['canvas.fitBboxToLayers', t('widgets.canvas.controls.fitBboxToLayers'), ['shift+n']],
+      ['canvas.fitBboxToMasks', t('widgets.canvas.controls.fitBboxToMasks'), ['shift+b']],
+      // No default keys — assignable through the hotkeys settings.
+      ['canvas.newSession', t('widgets.canvas.controls.newSession'), []],
+    ] as const;
+    const disposers = entries.flatMap(([id, title, defaultKeys]) => [
+      runtime.commands.register({ handler: () => executeHeaderCommand(id), id, title }),
+      runtime.hotkeys.register({ allowInEditable: false, commandId: id, defaultKeys: [...defaultKeys], id, title }),
+    ]);
+    return () => {
+      disposers.forEach((dispose) => dispose());
+    };
+  }, [runtime.commands, runtime.hotkeys, t]);
+
+  return (
+    <HStack gap="0.5">
+      <Menu.Root positioning={MENU_POSITIONING}>
+        <Menu.Trigger asChild>
+          <IconButton aria-label={t('widgets.canvas.controls.zoomLevel')} minW="4rem" px="2" size="2xs" variant="ghost">
+            <HStack gap="1">
+              <Text fontSize="xs" fontVariantNumeric="tabular-nums">
+                {formatZoomPercent(zoom)}
+              </Text>
+              <ChevronDownIcon size={12} />
+            </HStack>
+          </IconButton>
+        </Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent minW="7rem" py="1">
+              {ZOOM_OPTIONS.map((option) => (
+                <Menu.Item key={option.value} value={option.label} onClick={() => setZoom(option.value)}>
+                  <CheckIcon size={12} opacity={formatZoomPercent(zoom) === option.label ? 1 : 0} />
+                  <Menu.ItemText fontSize="xs">{option.label}</Menu.ItemText>
+                </Menu.Item>
+              ))}
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+
+      <Tooltip content={t('widgets.canvas.controls.fitToView')}>
+        <IconButton color="fg.muted" size="2xs" variant="ghost" onClick={() => engine.viewport.fitToView()}>
+          <MaximizeIcon />
+        </IconButton>
+      </Tooltip>
+
+      <Tooltip content={t('widgets.canvas.controls.fitBboxToLayers')}>
+        <IconButton
+          color="fg.muted"
+          disabled={editingLocked || !fitLayersRect}
+          size="2xs"
+          variant="ghost"
+          onClick={() => applyFit(fitLayersRect, true)}
+        >
+          <FrameIcon />
+        </IconButton>
+      </Tooltip>
+
+      <Tooltip content={t('widgets.canvas.controls.fitBboxToMasks')}>
+        <IconButton
+          color="fg.muted"
+          disabled={editingLocked || !fitMasksRect}
+          size="2xs"
+          variant="ghost"
+          onClick={() => applyFit(fitMasksRect, false)}
+        >
+          <SquareDashedBottomIcon />
+        </IconButton>
+      </Tooltip>
+
+      <HeaderDivider />
+
+      <Tooltip content={t('widgets.canvas.commands.undo')}>
+        <IconButton
+          color="fg.muted"
+          disabled={editingLocked || !canUndo}
+          size="2xs"
+          variant="ghost"
+          onClick={() => engine.history.undo()}
+        >
+          <Undo2Icon />
+        </IconButton>
+      </Tooltip>
+
+      <Tooltip content={t('widgets.canvas.commands.redo')}>
+        <IconButton
+          color="fg.muted"
+          disabled={editingLocked || !canRedo}
+          size="2xs"
+          variant="ghost"
+          onClick={() => engine.history.redo()}
+        >
+          <Redo2Icon />
+        </IconButton>
+      </Tooltip>
+
+      <Menu.Root positioning={MENU_POSITIONING}>
+        <Tooltip content={t('widgets.canvas.controls.newSession')}>
+          <span style={{ display: 'inline-flex' }}>
+            <Menu.Trigger asChild>
+              <IconButton
+                aria-label={t('widgets.canvas.controls.newSession')}
+                color="fg.muted"
+                disabled={editingLocked}
+                size="2xs"
+                variant="ghost"
+              >
+                <FilePlusIcon />
+              </IconButton>
+            </Menu.Trigger>
+          </span>
+        </Tooltip>
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent minW="11rem" py="1">
+              <Menu.Item value="new-canvas" onClick={openNewCanvas}>
+                <Icon as={FilePlusIcon} boxSize="3.5" color="fg.subtle" />
+                <Menu.ItemText fontSize="xs">{t('widgets.canvas.controls.newCanvas')}</Menu.ItemText>
+              </Menu.Item>
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+
+      <CanvasSettingsMenu editingLocked={editingLocked} engine={engine} />
+
+      <ConfirmDialog
+        body={t('widgets.canvas.controls.newCanvasConfirm')}
+        confirmLabel={t('widgets.canvas.controls.newCanvas')}
+        isOpen={isNewCanvasOpen}
+        title={t('widgets.canvas.controls.newCanvas')}
+        onClose={closeNewCanvas}
+        onConfirm={confirmNewCanvas}
+      />
+    </HStack>
+  );
+};
+
+/** A thin vertical rule separating header-action groups (matching legacy's dividers). */
+const HeaderDivider = () => <Box bg="border.subtle" flexShrink={0} h="4" mx="1" w="1px" />;
+
+/**
+ * The gear-icon settings popover: the data-driven boolean preferences grouped into
+ * Behavior / Display / Grid sections, plus a Shift-revealed Debug group of engine
+ * actions (matching legacy `CanvasSettingsPopover`). `closeOnSelect={false}` keeps
+ * it open while toggling. Settings persist per-project and never enter undo history.
+ */
+const CanvasSettingsMenu = ({ editingLocked, engine }: { editingLocked: boolean; engine: CanvasHeaderEngine }) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const settings = useActiveProjectSelector(selectCanvasSettings, canvasSettingsEqual);
+  // Shift reveals the Debug section, matching legacy `useShiftModifier` (event-driven).
+  const shiftHeld = useModifierHeld('Shift');
+
+  const toggle = (setting: CanvasBooleanSetting) => {
+    dispatch({
+      type: 'patchWidgetValues',
+      values: { [setting.key]: !settings[setting.key] },
+      widgetId: 'canvas',
+    });
+  };
+
+  return (
+    <Menu.Root closeOnSelect={false} positioning={MENU_POSITIONING}>
+      <Menu.Trigger asChild>
+        <IconButton aria-label={t('widgets.canvas.settings.label')} color="fg.muted" size="2xs" variant="ghost">
+          <SettingsIcon />
+        </IconButton>
+      </Menu.Trigger>
+      <Portal>
+        <Menu.Positioner>
+          <MenuContent minW="15rem" py="1">
+            {CANVAS_SETTING_SECTIONS.map((section, sectionIndex) => (
+              <Fragment key={section}>
+                {sectionIndex > 0 ? <Menu.Separator borderColor="border.subtle" /> : null}
+                <Menu.ItemGroup>
+                  <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                    {t(`widgets.canvas.settings.sections.${section}`)}
+                  </Menu.ItemGroupLabel>
+                  {CANVAS_SETTINGS.filter((setting) => setting.section === section).map((setting) => (
+                    <Menu.Item key={setting.key} value={setting.key} onClick={() => toggle(setting)}>
+                      <Icon as={CheckIcon} boxSize="3.5" opacity={settings[setting.key] ? 1 : 0} />
+                      <Menu.ItemText fontSize="xs">{t(setting.labelKey)}</Menu.ItemText>
+                    </Menu.Item>
+                  ))}
+                </Menu.ItemGroup>
+              </Fragment>
+            ))}
+            {shiftHeld ? (
+              <>
+                <Menu.Separator borderColor="border.subtle" />
+                <Menu.ItemGroup>
+                  <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                    {t('widgets.canvas.settings.sections.debug')}
+                  </Menu.ItemGroupLabel>
+                  <Menu.Item value="debug-clear-caches" onClick={() => void engine.diagnostics.clearCaches()}>
+                    <Icon as={DatabaseIcon} boxSize="3.5" color="fg.subtle" />
+                    <Menu.ItemText fontSize="xs">{t('widgets.canvas.settings.clearCaches')}</Menu.ItemText>
+                  </Menu.Item>
+                  <Menu.Item value="debug-log-info" onClick={() => engine.diagnostics.logDebugInfo()}>
+                    <Icon as={BugIcon} boxSize="3.5" color="fg.subtle" />
+                    <Menu.ItemText fontSize="xs">{t('widgets.canvas.settings.logDebugInfo')}</Menu.ItemText>
+                  </Menu.Item>
+                  <Menu.Item
+                    disabled={editingLocked}
+                    value="debug-clear-history"
+                    onClick={() => engine.history.clearHistory()}
+                  >
+                    <Icon as={Trash2Icon} boxSize="3.5" color="fg.subtle" />
+                    <Menu.ItemText fontSize="xs">{t('widgets.canvas.settings.clearHistory')}</Menu.ItemText>
+                  </Menu.Item>
+                </Menu.ItemGroup>
+              </>
+            ) : null}
+          </MenuContent>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasImageDropOverlay.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasImageDropOverlay.tsx
new file mode 100644
index 00000000000..d51caba9b4a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasImageDropOverlay.tsx
@@ -0,0 +1,61 @@
+import { Grid } from '@chakra-ui/react';
+import { useDndContext } from '@dnd-kit/core';
+import { isGalleryImageDragData } from '@workbench/widgets/gallery/galleryDnd';
+
+import { getCanvasImageDropData, getCanvasImageDropId } from './canvasImageDnd';
+import { CanvasImageDropZone, type CanvasImageDropZoneProps } from './CanvasImageDropZone';
+
+export const CANVAS_IMAGE_DROP_LAYOUT = [
+  { destination: 'raster', colSpan: 3, row: 1 },
+  { destination: 'control', colSpan: 3, row: 1 },
+  { destination: 'regional-reference', colSpan: 2, row: 2 },
+  { destination: 'inpaint-mask', colSpan: 2, row: 2 },
+  { destination: 'control-resized', colSpan: 2, row: 2 },
+] as const;
+
+export const CANVAS_IMAGE_DROP_GRID_LAYOUT = {
+  gap: '0',
+  padding: '0',
+  templateColumns: 'repeat(6, minmax(0, 1fr))',
+  templateRows: 'repeat(2, minmax(0, 1fr))',
+} as const;
+
+const LABEL_KEYS = {
+  control: 'widgets.canvas.import.dropControl',
+  'control-resized': 'widgets.canvas.import.dropResizedControl',
+  'inpaint-mask': 'widgets.canvas.import.dropInpaintMask',
+  raster: 'widgets.canvas.import.dropRaster',
+  'regional-reference': 'widgets.canvas.import.dropRegionalReference',
+} as const satisfies Record<
+  (typeof CANVAS_IMAGE_DROP_LAYOUT)[number]['destination'],
+  CanvasImageDropZoneProps['labelKey']
+>;
+
+const CANVAS_IMAGE_DROP_ZONES = CANVAS_IMAGE_DROP_LAYOUT.map((zone) => ({
+  ...zone,
+  data: getCanvasImageDropData(zone.destination),
+  id: getCanvasImageDropId(zone.destination),
+  labelKey: LABEL_KEYS[zone.destination],
+})) satisfies readonly CanvasImageDropZoneProps[];
+
+export const CanvasImageDropOverlay = ({
+  isDocumentEditingLocked,
+  isInteractionLocked,
+}: {
+  isDocumentEditingLocked: boolean;
+  isInteractionLocked: boolean;
+}) => {
+  const { active } = useDndContext();
+
+  if (isDocumentEditingLocked || isInteractionLocked || !isGalleryImageDragData(active?.data.current)) {
+    return null;
+  }
+
+  return (
+    <Grid {...CANVAS_IMAGE_DROP_GRID_LAYOUT} inset="0" pointerEvents="none" position="absolute" zIndex="2">
+      {CANVAS_IMAGE_DROP_ZONES.map((zone) => (
+        <CanvasImageDropZone key={zone.id} {...zone} />
+      ))}
+    </Grid>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasImageDropZone.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasImageDropZone.tsx
new file mode 100644
index 00000000000..dfe16ec31f4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasImageDropZone.tsx
@@ -0,0 +1,46 @@
+import { Flex, GridItem, Text } from '@chakra-ui/react';
+import { useDroppable } from '@dnd-kit/core';
+import { useTranslation } from 'react-i18next';
+
+import type { CanvasImageDropData } from './canvasImageDnd';
+
+export interface CanvasImageDropZoneProps {
+  colSpan: number;
+  data: CanvasImageDropData;
+  id: string;
+  labelKey:
+    | 'widgets.canvas.import.dropControl'
+    | 'widgets.canvas.import.dropInpaintMask'
+    | 'widgets.canvas.import.dropRaster'
+    | 'widgets.canvas.import.dropRegionalReference'
+    | 'widgets.canvas.import.dropResizedControl';
+  row: number;
+}
+
+export const CanvasImageDropZone = ({ colSpan, data, id, labelKey, row }: CanvasImageDropZoneProps) => {
+  const { t } = useTranslation();
+  const { isOver, setNodeRef } = useDroppable({ data, id });
+
+  return (
+    <GridItem ref={setNodeRef} colSpan={colSpan} gridRow={row} position="relative">
+      <Flex
+        alignItems="center"
+        bg={isOver ? 'accent.subtle' : 'bg.muted'}
+        borderColor={isOver ? 'accent.solid' : 'border.emphasized'}
+        borderStyle="dashed"
+        borderWidth="2px"
+        inset="0.5"
+        justifyContent="center"
+        opacity={isOver ? 0.98 : 0.88}
+        position="absolute"
+        rounded="md"
+        shadow={isOver ? '0 0 0 1px {colors.accent.solid}' : undefined}
+        transition="background var(--wb-motion-duration-fast) ease, border-color var(--wb-motion-duration-fast) ease, opacity var(--wb-motion-duration-fast) ease, box-shadow var(--wb-motion-duration-fast) ease"
+      >
+        <Text color="fg" fontSize="sm" fontWeight="700" textAlign="center">
+          {t(labelKey)}
+        </Text>
+      </Flex>
+    </GridItem>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSaveToGallerySubmenu.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSaveToGallerySubmenu.tsx
new file mode 100644
index 00000000000..6b21996119f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSaveToGallerySubmenu.tsx
@@ -0,0 +1,59 @@
+import type { CanvasGallerySaveRegion } from '@workbench/canvas-operations/saveCanvasToGallery';
+
+import { HStack, Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { MenuContent } from '@workbench/components/ui';
+import { ChevronRightIcon, SaveIcon } from 'lucide-react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const SUBMENU_POSITIONING = { placement: 'right-start' } as const;
+
+export const CanvasSaveToGallerySubmenu = ({
+  disabled,
+  onSave,
+}: {
+  disabled: boolean;
+  onSave: (region: CanvasGallerySaveRegion) => void;
+}) => {
+  const { t } = useTranslation();
+  const onSaveCanvas = useCallback(() => onSave('canvas'), [onSave]);
+  const onSaveBbox = useCallback(() => onSave('bbox'), [onSave]);
+
+  return (
+    <Menu.Root positioning={SUBMENU_POSITIONING}>
+      <Menu.TriggerItem asChild>
+        <button disabled={disabled} type="button">
+          <HStack gap="2" minW="0" w="full">
+            <Icon as={SaveIcon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+            <Text flex="1" fontSize="xs">
+              {t('widgets.canvas.contextMenu.saveToGallery')}
+            </Text>
+            <Icon as={ChevronRightIcon} boxSize="3" color="fg.subtle" flexShrink={0} />
+          </HStack>
+        </button>
+      </Menu.TriggerItem>
+      <Portal>
+        <Menu.Positioner>
+          <MenuContent minW="13rem" py="1">
+            <Menu.Item disabled={disabled} value="save-canvas" onSelect={onSaveCanvas}>
+              <HStack gap="2" minW="0" w="full">
+                <Icon as={SaveIcon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+                <Text flex="1" fontSize="xs">
+                  {t('widgets.canvas.contextMenu.saveCanvasToGallery')}
+                </Text>
+              </HStack>
+            </Menu.Item>
+            <Menu.Item disabled={disabled} value="save-bbox" onSelect={onSaveBbox}>
+              <HStack gap="2" minW="0" w="full">
+                <Icon as={SaveIcon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+                <Text flex="1" fontSize="xs">
+                  {t('widgets.canvas.contextMenu.saveBboxToGallery')}
+                </Text>
+              </HStack>
+            </Menu.Item>
+          </MenuContent>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurface.browser.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurface.browser.test.tsx
new file mode 100644
index 00000000000..9fa5cf971dd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurface.browser.test.tsx
@@ -0,0 +1,210 @@
+import type { CanvasEngine } from '@workbench/canvas-operations/createCanvasEngine';
+import type { EngineDeps, EngineRegistry } from '@workbench/canvas-operations/engineRegistry';
+import type { CanvasProjectMutationPort } from '@workbench/canvasProjectMutationPort';
+import type { CanvasStateContractV2 } from '@workbench/types';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createEngineRegistry } from '@workbench/canvas-operations/engineRegistry';
+import { createEmptyCanvasStateV2 } from '@workbench/canvasMigration';
+import { act, StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { CanvasSurface } from './CanvasSurface';
+
+type Cleanup = () => void | Promise<void>;
+
+const cleanupStack: Cleanup[] = [];
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const addCleanup = (cleanup: Cleanup): void => {
+  cleanupStack.push(cleanup);
+};
+
+const delay = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    globalThis.setTimeout(resolve, ms);
+  });
+
+const createTrackedRegistry = (gracePeriodMs: number): EngineRegistry => {
+  const registry = createEngineRegistry({ gracePeriodMs });
+  // Registered before references and roots, so reverse-order cleanup releases
+  // those first and then lets the registry's grace timers finish.
+  addCleanup(() => delay(gracePeriodMs + 20));
+  return registry;
+};
+
+const acquireTrackedEngine = (
+  registry: EngineRegistry,
+  projectId: string,
+  deps: EngineDeps
+): { engine: CanvasEngine; release: () => void } => {
+  const engine = registry.getOrCreateEngine(projectId, deps);
+  let isHeld = true;
+  const release = (): void => {
+    if (!isHeld) {
+      return;
+    }
+    isHeld = false;
+    registry.releaseEngine(projectId);
+  };
+  addCleanup(release);
+  return { engine, release };
+};
+
+const createTrackedRoot = (host: HTMLDivElement) => {
+  const root = createRoot(host);
+  let isMounted = true;
+  const unmount = async (): Promise<void> => {
+    if (!isMounted) {
+      return;
+    }
+    isMounted = false;
+    try {
+      await act(() => {
+        root.unmount();
+      });
+    } finally {
+      host.remove();
+    }
+  };
+  addCleanup(unmount);
+  return { root, unmount };
+};
+
+const createEngineDeps = (state: CanvasStateContractV2): EngineDeps => {
+  const listeners = new Set<() => void>();
+  const mutationPort: CanvasProjectMutationPort = {
+    dispatch: () => false,
+    getCanvasState: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+  return {
+    getMainModelBase: () => null,
+    imageResolver: () => Promise.resolve(new Blob()),
+    mutationPort,
+    reportError: () => undefined,
+  };
+};
+
+const nextFrame = (): Promise<void> =>
+  new Promise((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
+
+const StrictCanvasHarness = ({ engine }: { engine: CanvasEngine }) => (
+  <StrictMode>
+    <ChakraProvider value={system}>
+      <div data-testid="surface-bounds" style={{ height: 120, width: 160 }}>
+        <CanvasSurface engine={engine} />
+      </div>
+    </ChakraProvider>
+  </StrictMode>
+);
+
+afterEach(async () => {
+  let firstError: unknown;
+  for (const cleanup of cleanupStack.reverse()) {
+    try {
+      await cleanup();
+    } catch (error) {
+      firstError ??= error;
+    }
+  }
+  cleanupStack.length = 0;
+  vi.restoreAllMocks();
+  if (firstError) {
+    throw new Error('CanvasSurface browser-test cleanup failed', { cause: firstError });
+  }
+});
+
+describe('CanvasSurface browser lifecycle', () => {
+  it('is StrictMode-safe across resize, registry reacquisition, detachment, and project switching', async () => {
+    const gracePeriodMs = 80;
+    const registry = createTrackedRegistry(gracePeriodMs);
+    const projectADeps = createEngineDeps(createEmptyCanvasStateV2(64, 64));
+    const firstProjectA = acquireTrackedEngine(registry, 'project-a', projectADeps);
+    const disposeA = vi.spyOn(firstProjectA.engine.lifecycle, 'dispose');
+    const beginCooldownA = vi.spyOn(firstProjectA.engine.lifecycle, 'beginCooldown');
+    const releasedAt = performance.now();
+    firstProjectA.release();
+    expect(beginCooldownA).toHaveBeenCalledOnce();
+    expect(firstProjectA.engine.lifecycle.getLifecycleState()).toBe('cooling');
+
+    await delay(5);
+    const reacquiredProjectA = acquireTrackedEngine(registry, 'project-a', projectADeps);
+    const projectA = reacquiredProjectA.engine;
+    expect(projectA).toBe(firstProjectA.engine);
+    expect(projectA.lifecycle.getLifecycleState()).toBe('active');
+
+    const originalDeadline = releasedAt + gracePeriodMs;
+    await delay(Math.max(0, originalDeadline - performance.now()) + 20);
+    expect(performance.now()).toBeGreaterThan(originalDeadline);
+    expect(registry.getEngine('project-a')).toBe(projectA);
+    expect(disposeA).not.toHaveBeenCalled();
+    expect(projectA.lifecycle.getLifecycleState()).toBe('active');
+
+    const projectBReference = acquireTrackedEngine(
+      registry,
+      'project-b',
+      createEngineDeps(createEmptyCanvasStateV2(32, 48))
+    );
+    const projectB = projectBReference.engine;
+    const attachA = vi.spyOn(projectA.surface, 'attach');
+    const resizeA = vi.spyOn(projectA.surface, 'resize');
+    const detachA = vi.spyOn(projectA.surface, 'detach');
+    const attachB = vi.spyOn(projectB.surface, 'attach');
+    const resizeB = vi.spyOn(projectB.surface, 'resize');
+    const detachB = vi.spyOn(projectB.surface, 'detach');
+
+    const host = document.createElement('div');
+    document.body.append(host);
+    const { root, unmount } = createTrackedRoot(host);
+
+    await act(async () => {
+      root.render(<StrictCanvasHarness engine={projectA} />);
+      await nextFrame();
+    });
+
+    expect(attachA).toHaveBeenCalled();
+    expect(resizeA).toHaveBeenCalledWith(160, 120, globalThis.devicePixelRatio || 1);
+    const firstScreen = host.querySelector('canvas');
+    expect(firstScreen?.width).toBe(Math.round(160 * Math.min(globalThis.devicePixelRatio || 1, 2)));
+    expect(firstScreen?.height).toBe(Math.round(120 * Math.min(globalThis.devicePixelRatio || 1, 2)));
+
+    const bounds = host.querySelector<HTMLElement>('[data-testid="surface-bounds"]');
+    expect(bounds).not.toBeNull();
+    bounds!.style.width = '180px';
+    bounds!.style.height = '90px';
+    await act(async () => {
+      await nextFrame();
+      await nextFrame();
+    });
+    expect(resizeA).toHaveBeenCalledWith(180, 90, globalThis.devicePixelRatio || 1);
+
+    bounds!.style.width = '160px';
+    bounds!.style.height = '120px';
+
+    await act(async () => {
+      root.render(<StrictCanvasHarness engine={projectB} />);
+      await nextFrame();
+    });
+
+    expect(detachA).toHaveBeenCalled();
+    expect(attachB).toHaveBeenCalled();
+    expect(resizeB).toHaveBeenCalledWith(160, 120, globalThis.devicePixelRatio || 1);
+
+    await unmount();
+    reacquiredProjectA.release();
+    projectBReference.release();
+    expect(detachB).toHaveBeenCalled();
+
+    await delay(gracePeriodMs + 20);
+    expect(registry.getEngine('project-a')).toBeUndefined();
+    expect(registry.getEngine('project-b')).toBeUndefined();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurface.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurface.tsx
new file mode 100644
index 00000000000..ecbedc752ec
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurface.tsx
@@ -0,0 +1,119 @@
+/* oxlint-disable react-perf/jsx-no-new-function-as-prop -- the container ref callback is intentionally re-created when `engine` changes, so a project switch detaches the old engine and attaches the new one. */
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { CSSProperties, PointerEvent as ReactPointerEvent } from 'react';
+
+import { Box } from '@chakra-ui/react';
+import { shouldFocusCanvasSurface } from '@workbench/widgets/canvas/surfaceFocus';
+import { TextEditPortal } from '@workbench/widgets/canvas/TextEditPortal';
+import { useRef } from 'react';
+
+export type CanvasSurfaceEngine = Pick<CanvasEngineHandle, 'document' | 'layers' | 'stores' | 'surface' | 'viewport'>;
+
+/**
+ * Give the canvas widget hotkey focus on a pointerdown on the surface, so tool
+ * hotkeys (`b`/`e`/`r`/…) work immediately after clicking the canvas.
+ *
+ * The two `<canvas>` targets aren't focusable, so a plain click never moves DOM
+ * focus — it stays on whatever was last focused (e.g. a layers-panel button in a
+ * *different* widget), and the hotkey runtime's `getHotkeyTargetWidget` keeps
+ * resolving to that widget, so canvas hotkeys don't fire. Focusing this
+ * `tabIndex={-1}` container (a descendant of the canvas widget's
+ * `data-hotkey-widget-instance-id` element) moves focus into the canvas subtree
+ * so hotkeys resolve to the canvas. Focus-from-pointer doesn't match
+ * `:focus-visible`, so there's no focus ring.
+ *
+ * When focus is ALREADY inside the surface — critically, the text tool's
+ * contenteditable — this must NOT refocus: doing so in the capture phase would
+ * blur-commit the open text session before the engine's own (bubble-phase)
+ * pointerdown could run its commit-and-swallow, regressing "click away to
+ * commit" into "commit + open a stray new session at the click point". The full
+ * decision lives in the node-tested {@link shouldFocusCanvasSurface}.
+ *
+ * Runs in the capture phase so it fires before the engine's overlay pointerdown
+ * listener (which may `stopPropagation`).
+ */
+const focusCanvasSurface = (event: ReactPointerEvent<HTMLDivElement>) => {
+  if (shouldFocusCanvasSurface(event.currentTarget, event.target, document.activeElement)) {
+    event.currentTarget.focus({ preventScroll: true });
+  }
+};
+
+/**
+ * The engine-rendered canvas surface: two stacked `<canvas>` targets (the
+ * composited document below, the interaction overlay on top) bound to the
+ * shared {@link CanvasEngine}.
+ *
+ * Binding is done through the container's **ref callback** (React 19: the
+ * returned function is the cleanup), never a `useEffect` — the callback wires
+ * `attach` + a `ResizeObserver` and tears both down on unmount or engine swap.
+ * Because the callback closes over `engine`, a project switch (new engine
+ * instance) re-runs it: detach the old, attach the new. Pointer/wheel/key input
+ * is owned entirely by the engine via the overlay, so this component never
+ * re-renders on interaction.
+ */
+export const CanvasSurface = ({ engine }: { engine: CanvasSurfaceEngine }) => {
+  const screenRef = useRef<HTMLCanvasElement>(null);
+  const overlayRef = useRef<HTMLCanvasElement>(null);
+
+  const bindContainer = (container: HTMLDivElement) => {
+    const screen = screenRef.current;
+    const overlay = overlayRef.current;
+    if (!screen || !overlay) {
+      return;
+    }
+
+    engine.surface.attach(screen, overlay);
+
+    const syncSize = () => {
+      const dpr = globalThis.devicePixelRatio || 1;
+      engine.surface.resize(container.clientWidth, container.clientHeight, dpr);
+    };
+
+    syncSize();
+    // Fit the document into view on first attach, once the viewport is sized.
+    if (engine.document.getDocument()) {
+      engine.viewport.fitToView();
+    }
+
+    const observer = new ResizeObserver(syncSize);
+    observer.observe(container);
+
+    return () => {
+      observer.disconnect();
+      engine.surface.detach();
+    };
+  };
+
+  return (
+    <Box
+      ref={bindContainer}
+      h="full"
+      outline="none"
+      overflow="hidden"
+      position="relative"
+      tabIndex={-1}
+      w="full"
+      onPointerDownCapture={focusCanvasSurface}
+    >
+      <canvas ref={screenRef} style={CANVAS_STYLE} />
+      <canvas ref={overlayRef} style={OVERLAY_STYLE} />
+      {/*
+       * The text-editing portal: a positioned contenteditable that overlays the
+       * canvas whenever a text-edit session is active. It lives inside this
+       * relatively-positioned container so its `documentToScreen`-derived
+       * absolute offsets share the same origin as the canvas targets.
+       */}
+      <TextEditPortal engine={engine} />
+    </Box>
+  );
+};
+
+const CANVAS_STYLE: CSSProperties = {
+  height: '100%',
+  inset: 0,
+  position: 'absolute',
+  touchAction: 'none',
+  width: '100%',
+};
+
+const OVERLAY_STYLE: CSSProperties = { ...CANVAS_STYLE, zIndex: 1 };
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurfaceContextLayout.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurfaceContextLayout.test.tsx
new file mode 100644
index 00000000000..b001ef778b4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurfaceContextLayout.test.tsx
@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { CanvasSurfaceContextLayout } from './CanvasSurfaceContextLayout';
+
+const engineSurface = <span data-engine-surface="">Surface</span>;
+const noop = () => undefined;
+
+const renderLayout = (surface: ReactNode): string =>
+  renderToStaticMarkup(
+    <ChakraProvider value={system}>
+      <div data-canvas-widget="">
+        <CanvasSurfaceContextLayout surface={surface} onContextMenu={noop}>
+          <div data-canvas-chrome="">Chrome</div>
+        </CanvasSurfaceContextLayout>
+      </div>
+    </ChakraProvider>
+  );
+
+describe('CanvasSurfaceContextLayout', () => {
+  it('keeps one empty context-menu owner mounted beside chrome without an engine surface', () => {
+    const markup = renderLayout(null);
+
+    expect(markup.match(/data-canvas-context-menu-owner/g)).toHaveLength(1);
+    expect(markup).toMatch(/data-canvas-context-menu-owner=""[^>]*><\/div><div data-canvas-chrome="">Chrome<\/div>/);
+  });
+
+  it('contains the engine surface inside the owner while chrome remains its sibling', () => {
+    const markup = renderLayout(engineSurface);
+
+    expect(markup.match(/data-canvas-context-menu-owner/g)).toHaveLength(1);
+    expect(markup).toMatch(
+      /data-canvas-context-menu-owner=""[^>]*><span data-engine-surface="">Surface<\/span><\/div><div data-canvas-chrome="">Chrome<\/div>/
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurfaceContextLayout.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurfaceContextLayout.tsx
new file mode 100644
index 00000000000..7269227ffa4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasSurfaceContextLayout.tsx
@@ -0,0 +1,26 @@
+import type { BoxProps } from '@chakra-ui/react';
+import type { MouseEventHandler, ReactNode } from 'react';
+
+import { Box } from '@chakra-ui/react';
+
+const CANVAS_SURFACE_LAYER_LAYOUT = {
+  inset: '0',
+  position: 'absolute',
+} satisfies BoxProps;
+
+export const CanvasSurfaceContextLayout = ({
+  children,
+  onContextMenu,
+  surface,
+}: {
+  children: ReactNode;
+  onContextMenu: MouseEventHandler<HTMLDivElement>;
+  surface: ReactNode;
+}) => (
+  <>
+    <Box {...CANVAS_SURFACE_LAYER_LAYOUT} data-canvas-context-menu-owner="" onContextMenu={onContextMenu}>
+      {surface}
+    </Box>
+    {children}
+  </>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasWidgetView.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasWidgetView.test.tsx
new file mode 100644
index 00000000000..026f3d4c77c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasWidgetView.test.tsx
@@ -0,0 +1,93 @@
+import type { CanvasEngine } from '@workbench/canvas-operations/createCanvasEngine';
+import type { CanvasStagingCandidateContract, Project, WidgetViewProps } from '@workbench/types';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createWorkbenchStore } from '@workbench/workbenchStore';
+import { createInstance } from 'i18next';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { I18nextProvider } from 'react-i18next';
+import { describe, expect, it, vi } from 'vitest';
+
+const harness = vi.hoisted(() => ({ engine: null as CanvasEngine | null, project: null as Project | null }));
+
+vi.mock('@dnd-kit/core', () => ({ useDndMonitor: () => undefined }));
+vi.mock('@workbench/WorkbenchContext', () => ({
+  useActiveProjectSelector: (selector: (project: Project) => unknown) => selector(harness.project!),
+  useWorkbenchDispatch: () => () => undefined,
+  useWorkbenchStore: () => ({
+    getSnapshot: () => ({ activeProject: harness.project }),
+    getState: () => ({ projects: harness.project ? [harness.project] : [] }),
+  }),
+}));
+vi.mock('@workbench/useCanvasProjectMutationDispatch', () => ({
+  useCanvasProjectMutationDispatch: () => () => undefined,
+}));
+vi.mock('@workbench/backend/progressImageStore', () => ({ useQueueItemProgressImage: () => null }));
+vi.mock('./engineStoreHooks', () => ({ useCanvasOperation: () => null }));
+vi.mock('./useCanvasEngine', () => ({ useCanvasEngine: () => harness.engine }));
+vi.mock('./useCanvasGallerySave', () => ({
+  useCanvasGallerySave: () => ({ isSaving: false, save: () => undefined }),
+}));
+vi.mock('./CanvasBottomControls', () => ({ CanvasBottomControls: () => null }));
+vi.mock('./CanvasGlobalContextMenu', () => ({ CanvasGlobalContextMenu: () => null }));
+vi.mock('./CanvasImageDropOverlay', () => ({ CanvasImageDropOverlay: () => null }));
+vi.mock('./CanvasSaveToGallerySubmenu', () => ({ CanvasSaveToGallerySubmenu: () => null }));
+vi.mock('./CanvasSurface', () => ({ CanvasSurface: () => null }));
+vi.mock('./ToolStrip', () => ({ ToolStrip: () => null }));
+vi.mock('@workbench/widgets/layers/LayerContextMenu', () => ({ CanvasLayerContextMenu: () => null }));
+
+import { CanvasWidgetView } from './CanvasWidgetView';
+
+const englishCatalogModules = import.meta.glob('../../../../public/locales/en.json', {
+  eager: true,
+  import: 'default',
+});
+const enCatalog = Object.values(englishCatalogModules)[0] as Record<string, unknown>;
+const testI18n = createInstance();
+await testI18n.init({
+  initImmediate: false,
+  lng: 'en',
+  resources: { en: { translation: enCatalog } },
+});
+
+const candidate: CanvasStagingCandidateContract = {
+  height: 40,
+  imageName: 'ui-result.png',
+  imageUrl: '/ui-result.png',
+  placement: { height: 40, opacity: 1, width: 40, x: 0, y: 0 },
+  queuedAt: '2026-07-16T00:00:00.000Z',
+  sourceQueueItemId: 'queue-ui',
+  thumbnailUrl: '/ui-result-thumb.png',
+  width: 40,
+};
+
+const renderView = (): string =>
+  renderToStaticMarkup(
+    <ChakraProvider value={system}>
+      <I18nextProvider i18n={testI18n}>
+        <CanvasWidgetView {...({ runtime: { commands: {}, hotkeys: {} } } as unknown as WidgetViewProps)} />
+      </I18nextProvider>
+    </ChakraProvider>
+  );
+
+const getAcceptButtonTag = (markup: string): string => {
+  const labelIndex = markup.indexOf('Accept to Layer');
+  const buttonIndex = markup.lastIndexOf('<button', labelIndex);
+  return markup.slice(buttonIndex, markup.indexOf('>', buttonIndex) + 1);
+};
+
+describe('CanvasWidgetView staged acceptance eligibility', () => {
+  it('drives the rendered Chakra Accept button disabled state from interaction capabilities', () => {
+    const store = createWorkbenchStore();
+    const projectId = store.getState().activeProjectId;
+    store.dispatch({ candidate, projectId, type: 'appendCanvasStagingCandidate' });
+    harness.project = store.getState().projects[0]!;
+
+    harness.engine = null;
+    expect(getAcceptButtonTag(renderView())).toContain('disabled=""');
+
+    harness.engine = { layers: { commitStagedImage: vi.fn() } } as unknown as CanvasEngine;
+    expect(getAcceptButtonTag(renderView())).not.toContain('disabled=""');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasWidgetView.tsx
new file mode 100644
index 00000000000..2e828a4487b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/CanvasWidgetView.tsx
@@ -0,0 +1,549 @@
+/* oxlint-disable react-perf/jsx-no-new-function-as-prop */
+import type { WidgetViewProps } from '@workbench/types';
+import type { MouseEvent as ReactMouseEvent } from 'react';
+
+import { Box } from '@chakra-ui/react';
+import { useDndMonitor, type DragEndEvent } from '@dnd-kit/core';
+import { useQueueItemProgressImage } from '@workbench/backend/progressImageStore';
+import { getCanvasImportNotice } from '@workbench/canvas-operations/canvasImportNotice';
+import {
+  createLayerId,
+  deleteLayerActions,
+  duplicateLayerActions,
+  type LayerReorderKind,
+  reorderIdsForHotkey,
+  reorderLayerActions,
+} from '@workbench/canvasLayerOps';
+import { getCanvasStagingSlots } from '@workbench/canvasStagingView';
+import { recordCanvasImportError } from '@workbench/image-actions/canvasImportError';
+import { useWorkbenchSettingsSelector } from '@workbench/settings/store';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { CanvasLayerContextMenu } from '@workbench/widgets/layers/LayerContextMenu';
+import { canMergeLayerDown } from '@workbench/widgets/layers/layerOps';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector, useWorkbenchDispatch, useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useCallback, useEffect, useEffectEvent, useLayoutEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { gridSizeForModelBase } from './bboxGrid';
+import { CanvasBottomControls } from './CanvasBottomControls';
+import { CanvasBottomOverlay } from './CanvasBottomOverlay';
+import {
+  resolveCanvasContextMenu,
+  resolveCanvasContextMenuBranch,
+  type CanvasContextMenuTarget,
+} from './canvasContextMenu';
+import { CanvasGlobalContextMenu } from './CanvasGlobalContextMenu';
+import { resolveCanvasImageDrop } from './canvasImageDnd';
+import { CanvasImageDropOverlay } from './CanvasImageDropOverlay';
+import { getCanvasInteractionCapabilities } from './canvasInteractionLock';
+import { CanvasSaveToGallerySubmenu } from './CanvasSaveToGallerySubmenu';
+import {
+  CANVAS_SETTINGS,
+  CANVAS_SHOW_PROGRESS_KEY,
+  canvasSettingsEqual,
+  resolveCanvasSettings,
+} from './canvasSettings';
+import { CanvasSurface } from './CanvasSurface';
+import { CanvasSurfaceContextLayout } from './CanvasSurfaceContextLayout';
+import { resolveCheckerColors } from './checkerColors';
+import { useCanvasOperation } from './engineStoreHooks';
+import { executeCanvasImageDropImport } from './executeCanvasImageDropImport';
+import { StagingBar } from './StagingBar';
+import { selectStagedPreviewSource, stagedPreviewKey } from './stagingPreview';
+import { INLINE_EDIT_SELECTOR } from './surfaceFocus';
+import { ToolStrip } from './ToolStrip';
+import { useCanvasEngine } from './useCanvasEngine';
+import { useCanvasGallerySave } from './useCanvasGallerySave';
+
+/** Command id → document-space nudge delta (shift variants are ×10). */
+const NUDGE_DELTAS: Record<string, { dx: number; dy: number }> = {
+  'canvas.nudgeDown': { dx: 0, dy: 1 },
+  'canvas.nudgeDownLarge': { dx: 0, dy: 10 },
+  'canvas.nudgeLeft': { dx: -1, dy: 0 },
+  'canvas.nudgeLeftLarge': { dx: -10, dy: 0 },
+  'canvas.nudgeRight': { dx: 1, dy: 0 },
+  'canvas.nudgeRightLarge': { dx: 10, dy: 0 },
+  'canvas.nudgeUp': { dx: 0, dy: -1 },
+  'canvas.nudgeUpLarge': { dx: 0, dy: -10 },
+};
+
+/** Command id → z-reorder direction (index 0 = top-most; "forward" moves toward 0). */
+const REORDER_KINDS: Record<string, LayerReorderKind> = {
+  'canvas.layerBackward': 'backward',
+  'canvas.layerForward': 'forward',
+  'canvas.layerToBack': 'back',
+  'canvas.layerToFront': 'front',
+};
+
+/**
+ * The canvas widget shell. The engine owns pixels and interaction and renders
+ * into {@link CanvasSurface}; this component only wires the reducer-backed
+ * chrome around it — command/hotkey registration, the settings-store feed, and
+ * the floating bottom chrome (tool options + staging). Zoom / fit / settings
+ * live in the widget header ({@link CanvasHeaderActions}).
+ */
+export const CanvasWidgetView = ({ runtime }: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const canvasDispatch = useCanvasProjectMutationDispatch();
+  const store = useWorkbenchStore();
+  const engine = useCanvasEngine();
+  const canvas = useActiveProjectSelector((project) => project.canvas);
+  const queueItems = useActiveProjectSelector((project) => project.queue.items);
+  const antialiasProgressImages = useActiveProjectSelector((project) => project.settings.antialiasProgressImages);
+  const { document, stagingArea } = canvas;
+  const operation = useCanvasOperation(engine);
+  const { isSaving, save: saveToGallery } = useCanvasGallerySave(engine);
+
+  // Right-click on the canvas surface: hit-test the layer under the cursor and
+  // open either the shared per-layer menu or the global empty-space menu at the
+  // pointer. Locked interaction skips the hit-test but keeps global save visible.
+  const [contextMenuTarget, setContextMenuTarget] = useState<CanvasContextMenuTarget | null>(null);
+  const closeContextMenu = useCallback(() => setContextMenuTarget(null), []);
+  const handleSurfaceContextMenu = (event: ReactMouseEvent<HTMLDivElement>) => {
+    // Keep the native menu inside inline editors (the text tool's contenteditable
+    // overlay), consistent with the surface-focus INLINE_EDIT_SELECTOR.
+    const rect = event.currentTarget.getBoundingClientRect();
+    const resolution = resolveCanvasContextMenu({
+      clientX: event.clientX,
+      clientY: event.clientY,
+      hitTest: engine ? (point) => engine.tools.contextMenuLayerIdAt(point) : undefined,
+      isInlineEditor: event.target instanceof Element && !!event.target.closest(INLINE_EDIT_SELECTOR),
+      isInteractionLocked,
+      surfaceLeft: rect.left,
+      surfaceTop: rect.top,
+    });
+    if (!resolution.preventDefault) {
+      return;
+    }
+    event.preventDefault();
+    if (resolution.target?.layerId) {
+      canvasDispatch({ id: resolution.target.layerId, type: 'setCanvasSelectedLayer' });
+    }
+    setContextMenuTarget(resolution.target);
+  };
+
+  // The bbox tool snaps to a model-dependent grid; the engine is model-agnostic,
+  // so read the active generate model's base and feed the grid size in.
+  const modelBase = useActiveProjectSelector((project) => {
+    const values = getProjectWidgetValues(project, 'generate') as { model?: { base?: unknown } } | undefined;
+    return typeof values?.model?.base === 'string' ? values.model.base : null;
+  });
+  useEffect(() => {
+    engine?.viewport.setBboxGrid(gridSizeForModelBase(modelBase));
+  }, [engine, modelBase]);
+
+  // Canvas view settings (checkerboard / grid / invert-scroll) persist in the
+  // canvas widget's per-project values; the engine only reads its stores, so
+  // push the resolved values down whenever they change — same one-directional
+  // feed as the bbox grid above. The header settings menu writes the values.
+  const settings = useActiveProjectSelector(
+    (project) => resolveCanvasSettings(getProjectWidgetValues(project, 'canvas')),
+    canvasSettingsEqual
+  );
+  useEffect(() => {
+    if (!engine) {
+      return;
+    }
+    for (const setting of CANVAS_SETTINGS) {
+      // Only engine-backed settings feed a store; React-consumed ones (e.g.
+      // showProgressOnCanvas, read below) have no store and are skipped here.
+      if (setting.store) {
+        engine.stores[setting.store].set(settings[setting.key]);
+      }
+    }
+  }, [engine, settings]);
+
+  // The checkerboard fills the whole (unbounded) canvas, so its two square colors
+  // come from theme tokens rather than hardcoded greys. Resolve them from the live
+  // Chakra theme and feed them into the engine's checker-colors store; re-resolve
+  // whenever the theme (and thus color mode) changes. `themeId` flips
+  // `<html data-theme>` in ThemeController's layout effect, which runs before this
+  // passive effect in the same commit, so getComputedStyle reads the new theme.
+  const themeId = useWorkbenchSettingsSelector((snapshot) => snapshot.preferences.themeId);
+  useEffect(() => {
+    engine?.stores.checkerColors.set(resolveCheckerColors());
+  }, [engine, themeId]);
+
+  const stagingSlots = getCanvasStagingSlots(canvas, queueItems);
+  const selectedSlot = stagingSlots[stagingArea.selectedImageIndex];
+  const selectedCandidate = selectedSlot?.kind === 'candidate' ? selectedSlot.candidate : undefined;
+  const selectedPlaceholder = selectedSlot?.kind === 'placeholder' ? selectedSlot : null;
+  const hasStagingSlots = stagingSlots.length > 0;
+  const hasMultipleStagingSlots = stagingSlots.length > 1;
+  const isCanvasGenerationInFlight = queueItems.some(
+    (item) =>
+      item.snapshot.destination === 'canvas' &&
+      (item.status === 'pending' || item.status === 'running') &&
+      // Only this canvas SESSION's in-flight items: an item submitted before a
+      // wholesale swap (new canvas / snapshot restore) belongs to a document
+      // that no longer exists, so its denoise frames must not leak onto the
+      // fresh canvas (F2). `documentRevision` bumps only on those swaps.
+      item.snapshot.canvas.documentRevision === canvas.documentRevision
+  );
+  const interactionCapabilities = getCanvasInteractionCapabilities({
+    hasCanvasEngine: engine !== null,
+    hasSelectedCandidate: selectedCandidate !== undefined,
+    hasStagingSlots,
+    isCanvasGenerationInFlight,
+    operationKind: operation?.status === 'active' ? operation.identity.kind : null,
+  });
+  const isInteractionLocked = interactionCapabilities.isSurfaceInteractionLocked;
+
+  const handleCanvasImageDrop = useCallback(
+    (event: DragEndEvent) => {
+      const resolution = resolveCanvasImageDrop(event.active.data.current, event.over?.data.current);
+      if (!resolution) {
+        return;
+      }
+
+      // Capture the destination project and mounted engine before any network
+      // work so a project switch cannot retarget this import mid-flight.
+      const project = store.getSnapshot().activeProject;
+      const mountedEngine = engine;
+
+      const execute = async (): Promise<void> => {
+        try {
+          const result = await executeCanvasImageDropImport({
+            destination: resolution.destination,
+            dispatch,
+            engine: mountedEngine,
+            getState: store.getState,
+            imageNames: resolution.imageNames,
+            project,
+          });
+          const notice = getCanvasImportNotice(result);
+          dispatch({ kind: notice.kind, title: t(notice.titleKey, notice.options ?? {}), type: 'recordNotice' });
+        } catch (error: unknown) {
+          recordCanvasImportError({
+            dispatch,
+            error,
+            localizedMessage: t('widgets.canvas.import.failed'),
+            projectId: project.id,
+          });
+        }
+      };
+
+      void execute();
+    },
+    [dispatch, engine, store, t]
+  );
+
+  useDndMonitor({ onDragEnd: handleCanvasImageDrop });
+
+  useLayoutEffect(() => {
+    engine?.tools.setInteractionLocked(isInteractionLocked);
+    return () => engine?.tools.setInteractionLocked(false);
+  }, [engine, isInteractionLocked]);
+
+  // "Show progress on canvas" gates ONLY the selected placeholder's live denoise
+  // frame; a selected finished candidate still previews (that's staging, not progress).
+  const selectedPlaceholderProgressImage = useQueueItemProgressImage(
+    selectedPlaceholder?.queueItemId ?? '',
+    selectedPlaceholder?.itemIndex ?? 0
+  );
+  const progressImage = settings[CANVAS_SHOW_PROGRESS_KEY] ? selectedPlaceholderProgressImage : null;
+
+  // What the engine should draw as the staged preview: the live denoise-progress
+  // frame while generating, else the selected candidate, else nothing. The pure
+  // helper is unit-tested; the effect below drives the engine imperatively.
+  const previewSource = selectStagedPreviewSource({
+    bboxHeight: document.bbox.height,
+    bboxWidth: document.bbox.width,
+    isGenerationInFlight: selectedPlaceholder !== null,
+    isVisible: stagingArea.isVisible,
+    progressImage,
+    selectedImageName: selectedCandidate?.imageName ?? null,
+    selectedPlacement: selectedCandidate?.placement ?? null,
+  });
+  const previewKey = stagedPreviewKey(previewSource);
+
+  // Syncing an external imperative system (the engine's staged preview) with
+  // derived reducer/progress state is a genuine effect. `useEffectEvent` reads
+  // the latest source without making it a dependency, so the decoding
+  // `setStagedPreview` re-runs only when `previewKey` actually changes (which
+  // includes every new progress frame) — never on unrelated re-renders.
+  const applyStagedPreview = useEffectEvent(() => {
+    engine?.previews.setStagedPreview(previewSource);
+  });
+  useEffect(() => {
+    applyStagedPreview();
+  }, [engine, previewKey]);
+  // Clear the preview when the widget (or engine) goes away, so an accepted /
+  // discarded candidate never lingers over the canvas.
+  useEffect(() => {
+    return () => engine?.previews.setStagedPreview(null);
+  }, [engine]);
+
+  const executeCanvasHotkey = useEffectEvent((commandId: string) => {
+    const { layers, selectedLayerId } = document;
+    const selectedIndex = selectedLayerId ? layers.findIndex((layer) => layer.id === selectedLayerId) : -1;
+    const selectedLayer = selectedIndex >= 0 ? layers[selectedIndex] : undefined;
+
+    if ((commandId === 'canvas.prevEntity' || commandId === 'canvas.nudgeLeft') && hasStagingSlots) {
+      canvasDispatch({ direction: -1, type: 'cycleStagedImage' });
+      return;
+    }
+
+    if ((commandId === 'canvas.nextEntity' || commandId === 'canvas.nudgeRight') && hasStagingSlots) {
+      canvasDispatch({ direction: 1, type: 'cycleStagedImage' });
+      return;
+    }
+
+    if (commandId === 'canvas.deleteSelected' && selectedCandidate) {
+      canvasDispatch({ type: 'discardSelectedStagedImage' });
+      return;
+    }
+
+    if (isInteractionLocked) {
+      if (commandId === 'canvas.tool.view') {
+        engine?.tools.setTool('view');
+      }
+      return;
+    }
+
+    // Arrow-key nudge: engine owns the bounds/lock logic (no-op with no/locked selection).
+    const nudge = NUDGE_DELTAS[commandId];
+    if (nudge) {
+      engine?.layers.nudgeSelectedLayer(nudge.dx, nudge.dy);
+      return;
+    }
+
+    // Layer z-reorder: same forward/inverse construction as the layers panel.
+    const reorderKind = REORDER_KINDS[commandId];
+    if (reorderKind) {
+      if (!engine || selectedIndex < 0) {
+        return;
+      }
+      const currentIds = layers.map((layer) => layer.id);
+      const nextIds = reorderIdsForHotkey(currentIds, selectedIndex, reorderKind);
+      if (!nextIds) {
+        return;
+      }
+      const { forward, inverse } = reorderLayerActions(currentIds, nextIds);
+      engine.layers.commitStructural(t('widgets.canvas.commands.reorderLayer'), forward, inverse);
+      return;
+    }
+
+    if (commandId === 'canvas.deleteSelected') {
+      // Staged images take priority; otherwise delete the selected layer (undoable).
+      if (engine && selectedLayer && selectedIndex >= 0) {
+        const { forward, inverse } = deleteLayerActions(selectedLayer, selectedIndex);
+        engine.layers.commitStructural(t('widgets.canvas.commands.deleteLayer'), forward, inverse);
+      }
+    } else if (commandId === 'canvas.resetSelected') {
+      if (engine && selectedLayer) {
+        engine.layers.clearMask(selectedLayer.id);
+      }
+    } else if (commandId === 'canvas.undo') {
+      // Canvas undo/redo is engine-scoped: it drives the engine-owned pixel/
+      // structural history, NOT project-level (reducer) undo. When the canvas
+      // history is empty this is a no-op — it deliberately does not fall back to
+      // `undoProjectChange` (project undo keeps its own commands/hotkeys, e.g.
+      // the workflow editor's `workflows.undo`).
+      engine?.history.undo();
+    } else if (commandId === 'canvas.redo') {
+      engine?.history.redo();
+    } else if (commandId === 'canvas.tool.view') {
+      engine?.tools.setTool('view');
+    } else if (commandId === 'canvas.tool.move') {
+      engine?.tools.setTool('move');
+    } else if (commandId === 'canvas.transformSelected') {
+      // Selecting the transform tool opens a session on the selected layer (if any
+      // eligible one); Apply/Cancel (enter/esc) are handled engine-side.
+      engine?.tools.setTool('transform');
+    } else if (commandId === 'canvas.tool.bbox') {
+      engine?.tools.setTool('bbox');
+    } else if (commandId === 'canvas.tool.brush') {
+      engine?.tools.setTool('brush');
+    } else if (commandId === 'canvas.tool.eraser') {
+      engine?.tools.setTool('eraser');
+    } else if (commandId === 'canvas.tool.lasso') {
+      engine?.tools.setTool('lasso');
+    } else if (commandId === 'canvas.tool.shape') {
+      engine?.tools.setTool('shape');
+    } else if (commandId === 'canvas.tool.text') {
+      engine?.tools.setTool('text');
+    } else if (commandId === 'canvas.tool.gradient') {
+      engine?.tools.setTool('gradient');
+    } else if (commandId === 'canvas.selectAll') {
+      engine?.selection.selectAll();
+    } else if (commandId === 'canvas.deselect') {
+      engine?.selection.deselect();
+    } else if (commandId === 'canvas.invertSelection') {
+      engine?.selection.invertSelection();
+    } else if (commandId === 'canvas.brushSizeDown') {
+      engine?.tools.stepBrushSize(-1);
+    } else if (commandId === 'canvas.brushSizeUp') {
+      engine?.tools.stepBrushSize(1);
+    } else if (commandId === 'canvas.duplicateLayer') {
+      if (engine && selectedLayer) {
+        const { forward, inverse } = duplicateLayerActions(selectedLayer.id, createLayerId());
+        engine.layers.commitStructural(t('widgets.canvas.commands.duplicateLayer'), forward, inverse);
+      }
+    } else if (commandId === 'canvas.mergeDown') {
+      // Gate on the SAME predicate the layers panel's context menu uses to
+      // enable/disable its "Merge Down" item (`canMergeLayerDown`), so the hotkey
+      // can never fire where the menu would refuse — e.g. a mask layer selected,
+      // or a mask directly below the selection. `engine.layers.mergeLayerDown` also
+      // guards this itself (defense in depth for callers other than this hotkey),
+      // but checking here keeps the two surfaces visibly in lockstep.
+      if (engine && selectedLayer && canMergeLayerDown(layers, selectedIndex, true)) {
+        engine.layers.mergeLayerDown(selectedLayer.id);
+      }
+    }
+  });
+
+  useEffect(() => {
+    const hotkeys = [
+      // Staging keeps `alt+[` / `alt+]`; bare left/right are registered as layer nudges,
+      // then intercepted above to cycle staging slots while any slot exists.
+      ['canvas.prevEntity', t('widgets.canvas.commands.previousEntity'), ['alt+[']],
+      ['canvas.nextEntity', t('widgets.canvas.commands.nextEntity'), ['alt+]']],
+      ['canvas.deleteSelected', t('widgets.canvas.commands.deleteSelected'), ['delete', 'backspace']],
+      ['canvas.resetSelected', t('widgets.canvas.commands.resetSelected'), ['shift+c']],
+      ['canvas.undo', t('widgets.canvas.commands.undo'), ['mod+z']],
+      ['canvas.redo', t('widgets.canvas.commands.redo'), ['mod+shift+z', 'mod+y']],
+      // Tool selection and brush/eraser size step. `allowInEditable: false` below
+      // keeps these single-letter/bracket keys from firing while the user is
+      // typing in a prompt/text field elsewhere in the workbench.
+      ['canvas.tool.view', t('widgets.canvas.commands.selectViewTool'), ['h']],
+      ['canvas.tool.move', t('widgets.canvas.commands.selectMoveTool'), ['v']],
+      ['canvas.transformSelected', t('widgets.canvas.commands.selectTransformTool'), ['mod+t']],
+      ['canvas.tool.bbox', t('widgets.canvas.commands.selectBboxTool'), []],
+      ['canvas.tool.brush', t('widgets.canvas.commands.selectBrushTool'), ['b']],
+      ['canvas.tool.eraser', t('widgets.canvas.commands.selectEraserTool'), ['e']],
+      ['canvas.tool.lasso', t('widgets.canvas.commands.selectLassoTool'), ['l']],
+      ['canvas.tool.shape', t('widgets.canvas.commands.selectShapeTool'), ['r']],
+      ['canvas.tool.text', t('widgets.canvas.commands.selectTextTool'), ['t']],
+      ['canvas.tool.gradient', t('widgets.canvas.commands.selectGradientTool'), ['g']],
+      // Selection: select all / deselect / invert (engine-owned transient selection).
+      ['canvas.selectAll', t('widgets.canvas.commands.selectAll'), ['mod+a']],
+      ['canvas.deselect', t('widgets.canvas.commands.deselect'), ['mod+d']],
+      ['canvas.invertSelection', t('widgets.canvas.commands.invertSelection'), ['mod+shift+i']],
+      ['canvas.brushSizeDown', t('widgets.canvas.commands.decreaseBrushSize'), ['[']],
+      ['canvas.brushSizeUp', t('widgets.canvas.commands.increaseBrushSize'), [']']],
+      // Move the selected layer: arrows nudge 1px, shift+arrows 10px.
+      ['canvas.nudgeLeft', t('widgets.canvas.commands.nudgeLeft'), ['arrowleft']],
+      ['canvas.nudgeRight', t('widgets.canvas.commands.nudgeRight'), ['arrowright']],
+      ['canvas.nudgeUp', t('widgets.canvas.commands.nudgeUp'), ['arrowup']],
+      ['canvas.nudgeDown', t('widgets.canvas.commands.nudgeDown'), ['arrowdown']],
+      ['canvas.nudgeLeftLarge', t('widgets.canvas.commands.nudgeLeftLarge'), ['shift+arrowleft']],
+      ['canvas.nudgeRightLarge', t('widgets.canvas.commands.nudgeRightLarge'), ['shift+arrowright']],
+      ['canvas.nudgeUpLarge', t('widgets.canvas.commands.nudgeUpLarge'), ['shift+arrowup']],
+      ['canvas.nudgeDownLarge', t('widgets.canvas.commands.nudgeDownLarge'), ['shift+arrowdown']],
+      // Layer management.
+      ['canvas.duplicateLayer', t('widgets.canvas.commands.duplicateLayer'), ['mod+j']],
+      ['canvas.mergeDown', t('widgets.canvas.commands.mergeDown'), ['mod+e']],
+      ['canvas.layerForward', t('widgets.canvas.commands.layerForward'), ['mod+]']],
+      ['canvas.layerBackward', t('widgets.canvas.commands.layerBackward'), ['mod+[']],
+      ['canvas.layerToFront', t('widgets.canvas.commands.layerToFront'), ['mod+shift+]']],
+      ['canvas.layerToBack', t('widgets.canvas.commands.layerToBack'), ['mod+shift+[']],
+    ] as const;
+    const disposers = hotkeys.flatMap(([id, title, defaultKeys]) => [
+      runtime.commands.register({ handler: () => executeCanvasHotkey(id), id, title }),
+      runtime.hotkeys.register({ allowInEditable: false, commandId: id, defaultKeys: [...defaultKeys], id, title }),
+    ]);
+
+    return () => {
+      disposers.forEach((dispose) => dispose());
+    };
+  }, [runtime.commands, runtime.hotkeys, t]);
+
+  const layerContextMenuTarget = useMemo(
+    () =>
+      contextMenuTarget?.layerId !== null && contextMenuTarget?.layerId !== undefined
+        ? { layerId: contextMenuTarget.layerId, x: contextMenuTarget.x, y: contextMenuTarget.y }
+        : null,
+    [contextMenuTarget]
+  );
+  const contextMenuBranch = resolveCanvasContextMenuBranch(contextMenuTarget, engine !== null);
+  const isSaveToGalleryDisabled = !engine || isSaving || isInteractionLocked;
+  const saveToGallerySubmenu = useMemo(
+    () => <CanvasSaveToGallerySubmenu disabled={isSaveToGalleryDisabled} onSave={saveToGallery} />,
+    [isSaveToGalleryDisabled, saveToGallery]
+  );
+  const canvasSurface = useMemo(() => (engine ? <CanvasSurface engine={engine} /> : null), [engine]);
+
+  return (
+    <Box aria-label={t('widgets.canvas.surface')} bg="bg.inset" h="full" overflow="hidden" position="relative" w="full">
+      <CanvasSurfaceContextLayout surface={canvasSurface} onContextMenu={handleSurfaceContextMenu}>
+        <CanvasImageDropOverlay
+          isDocumentEditingLocked={interactionCapabilities.isDocumentEditingLocked}
+          isInteractionLocked={isInteractionLocked}
+        />
+        {engine ? (
+          <>
+            <ToolStrip engine={engine} isInteractionLocked={isInteractionLocked} />
+            <CanvasLayerContextMenu
+              beforeDangerItems={saveToGallerySubmenu}
+              dispatch={canvasDispatch}
+              engine={engine}
+              layers={document.layers}
+              showGroupLabels
+              target={layerContextMenuTarget}
+              onClose={closeContextMenu}
+            />
+          </>
+        ) : null}
+        {contextMenuBranch === 'global' && contextMenuTarget ? (
+          <CanvasGlobalContextMenu target={contextMenuTarget} onClose={closeContextMenu}>
+            {saveToGallerySubmenu}
+          </CanvasGlobalContextMenu>
+        ) : null}
+
+        {/*
+         * Floating bottom-center chrome: the staging bar (when active) stacks
+         * directly above the always-present tool options bar — "just like the
+         * staging UI". The wrapper is click-through so the canvas stays
+         * interactive around the bars; each bar re-enables pointer events.
+         */}
+        <CanvasBottomOverlay.Root>
+          {hasStagingSlots || isCanvasGenerationInFlight ? (
+            <CanvasBottomOverlay.Staging>
+              <StagingBar
+                antialiasProgressImages={antialiasProgressImages}
+                areThumbnailsVisible={stagingArea.areThumbnailsVisible}
+                autoSwitchMode={stagingArea.autoSwitchMode}
+                canAccept={interactionCapabilities.canAcceptStagedImage}
+                hasMultipleSlots={hasMultipleStagingSlots}
+                isGenerating={isCanvasGenerationInFlight}
+                isVisible={stagingArea.isVisible}
+                selectedCandidate={selectedCandidate}
+                selectedImageIndex={stagingArea.selectedImageIndex}
+                selectedSlot={selectedSlot}
+                slots={stagingSlots}
+                onAccept={() => {
+                  if (selectedSlot?.kind === 'candidate') {
+                    engine?.layers.commitStagedImage({
+                      candidate: selectedSlot.candidate,
+                      selectedImageIndex: stagingArea.selectedImageIndex,
+                    });
+                  }
+                }}
+                onCancelQueueItem={(queueItemId) => dispatch({ queueItemId, type: 'cancelQueueItem' })}
+                onCycle={(direction) => canvasDispatch({ direction, type: 'cycleStagedImage' })}
+                onDiscardAll={() => canvasDispatch({ type: 'discardAllStagedImages' })}
+                onDiscardSelected={() => canvasDispatch({ type: 'discardSelectedStagedImage' })}
+                onSelectImage={(imageIndex) => canvasDispatch({ imageIndex, type: 'setStagedImageIndex' })}
+                onSetAutoSwitch={(mode) => canvasDispatch({ mode, type: 'setCanvasStagingAutoSwitch' })}
+                onToggleThumbnails={() => canvasDispatch({ type: 'toggleCanvasStagingThumbnailsVisibility' })}
+                onToggleVisibility={() => canvasDispatch({ type: 'toggleCanvasStagingVisibility' })}
+              />
+            </CanvasBottomOverlay.Staging>
+          ) : null}
+          <CanvasBottomOverlay.Controls>
+            <CanvasBottomControls
+              documentHeight={document.height}
+              documentWidth={document.width}
+              engine={engine}
+              isExternalInteractionLocked={isInteractionLocked}
+              operation={operation}
+            />
+          </CanvasBottomOverlay.Controls>
+        </CanvasBottomOverlay.Root>
+      </CanvasSurfaceContextLayout>
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/StagingBar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/StagingBar.tsx
new file mode 100644
index 00000000000..06b17394239
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/StagingBar.tsx
@@ -0,0 +1,437 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop */
+import type { CanvasStagingSlot } from '@workbench/canvasStagingView';
+import type { CanvasStagingAreaContractV2, CanvasStagingCandidateContract } from '@workbench/types';
+
+import {
+  Flex,
+  HStack,
+  Menu,
+  Portal,
+  ProgressCircle,
+  ScrollArea,
+  Skeleton,
+  Spinner,
+  Stack,
+  Text,
+} from '@chakra-ui/react';
+import { useQueueItemProgressImage } from '@workbench/backend/progressImageStore';
+import { useQueueItemProgress } from '@workbench/backend/progressStore';
+import { getCancelableCanvasStagingQueueItemId } from '@workbench/canvasStagingView';
+import { Button, IconButton, MenuContent, toaster, Tooltip } from '@workbench/components/ui';
+import { getImageThumbnailUrl, saveImageToGallery } from '@workbench/gallery/api';
+import { StreamingImageFrame } from '@workbench/images/StreamingImageFrame';
+import { progressImageToStreamingSource } from '@workbench/images/streamingImageSource';
+import { CanvasOptionsBar } from '@workbench/widgets/canvas/tool-options/CanvasOptionsBar';
+import {
+  CheckIcon,
+  ChevronDownIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  ChevronUpIcon,
+  EyeIcon,
+  EyeOffIcon,
+  SaveIcon,
+  SparklesIcon,
+  Trash2Icon,
+  XIcon,
+} from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { CanvasFloatingBarDivider } from './CanvasFloatingBar';
+
+type AutoSwitchMode = CanvasStagingAreaContractV2['autoSwitchMode'];
+
+const THUMBNAIL_STRIP_HEIGHT = '5rem';
+const AUTO_SWITCH_MODES: AutoSwitchMode[] = ['off', 'progress', 'latest'];
+const MENU_POSITIONING = { placement: 'top-end' } as const;
+
+interface StagingBarProps {
+  antialiasProgressImages: boolean;
+  areThumbnailsVisible: boolean;
+  autoSwitchMode: AutoSwitchMode;
+  canAccept: boolean;
+  hasMultipleSlots: boolean;
+  isGenerating: boolean;
+  isVisible: boolean;
+  selectedCandidate: CanvasStagingCandidateContract | undefined;
+  selectedImageIndex: number;
+  selectedSlot: CanvasStagingSlot | undefined;
+  slots: CanvasStagingSlot[];
+  onAccept: () => void;
+  onCancelQueueItem: (queueItemId: string) => void;
+  onCycle: (direction: -1 | 1) => void;
+  onDiscardAll: () => void;
+  onDiscardSelected: () => void;
+  onSelectImage: (imageIndex: number) => void;
+  onSetAutoSwitch: (mode: AutoSwitchMode) => void;
+  onToggleThumbnails: () => void;
+  onToggleVisibility: () => void;
+}
+
+/**
+ * The floating staging bar over the canvas: appears while a canvas generation
+ * is in flight or staged candidates await a decision. It drives the reducer's
+ * staging actions (cycle / accept / discard / auto-switch); the candidate and
+ * live progress pixels themselves are drawn on the engine canvas via
+ * `engine.previews.setStagedPreview` (wired in {@link CanvasWidgetView}). Rendered inside
+ * the canvas's bottom-center floating group, stacked directly above the tool
+ * options bar; positioning is the parent's job.
+ */
+export const StagingBar = ({
+  antialiasProgressImages,
+  areThumbnailsVisible,
+  autoSwitchMode,
+  canAccept,
+  hasMultipleSlots,
+  isGenerating,
+  isVisible,
+  selectedCandidate,
+  selectedImageIndex,
+  selectedSlot,
+  slots,
+  onAccept,
+  onCancelQueueItem,
+  onCycle,
+  onDiscardAll,
+  onDiscardSelected,
+  onSelectImage,
+  onSetAutoSwitch,
+  onToggleThumbnails,
+  onToggleVisibility,
+}: StagingBarProps) => {
+  const { t } = useTranslation();
+  const [isSaving, setIsSaving] = useState(false);
+  const hasSlots = slots.length > 0;
+  const cancelableQueueItemId = getCancelableCanvasStagingQueueItemId(selectedSlot);
+
+  const handleSaveToGallery = async () => {
+    if (!selectedCandidate || isSaving) {
+      return;
+    }
+    setIsSaving(true);
+    try {
+      await saveImageToGallery(selectedCandidate.imageName);
+      toaster.create({
+        description: t('widgets.canvas.staging.savedDescription', { name: selectedCandidate.imageName }),
+        title: t('widgets.canvas.staging.saved'),
+        type: 'success',
+      });
+    } catch {
+      toaster.create({ title: t('widgets.canvas.staging.saveError'), type: 'error' });
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  return (
+    <Stack align="center" gap="2" w="full">
+      {hasSlots ? (
+        <ScrollArea.Root
+          h={areThumbnailsVisible ? THUMBNAIL_STRIP_HEIGHT : '0'}
+          opacity={areThumbnailsVisible ? 1 : 0}
+          pointerEvents={areThumbnailsVisible ? 'auto' : 'none'}
+          size="xs"
+          transition="height var(--wb-motion-duration-slow) ease, opacity var(--wb-motion-duration-slow) ease"
+          variant="hover"
+          w="full"
+        >
+          <ScrollArea.Viewport h="full" w="full">
+            <ScrollArea.Content asChild>
+              <HStack h="full" justify="center">
+                {slots.map((slot, index) => (
+                  <StagingThumbnail
+                    key={slot.id}
+                    antialiasProgressImages={antialiasProgressImages}
+                    index={index}
+                    isSelected={index === selectedImageIndex}
+                    slot={slot}
+                    onSelect={() => onSelectImage(index)}
+                  />
+                ))}
+              </HStack>
+            </ScrollArea.Content>
+          </ScrollArea.Viewport>
+          <ScrollArea.Scrollbar orientation="horizontal">
+            <ScrollArea.Thumb />
+          </ScrollArea.Scrollbar>
+        </ScrollArea.Root>
+      ) : null}
+
+      <CanvasOptionsBar>
+        {isGenerating ? (
+          <HStack color="fg.muted" gap="1.5" px="1">
+            <Spinner size="xs" />
+            <Text fontSize="xs" fontWeight="600">
+              {t('widgets.canvas.staging.generating')}
+            </Text>
+          </HStack>
+        ) : null}
+
+        {hasSlots && selectedSlot ? (
+          <>
+            <IconButton
+              aria-label={
+                areThumbnailsVisible
+                  ? t('widgets.canvas.hideStagingThumbnails')
+                  : t('widgets.canvas.showStagingThumbnails')
+              }
+              size="xs"
+              variant="ghost"
+              onClick={onToggleThumbnails}
+            >
+              {areThumbnailsVisible ? <ChevronDownIcon /> : <ChevronUpIcon />}
+            </IconButton>
+
+            <HStack gap="0.5">
+              <IconButton
+                aria-label={t('widgets.canvas.previousStagedCandidate')}
+                disabled={!hasMultipleSlots}
+                size="xs"
+                variant="ghost"
+                onClick={() => onCycle(-1)}
+              >
+                <ChevronLeftIcon />
+              </IconButton>
+              <Text fontSize="xs" fontVariantNumeric="tabular-nums" minW="3.5rem" px="1" textAlign="center">
+                {t('widgets.canvas.candidateCount', {
+                  current: selectedImageIndex + 1,
+                  total: slots.length,
+                })}
+              </Text>
+              <IconButton
+                aria-label={t('widgets.canvas.nextStagedCandidate')}
+                disabled={!hasMultipleSlots}
+                size="xs"
+                variant="ghost"
+                onClick={() => onCycle(1)}
+              >
+                <ChevronRightIcon />
+              </IconButton>
+            </HStack>
+
+            <CanvasFloatingBarDivider />
+
+            <AutoSwitchMenu mode={autoSwitchMode} onSelect={onSetAutoSwitch} />
+
+            {cancelableQueueItemId ? (
+              <Button size="xs" variant="ghost" onClick={() => onCancelQueueItem(cancelableQueueItemId)}>
+                <XIcon />
+                {t('common.cancel')}
+              </Button>
+            ) : null}
+
+            {selectedCandidate ? (
+              <>
+                <Tooltip
+                  content={
+                    isVisible
+                      ? t('widgets.canvas.hideStagedResultPreview')
+                      : t('widgets.canvas.showStagedResultPreview')
+                  }
+                >
+                  <IconButton
+                    aria-label={
+                      isVisible
+                        ? t('widgets.canvas.hideStagedResultPreview')
+                        : t('widgets.canvas.showStagedResultPreview')
+                    }
+                    size="xs"
+                    variant="ghost"
+                    onClick={onToggleVisibility}
+                  >
+                    {isVisible ? <EyeIcon /> : <EyeOffIcon />}
+                  </IconButton>
+                </Tooltip>
+
+                <Tooltip content={t('widgets.canvas.staging.saveToGallery')}>
+                  <IconButton
+                    aria-label={t('widgets.canvas.staging.saveToGallery')}
+                    disabled={isSaving}
+                    size="xs"
+                    variant="ghost"
+                    onClick={handleSaveToGallery}
+                  >
+                    {isSaving ? <Spinner size="xs" /> : <SaveIcon />}
+                  </IconButton>
+                </Tooltip>
+
+                <Tooltip content={t('common.discard')}>
+                  <IconButton aria-label={t('common.discard')} size="xs" variant="ghost" onClick={onDiscardSelected}>
+                    <XIcon />
+                  </IconButton>
+                </Tooltip>
+
+                <CanvasFloatingBarDivider />
+
+                <Button size="xs" variant="ghost" onClick={onDiscardAll}>
+                  <Trash2Icon />
+                  {t('common.discardAll')}
+                </Button>
+
+                <Button disabled={!canAccept} size="xs" onClick={onAccept}>
+                  <CheckIcon />
+                  {t('widgets.canvas.acceptToLayer')}
+                </Button>
+              </>
+            ) : null}
+          </>
+        ) : null}
+      </CanvasOptionsBar>
+    </Stack>
+  );
+};
+
+const AutoSwitchMenu = ({ mode, onSelect }: { mode: AutoSwitchMode; onSelect: (mode: AutoSwitchMode) => void }) => {
+  const { t } = useTranslation();
+  const label = (value: AutoSwitchMode): string =>
+    t(
+      value === 'off'
+        ? 'widgets.canvas.staging.autoSwitchOff'
+        : value === 'progress'
+          ? 'widgets.canvas.staging.autoSwitchProgress'
+          : 'widgets.canvas.staging.autoSwitchLatest'
+    );
+
+  return (
+    <Menu.Root positioning={MENU_POSITIONING}>
+      <Tooltip content={t('widgets.canvas.staging.autoSwitch')}>
+        <span style={{ display: 'inline-flex' }}>
+          <Menu.Trigger asChild>
+            <Button minW="unset" px="2" size="xs" variant="ghost">
+              <SparklesIcon size={13} />
+              <Text fontSize="xs">{label(mode)}</Text>
+            </Button>
+          </Menu.Trigger>
+        </span>
+      </Tooltip>
+      <Portal>
+        <Menu.Positioner>
+          <MenuContent minW="8rem" py="1">
+            <Menu.ItemGroup>
+              <Menu.ItemGroupLabel>{t('widgets.canvas.staging.autoSwitch')}</Menu.ItemGroupLabel>
+              {AUTO_SWITCH_MODES.map((value) => (
+                <Menu.Item key={value} value={value} onClick={() => onSelect(value)}>
+                  <CheckIcon size={12} opacity={mode === value ? 1 : 0} />
+                  <Menu.ItemText fontSize="xs">{label(value)}</Menu.ItemText>
+                </Menu.Item>
+              ))}
+            </Menu.ItemGroup>
+          </MenuContent>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
+
+const StagingThumbnail = ({
+  antialiasProgressImages,
+  index,
+  isSelected,
+  slot,
+  onSelect,
+}: {
+  antialiasProgressImages: boolean;
+  index: number;
+  isSelected: boolean;
+  slot: CanvasStagingSlot;
+  onSelect: () => void;
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <Stack
+      aria-label={t('widgets.canvas.selectStagedCandidate', { number: index + 1 })}
+      as="button"
+      bg="bg.emphasized"
+      borderWidth="2px"
+      borderColor={isSelected ? 'accent.solid' : 'border.subtle'}
+      flex="0 0 auto"
+      h="full"
+      overflow="hidden"
+      position="relative"
+      rounded="md"
+      shadow={isSelected ? '0 0 0 1px {colors.accent.solid}' : 'md'}
+      style={{ aspectRatio: '1 / 1' }}
+      onClick={onSelect}
+    >
+      {slot.kind === 'candidate' ? (
+        <img
+          alt={slot.candidate.imageName}
+          src={slot.candidate.thumbnailUrl || getImageThumbnailUrl(slot.candidate.imageName)}
+          style={{ display: 'block', height: '100%', objectFit: 'cover', width: '100%' }}
+        />
+      ) : (
+        <StagingPlaceholderThumbnail antialiasProgressImages={antialiasProgressImages} slot={slot} />
+      )}
+      <Text
+        bg="blackAlpha.700"
+        bottom="1"
+        color="white"
+        fontSize="2xs"
+        fontWeight="700"
+        left="1"
+        px="1.5"
+        position="absolute"
+        rounded="sm"
+      >
+        {index + 1}
+      </Text>
+    </Stack>
+  );
+};
+
+const StagingPlaceholderThumbnail = ({
+  antialiasProgressImages,
+  slot,
+}: {
+  antialiasProgressImages: boolean;
+  slot: Extract<CanvasStagingSlot, { kind: 'placeholder' }>;
+}) => {
+  const progressImage = useQueueItemProgressImage(slot.queueItemId, slot.itemIndex);
+  const progress = useQueueItemProgress(slot.queueItemId);
+  const isActive = progress?.activeItemIndex === slot.itemIndex;
+  const percentage = typeof progress?.percentage === 'number' ? Math.round(progress.percentage * 100) : null;
+
+  return (
+    <>
+      <StreamingImageFrame
+        fit="cover"
+        h="full"
+        liveImage={progressImageToStreamingSource(progressImage)}
+        shouldAntialiasLiveImage={antialiasProgressImages}
+        w="full"
+      >
+        <Skeleton h="full" w="full" />
+      </StreamingImageFrame>
+      {isActive ? <StagingPlaceholderProgress percentage={percentage} /> : null}
+    </>
+  );
+};
+
+const StagingPlaceholderProgress = ({ percentage }: { percentage: number | null }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Flex
+      align="center"
+      aria-label={
+        percentage === null
+          ? t('widgets.gallery.generationProgress')
+          : t('widgets.gallery.generationProgressPercent', { percentage })
+      }
+      inset="0"
+      justify="center"
+      pointerEvents="none"
+      position="absolute"
+      zIndex="1"
+    >
+      <ProgressCircle.Root bg="bg/85" borderWidth={1} p={0.5} rounded="full" size="xs" value={percentage}>
+        <ProgressCircle.Circle>
+          <ProgressCircle.Track />
+          <ProgressCircle.Range />
+        </ProgressCircle.Circle>
+      </ProgressCircle.Root>
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/TextEditPortal.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/TextEditPortal.tsx
new file mode 100644
index 00000000000..eb22969480c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/TextEditPortal.tsx
@@ -0,0 +1,178 @@
+import type { TextEditSession } from '@workbench/canvas-engine/engineStores';
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop -- the editable's style object is derived from the live session/viewport and intentionally recomputed each render. */
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { CSSProperties, KeyboardEvent as ReactKeyboardEvent } from 'react';
+
+import { useTextEditSession } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useCallback, useSyncExternalStore } from 'react';
+
+type TextEditEngine = Pick<CanvasEngineHandle, 'layers' | 'stores' | 'viewport'>;
+
+/**
+ * The text-editing portal: a positioned `contenteditable` div, rendered over the
+ * canvas whenever a text-edit session is active, that IS the text while editing
+ * (the compositor skips the session's layer so the two never double-draw).
+ *
+ * ## WYSIWYG
+ *
+ * The editable's intrinsic styles are set in DOCUMENT units (font size in px,
+ * unitless line-height, family/weight/align/color from the live session source)
+ * — exactly what the rasterizer will bake. A single CSS transform then maps the
+ * layer's document anchor to the screen and magnifies by the view zoom, so the
+ * on-screen editable matches the rasterized output at any pan/zoom. `white-space:
+ * pre` mirrors the rasterizer's manual-line-break, no-auto-wrap layout.
+ *
+ * ## Keystrokes stay local
+ *
+ * Typing only mutates the editable's DOM — never the engine/store (no per-key
+ * traffic). Every keydown is `stopPropagation`'d so canvas hotkeys can't fire
+ * from the field (belt-and-braces with the pipeline's editable guard and the
+ * widget hotkeys' `allowInEditable: false`). Commit is on blur / `mod+enter`;
+ * `esc` cancels — the editable owns Escape (stopPropagation) so the engine's
+ * Escape priority never also runs.
+ */
+
+/** Re-renders on any viewport (pan/zoom) change via a value-stable snapshot string. */
+const useViewportTick = (engine: TextEditEngine): string => {
+  const viewport = engine.viewport.getViewport();
+  const subscribe = useCallback((onChange: () => void) => viewport.subscribe(onChange), [viewport]);
+  const getSnapshot = useCallback(() => {
+    const { pan, zoom } = viewport.getState();
+    return `${zoom}|${pan.x}|${pan.y}`;
+  }, [viewport]);
+  useSyncExternalStore(subscribe, getSnapshot);
+  return '';
+};
+
+/** Reads the editable's text with manual line breaks preserved (`\n` per visual line). */
+const readEditableText = (el: HTMLElement): string => el.innerText;
+
+/** Moves the caret to the end of `el`'s content. */
+const placeCaretAtEnd = (el: HTMLElement): void => {
+  const selection = window.getSelection();
+  if (!selection) {
+    return;
+  }
+  const range = document.createRange();
+  range.selectNodeContents(el);
+  range.collapse(false);
+  selection.removeAllRanges();
+  selection.addRange(range);
+};
+
+interface TextEditableProps {
+  engine: TextEditEngine;
+  session: TextEditSession;
+}
+
+/**
+ * The single editable element for one session. Keyed by `session.id` in the
+ * parent so a fresh session remounts it — the ref callback then seeds content +
+ * focus exactly once, while position/style recompute on each render.
+ */
+const TextEditable = ({ engine, session }: TextEditableProps) => {
+  // Re-render on pan/zoom so the transform below tracks the viewport.
+  useViewportTick(engine);
+  const viewport = engine.viewport.getViewport();
+  const { source, transform } = session;
+
+  // Seeds content + focus once when the element mounts, and registers a live-
+  // content reader with the engine so it can commit on a canvas pointerdown
+  // (click-elsewhere-to-commit) without per-keystroke traffic. Cleared on unmount.
+  // A stable callback, so React never re-runs it on a position/style re-render.
+  const setRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (!el) {
+        // Unmount: stop the engine from reading a detached element.
+        engine.layers.setTextEditContentReader(null);
+        return;
+      }
+      engine.layers.setTextEditContentReader(() => readEditableText(el));
+      if (el.dataset.seeded === 'true') {
+        return;
+      }
+      el.dataset.seeded = 'true';
+      el.textContent = source.content;
+      el.focus();
+      placeCaretAtEnd(el);
+    },
+    // `session` is stable for this element's life (parent keys by session.id);
+    // seed from the source captured at mount.
+    [engine, source.content]
+  );
+
+  const onBlur = useCallback(
+    (event: { currentTarget: HTMLElement }) => {
+      engine.layers.commitTextEdit(readEditableText(event.currentTarget));
+    },
+    [engine]
+  );
+
+  const onKeyDown = useCallback(
+    (event: ReactKeyboardEvent<HTMLDivElement>) => {
+      // Keep every keystroke inside the field — no canvas hotkey/window key fires.
+      event.stopPropagation();
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        engine.layers.cancelTextEdit();
+        return;
+      }
+      if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        engine.layers.commitTextEdit(readEditableText(event.currentTarget));
+      }
+    },
+    [engine]
+  );
+
+  const origin = viewport.documentToScreen({ x: transform.x, y: transform.y });
+  const scale = viewport.getZoom() * transform.scaleX;
+
+  const style: CSSProperties = {
+    background: 'transparent',
+    border: 'none',
+    color: source.color,
+    cursor: 'text',
+    fontFamily: source.fontFamily,
+    fontSize: `${source.fontSize}px`,
+    fontWeight: source.fontWeight,
+    left: 0,
+    lineHeight: source.lineHeight,
+    margin: 0,
+    minWidth: '1ch',
+    outline: 'none',
+    padding: 0,
+    pointerEvents: 'auto',
+    position: 'absolute',
+    textAlign: source.align,
+    top: 0,
+    transform: `translate(${origin.x}px, ${origin.y}px) rotate(${transform.rotation}rad) scale(${scale})`,
+    transformOrigin: '0 0',
+    whiteSpace: 'pre',
+    zIndex: 4,
+  };
+
+  return (
+    <div
+      aria-label="Text editor"
+      contentEditable
+      dir="auto"
+      ref={setRef}
+      role="textbox"
+      style={style}
+      suppressContentEditableWarning
+      tabIndex={0}
+      onBlur={onBlur}
+      onKeyDown={onKeyDown}
+    />
+  );
+};
+
+/** Renders the editable for the active session, or nothing. */
+export const TextEditPortal = ({ engine }: { engine: TextEditEngine }) => {
+  const session = useTextEditSession(engine);
+  if (!session) {
+    return null;
+  }
+  return <TextEditable key={session.id} engine={engine} session={session} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/ToolStrip.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/ToolStrip.tsx
new file mode 100644
index 00000000000..39984204c98
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/ToolStrip.tsx
@@ -0,0 +1,137 @@
+import type { CanvasCoreStoreCapability, CanvasToolCapability } from '@workbench/canvas-engine/api';
+import type { ToolId } from '@workbench/canvas-engine/types';
+
+import { Box } from '@chakra-ui/react';
+import { Toolbar, ToolbarButton } from '@workbench/components/ui';
+import {
+  BrushIcon,
+  EraserIcon,
+  FrameIcon,
+  HandIcon,
+  LassoIcon,
+  MoveIcon,
+  PaintBucketIcon,
+  Rotate3dIcon,
+  SquareIcon,
+  TypeIcon,
+} from 'lucide-react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { isCanvasToolEnabled } from './canvasInteractionLock';
+import { useCanvasActiveTool } from './engineStoreHooks';
+
+type ToolStripEngine = CanvasCoreStoreCapability & { readonly tools: CanvasToolCapability };
+
+interface ToolStripButtonProps {
+  engine: ToolStripEngine;
+  icon: typeof HandIcon;
+  isInteractionLocked: boolean;
+  label: string;
+  toolId: ToolId;
+}
+
+/** One sticky tool button: active state comes from core stores; click drives the tool capability. */
+const ToolStripButton = ({ engine, icon, isInteractionLocked, label, toolId }: ToolStripButtonProps) => {
+  const activeTool = useCanvasActiveTool(engine);
+  const isDisabled = !isCanvasToolEnabled(toolId, isInteractionLocked);
+  const onClick = useCallback(() => engine.tools.setTool(toolId), [engine, toolId]);
+
+  return (
+    <ToolbarButton disabled={isDisabled} icon={icon} isActive={activeTool === toolId} label={label} onClick={onClick} />
+  );
+};
+
+/**
+ * The canvas's left-docked, vertical tool strip. Color-picker is intentionally
+ * absent — it's alt-hold-only for now (see `canvas-engine/input/pointerPipeline.ts`),
+ * not a sticky tool a user selects directly.
+ */
+const ToolStripRoot = ({
+  engine,
+  isInteractionLocked = false,
+}: {
+  engine: ToolStripEngine;
+  isInteractionLocked?: boolean;
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <Box left="2" position="absolute" top="50%" transform="translateY(-50%)" zIndex="2">
+      <Toolbar aria-label={t('widgets.canvas.tools.label')}>
+        <ToolStripButton
+          engine={engine}
+          icon={HandIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.view')}
+          toolId="view"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={MoveIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.move')}
+          toolId="move"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={Rotate3dIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.transform')}
+          toolId="transform"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={FrameIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.bbox')}
+          toolId="bbox"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={BrushIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.brush')}
+          toolId="brush"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={EraserIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.eraser')}
+          toolId="eraser"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={SquareIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.shape')}
+          toolId="shape"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={PaintBucketIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.gradient')}
+          toolId="gradient"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={TypeIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.text')}
+          toolId="text"
+        />
+        <ToolStripButton
+          engine={engine}
+          icon={LassoIcon}
+          isInteractionLocked={isInteractionLocked}
+          label={t('widgets.canvas.tools.lasso')}
+          toolId="lasso"
+        />
+      </Toolbar>
+    </Box>
+  );
+};
+
+export const ToolStrip = Object.assign(ToolStripRoot, { Button: ToolStripButton });
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/bboxGrid.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/bboxGrid.test.ts
new file mode 100644
index 00000000000..85212707e72
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/bboxGrid.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_MODEL_GRID, gridSizeForModelBase } from './bboxGrid';
+
+describe('gridSizeForModelBase', () => {
+  it('maps flux-family and sd-3 bases to a 16px grid', () => {
+    for (const base of ['flux', 'flux2', 'sd-3', 'qwen-image', 'z-image']) {
+      expect(gridSizeForModelBase(base)).toBe(16);
+    }
+  });
+
+  it('maps cogview4 to a 32px grid', () => {
+    expect(gridSizeForModelBase('cogview4')).toBe(32);
+  });
+
+  it('maps sd/sdxl and unknown bases to the default 8px grid', () => {
+    for (const base of ['sd-1', 'sd-2', 'sdxl', 'anima', 'mystery-model']) {
+      expect(gridSizeForModelBase(base)).toBe(8);
+    }
+  });
+
+  it('falls back to the default grid for null/undefined', () => {
+    expect(gridSizeForModelBase(null)).toBe(DEFAULT_MODEL_GRID);
+    expect(gridSizeForModelBase(undefined)).toBe(DEFAULT_MODEL_GRID);
+    expect(DEFAULT_MODEL_GRID).toBe(8);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/bboxGrid.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/bboxGrid.ts
new file mode 100644
index 00000000000..fd01aabc8ec
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/bboxGrid.ts
@@ -0,0 +1,30 @@
+/**
+ * Maps a model base to the bbox snapping grid size (document px), mirroring the
+ * legacy `getGridSize` rule: generation dimensions must land on a base-specific
+ * multiple. React reads the active generate model's base and feeds the result
+ * into `engine.viewport.setBboxGrid`; the engine itself stays model-agnostic.
+ */
+
+/** Default grid when no model is selected (or an unknown base). */
+export const DEFAULT_MODEL_GRID = 8;
+
+/**
+ * The bbox grid size for a model base:
+ * - `cogview4` → 32
+ * - `flux` / `flux2` / `sd-3` / `qwen-image` / `z-image` → 16
+ * - everything else (sd-1/sd-2/sdxl/anima/unknown) → 8
+ */
+export const gridSizeForModelBase = (base: string | null | undefined): number => {
+  switch (base) {
+    case 'cogview4':
+      return 32;
+    case 'flux':
+    case 'flux2':
+    case 'sd-3':
+    case 'qwen-image':
+    case 'z-image':
+      return 16;
+    default:
+      return DEFAULT_MODEL_GRID;
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasContextMenu.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasContextMenu.test.ts
new file mode 100644
index 00000000000..a27b159dec0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasContextMenu.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { resolveCanvasContextMenu, resolveCanvasContextMenuBranch } from './canvasContextMenu';
+
+const baseOptions = {
+  clientX: 240,
+  clientY: 160,
+  isInlineEditor: false,
+  isInteractionLocked: false,
+  surfaceLeft: 40,
+  surfaceTop: 20,
+};
+
+describe('resolveCanvasContextMenu', () => {
+  it('leaves inline editors to the native context menu', () => {
+    const hitTest = vi.fn(() => 'layer-1');
+
+    expect(resolveCanvasContextMenu({ ...baseOptions, hitTest, isInlineEditor: true })).toEqual({
+      preventDefault: false,
+      target: null,
+    });
+    expect(hitTest).not.toHaveBeenCalled();
+  });
+
+  it('opens the global menu without hit-testing while interaction is locked', () => {
+    const hitTest = vi.fn(() => 'layer-1');
+
+    expect(resolveCanvasContextMenu({ ...baseOptions, hitTest, isInteractionLocked: true })).toEqual({
+      preventDefault: true,
+      target: { layerId: null, x: 240, y: 160 },
+    });
+    expect(hitTest).not.toHaveBeenCalled();
+  });
+
+  it('opens the layer menu at the pointer for a hit layer', () => {
+    const hitTest = vi.fn(() => 'layer-1');
+
+    expect(resolveCanvasContextMenu({ ...baseOptions, hitTest })).toEqual({
+      preventDefault: true,
+      target: { layerId: 'layer-1', x: 240, y: 160 },
+    });
+    expect(hitTest).toHaveBeenCalledWith({ x: 200, y: 140 });
+  });
+
+  it('opens the global menu when the pointer is over empty canvas', () => {
+    expect(resolveCanvasContextMenu({ ...baseOptions, hitTest: () => null })).toEqual({
+      preventDefault: true,
+      target: { layerId: null, x: 240, y: 160 },
+    });
+  });
+
+  it('opens the global menu without a hit-test when the engine is unavailable', () => {
+    const resolution = resolveCanvasContextMenu(baseOptions);
+
+    expect(resolution).toEqual({
+      preventDefault: true,
+      target: { layerId: null, x: 240, y: 160 },
+    });
+    expect(resolveCanvasContextMenuBranch(resolution.target, false)).toBe('global');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasContextMenu.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasContextMenu.ts
new file mode 100644
index 00000000000..707ce0e60f4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasContextMenu.ts
@@ -0,0 +1,56 @@
+export interface CanvasContextMenuTarget {
+  x: number;
+  y: number;
+  layerId: string | null;
+}
+
+interface ResolveCanvasContextMenuOptions {
+  clientX: number;
+  clientY: number;
+  hitTest?: (point: { x: number; y: number }) => string | null;
+  isInlineEditor: boolean;
+  isInteractionLocked: boolean;
+  surfaceLeft: number;
+  surfaceTop: number;
+}
+
+interface CanvasContextMenuResolution {
+  preventDefault: boolean;
+  target: CanvasContextMenuTarget | null;
+}
+
+export type CanvasContextMenuBranch = 'global' | 'layer' | null;
+
+export const resolveCanvasContextMenuBranch = (
+  target: CanvasContextMenuTarget | null,
+  hasEngine: boolean
+): CanvasContextMenuBranch => {
+  if (!target) {
+    return null;
+  }
+
+  return target.layerId !== null && hasEngine ? 'layer' : 'global';
+};
+
+export const resolveCanvasContextMenu = ({
+  clientX,
+  clientY,
+  hitTest,
+  isInlineEditor,
+  isInteractionLocked,
+  surfaceLeft,
+  surfaceTop,
+}: ResolveCanvasContextMenuOptions): CanvasContextMenuResolution => {
+  if (isInlineEditor) {
+    return { preventDefault: false, target: null };
+  }
+
+  const layerId = isInteractionLocked
+    ? null
+    : (hitTest?.({ x: clientX - surfaceLeft, y: clientY - surfaceTop }) ?? null);
+
+  return {
+    preventDefault: true,
+    target: { layerId, x: clientX, y: clientY },
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasGallerySaveState.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasGallerySaveState.test.ts
new file mode 100644
index 00000000000..82dc1e088da
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasGallerySaveState.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { getCanvasGallerySaveErrorAction, withMatchingCanvasProject } from './canvasGallerySaveState';
+
+describe('withMatchingCanvasProject', () => {
+  it('does not run save, refresh, or error effects for a mismatched engine and project', () => {
+    const save = vi.fn();
+    const refresh = vi.fn();
+    const recordError = vi.fn();
+
+    const result = withMatchingCanvasProject({ projectId: 'engine-project' }, 'active-project', () => {
+      save();
+      refresh();
+      recordError();
+    });
+
+    expect(result).toBeUndefined();
+    expect(save).not.toHaveBeenCalled();
+    expect(refresh).not.toHaveBeenCalled();
+    expect(recordError).not.toHaveBeenCalled();
+  });
+});
+
+describe('getCanvasGallerySaveErrorAction', () => {
+  it('maps a save failure to one localized record with diagnostic context', () => {
+    expect(
+      getCanvasGallerySaveErrorAction(new Error('backend exploded'), 'project-1', "Couldn't save to gallery")
+    ).toEqual({
+      area: 'canvas-save-to-gallery',
+      context: { error: 'backend exploded' },
+      message: "Couldn't save to gallery",
+      namespace: 'canvas',
+      projectId: 'project-1',
+      type: 'recordError',
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasGallerySaveState.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasGallerySaveState.ts
new file mode 100644
index 00000000000..9a2f4d0db14
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasGallerySaveState.ts
@@ -0,0 +1,26 @@
+interface CanvasProjectIdentity {
+  readonly projectId: string;
+}
+
+const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+export const getCanvasGallerySaveErrorAction = (error: unknown, projectId: string, message: string) => ({
+  area: 'canvas-save-to-gallery',
+  context: { error: toErrorMessage(error) },
+  message,
+  namespace: 'canvas' as const,
+  projectId,
+  type: 'recordError' as const,
+});
+
+export const withMatchingCanvasProject = <Engine extends CanvasProjectIdentity, Result>(
+  engine: Engine | null,
+  projectId: string,
+  run: (engine: Engine) => Result
+): Result | undefined => {
+  if (!engine || engine.projectId !== projectId) {
+    return undefined;
+  }
+
+  return run(engine);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDnd.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDnd.test.ts
new file mode 100644
index 00000000000..31daeee8b36
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDnd.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { getCanvasImageDropData, isCanvasImageDropData } from './canvasImageDnd';
+
+describe('canvasImageDnd', () => {
+  it.each(['raster', 'control', 'regional-reference', 'inpaint-mask', 'control-resized'] as const)(
+    'round-trips the %s destination through the factory and guard',
+    (destination) => {
+      const data = getCanvasImageDropData(destination);
+
+      expect(data).toEqual({ destination, kind: 'canvas-image-target' });
+      expect(isCanvasImageDropData(data)).toBe(true);
+    }
+  );
+
+  it.each([
+    null,
+    undefined,
+    'canvas-image-target',
+    {},
+    { destination: 'raster' },
+    { kind: 'canvas-image-target' },
+    { destination: 'regional-guidance', kind: 'canvas-image-target' },
+    { destination: 'unknown', kind: 'canvas-image-target' },
+    { destination: null, kind: 'canvas-image-target' },
+  ])('rejects malformed canvas image drop data: %j', (value) => {
+    expect(isCanvasImageDropData(value)).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDnd.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDnd.ts
new file mode 100644
index 00000000000..6f376aadfd9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDnd.ts
@@ -0,0 +1,60 @@
+import type { GalleryCanvasImportDestination } from '@workbench/canvas-operations/api';
+import type { GalleryImage } from '@workbench/gallery/api';
+
+import { isGalleryImageDragData } from '@workbench/widgets/gallery/galleryDnd';
+
+export interface CanvasImageDropData {
+  kind: 'canvas-image-target';
+  destination: Exclude<GalleryCanvasImportDestination, 'regional-guidance'>;
+}
+
+export const isCanvasImageDropData = (value: unknown): value is CanvasImageDropData =>
+  isRecord(value) && value.kind === 'canvas-image-target' && isCanvasImageDropDestination(value.destination);
+
+export const getCanvasImageDropData = (destination: CanvasImageDropData['destination']): CanvasImageDropData => ({
+  destination,
+  kind: 'canvas-image-target',
+});
+
+export const getCanvasImageDropId = (destination: CanvasImageDropData['destination']): string =>
+  `canvas-image-target:${destination}`;
+
+export interface CanvasImageDropResolution {
+  destination: CanvasImageDropData['destination'];
+  imageNames: string[];
+}
+
+export const resolveCanvasImageDrop = (activeData: unknown, overData: unknown): CanvasImageDropResolution | null => {
+  if (!isGalleryImageDragData(activeData) || !isCanvasImageDropData(overData)) {
+    return null;
+  }
+
+  return {
+    destination: overData.destination,
+    imageNames: activeData.images.map((image) => image.imageName),
+  };
+};
+
+export const orderCanvasImageDropImages = (
+  imageNames: readonly string[],
+  images: readonly GalleryImage[]
+): GalleryImage[] => {
+  const imagesByName = new Map(images.map((image) => [image.imageName, image]));
+  return imageNames.flatMap((imageName) => {
+    const image = imagesByName.get(imageName);
+    return image ? [image] : [];
+  });
+};
+
+const canvasImageDropDestinations = {
+  control: true,
+  'control-resized': true,
+  'inpaint-mask': true,
+  raster: true,
+  'regional-reference': true,
+} satisfies Record<CanvasImageDropData['destination'], true>;
+
+const isCanvasImageDropDestination = (value: unknown): value is CanvasImageDropData['destination'] =>
+  typeof value === 'string' && Object.hasOwn(canvasImageDropDestinations, value);
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDropLayout.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDropLayout.test.ts
new file mode 100644
index 00000000000..1d27f2d79ef
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasImageDropLayout.test.ts
@@ -0,0 +1,132 @@
+import type { CanvasEngine } from '@workbench/canvas-operations/createCanvasEngine';
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { Project, WorkbenchState } from '@workbench/types';
+
+import { getGalleryImageDragData } from '@workbench/widgets/gallery/galleryDnd';
+import { describe, expect, it } from 'vitest';
+
+import {
+  getCanvasImageDropData,
+  getCanvasImageDropId,
+  orderCanvasImageDropImages,
+  resolveCanvasImageDrop,
+} from './canvasImageDnd';
+import { CANVAS_IMAGE_DROP_GRID_LAYOUT, CANVAS_IMAGE_DROP_LAYOUT } from './CanvasImageDropOverlay';
+import { executeCanvasImageDropImport } from './executeCanvasImageDropImport';
+
+describe('canvas image drop layout', () => {
+  it('covers the full surface with the legacy six-column, two-row grid', () => {
+    expect(CANVAS_IMAGE_DROP_GRID_LAYOUT).toEqual({
+      gap: '0',
+      padding: '0',
+      templateColumns: 'repeat(6, minmax(0, 1fr))',
+      templateRows: 'repeat(2, minmax(0, 1fr))',
+    });
+  });
+
+  it('occupies exactly six columns in each of two rows', () => {
+    expect(CANVAS_IMAGE_DROP_LAYOUT).toEqual([
+      { colSpan: 3, destination: 'raster', row: 1 },
+      { colSpan: 3, destination: 'control', row: 1 },
+      { colSpan: 2, destination: 'regional-reference', row: 2 },
+      { colSpan: 2, destination: 'inpaint-mask', row: 2 },
+      { colSpan: 2, destination: 'control-resized', row: 2 },
+    ]);
+
+    expect(
+      CANVAS_IMAGE_DROP_LAYOUT.reduce<Record<number, number>>((columnsByRow, zone) => {
+        columnsByRow[zone.row] = (columnsByRow[zone.row] ?? 0) + zone.colSpan;
+        return columnsByRow;
+      }, {})
+    ).toEqual({ 1: 6, 2: 6 });
+  });
+
+  it('has unique destinations and stable unique droppable ids', () => {
+    const destinations = CANVAS_IMAGE_DROP_LAYOUT.map((zone) => zone.destination);
+    const firstIds = destinations.map(getCanvasImageDropId);
+    const secondIds = destinations.map(getCanvasImageDropId);
+
+    expect(new Set(destinations).size).toBe(CANVAS_IMAGE_DROP_LAYOUT.length);
+    expect(new Set(firstIds).size).toBe(CANVAS_IMAGE_DROP_LAYOUT.length);
+    expect(secondIds).toEqual(firstIds);
+  });
+});
+
+describe('resolveCanvasImageDrop', () => {
+  const galleryDrag = getGalleryImageDragData([
+    { boardId: 'board-a', imageName: 'third.png' },
+    { boardId: 'board-b', imageName: 'first.png' },
+    { boardId: 'board-a', imageName: 'second.png' },
+  ]);
+
+  it('accepts a gallery-image to canvas-image-target pair and preserves requested order', () => {
+    expect(resolveCanvasImageDrop(galleryDrag, getCanvasImageDropData('control-resized'))).toEqual({
+      destination: 'control-resized',
+      imageNames: ['third.png', 'first.png', 'second.png'],
+    });
+  });
+
+  it.each([
+    [null, getCanvasImageDropData('raster')],
+    [{ kind: 'widget-instance' }, getCanvasImageDropData('raster')],
+    [galleryDrag, null],
+    [galleryDrag, { destination: 'raster', kind: 'widget-region' }],
+    [galleryDrag, { destination: 'regional-guidance', kind: 'canvas-image-target' }],
+  ])('rejects a non gallery-image to canvas-image-target pair', (activeData, overData) => {
+    expect(resolveCanvasImageDrop(activeData, overData)).toBeNull();
+  });
+});
+
+describe('orderCanvasImageDropImages', () => {
+  it('restores requested order and omits backend results that were not requested', () => {
+    const first = { imageName: 'first.png' } as GalleryImage;
+    const second = { imageName: 'second.png' } as GalleryImage;
+    const extra = { imageName: 'extra.png' } as GalleryImage;
+
+    expect(orderCanvasImageDropImages(['first.png', 'missing.png', 'second.png'], [extra, second, first])).toEqual([
+      first,
+      second,
+    ]);
+  });
+});
+
+describe('executeCanvasImageDropImport', () => {
+  it('looks up all names once, restores requested order, and calls the shared service once', async () => {
+    const first = { imageName: 'first.png' } as GalleryImage;
+    const second = { imageName: 'second.png' } as GalleryImage;
+    const extra = { imageName: 'extra.png' } as GalleryImage;
+    const project = { id: 'captured-project' } as Project;
+    const engine = { projectId: project.id } as CanvasEngine;
+    const getState = () => ({ activeProjectId: project.id }) as WorkbenchState;
+    const lookupCalls: string[][] = [];
+    const importCalls: unknown[] = [];
+
+    const result = await executeCanvasImageDropImport({
+      destination: 'control',
+      dispatch: () => undefined,
+      engine,
+      getGalleryImages: (imageNames) => {
+        lookupCalls.push([...imageNames]);
+        return Promise.resolve([second, extra, first]);
+      },
+      getState,
+      imageNames: ['first.png', 'second.png'],
+      importGalleryImages: (options) => {
+        importCalls.push(options);
+        return Promise.resolve({ failedImageNames: [], layerIds: ['layer-1', 'layer-2'], status: 'imported' });
+      },
+      project,
+    });
+
+    expect(lookupCalls).toEqual([['first.png', 'second.png']]);
+    expect(importCalls).toHaveLength(1);
+    expect(importCalls[0]).toMatchObject({
+      destination: 'control',
+      engine,
+      getState,
+      images: [first, second],
+      project,
+    });
+    expect(result).toEqual({ failedImageNames: [], layerIds: ['layer-1', 'layer-2'], status: 'imported' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasInteractionLock.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasInteractionLock.test.ts
new file mode 100644
index 00000000000..d053674b65e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasInteractionLock.test.ts
@@ -0,0 +1,214 @@
+import type { CanvasStagingCandidateContract, QueueItem, QueueItemStatus } from '@workbench/types';
+
+import { createEmptyCanvasStateV2 } from '@workbench/canvasMigration';
+import { describe, expect, it } from 'vitest';
+
+import {
+  getCanvasInteractionCapabilities,
+  isCanvasInteractionLocked,
+  isCanvasStagingActive,
+  isCanvasToolEnabled,
+} from './canvasInteractionLock';
+
+const createStagedCandidate = (): CanvasStagingCandidateContract => ({
+  height: 512,
+  imageName: 'staged.png',
+  imageUrl: '/api/v1/images/i/staged.png/full',
+  placement: { height: 512, opacity: 1, width: 512, x: 0, y: 0 },
+  queuedAt: '2026-06-09T00:00:00.000Z',
+  sourceQueueItemId: 'queue-staged',
+  thumbnailUrl: '/api/v1/images/i/staged.png/thumbnail',
+  width: 512,
+});
+
+const createCanvas = ({ revision = 1, staged = false }: { revision?: number; staged?: boolean } = {}) => {
+  const canvas = createEmptyCanvasStateV2(512, 512);
+  const pendingImages = staged ? [createStagedCandidate()] : [];
+
+  return {
+    ...canvas,
+    documentRevision: revision,
+    stagingArea: {
+      ...canvas.stagingArea,
+      isVisible: staged,
+      pendingImageIds: pendingImages.map((image) => image.imageName),
+      pendingImages,
+    },
+  };
+};
+
+const createQueueItem = ({ revision = 1, status }: { revision?: number; status: QueueItemStatus }): QueueItem =>
+  ({
+    backendItemIds: [1],
+    completedBackendItemIds: [1],
+    id: `queue-${status}`,
+    snapshot: {
+      canvas: { documentRevision: revision },
+      destination: 'canvas',
+      submittedAt: '2026-06-09T00:00:00.000Z',
+    },
+    status,
+  }) as QueueItem;
+
+describe('canvas interaction lock', () => {
+  it.each([
+    {
+      expected: {
+        areOperationActionsEnabled: false,
+        canAcceptStagedImage: false,
+        isDocumentEditingLocked: false,
+        isOperationChromeVisible: false,
+        isRegularToolOptionsVisible: true,
+        isSurfaceInteractionLocked: false,
+      },
+      generation: false,
+      operationKind: null,
+      staged: false,
+    },
+    {
+      expected: {
+        areOperationActionsEnabled: true,
+        canAcceptStagedImage: false,
+        isDocumentEditingLocked: true,
+        isOperationChromeVisible: true,
+        isRegularToolOptionsVisible: false,
+        isSurfaceInteractionLocked: false,
+      },
+      generation: false,
+      operationKind: 'filter' as const,
+      staged: false,
+    },
+    {
+      expected: {
+        areOperationActionsEnabled: true,
+        canAcceptStagedImage: false,
+        isDocumentEditingLocked: true,
+        isOperationChromeVisible: true,
+        isRegularToolOptionsVisible: false,
+        isSurfaceInteractionLocked: false,
+      },
+      generation: false,
+      operationKind: 'select-object' as const,
+      staged: false,
+    },
+    {
+      expected: {
+        areOperationActionsEnabled: false,
+        canAcceptStagedImage: true,
+        isDocumentEditingLocked: false,
+        isOperationChromeVisible: false,
+        isRegularToolOptionsVisible: false,
+        isSurfaceInteractionLocked: true,
+      },
+      generation: false,
+      operationKind: null,
+      staged: true,
+    },
+    {
+      expected: {
+        areOperationActionsEnabled: false,
+        canAcceptStagedImage: false,
+        isDocumentEditingLocked: false,
+        isOperationChromeVisible: false,
+        isRegularToolOptionsVisible: false,
+        isSurfaceInteractionLocked: true,
+      },
+      generation: true,
+      operationKind: null,
+      staged: false,
+    },
+    {
+      expected: {
+        areOperationActionsEnabled: false,
+        canAcceptStagedImage: false,
+        isDocumentEditingLocked: true,
+        isOperationChromeVisible: true,
+        isRegularToolOptionsVisible: false,
+        isSurfaceInteractionLocked: true,
+      },
+      generation: false,
+      operationKind: 'filter' as const,
+      staged: true,
+    },
+    {
+      expected: {
+        areOperationActionsEnabled: false,
+        canAcceptStagedImage: false,
+        isDocumentEditingLocked: true,
+        isOperationChromeVisible: true,
+        isRegularToolOptionsVisible: false,
+        isSurfaceInteractionLocked: true,
+      },
+      generation: true,
+      operationKind: 'select-object' as const,
+      staged: false,
+    },
+  ])(
+    'separates surface, document, and chrome capabilities for operation=$operationKind staged=$staged generation=$generation',
+    ({ expected, generation, operationKind, staged }) => {
+      expect(
+        getCanvasInteractionCapabilities({
+          hasCanvasEngine: true,
+          hasSelectedCandidate: staged,
+          hasStagingSlots: staged,
+          isCanvasGenerationInFlight: generation,
+          operationKind,
+        })
+      ).toEqual(expected);
+    }
+  );
+
+  it('does not lock an empty canvas', () => {
+    expect(isCanvasInteractionLocked(createCanvas(), [])).toBe(false);
+  });
+
+  it('locks while a staged candidate exists', () => {
+    expect(isCanvasInteractionLocked(createCanvas({ staged: true }), [])).toBe(true);
+  });
+
+  it('locks for a pending queue item on the current document revision without staging slots', () => {
+    expect(
+      isCanvasInteractionLocked(createCanvas({ revision: 2 }), [createQueueItem({ revision: 2, status: 'pending' })])
+    ).toBe(true);
+  });
+
+  it('locks for a running queue item on the current document revision without staging slots', () => {
+    expect(
+      isCanvasInteractionLocked(createCanvas({ revision: 2 }), [createQueueItem({ revision: 2, status: 'running' })])
+    ).toBe(true);
+  });
+
+  it('does not lock for terminal queue items', () => {
+    const canvas = createCanvas({ revision: 2 });
+
+    for (const status of ['completed', 'failed', 'cancelled'] as const) {
+      expect(isCanvasInteractionLocked(canvas, [createQueueItem({ revision: 2, status })])).toBe(false);
+    }
+  });
+
+  it('does not lock for an active queue item from a stale document revision', () => {
+    expect(
+      isCanvasInteractionLocked(createCanvas({ revision: 2 }), [createQueueItem({ revision: 1, status: 'running' })])
+    ).toBe(false);
+  });
+
+  it('treats pending staged candidates and in-flight canvas generation as active staging', () => {
+    expect(isCanvasStagingActive({ hasStagedCandidates: true, isCanvasGenerationInFlight: false })).toBe(true);
+    expect(isCanvasStagingActive({ hasStagedCandidates: false, isCanvasGenerationInFlight: true })).toBe(true);
+    expect(isCanvasStagingActive({ hasStagedCandidates: false, isCanvasGenerationInFlight: false })).toBe(false);
+  });
+
+  it('allows only the view tool while staging locks canvas interactions', () => {
+    expect(isCanvasToolEnabled('view', true)).toBe(true);
+    expect(isCanvasToolEnabled('bbox', true)).toBe(false);
+    expect(isCanvasToolEnabled('brush', true)).toBe(false);
+    expect(isCanvasToolEnabled('move', true)).toBe(false);
+    expect(isCanvasToolEnabled('colorPicker', true)).toBe(false);
+  });
+
+  it('allows all tools when staging is inactive', () => {
+    expect(isCanvasToolEnabled('bbox', false)).toBe(true);
+    expect(isCanvasToolEnabled('brush', false)).toBe(true);
+    expect(isCanvasToolEnabled('colorPicker', false)).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasInteractionLock.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasInteractionLock.ts
new file mode 100644
index 00000000000..ec616529f8b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasInteractionLock.ts
@@ -0,0 +1,61 @@
+import type { ToolId } from '@workbench/canvas-engine/types';
+import type { CanvasStateContractV2, QueueItem } from '@workbench/types';
+
+import { getCanvasStagingSlots } from '@workbench/canvasStagingView';
+
+export const isCanvasInteractionLocked = (canvas: CanvasStateContractV2, queueItems: readonly QueueItem[]): boolean =>
+  getCanvasStagingSlots(canvas, queueItems).length > 0 ||
+  queueItems.some(
+    (item) =>
+      item.snapshot.destination === 'canvas' &&
+      item.snapshot.canvas.documentRevision === canvas.documentRevision &&
+      (item.status === 'pending' || item.status === 'running')
+  );
+
+export const isCanvasStagingActive = ({
+  hasStagedCandidates,
+  isCanvasGenerationInFlight,
+}: {
+  hasStagedCandidates: boolean;
+  isCanvasGenerationInFlight: boolean;
+}): boolean => hasStagedCandidates || isCanvasGenerationInFlight;
+
+export interface CanvasInteractionCapabilities {
+  areOperationActionsEnabled: boolean;
+  canAcceptStagedImage: boolean;
+  isDocumentEditingLocked: boolean;
+  isOperationChromeVisible: boolean;
+  isRegularToolOptionsVisible: boolean;
+  isSurfaceInteractionLocked: boolean;
+}
+
+export const getCanvasInteractionCapabilities = ({
+  hasCanvasEngine,
+  hasSelectedCandidate,
+  hasStagingSlots,
+  isCanvasGenerationInFlight,
+  operationKind,
+}: {
+  hasCanvasEngine: boolean;
+  hasSelectedCandidate: boolean;
+  hasStagingSlots: boolean;
+  isCanvasGenerationInFlight: boolean;
+  operationKind: 'filter' | 'select-object' | null;
+}): CanvasInteractionCapabilities => {
+  const isSurfaceInteractionLocked = isCanvasStagingActive({
+    hasStagedCandidates: hasStagingSlots,
+    isCanvasGenerationInFlight,
+  });
+  const isDocumentEditingLocked = operationKind !== null;
+  return {
+    areOperationActionsEnabled: isDocumentEditingLocked && !isSurfaceInteractionLocked,
+    canAcceptStagedImage: hasCanvasEngine && hasSelectedCandidate && !isDocumentEditingLocked,
+    isDocumentEditingLocked,
+    isOperationChromeVisible: isDocumentEditingLocked,
+    isRegularToolOptionsVisible: !isDocumentEditingLocked && !isSurfaceInteractionLocked,
+    isSurfaceInteractionLocked,
+  };
+};
+
+export const isCanvasToolEnabled = (toolId: ToolId, isInteractionLocked: boolean): boolean =>
+  !isInteractionLocked || toolId === 'view';
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasSettings.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasSettings.test.ts
new file mode 100644
index 00000000000..3a2626f1358
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasSettings.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  CANVAS_BBOX_OVERLAY_KEY,
+  CANVAS_CHECKERBOARD_KEY,
+  CANVAS_INVERT_BRUSH_SCROLL_KEY,
+  CANVAS_RULE_OF_THIRDS_KEY,
+  CANVAS_SETTING_SECTIONS,
+  CANVAS_SETTINGS,
+  CANVAS_SHOW_BBOX_KEY,
+  CANVAS_SHOW_GRID_KEY,
+  CANVAS_SHOW_PROGRESS_KEY,
+  CANVAS_SNAP_TO_GRID_KEY,
+  canvasSettingsEqual,
+  readCanvasBooleanSetting,
+  resolveCanvasSettings,
+} from './canvasSettings';
+
+const settingByKey = (key: string) => {
+  const found = CANVAS_SETTINGS.find((s) => s.key === key);
+  if (!found) {
+    throw new Error(`no setting for key ${key}`);
+  }
+  return found;
+};
+
+const DEFAULTS = {
+  [CANVAS_BBOX_OVERLAY_KEY]: false,
+  [CANVAS_CHECKERBOARD_KEY]: true,
+  [CANVAS_INVERT_BRUSH_SCROLL_KEY]: false,
+  [CANVAS_RULE_OF_THIRDS_KEY]: false,
+  [CANVAS_SHOW_BBOX_KEY]: true,
+  [CANVAS_SHOW_GRID_KEY]: false,
+  [CANVAS_SHOW_PROGRESS_KEY]: true,
+  [CANVAS_SNAP_TO_GRID_KEY]: true,
+};
+
+describe('canvasSettings persistence mapping', () => {
+  it('applies each setting default when values are missing', () => {
+    expect(resolveCanvasSettings(undefined)).toEqual(DEFAULTS);
+    expect(resolveCanvasSettings({})).toEqual(DEFAULTS);
+  });
+
+  it('reads persisted booleans over the defaults', () => {
+    const resolved = resolveCanvasSettings({
+      [CANVAS_BBOX_OVERLAY_KEY]: true,
+      [CANVAS_CHECKERBOARD_KEY]: false,
+      [CANVAS_INVERT_BRUSH_SCROLL_KEY]: true,
+      [CANVAS_RULE_OF_THIRDS_KEY]: true,
+      [CANVAS_SHOW_BBOX_KEY]: false,
+      [CANVAS_SHOW_GRID_KEY]: true,
+      [CANVAS_SHOW_PROGRESS_KEY]: false,
+      [CANVAS_SNAP_TO_GRID_KEY]: false,
+    });
+    expect(resolved).toEqual({
+      [CANVAS_BBOX_OVERLAY_KEY]: true,
+      [CANVAS_CHECKERBOARD_KEY]: false,
+      [CANVAS_INVERT_BRUSH_SCROLL_KEY]: true,
+      [CANVAS_RULE_OF_THIRDS_KEY]: true,
+      [CANVAS_SHOW_BBOX_KEY]: false,
+      [CANVAS_SHOW_GRID_KEY]: true,
+      [CANVAS_SHOW_PROGRESS_KEY]: false,
+      [CANVAS_SNAP_TO_GRID_KEY]: false,
+    });
+  });
+
+  it('falls back to the default for a non-boolean persisted value', () => {
+    expect(readCanvasBooleanSetting({ [CANVAS_CHECKERBOARD_KEY]: 'nope' }, settingByKey(CANVAS_CHECKERBOARD_KEY))).toBe(
+      true
+    );
+    expect(readCanvasBooleanSetting({ [CANVAS_SHOW_GRID_KEY]: 1 }, settingByKey(CANVAS_SHOW_GRID_KEY))).toBe(false);
+  });
+
+  it('maps every setting to a unique key and a known section', () => {
+    const keys = CANVAS_SETTINGS.map((s) => s.key);
+    expect(new Set(keys).size).toBe(keys.length);
+    for (const setting of CANVAS_SETTINGS) {
+      expect(CANVAS_SETTING_SECTIONS).toContain(setting.section);
+    }
+  });
+
+  it('gives every engine-backed store a distinct store id (React-consumed settings have none)', () => {
+    const stores = CANVAS_SETTINGS.map((s) => s.store).filter((s): s is NonNullable<typeof s> => s !== undefined);
+    expect(new Set(stores).size).toBe(stores.length);
+    // showProgressOnCanvas is consumed React-side and intentionally has no store.
+    expect(settingByKey(CANVAS_SHOW_PROGRESS_KEY).store).toBeUndefined();
+  });
+});
+
+describe('canvasSettingsEqual', () => {
+  it('is true for equal maps and false when any setting differs', () => {
+    const base = resolveCanvasSettings({});
+    expect(canvasSettingsEqual(base, resolveCanvasSettings({}))).toBe(true);
+    expect(canvasSettingsEqual(base, resolveCanvasSettings({ [CANVAS_SHOW_GRID_KEY]: true }))).toBe(false);
+    expect(canvasSettingsEqual(base, resolveCanvasSettings({ [CANVAS_SHOW_BBOX_KEY]: false }))).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasSettings.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasSettings.ts
new file mode 100644
index 00000000000..4ab14fc9b77
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/canvasSettings.ts
@@ -0,0 +1,156 @@
+/**
+ * Canvas view settings — the sectioned, legacy-style popover of per-project
+ * canvas preferences (Behavior / Display / Grid), plus the Shift-revealed Debug
+ * actions rendered separately in the header.
+ *
+ * Each setting is a boolean persisted in the canvas widget's own state values
+ * (`widgetInstances['canvas'].state.values[key]`) — the same plumbing as the
+ * denoising strength (`invoke/canvasStrength.ts`), so it survives reloads and
+ * rides along in queue snapshots. Persistence is per-user (per-project), NEVER in
+ * the canvas undo history.
+ *
+ * A setting either drives an engine boolean store (`store` set — React resolves
+ * the persisted value and feeds it down; see the settings-feed effect in
+ * `CanvasWidgetView`, the engine reads only its stores and never React) OR is
+ * consumed directly React-side (`store` absent — e.g. `showProgressOnCanvas`,
+ * which gates the progress-preview feed in the widget shell). The feed is strictly
+ * one-directional: settings → engine, never the reverse.
+ *
+ * The list is data-driven: adding a boolean setting is one entry here plus its
+ * i18n label and (when engine-backed) the store it drives. Pure data + readers;
+ * no React, no engine imports — unit-testable in node.
+ */
+
+/** Which engine boolean store a setting feeds (settings whose `store` is absent are React-consumed). */
+export type CanvasSettingStore =
+  | 'checkerboard'
+  | 'showGrid'
+  | 'invertBrushSizeScroll'
+  | 'showBbox'
+  | 'bboxOverlay'
+  | 'ruleOfThirds'
+  | 'snapToGrid';
+
+/** The popover section a setting is grouped under. */
+export type CanvasSettingSection = 'behavior' | 'display' | 'grid';
+
+/** Persisted keys inside the canvas widget's `state.values`. */
+export const CANVAS_CHECKERBOARD_KEY = 'showCheckerboard';
+export const CANVAS_SHOW_GRID_KEY = 'showGrid';
+export const CANVAS_INVERT_BRUSH_SCROLL_KEY = 'invertBrushSizeScroll';
+export const CANVAS_SHOW_BBOX_KEY = 'showBbox';
+export const CANVAS_BBOX_OVERLAY_KEY = 'bboxOverlay';
+export const CANVAS_RULE_OF_THIRDS_KEY = 'ruleOfThirds';
+export const CANVAS_SNAP_TO_GRID_KEY = 'snapToGrid';
+export const CANVAS_SHOW_PROGRESS_KEY = 'showProgressOnCanvas';
+
+/** A single boolean canvas setting: its persisted key, default, label, section, and (optional) engine store. */
+export interface CanvasBooleanSetting {
+  /** The persisted key inside the canvas widget's `state.values`. */
+  key: string;
+  /** The engine store this value drives; absent when the setting is consumed React-side. */
+  store?: CanvasSettingStore;
+  /** Default value applied when the key is unset. */
+  defaultValue: boolean;
+  /** i18n key for the popover label. */
+  labelKey: string;
+  /** Which popover section the setting belongs to. */
+  section: CanvasSettingSection;
+}
+
+/**
+ * The canvas settings, in popover order (grouped by section). Extend by adding an
+ * entry (plus its label and, when engine-backed, a store); the popover,
+ * persistence, and engine feed all derive from this list.
+ */
+export const CANVAS_SETTINGS: readonly CanvasBooleanSetting[] = [
+  // ── Behavior ──────────────────────────────────────────────────────────────
+  {
+    defaultValue: false,
+    key: CANVAS_INVERT_BRUSH_SCROLL_KEY,
+    labelKey: 'widgets.canvas.settings.invertBrushScroll',
+    section: 'behavior',
+    store: 'invertBrushSizeScroll',
+  },
+  // ── Display ───────────────────────────────────────────────────────────────
+  {
+    defaultValue: true,
+    key: CANVAS_SHOW_PROGRESS_KEY,
+    labelKey: 'widgets.canvas.settings.showProgressOnCanvas',
+    section: 'display',
+    // No engine store: gated React-side (the progress-preview feed in CanvasWidgetView).
+  },
+  {
+    // Legacy-parity "bbox overlay": dims everything OUTSIDE the generation frame.
+    defaultValue: false,
+    key: CANVAS_BBOX_OVERLAY_KEY,
+    labelKey: 'widgets.canvas.settings.bboxOverlay',
+    section: 'display',
+    store: 'bboxOverlay',
+  },
+  {
+    // webv2 extra (no legacy counterpart): hides the passive dashed bbox frame.
+    defaultValue: true,
+    key: CANVAS_SHOW_BBOX_KEY,
+    labelKey: 'widgets.canvas.settings.showBbox',
+    section: 'display',
+    store: 'showBbox',
+  },
+  {
+    defaultValue: true,
+    key: CANVAS_CHECKERBOARD_KEY,
+    labelKey: 'widgets.canvas.settings.checkerboard',
+    section: 'display',
+    store: 'checkerboard',
+  },
+  // ── Grid ──────────────────────────────────────────────────────────────────
+  {
+    defaultValue: false,
+    key: CANVAS_SHOW_GRID_KEY,
+    labelKey: 'widgets.canvas.settings.grid',
+    section: 'grid',
+    store: 'showGrid',
+  },
+  {
+    defaultValue: true,
+    key: CANVAS_SNAP_TO_GRID_KEY,
+    labelKey: 'widgets.canvas.settings.snapToGrid',
+    section: 'grid',
+    store: 'snapToGrid',
+  },
+  {
+    defaultValue: false,
+    key: CANVAS_RULE_OF_THIRDS_KEY,
+    labelKey: 'widgets.canvas.settings.ruleOfThirds',
+    section: 'grid',
+    store: 'ruleOfThirds',
+  },
+];
+
+/** The sections, in popover render order. */
+export const CANVAS_SETTING_SECTIONS: readonly CanvasSettingSection[] = ['behavior', 'display', 'grid'];
+
+/** Resolved settings, keyed by persisted setting key (default-applied). */
+export type ResolvedCanvasSettings = Record<string, boolean>;
+
+/** Reads one boolean setting from a widget's `state.values`, applying its default when unset/non-boolean. */
+export const readCanvasBooleanSetting = (
+  values: Record<string, unknown> | undefined,
+  setting: CanvasBooleanSetting
+): boolean => {
+  const raw = values?.[setting.key];
+  return typeof raw === 'boolean' ? raw : setting.defaultValue;
+};
+
+/** Resolves every canvas setting from persisted values into a key→boolean map. */
+export const resolveCanvasSettings = (values: Record<string, unknown> | undefined): ResolvedCanvasSettings => {
+  const resolved: ResolvedCanvasSettings = {};
+  for (const setting of CANVAS_SETTINGS) {
+    resolved[setting.key] = readCanvasBooleanSetting(values, setting);
+  }
+  return resolved;
+};
+
+/** Structural equality for two resolved-settings maps (stable selector identity). */
+export const canvasSettingsEqual = (a: ResolvedCanvasSettings, b: ResolvedCanvasSettings): boolean =>
+  CANVAS_SETTINGS.every((setting) => a[setting.key] === b[setting.key]);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/checkerColors.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/checkerColors.ts
new file mode 100644
index 00000000000..0ea15e17c8c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/checkerColors.ts
@@ -0,0 +1,71 @@
+/**
+ * Resolves the transparency checkerboard's two square colors from the live Chakra
+ * theme so the infinite-canvas surround uses theme tokens (not hardcoded greys),
+ * and re-resolves on theme / color-mode switches. The resolved colors are fed
+ * one-directionally into the engine's `checkerColors` store (the same
+ * settings→engine-store pattern as the boolean canvas settings); the engine stays
+ * React-free and rebuilds its cached checker tile when the colors change.
+ *
+ * Resolution reads the *computed* backgroundColor of a hidden probe element set to
+ * each semantic token's CSS custom property — the browser's ground truth for the
+ * active `<html data-theme>`. Falls back to {@link DEFAULT_CHECKER_COLORS} when the
+ * DOM is unavailable (node tests) or a token yields nothing usable.
+ */
+
+import { system } from '@theme/system';
+import { type CheckerColors, DEFAULT_CHECKER_COLORS } from '@workbench/canvas-engine/render/compositor';
+
+/**
+ * The two Chakra semantic tokens used for the checker squares. `bg.subtle` and
+ * `bg.emphasized` are two adjacent neutral surfaces, giving a low-contrast checker
+ * that reads as "empty" in every theme (light and dark) without a bespoke pair.
+ */
+export const CHECKER_TOKEN_A = 'bg.subtle';
+export const CHECKER_TOKEN_B = 'bg.emphasized';
+
+/** The `var(--chakra-colors-…)` reference for a semantic color token, or `null` if unknown. */
+const cssVarRef = (token: string): string | null => {
+  const varName = system.tokens.getByName(`colors.${token}`)?.extensions.cssVar?.var;
+  return varName ? `var(${varName})` : null;
+};
+
+/**
+ * Whether a computed color string is usable — a non-empty color that isn't fully
+ * transparent (the browser's answer when a var failed to resolve).
+ */
+export const isUsableColor = (value: string | null | undefined): value is string =>
+  typeof value === 'string' && value.trim() !== '' && value !== 'transparent' && value !== 'rgba(0, 0, 0, 0)';
+
+/** Returns `resolved` when usable, else `fallback`. */
+export const pickCheckerColor = (resolved: string | null | undefined, fallback: string): string =>
+  isUsableColor(resolved) ? resolved : fallback;
+
+/**
+ * Resolves both checker colors from the current theme. Safe to call anytime; in a
+ * non-DOM environment (or before the theme is applied) it returns the fallback
+ * pair so callers always get concrete colors.
+ */
+export const resolveCheckerColors = (): CheckerColors => {
+  if (typeof document === 'undefined' || typeof getComputedStyle !== 'function' || !document.body) {
+    return { ...DEFAULT_CHECKER_COLORS };
+  }
+  const probe = document.createElement('div');
+  probe.style.display = 'none';
+  document.body.appendChild(probe);
+  try {
+    const read = (token: string, fallback: string): string => {
+      const ref = cssVarRef(token);
+      if (!ref) {
+        return fallback;
+      }
+      probe.style.backgroundColor = ref;
+      return pickCheckerColor(getComputedStyle(probe).backgroundColor, fallback);
+    };
+    return {
+      a: read(CHECKER_TOKEN_A, DEFAULT_CHECKER_COLORS.a),
+      b: read(CHECKER_TOKEN_B, DEFAULT_CHECKER_COLORS.b),
+    };
+  } finally {
+    probe.remove();
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/engineStoreHooks.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/engineStoreHooks.ts
new file mode 100644
index 00000000000..39f52acfc67
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/engineStoreHooks.ts
@@ -0,0 +1,160 @@
+/**
+ * React bindings for the engine's transient stores.
+ *
+ * `canvas-engine/engineStores.ts` deliberately ships React-free
+ * (`useSyncExternalStore`-compatible) channels so the engine stays node-safe.
+ * These hooks are the widget-side adapter — the one place React subscribes to
+ * that engine-owned interaction state. Keeping the React import here (under
+ * `widgets/`) preserves the engine's zero-React boundary.
+ */
+
+import type { CanvasCoreStoreCapability } from '@workbench/canvas-engine/api';
+import type {
+  BboxToolOptions,
+  BrushOptions,
+  EraserOptions,
+  GradientToolOptions,
+  LassoToolOptions,
+  ScalarStore,
+  ShapeToolOptions,
+  TextEditSession,
+  TextToolOptions,
+  TransformSession,
+  LayerThumbnailStatus,
+} from '@workbench/canvas-engine/engineStores';
+import type { ToolId } from '@workbench/canvas-engine/types';
+import type { CanvasOperationState } from '@workbench/canvas-operations/operationController';
+import type { FilterOperationSessionState, SamSessionSnapshot } from '@workbench/canvas-operations/operationTypes';
+
+import { getCanvasOperations } from '@workbench/canvas-operations/createCanvasEngine';
+import { useCallback, useSyncExternalStore } from 'react';
+
+/** Subscribes the calling component to a single engine scalar store. */
+const useScalarStore = <T>(store: ScalarStore<T>): T => useSyncExternalStore(store.subscribe, store.get);
+
+/**
+ * Subscribes to a single layer's thumbnail version on `engine`, re-rendering
+ * only when that layer's cached pixels change (the engine bumps the version on
+ * every repaint / rasterize). Tolerates a `null` engine — before the engine
+ * mounts the hook simply reports `undefined` and never subscribes — so the
+ * layers panel can render fallback thumbnails without an attached engine.
+ */
+export const useLayerThumbnailVersion = (
+  engine: CanvasCoreStoreCapability | null,
+  layerId: string
+): number | undefined => {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => engine?.stores.thumbnailVersion.subscribeKey(layerId, onStoreChange) ?? (() => {}),
+    [engine, layerId]
+  );
+  const getSnapshot = useCallback(() => engine?.stores.thumbnailVersion.get(layerId), [engine, layerId]);
+  return useSyncExternalStore(subscribe, getSnapshot);
+};
+
+/** Subscribes to one layer's thumbnail request state; an absent key is idle. */
+export const useLayerThumbnailStatus = (
+  engine: CanvasCoreStoreCapability | null,
+  layerId: string
+): LayerThumbnailStatus | 'idle' => {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => engine?.stores.thumbnailStatus.subscribeKey(layerId, onStoreChange) ?? (() => {}),
+    [engine, layerId]
+  );
+  const getSnapshot = useCallback(() => engine?.stores.thumbnailStatus.get(layerId) ?? 'idle', [engine, layerId]);
+  return useSyncExternalStore(subscribe, getSnapshot);
+};
+
+/** Current viewport zoom factor for `engine` (re-renders on zoom change). */
+export const useCanvasZoom = (engine: CanvasCoreStoreCapability): number => useScalarStore(engine.stores.zoom);
+
+/** Whether `engine` has render targets bound and its viewport is live. */
+export const useCanvasViewportReady = (engine: CanvasCoreStoreCapability): boolean =>
+  useScalarStore(engine.stores.viewportReady);
+
+/** The active tool id for `engine`. */
+export const useCanvasActiveTool = (engine: CanvasCoreStoreCapability): ToolId =>
+  useScalarStore(engine.stores.activeTool);
+
+const IDLE_CANVAS_OPERATION: CanvasOperationState = { status: 'idle' };
+
+export const useCanvasOperation = (engine: object | null): CanvasOperationState => {
+  const subscribe = useCallback(
+    (listener: () => void) => (engine ? getCanvasOperations(engine).controller.subscribe(listener) : () => undefined),
+    [engine]
+  );
+  const getSnapshot = useCallback(
+    () => (engine ? getCanvasOperations(engine).controller.getSnapshot() : IDLE_CANVAS_OPERATION),
+    [engine]
+  );
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+
+export const useSamSession = (engine: object): SamSessionSnapshot | null =>
+  useScalarStore(getCanvasOperations(engine).stores.samSession);
+
+export const useFilterSession = (engine: object): FilterOperationSessionState | null =>
+  useScalarStore(getCanvasOperations(engine).stores.filterSession);
+
+/** Whether the engine-owned canvas history has an entry to undo (enables the header undo button). */
+export const useCanvasCanUndo = (engine: CanvasCoreStoreCapability): boolean => useScalarStore(engine.stores.canUndo);
+
+/** Whether the engine-owned canvas history has an entry to redo (enables the header redo button). */
+export const useCanvasCanRedo = (engine: CanvasCoreStoreCapability): boolean => useScalarStore(engine.stores.canRedo);
+
+/** Whether a SAM/filter operation currently excludes ordinary canvas document edits. */
+export const useCanvasDocumentEditingLocked = (engine: CanvasCoreStoreCapability | null): boolean => {
+  const subscribe = useCallback(
+    (listener: () => void) => engine?.stores.documentEditingLocked.subscribe(listener) ?? (() => undefined),
+    [engine]
+  );
+  const getSnapshot = useCallback(() => engine?.stores.documentEditingLocked.get() ?? false, [engine]);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+
+/**
+ * The brush tool's current options (size / color / opacity / pressure). Write
+ * through `engine.stores.brushOptions.set(...)` directly — there is no reducer
+ * mirror to dispatch through, so the options bar reads and writes this one
+ * store.
+ */
+export const useBrushOptions = (engine: CanvasCoreStoreCapability): BrushOptions =>
+  useScalarStore(engine.stores.brushOptions);
+
+/** The eraser tool's current options (size / opacity). Write through `engine.stores.eraserOptions.set(...)`. */
+export const useEraserOptions = (engine: CanvasCoreStoreCapability): EraserOptions =>
+  useScalarStore(engine.stores.eraserOptions);
+
+/** The bbox tool's current options (aspect lock / ratio). Write through `engine.stores.bboxOptions.set(...)`. */
+export const useBboxOptions = (engine: CanvasCoreStoreCapability): BboxToolOptions =>
+  useScalarStore(engine.stores.bboxOptions);
+
+/** The bbox tool's current snapping grid size (document px). */
+export const useBboxGrid = (engine: CanvasCoreStoreCapability): number => useScalarStore(engine.stores.bboxGrid);
+
+/** The active transform-tool session (layer id + live transform), or `null`. */
+export const useTransformSession = (engine: CanvasCoreStoreCapability): TransformSession | null =>
+  useScalarStore(engine.stores.transformSession);
+
+/** Whether a pixel selection currently exists (enables fill/erase/invert/deselect controls). */
+export const useCanvasHasSelection = (engine: CanvasCoreStoreCapability): boolean =>
+  useScalarStore(engine.stores.hasSelection);
+
+/** The lasso tool's current options (the committed boolean op mode). Write through `engine.stores.lassoOptions.set(...)`. */
+export const useLassoOptions = (engine: CanvasCoreStoreCapability): LassoToolOptions =>
+  useScalarStore(engine.stores.lassoOptions);
+
+/** The shape tool's current options (kind / fill / stroke / stroke width). Write through `engine.stores.shapeOptions.set(...)`. */
+export const useShapeOptions = (engine: CanvasCoreStoreCapability): ShapeToolOptions =>
+  useScalarStore(engine.stores.shapeOptions);
+
+/** The gradient tool's current options (kind / angle / stops). Write through `engine.stores.gradientOptions.set(...)`. */
+export const useGradientOptions = (engine: CanvasCoreStoreCapability): GradientToolOptions =>
+  useScalarStore(engine.stores.gradientOptions);
+
+/** The text tool's current options (font / size / weight / line-height / align / color). */
+export const useTextOptions = (engine: CanvasCoreStoreCapability): TextToolOptions =>
+  useScalarStore(engine.stores.textOptions);
+
+/** The active text-editing session (create/edit mode + live source + transform), or `null`. */
+export const useTextEditSession = (engine: CanvasCoreStoreCapability): TextEditSession | null =>
+  useScalarStore(engine.stores.textEditSession);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/executeCanvasImageDropImport.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/executeCanvasImageDropImport.ts
new file mode 100644
index 00000000000..1b916cb1bad
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/executeCanvasImageDropImport.ts
@@ -0,0 +1,40 @@
+import type { Project, WorkbenchState } from '@workbench/types';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+import type { Dispatch } from 'react';
+
+import {
+  importGalleryImagesToCanvas,
+  type GalleryCanvasImportDestination,
+  type ImportGalleryImagesResult,
+} from '@workbench/canvas-operations/api';
+import { getGalleryImagesByNames } from '@workbench/gallery/api';
+
+import { orderCanvasImageDropImages } from './canvasImageDnd';
+
+type CanvasImageDropEngine = Pick<CanvasEngineHandle, 'layers' | 'projectId'>;
+
+export const executeCanvasImageDropImport = async ({
+  destination,
+  dispatch,
+  engine,
+  getGalleryImages = getGalleryImagesByNames,
+  getState,
+  imageNames,
+  importGalleryImages = importGalleryImagesToCanvas,
+  project,
+}: {
+  destination: GalleryCanvasImportDestination;
+  dispatch: Dispatch<WorkbenchAction>;
+  engine: CanvasImageDropEngine | null;
+  getGalleryImages?: typeof getGalleryImagesByNames;
+  getState: () => WorkbenchState;
+  imageNames: readonly string[];
+  importGalleryImages?: typeof importGalleryImagesToCanvas;
+  project: Project;
+}): Promise<ImportGalleryImagesResult> => {
+  const fetchedImages = await getGalleryImages([...imageNames]);
+  const images = orderCanvasImageDropImages(imageNames, fetchedImages);
+
+  return importGalleryImages({ destination, dispatch, engine, getState, images, project });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/fitBbox.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/fitBbox.test.ts
new file mode 100644
index 00000000000..540b0eb4135
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/fitBbox.test.ts
@@ -0,0 +1,137 @@
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { computeFitBboxToLayers, computeFitBboxToMasks, fitRectToGrid, unionRenderableBounds } from './fitBbox';
+
+/** An axis-aligned image layer (no rotation): document bounds are `[x, y, w, h]`. */
+const imageLayer = (
+  id: string,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  isEnabled = true
+): CanvasLayerContract =>
+  ({
+    blendMode: 'normal',
+    id,
+    isEnabled,
+    isLocked: false,
+    name: id,
+    opacity: 1,
+    source: { image: { height, imageName: `${id}-img`, width }, type: 'image' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x, y },
+    type: 'raster',
+  }) as CanvasLayerContract;
+
+const maskLayer = (
+  type: 'inpaint_mask' | 'regional_guidance',
+  id: string,
+  x: number,
+  y: number,
+  bitmap: { imageName: string; width: number; height: number } | null
+): CanvasLayerContract =>
+  ({
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    mask: { bitmap, fill: { color: '#e07575', style: 'diagonal' } },
+    name: id,
+    opacity: 1,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x, y },
+    type,
+  }) as CanvasLayerContract;
+
+const inpaintMask = (
+  id: string,
+  x: number,
+  y: number,
+  bitmap: { imageName: string; width: number; height: number } | null
+): CanvasLayerContract => maskLayer('inpaint_mask', id, x, y, bitmap);
+
+const docWith = (layers: CanvasLayerContract[]): CanvasDocumentContractV2 =>
+  ({
+    background: 'transparent',
+    bbox: { height: 512, width: 512, x: 0, y: 0 },
+    height: 1024,
+    layers,
+    selectedLayerId: null,
+    version: 2,
+    width: 1024,
+  }) as CanvasDocumentContractV2;
+
+describe('fitRectToGrid', () => {
+  it('snaps the rect inward to grid multiples (top-left up, size down)', () => {
+    // x=10 → ceil(10/8)*8=16 (+6); w=240 → floor((240-6)/8)*8=232.
+    expect(fitRectToGrid({ height: 230, width: 240, x: 10, y: 20 }, 8)).toEqual({
+      height: 224,
+      width: 232,
+      x: 16,
+      y: 24,
+    });
+  });
+
+  it('degrades to a plain integer round when the grid is <= 1 (snap-to-grid off)', () => {
+    // g=1: x=ceil(3.2)=4 (+0.8), w=floor(10.9-0.8)=10; y=ceil(4.8)=5 (+0.2), h=floor(12.4-0.2)=12.
+    expect(fitRectToGrid({ height: 12.4, width: 10.9, x: 3.2, y: 4.8 }, 1)).toEqual({
+      height: 12,
+      width: 10,
+      x: 4,
+      y: 5,
+    });
+  });
+});
+
+describe('unionRenderableBounds', () => {
+  it('unions enabled, non-empty layers and skips disabled / empty ones', () => {
+    const doc = docWith([
+      imageLayer('a', 10, 20, 100, 100),
+      imageLayer('b', 200, 200, 50, 50),
+      imageLayer('c', 500, 500, 40, 40, false), // disabled → excluded
+      inpaintMask('empty', 0, 0, null), // empty mask → excluded
+    ]);
+    expect(unionRenderableBounds(doc, () => true)).toEqual({ height: 230, width: 240, x: 10, y: 20 });
+  });
+
+  it('returns null when nothing qualifies', () => {
+    expect(unionRenderableBounds(docWith([inpaintMask('empty', 0, 0, null)]), () => true)).toBeNull();
+  });
+});
+
+describe('computeFitBboxToLayers', () => {
+  it('fits the union of all visible content, grid-snapped', () => {
+    const doc = docWith([imageLayer('a', 10, 20, 100, 100), imageLayer('b', 200, 200, 50, 50)]);
+    expect(computeFitBboxToLayers(doc, 8)).toEqual({ height: 224, width: 232, x: 16, y: 24 });
+  });
+
+  it('returns null with no content (empty canvas)', () => {
+    expect(computeFitBboxToLayers(docWith([]), 8)).toBeNull();
+  });
+});
+
+describe('computeFitBboxToMasks', () => {
+  it('fits only inpaint masks, padded then grid-snapped', () => {
+    const doc = docWith([
+      imageLayer('a', 0, 0, 500, 500), // ignored (not a mask)
+      inpaintMask('m', 100, 100, { height: 40, imageName: 'm-img', width: 40 }),
+    ]);
+    // mask bounds {100,100,40,40} → pad 8 → {92,92,56,56} → grid 8 → {96,96,48,48}.
+    expect(computeFitBboxToMasks(doc, 8)).toEqual({ height: 48, width: 48, x: 96, y: 96 });
+  });
+
+  it('excludes regional-guidance masks (legacy fits inpaint_mask only)', () => {
+    const regional = maskLayer('regional_guidance', 'rg', 400, 400, { height: 40, imageName: 'rg-img', width: 40 });
+    const doc = docWith([regional, inpaintMask('m', 100, 100, { height: 40, imageName: 'm-img', width: 40 })]);
+    // Identical to the inpaint-only fit above: the regional mask contributes nothing.
+    expect(computeFitBboxToMasks(doc, 8)).toEqual({ height: 48, width: 48, x: 96, y: 96 });
+    // Regional masks alone ⇒ nothing to fit.
+    expect(computeFitBboxToMasks(docWith([regional]), 8)).toBeNull();
+  });
+
+  it('returns null when there are no visible inpaint masks', () => {
+    expect(computeFitBboxToMasks(docWith([imageLayer('a', 0, 0, 100, 100)]), 8)).toBeNull();
+    expect(computeFitBboxToMasks(docWith([inpaintMask('empty', 0, 0, null)]), 8)).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/fitBbox.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/fitBbox.ts
new file mode 100644
index 00000000000..4650ef1626e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/fitBbox.ts
@@ -0,0 +1,100 @@
+/**
+ * Pure geometry for the "fit bbox to layers / masks" header actions, mirroring
+ * legacy `CanvasBboxToolModule.fitToLayers` / `useAutoFitBBoxToMasks`:
+ *
+ * 1. Union the DOCUMENT-space bounds of the qualifying ENABLED, renderable,
+ *    non-empty layers (all layers for fit-to-layers; INPAINT masks only for
+ *    fit-to-masks — legacy fits `getVisibleRectOfType('inpaint_mask')`, so
+ *    regional-guidance masks are deliberately excluded).
+ * 2. For masks, expand the union outward by a fixed padding (legacy adds
+ *    `maskBlur + 8`; webv2 does not plumb the mask-blur param through the widget
+ *    yet, so a constant {@link MASK_FIT_PADDING} is used — see the report).
+ * 3. Snap the rect INWARD to the model bbox grid via {@link fitRectToGrid} so the
+ *    result lands on the same multiples a manual bbox edit snaps to.
+ *
+ * Returns `null` when there is nothing to fit (no qualifying content, or the
+ * snapped rect collapses to empty) so the caller can disable the button and never
+ * dispatch a degenerate bbox. React feeds the grid size from generate settings
+ * (`gridSizeForModelBase`), exactly like the bbox tool.
+ *
+ * Zero React, zero engine/DOM state — unit-tested in node.
+ */
+
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+
+import { getSourceBounds, isRenderableLayer } from '@workbench/canvas-engine/document/sources';
+import { isEmpty, union } from '@workbench/canvas-engine/math/rect';
+
+/** Fixed outward padding (document px) applied to the mask union before grid-fitting. */
+const MASK_FIT_PADDING = 8;
+
+/**
+ * Snaps a rect INWARD to `gridSize`: the top-left edges round up (toward the
+ * interior) and the width/height round down, so the result aligns to the grid and
+ * never exceeds the input rect. `gridSize <= 1` degrades to a plain integer round
+ * (no snapping — used when snap-to-grid is off). Mirrors legacy `fitRectToGrid`.
+ */
+export const fitRectToGrid = (rect: Rect, gridSize: number): Rect => {
+  const g = gridSize > 1 ? gridSize : 1;
+  const x = Math.ceil(rect.x / g) * g;
+  const y = Math.ceil(rect.y / g) * g;
+  const width = Math.floor((rect.width - (x - rect.x)) / g) * g;
+  const height = Math.floor((rect.height - (y - rect.y)) / g) * g;
+  return { height, width, x, y };
+};
+
+/**
+ * The union of the document-space bounds of every ENABLED, renderable layer whose
+ * content is non-empty and that satisfies `predicate`, or `null` when none
+ * qualify. Empty layers (a brand-new bitmap-less mask, an empty paint layer)
+ * contribute a zero-size rect and are skipped, matching legacy's `hasObjects()`
+ * gate.
+ */
+export const unionRenderableBounds = (
+  doc: CanvasDocumentContractV2,
+  predicate: (layer: CanvasLayerContract) => boolean
+): Rect | null => {
+  let bounds: Rect | null = null;
+  for (const layer of doc.layers) {
+    if (!isRenderableLayer(layer) || !predicate(layer)) {
+      continue;
+    }
+    const layerBounds = getSourceBounds(layer, doc);
+    if (isEmpty(layerBounds)) {
+      continue;
+    }
+    bounds = bounds ? union(bounds, layerBounds) : layerBounds;
+  }
+  return bounds;
+};
+
+/** The grid-snapped bbox that tightly fits all visible content, or `null` when there is none. */
+export const computeFitBboxToLayers = (doc: CanvasDocumentContractV2, gridSize: number): Rect | null => {
+  const bounds = unionRenderableBounds(doc, () => true);
+  if (!bounds) {
+    return null;
+  }
+  const fitted = fitRectToGrid(bounds, gridSize);
+  return isEmpty(fitted) ? null : fitted;
+};
+
+/** The padded, grid-snapped bbox that fits the visible INPAINT masks (legacy parity), or `null` when there are none. */
+export const computeFitBboxToMasks = (
+  doc: CanvasDocumentContractV2,
+  gridSize: number,
+  padding: number = MASK_FIT_PADDING
+): Rect | null => {
+  const bounds = unionRenderableBounds(doc, (layer) => layer.type === 'inpaint_mask');
+  if (!bounds) {
+    return null;
+  }
+  const expanded: Rect = {
+    height: bounds.height + padding * 2,
+    width: bounds.width + padding * 2,
+    x: bounds.x - padding,
+    y: bounds.y - padding,
+  };
+  const fitted = fitRectToGrid(expanded, gridSize);
+  return isEmpty(fitted) ? null : fitted;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/index.ts
new file mode 100644
index 00000000000..9dcadede163
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/index.ts
@@ -0,0 +1,19 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { WandSparklesIcon } from 'lucide-react';
+
+import { CanvasHeaderActions } from './CanvasHeaderActions';
+import { CanvasWidgetView } from './CanvasWidgetView';
+
+export const canvasWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['center'],
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  graphBearing: { defaultGraphId: 'canvas-graph', sourceId: 'canvas', surfaces: ['center'] },
+  headerActions: CanvasHeaderActions,
+  icon: WandSparklesIcon,
+  id: 'canvas',
+  label: (t) => t('widgets.labels.canvas'),
+  version: 1,
+  view: CanvasWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasCompositing.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasCompositing.test.ts
new file mode 100644
index 00000000000..0c77df6f97e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasCompositing.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_CANVAS_COMPOSITING, readCanvasCompositingSettings } from './canvasCompositing';
+
+describe('readCanvasCompositingSettings', () => {
+  it('returns legacy defaults for undefined values', () => {
+    expect(readCanvasCompositingSettings(undefined)).toEqual(DEFAULT_CANVAS_COMPOSITING);
+  });
+
+  it('mirrors the legacy params-slice defaults exactly', () => {
+    expect(DEFAULT_CANVAS_COMPOSITING).toEqual({
+      coherenceEdgeSize: 16,
+      coherenceMinDenoise: 0,
+      coherenceMode: 'Gaussian Blur',
+      infillColorValue: { a: 1, b: 0, g: 0, r: 0 },
+      infillMethod: 'lama',
+      infillPatchmatchDownscaleSize: 1,
+      infillTileSize: 32,
+      maskBlur: 16,
+    });
+  });
+
+  it('reads valid persisted values', () => {
+    const settings = readCanvasCompositingSettings({
+      coherenceEdgeSize: 32,
+      coherenceMinDenoise: 0.2,
+      coherenceMode: 'Box Blur',
+      infillMethod: 'patchmatch',
+      maskBlur: 8,
+    });
+    expect(settings.coherenceEdgeSize).toBe(32);
+    expect(settings.coherenceMinDenoise).toBe(0.2);
+    expect(settings.coherenceMode).toBe('Box Blur');
+    expect(settings.infillMethod).toBe('patchmatch');
+    expect(settings.maskBlur).toBe(8);
+  });
+
+  it('falls back to defaults for invalid enum values', () => {
+    const settings = readCanvasCompositingSettings({ coherenceMode: 'Wobble', infillMethod: 'magic' });
+    expect(settings.coherenceMode).toBe('Gaussian Blur');
+    expect(settings.infillMethod).toBe('lama');
+  });
+
+  it('clamps numeric ranges and rounds integers', () => {
+    const settings = readCanvasCompositingSettings({
+      coherenceEdgeSize: -5,
+      coherenceMinDenoise: 5,
+      maskBlur: 12.7,
+    });
+    expect(settings.coherenceEdgeSize).toBe(0);
+    expect(settings.coherenceMinDenoise).toBe(1);
+    expect(settings.maskBlur).toBe(13);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasCompositing.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasCompositing.ts
new file mode 100644
index 00000000000..63aba28df4b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasCompositing.ts
@@ -0,0 +1,133 @@
+/**
+ * Canvas compositing settings — the infill / coherence / mask-blur knobs a
+ * canvas inpaint or outpaint invoke exposes.
+ *
+ * Like {@link import('./canvasStrength').readCanvasDenoisingStrength}, these
+ * values are persisted per-project inside the canvas widget's own state values
+ * (`widgetInstances['canvas'].state.values`), so they survive reloads and ride
+ * along in queue snapshots. The generate widget's compositing section
+ * (`widgets/generate/GenerateCanvasCompositingSection`) reads/writes them, and
+ * `prepareCanvasInvocation` reads them back — defaulted + clamped — to thread
+ * into the pure graph compiler.
+ *
+ * Defaults mirror the legacy params slice (`features/controlLayers/store/types.ts`
+ * `getInitialParamsState`): infill `lama`, mask blur 16, coherence Gaussian Blur
+ * / edge 16 / min-denoise 0. Pure data + a reader; no React, no engine.
+ */
+
+/** The infill methods the outpaint graph can request (legacy `zInfillMethod`). */
+export type CanvasInfillMethod = 'patchmatch' | 'lama' | 'cv2' | 'color' | 'tile';
+
+/** The coherence-pass blur modes `create_gradient_mask` accepts (legacy `zParameterCanvasCoherenceMode`). */
+export type CanvasCoherenceMode = 'Gaussian Blur' | 'Box Blur' | 'Staged';
+
+/** An 8-bit RGBA color, mirroring legacy `infillColorValue` (a in 0..1). */
+export interface CanvasInfillColor {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/** The resolved compositing settings threaded into `compileCanvasGraph`. */
+export interface CanvasCompositingSettings {
+  infillMethod: CanvasInfillMethod;
+  infillTileSize: number;
+  infillPatchmatchDownscaleSize: number;
+  infillColorValue: CanvasInfillColor;
+  maskBlur: number;
+  coherenceMode: CanvasCoherenceMode;
+  coherenceMinDenoise: number;
+  coherenceEdgeSize: number;
+}
+
+/** Persisted keys inside the canvas widget's `state.values`. */
+export const CANVAS_COMPOSITING_KEYS = {
+  coherenceEdgeSize: 'coherenceEdgeSize',
+  coherenceMinDenoise: 'coherenceMinDenoise',
+  coherenceMode: 'coherenceMode',
+  infillColorValue: 'infillColorValue',
+  infillMethod: 'infillMethod',
+  infillPatchmatchDownscaleSize: 'infillPatchmatchDownscaleSize',
+  infillTileSize: 'infillTileSize',
+  maskBlur: 'maskBlur',
+} as const;
+
+/** Legacy-parity defaults (`getInitialParamsState`). */
+export const DEFAULT_CANVAS_COMPOSITING: CanvasCompositingSettings = {
+  coherenceEdgeSize: 16,
+  coherenceMinDenoise: 0,
+  coherenceMode: 'Gaussian Blur',
+  infillColorValue: { a: 1, b: 0, g: 0, r: 0 },
+  infillMethod: 'lama',
+  infillPatchmatchDownscaleSize: 1,
+  infillTileSize: 32,
+  maskBlur: 16,
+};
+
+/** Inclusive UI/value bounds for the numeric compositing knobs. */
+export const CANVAS_MASK_BLUR_MAX = 512;
+export const CANVAS_COHERENCE_EDGE_SIZE_MAX = 512;
+
+const INFILL_METHODS: ReadonlySet<CanvasInfillMethod> = new Set(['patchmatch', 'lama', 'cv2', 'color', 'tile']);
+const COHERENCE_MODES: ReadonlySet<CanvasCoherenceMode> = new Set(['Gaussian Blur', 'Box Blur', 'Staged']);
+
+export const isCanvasInfillMethod = (value: unknown): value is CanvasInfillMethod =>
+  typeof value === 'string' && INFILL_METHODS.has(value as CanvasInfillMethod);
+
+export const isCanvasCoherenceMode = (value: unknown): value is CanvasCoherenceMode =>
+  typeof value === 'string' && COHERENCE_MODES.has(value as CanvasCoherenceMode);
+
+const clampInt = (value: unknown, min: number, max: number, fallback: number): number =>
+  typeof value === 'number' && Number.isFinite(value) ? Math.min(max, Math.max(min, Math.round(value))) : fallback;
+
+const clampUnit = (value: unknown, fallback: number): number =>
+  typeof value === 'number' && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : fallback;
+
+const readInfillColor = (value: unknown): CanvasInfillColor => {
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const channel = (key: string, fallback: number) => clampInt(record[key], 0, 255, fallback);
+    return {
+      a: clampUnit(record.a, DEFAULT_CANVAS_COMPOSITING.infillColorValue.a),
+      b: channel('b', DEFAULT_CANVAS_COMPOSITING.infillColorValue.b),
+      g: channel('g', DEFAULT_CANVAS_COMPOSITING.infillColorValue.g),
+      r: channel('r', DEFAULT_CANVAS_COMPOSITING.infillColorValue.r),
+    };
+  }
+  return { ...DEFAULT_CANVAS_COMPOSITING.infillColorValue };
+};
+
+/**
+ * Reads the persisted canvas compositing settings from a widget's `state.values`,
+ * applying legacy defaults for any missing/invalid field and clamping to valid
+ * ranges. Always returns a fully-populated settings object.
+ */
+export const readCanvasCompositingSettings = (
+  values: Record<string, unknown> | undefined
+): CanvasCompositingSettings => {
+  const v = values ?? {};
+  const d = DEFAULT_CANVAS_COMPOSITING;
+  const coherenceMode = v[CANVAS_COMPOSITING_KEYS.coherenceMode];
+  const infillMethod = v[CANVAS_COMPOSITING_KEYS.infillMethod];
+  return {
+    coherenceEdgeSize: clampInt(
+      v[CANVAS_COMPOSITING_KEYS.coherenceEdgeSize],
+      0,
+      CANVAS_COHERENCE_EDGE_SIZE_MAX,
+      d.coherenceEdgeSize
+    ),
+    coherenceMinDenoise: clampUnit(v[CANVAS_COMPOSITING_KEYS.coherenceMinDenoise], d.coherenceMinDenoise),
+    coherenceMode: isCanvasCoherenceMode(coherenceMode) ? coherenceMode : d.coherenceMode,
+    infillColorValue: readInfillColor(v[CANVAS_COMPOSITING_KEYS.infillColorValue]),
+    infillMethod: isCanvasInfillMethod(infillMethod) ? infillMethod : d.infillMethod,
+    infillPatchmatchDownscaleSize: clampInt(
+      v[CANVAS_COMPOSITING_KEYS.infillPatchmatchDownscaleSize],
+      1,
+      10,
+      d.infillPatchmatchDownscaleSize
+    ),
+    infillTileSize: clampInt(v[CANVAS_COMPOSITING_KEYS.infillTileSize], 16, 256, d.infillTileSize),
+    maskBlur: clampInt(v[CANVAS_COMPOSITING_KEYS.maskBlur], 0, CANVAS_MASK_BLUR_MAX, d.maskBlur),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasStrength.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasStrength.ts
new file mode 100644
index 00000000000..b31698c9678
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/canvasStrength.ts
@@ -0,0 +1,39 @@
+/**
+ * Canvas denoising-strength: the single knob a canvas img2img invoke exposes.
+ *
+ * The value is persisted in the canvas widget's own state values
+ * (`widgetInstances['canvas'].state.values.denoisingStrength`) so it survives
+ * reloads and rides along in queue snapshots, and is read back — with the
+ * default applied — by the invoke orchestrator. Only consulted for img2img
+ * (txt2img ignores it), matching the graph compiler.
+ *
+ * Pure data + a reader; no React, no engine. Shared by the tool-options UI and
+ * `prepareCanvasInvocation` so the storage key and clamp stay in one place.
+ */
+
+/** The persisted key inside the canvas widget's `state.values`. */
+export const CANVAS_DENOISING_STRENGTH_KEY = 'denoisingStrength';
+
+/** Default strength when unset — a moderate img2img denoise (legacy parity). */
+export const DEFAULT_CANVAS_DENOISING_STRENGTH = 0.75;
+
+/** Inclusive slider/value bounds. */
+export const MIN_CANVAS_DENOISING_STRENGTH = 0.01;
+export const MAX_CANVAS_DENOISING_STRENGTH = 1;
+
+/** Clamps to `[MIN, MAX]`, snapping a non-finite value to the default. */
+export const clampCanvasDenoisingStrength = (value: number): number =>
+  Number.isFinite(value)
+    ? Math.min(MAX_CANVAS_DENOISING_STRENGTH, Math.max(MIN_CANVAS_DENOISING_STRENGTH, value))
+    : DEFAULT_CANVAS_DENOISING_STRENGTH;
+
+/**
+ * Reads the persisted canvas denoising strength from a widget's `state.values`,
+ * applying the default when unset and clamping to the valid range.
+ */
+export const readCanvasDenoisingStrength = (values: Record<string, unknown> | undefined): number => {
+  const raw = values?.[CANVAS_DENOISING_STRENGTH_KEY];
+  return typeof raw === 'number' && Number.isFinite(raw)
+    ? clampCanvasDenoisingStrength(raw)
+    : DEFAULT_CANVAS_DENOISING_STRENGTH;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/prepareCanvasInvocation.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/prepareCanvasInvocation.test.ts
new file mode 100644
index 00000000000..0e48fea1adb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/prepareCanvasInvocation.test.ts
@@ -0,0 +1,969 @@
+import type { CanvasRasterSnapshot } from '@workbench/canvas-engine/api';
+import type { CanvasImageUploadResult } from '@workbench/canvas-engine/document/imageUpload';
+import type { RasterSurface } from '@workbench/canvas-engine/render/raster';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type {
+  GenerateModelConfig,
+  GenerateReferenceImage,
+  GenerateReferenceImageAsset,
+  MainModelConfig,
+} from '@workbench/generation/types';
+import type {
+  CanvasDocumentContractV2,
+  CanvasControlLayerContract,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+  CanvasStateContractV2,
+  WorkbenchState,
+} from '@workbench/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import { createTestStubRasterBackend } from '@workbench/canvas-engine/render/raster.testStub';
+import { createCompositeDedupeCache } from '@workbench/canvas-operations/compositeForGeneration';
+import { getDefaultGenerateSettings } from '@workbench/generation/baseGenerationPolicies';
+import { createInitialWorkbenchState, workbenchReducer } from '@workbench/workbenchState';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RunCanvasInvocationDeps } from './prepareCanvasInvocation';
+
+import { DEFAULT_CANVAS_COMPOSITING } from './canvasCompositing';
+import { resolveRegionalReferenceImages, runCanvasInvocation } from './prepareCanvasInvocation';
+
+const sd1Model: MainModelConfig = { base: 'sd-1', key: 'sd1-model', name: 'SD 1.5', type: 'main' };
+const externalModel: GenerateModelConfig = {
+  base: 'external',
+  capabilities: { modes: ['txt2img'], supports_seed: true },
+  format: 'external_api',
+  key: 'external-model',
+  name: 'OpenAI Image',
+  provider_id: 'openai',
+  type: 'external_image_generator',
+};
+
+const generateValuesFor = (model: GenerateModelConfig): Record<string, unknown> => ({
+  ...getDefaultGenerateSettings(model),
+  model,
+  modelKey: model.key,
+  positivePrompt: 'a canvas prompt',
+  seed: 7,
+  shouldRandomizeSeed: false,
+});
+
+const rasterLayer = (id: string, size = 64): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: size, imageName: `${id}.png`, width: size }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const makeDoc = (layers: CanvasRasterLayerContractV2[], size = 64): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: size, width: size, x: 0, y: 0 },
+  height: size,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: size,
+});
+
+/** Uniform-alpha ImageData (255 = fully opaque → bboxFullyCovered true). */
+const uniformImageData = (width: number, height: number, alpha: number): ImageData => {
+  const data = new Uint8ClampedArray(Math.max(1, width) * Math.max(1, height) * 4);
+  for (let i = 3; i < data.length; i += 4) {
+    data[i] = alpha;
+  }
+  return { colorSpace: 'srgb', data, height, width } as unknown as ImageData;
+};
+
+interface Harness {
+  deps: RunCanvasInvocationDeps;
+  dispatch: ReturnType<typeof vi.fn>;
+  uploadImage: ReturnType<typeof vi.fn>;
+  flushPendingUploads: ReturnType<typeof vi.fn>;
+  events: string[];
+  surfaceIds: string[];
+  releaseRasterSnapshot: ReturnType<typeof vi.fn>;
+  submittedGraphs: () => Extract<WorkbenchAction, { type: 'submitCanvasInvocationSnapshot' }>[];
+  notices: () => { message?: string }[];
+}
+
+interface HarnessOptions {
+  document?: CanvasDocumentContractV2;
+  destination?: 'canvas' | 'gallery';
+  model?: GenerateModelConfig;
+  strength?: number;
+  alpha?: number;
+  inFlight?: Set<string>;
+  flushPendingUploads?: () => Promise<void>;
+  uploadImage?: (blob: Blob) => Promise<CanvasImageUploadResult>;
+  projectId?: string;
+  dispatch?: ReturnType<typeof vi.fn<(action: WorkbenchAction) => void>>;
+  models?: RunCanvasInvocationDeps['models'];
+}
+
+const makeHarness = (options: HarnessOptions = {}): Harness => {
+  const stub = createTestStubRasterBackend();
+  const events: string[] = [];
+  const surfaceIds: string[] = [];
+  const model = options.model ?? sd1Model;
+  const alpha = options.alpha ?? 255;
+
+  const backend = {
+    createSurface: (w: number, h: number): RasterSurface => stub.createSurface(w, h),
+    encodeSurface: (surface: RasterSurface): Promise<Blob> => stub.encodeSurface(surface),
+  };
+
+  const layerSurfaces = new Map<string, RasterSurface>();
+  const getLayerSurface = (layerId: string): Promise<{ surface: RasterSurface; rect: Rect }> => {
+    events.push('getLayerSurface');
+    surfaceIds.push(layerId);
+    let surface = layerSurfaces.get(layerId);
+    if (!surface) {
+      surface = stub.createSurface(64, 64);
+      layerSurfaces.set(layerId, surface);
+    }
+    // Content-sized: the layer's cache occupies its content rect (origin-anchored
+    // for these 64×64 image layers).
+    return Promise.resolve({ rect: { height: 64, width: 64, x: 0, y: 0 }, surface });
+  };
+
+  let counter = 0;
+  const uploadImage = vi.fn(
+    options.uploadImage ??
+      ((blob: Blob): Promise<CanvasImageUploadResult> => {
+        void blob;
+        events.push('upload');
+        counter += 1;
+        return Promise.resolve({ height: 64, imageName: `composite-${counter}.png`, width: 64 });
+      })
+  );
+
+  const flushPendingUploads = vi.fn(
+    options.flushPendingUploads ??
+      ((): Promise<void> =>
+        new Promise((resolve) => {
+          // Resolve on a microtask so a missing `await` would let compositing
+          // start first — the ordering assertion depends on this.
+          queueMicrotask(() => {
+            events.push('flush');
+            resolve();
+          });
+        }))
+  );
+
+  const dispatch = options.dispatch ?? vi.fn((_action: WorkbenchAction) => {});
+  const releaseRasterSnapshot = vi.fn();
+
+  const makeCanvas = (document: CanvasDocumentContractV2): CanvasStateContractV2 => ({
+    document: structuredClone(document),
+    documentRevision: 0,
+    snapshots: [],
+    stagingArea: {
+      areThumbnailsVisible: true,
+      autoSwitchMode: 'off',
+      isVisible: false,
+      pendingImageIds: [],
+      pendingImages: [],
+      selectedImageIndex: 0,
+    },
+    version: 2,
+  });
+
+  const deps: RunCanvasInvocationDeps = {
+    captureDocumentSnapshot: () => ({
+      canvas: makeCanvas(options.document ?? makeDoc([rasterLayer('layer-a')])),
+      documentGeneration: 0,
+    }),
+    captureRasterSnapshot: async (documentSnapshot, layerIds) => {
+      const layerSurfaces = new Map<string, { surface: RasterSurface; rect: Rect }>();
+      for (const layerId of layerIds) {
+        layerSurfaces.set(layerId, await getLayerSurface(layerId));
+      }
+      const snapshot: CanvasRasterSnapshot = {
+        ...documentSnapshot,
+        emptyLayerIds: new Set<string>(),
+        layerSurfaces,
+        release: releaseRasterSnapshot,
+      };
+      return { snapshot, status: 'ok' };
+    },
+    compositing: DEFAULT_CANVAS_COMPOSITING,
+    dedupe: createCompositeDedupeCache(),
+    destination: options.destination ?? 'canvas',
+    dispatch,
+    executorDeps: {
+      backend,
+      hashBlob: (blob: Blob) => blob.text(),
+      readImageData: (_surface, rect) => uniformImageData(rect.width, rect.height, alpha),
+      uploadImage: uploadImage as (blob: Blob) => Promise<CanvasImageUploadResult>,
+    },
+    flushPendingUploads: flushPendingUploads as () => Promise<void>,
+    generateValues: generateValuesFor(model),
+    inFlight: options.inFlight ?? new Set<string>(),
+    models: options.models,
+    projectId: options.projectId ?? 'project-1',
+    projectSettings: { useCpuNoise: true },
+    signal: new AbortController().signal,
+    strength: options.strength ?? 0.75,
+  };
+
+  const submittedGraphs = () =>
+    dispatch.mock.calls.map(([action]) => action).filter((action) => action.type === 'submitCanvasInvocationSnapshot');
+  const notices = () =>
+    dispatch.mock.calls.map(([action]) => action).filter((action) => action.type === 'recordNotice');
+
+  return {
+    deps,
+    dispatch,
+    events,
+    flushPendingUploads,
+    notices,
+    releaseRasterSnapshot,
+    submittedGraphs,
+    surfaceIds,
+    uploadImage,
+  };
+};
+
+const controlLayer = (
+  id: string,
+  overrides: Partial<CanvasControlLayerContract['adapter']> = {},
+  hasContent = true
+): CanvasControlLayerContract => ({
+  adapter: {
+    beginEndStepPct: [0, 1],
+    controlMode: 'balanced',
+    kind: 'controlnet',
+    model: null,
+    weight: 0.75,
+    ...overrides,
+  },
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: hasContent
+    ? { image: { height: 64, imageName: `${id}.png`, width: 64 }, type: 'image' }
+    : { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: true,
+});
+
+describe('runCanvasInvocation', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('generates txt2img without any composite upload when content does not overlap the bbox', async () => {
+    // Empty document → no raster content → txt2img, no executor work.
+    const harness = makeHarness({ document: makeDoc([]) });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.uploadImage).not.toHaveBeenCalled();
+    expect(harness.events).not.toContain('getLayerSurface');
+
+    const submitted = harness.submittedGraphs();
+    expect(submitted).toHaveLength(1);
+    expect(submitted[0]?.graph.label).toBe('SD 1.5 txt2img');
+    // Pure txt2img graph has no image-to-latents encode node.
+    expect(submitted[0]!.graph.backendGraph!.nodes.canvas_i2l).toBeUndefined();
+    expect(harness.notices()).toHaveLength(0);
+  });
+
+  it('generates img2img with the composite reference and the strength-derived denoising_start', async () => {
+    const harness = makeHarness({ strength: 0.75 });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.uploadImage).toHaveBeenCalledTimes(1);
+
+    const submitted = harness.submittedGraphs();
+    expect(submitted).toHaveLength(1);
+    expect(submitted[0]?.graph.label).toBe('SD 1.5 img2img');
+
+    const nodes = submitted[0]!.graph.backendGraph!.nodes;
+    const encode = Object.values(nodes).find((node: any) => node.type === 'i2l') as any;
+    expect(encode?.image).toEqual({ image_name: 'composite-1.png' });
+    // sd-1 is linear: denoising_start = 1 - 0.75.
+    expect(nodes.denoise_latents.denoising_start).toBeCloseTo(0.25, 10);
+    expect(harness.notices()).toHaveLength(0);
+  });
+
+  it('dispatches resolved prompt and seed metadata with the compiled canvas graph', async () => {
+    const harness = makeHarness();
+    harness.deps.generateValues = {
+      ...harness.deps.generateValues,
+      negativePrompt: 'low quality',
+      positivePrompt: 'a resolved canvas prompt',
+      seed: 123,
+      shouldRandomizeSeed: false,
+    };
+
+    await runCanvasInvocation(harness.deps);
+
+    const submitted = harness.submittedGraphs();
+    expect(submitted).toHaveLength(1);
+    expect(submitted[0]?.generate).toMatchObject({
+      negativePromptNodeId: 'negative_prompt',
+      positivePromptNodeId: 'positive_prompt',
+      seedNodeId: 'seed',
+      values: {
+        negativePrompt: 'low quality',
+        positivePrompt: 'a resolved canvas prompt',
+        seed: 123,
+        shouldRandomizeSeed: false,
+      },
+    });
+  });
+
+  it('threads a Gallery destination through to the snapshot and a durable (non-intermediate) output', async () => {
+    // Empty document → txt2img, so no composite upload noise; we only care about
+    // the destination + is_intermediate wiring.
+    const harness = makeHarness({ destination: 'gallery', document: makeDoc([]) });
+
+    await runCanvasInvocation(harness.deps);
+
+    const submitted = harness.submittedGraphs();
+    expect(submitted).toHaveLength(1);
+    expect(submitted[0]?.destination).toBe('gallery');
+    // A Gallery destination must produce a durable image, not a staging intermediate.
+    expect(submitted[0]!.graph.backendGraph!.nodes.canvas_output!.is_intermediate).toBe(false);
+  });
+
+  it('marks the output intermediate for a Canvas destination (staging)', async () => {
+    const harness = makeHarness({ destination: 'canvas', document: makeDoc([]) });
+
+    await runCanvasInvocation(harness.deps);
+
+    const submitted = harness.submittedGraphs();
+    expect(submitted).toHaveLength(1);
+    expect(submitted[0]?.destination).toBe('canvas');
+    expect(submitted[0]!.graph.backendGraph!.nodes.canvas_output!.is_intermediate).toBe(true);
+  });
+
+  it('awaits the upload flush before compositing', async () => {
+    const harness = makeHarness();
+
+    await runCanvasInvocation(harness.deps);
+
+    // Flush must settle before any layer is rasterized/uploaded.
+    expect(harness.events[0]).toBe('flush');
+    expect(harness.events.indexOf('flush')).toBeLessThan(harness.events.indexOf('getLayerSurface'));
+    expect(harness.events.indexOf('flush')).toBeLessThan(harness.events.indexOf('upload'));
+  });
+
+  it('aborts with a visible notice when pending paint persistence fails', async () => {
+    const harness = makeHarness({
+      flushPendingUploads: () => Promise.reject(new Error('Canvas pixel persistence failed for 1 layer.')),
+    });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.notices()).toEqual([
+      expect.objectContaining({ message: 'Canvas pixel persistence failed for 1 layer.' }),
+    ]);
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    expect(harness.uploadImage).not.toHaveBeenCalled();
+  });
+
+  it('plans from the POST-flush document (re-reads getDocument after the flush barrier)', async () => {
+    // The flush dispatches `updateCanvasLayerSource` for just-persisted paint
+    // layers, so the pre-flush snapshot references stale/empty sources. The
+    // orchestrator must re-read the document after the flush and composite from
+    // it — otherwise the stale refs build wrong dedupe keys and the empty-paint
+    // filter reads a `null` bitmap that the flush already replaced.
+    const preDoc = makeDoc([rasterLayer('pre')]);
+    const postDoc = makeDoc([rasterLayer('post')]);
+    let flushed = false;
+    const harness = makeHarness({
+      flushPendingUploads: () =>
+        new Promise((resolve) => {
+          queueMicrotask(() => {
+            flushed = true;
+            resolve();
+          });
+        }),
+    });
+    // Return the stale doc until the flush resolves, the fresh doc afterwards.
+    harness.deps.captureDocumentSnapshot = () => ({
+      canvas: {
+        document: structuredClone(flushed ? postDoc : preDoc),
+        documentRevision: 0,
+        snapshots: [],
+        stagingArea: {
+          areThumbnailsVisible: true,
+          autoSwitchMode: 'off',
+          isVisible: false,
+          pendingImageIds: [],
+          pendingImages: [],
+          selectedImageIndex: 0,
+        },
+        version: 2,
+      },
+      documentGeneration: 0,
+    });
+
+    await runCanvasInvocation(harness.deps);
+
+    // The composite rasterized the post-flush layer, never the stale pre-flush one.
+    expect(harness.surfaceIds).toContain('post');
+    expect(harness.surfaceIds).not.toContain('pre');
+  });
+
+  it('does not submit or publish dedupe entries when the document becomes stale during raster detachment', async () => {
+    const harness = makeHarness();
+    const snapshot = {
+      canvas: {
+        document: makeDoc([rasterLayer('layer-a')]),
+        documentRevision: 0,
+        snapshots: [],
+        stagingArea: {
+          areThumbnailsVisible: true,
+          autoSwitchMode: 'off' as const,
+          isVisible: false,
+          pendingImageIds: [],
+          pendingImages: [],
+          selectedImageIndex: 0,
+        },
+        version: 2 as const,
+      },
+      documentGeneration: 0,
+    };
+    Object.assign(harness.deps, {
+      captureDocumentSnapshot: vi.fn(() => snapshot),
+      captureRasterSnapshot: vi.fn(() => Promise.resolve({ status: 'stale' as const })),
+    });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    expect(harness.notices()).toHaveLength(1);
+    expect(harness.deps.dedupe.byKey).toHaveLength(0);
+    expect(harness.deps.dedupe.byHash).toHaveLength(0);
+  });
+
+  it.each(['aborted', 'not-ready', 'over-budget'] as const)(
+    'does not submit when raster capture returns the typed %s outcome',
+    async (status) => {
+      const harness = makeHarness();
+      harness.deps.captureRasterSnapshot = vi.fn(() => Promise.resolve({ status }));
+
+      await runCanvasInvocation(harness.deps);
+
+      expect(harness.submittedGraphs()).toHaveLength(0);
+      expect(harness.notices()).toHaveLength(1);
+      expect(harness.deps.dedupe.byKey).toHaveLength(0);
+      expect(harness.deps.dedupe.byHash).toHaveLength(0);
+    }
+  );
+
+  it('passes the orchestration AbortSignal into raster snapshot capture', async () => {
+    const harness = makeHarness();
+    const controller = new AbortController();
+    const captureRasterSnapshot = vi.fn(() => Promise.resolve({ status: 'aborted' as const }));
+    Object.assign(harness.deps, { captureRasterSnapshot, signal: controller.signal });
+    controller.abort(new DOMException('invoke cancelled', 'AbortError'));
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(captureRasterSnapshot).toHaveBeenCalledWith(
+      expect.any(Object),
+      ['layer-a'],
+      expect.objectContaining({ signal: controller.signal })
+    );
+    expect(harness.submittedGraphs()).toHaveLength(0);
+  });
+
+  it('uses the frozen canvas and detached pixels after edits at composite, upload, and queue-dispatch boundaries', async () => {
+    let liveDocument = makeDoc([rasterLayer('frozen-layer')], 96);
+    liveDocument.bbox = { height: 64, width: 64, x: 7, y: 11 };
+    const dispatch = vi.fn((_action: WorkbenchAction) => {
+      liveDocument = { ...liveDocument, bbox: { height: 96, width: 96, x: 303, y: 404 } };
+    });
+    const harness = makeHarness({ dispatch, document: liveDocument });
+    harness.deps.captureDocumentSnapshot = () => ({
+      canvas: {
+        document: structuredClone(liveDocument),
+        documentRevision: 4,
+        snapshots: [],
+        stagingArea: {
+          areThumbnailsVisible: true,
+          autoSwitchMode: 'off',
+          isVisible: false,
+          pendingImageIds: [],
+          pendingImages: [],
+          selectedImageIndex: 0,
+        },
+        version: 2,
+      },
+      documentGeneration: 9,
+    });
+    const captureRasterSnapshot = harness.deps.captureRasterSnapshot;
+    harness.deps.captureRasterSnapshot = async (snapshot, layerIds) => {
+      const result = await captureRasterSnapshot(snapshot, layerIds, { signal: harness.deps.signal });
+      // The transaction is fully detached at this boundary. Subsequent edits
+      // must not alter any composite/upload/compile/dispatch input.
+      liveDocument = {
+        ...liveDocument,
+        bbox: { height: 64, width: 64, x: 101, y: 202 },
+        layers: [rasterLayer('replacement-layer')],
+      };
+      return result;
+    };
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.surfaceIds).toEqual(['frozen-layer']);
+    expect(harness.notices()).toEqual([]);
+    expect(harness.submittedGraphs()).toHaveLength(1);
+    expect(harness.submittedGraphs()[0]?.canvas.document.bbox).toEqual({ height: 64, width: 64, x: 7, y: 11 });
+    expect(harness.submittedGraphs()[0]?.canvas.document.layers[0]?.id).toBe('frozen-layer');
+    expect(harness.releaseRasterSnapshot).toHaveBeenCalledTimes(1);
+    expect(harness.deps.dedupe.byKey.size).toBeGreaterThan(0);
+  });
+
+  it.each(['coverage-scan', 'encode', 'upload'] as const)(
+    'keeps the frozen transaction when the live bbox changes at the %s boundary',
+    async (boundary) => {
+      let liveDocument = makeDoc([rasterLayer('layer-a')]);
+      const harness = makeHarness({ document: liveDocument });
+      harness.deps.captureDocumentSnapshot = () => ({
+        canvas: {
+          document: structuredClone(liveDocument),
+          documentRevision: 2,
+          snapshots: [],
+          stagingArea: {
+            areThumbnailsVisible: true,
+            autoSwitchMode: 'off',
+            isVisible: false,
+            pendingImageIds: [],
+            pendingImages: [],
+            selectedImageIndex: 0,
+          },
+          version: 2,
+        },
+        documentGeneration: 3,
+      });
+      const editLiveBbox = (): void => {
+        liveDocument = { ...liveDocument, bbox: { height: 64, width: 64, x: 88, y: 99 } };
+      };
+      if (boundary === 'coverage-scan') {
+        const readImageData = harness.deps.executorDeps.readImageData!;
+        harness.deps.executorDeps.readImageData = (...args) => {
+          editLiveBbox();
+          return readImageData(...args);
+        };
+      } else if (boundary === 'encode') {
+        const encodeSurface = harness.deps.executorDeps.backend.encodeSurface;
+        harness.deps.executorDeps.backend.encodeSurface = (...args) => {
+          editLiveBbox();
+          return encodeSurface(...args);
+        };
+      } else {
+        const uploadImage = harness.deps.executorDeps.uploadImage;
+        harness.deps.executorDeps.uploadImage = (...args) => {
+          editLiveBbox();
+          return uploadImage(...args);
+        };
+      }
+
+      await runCanvasInvocation(harness.deps);
+
+      expect(harness.submittedGraphs()).toHaveLength(1);
+      expect(harness.submittedGraphs()[0]?.canvas.document.bbox).toEqual({ height: 64, width: 64, x: 0, y: 0 });
+      expect(harness.releaseRasterSnapshot).toHaveBeenCalledTimes(1);
+    }
+  );
+
+  it('records a notice and dispatches no snapshot when the graph fails validation', async () => {
+    // External image generators are rejected by the graph compiler.
+    const harness = makeHarness({ document: makeDoc([]), model: externalModel });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    const notices = harness.notices();
+    expect(notices).toHaveLength(1);
+    expect(notices[0]?.message).toContain('does not support canvas generation');
+    expect(harness.deps.dedupe.byKey).toHaveLength(0);
+    expect(harness.deps.dedupe.byHash).toHaveLength(0);
+    expect(harness.releaseRasterSnapshot).toHaveBeenCalledTimes(1);
+  });
+
+  it('records a notice and dispatches no snapshot when the composite upload fails', async () => {
+    const uploadImage = vi.fn(() => Promise.reject(new Error('upload exploded')));
+    const harness = makeHarness({ uploadImage });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    const notices = harness.notices();
+    expect(notices).toHaveLength(1);
+    expect(notices[0]?.message).toBe('upload exploded');
+    expect(harness.deps.dedupe.byKey).toHaveLength(0);
+    expect(harness.deps.dedupe.byHash).toHaveLength(0);
+    expect(harness.releaseRasterSnapshot).toHaveBeenCalledTimes(1);
+  });
+
+  it('blocks invocation with the shared reason code when a nonempty control layer has no model', async () => {
+    const harness = makeHarness({ document: docWithLayers([controlLayer('control')]) });
+    await runCanvasInvocation(harness.deps);
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    expect(harness.notices()).toHaveLength(1);
+    expect(harness.notices()[0]?.message).toContain('missing_model');
+  });
+
+  it('blocks invocation when a nonempty control layer has malformed numeric settings', async () => {
+    const model = {
+      base: 'sd-1',
+      file_size: 1,
+      format: 'checkpoint',
+      hash: 'hash',
+      key: 'controlnet',
+      name: 'ControlNet',
+      path: 'controlnet',
+      source: 'controlnet',
+      source_type: 'path' as const,
+      type: 'controlnet',
+    };
+    const harness = makeHarness({
+      document: docWithLayers([controlLayer('control', { model: model.key, weight: Number.NaN })]),
+      models: [model],
+    });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    expect(harness.notices()[0]?.message).toContain('invalid_adapter_values');
+  });
+
+  it('ignores an empty control layer with no model', async () => {
+    const harness = makeHarness({ document: docWithLayers([controlLayer('control', {}, false)]) });
+    await runCanvasInvocation(harness.deps);
+    expect(harness.submittedGraphs()).toHaveLength(1);
+    expect(harness.notices()).toHaveLength(0);
+  });
+
+  it('ignores a disabled nonempty control layer with no model', async () => {
+    const disabled = { ...controlLayer('control'), isEnabled: false };
+    const harness = makeHarness({ document: docWithLayers([disabled]) });
+    await runCanvasInvocation(harness.deps);
+    expect(harness.submittedGraphs()).toHaveLength(1);
+    expect(harness.notices()).toHaveLength(0);
+    expect(harness.surfaceIds).toEqual([]);
+  });
+
+  it('blocks the second enabled nonempty Control LoRA', async () => {
+    const model = {
+      base: 'flux',
+      file_size: 1,
+      format: 'checkpoint',
+      hash: 'hash',
+      key: 'control-lora',
+      name: 'Control LoRA',
+      path: 'control-lora',
+      source: 'control-lora',
+      source_type: 'path' as const,
+      type: 'control_lora',
+    };
+    const flux = { ...sd1Model, base: 'flux' as const, key: 'flux', name: 'FLUX' };
+    const harness = makeHarness({
+      document: docWithLayers([
+        controlLayer('first', { kind: 'control_lora', model: model.key }),
+        controlLayer('second', { kind: 'control_lora', model: model.key }),
+      ]),
+      model: flux,
+      models: [model],
+    });
+    await runCanvasInvocation(harness.deps);
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    expect(harness.notices()[0]?.message).toContain('control_lora_limit');
+  });
+
+  it('prepares a Z-Image control with exact adapter and model configuration', async () => {
+    const zImage = {
+      ...sd1Model,
+      base: 'z-image' as const,
+      format: 'diffusers' as const,
+      key: 'z-image',
+      name: 'Z-Image',
+    };
+    const controlModel = {
+      base: 'z-image',
+      file_size: 1,
+      format: 'checkpoint',
+      hash: 'z-control-hash',
+      key: 'z-control',
+      name: 'Z Control',
+      path: 'z-control',
+      source: 'z-control',
+      source_type: 'path' as const,
+      type: 'controlnet',
+    };
+    const harness = makeHarness({
+      document: docWithLayers([
+        controlLayer('z-layer', {
+          beginEndStepPct: [0.15, 0.85],
+          controlMode: null,
+          kind: 'z_image_control',
+          model: controlModel.key,
+          weight: 0.7,
+        }),
+      ]),
+      model: zImage,
+      models: [controlModel],
+    });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.notices()).toHaveLength(0);
+    const node = harness.submittedGraphs()[0]?.graph.backendGraph?.nodes['z_image_control_z-layer'];
+    expect(node).toMatchObject({
+      begin_step_percent: 0.15,
+      control_context_scale: 0.7,
+      control_model: {
+        base: 'z-image',
+        hash: 'z-control-hash',
+        key: 'z-control',
+        name: 'Z Control',
+        type: 'controlnet',
+      },
+      end_step_percent: 0.85,
+      type: 'z_image_control',
+    });
+    expect(harness.surfaceIds).toEqual(['z-layer']);
+  });
+
+  it('blocks a second enabled nonempty Z-Image control', async () => {
+    const zImage = {
+      ...sd1Model,
+      base: 'z-image' as const,
+      format: 'diffusers' as const,
+      key: 'z-image',
+      name: 'Z-Image',
+    };
+    const controlModel = {
+      base: 'z-image',
+      file_size: 1,
+      format: 'checkpoint',
+      hash: 'hash',
+      key: 'z-control',
+      name: 'Z Control',
+      path: 'z-control',
+      source: 'z-control',
+      source_type: 'path' as const,
+      type: 'controlnet',
+    };
+    const harness = makeHarness({
+      document: docWithLayers([
+        controlLayer('first', { kind: 'z_image_control', model: controlModel.key }),
+        controlLayer('second', { kind: 'z_image_control', model: controlModel.key }),
+      ]),
+      model: zImage,
+      models: [controlModel],
+    });
+
+    await runCanvasInvocation(harness.deps);
+
+    expect(harness.submittedGraphs()).toHaveLength(0);
+    expect(harness.notices()[0]?.message).toContain('z_image_control_limit');
+  });
+
+  it('ignores a concurrent invoke while a prior prepare for the same project is in flight', async () => {
+    const inFlight = new Set<string>();
+    let releaseFlush = (): void => {};
+    const gatedFlush = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          releaseFlush = resolve;
+        })
+    );
+
+    const first = makeHarness({ flushPendingUploads: gatedFlush, inFlight });
+    // Kick off the first invoke; it parks on the gated flush.
+    const firstRun = runCanvasInvocation(first.deps);
+    await Promise.resolve();
+
+    // A second invoke for the same project (shares the in-flight set) is dropped.
+    const second = makeHarness({ inFlight });
+    await runCanvasInvocation(second.deps);
+
+    expect(second.submittedGraphs()).toHaveLength(0);
+    expect(second.notices()).toHaveLength(0);
+    expect(second.uploadImage).not.toHaveBeenCalled();
+
+    // Let the first invoke finish; it still submits exactly once.
+    releaseFlush();
+    await firstRun;
+    expect(first.submittedGraphs()).toHaveLength(1);
+  });
+
+  it('enqueues into the originating project, not the active one, when the active project changes mid-flight', async () => {
+    // Two real projects, driven through the real reducer, so we can tell
+    // "landed in project A" apart from "landed in project B".
+    let state: WorkbenchState = createInitialWorkbenchState();
+    const originatingProjectId = state.activeProjectId;
+    state = workbenchReducer(state, { type: 'createProject' });
+    const otherProjectId = state.activeProjectId;
+    expect(otherProjectId).not.toBe(originatingProjectId);
+
+    let releaseFlush = (): void => {};
+    const gatedFlush = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          releaseFlush = resolve;
+        })
+    );
+    const dispatch = vi.fn((action: WorkbenchAction) => {
+      state = workbenchReducer(state, action);
+    });
+
+    // The invoke is prepared while `originatingProjectId` is active...
+    const harness = makeHarness({ dispatch, flushPendingUploads: gatedFlush, projectId: originatingProjectId });
+    const invokePromise = runCanvasInvocation(harness.deps);
+    await Promise.resolve();
+
+    // ...but by the time the flush/composite/compile settles, the user has
+    // switched to another project.
+    expect(state.activeProjectId).toBe(otherProjectId);
+
+    releaseFlush();
+    await invokePromise;
+
+    const originatingProject = state.projects.find((project) => project.id === originatingProjectId);
+    const otherProject = state.projects.find((project) => project.id === otherProjectId);
+
+    expect(originatingProject?.queue.items).toHaveLength(1);
+    expect(originatingProject?.queue.items[0]?.snapshot.sourceId).toBe('canvas');
+    expect(otherProject?.queue.items).toHaveLength(0);
+  });
+});
+
+// ---- Inpaint / outpaint mode dispatch -------------------------------------
+
+const inpaintMaskLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: { height: 64, imageName: `${id}-bmp`, width: 64 }, fill: { color: '#ff0000', style: 'solid' } },
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+const docWithLayers = (layers: CanvasLayerContract[], size = 64): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: size, width: size, x: 0, y: 0 },
+  height: size,
+  layers,
+  selectedLayerId: null,
+  version: 2,
+  width: size,
+});
+
+describe('runCanvasInvocation — inpaint / outpaint dispatch', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('dispatches an inpaint graph when content covers the bbox and a mask has content', async () => {
+    const doc = docWithLayers([rasterLayer('base'), inpaintMaskLayer('mask')]);
+    const harness = makeHarness({ document: doc, alpha: 255 });
+
+    await runCanvasInvocation(harness.deps);
+
+    const submitted = harness.submittedGraphs();
+    expect(submitted).toHaveLength(1);
+    expect(submitted[0]?.graph.label).toBe('SD 1.5 inpaint');
+    const nodes = submitted[0]!.graph.backendGraph!.nodes;
+    expect(nodes.create_gradient_mask?.type).toBe('create_gradient_mask');
+    expect(nodes.canvas_output?.type).toBe('invokeai_img_blend');
+    // The gradient mask consumes the uploaded grayscale mask (base upload is composite-1).
+    expect((nodes.create_gradient_mask?.mask as { image_name?: string } | undefined)?.image_name).toBeDefined();
+    expect(harness.notices()).toHaveLength(0);
+    // The mask layer was rasterized for the grayscale composite.
+    expect(harness.surfaceIds).toEqual(['base', 'mask']);
+  });
+
+  it('dispatches an outpaint graph when content only partially covers the bbox', async () => {
+    // Partial alpha → bboxFullyCovered false → outpaint.
+    const harness = makeHarness({ document: makeDoc([rasterLayer('base')]), alpha: 200 });
+
+    await runCanvasInvocation(harness.deps);
+
+    const submitted = harness.submittedGraphs();
+    expect(submitted).toHaveLength(1);
+    expect(submitted[0]?.graph.label).toBe('SD 1.5 outpaint');
+    const nodes = submitted[0]!.graph.backendGraph!.nodes;
+    expect(nodes.infill?.type).toBe('infill_lama');
+    expect(nodes.image_alpha_to_mask?.type).toBe('tomask');
+    expect(nodes.canvas_output?.type).toBe('invokeai_img_blend');
+    expect(harness.notices()).toHaveLength(0);
+  });
+});
+
+// Task 39, finding 1: a regional reference image is only usable once an image is
+// assigned (the settings UI now wires drop/upload → config.image). This guards
+// the resolver seam: refs without an image are dropped; refs with an image + a
+// compatible model survive into the graph inputs.
+describe('resolveRegionalReferenceImages', () => {
+  const asset = { imageName: 'ref.png' } as GenerateReferenceImageAsset;
+  const ipAdapterModel = { base: 'sd-1', key: 'ipa', name: 'IP Adapter', type: 'ip_adapter' };
+  const fluxReduxModel = { base: 'flux', key: 'redux', name: 'FLUX Redux', type: 'flux_redux' };
+
+  const ipAdapterRef = (image: GenerateReferenceImageAsset | null): GenerateReferenceImage => ({
+    config: {
+      beginEndStepPct: [0, 1],
+      clipVisionModel: 'ViT-H',
+      image,
+      method: 'full',
+      model: ipAdapterModel,
+      type: 'ip_adapter',
+      weight: 1,
+    },
+    id: 'ref-ipa',
+    isEnabled: true,
+  });
+
+  const fluxReduxRef = (image: GenerateReferenceImageAsset | null): GenerateReferenceImage => ({
+    config: { image, imageInfluence: 'highest', model: fluxReduxModel, type: 'flux_redux' },
+    id: 'ref-redux',
+    isEnabled: true,
+  });
+
+  it('drops an IP-Adapter ref with no image assigned', () => {
+    expect(resolveRegionalReferenceImages({ referenceImages: [ipAdapterRef(null)] }, 'sd-1')).toEqual([]);
+  });
+
+  it('keeps an IP-Adapter ref once an image is assigned (non-FLUX base)', () => {
+    const inputs = resolveRegionalReferenceImages({ referenceImages: [ipAdapterRef(asset)] }, 'sd-1');
+    expect(inputs).toHaveLength(1);
+    expect(inputs[0]).toMatchObject({ id: 'ref-ipa', imageName: 'ref.png', type: 'ip_adapter' });
+  });
+
+  it('drops a FLUX Redux ref with no image assigned', () => {
+    expect(resolveRegionalReferenceImages({ referenceImages: [fluxReduxRef(null)] }, 'flux')).toEqual([]);
+  });
+
+  it('keeps a FLUX Redux ref once an image is assigned (FLUX base)', () => {
+    const inputs = resolveRegionalReferenceImages({ referenceImages: [fluxReduxRef(asset)] }, 'flux');
+    expect(inputs).toHaveLength(1);
+    expect(inputs[0]).toMatchObject({ id: 'ref-redux', imageName: 'ref.png', type: 'flux_redux' });
+  });
+
+  it('drops a disabled ref even when an image is assigned', () => {
+    const disabled = { ...ipAdapterRef(asset), isEnabled: false };
+    expect(resolveRegionalReferenceImages({ referenceImages: [disabled] }, 'sd-1')).toEqual([]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/prepareCanvasInvocation.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/prepareCanvasInvocation.ts
new file mode 100644
index 00000000000..2ba2cefa7b5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/invoke/prepareCanvasInvocation.ts
@@ -0,0 +1,607 @@
+/**
+ * Wires the canvas-generation pipeline into the Invoke button.
+ *
+ * `prepareCanvasInvocation` is the thin command-layer entry: it resolves the
+ * active project's engine, scopes a per-engine dedupe cache, and delegates to
+ * the React-free {@link runCanvasInvocation} orchestrator. The orchestrator runs
+ * the whole flush → composite → mode-detect → compile → enqueue flow with every
+ * side-effecting dependency injected, so it is fully node-testable with fakes.
+ *
+ * ## Flow (per the plan)
+ * 1. Resolve the engine + its live document (no engine/document → notice, abort).
+ * 2. `flushPendingUploads()` — the paint-bitmap persistence barrier — so the
+ *    composite reads the latest painted pixels.
+ * 3. Plan the composites, then run a **bounds-only pre-pass**: if enabled raster
+ *    content does not overlap the bbox, the mode is txt2img regardless of
+ *    coverage, so we skip the composite/encode/upload entirely (no useless base
+ *    image). Only when content overlaps do we run the executor (which the
+ *    image-referencing modes need) and detect img2img/outpaint from coverage.
+ * 4. Compile the base-appropriate graph and dispatch it to canvas staging.
+ * 5. Any failure (validation throw, upload error, unsupported mode) records a
+ *    notice — the app never gets stuck.
+ *
+ * A module-scoped in-flight guard drops an invoke while a prior prepare for the
+ * same project is still running (the Invoke hotkey can be mashed).
+ */
+
+import type {
+  CanvasDocumentSnapshot,
+  CanvasDocumentCapability,
+  CanvasExportCapability,
+  CanvasLifecycleCapability,
+  CaptureRasterSnapshotResult,
+} from '@workbench/canvas-engine/api';
+import type {
+  CompositeDedupeCache,
+  ExecuteCompositePlanDeps,
+} from '@workbench/canvas-operations/compositeForGeneration';
+import type { ControlLayerGraphInput } from '@workbench/generation/canvas/addControlLayers';
+import type {
+  RegionalGuidanceInput,
+  RegionalReferenceImageInput,
+} from '@workbench/generation/canvas/addRegionalGuidance';
+import type { CanvasCompileMode } from '@workbench/generation/canvas/types';
+import type { GenerateModelConfig, GenerateReferenceImage } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type {
+  CanvasDocumentContractV2,
+  ProjectSettings,
+  ResultDestination,
+  WorkbenchNotificationKind,
+} from '@workbench/types';
+import type { CanvasCompositingSettings } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import {
+  computeCompositeContentBounds,
+  executeCompositePlan,
+  executeControlComposite,
+  executeMaskComposite,
+  executeRegionalMaskComposite,
+} from '@workbench/canvas-operations/compositeForGeneration';
+import { getEngine } from '@workbench/canvas-operations/engineRegistry';
+import {
+  getRegionalGuidanceRejectionReason,
+  isRegionalGuidanceSupportedForBase,
+} from '@workbench/generation/canvas/addRegionalGuidance';
+import { detectCanvasMode, rectsIntersect } from '@workbench/generation/canvas/canvasMode';
+import { compileCanvasGraph } from '@workbench/generation/canvas/compileCanvasGraph';
+import {
+  planComposites,
+  planControlComposites,
+  planRegionalMaskComposites,
+} from '@workbench/generation/canvas/compositePlan';
+import { getControlValidationReason } from '@workbench/generation/canvas/controlValidation';
+import { resolveGenerateSeed } from '@workbench/generation/graph';
+import { normalizeGenerateWidgetValues, syncGenerateWidgetValuesWithModels } from '@workbench/generation/settings';
+import { DEFAULT_CANVAS_COMPOSITING } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+
+/** Title on every canvas-invoke failure notice. */
+export const CANVAS_INVOKE_ERROR_TITLE = 'Canvas generation failed';
+
+/** Engine-backed executor deps, minus the caller-owned dedupe cache. */
+type CompositeExecutorDeps = Omit<ExecuteCompositePlanDeps, 'dedupe' | 'getLayerSurface'>;
+
+/** Injected dependencies for the React-free orchestrator. */
+export interface RunCanvasInvocationDeps {
+  /** The active project id (also the in-flight guard key). */
+  projectId: string;
+  /**
+   * The resolved result destination. Drives the compiled output node's
+   * `is_intermediate` flag (`destination === 'canvas'`) and the enqueued
+   * snapshot's destination, so a Canvas source can target the Gallery.
+   */
+  destination: ResultDestination;
+  /** Captures the exact post-flush canvas contract used by immutable invocation transactions. */
+  captureDocumentSnapshot: () => CanvasDocumentSnapshot | null;
+  /** Detaches every layer surface required by the transaction's complete composite plan. */
+  captureRasterSnapshot: (
+    snapshot: CanvasDocumentSnapshot,
+    layerIds: readonly string[],
+    options: { signal: AbortSignal }
+  ) => Promise<CaptureRasterSnapshotResult>;
+  /** Cancels cache preparation and detachment for this invocation transaction. */
+  signal: AbortSignal;
+  /** Paint-bitmap persistence barrier, awaited before compositing. */
+  flushPendingUploads: () => Promise<void>;
+  /** Engine-backed composite executor deps (backend + rasterize-or-throw + uploader). */
+  executorDeps: CompositeExecutorDeps;
+  /** Per-engine dedupe cache (caller-owned; persists across invokes, size-capped). */
+  dedupe: CompositeDedupeCache;
+  /** Project ids with a prepare currently in flight (module/registry-scoped). */
+  inFlight: Set<string>;
+  /** The generate widget's raw persisted values (model/prompt/steps, shared with Generate). */
+  generateValues: Record<string, unknown>;
+  /** Loaded models, for the same value/model sync the generate path performs. */
+  models?: readonly ModelConfig[];
+  /** Project settings (only `useCpuNoise` is consulted by the compiler). */
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>;
+  /** Persisted denoising strength (already defaulted + clamped). Used for every image mode. */
+  strength: number;
+  /** Persisted compositing settings (infill / coherence / mask blur), defaulted + clamped. */
+  compositing: CanvasCompositingSettings;
+  /** Reducer dispatch. */
+  dispatch: (action: WorkbenchAction) => void;
+}
+
+const recordNotice = (
+  dispatch: (action: WorkbenchAction) => void,
+  kind: WorkbenchNotificationKind,
+  message: string
+): void => {
+  dispatch({ kind, message, title: CANVAS_INVOKE_ERROR_TITLE, type: 'recordNotice' });
+};
+
+/**
+ * Composites + resolves the enabled control layers into graph inputs. Each
+ * content-bearing control layer is composited SEPARATELY (never blended) and its
+ * adapter model resolved from the loaded models. Enabled nonempty invalid layers
+ * throw a shared reason code and block invocation; content-less control layers
+ * are already excluded by `planControlComposites` and remain harmless.
+ */
+const collectControlLayerInputs = async (
+  document: CanvasDocumentContractV2,
+  bbox: { x: number; y: number; width: number; height: number },
+  model: GenerateModelConfig,
+  models: readonly ModelConfig[] | undefined,
+  executorDeps: ExecuteCompositePlanDeps
+): Promise<ControlLayerGraphInput[]> => {
+  const composites = planControlComposites(document, bbox);
+  if (composites.length === 0) {
+    return [];
+  }
+
+  const layerById = new Map(document.layers.map((layer) => [layer.id, layer]));
+  const inputs: ControlLayerGraphInput[] = [];
+  let controlLoraCount = 0;
+  let zImageControlCount = 0;
+
+  for (const { entry, layerId } of composites) {
+    const layer = layerById.get(layerId);
+    if (!layer || layer.type !== 'control') {
+      continue;
+    }
+
+    const { adapter } = layer;
+    const resolved = adapter.model ? models?.find((candidate) => candidate.key === adapter.model) : undefined;
+    const rejection = getControlValidationReason({
+      adapterModel: resolved ? { base: resolved.base, type: resolved.type } : null,
+      beginEndStepPct: adapter.beginEndStepPct,
+      controlLoraIndex: adapter.kind === 'control_lora' ? controlLoraCount : 0,
+      kind: adapter.kind,
+      mainBase: model.base,
+      mainVariant: model.variant ?? undefined,
+      weight: adapter.weight,
+      zImageControlIndex: adapter.kind === 'z_image_control' ? zImageControlCount : 0,
+    });
+    if (rejection || !resolved) {
+      throw new Error(`[${rejection ?? 'missing_model'}] Control layer "${layer.name}" is invalid.`);
+    }
+    if (adapter.kind === 'control_lora') {
+      controlLoraCount += 1;
+    }
+    if (adapter.kind === 'z_image_control') {
+      zImageControlCount += 1;
+    }
+
+    const result = await executeControlComposite(entry, executorDeps);
+    inputs.push({
+      beginEndStepPct: adapter.beginEndStepPct,
+      controlMode: adapter.controlMode,
+      id: layerId,
+      imageName: result.imageName,
+      kind: adapter.kind,
+      model: {
+        base: resolved.base,
+        key: resolved.key,
+        name: resolved.name,
+        type: resolved.type,
+        ...(typeof resolved.hash === 'string' ? { hash: resolved.hash } : {}),
+      },
+      weight: adapter.weight,
+    });
+  }
+
+  return inputs;
+};
+
+/** FLUX Redux image-influence → backend redux settings (mirrors `graph.ts` FLUX_REDUX_INFLUENCE). */
+const FLUX_REDUX_INFLUENCE_SETTINGS = {
+  lowest: { downsampling_factor: 5, weight: 1 },
+  low: { downsampling_factor: 4, weight: 1 },
+  medium: { downsampling_factor: 3, weight: 1 },
+  high: { downsampling_factor: 2, weight: 1 },
+  highest: { downsampling_factor: 1, weight: 1 },
+} as const;
+
+/** Resolves a regional-guidance layer's reference images into graph inputs (drops incomplete/incompatible ones). */
+export const resolveRegionalReferenceImages = (
+  region: { referenceImages: GenerateReferenceImage[] },
+  base: string
+): RegionalReferenceImageInput[] => {
+  const inputs: RegionalReferenceImageInput[] = [];
+  for (const ref of region.referenceImages) {
+    if (!ref.isEnabled) {
+      continue;
+    }
+    const { config } = ref;
+    if (config.type === 'ip_adapter' && base !== 'flux') {
+      if (!config.image || !config.model || config.model.base !== base) {
+        continue;
+      }
+      inputs.push({
+        beginEndStepPct: config.beginEndStepPct,
+        clipVisionModel: config.clipVisionModel,
+        id: ref.id,
+        imageName: config.image.imageName,
+        method: config.method,
+        model: {
+          base: config.model.base,
+          key: config.model.key,
+          name: config.model.name,
+          type: config.model.type,
+          ...(typeof config.model.hash === 'string' ? { hash: config.model.hash } : {}),
+        },
+        type: 'ip_adapter',
+        weight: config.weight,
+      });
+    } else if (config.type === 'flux_redux' && base === 'flux') {
+      if (!config.image || !config.model || config.model.base !== base) {
+        continue;
+      }
+      inputs.push({
+        id: ref.id,
+        imageName: config.image.imageName,
+        model: {
+          base: config.model.base,
+          key: config.model.key,
+          name: config.model.name,
+          type: config.model.type,
+          ...(typeof config.model.hash === 'string' ? { hash: config.model.hash } : {}),
+        },
+        settings: FLUX_REDUX_INFLUENCE_SETTINGS[config.imageInfluence],
+        type: 'flux_redux',
+      });
+    }
+  }
+  return inputs;
+};
+
+/**
+ * Composites + resolves the enabled regional-guidance regions into graph inputs.
+ * Each region with mask content is composited SEPARATELY (its alpha feeds its own
+ * `alpha_mask_to_tensor`); regions invalid for the base (unsupported base, empty,
+ * FLUX + negative/autoNegative) are skipped silently, mirroring legacy. Regions
+ * whose prompts + reference images are all empty are also skipped.
+ */
+const collectRegionalGuidanceInputs = async (
+  document: CanvasDocumentContractV2,
+  bbox: { x: number; y: number; width: number; height: number },
+  model: GenerateModelConfig,
+  executorDeps: ExecuteCompositePlanDeps
+): Promise<RegionalGuidanceInput[]> => {
+  if (!isRegionalGuidanceSupportedForBase(model.base)) {
+    return [];
+  }
+  const composites = planRegionalMaskComposites(document, bbox);
+  if (composites.length === 0) {
+    return [];
+  }
+
+  const layerById = new Map(document.layers.map((layer) => [layer.id, layer]));
+  const inputs: RegionalGuidanceInput[] = [];
+
+  for (const { entry, layerId } of composites) {
+    const layer = layerById.get(layerId);
+    if (!layer || layer.type !== 'regional_guidance') {
+      continue;
+    }
+
+    const referenceImages = resolveRegionalReferenceImages(layer, model.base);
+    const rejection = getRegionalGuidanceRejectionReason({
+      autoNegative: layer.autoNegative,
+      hasContent: true,
+      layerName: layer.name,
+      mainBase: model.base,
+      negativePrompt: layer.negativePrompt,
+      positivePrompt: layer.positivePrompt,
+      referenceImageCount: referenceImages.length,
+    });
+    if (rejection) {
+      continue;
+    }
+
+    const result = await executeRegionalMaskComposite(entry, executorDeps);
+    inputs.push({
+      autoNegative: layer.autoNegative,
+      id: layerId,
+      maskImageName: result.imageName,
+      negativePrompt: layer.negativePrompt,
+      positivePrompt: layer.positivePrompt,
+      referenceImages,
+    });
+  }
+
+  return inputs;
+};
+
+/**
+ * Runs the canvas-invoke pipeline with injected dependencies. Never throws:
+ * every failure is turned into a notice, and the in-flight guard is always
+ * cleared. Returns when the graph has been dispatched (or the invoke aborted).
+ */
+export const runCanvasInvocation = async (deps: RunCanvasInvocationDeps): Promise<void> => {
+  const { dispatch, inFlight, projectId } = deps;
+
+  // Concurrency guard: ignore a re-invoke while a prior prepare for this project
+  // is still settling (the hotkey can be mashed). Cleared in `finally`.
+  if (inFlight.has(projectId)) {
+    return;
+  }
+  inFlight.add(projectId);
+
+  let rasterSnapshot: Extract<CaptureRasterSnapshotResult, { status: 'ok' }>['snapshot'] | null = null;
+  try {
+    const values = normalizeGenerateWidgetValues(deps.generateValues);
+    if (!values) {
+      recordNotice(dispatch, 'error', 'Select a supported model before invoking the canvas.');
+      return;
+    }
+
+    // Resolve model + settings exactly as the generate path does (sync to loaded
+    // models, then resolve the seed) so canvas and generate stay in lockstep.
+    const synced = deps.models ? syncGenerateWidgetValuesWithModels(values, deps.models) : values;
+    const settings = { ...synced, seed: resolveGenerateSeed(synced) };
+    const model: GenerateModelConfig = settings.model;
+
+    // Persist any pending paint bitmaps BEFORE compositing from their pixels.
+    await deps.flushPendingUploads();
+
+    // Re-read the document AFTER the flush barrier: the flush dispatches
+    // `updateCanvasLayerSource` for each just-persisted paint layer, so the
+    // pre-flush snapshot still references `paint:empty`/stale bitmap names. Plan,
+    // composite, and compile from the post-flush document so the dedupe keys are
+    // built from the persisted refs (silent cache misses otherwise) and so the
+    // empty-paint-layer filter (see `planComposites`) sees the real `bitmap`.
+    // The bbox can also move during a slow flush; take it from the fresh snapshot.
+    const documentSnapshot = deps.captureDocumentSnapshot();
+    if (!documentSnapshot) {
+      recordNotice(dispatch, 'error', 'The canvas has no active document to generate from.');
+      return;
+    }
+    const postFlushDocument = documentSnapshot.canvas.document;
+    const bbox = postFlushDocument.bbox;
+
+    const plan = planComposites(postFlushDocument, bbox);
+    const controlPlan = planControlComposites(postFlushDocument, bbox);
+    const regionalPlan = planRegionalMaskComposites(postFlushDocument, bbox);
+
+    const requiredLayerIds = new Set<string>();
+    for (const entry of [
+      ...plan.entries,
+      ...controlPlan.map((item) => item.entry),
+      ...regionalPlan.map((item) => item.entry),
+    ]) {
+      for (const layer of entry.layers) {
+        requiredLayerIds.add(layer.id);
+      }
+      for (const layer of entry.maskLayers ?? []) {
+        requiredLayerIds.add(layer.id);
+      }
+    }
+    const capture = await deps.captureRasterSnapshot(documentSnapshot, [...requiredLayerIds], { signal: deps.signal });
+    if (capture.status !== 'ok') {
+      recordNotice(
+        dispatch,
+        'error',
+        capture.status === 'stale'
+          ? 'The canvas changed while generation was being prepared. Please invoke again.'
+          : `The canvas could not be captured for generation (${capture.status}).`
+      );
+      return;
+    }
+    rasterSnapshot = capture.snapshot;
+    const canvasSnapshot = rasterSnapshot.canvas;
+    const getLayerSurface = (layerId: string) => {
+      const detached = rasterSnapshot?.layerSurfaces.get(layerId);
+      if (!detached) {
+        return Promise.reject(new Error(`Canvas raster snapshot is missing layer ${layerId}.`));
+      }
+      return Promise.resolve(detached);
+    };
+    const transactionDedupe: CompositeDedupeCache = {
+      byHash: new Map(deps.dedupe.byHash),
+      byKey: new Map(deps.dedupe.byKey),
+    };
+    // Bounds-only pre-pass (pure geometry, no upload): content that does not
+    // overlap the bbox is txt2img no matter the coverage. Also naturally skips a
+    // zero-area bbox (rectsIntersect is false), which validation rejects anyway.
+    const contentBounds = computeCompositeContentBounds(plan);
+
+    const executorDeps = { ...deps.executorDeps, dedupe: transactionDedupe, getLayerSurface };
+
+    let mode: CanvasCompileMode = 'txt2img';
+    let compositeImageName: string | null = null;
+    let maskImageName: string | null = null;
+    let noiseMaskImageName: string | null = null;
+
+    if (contentBounds && rectsIntersect(contentBounds, bbox)) {
+      const result = await executeCompositePlan(plan, executorDeps);
+      compositeImageName = result.base.imageName;
+
+      // The grayscale denoise-limit mask (when enabled inpaint masks exist) both
+      // decides inpaint-vs-img2img (its coverage) and feeds the graph. Legacy
+      // parity: raster opaque + mask has content → inpaint; else img2img.
+      const maskEntry = plan.entries.find((entry) => entry.kind === 'inpaint-mask');
+      const maskResult = maskEntry ? await executeMaskComposite(maskEntry, executorDeps) : null;
+
+      const detected = detectCanvasMode({
+        bbox,
+        bboxFullyCovered: result.bboxFullyCovered,
+        contentBounds: result.contentBounds,
+        hasActiveInpaintMask: maskResult?.hasContent ?? false,
+      });
+      mode = detected;
+
+      if (detected === 'inpaint' || detected === 'outpaint') {
+        // A real (non-white) mask feeds create_gradient_mask; outpaint without one
+        // derives its mask from the raster alpha (maskImageName stays null).
+        maskImageName = maskResult?.hasContent ? maskResult.imageName : null;
+        const noiseEntry = plan.entries.find((entry) => entry.kind === 'noise-mask');
+        if (noiseEntry) {
+          noiseMaskImageName = (await executeMaskComposite(noiseEntry, executorDeps)).imageName;
+        }
+      }
+    }
+
+    // Control layers apply in every mode, independent of the base composite —
+    // composite + resolve them regardless of whether raster content overlaps.
+    const controlLayers = await collectControlLayerInputs(postFlushDocument, bbox, model, deps.models, executorDeps);
+
+    // Regional guidance also applies in every mode, independent of the base
+    // composite — composite + resolve each region regardless of raster overlap.
+    const regionalGuidance = await collectRegionalGuidanceInputs(postFlushDocument, bbox, model, executorDeps);
+
+    const compiled = compileCanvasGraph({
+      bbox,
+      compositeImageName,
+      compositing: deps.compositing,
+      controlLayers,
+      destination: deps.destination,
+      maskImageName,
+      mode,
+      model,
+      noiseMaskImageName,
+      projectSettings: deps.projectSettings,
+      regionalGuidance,
+      settings,
+      strength: deps.strength,
+    });
+
+    dispatch({
+      backendSupportsCancellation: true,
+      destination: deps.destination,
+      generate: {
+        negativePromptNodeId: compiled.negativePromptNodeId,
+        positivePromptNodeId: compiled.positivePromptNodeId,
+        seedNodeId: compiled.seedNodeId,
+        values: settings,
+      },
+      graph: compiled.graph,
+      canvas: canvasSnapshot,
+      projectId,
+      type: 'submitCanvasInvocationSnapshot',
+    });
+    for (const [key, value] of transactionDedupe.byHash) {
+      deps.dedupe.byHash.set(key, value);
+    }
+    for (const [key, value] of transactionDedupe.byKey) {
+      deps.dedupe.byKey.set(key, value);
+    }
+  } catch (error) {
+    recordNotice(dispatch, 'error', error instanceof Error ? error.message : String(error));
+  } finally {
+    rasterSnapshot?.release();
+    inFlight.delete(projectId);
+  }
+};
+
+// ---- Command-layer wiring (per-engine caches + in-flight guard) -------------
+
+/** The dedupe cache's per-map entry cap (bounds unbounded growth across invokes). */
+const DEDUPE_CACHE_CAPACITY = 16;
+
+/**
+ * A {@link Map} that evicts its oldest (insertion-order) entry once it exceeds
+ * `capacity`, so a long-lived dedupe cache can't grow without bound across many
+ * invokes with distinct plans/pixels.
+ */
+class BoundedMap<K, V> extends Map<K, V> {
+  constructor(private readonly capacity: number) {
+    super();
+  }
+
+  override set(key: K, value: V): this {
+    if (!this.has(key) && this.size >= this.capacity) {
+      const oldest = this.keys().next().value;
+      if (oldest !== undefined) {
+        this.delete(oldest);
+      }
+    }
+    return super.set(key, value);
+  }
+}
+
+/** A size-capped {@link CompositeDedupeCache}. */
+export const createBoundedCompositeDedupeCache = (capacity = DEDUPE_CACHE_CAPACITY): CompositeDedupeCache => ({
+  byHash: new BoundedMap(capacity),
+  byKey: new BoundedMap(capacity),
+});
+
+// Project ids with a prepare in flight (survives across the async orchestrator).
+const inFlightProjects = new Set<string>();
+type CanvasInvocationEngine = {
+  readonly document: CanvasDocumentCapability;
+  readonly exports: CanvasExportCapability;
+  readonly lifecycle: CanvasLifecycleCapability;
+};
+// Per-engine dedupe caches, dropped when the engine is disposed and GC'd.
+const dedupeCachesByEngine = new WeakMap<CanvasInvocationEngine, CompositeDedupeCache>();
+
+const getEngineDedupeCache = (engine: CanvasInvocationEngine): CompositeDedupeCache => {
+  let cache = dedupeCachesByEngine.get(engine);
+  if (!cache) {
+    cache = createBoundedCompositeDedupeCache();
+    dedupeCachesByEngine.set(engine, cache);
+  }
+  return cache;
+};
+
+/** Arguments for the thin command-layer {@link prepareCanvasInvocation}. */
+export interface PrepareCanvasInvocationArgs {
+  projectId: string;
+  /** The resolved result destination (Canvas staging vs. a durable Gallery image). */
+  destination: ResultDestination;
+  generateValues: Record<string, unknown>;
+  models?: readonly ModelConfig[];
+  projectSettings: Pick<ProjectSettings, 'useCpuNoise'>;
+  strength: number;
+  signal?: AbortSignal;
+  /**
+   * Persisted compositing settings, already defaulted + clamped by the caller
+   * (`readCanvasCompositingSettings`). Falls back to legacy defaults when omitted.
+   */
+  compositing?: CanvasCompositingSettings;
+  dispatch: (action: WorkbenchAction) => void;
+}
+
+/**
+ * Resolves the active project's engine and runs the canvas-invoke orchestrator.
+ * Fire-and-track: the caller does not await it (the Invoke command stays sync).
+ */
+export const prepareCanvasInvocation = async (args: PrepareCanvasInvocationArgs): Promise<void> => {
+  const engine = getEngine(args.projectId);
+  if (!engine) {
+    recordNotice(args.dispatch, 'error', 'Open the canvas before invoking it.');
+    return;
+  }
+
+  await runCanvasInvocation({
+    compositing: args.compositing ?? DEFAULT_CANVAS_COMPOSITING,
+    dedupe: getEngineDedupeCache(engine),
+    destination: args.destination,
+    dispatch: args.dispatch,
+    executorDeps: engine.exports.getCompositeExecutorDeps(),
+    captureDocumentSnapshot: () => engine.document.captureSnapshot(),
+    captureRasterSnapshot: (snapshot, layerIds, options) =>
+      engine.exports.captureRasterSnapshot(snapshot, layerIds, options),
+    flushPendingUploads: () => engine.lifecycle.flushPendingUploads(),
+    generateValues: args.generateValues,
+    inFlight: inFlightProjects,
+    models: args.models,
+    projectId: args.projectId,
+    projectSettings: args.projectSettings,
+    signal: args.signal ?? new AbortController().signal,
+    strength: args.strength,
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/stagingPreview.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/stagingPreview.test.ts
new file mode 100644
index 00000000000..eb34798ed14
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/stagingPreview.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+
+import { selectStagedPreviewSource, stagedPreviewKey } from './stagingPreview';
+
+const base = {
+  bboxHeight: 512,
+  bboxWidth: 512,
+  isGenerationInFlight: false,
+  isVisible: true,
+  progressImage: null,
+  selectedImageName: null,
+} as const;
+
+describe('selectStagedPreviewSource', () => {
+  it('returns null when nothing is staged and not generating', () => {
+    expect(selectStagedPreviewSource(base)).toBeNull();
+  });
+
+  it('returns the selected candidate when visible and present', () => {
+    expect(selectStagedPreviewSource({ ...base, selectedImageName: 'img-1' })).toEqual({ imageName: 'img-1' });
+  });
+
+  it('carries the selected candidate placement into the image preview', () => {
+    const placement = { height: 240, opacity: 0.4, width: 320, x: 11, y: 17 };
+
+    expect(
+      selectStagedPreviewSource({
+        ...base,
+        selectedImageName: 'img-1',
+        selectedPlacement: placement,
+      })
+    ).toEqual({ imageName: 'img-1', placement });
+  });
+
+  it('returns null for a selected candidate when the preview is hidden', () => {
+    expect(selectStagedPreviewSource({ ...base, isVisible: false, selectedImageName: 'img-1' })).toBeNull();
+  });
+
+  it('returns the selected candidate even while another canvas slot is generating', () => {
+    expect(
+      selectStagedPreviewSource({
+        ...base,
+        isGenerationInFlight: true,
+        progressImage: { dataUrl: 'data:image/png;base64,AAAA', height: 64, width: 64 },
+        selectedImageName: 'img-1',
+      })
+    ).toEqual({ imageName: 'img-1' });
+  });
+
+  it('returns the selected placeholder progress frame while generating, scaled to fill the bbox', () => {
+    const source = selectStagedPreviewSource({
+      ...base,
+      isGenerationInFlight: true,
+      progressImage: { dataUrl: 'data:image/png;base64,AAAA', height: 64, width: 64 },
+    });
+
+    // Fills the bbox dims (512x512), not the progress frame's native 64x64.
+    expect(source).toEqual({ dataUrl: 'data:image/png;base64,AAAA', height: 512, width: 512 });
+  });
+
+  it('falls back to the candidate once generation settles (no progress frame)', () => {
+    expect(
+      selectStagedPreviewSource({
+        ...base,
+        isGenerationInFlight: true,
+        progressImage: null,
+        selectedImageName: 'img-1',
+      })
+    ).toEqual({ imageName: 'img-1' });
+  });
+
+  it('ignores a progress frame when the bbox has no area', () => {
+    expect(
+      selectStagedPreviewSource({
+        ...base,
+        bboxHeight: 0,
+        bboxWidth: 0,
+        isGenerationInFlight: true,
+        progressImage: { dataUrl: 'data:image/png;base64,AAAA', height: 64, width: 64 },
+      })
+    ).toBeNull();
+  });
+});
+
+describe('stagedPreviewKey', () => {
+  it('is stable per source and distinguishes the source kinds', () => {
+    expect(stagedPreviewKey(null)).toBe('none');
+    expect(stagedPreviewKey({ imageName: 'a' })).toBe('image:a');
+    expect(stagedPreviewKey({ imageName: 'a' })).not.toBe(stagedPreviewKey({ imageName: 'b' }));
+    // A new progress frame (different data URL) yields a new key so the effect re-fires.
+    expect(stagedPreviewKey({ dataUrl: 'AA', height: 8, width: 8 })).not.toBe(
+      stagedPreviewKey({ dataUrl: 'BB', height: 8, width: 8 })
+    );
+  });
+
+  it('includes every image placement field', () => {
+    const placement = { height: 240, opacity: 0.4, width: 320, x: 11, y: 17 };
+    const original = stagedPreviewKey({ imageName: 'a', placement });
+
+    expect(original).not.toBe(stagedPreviewKey({ imageName: 'a' }));
+    expect(original).not.toBe(stagedPreviewKey({ imageName: 'a', placement: { ...placement, x: 12 } }));
+    expect(original).not.toBe(stagedPreviewKey({ imageName: 'a', placement: { ...placement, y: 18 } }));
+    expect(original).not.toBe(stagedPreviewKey({ imageName: 'a', placement: { ...placement, width: 321 } }));
+    expect(original).not.toBe(stagedPreviewKey({ imageName: 'a', placement: { ...placement, height: 241 } }));
+    expect(original).not.toBe(stagedPreviewKey({ imageName: 'a', placement: { ...placement, opacity: 0.5 } }));
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/stagingPreview.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/stagingPreview.ts
new file mode 100644
index 00000000000..e976c4e1897
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/stagingPreview.ts
@@ -0,0 +1,71 @@
+/**
+ * Pure selection of what the engine should draw as the canvas staged preview:
+ * the selected finished candidate when visible, otherwise the selected
+ * placeholder's live denoise-progress frame, otherwise nothing. Kept React-free
+ * so the candidate-vs-progress decision is unit-testable in node.
+ */
+
+import type { StagedPreviewInput } from '@workbench/canvas-engine/engine';
+import type { CanvasPlacementContract } from '@workbench/types';
+
+/** Inputs to {@link selectStagedPreviewSource}. */
+export interface StagedPreviewSelection {
+  /** Whether the selected slot is a canvas placeholder that may have live progress. */
+  isGenerationInFlight: boolean;
+  /** The selected placeholder's denoise-progress frame, if any (b64 data URL + native dims). */
+  progressImage: { dataUrl: string; width: number; height: number } | null;
+  /** Whether finished candidate previews are visible. Placeholder progress is controlled separately. */
+  isVisible: boolean;
+  /** The currently selected staged candidate's image name, if any. */
+  selectedImageName: string | null;
+  /** The selected candidate's world-space placement, if it has one. */
+  selectedPlacement?: CanvasPlacementContract | null;
+  /** The current bbox size (document px) — progress frames scale to fill it. */
+  bboxWidth: number;
+  bboxHeight: number;
+}
+
+/**
+ * Resolves the staged-preview source. A selected finished candidate wins when
+ * candidate previews are visible; otherwise selected-placeholder progress fills
+ * the bbox. Returns `null` when neither source is available.
+ */
+export const selectStagedPreviewSource = ({
+  bboxHeight,
+  bboxWidth,
+  isGenerationInFlight,
+  isVisible,
+  progressImage,
+  selectedImageName,
+  selectedPlacement,
+}: StagedPreviewSelection): StagedPreviewInput | null => {
+  if (isVisible && selectedImageName) {
+    return selectedPlacement
+      ? { imageName: selectedImageName, placement: selectedPlacement }
+      : { imageName: selectedImageName };
+  }
+  if (isGenerationInFlight && progressImage && bboxWidth > 0 && bboxHeight > 0) {
+    // Progress frames are low-res latents of the bbox region; scale to fill it.
+    return { dataUrl: progressImage.dataUrl, height: bboxHeight, width: bboxWidth };
+  }
+  return null;
+};
+
+/**
+ * A stable string key for a {@link StagedPreviewInput}, so a React effect only
+ * re-drives the (async, decoding) `setStagedPreview` when the source actually
+ * changes — including every new progress frame, but not on unrelated renders.
+ */
+export const stagedPreviewKey = (source: StagedPreviewInput | null): string => {
+  if (source === null) {
+    return 'none';
+  }
+  if ('imageName' in source) {
+    const { placement } = source;
+
+    return placement
+      ? `image:${source.imageName}:${placement.x}:${placement.y}:${placement.width}:${placement.height}:${placement.opacity}`
+      : `image:${source.imageName}`;
+  }
+  return `data:${source.width}x${source.height}:${source.dataUrl}`;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/surfaceFocus.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/surfaceFocus.test.ts
new file mode 100644
index 00000000000..7dc262baa7e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/surfaceFocus.test.ts
@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { INLINE_EDIT_SELECTOR, shouldFocusCanvasSurface } from './surfaceFocus';
+
+/**
+ * Minimal DOM stand-in for node-env: `contains` walks the parent chain,
+ * `closest` reports whether this element (or an ancestor) matches the
+ * inline-edit selector. Mirrors the FakeElement approach in
+ * `hotkeys/targetWidget.test.ts`.
+ */
+class FakeElement {
+  parent: FakeElement | null = null;
+
+  constructor(private readonly matchesInlineEdit = false) {}
+
+  appendTo(parent: FakeElement): this {
+    this.parent = parent;
+    return this;
+  }
+
+  closest(selector: string): FakeElement | null {
+    expect(selector).toBe(INLINE_EDIT_SELECTOR);
+    if (this.matchesInlineEdit) {
+      return this;
+    }
+    return this.parent ? this.parent.closest(selector) : null;
+  }
+
+  contains(other: unknown): boolean {
+    let current = other as FakeElement | null;
+    while (current) {
+      if (current === this) {
+        return true;
+      }
+      current = current.parent;
+    }
+    return false;
+  }
+}
+
+const asContainer = (el: FakeElement): HTMLElement => el as unknown as HTMLElement;
+const asTarget = (el: FakeElement): EventTarget => el as unknown as EventTarget;
+const asActive = (el: FakeElement): Element => el as unknown as Element;
+
+describe('shouldFocusCanvasSurface', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('focuses when DOM focus is outside the surface (e.g. a layers-panel button)', () => {
+    vi.stubGlobal('Element', FakeElement);
+    const container = new FakeElement();
+    const overlayCanvas = new FakeElement().appendTo(container);
+    const layersButtonElsewhere = new FakeElement();
+
+    expect(
+      shouldFocusCanvasSurface(asContainer(container), asTarget(overlayCanvas), asActive(layersButtonElsewhere))
+    ).toBe(true);
+  });
+
+  it('focuses when nothing is focused at all', () => {
+    vi.stubGlobal('Element', FakeElement);
+    const container = new FakeElement();
+    const overlayCanvas = new FakeElement().appendTo(container);
+
+    expect(shouldFocusCanvasSurface(asContainer(container), asTarget(overlayCanvas), null)).toBe(true);
+  });
+
+  it('does not refocus when focus is already inside the surface (open text session: click-away commits via the engine)', () => {
+    vi.stubGlobal('Element', FakeElement);
+    const container = new FakeElement();
+    const overlayCanvas = new FakeElement().appendTo(container);
+    // The text tool's contenteditable lives inside the surface container.
+    const contenteditable = new FakeElement(true).appendTo(container);
+
+    // Click on the canvas OUTSIDE the editable — the commit gesture. Focus must
+    // stay on the editable so the engine's pointerdown commit-and-swallow runs.
+    expect(shouldFocusCanvasSurface(asContainer(container), asTarget(overlayCanvas), asActive(contenteditable))).toBe(
+      false
+    );
+  });
+
+  it('does not steal focus when the click lands inside an inline editor', () => {
+    vi.stubGlobal('Element', FakeElement);
+    const container = new FakeElement();
+    // A portal-rendered editor: its DOM sits OUTSIDE the container, so only the
+    // target-side selector guard can spare it.
+    const portalEditor = new FakeElement(true);
+    const focusElsewhere = new FakeElement();
+
+    expect(shouldFocusCanvasSurface(asContainer(container), asTarget(portalEditor), asActive(focusElsewhere))).toBe(
+      false
+    );
+  });
+
+  it('focuses when the target is not an Element (defensive: non-element event targets)', () => {
+    vi.stubGlobal('Element', FakeElement);
+    const container = new FakeElement();
+
+    expect(shouldFocusCanvasSurface(asContainer(container), {} as EventTarget, null)).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/surfaceFocus.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/surfaceFocus.ts
new file mode 100644
index 00000000000..e7fa7f90d9d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/surfaceFocus.ts
@@ -0,0 +1,52 @@
+/**
+ * Pure predicate for the canvas surface's focus-on-pointerdown behavior, kept
+ * free of React/Chakra so it is node-testable (see `surfaceFocus.test.ts`).
+ *
+ * The two `<canvas>` render targets aren't focusable, so a plain click never
+ * moves DOM focus — it stays wherever it was (e.g. a layers-panel button in a
+ * DIFFERENT widget), and the hotkey runtime's DOM-focus-based widget resolution
+ * (`getHotkeyTargetWidget`) keeps routing tool hotkeys (`b`/`e`/…) to that other
+ * widget. Focusing the surface container on pointerdown moves focus into the
+ * canvas widget's subtree so its hotkeys fire immediately.
+ */
+
+/**
+ * Elements that own their own focus/caret and must NOT be focus-stolen by the
+ * surface: the text tool's contenteditable overlay and any inline input the
+ * chrome overlays on the surface.
+ */
+export const INLINE_EDIT_SELECTOR = 'input, textarea, select, [contenteditable="true"], [role="textbox"]';
+
+/**
+ * Whether a pointerdown on the canvas surface should focus the surface
+ * container.
+ *
+ * - **Focus already inside the surface → no.** Most importantly the text
+ *   tool's contenteditable (rendered inside the container by `TextEditPortal`):
+ *   clicking the canvas *outside* it is the "click away to commit" gesture,
+ *   which the ENGINE owns (`commitOpenTextSession` in its pointerdown, which
+ *   then swallows the click). Focusing the container here would fire in the
+ *   capture phase — before the engine's bubble-phase handler — synchronously
+ *   blurring the editable, committing + nulling the session via its `onBlur`,
+ *   so the engine would then see no session, not swallow the click, and open a
+ *   stray new text session at the click point. Skipping is also harmless for
+ *   hotkey scope: focus inside the surface already resolves to the canvas
+ *   widget.
+ * - **Click landing in an inline editor → no.** Belt and suspenders for
+ *   portal-rendered editors whose DOM may sit outside the container (so the
+ *   `contains` check above wouldn't spare them).
+ * - **Otherwise → yes** (e.g. focus is on a button in another widget's panel).
+ */
+export const shouldFocusCanvasSurface = (
+  container: HTMLElement,
+  target: EventTarget | null,
+  activeElement: Element | null
+): boolean => {
+  if (activeElement && container.contains(activeElement)) {
+    return false;
+  }
+  if (target instanceof Element && target.closest(INLINE_EDIT_SELECTOR)) {
+    return false;
+  }
+  return true;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/BboxOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/BboxOptions.tsx
new file mode 100644
index 00000000000..409dc58ceab
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/BboxOptions.tsx
@@ -0,0 +1,105 @@
+import type { SelectValueChangeDetails } from '@chakra-ui/react';
+
+import { createListCollection, HStack } from '@chakra-ui/react';
+import { constrainBboxToRatio } from '@workbench/canvas-engine/tools/bboxHitTest';
+import { Select, ToggleDot } from '@workbench/components/ui';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+import { useBboxEditor } from './useBboxEditor';
+
+/** Aspect-ratio presets offered in the options bar. `null` ratio = Free (unlocked). */
+interface AspectPreset {
+  id: string;
+  ratio: number | null;
+}
+
+const ASPECT_PRESETS: readonly AspectPreset[] = [
+  { id: 'Free', ratio: null },
+  { id: '1:1', ratio: 1 },
+  { id: '4:3', ratio: 4 / 3 },
+  { id: '3:4', ratio: 3 / 4 },
+  { id: '16:9', ratio: 16 / 9 },
+  { id: '9:16', ratio: 9 / 16 },
+];
+
+const ASPECT_TRIGGER_PROPS = { minW: '5.5rem' } as const;
+
+/** The preset id whose ratio matches `aspectRatio` (within tolerance), or `null`. */
+const matchingPresetId = (aspectRatio: number): string | null =>
+  ASPECT_PRESETS.find((preset) => preset.ratio !== null && Math.abs(preset.ratio - aspectRatio) < 1e-3)?.id ?? null;
+
+/**
+ * Bbox tool options: aspect-ratio preset select and aspect lock toggle. Numeric
+ * frame details live in the separate bbox details bar.
+ */
+export const BboxOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const { bbox, commitBbox, grid, options } = useBboxEditor(engine);
+
+  const collection = useMemo(
+    () =>
+      createListCollection({
+        itemToString: (item: AspectPreset) => item.id,
+        itemToValue: (item: AspectPreset) => item.id,
+        items: [...ASPECT_PRESETS],
+      }),
+    []
+  );
+
+  const selectValue = useMemo(
+    () => [options.aspectLocked ? (matchingPresetId(options.aspectRatio) ?? 'Free') : 'Free'],
+    [options.aspectLocked, options.aspectRatio]
+  );
+
+  const onAspectPresetChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const id = value[0];
+      const preset = ASPECT_PRESETS.find((entry) => entry.id === id);
+      if (!preset) {
+        return;
+      }
+      if (preset.ratio === null) {
+        engine.stores.bboxOptions.set({ ...options, aspectLocked: false });
+        return;
+      }
+      engine.stores.bboxOptions.set({ aspectLocked: true, aspectRatio: preset.ratio });
+      commitBbox(constrainBboxToRatio(bbox, preset.ratio, grid));
+    },
+    [bbox, commitBbox, engine, grid, options]
+  );
+
+  const onLockToggle = useCallback(
+    (checked: boolean) => {
+      const aspectRatio =
+        checked && bbox.height > 0 && matchingPresetId(options.aspectRatio) === null
+          ? bbox.width / bbox.height
+          : options.aspectRatio > 0
+            ? options.aspectRatio
+            : 1;
+      engine.stores.bboxOptions.set({ aspectLocked: checked, aspectRatio });
+    },
+    [bbox, engine, options.aspectRatio]
+  );
+
+  return (
+    <HStack align="center" gap="3">
+      <Select
+        aria-label={t('widgets.canvas.toolOptions.aspectRatio')}
+        collection={collection}
+        size="xs"
+        triggerProps={ASPECT_TRIGGER_PROPS}
+        value={selectValue}
+        valueText={selectValue[0]}
+        onValueChange={onAspectPresetChange}
+      />
+      <ToggleDot
+        checked={options.aspectLocked}
+        label={t('widgets.canvas.toolOptions.lockAspect')}
+        onCheckedChange={onLockToggle}
+      />
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/BrushOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/BrushOptions.tsx
new file mode 100644
index 00000000000..6e393280f09
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/BrushOptions.tsx
@@ -0,0 +1,124 @@
+import type { NumberInput as ChakraNumberInput, SliderValueChangeDetails } from '@chakra-ui/react';
+
+import { HStack, NumberInput } from '@chakra-ui/react';
+import { MAX_BRUSH_SIZE, MIN_BRUSH_SIZE } from '@workbench/canvas-engine/engineStores';
+import { ColorPicker, Slider, ToggleDot } from '@workbench/components/ui';
+import { useBrushOptions } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+/**
+ * The slider's own travel tops out well below `MAX_BRUSH_SIZE` — most brush
+ * work happens under ~600px, and the numeric input still reaches the full
+ * engine-clamped range for outliers.
+ */
+const SLIDER_MAX_SIZE = 600;
+
+const formatSizePx = (value: number): string => `${Math.round(value)}px`;
+const formatOpacityPercent = (value: number): string => `${Math.round(value)}%`;
+
+/** Brush tool options: color swatch, size (slider + numeric), opacity, and pressure sensitivity. */
+export const BrushOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const options = useBrushOptions(engine);
+
+  const sizeAriaLabel = useMemo(() => [t('widgets.canvas.toolOptions.brushSize')], [t]);
+  const opacityAriaLabel = useMemo(() => [t('widgets.canvas.toolOptions.opacity')], [t]);
+  const sliderValue = useMemo(() => [Math.min(options.size, SLIDER_MAX_SIZE)], [options.size]);
+  const opacityValue = useMemo(() => [Math.round(options.opacity * 100)], [options.opacity]);
+  const numberInputValue = useMemo(() => String(Math.round(options.size)), [options.size]);
+
+  const setSize = useCallback(
+    (size: number) => engine.stores.brushOptions.set({ ...options, size }),
+    [engine, options]
+  );
+
+  const onSliderSizeChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next !== undefined && Number.isFinite(next)) {
+        setSize(next);
+      }
+    },
+    [setSize]
+  );
+
+  const onNumberSizeChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setSize(valueAsNumber);
+      }
+    },
+    [setSize]
+  );
+
+  const onOpacityChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next !== undefined && Number.isFinite(next)) {
+        engine.stores.brushOptions.set({ ...options, opacity: next / 100 });
+      }
+    },
+    [engine, options]
+  );
+
+  const onColorChange = useCallback(
+    (hex: string) => engine.stores.brushOptions.set({ ...options, color: hex }),
+    [engine, options]
+  );
+
+  const onPressureToggle = useCallback(
+    (checked: boolean) => engine.stores.brushOptions.set({ ...options, pressureSensitivity: checked }),
+    [engine, options]
+  );
+
+  return (
+    <HStack align="center" gap="3">
+      <ColorPicker
+        aria-label={t('widgets.canvas.toolOptions.brushColor')}
+        value={options.color}
+        onValueChange={onColorChange}
+      />
+      <HStack align="center" gap="1.5">
+        <Slider
+          aria-label={sizeAriaLabel}
+          formatValue={formatSizePx}
+          max={SLIDER_MAX_SIZE}
+          min={MIN_BRUSH_SIZE}
+          size="sm"
+          value={sliderValue}
+          w="7rem"
+          onValueChange={onSliderSizeChange}
+        />
+        <NumberInput.Root
+          max={MAX_BRUSH_SIZE}
+          min={MIN_BRUSH_SIZE}
+          size="xs"
+          value={numberInputValue}
+          w="4.5rem"
+          onValueChange={onNumberSizeChange}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.brushSize')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <Slider
+        aria-label={opacityAriaLabel}
+        formatValue={formatOpacityPercent}
+        max={100}
+        min={0}
+        size="sm"
+        value={opacityValue}
+        w="6rem"
+        onValueChange={onOpacityChange}
+      />
+      <ToggleDot
+        checked={options.pressureSensitivity}
+        label={t('widgets.canvas.toolOptions.pressureSensitivity')}
+        onCheckedChange={onPressureToggle}
+      />
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/CanvasOperationBar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/CanvasOperationBar.tsx
new file mode 100644
index 00000000000..162ec837c6e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/CanvasOperationBar.tsx
@@ -0,0 +1,30 @@
+import type { CanvasOperationState } from '@workbench/canvas-operations/operationController';
+
+import type { CanvasOperationUIEngine } from './operationUIEngine';
+
+import { FilterOptions } from './FilterOptions';
+import { SamOptions } from './SamOptions';
+
+/**
+ * Bottom-center controls for the active guarded operation, independent of
+ * temporary tools. Both operations render single-row floating-bar chrome,
+ * matching the per-tool options bars.
+ */
+export const CanvasOperationBar = ({
+  engine,
+  isExternalInteractionLocked,
+  operation,
+}: {
+  engine: CanvasOperationUIEngine;
+  isExternalInteractionLocked: boolean;
+  operation: Extract<CanvasOperationState, { status: 'active' }>;
+}) => (
+  <>
+    {operation.identity.kind === 'select-object' ? (
+      <SamOptions engine={engine} isExternalInteractionLocked={isExternalInteractionLocked} />
+    ) : null}
+    {operation.identity.kind === 'filter' ? (
+      <FilterOptions engine={engine} isExternalInteractionLocked={isExternalInteractionLocked} />
+    ) : null}
+  </>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/CanvasOptionsBar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/CanvasOptionsBar.tsx
new file mode 100644
index 00000000000..1217636c18a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/CanvasOptionsBar.tsx
@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+
+import { HStack } from '@chakra-ui/react';
+import { CanvasFloatingBar } from '@workbench/widgets/canvas/CanvasFloatingBar';
+
+export const CanvasOptionsBar = ({ children }: { children?: ReactNode }) => (
+  <CanvasFloatingBar maxW="full">
+    <HStack align="center" gap="1" minW="0">
+      {children}
+    </HStack>
+  </CanvasFloatingBar>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/EraserOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/EraserOptions.tsx
new file mode 100644
index 00000000000..12c1c881d45
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/EraserOptions.tsx
@@ -0,0 +1,100 @@
+import type { NumberInput as ChakraNumberInput, SliderValueChangeDetails } from '@chakra-ui/react';
+
+import { HStack, NumberInput } from '@chakra-ui/react';
+import { MAX_BRUSH_SIZE, MIN_BRUSH_SIZE } from '@workbench/canvas-engine/engineStores';
+import { Slider } from '@workbench/components/ui';
+import { useEraserOptions } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+/** Same rationale as `BrushOptions`: the slider tops out below `MAX_BRUSH_SIZE`; the numeric input reaches the full range. */
+const SLIDER_MAX_SIZE = 600;
+
+const formatSizePx = (value: number): string => `${Math.round(value)}px`;
+const formatOpacityPercent = (value: number): string => `${Math.round(value)}%`;
+
+/** Eraser tool options: size (slider + numeric) and opacity. */
+export const EraserOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const options = useEraserOptions(engine);
+
+  const sizeAriaLabel = useMemo(() => [t('widgets.canvas.toolOptions.eraserSize')], [t]);
+  const opacityAriaLabel = useMemo(() => [t('widgets.canvas.toolOptions.opacity')], [t]);
+  const sliderValue = useMemo(() => [Math.min(options.size, SLIDER_MAX_SIZE)], [options.size]);
+  const opacityValue = useMemo(() => [Math.round(options.opacity * 100)], [options.opacity]);
+  const numberInputValue = useMemo(() => String(Math.round(options.size)), [options.size]);
+
+  const setSize = useCallback(
+    (size: number) => engine.stores.eraserOptions.set({ ...options, size }),
+    [engine, options]
+  );
+
+  const onSliderSizeChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next !== undefined && Number.isFinite(next)) {
+        setSize(next);
+      }
+    },
+    [setSize]
+  );
+
+  const onNumberSizeChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setSize(valueAsNumber);
+      }
+    },
+    [setSize]
+  );
+
+  const onOpacityChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next !== undefined && Number.isFinite(next)) {
+        engine.stores.eraserOptions.set({ ...options, opacity: next / 100 });
+      }
+    },
+    [engine, options]
+  );
+
+  return (
+    <HStack align="center" gap="3">
+      <HStack align="center" gap="1.5">
+        <Slider
+          aria-label={sizeAriaLabel}
+          formatValue={formatSizePx}
+          max={SLIDER_MAX_SIZE}
+          min={MIN_BRUSH_SIZE}
+          size="sm"
+          value={sliderValue}
+          w="7rem"
+          onValueChange={onSliderSizeChange}
+        />
+        <NumberInput.Root
+          max={MAX_BRUSH_SIZE}
+          min={MIN_BRUSH_SIZE}
+          size="xs"
+          value={numberInputValue}
+          w="4.5rem"
+          onValueChange={onNumberSizeChange}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.eraserSize')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <Slider
+        aria-label={opacityAriaLabel}
+        formatValue={formatOpacityPercent}
+        max={100}
+        min={0}
+        size="sm"
+        value={opacityValue}
+        w="6rem"
+        onValueChange={onOpacityChange}
+      />
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/FilterOptions.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/FilterOptions.test.tsx
new file mode 100644
index 00000000000..4eb9c16e132
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/FilterOptions.test.tsx
@@ -0,0 +1,237 @@
+import type { LayerExportGuard } from '@workbench/canvas-engine/engine';
+import type { FilterOperationSessionState } from '@workbench/canvas-operations/filterOperationSession';
+import type { ComponentProps } from 'react';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createInstance } from 'i18next';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { I18nextProvider } from 'react-i18next';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  FilterOptionsBar,
+  getFilterActionEligibility,
+  getFilterSaveTargetEligibility,
+  getFilterStatusTranslationKey,
+} from './FilterOptions';
+
+const englishCatalogModules = import.meta.glob('../../../../../public/locales/en.json', {
+  eager: true,
+  import: 'default',
+});
+const enCatalog = Object.values(englishCatalogModules)[0] as Record<string, unknown>;
+const testI18n = createInstance();
+await testI18n.init({
+  initImmediate: false,
+  lng: 'en',
+  resources: { en: { translation: enCatalog } },
+});
+
+const state = (patch: Partial<FilterOperationSessionState> = {}): FilterOperationSessionState => ({
+  autoProcess: true,
+  draft: { settings: {}, type: 'canny_edge_detection' },
+  error: null,
+  initialFilter: null,
+  layerId: 'layer-1',
+  layerName: 'Portrait',
+  layerType: 'raster',
+  preview: null,
+  status: 'ready',
+  ...patch,
+});
+
+describe('getFilterActionEligibility', () => {
+  it('allows processing/reset/cancel before a preview exists', () => {
+    expect(getFilterActionEligibility(state())).toEqual({
+      canApply: false,
+      canCancel: true,
+      canEdit: true,
+      canProcess: true,
+      canReset: true,
+      canSave: false,
+    });
+  });
+
+  it('enables apply/save only for a ready preview', () => {
+    const preview = {
+      guard: {} as LayerExportGuard,
+      height: 10,
+      imageName: 'filtered',
+      origin: { x: 0, y: 0 },
+      rect: { height: 10, width: 10, x: 0, y: 0 },
+      width: 10,
+    } as NonNullable<FilterOperationSessionState['preview']>;
+    const eligibility = getFilterActionEligibility(state({ preview }));
+    expect(eligibility).toMatchObject({ canApply: true, canSave: true });
+    expect(getFilterSaveTargetEligibility(eligibility)).toEqual({ control: true, raster: true });
+  });
+
+  it.each(['processing', 'committing'] as const)('disables ordinary actions while %s', (status) => {
+    expect(getFilterActionEligibility(state({ status }))).toEqual({
+      canApply: false,
+      canCancel: true,
+      canEdit: false,
+      canProcess: false,
+      canReset: false,
+      canSave: false,
+    });
+  });
+
+  it('disables mutating actions under an external interaction lock but preserves Cancel', () => {
+    const eligibility = getFilterActionEligibility(state(), true);
+    expect(eligibility).toEqual({
+      canApply: false,
+      canCancel: true,
+      canEdit: false,
+      canProcess: false,
+      canReset: false,
+      canSave: false,
+    });
+    expect(getFilterSaveTargetEligibility(eligibility)).toEqual({ control: false, raster: false });
+  });
+
+  it('disables Process for Spandrel until a compatible model is selected', () => {
+    expect(
+      getFilterActionEligibility(state({ draft: { settings: { model: null }, type: 'spandrel_filter' } }))
+    ).toMatchObject({ canProcess: false });
+    expect(
+      getFilterActionEligibility(
+        state({
+          draft: {
+            settings: {
+              model: {
+                base: 'any',
+                hash: 'blake3-hash',
+                key: 'upscale',
+                name: 'Upscaler',
+                type: 'spandrel_image_to_image',
+              },
+            },
+            type: 'spandrel_filter',
+          },
+        })
+      )
+    ).toMatchObject({ canProcess: true });
+  });
+
+  it('disables Process for stale partial Spandrel identifiers', () => {
+    expect(
+      getFilterActionEligibility(
+        state({
+          draft: {
+            settings: {
+              model: { base: 'any', hash: '', key: 'upscale', name: 'Upscaler', type: 'spandrel_image_to_image' },
+            },
+            type: 'spandrel_filter',
+          },
+        })
+      )
+    ).toMatchObject({ canProcess: false });
+  });
+});
+
+describe('getFilterStatusTranslationKey', () => {
+  it('maps each session status to its message key', () => {
+    expect(getFilterStatusTranslationKey('processing')).toBe('widgets.layers.rasterFilter.running');
+    expect(getFilterStatusTranslationKey('committing')).toBe('widgets.layers.rasterFilter.statusCommitting');
+    expect(getFilterStatusTranslationKey('error')).toBe('widgets.layers.rasterFilter.statusError');
+    expect(getFilterStatusTranslationKey('ready')).toBe('widgets.layers.selectObject.statusReady');
+  });
+});
+
+describe('FilterOptionsBar', () => {
+  it('server-renders one row of controls in stable order without panel slots', () => {
+    const engine = {
+      cancelFilterOperation: vi.fn(),
+      commitFilterOperation: vi.fn(),
+      processFilterOperation: vi.fn(),
+      resetFilterOperation: vi.fn(),
+      setFilterOperationAutoProcess: vi.fn(),
+      updateFilterOperation: vi.fn(),
+    };
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(
+          I18nextProvider,
+          { i18n: testI18n },
+          createElement(FilterOptionsBar, {
+            engine: engine as never,
+            session: state({
+              draft: { settings: { high_threshold: 200, low_threshold: 100 }, type: 'canny_edge_detection' },
+            }),
+          })
+        )
+      )
+    );
+
+    expect(markup).not.toContain('data-slot="header"');
+    expect(markup).not.toContain('data-slot="body"');
+    expect(markup).not.toContain('data-slot="feedback"');
+    expect(markup).not.toContain('data-slot="footer"');
+    expect(markup).not.toContain('data-operation=');
+    expect(markup).toContain('Portrait · Raster layer');
+    expect(markup).toContain('role="status"');
+    expect(markup).toContain('aria-label="Save As"');
+    expect(markup.indexOf('>Filter<')).toBeLessThan(markup.indexOf('>Auto<'));
+    expect(markup.indexOf('>Auto<')).toBeLessThan(markup.indexOf('>Process<'));
+    expect(markup.indexOf('>Process<')).toBeLessThan(markup.indexOf('>Reset<'));
+    expect(markup.indexOf('>Reset<')).toBeLessThan(markup.indexOf('>Apply<'));
+    expect(markup.indexOf('>Apply<')).toBeLessThan(markup.indexOf('aria-label="Save As"'));
+    expect(markup.indexOf('aria-label="Save As"')).toBeLessThan(markup.indexOf('>Cancel<'));
+  });
+
+  it('server-renders disabled action buttons while processing', () => {
+    const engine = {
+      cancelFilterOperation: vi.fn(),
+      commitFilterOperation: vi.fn(),
+      processFilterOperation: vi.fn(),
+      resetFilterOperation: vi.fn(),
+      setFilterOperationAutoProcess: vi.fn(),
+      updateFilterOperation: vi.fn(),
+    };
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(
+          I18nextProvider,
+          { i18n: testI18n },
+          createElement(FilterOptionsBar, {
+            engine: engine as never,
+            session: state({ status: 'processing' }),
+          })
+        )
+      )
+    );
+
+    const processIdx = markup.indexOf('>Process<');
+    const processButtonTag = markup.slice(markup.lastIndexOf('<button', processIdx), processIdx);
+    expect(processButtonTag).toContain('disabled=""');
+    expect(processButtonTag).toContain('data-loading=""');
+
+    const autoIdx = markup.indexOf('>Auto<');
+    const autoButtonTag = markup.slice(markup.lastIndexOf('<button', autoIdx), autoIdx);
+    expect(autoButtonTag).toContain('disabled=""');
+  });
+
+  it('marks the Auto chip pressed state from the session', () => {
+    const render = (autoProcess: boolean) =>
+      renderToStaticMarkup(
+        createElement(
+          ChakraProvider,
+          { value: system } as ComponentProps<typeof ChakraProvider>,
+          createElement(
+            I18nextProvider,
+            { i18n: testI18n },
+            createElement(FilterOptionsBar, { engine: {} as never, session: state({ autoProcess }) })
+          )
+        )
+      );
+    expect(render(true)).toContain('aria-pressed="true"');
+    expect(render(false)).toContain('aria-pressed="false"');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/FilterOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/FilterOptions.tsx
new file mode 100644
index 00000000000..47769d4b401
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/FilterOptions.tsx
@@ -0,0 +1,240 @@
+/* oxlint-disable react-perf/jsx-no-new-function-as-prop */
+import type { FilterOperationSessionState } from '@workbench/canvas-operations/filterOperationSession';
+
+import { Flex, Group, HStack, IconButton, Menu, Portal, Text, VisuallyHidden } from '@chakra-ui/react';
+import { getCanvasOperations } from '@workbench/canvas-operations/createCanvasEngine';
+import { Button, MenuContent, Tooltip } from '@workbench/components/ui';
+import { makeImageDurable } from '@workbench/gallery/api';
+import {
+  buildFilterDefaults,
+  getFilterDefinition,
+  isFilterConfigValid,
+} from '@workbench/generation/canvas/filterGraphs';
+import { CanvasFloatingBar, CanvasFloatingBarDivider } from '@workbench/widgets/canvas/CanvasFloatingBar';
+import { useFilterSession } from '@workbench/widgets/canvas/engineStoreHooks';
+import { LayerFilterControls } from '@workbench/widgets/layers/LayerFilterControls';
+import { ChevronDownIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import type { CanvasOperationUIEngine } from './operationUIEngine';
+
+import { OperationStatusSlot } from './OperationStatusSlot';
+
+const FILTER_UPWARD_POSITIONING = { placement: 'top-end' } as const;
+
+export interface FilterActionEligibility {
+  canApply: boolean;
+  canCancel: boolean;
+  canEdit: boolean;
+  canProcess: boolean;
+  canReset: boolean;
+  canSave: boolean;
+}
+
+export const getFilterSaveTargetEligibility = (
+  eligibility: Pick<FilterActionEligibility, 'canSave'>
+): Record<'raster' | 'control', boolean> => ({
+  control: eligibility.canSave,
+  raster: eligibility.canSave,
+});
+
+export const getFilterActionEligibility = (
+  session: FilterOperationSessionState,
+  isExternalInteractionLocked = false
+): FilterActionEligibility => {
+  const busy = session.status === 'processing' || session.status === 'committing';
+  const actionsBlocked = busy || isExternalInteractionLocked;
+  const hasPreview = session.preview !== null && !actionsBlocked;
+  const isValid = isFilterConfigValid(session.draft.type, session.draft.settings);
+  return {
+    canApply: hasPreview,
+    canCancel: true,
+    canEdit: !actionsBlocked,
+    canProcess: !actionsBlocked && isValid,
+    canReset: !actionsBlocked,
+    canSave: hasPreview,
+  };
+};
+
+export const getFilterStatusTranslationKey = (status: FilterOperationSessionState['status']): string =>
+  status === 'processing'
+    ? 'widgets.layers.rasterFilter.running'
+    : status === 'committing'
+      ? 'widgets.layers.rasterFilter.statusCommitting'
+      : status === 'error'
+        ? 'widgets.layers.rasterFilter.statusError'
+        : 'widgets.layers.selectObject.statusReady';
+
+export const FilterOptionsBar = ({
+  engine,
+  session,
+  isExternalInteractionLocked = false,
+}: { engine: CanvasOperationUIEngine } & {
+  isExternalInteractionLocked?: boolean;
+  session: FilterOperationSessionState;
+}) => {
+  const { t } = useTranslation();
+  const eligibility = getFilterActionEligibility(session, isExternalInteractionLocked);
+  const saveTargetEligibility = getFilterSaveTargetEligibility(eligibility);
+  const sourceLabel = `${session.layerName} · ${t(`widgets.layers.selectObject.saveAs_${session.layerType}`)}`;
+  const isBusy = !session.error && (session.status === 'processing' || session.status === 'committing');
+  const setType = (type: string) => {
+    const definition = getFilterDefinition(type);
+    getCanvasOperations(engine).updateFilterOperation({
+      settings: definition ? buildFilterDefaults(definition) : {},
+      type,
+    });
+  };
+  const setSettings = (settings: Record<string, unknown>) => {
+    const current = getCanvasOperations(engine).stores.filterSession.get();
+    if (current) {
+      getCanvasOperations(engine).updateFilterOperation({ settings, type: current.draft.type });
+    }
+  };
+  const reset = () => {
+    const current = getCanvasOperations(engine).stores.filterSession.get();
+    if (!current) {
+      return;
+    }
+    const definition = getFilterDefinition(current.draft.type);
+    getCanvasOperations(engine).resetFilterOperation(definition ? buildFilterDefaults(definition) : {});
+  };
+
+  return (
+    <CanvasFloatingBar maxW="full">
+      <Flex
+        align="center"
+        aria-label={t('widgets.layers.rasterFilter.title')}
+        flexWrap="wrap"
+        gap="1"
+        minW="0"
+        role="group"
+      >
+        <Tooltip content={sourceLabel}>
+          <Text flexShrink="0" fontSize="xs" fontWeight="semibold" px="1" whiteSpace="nowrap">
+            {t('widgets.layers.rasterFilter.title')}
+            <VisuallyHidden>{sourceLabel}</VisuallyHidden>
+          </Text>
+        </Tooltip>
+        <CanvasFloatingBarDivider />
+        <Flex align="center" flexWrap="wrap" gap="2" minW="0">
+          <LayerFilterControls
+            disabled={!eligibility.canEdit}
+            filterType={session.draft.type}
+            focusFilter={false}
+            settings={session.draft.settings}
+            variant="operation"
+            onFilterTypeChange={setType}
+            onSettingsChange={setSettings}
+          />
+        </Flex>
+        <CanvasFloatingBarDivider />
+        <Tooltip content={t('widgets.layers.rasterFilter.autoProcessDescription')}>
+          <Button
+            aria-pressed={session.autoProcess}
+            disabled={!eligibility.canEdit}
+            size="xs"
+            variant={session.autoProcess ? 'solid' : 'ghost'}
+            onClick={() => getCanvasOperations(engine).setFilterOperationAutoProcess(!session.autoProcess)}
+          >
+            {t('widgets.layers.rasterFilter.autoProcess')}
+          </Button>
+        </Tooltip>
+        <CanvasFloatingBarDivider />
+        <OperationStatusSlot
+          errorDetail={null}
+          errorText={session.error}
+          isBusy={isBusy}
+          minW="0"
+          statusText={t(getFilterStatusTranslationKey(session.status))}
+          technicalDetailsLabel={t('widgets.layers.selectObject.technicalDetails')}
+        />
+        <CanvasFloatingBarDivider />
+        <HStack flexShrink="0" gap="1">
+          <Button
+            disabled={!eligibility.canProcess}
+            loading={session.status === 'processing'}
+            size="xs"
+            onClick={() => void getCanvasOperations(engine).processFilterOperation()}
+          >
+            {t('widgets.layers.selectObject.process')}
+          </Button>
+          <Button disabled={!eligibility.canReset} size="xs" variant="ghost" onClick={reset}>
+            {t('widgets.layers.selectObject.reset')}
+          </Button>
+          <Menu.Root positioning={FILTER_UPWARD_POSITIONING}>
+            <Group attached>
+              <Button
+                colorPalette="accent"
+                disabled={!eligibility.canApply}
+                loading={session.status === 'committing'}
+                roundedEnd="none"
+                size="xs"
+                onClick={() => void getCanvasOperations(engine).commitFilterOperation('apply', makeImageDurable)}
+              >
+                {t('common.apply')}
+              </Button>
+              <Menu.Trigger asChild>
+                <IconButton
+                  aria-label={t('widgets.layers.selectObject.saveAs')}
+                  colorPalette="accent"
+                  disabled={!eligibility.canSave}
+                  minW="0"
+                  roundedStart="none"
+                  size="xs"
+                  w="6"
+                >
+                  <ChevronDownIcon />
+                </IconButton>
+              </Menu.Trigger>
+            </Group>
+            <Portal>
+              <Menu.Positioner>
+                <MenuContent minW="11rem" py="1">
+                  <Menu.Item
+                    disabled={!saveTargetEligibility.raster}
+                    value="raster"
+                    onClick={() => void getCanvasOperations(engine).commitFilterOperation('raster', makeImageDurable)}
+                  >
+                    <Menu.ItemText>{t('widgets.layers.selectObject.saveAs_raster')}</Menu.ItemText>
+                  </Menu.Item>
+                  <Menu.Item
+                    disabled={!saveTargetEligibility.control}
+                    value="control"
+                    onClick={() => void getCanvasOperations(engine).commitFilterOperation('control', makeImageDurable)}
+                  >
+                    <Menu.ItemText>{t('widgets.layers.selectObject.saveAs_control')}</Menu.ItemText>
+                  </Menu.Item>
+                </MenuContent>
+              </Menu.Positioner>
+            </Portal>
+          </Menu.Root>
+          <Button
+            disabled={!eligibility.canCancel}
+            size="xs"
+            variant="ghost"
+            onClick={() => getCanvasOperations(engine).cancelFilterOperation()}
+          >
+            {t('common.cancel')}
+          </Button>
+        </HStack>
+      </Flex>
+    </CanvasFloatingBar>
+  );
+};
+
+export const FilterOptions = ({
+  engine,
+  isExternalInteractionLocked = false,
+}: {
+  engine: CanvasOperationUIEngine;
+  isExternalInteractionLocked?: boolean;
+}) => {
+  const session = useFilterSession(engine);
+  if (!session) {
+    return null;
+  }
+  return (
+    <FilterOptionsBar engine={engine} isExternalInteractionLocked={isExternalInteractionLocked} session={session} />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/GradientOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/GradientOptions.tsx
new file mode 100644
index 00000000000..7233a5810d7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/GradientOptions.tsx
@@ -0,0 +1,248 @@
+import type { NumberInput as ChakraNumberInput, SelectValueChangeDetails } from '@chakra-ui/react';
+import type { GradientStop, GradientToolOptions } from '@workbench/canvas-engine/engineStores';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import { createListCollection, HStack, NumberInput, Text } from '@chakra-ui/react';
+import { ColorPicker, Select } from '@workbench/components/ui';
+import { useGradientOptions } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+type GradientSource = Extract<CanvasLayerSourceContract, { type: 'gradient' }>;
+type GradientKind = GradientToolOptions['kind'];
+
+interface SelectedGradient {
+  id: string;
+  source: GradientSource;
+}
+
+const SELECT_POSITIONING = { placement: 'top-start', sameWidth: false } as const;
+const SELECT_TRIGGER_PROPS = { minW: '6rem' } as const;
+
+const clamp01 = (v: number): number => Math.min(1, Math.max(0, v));
+
+/** Splits a stop color into a `#rrggbb` part (for the picker) and an alpha in [0,1]. */
+const splitColor = (color: string): { rgb: string; alpha: number } => {
+  const match = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i.exec(color.trim());
+  if (match) {
+    return { alpha: match[2] !== undefined ? parseInt(match[2], 16) / 255 : 1, rgb: `#${match[1]}` };
+  }
+  return { alpha: 1, rgb: '#000000' };
+};
+
+/** Recombines a `#rrggbb` and an alpha into an `#rrggbbaa` string. */
+const joinColor = (rgb: string, alpha: number): string => {
+  const a = Math.round(clamp01(alpha) * 255)
+    .toString(16)
+    .padStart(2, '0');
+  return `${rgb}${a}`;
+};
+
+/**
+ * Gradient tool options: kind (linear/radial), angle (degrees), and a MINIMAL
+ * two-stop editor — start/end color with per-stop opacity. Edits set defaults
+ * for the next created gradient AND apply to a selected gradient layer (colors
+ * commit one history entry on interaction end; discrete edits commit at once).
+ * A full multi-stop editor is a follow-up.
+ */
+export const GradientOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const options = useGradientOptions(engine);
+
+  const selected = useActiveProjectSelector(
+    (project): SelectedGradient | null => {
+      const { document } = project.canvas;
+      const layer = document.selectedLayerId
+        ? document.layers.find((entry) => entry.id === document.selectedLayerId)
+        : undefined;
+      if (layer && layer.type === 'raster' && layer.source.type === 'gradient') {
+        return { id: layer.id, source: layer.source };
+      }
+      return null;
+    },
+    (a, b) => a?.id === b?.id && a?.source === b?.source
+  );
+
+  const kind: GradientKind = selected ? selected.source.kind : options.kind;
+  const angle = selected ? selected.source.angle : options.angle;
+  const stops = selected ? selected.source.stops : options.stops;
+  const start = stops[0] ?? { color: '#000000ff', offset: 0 };
+  const end = stops[stops.length - 1] ?? { color: '#ffffffff', offset: 1 };
+  const startParts = splitColor(start.color);
+  const endParts = splitColor(end.color);
+
+  const kindCollection = useMemo(
+    () =>
+      createListCollection<{ label: string; value: GradientKind }>({
+        items: [
+          { label: t('widgets.canvas.toolOptions.gradientLinear'), value: 'linear' },
+          { label: t('widgets.canvas.toolOptions.gradientRadial'), value: 'radial' },
+        ],
+      }),
+    [t]
+  );
+  const kindValue = useMemo(() => [kind], [kind]);
+
+  const applyGradient = useCallback(
+    (next: { kind: GradientKind; angle: number; stops: GradientStop[] }, commit: boolean) => {
+      engine.stores.gradientOptions.set({ angle: next.angle, kind: next.kind, stops: next.stops });
+      if (selected && commit) {
+        const before = selected.source;
+        const after: GradientSource = { ...before, angle: next.angle, kind: next.kind, stops: next.stops };
+        engine.layers.commitStructural(
+          t('widgets.canvas.toolOptions.gradientEdit'),
+          { id: selected.id, source: after, type: 'updateCanvasLayerSource' },
+          { id: selected.id, source: before, type: 'updateCanvasLayerSource' }
+        );
+      }
+    },
+    [engine, selected, t]
+  );
+
+  const setStopColor = useCallback(
+    (index: number, color: string, commit: boolean) => {
+      const nextStops = stops.map((stop, i) => (i === index ? { ...stop, color } : stop));
+      applyGradient({ angle, kind, stops: nextStops }, commit);
+    },
+    [angle, applyGradient, kind, stops]
+  );
+
+  const lastIndex = stops.length - 1;
+
+  const onKindChange = useCallback(
+    ({ value }: SelectValueChangeDetails<{ label: string; value: GradientKind }>) => {
+      const next = value[0] as GradientKind | undefined;
+      if (next && next !== kind) {
+        applyGradient({ angle, kind: next, stops: [...stops] }, true);
+      }
+    },
+    [angle, applyGradient, kind, stops]
+  );
+
+  const onAngleChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        applyGradient({ angle: Math.round(valueAsNumber), kind, stops: [...stops] }, true);
+      }
+    },
+    [applyGradient, kind, stops]
+  );
+
+  const onStartColorChange = useCallback(
+    (hex: string) => setStopColor(0, joinColor(hex, startParts.alpha), false),
+    [setStopColor, startParts.alpha]
+  );
+  const onStartColorEnd = useCallback(
+    (hex: string) => setStopColor(0, joinColor(hex, startParts.alpha), true),
+    [setStopColor, startParts.alpha]
+  );
+  const onStartOpacity = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setStopColor(0, joinColor(startParts.rgb, clamp01(valueAsNumber / 100)), true);
+      }
+    },
+    [setStopColor, startParts.rgb]
+  );
+
+  const onEndColorChange = useCallback(
+    (hex: string) => setStopColor(lastIndex, joinColor(hex, endParts.alpha), false),
+    [endParts.alpha, lastIndex, setStopColor]
+  );
+  const onEndColorEnd = useCallback(
+    (hex: string) => setStopColor(lastIndex, joinColor(hex, endParts.alpha), true),
+    [endParts.alpha, lastIndex, setStopColor]
+  );
+  const onEndOpacity = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setStopColor(lastIndex, joinColor(endParts.rgb, clamp01(valueAsNumber / 100)), true);
+      }
+    },
+    [endParts.rgb, lastIndex, setStopColor]
+  );
+
+  return (
+    <HStack align="center" gap="3">
+      <Select
+        aria-label={t('widgets.canvas.toolOptions.gradientKind')}
+        collection={kindCollection}
+        positioning={SELECT_POSITIONING}
+        size="xs"
+        triggerProps={SELECT_TRIGGER_PROPS}
+        value={kindValue}
+        valueText={t(
+          kind === 'radial' ? 'widgets.canvas.toolOptions.gradientRadial' : 'widgets.canvas.toolOptions.gradientLinear'
+        )}
+        onValueChange={onKindChange}
+      />
+
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.gradientAngle')}
+        </Text>
+        <NumberInput.Root
+          disabled={kind === 'radial'}
+          max={360}
+          min={-360}
+          size="xs"
+          value={String(Math.round(angle))}
+          w="4.5rem"
+          onValueChange={onAngleChange}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.gradientAngle')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.gradientStart')}
+        </Text>
+        <ColorPicker
+          aria-label={t('widgets.canvas.toolOptions.gradientStart')}
+          value={startParts.rgb}
+          onValueChange={onStartColorChange}
+          onValueChangeEnd={onStartColorEnd}
+        />
+        <NumberInput.Root
+          max={100}
+          min={0}
+          size="xs"
+          value={String(Math.round(startParts.alpha * 100))}
+          w="4rem"
+          onValueChange={onStartOpacity}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.gradientStartOpacity')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.gradientEnd')}
+        </Text>
+        <ColorPicker
+          aria-label={t('widgets.canvas.toolOptions.gradientEnd')}
+          value={endParts.rgb}
+          onValueChange={onEndColorChange}
+          onValueChangeEnd={onEndColorEnd}
+        />
+        <NumberInput.Root
+          max={100}
+          min={0}
+          size="xs"
+          value={String(Math.round(endParts.alpha * 100))}
+          w="4rem"
+          onValueChange={onEndOpacity}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.gradientEndOpacity')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/LassoOptions.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/LassoOptions.test.tsx
new file mode 100644
index 00000000000..1f87656704b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/LassoOptions.test.tsx
@@ -0,0 +1,92 @@
+import type { CanvasEngine } from '@workbench/canvas-operations/createCanvasEngine';
+import type { CanvasLayerContract, Project } from '@workbench/types';
+import type { ReactNode } from 'react';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createControlLayer, createEmptyPaintLayer } from '@workbench/widgets/layers/layerOps';
+import { createDraftProject } from '@workbench/workbenchState';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { LassoOptions } from './LassoOptions';
+
+interface CapturedButton {
+  children?: ReactNode;
+  disabled?: boolean;
+}
+
+const { activeProject, buttons } = vi.hoisted(() => ({
+  activeProject: { current: null as Project | null },
+  buttons: new Map<string, CapturedButton>(),
+}));
+
+vi.mock('@workbench/components/ui', () => ({
+  Button: (props: CapturedButton) => {
+    buttons.set(String(props.children), props);
+    return <button disabled={props.disabled}>{props.children}</button>;
+  },
+}));
+vi.mock('@workbench/widgets/canvas/engineStoreHooks', () => ({
+  useCanvasHasSelection: () => true,
+  useLassoOptions: () => ({ mode: 'replace' }),
+}));
+vi.mock('@workbench/WorkbenchContext', () => ({
+  useActiveProjectSelector: (selector: (project: Project) => unknown) => selector(activeProject.current!),
+}));
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const engine = {
+  deselect: vi.fn(),
+  eraseSelection: vi.fn(),
+  fillSelection: vi.fn(),
+  invertSelection: vi.fn(),
+  stores: { lassoOptions: { set: vi.fn() } },
+} as unknown as CanvasEngine;
+
+const renderLassoOptions = (layer: CanvasLayerContract): Map<string, CapturedButton> => {
+  const project = createDraftProject([]);
+  project.canvas.document = {
+    background: 'transparent',
+    bbox: { height: 100, width: 100, x: 0, y: 0 },
+    height: 100,
+    layers: [layer],
+    selectedLayerId: layer.id,
+    version: 2,
+    width: 100,
+  };
+  activeProject.current = project;
+  renderToStaticMarkup(
+    <ChakraProvider value={system}>
+      <LassoOptions engine={engine} />
+    </ChakraProvider>
+  );
+  return new Map(buttons);
+};
+
+beforeEach(() => {
+  buttons.clear();
+});
+
+describe('LassoOptions pixel target eligibility', () => {
+  const rasterPaint = createEmptyPaintLayer('Raster', 'raster');
+  const controlPaint = createControlLayer('Control', 'control');
+  const rasterImage: CanvasLayerContract = {
+    ...createEmptyPaintLayer('Raster image', 'raster-image'),
+    source: { image: { height: 10, imageName: 'raster-image', width: 10 }, type: 'image' },
+  };
+
+  it.each([
+    { disabled: false, layer: rasterPaint, scenario: 'raster paint' },
+    { disabled: false, layer: controlPaint, scenario: 'control paint' },
+    { disabled: true, layer: { ...controlPaint, isLocked: true }, scenario: 'locked control' },
+    { disabled: true, layer: { ...controlPaint, isEnabled: false }, scenario: 'disabled control' },
+    { disabled: true, layer: rasterImage, scenario: 'raster image' },
+  ])('sets Fill and Erase disabled=$disabled for $scenario', ({ disabled, layer }) => {
+    const rendered = renderLassoOptions(layer);
+    expect(rendered.get('widgets.canvas.toolOptions.fillSelection')?.disabled).toBe(disabled);
+    expect(rendered.get('widgets.canvas.toolOptions.eraseSelection')?.disabled).toBe(disabled);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/LassoOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/LassoOptions.tsx
new file mode 100644
index 00000000000..b6443911e0b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/LassoOptions.tsx
@@ -0,0 +1,94 @@
+import type { CanvasCoreStoreCapability, CanvasSelectionCapability } from '@workbench/canvas-engine/api';
+import type { SelectionOp } from '@workbench/canvas-engine/types';
+
+import { HStack, Text } from '@chakra-ui/react';
+import { isLayerPixelEditEligible } from '@workbench/canvas-engine/editing/controlPixelEdit';
+import { Button } from '@workbench/components/ui';
+import { useCanvasHasSelection, useLassoOptions } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+const OP_MODES: readonly SelectionOp[] = ['replace', 'add', 'subtract', 'intersect'];
+
+const OP_MODE_LABEL_KEYS: Record<SelectionOp, string> = {
+  add: 'widgets.canvas.toolOptions.selectionAdd',
+  intersect: 'widgets.canvas.toolOptions.selectionIntersect',
+  replace: 'widgets.canvas.toolOptions.selectionReplace',
+  subtract: 'widgets.canvas.toolOptions.selectionSubtract',
+};
+
+type LassoEngine = CanvasCoreStoreCapability & { readonly selection: CanvasSelectionCapability };
+
+/** One op-mode button with a stable click handler (avoids a per-render closure in the map). */
+const OpModeButton = ({ engine, mode, active }: { engine: LassoEngine; mode: SelectionOp; active: boolean }) => {
+  const { t } = useTranslation();
+  const onClick = useCallback(() => engine.stores.lassoOptions.set({ mode }), [engine, mode]);
+  return (
+    <Button aria-pressed={active} size="xs" variant={active ? 'solid' : 'ghost'} onClick={onClick}>
+      {t(OP_MODE_LABEL_KEYS[mode])}
+    </Button>
+  );
+};
+
+/**
+ * Lasso tool options: the boolean op-mode selector (replace / add / subtract /
+ * intersect — also settable transiently by holding shift / alt / shift+alt while
+ * committing a path) plus fill / erase / invert / deselect actions. Fill and
+ * erase require an eligible (unlocked, visible) paint layer selected; invert and
+ * deselect only require a live selection. Reads/writes the engine's transient
+ * selection state directly — no reducer mirror.
+ */
+export const LassoOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const options = useLassoOptions(engine);
+  const hasSelection = useCanvasHasSelection(engine);
+
+  // Whether the selected layer can receive a masked fill/erase (paint, unlocked,
+  // visible). Same eligibility the engine enforces; used to disable the buttons.
+  const canPaintTarget = useActiveProjectSelector((project) => {
+    const { document } = project.canvas;
+    const layer = document.selectedLayerId
+      ? document.layers.find((entry) => entry.id === document.selectedLayerId)
+      : undefined;
+    return isLayerPixelEditEligible(layer);
+  });
+
+  const onFill = useCallback(() => engine.selection.fillSelection(), [engine]);
+  const onErase = useCallback(() => engine.selection.eraseSelection(), [engine]);
+  const onInvert = useCallback(() => engine.selection.invertSelection(), [engine]);
+  const onDeselect = useCallback(() => engine.selection.deselect(), [engine]);
+
+  const canEdit = hasSelection && canPaintTarget;
+
+  return (
+    <HStack align="center" gap="3">
+      <HStack align="center" gap="1" role="group" aria-label={t('widgets.canvas.toolOptions.selectionMode')}>
+        {OP_MODES.map((mode) => (
+          <OpModeButton key={mode} active={options.mode === mode} engine={engine} mode={mode} />
+        ))}
+      </HStack>
+      <HStack align="center" gap="1">
+        <Button disabled={!canEdit} size="xs" variant="ghost" onClick={onFill}>
+          {t('widgets.canvas.toolOptions.fillSelection')}
+        </Button>
+        <Button disabled={!canEdit} size="xs" variant="ghost" onClick={onErase}>
+          {t('widgets.canvas.toolOptions.eraseSelection')}
+        </Button>
+        <Button disabled={!hasSelection} size="xs" variant="ghost" onClick={onInvert}>
+          {t('widgets.canvas.toolOptions.invertSelection')}
+        </Button>
+        <Button disabled={!hasSelection} size="xs" variant="ghost" onClick={onDeselect}>
+          {t('widgets.canvas.toolOptions.deselect')}
+        </Button>
+      </HStack>
+      {!hasSelection ? (
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.lassoHint')}
+        </Text>
+      ) : null}
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/MoveOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/MoveOptions.tsx
new file mode 100644
index 00000000000..ee2854b0a16
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/MoveOptions.tsx
@@ -0,0 +1,105 @@
+import type { NumberInput as ChakraNumberInput } from '@chakra-ui/react';
+
+import { HStack, NumberInput, Text } from '@chakra-ui/react';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+interface SelectedTransform {
+  id: string;
+  x: number;
+  y: number;
+}
+
+/**
+ * Move tool options: numeric X / Y position of the selected layer (document
+ * pixels). Reads the committed transform from the reducer and writes each edit
+ * back through the engine's structural history (so it shares the canvas undo
+ * stack with drags and nudges). Disabled with no selection.
+ */
+export const MoveOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const selected = useActiveProjectSelector(
+    (project): SelectedTransform | null => {
+      const { document } = project.canvas;
+      const layer = document.selectedLayerId
+        ? document.layers.find((entry) => entry.id === document.selectedLayerId)
+        : undefined;
+      return layer ? { id: layer.id, x: layer.transform.x, y: layer.transform.y } : null;
+    },
+    (a, b) => a?.id === b?.id && a?.x === b?.x && a?.y === b?.y
+  );
+
+  const commitAxis = useCallback(
+    (axis: 'x' | 'y', next: number) => {
+      if (!selected || next === selected[axis]) {
+        return;
+      }
+      const forwardTransform = axis === 'x' ? { x: next } : { y: next };
+      const inverseTransform = axis === 'x' ? { x: selected.x } : { y: selected.y };
+      engine.layers.commitStructural(
+        t('widgets.canvas.toolOptions.movePosition'),
+        { id: selected.id, patch: { transform: forwardTransform }, type: 'updateCanvasLayer' },
+        { id: selected.id, patch: { transform: inverseTransform }, type: 'updateCanvasLayer' }
+      );
+    },
+    [engine, selected, t]
+  );
+
+  const onXChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        commitAxis('x', Math.round(valueAsNumber));
+      }
+    },
+    [commitAxis]
+  );
+
+  const onYChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        commitAxis('y', Math.round(valueAsNumber));
+      }
+    },
+    [commitAxis]
+  );
+
+  const disabled = !selected;
+
+  return (
+    <HStack align="center" gap="3">
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.positionX')}
+        </Text>
+        <NumberInput.Root
+          disabled={disabled}
+          size="xs"
+          value={selected ? String(Math.round(selected.x)) : ''}
+          w="5rem"
+          onValueChange={onXChange}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.positionX')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.positionY')}
+        </Text>
+        <NumberInput.Root
+          disabled={disabled}
+          size="xs"
+          value={selected ? String(Math.round(selected.y)) : ''}
+          w="5rem"
+          onValueChange={onYChange}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.positionY')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/OperationStatusSlot.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/OperationStatusSlot.tsx
new file mode 100644
index 00000000000..61d34810d03
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/OperationStatusSlot.tsx
@@ -0,0 +1,71 @@
+import type { CSSProperties } from 'react';
+
+import { Flex, IconButton, Spinner } from '@chakra-ui/react';
+import { Tooltip } from '@workbench/components/ui';
+import { InfoIcon } from 'lucide-react';
+
+const ERROR_CLAMP_STYLE: CSSProperties = {
+  display: '-webkit-box',
+  overflow: 'hidden',
+  WebkitBoxOrient: 'vertical',
+  WebkitLineClamp: 2,
+};
+
+/**
+ * The always-mounted status slot shared by the canvas operation bars: reserves
+ * its width so status/error text appearing never shifts the surrounding
+ * controls, and keeps the polite live region in the tree before content
+ * arrives so announcements are reliable.
+ */
+export const OperationStatusSlot = ({
+  errorDetail,
+  errorText,
+  isBusy,
+  minW = '8rem',
+  statusText,
+  technicalDetailsLabel,
+}: {
+  errorDetail: string | null;
+  errorText: string | null;
+  isBusy: boolean;
+  minW?: string;
+  statusText: string;
+  technicalDetailsLabel: string;
+}) => {
+  const detail = errorDetail?.trim();
+  return (
+    <Flex
+      align="center"
+      color={errorText ? 'fg.error' : 'fg.muted'}
+      flex="0 1 auto"
+      fontSize="xs"
+      gap="1"
+      maxW="16rem"
+      minW={minW}
+    >
+      {errorText ? (
+        <>
+          <span aria-live="assertive" role="alert" style={ERROR_CLAMP_STYLE}>
+            {errorText}
+          </span>
+          {detail && detail !== errorText ? (
+            <Tooltip content={detail}>
+              <IconButton aria-label={technicalDetailsLabel} flexShrink="0" size="xs" tabIndex={0} variant="ghost">
+                <InfoIcon />
+              </IconButton>
+            </Tooltip>
+          ) : null}
+        </>
+      ) : (
+        <Flex align="center" aria-live="polite" gap="2" minW="0" role="status">
+          {isBusy ? (
+            <>
+              <Spinner flexShrink="0" size="xs" />
+              <span>{statusText}</span>
+            </>
+          ) : null}
+        </Flex>
+      )}
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/SamOptions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/SamOptions.test.ts
new file mode 100644
index 00000000000..fe01d9db196
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/SamOptions.test.ts
@@ -0,0 +1,508 @@
+import type { SamSessionSnapshot } from '@workbench/canvas-operations/operationTypes';
+import type { ComponentProps } from 'react';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createInstance } from 'i18next';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { I18nextProvider } from 'react-i18next';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  getSamPanelViewModel,
+  getSamActionEligibility,
+  getSamActionHandlers,
+  getSamErrorTranslationKey,
+  getSamStatusTranslationKey,
+  keepSamImageIntermediate,
+  SamPromptBody,
+  SamModeToggle,
+  SamOptionsBar,
+  SamStatusSlot,
+  SamVisualInput,
+} from './SamOptions';
+
+const englishCatalogModules = import.meta.glob('../../../../../public/locales/en.json', {
+  eager: true,
+  import: 'default',
+});
+const enCatalog = Object.values(englishCatalogModules)[0] as {
+  common: Record<string, string>;
+  widgets: { layers: { selectObject: Record<string, string> } };
+};
+const en = enCatalog;
+const testI18n = createInstance();
+await testI18n.init({
+  initImmediate: false,
+  lng: 'en',
+  resources: { en: { translation: enCatalog } },
+  showSupportNotice: false,
+});
+
+const snapshot = (overrides: Partial<SamSessionSnapshot> = {}): SamSessionSnapshot => ({
+  applyPolygonRefinement: false,
+  autoProcess: false,
+  error: null,
+  hasPreview: false,
+  input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' },
+  invert: false,
+  isolatedPreview: true,
+  layerName: 'Layer 1',
+  layerType: 'raster',
+  model: 'segment-anything-2-large',
+  pointLabel: 'include',
+  sourceRect: { height: 20, width: 20, x: 0, y: 0 },
+  status: 'ready',
+  ...overrides,
+});
+
+describe('getSamActionEligibility', () => {
+  it('requires valid visual or prompt input before processing', () => {
+    expect(getSamActionEligibility(snapshot())).toMatchObject({ canProcess: false });
+    expect(
+      getSamActionEligibility(
+        snapshot({ input: { bbox: null, excludePoints: [], includePoints: [{ x: 1, y: 2 }], type: 'visual' } })
+      )
+    ).toMatchObject({ canProcess: true });
+    expect(getSamActionEligibility(snapshot({ input: { prompt: '  object  ', type: 'prompt' } }))).toMatchObject({
+      canProcess: true,
+    });
+  });
+
+  it('permits Apply and Save only for a current ready preview', () => {
+    expect(getSamActionEligibility(snapshot({ hasPreview: true }))).toMatchObject({ canApply: true, canSave: true });
+    expect(getSamActionEligibility(snapshot({ hasPreview: true, status: 'processing-sam' }))).toMatchObject({
+      canApply: false,
+      canProcess: false,
+      canSave: false,
+    });
+    expect(getSamActionEligibility(snapshot({ hasPreview: false }))).toMatchObject({
+      canApply: false,
+      canSave: false,
+    });
+    expect(
+      getSamActionEligibility(
+        snapshot({ error: { code: 'unknown', detail: 'commit failed' }, hasPreview: true, status: 'error' })
+      )
+    ).toMatchObject({
+      canApply: true,
+      canSave: true,
+    });
+  });
+
+  it('keeps Cancel available while processing and Reset available for every active session', () => {
+    expect(getSamActionEligibility(snapshot({ status: 'processing-sam' }))).toMatchObject({
+      canCancel: true,
+      canReset: true,
+    });
+    expect(getSamActionEligibility(snapshot({ error: { code: 'not-ready' }, status: 'error' }))).toMatchObject({
+      canReset: true,
+    });
+    expect(getSamActionEligibility(snapshot({ status: 'ready' }))).toMatchObject({ canReset: true });
+  });
+
+  it('disables every mutating control while committing and keeps Cancel available', () => {
+    const committing = snapshot({ hasPreview: true, status: 'committing' as never });
+
+    expect(getSamActionEligibility(committing)).toEqual({
+      canApply: false,
+      canCancel: true,
+      canEditInputs: false,
+      canProcess: false,
+      canReset: false,
+      canSave: false,
+    });
+  });
+
+  it('disables mutating actions under an external interaction lock but preserves Cancel', () => {
+    expect(getSamActionEligibility(snapshot({ hasPreview: true }), true)).toEqual({
+      canApply: false,
+      canCancel: true,
+      canEditInputs: false,
+      canProcess: false,
+      canReset: false,
+      canSave: false,
+    });
+  });
+});
+
+describe('getSamPanelViewModel', () => {
+  it('derives visual counts, bbox state, and a localized layer source label', () => {
+    expect(
+      getSamPanelViewModel(
+        snapshot({
+          input: {
+            bbox: { height: 8, width: 12, x: 1, y: 2 },
+            excludePoints: [{ x: 3, y: 4 }],
+            includePoints: [
+              { x: 1, y: 2 },
+              { x: 2, y: 3 },
+            ],
+            type: 'visual',
+          },
+          layerName: 'Subject',
+          sourceRect: { height: 768, width: 1024, x: 64, y: 32 },
+        }),
+        (layerName, width, height) => `${layerName} at ${width} by ${height}`
+      )
+    ).toEqual({
+      bboxActive: true,
+      excludeCount: 1,
+      includeCount: 2,
+      sourceLabel: 'Subject at 1024 by 768',
+    });
+  });
+
+  it('returns zero visual counts for prompt mode', () => {
+    expect(
+      getSamPanelViewModel(
+        snapshot({ input: { prompt: 'cat', type: 'prompt' } }),
+        (layerName, w, h) => `${layerName} ${w} × ${h}`
+      )
+    ).toEqual({
+      bboxActive: false,
+      excludeCount: 0,
+      includeCount: 0,
+      sourceLabel: 'Layer 1 20 × 20',
+    });
+  });
+});
+
+describe('SamModeToggle', () => {
+  it('uses ordinary pressed buttons without incomplete tab relationships', () => {
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(SamModeToggle, {
+          disabled: false,
+          mode: 'visual',
+          onPrompt: () => undefined,
+          onVisual: () => undefined,
+          promptLabel: 'Prompt',
+          visualLabel: 'Visual',
+        })
+      )
+    );
+
+    expect(markup).toContain('aria-label="Selection mode"');
+    expect(markup).toContain('aria-pressed="true"');
+    expect(markup).toContain('aria-pressed="false"');
+    expect(markup).not.toContain('role="tab"');
+    expect(markup).not.toContain('aria-controls');
+  });
+});
+
+describe('SamStatusSlot', () => {
+  it.each([
+    'ready',
+    'scheduled',
+    'preparing-source',
+    'uploading',
+    'processing-sam',
+    'rendering-preview',
+    'committing',
+    'error',
+  ] as const)('maps %s to localized user-facing copy without exposing the identifier', (status) => {
+    const key = getSamStatusTranslationKey(status).split('.').at(-1);
+    const copy = key ? en.widgets.layers.selectObject[key] : undefined;
+    expect(copy).toBeTypeOf('string');
+    expect(copy).not.toContain(status);
+  });
+
+  it.each([
+    'invalid',
+    'not-ready',
+    'empty',
+    'upload',
+    'queue',
+    'no-output',
+    'reconcile',
+    'output-dimension',
+    'decode',
+    'locked',
+    'unknown',
+  ] as const)('maps %s errors to localized primary copy', (code) => {
+    const key = getSamErrorTranslationKey(code).split('.').at(-1);
+    const copy = key ? en.widgets.layers.selectObject[key] : undefined;
+    expect(copy).toBeTypeOf('string');
+    expect(copy).not.toBe(code);
+  });
+
+  it('server-renders a localized phase with polite status semantics', () => {
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(SamStatusSlot, {
+          error: null,
+          errorText: null,
+          isBusy: true,
+          statusText: 'Rendering object preview…',
+          technicalDetailsLabel: 'Technical details',
+        })
+      )
+    );
+
+    expect(markup).toContain('role="status"');
+    expect(markup).toContain('aria-live="polite"');
+    expect(markup).toContain('Rendering object preview…');
+    expect(markup).not.toContain('role="alert"');
+  });
+
+  it('reserves an empty polite live region when ready without an error', () => {
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(SamStatusSlot, {
+          error: null,
+          errorText: null,
+          isBusy: false,
+          statusText: 'Ready',
+          technicalDetailsLabel: 'Technical details',
+        })
+      )
+    );
+
+    expect(markup).toContain('role="status"');
+    expect(markup).toContain('aria-live="polite"');
+    expect(markup).not.toContain('Ready');
+    expect(markup).not.toContain('role="alert"');
+  });
+
+  it('server-renders a known localized error as the assertive primary message', () => {
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(SamStatusSlot, {
+          error: { code: 'decode' },
+          errorText: 'The object preview could not be decoded.',
+          isBusy: false,
+          statusText: 'Select Object needs attention.',
+          technicalDetailsLabel: 'Technical details',
+        })
+      )
+    );
+
+    expect(markup).toContain('role="alert"');
+    expect(markup).toContain('aria-live="assertive"');
+    expect(markup).toContain('The object preview could not be decoded.');
+  });
+
+  it('server-renders unknown diagnostics only after a localized primary message', () => {
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(SamStatusSlot, {
+          error: { code: 'unknown', detail: 'GPU worker disconnected' },
+          errorText: 'Select Object could not finish.',
+          isBusy: false,
+          statusText: 'Select Object needs attention.',
+          technicalDetailsLabel: 'Technical details',
+        })
+      )
+    );
+
+    expect(markup).not.toContain('title=');
+    expect(markup).toContain('aria-label="Technical details"');
+    expect(markup).toContain('tabindex="0"');
+    expect(markup).toContain('data-scope="tooltip"');
+    expect(markup).not.toContain('>GPU worker disconnected<');
+    expect(markup).toContain('role="alert"');
+  });
+
+  it('server-renders a localized queue error before its backend exception type', () => {
+    const errorText = en.widgets.layers.selectObject.errorQueue;
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(SamStatusSlot, {
+          error: { code: 'queue', detail: 'AttributeError' },
+          errorText,
+          isBusy: false,
+          statusText: 'Select Object needs attention.',
+          technicalDetailsLabel: 'Technical details',
+        })
+      )
+    );
+
+    expect(markup).not.toContain('title=');
+    expect(markup).toContain('aria-label="Technical details"');
+    expect(markup).toContain('data-scope="tooltip"');
+    expect(markup).not.toContain('>AttributeError<');
+    expect(markup).toContain('role="alert"');
+  });
+});
+
+describe('single-row SAM inputs', () => {
+  it('uses bar-scale copy including the settings popover and bbox indicator labels', () => {
+    expect(en.widgets.layers.selectObject.model).toBe('Model');
+    expect(en.widgets.layers.selectObject.refine).toBe('Refine');
+    expect(en.widgets.layers.selectObject.autoProcess).toBe('Auto Process');
+    expect(en.widgets.layers.selectObject.isolatedPreview).toBe('Isolated Preview');
+    expect(en.widgets.layers.selectObject.settings).toBe('Select Object settings');
+    expect(en.widgets.layers.selectObject.bbox).toBe('BBox');
+    expect(en.widgets.layers.selectObject.technicalDetails).toBe('Technical details');
+    expect(en.widgets.layers.selectObject.sourceLayerLabel).toContain('{{name}}');
+    expect(en.widgets.layers.selectObject.sourceLayerLabel).toContain('{{width}}');
+    expect(en.widgets.layers.selectObject.saveAs_selection).toBe('Selection');
+    expect(en.widgets.layers.selectObject.includeCount).toBe('Include {{count}}');
+    expect(en.widgets.layers.selectObject.excludeCount).toBe('Exclude {{count}}');
+    expect(en.widgets.layers.selectObject).not.toHaveProperty('autoProcessCompact');
+    expect(en.widgets.layers.selectObject).not.toHaveProperty('isolatedPreviewCompact');
+  });
+
+  it('server-renders Prompt as a one-line accessible input', () => {
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(SamPromptBody, { disabled: false, prompt: 'cat', onChange: () => undefined })
+      )
+    );
+
+    expect(markup).toContain('<input');
+    expect(markup).toContain('aria-label=');
+    expect(markup).toContain('aria-describedby="sam-prompt-guidance"');
+    expect(markup).toContain('id="sam-prompt-guidance"');
+    expect(markup).toContain('placeholder=');
+    expect(markup).not.toContain('<textarea');
+  });
+
+  it('server-renders the visual controls as one labeled group without permanent guidance', () => {
+    const session = snapshot({
+      input: {
+        bbox: { height: 8, width: 12, x: 1, y: 2 },
+        excludePoints: [{ x: 3, y: 4 }],
+        includePoints: [{ x: 1, y: 2 }],
+        type: 'visual',
+      },
+    });
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(
+          I18nextProvider,
+          { i18n: testI18n },
+          createElement(SamVisualInput, {
+            disabled: false,
+            onExclude: () => undefined,
+            onInclude: () => undefined,
+            pointLabel: session.pointLabel,
+            viewModel: getSamPanelViewModel(session, (layerName, width, height) => `${layerName} ${width} × ${height}`),
+          })
+        )
+      )
+    );
+
+    expect(markup).toContain('role="group"');
+    expect(markup).toContain('aria-pressed="true"');
+    expect(markup).not.toContain('title=');
+    expect(markup).toContain('aria-describedby="sam-visual-guidance"');
+    expect(markup).toContain('id="sam-visual-guidance"');
+    expect(markup).toContain('Include 1');
+    expect(markup).toContain('Exclude 1');
+    expect(markup).toContain('Bounding box active');
+    expect(markup).not.toContain('>widgets.layers.selectObject.pointType<');
+  });
+});
+
+describe('getSamActionHandlers', () => {
+  it('keeps adopted SAM images intermediate', async () => {
+    await expect(keepSamImageIntermediate('sam-selection.png')).resolves.toBeUndefined();
+  });
+
+  it('wires every bar action and save target to the engine', () => {
+    const operations = {
+      applySelectObjectSession: vi.fn(),
+      cancelSelectObjectSession: vi.fn(),
+      processSelectObjectSession: vi.fn(),
+      resetSelectObjectSession: vi.fn(),
+      saveSelectObjectSession: vi.fn(),
+    };
+    const actions = getSamActionHandlers(operations as never);
+
+    actions.process();
+    actions.reset();
+    actions.apply();
+    actions.save('raster');
+    actions.save('control');
+    actions.save('inpaint_mask');
+    actions.save('regional_guidance');
+    actions.save('selection');
+    actions.cancel();
+
+    expect(operations.processSelectObjectSession).toHaveBeenCalledOnce();
+    expect(operations.resetSelectObjectSession).toHaveBeenCalledOnce();
+    expect(operations.applySelectObjectSession).toHaveBeenCalledOnce();
+    expect(operations.applySelectObjectSession).toHaveBeenCalledWith(keepSamImageIntermediate);
+    expect(operations.processSelectObjectSession.mock.invocationCallOrder[0]).toBeLessThan(
+      operations.resetSelectObjectSession.mock.invocationCallOrder[0] as number
+    );
+    expect(operations.resetSelectObjectSession.mock.invocationCallOrder[0]).toBeLessThan(
+      operations.applySelectObjectSession.mock.invocationCallOrder[0] as number
+    );
+    expect(operations.saveSelectObjectSession).toHaveBeenCalledWith('raster', keepSamImageIntermediate);
+    expect(operations.saveSelectObjectSession).toHaveBeenCalledWith('control', keepSamImageIntermediate);
+    expect(operations.saveSelectObjectSession).toHaveBeenCalledWith('inpaint_mask', keepSamImageIntermediate);
+    expect(operations.saveSelectObjectSession).toHaveBeenCalledWith('regional_guidance', keepSamImageIntermediate);
+    expect(operations.saveSelectObjectSession).toHaveBeenCalledWith('selection', keepSamImageIntermediate);
+    expect(operations.cancelSelectObjectSession).toHaveBeenCalledOnce();
+  });
+});
+
+describe('SamOptionsBar', () => {
+  it('server-renders one row of controls in stable order without panel slots', () => {
+    const engine = {
+      operations: {
+        applySelectObjectSession: vi.fn(),
+        cancelSelectObjectSession: vi.fn(),
+        processSelectObjectSession: vi.fn(),
+        resetSelectObjectSession: vi.fn(),
+        saveSelectObjectSession: vi.fn(),
+        updateSelectObjectSession: vi.fn(),
+      },
+    };
+    const markup = renderToStaticMarkup(
+      createElement(
+        ChakraProvider,
+        { value: system } as ComponentProps<typeof ChakraProvider>,
+        createElement(
+          I18nextProvider,
+          { i18n: testI18n },
+          createElement(SamOptionsBar, {
+            engine: engine as never,
+            operations: engine.operations as never,
+            session: snapshot({
+              hasPreview: true,
+              input: { bbox: null, excludePoints: [], includePoints: [{ x: 4, y: 5 }], type: 'visual' },
+              sourceRect: { height: 768, width: 1024, x: 0, y: 0 },
+            }),
+          })
+        )
+      )
+    );
+
+    expect(markup).not.toContain('data-slot="header"');
+    expect(markup).not.toContain('data-slot="body"');
+    expect(markup).not.toContain('data-slot="footer"');
+    expect(markup).not.toContain('data-operation=');
+    expect(markup).toContain('Layer 1 · Raster layer · 1024 × 768');
+    expect(markup).toContain('aria-label="Select Object settings"');
+    expect(markup).toContain('aria-label="Save As"');
+    expect(markup.indexOf('>Visual<')).toBeLessThan(markup.indexOf('Include 1'));
+    expect(markup.indexOf('Include 1')).toBeLessThan(markup.indexOf('>Invert<'));
+    expect(markup.indexOf('>Invert<')).toBeLessThan(markup.indexOf('aria-label="Select Object settings"'));
+    expect(markup.indexOf('aria-label="Select Object settings"')).toBeLessThan(markup.indexOf('>Process<'));
+    expect(markup.indexOf('>Process<')).toBeLessThan(markup.indexOf('>Reset<'));
+    expect(markup.indexOf('>Reset<')).toBeLessThan(markup.indexOf('>Apply<'));
+    expect(markup.indexOf('>Apply<')).toBeLessThan(markup.indexOf('aria-label="Save As"'));
+    expect(markup.indexOf('aria-label="Save As"')).toBeLessThan(markup.indexOf('>Cancel<'));
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/SamOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/SamOptions.tsx
new file mode 100644
index 00000000000..4b1fe052b24
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/SamOptions.tsx
@@ -0,0 +1,596 @@
+/* oxlint-disable react-perf/jsx-no-jsx-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-object-as-prop */
+import type { CanvasOperationCapability, SelectObjectSaveTarget } from '@workbench/canvas-operations/api';
+import type {
+  SamSessionError,
+  SamSessionErrorCode,
+  SamSessionSnapshot,
+} from '@workbench/canvas-operations/operationTypes';
+import type { SamModel } from '@workbench/generation/canvas/samGraph';
+import type { ChangeEvent } from 'react';
+
+import {
+  Flex,
+  Group,
+  HStack,
+  IconButton,
+  Input,
+  Menu,
+  NativeSelect,
+  Popover,
+  Portal,
+  Stack,
+  Switch,
+  Text,
+  VisuallyHidden,
+} from '@chakra-ui/react';
+import { getCanvasOperations } from '@workbench/canvas-operations/createCanvasEngine';
+import { Button, MenuContent, Tooltip } from '@workbench/components/ui';
+import { isSamDocumentInputValid } from '@workbench/generation/canvas/samGraph';
+import { CanvasFloatingBar, CanvasFloatingBarDivider } from '@workbench/widgets/canvas/CanvasFloatingBar';
+import { useSamSession } from '@workbench/widgets/canvas/engineStoreHooks';
+import { ChevronDownIcon, SettingsIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import type { CanvasOperationUIEngine } from './operationUIEngine';
+
+import { OperationStatusSlot } from './OperationStatusSlot';
+
+export interface SamActionEligibility {
+  canApply: boolean;
+  canCancel: boolean;
+  canEditInputs: boolean;
+  canProcess: boolean;
+  canReset: boolean;
+  canSave: boolean;
+}
+
+export interface SamPanelViewModel {
+  bboxActive: boolean;
+  excludeCount: number;
+  includeCount: number;
+  sourceLabel: string;
+}
+
+const SAM_PROMPT_GUIDANCE_ID = 'sam-prompt-guidance';
+const SAM_VISUAL_GUIDANCE_ID = 'sam-visual-guidance';
+
+const SAM_UPWARD_POSITIONING = { placement: 'top-end' } as const;
+
+const SAM_STATUS_TRANSLATION_KEYS: Record<SamSessionSnapshot['status'], string> = {
+  committing: 'widgets.layers.selectObject.statusCommitting',
+  error: 'widgets.layers.selectObject.statusError',
+  'preparing-source': 'widgets.layers.selectObject.statusPreparingSource',
+  'processing-sam': 'widgets.layers.selectObject.statusProcessingSam',
+  ready: 'widgets.layers.selectObject.statusReady',
+  'rendering-preview': 'widgets.layers.selectObject.statusRenderingPreview',
+  scheduled: 'widgets.layers.selectObject.statusScheduled',
+  uploading: 'widgets.layers.selectObject.statusUploading',
+};
+
+const SAM_ERROR_TRANSLATION_KEYS: Record<SamSessionErrorCode, string> = {
+  decode: 'widgets.layers.selectObject.errorDecode',
+  empty: 'widgets.layers.selectObject.errorEmpty',
+  invalid: 'widgets.layers.selectObject.errorInvalid',
+  locked: 'widgets.layers.selectObject.errorLocked',
+  'no-output': 'widgets.layers.selectObject.errorNoOutput',
+  'not-ready': 'widgets.layers.selectObject.errorNotReady',
+  'output-dimension': 'widgets.layers.selectObject.errorOutputDimension',
+  queue: 'widgets.layers.selectObject.errorQueue',
+  reconcile: 'widgets.layers.selectObject.errorReconcile',
+  unknown: 'widgets.layers.selectObject.errorUnknown',
+  upload: 'widgets.layers.selectObject.errorUpload',
+};
+
+const SAVE_TARGETS: readonly SelectObjectSaveTarget[] = [
+  'selection',
+  'raster',
+  'control',
+  'inpaint_mask',
+  'regional_guidance',
+];
+
+const isSamProcessingStatus = (status: SamSessionSnapshot['status']): boolean =>
+  status === 'preparing-source' ||
+  status === 'uploading' ||
+  status === 'processing-sam' ||
+  status === 'rendering-preview';
+
+export const getSamStatusTranslationKey = (status: SamSessionSnapshot['status']): string =>
+  SAM_STATUS_TRANSLATION_KEYS[status];
+
+export const getSamErrorTranslationKey = (code: SamSessionErrorCode): string => SAM_ERROR_TRANSLATION_KEYS[code];
+
+export const getSamPanelViewModel = (
+  session: SamSessionSnapshot,
+  formatSourceLabel: (layerName: string, width: number, height: number) => string
+): SamPanelViewModel => ({
+  bboxActive: session.input.type === 'visual' && session.input.bbox !== null,
+  excludeCount: session.input.type === 'visual' ? session.input.excludePoints.length : 0,
+  includeCount: session.input.type === 'visual' ? session.input.includePoints.length : 0,
+  sourceLabel: formatSourceLabel(session.layerName, session.sourceRect.width, session.sourceRect.height),
+});
+
+/**
+ * SAM-flavored adapter over {@link OperationStatusSlot}: the always-mounted
+ * status slot that reserves its width so status/error text appearing never
+ * shifts the surrounding controls.
+ */
+export const SamStatusSlot = ({
+  error,
+  errorText,
+  isBusy,
+  statusText,
+  technicalDetailsLabel,
+}: {
+  error: SamSessionError | null;
+  errorText: string | null;
+  isBusy: boolean;
+  statusText: string;
+  technicalDetailsLabel: string;
+}) => (
+  <OperationStatusSlot
+    errorDetail={error?.detail ?? null}
+    errorText={error && errorText ? errorText : null}
+    isBusy={isBusy}
+    statusText={statusText}
+    technicalDetailsLabel={technicalDetailsLabel}
+  />
+);
+
+/** Legacy parity: canvas adoption keeps the SAM result intermediate and out of the gallery. */
+export const keepSamImageIntermediate = (_imageName: string): Promise<void> => Promise.resolve();
+
+export const getSamActionHandlers = (operations: CanvasOperationCapability) => ({
+  apply: () => void operations.applySelectObjectSession(keepSamImageIntermediate),
+  cancel: () => operations.cancelSelectObjectSession(),
+  process: () => void operations.processSelectObjectSession(),
+  reset: () => operations.resetSelectObjectSession(),
+  save: (target: SelectObjectSaveTarget) => void operations.saveSelectObjectSession(target, keepSamImageIntermediate),
+});
+
+export const getSamActionEligibility = (
+  session: SamSessionSnapshot,
+  isExternalInteractionLocked = false
+): SamActionEligibility => {
+  const isProcessing = isSamProcessingStatus(session.status);
+  const actionsBlocked = session.status === 'committing' || isExternalInteractionLocked;
+  const hasReadyPreview = session.hasPreview && !isProcessing && !actionsBlocked;
+  return {
+    canApply: hasReadyPreview,
+    canCancel: true,
+    canEditInputs: !actionsBlocked,
+    canProcess: !isProcessing && !actionsBlocked && isSamDocumentInputValid(session.input),
+    canReset: !actionsBlocked,
+    canSave: hasReadyPreview,
+  };
+};
+
+export const SamModeToggle = ({
+  disabled,
+  groupLabel = 'Selection mode',
+  mode,
+  onPrompt,
+  onVisual,
+  promptLabel,
+  visualLabel,
+}: {
+  disabled: boolean;
+  groupLabel?: string;
+  mode: SamSessionSnapshot['input']['type'];
+  onPrompt(): void;
+  onVisual(): void;
+  promptLabel: string;
+  visualLabel: string;
+}) => (
+  <Group aria-label={groupLabel} attached flexShrink="0" role="group">
+    <Button
+      aria-pressed={mode === 'visual'}
+      disabled={disabled}
+      size="xs"
+      variant={mode === 'visual' ? 'solid' : 'ghost'}
+      onClick={onVisual}
+    >
+      {visualLabel}
+    </Button>
+    <Button
+      aria-pressed={mode === 'prompt'}
+      disabled={disabled}
+      size="xs"
+      variant={mode === 'prompt' ? 'solid' : 'ghost'}
+      onClick={onPrompt}
+    >
+      {promptLabel}
+    </Button>
+  </Group>
+);
+
+export const SamVisualInput = ({
+  disabled,
+  pointLabel,
+  viewModel,
+  onExclude,
+  onInclude,
+}: {
+  disabled: boolean;
+  pointLabel: SamSessionSnapshot['pointLabel'];
+  viewModel: SamPanelViewModel;
+  onExclude(): void;
+  onInclude(): void;
+}) => {
+  const { t } = useTranslation();
+  const bboxText = viewModel.bboxActive
+    ? t('widgets.layers.selectObject.bboxActive')
+    : t('widgets.layers.selectObject.bboxInactive');
+  return (
+    <Flex
+      align="center"
+      aria-describedby={SAM_VISUAL_GUIDANCE_ID}
+      aria-label={t('widgets.layers.selectObject.pointType')}
+      gap="1"
+      minW="0"
+      role="group"
+    >
+      <VisuallyHidden id={SAM_VISUAL_GUIDANCE_ID}>{t('widgets.layers.selectObject.visualGuidance')}</VisuallyHidden>
+      <Group attached flexShrink="0">
+        <Button
+          aria-pressed={pointLabel === 'include'}
+          disabled={disabled}
+          size="xs"
+          variant={pointLabel === 'include' ? 'solid' : 'outline'}
+          onClick={onInclude}
+        >
+          <Text as="span" fontVariantNumeric="tabular-nums">
+            {t('widgets.layers.selectObject.includeCount', { count: viewModel.includeCount })}
+          </Text>
+        </Button>
+        <Button
+          aria-pressed={pointLabel === 'exclude'}
+          disabled={disabled}
+          size="xs"
+          variant={pointLabel === 'exclude' ? 'solid' : 'outline'}
+          onClick={onExclude}
+        >
+          <Text as="span" fontVariantNumeric="tabular-nums">
+            {t('widgets.layers.selectObject.excludeCount', { count: viewModel.excludeCount })}
+          </Text>
+        </Button>
+      </Group>
+      <Tooltip content={bboxText}>
+        <Text
+          color={viewModel.bboxActive ? 'fg' : 'fg.subtle'}
+          fontSize="2xs"
+          fontWeight="medium"
+          px="1"
+          whiteSpace="nowrap"
+        >
+          <span aria-hidden="true">{t('widgets.layers.selectObject.bbox')}</span>
+          <VisuallyHidden>{bboxText}</VisuallyHidden>
+        </Text>
+      </Tooltip>
+    </Flex>
+  );
+};
+
+export const SamPromptBody = ({
+  disabled,
+  prompt,
+  onChange,
+}: {
+  disabled: boolean;
+  prompt: string;
+  onChange(event: ChangeEvent<HTMLInputElement>): void;
+}) => {
+  const { t } = useTranslation();
+  return (
+    <>
+      <Input
+        aria-describedby={SAM_PROMPT_GUIDANCE_ID}
+        aria-label={t('widgets.layers.selectObject.prompt')}
+        autoComplete="off"
+        disabled={disabled}
+        flex="0 1 13rem"
+        h="8"
+        minW="6rem"
+        placeholder={t('widgets.layers.selectObject.promptGuidance')}
+        size="xs"
+        value={prompt}
+        w="13rem"
+        onChange={onChange}
+      />
+      <VisuallyHidden id={SAM_PROMPT_GUIDANCE_ID}>{t('widgets.layers.selectObject.promptGuidance')}</VisuallyHidden>
+    </>
+  );
+};
+
+const SamSettingsSwitch = ({
+  checked,
+  disabled,
+  label,
+  onChange,
+}: {
+  checked: boolean;
+  disabled?: boolean;
+  label: string;
+  onChange(checked: boolean): void;
+}) => (
+  <Switch.Root
+    checked={checked}
+    disabled={disabled}
+    justifyContent="space-between"
+    size="sm"
+    w="full"
+    onCheckedChange={({ checked: next }) => onChange(next)}
+  >
+    <Switch.Label fontSize="xs">{label}</Switch.Label>
+    <Switch.HiddenInput />
+    <Switch.Control>
+      <Switch.Thumb />
+    </Switch.Control>
+  </Switch.Root>
+);
+
+/** Set-once session settings (model, refinement, preview behavior) demoted out of the bar. */
+export const SamSettingsPopover = ({
+  eligibility,
+  isProcessing,
+  session,
+  onModelChange,
+  onToggle,
+}: {
+  eligibility: SamActionEligibility;
+  isProcessing: boolean;
+  session: SamSessionSnapshot;
+  onModelChange(model: SamModel): void;
+  onToggle(key: 'applyPolygonRefinement' | 'autoProcess' | 'isolatedPreview', value: boolean): void;
+}) => {
+  const { t } = useTranslation();
+  return (
+    <Popover.Root lazyMount positioning={SAM_UPWARD_POSITIONING} unmountOnExit>
+      <Popover.Trigger asChild>
+        <Tooltip content={t('widgets.layers.selectObject.settings')}>
+          <IconButton aria-label={t('widgets.layers.selectObject.settings')} size="xs" variant="ghost">
+            <SettingsIcon />
+          </IconButton>
+        </Tooltip>
+      </Popover.Trigger>
+      <Portal>
+        <Popover.Positioner>
+          <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="16rem">
+            <Popover.Body p="2.5">
+              <Stack gap="2.5">
+                <Stack gap="1">
+                  <Text asChild fontSize="xs" fontWeight="semibold">
+                    <label htmlFor="sam-model">{t('widgets.layers.selectObject.model')}</label>
+                  </Text>
+                  <NativeSelect.Root disabled={isProcessing || !eligibility.canEditInputs} size="xs">
+                    <NativeSelect.Field
+                      id="sam-model"
+                      value={session.model}
+                      onChange={(event) => onModelChange(event.currentTarget.value as SamModel)}
+                    >
+                      <option value="segment-anything-2-large">
+                        {t('widgets.layers.selectObject.modelSam2Large')}
+                      </option>
+                      <option value="segment-anything-huge">{t('widgets.layers.selectObject.modelHuge')}</option>
+                    </NativeSelect.Field>
+                    <NativeSelect.Indicator />
+                  </NativeSelect.Root>
+                </Stack>
+                <SamSettingsSwitch
+                  checked={session.applyPolygonRefinement}
+                  disabled={isProcessing || !eligibility.canEditInputs}
+                  label={t('widgets.layers.selectObject.refine')}
+                  onChange={(value) => onToggle('applyPolygonRefinement', value)}
+                />
+                <SamSettingsSwitch
+                  checked={session.autoProcess}
+                  disabled={!eligibility.canEditInputs}
+                  label={t('widgets.layers.selectObject.autoProcess')}
+                  onChange={(value) => onToggle('autoProcess', value)}
+                />
+                <SamSettingsSwitch
+                  checked={session.isolatedPreview}
+                  disabled={!eligibility.canEditInputs}
+                  label={t('widgets.layers.selectObject.isolatedPreview')}
+                  onChange={(value) => onToggle('isolatedPreview', value)}
+                />
+              </Stack>
+            </Popover.Body>
+          </Popover.Content>
+        </Popover.Positioner>
+      </Portal>
+    </Popover.Root>
+  );
+};
+
+const SamSaveItem = ({
+  disabled,
+  onSave,
+  target,
+}: {
+  disabled: boolean;
+  onSave(target: SelectObjectSaveTarget): void;
+  target: SelectObjectSaveTarget;
+}) => {
+  const { t } = useTranslation();
+  return (
+    <Menu.Item disabled={disabled} value={target} onClick={() => onSave(target)}>
+      <Menu.ItemText>{t(`widgets.layers.selectObject.saveAs_${target}`)}</Menu.ItemText>
+    </Menu.Item>
+  );
+};
+
+export const SamOptionsBar = ({
+  engine,
+  operations,
+  session,
+  isExternalInteractionLocked = false,
+}: { engine: CanvasOperationUIEngine } & {
+  isExternalInteractionLocked?: boolean;
+  operations: CanvasOperationCapability;
+  session: SamSessionSnapshot;
+}) => {
+  const { t } = useTranslation();
+  const eligibility = getSamActionEligibility(session, isExternalInteractionLocked);
+  const viewModel = getSamPanelViewModel(session, (layerName, width, height) =>
+    t('widgets.layers.selectObject.sourceLayerLabel', {
+      height,
+      name: layerName,
+      type: t(`widgets.layers.selectObject.saveAs_${session.layerType}`),
+      width,
+    })
+  );
+  const actions = getSamActionHandlers(operations);
+  const isProcessing = isSamProcessingStatus(session.status);
+  const isBusy = !session.error && (isProcessing || session.status === 'scheduled' || session.status === 'committing');
+  const setBoolean = (key: 'applyPolygonRefinement' | 'autoProcess' | 'invert' | 'isolatedPreview', value: boolean) =>
+    operations.updateSelectObjectSession({ [key]: value });
+
+  return (
+    <CanvasFloatingBar maxW="full">
+      <Flex
+        align="center"
+        aria-label={t('widgets.layers.selectObject.title')}
+        flexWrap="wrap"
+        gap="1"
+        minW="0"
+        role="group"
+      >
+        <Tooltip content={viewModel.sourceLabel}>
+          <Text flexShrink="0" fontSize="xs" fontWeight="semibold" px="1" whiteSpace="nowrap">
+            {t('widgets.layers.selectObject.title')}
+            <VisuallyHidden>{viewModel.sourceLabel}</VisuallyHidden>
+          </Text>
+        </Tooltip>
+        <CanvasFloatingBarDivider />
+        <SamModeToggle
+          disabled={!eligibility.canEditInputs}
+          groupLabel={t('widgets.layers.selectObject.mode')}
+          mode={session.input.type}
+          promptLabel={t('widgets.layers.selectObject.promptMode')}
+          visualLabel={t('widgets.layers.selectObject.visual')}
+          onPrompt={() =>
+            getCanvasOperations(engine).updateSelectObjectSession({ input: { prompt: '', type: 'prompt' } })
+          }
+          onVisual={() =>
+            getCanvasOperations(engine).updateSelectObjectSession({
+              input: { bbox: null, excludePoints: [], includePoints: [], type: 'visual' },
+            })
+          }
+        />
+        {session.input.type === 'visual' ? (
+          <SamVisualInput
+            disabled={!eligibility.canEditInputs}
+            pointLabel={session.pointLabel}
+            viewModel={viewModel}
+            onExclude={() => getCanvasOperations(engine).updateSelectObjectSession({ pointLabel: 'exclude' })}
+            onInclude={() => getCanvasOperations(engine).updateSelectObjectSession({ pointLabel: 'include' })}
+          />
+        ) : (
+          <SamPromptBody
+            disabled={!eligibility.canEditInputs}
+            prompt={session.input.prompt}
+            onChange={(event) =>
+              getCanvasOperations(engine).updateSelectObjectSession({
+                input: { prompt: event.currentTarget.value, type: 'prompt' },
+              })
+            }
+          />
+        )}
+        <CanvasFloatingBarDivider />
+        <Button
+          aria-pressed={session.invert}
+          disabled={!eligibility.canEditInputs}
+          size="xs"
+          variant={session.invert ? 'solid' : 'ghost'}
+          onClick={() => setBoolean('invert', !session.invert)}
+        >
+          {t('widgets.layers.selectObject.invert')}
+        </Button>
+        <CanvasFloatingBarDivider />
+        <SamStatusSlot
+          error={session.error}
+          errorText={session.error ? t(getSamErrorTranslationKey(session.error.code)) : null}
+          isBusy={isBusy}
+          statusText={t(getSamStatusTranslationKey(session.status))}
+          technicalDetailsLabel={t('widgets.layers.selectObject.technicalDetails')}
+        />
+        <SamSettingsPopover
+          eligibility={eligibility}
+          isProcessing={isProcessing}
+          session={session}
+          onModelChange={(model) => getCanvasOperations(engine).updateSelectObjectSession({ model })}
+          onToggle={setBoolean}
+        />
+        <CanvasFloatingBarDivider />
+        <HStack flexShrink="0" gap="1">
+          <Button disabled={!eligibility.canProcess} loading={isProcessing} size="xs" onClick={actions.process}>
+            {t('widgets.layers.selectObject.process')}
+          </Button>
+          <Button disabled={!eligibility.canReset} size="xs" variant="ghost" onClick={actions.reset}>
+            {t('widgets.layers.selectObject.reset')}
+          </Button>
+          <Menu.Root positioning={SAM_UPWARD_POSITIONING}>
+            <Group attached>
+              <Button
+                colorPalette="accent"
+                disabled={!eligibility.canApply}
+                roundedEnd="none"
+                size="xs"
+                onClick={actions.apply}
+              >
+                {t('common.apply')}
+              </Button>
+              <Menu.Trigger asChild>
+                <IconButton
+                  aria-label={t('widgets.layers.selectObject.saveAs')}
+                  colorPalette="accent"
+                  disabled={!eligibility.canSave}
+                  minW="0"
+                  roundedStart="none"
+                  size="xs"
+                  w="6"
+                >
+                  <ChevronDownIcon />
+                </IconButton>
+              </Menu.Trigger>
+            </Group>
+            <Portal>
+              <Menu.Positioner>
+                <MenuContent minW="11rem" py="1">
+                  {SAVE_TARGETS.map((target) => (
+                    <SamSaveItem key={target} disabled={!eligibility.canSave} target={target} onSave={actions.save} />
+                  ))}
+                </MenuContent>
+              </Menu.Positioner>
+            </Portal>
+          </Menu.Root>
+          <Button disabled={!eligibility.canCancel} size="xs" variant="ghost" onClick={actions.cancel}>
+            {t('common.cancel')}
+          </Button>
+        </HStack>
+      </Flex>
+    </CanvasFloatingBar>
+  );
+};
+
+export const SamOptions = ({
+  engine,
+  isExternalInteractionLocked = false,
+}: {
+  engine: CanvasOperationUIEngine;
+  isExternalInteractionLocked?: boolean;
+}) => {
+  const session = useSamSession(engine);
+  if (!session) {
+    return null;
+  }
+  return (
+    <SamOptionsBar
+      engine={engine}
+      isExternalInteractionLocked={isExternalInteractionLocked}
+      operations={getCanvasOperations(engine)}
+      session={session}
+    />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ShapeOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ShapeOptions.tsx
new file mode 100644
index 00000000000..ef7025156d0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ShapeOptions.tsx
@@ -0,0 +1,193 @@
+import type { NumberInput as ChakraNumberInput, SelectValueChangeDetails } from '@chakra-ui/react';
+import type { ShapeToolOptions } from '@workbench/canvas-engine/engineStores';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import { createListCollection, HStack, NumberInput, Text } from '@chakra-ui/react';
+import { MAX_SHAPE_STROKE_WIDTH } from '@workbench/canvas-engine/engineStores';
+import { ColorPicker, Select, ToggleDot } from '@workbench/components/ui';
+import { useShapeOptions } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+type ShapeSource = Extract<CanvasLayerSourceContract, { type: 'shape' }>;
+type ShapeKind = ShapeToolOptions['kind'];
+
+interface SelectedShape {
+  id: string;
+  source: ShapeSource;
+}
+
+/** Fallback color used when re-enabling a `none` fill/stroke. */
+const FALLBACK_COLOR = '#000000';
+
+const SELECT_POSITIONING = { placement: 'top-start', sameWidth: false } as const;
+const SELECT_TRIGGER_PROPS = { minW: '6rem' } as const;
+
+/**
+ * Shape tool options: kind (rect/ellipse), fill color (+ none), stroke color
+ * (+ none) and stroke width. Edits set the defaults for the next created shape
+ * AND, when a shape layer is selected, apply to it — colors commit ONE history
+ * entry on interaction end (the ColorPicker popover shows the live color while
+ * dragging; the canvas updates on release), discrete edits commit immediately.
+ */
+export const ShapeOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const options = useShapeOptions(engine);
+
+  const selected = useActiveProjectSelector(
+    (project): SelectedShape | null => {
+      const { document } = project.canvas;
+      const layer = document.selectedLayerId
+        ? document.layers.find((entry) => entry.id === document.selectedLayerId)
+        : undefined;
+      if (layer && layer.type === 'raster' && layer.source.type === 'shape') {
+        return { id: layer.id, source: layer.source };
+      }
+      return null;
+    },
+    // Re-render on a selection change or a source-reference change (the reducer
+    // replaces the source object on every edit).
+    (a, b) => a?.id === b?.id && a?.source === b?.source
+  );
+
+  // Displayed values track the selected shape layer, or the tool defaults.
+  const kind: ShapeKind = selected ? (selected.source.kind === 'ellipse' ? 'ellipse' : 'rect') : options.kind;
+  const fill = selected ? selected.source.fill : options.fill;
+  const stroke = selected ? selected.source.stroke : options.stroke;
+  const strokeWidth = selected ? selected.source.strokeWidth : options.strokeWidth;
+
+  const kindCollection = useMemo(
+    () =>
+      createListCollection<{ label: string; value: ShapeKind }>({
+        items: [
+          { label: t('widgets.canvas.toolOptions.shapeRect'), value: 'rect' },
+          { label: t('widgets.canvas.toolOptions.shapeEllipse'), value: 'ellipse' },
+        ],
+      }),
+    [t]
+  );
+  const kindValue = useMemo(() => [kind], [kind]);
+
+  /**
+   * Applies an options patch: always updates the defaults store; when a shape
+   * layer is selected and `commit` is set, records one history entry on it.
+   */
+  const applyEdit = useCallback(
+    (patch: Partial<ShapeToolOptions>, commit: boolean) => {
+      engine.stores.shapeOptions.set({ fill, kind, stroke, strokeWidth, ...patch });
+      if (selected && commit) {
+        const before = selected.source;
+        const after: ShapeSource = { ...before, ...patch };
+        engine.layers.commitStructural(
+          t('widgets.canvas.toolOptions.shapeEdit'),
+          { id: selected.id, source: after, type: 'updateCanvasLayerSource' },
+          { id: selected.id, source: before, type: 'updateCanvasLayerSource' }
+        );
+      }
+    },
+    [engine, fill, kind, stroke, strokeWidth, selected, t]
+  );
+
+  const onKindChange = useCallback(
+    ({ value }: SelectValueChangeDetails<{ label: string; value: ShapeKind }>) => {
+      const next = value[0] as ShapeKind | undefined;
+      if (next && next !== kind) {
+        applyEdit({ kind: next }, true);
+      }
+    },
+    [applyEdit, kind]
+  );
+
+  // Fill: a toggle for none, plus a color picker (live store on drag, one commit on end).
+  const onFillToggle = useCallback(
+    (checked: boolean) => applyEdit({ fill: checked ? (fill ?? FALLBACK_COLOR) : null }, true),
+    [applyEdit, fill]
+  );
+  const onFillChange = useCallback((hex: string) => applyEdit({ fill: hex }, false), [applyEdit]);
+  const onFillChangeEnd = useCallback((hex: string) => applyEdit({ fill: hex }, true), [applyEdit]);
+
+  const onStrokeToggle = useCallback(
+    (checked: boolean) => applyEdit({ stroke: checked ? (stroke ?? FALLBACK_COLOR) : null }, true),
+    [applyEdit, stroke]
+  );
+  const onStrokeChange = useCallback((hex: string) => applyEdit({ stroke: hex }, false), [applyEdit]);
+  const onStrokeChangeEnd = useCallback((hex: string) => applyEdit({ stroke: hex }, true), [applyEdit]);
+
+  const onStrokeWidthChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        applyEdit({ strokeWidth: Math.max(0, Math.round(valueAsNumber)) }, true);
+      }
+    },
+    [applyEdit]
+  );
+
+  return (
+    <HStack align="center" gap="3">
+      <Select
+        aria-label={t('widgets.canvas.toolOptions.shapeKind')}
+        collection={kindCollection}
+        positioning={SELECT_POSITIONING}
+        size="xs"
+        triggerProps={SELECT_TRIGGER_PROPS}
+        value={kindValue}
+        valueText={t(
+          kind === 'ellipse' ? 'widgets.canvas.toolOptions.shapeEllipse' : 'widgets.canvas.toolOptions.shapeRect'
+        )}
+        onValueChange={onKindChange}
+      />
+
+      <HStack align="center" gap="1.5">
+        <ToggleDot
+          checked={fill !== null}
+          label={t('widgets.canvas.toolOptions.shapeFill')}
+          onCheckedChange={onFillToggle}
+        />
+        {fill !== null ? (
+          <ColorPicker
+            aria-label={t('widgets.canvas.toolOptions.shapeFill')}
+            value={fill}
+            onValueChange={onFillChange}
+            onValueChangeEnd={onFillChangeEnd}
+          />
+        ) : null}
+      </HStack>
+
+      <HStack align="center" gap="1.5">
+        <ToggleDot
+          checked={stroke !== null}
+          label={t('widgets.canvas.toolOptions.shapeStroke')}
+          onCheckedChange={onStrokeToggle}
+        />
+        {stroke !== null ? (
+          <>
+            <ColorPicker
+              aria-label={t('widgets.canvas.toolOptions.shapeStroke')}
+              value={stroke}
+              onValueChange={onStrokeChange}
+              onValueChangeEnd={onStrokeChangeEnd}
+            />
+            <NumberInput.Root
+              max={MAX_SHAPE_STROKE_WIDTH}
+              min={0}
+              size="xs"
+              value={String(Math.round(strokeWidth))}
+              w="4.5rem"
+              onValueChange={onStrokeWidthChange}
+            >
+              <NumberInput.Control />
+              <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.shapeStrokeWidth')} fontSize="xs" />
+            </NumberInput.Root>
+          </>
+        ) : null}
+      </HStack>
+
+      <Text color="fg.muted" flexShrink="0" fontSize="2xs">
+        {t('widgets.canvas.toolOptions.shapeHint')}
+      </Text>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/TextOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/TextOptions.tsx
new file mode 100644
index 00000000000..5d36fcc194d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/TextOptions.tsx
@@ -0,0 +1,261 @@
+import type { NumberInput as ChakraNumberInput, SelectValueChangeDetails } from '@chakra-ui/react';
+import type { TextToolOptions } from '@workbench/canvas-engine/engineStores';
+import type { CanvasLayerSourceContract } from '@workbench/types';
+
+import { createListCollection, HStack, NumberInput } from '@chakra-ui/react';
+import {
+  MAX_TEXT_FONT_SIZE,
+  MIN_TEXT_FONT_SIZE,
+  TEXT_FONT_FAMILIES,
+  TEXT_FONT_WEIGHTS,
+} from '@workbench/canvas-engine/engineStores';
+import { ColorPicker, IconButton, Select } from '@workbench/components/ui';
+import { useTextEditSession, useTextOptions } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { AlignCenterIcon, AlignLeftIcon, AlignRightIcon } from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+type TextSource = Extract<CanvasLayerSourceContract, { type: 'text' }>;
+type TextAlign = TextToolOptions['align'];
+
+interface SelectedText {
+  id: string;
+  source: TextSource;
+}
+
+const SELECT_POSITIONING = { placement: 'top-start', sameWidth: false } as const;
+const FAMILY_TRIGGER_PROPS = { minW: '7rem' } as const;
+const WEIGHT_TRIGGER_PROPS = { minW: '4.5rem' } as const;
+
+const ALIGN_ICONS: Record<TextAlign, typeof AlignLeftIcon> = {
+  center: AlignCenterIcon,
+  left: AlignLeftIcon,
+  right: AlignRightIcon,
+};
+
+const ALIGN_LABEL_KEYS: Record<TextAlign, string> = {
+  center: 'widgets.canvas.toolOptions.textAlignCenter',
+  left: 'widgets.canvas.toolOptions.textAlignLeft',
+  right: 'widgets.canvas.toolOptions.textAlignRight',
+};
+
+const ALIGN_VALUES: readonly TextAlign[] = ['left', 'center', 'right'];
+
+/** One alignment icon button with a stable per-value click handler. */
+const AlignButton = ({
+  active,
+  onSelect,
+  value,
+}: {
+  active: boolean;
+  onSelect: (value: TextAlign) => void;
+  value: TextAlign;
+}) => {
+  const { t } = useTranslation();
+  const Icon = ALIGN_ICONS[value];
+  const onClick = useCallback(() => onSelect(value), [onSelect, value]);
+  return (
+    <IconButton
+      aria-label={t(ALIGN_LABEL_KEYS[value])}
+      aria-pressed={active}
+      size="xs"
+      variant={active ? 'solid' : 'ghost'}
+      onClick={onClick}
+    >
+      <Icon />
+    </IconButton>
+  );
+};
+
+/**
+ * Text tool options: font family, size, weight, line-height, alignment and
+ * color. The displayed values follow a precedence — an active text-editing
+ * session's live source wins, else the selected text layer's source, else the
+ * tool defaults.
+ *
+ * Edits always update the defaults store (seeding the next created layer) and
+ * then, depending on context:
+ * - **session open**: restyle the live session (`updateTextEditStyle`), folded
+ *   into the session's single commit — the contenteditable restyles instantly.
+ * - **text layer selected, no session**: commit ONE `updateCanvasLayerSource`
+ *   per completed change (documentPatch history — same pattern as ShapeOptions).
+ *   Colors update the store live while dragging and commit once on release.
+ * - **neither**: only the defaults change.
+ */
+export const TextOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const options = useTextOptions(engine);
+  const session = useTextEditSession(engine);
+
+  const selected = useActiveProjectSelector(
+    (project): SelectedText | null => {
+      const { document } = project.canvas;
+      const layer = document.selectedLayerId
+        ? document.layers.find((entry) => entry.id === document.selectedLayerId)
+        : undefined;
+      if (layer && layer.type === 'raster' && layer.source.type === 'text') {
+        return { id: layer.id, source: layer.source };
+      }
+      return null;
+    },
+    (a, b) => a?.id === b?.id && a?.source === b?.source
+  );
+
+  // Precedence: live session source → selected layer source → tool defaults.
+  const active: TextToolOptions = session ? session.source : (selected?.source ?? options);
+  const { align, color, fontFamily, fontSize, fontWeight, lineHeight } = active;
+
+  const familyCollection = useMemo(
+    () => createListCollection<{ label: string; value: string }>({ items: [...TEXT_FONT_FAMILIES] }),
+    []
+  );
+  const familyValue = useMemo(() => [fontFamily], [fontFamily]);
+  const familyLabel = useMemo(
+    () => TEXT_FONT_FAMILIES.find((entry) => entry.value === fontFamily)?.label ?? fontFamily,
+    [fontFamily]
+  );
+
+  const weightCollection = useMemo(
+    () =>
+      createListCollection<{ label: string; value: string }>({
+        items: TEXT_FONT_WEIGHTS.map((weight) => ({ label: String(weight), value: String(weight) })),
+      }),
+    []
+  );
+  const weightValue = useMemo(() => [String(fontWeight)], [fontWeight]);
+
+  /**
+   * Applies a style patch: always updates the defaults store; restyles the live
+   * session when one is open; else records one history entry on the selected
+   * text layer when `commit` is set.
+   */
+  const applyEdit = useCallback(
+    (patch: Partial<TextToolOptions>, commit: boolean) => {
+      engine.stores.textOptions.set({ align, color, fontFamily, fontSize, fontWeight, lineHeight, ...patch });
+      if (session) {
+        engine.layers.updateTextEditStyle(patch);
+        return;
+      }
+      if (selected && commit) {
+        const before = selected.source;
+        const after: TextSource = { ...before, ...patch };
+        engine.layers.commitStructural(
+          t('widgets.canvas.toolOptions.textEdit'),
+          { id: selected.id, source: after, type: 'updateCanvasLayerSource' },
+          { id: selected.id, source: before, type: 'updateCanvasLayerSource' }
+        );
+      }
+    },
+    [engine, align, color, fontFamily, fontSize, fontWeight, lineHeight, session, selected, t]
+  );
+
+  const onFamilyChange = useCallback(
+    ({ value }: SelectValueChangeDetails<{ label: string; value: string }>) => {
+      const next = value[0];
+      if (next && next !== fontFamily) {
+        applyEdit({ fontFamily: next }, true);
+      }
+    },
+    [applyEdit, fontFamily]
+  );
+
+  const onWeightChange = useCallback(
+    ({ value }: SelectValueChangeDetails<{ label: string; value: string }>) => {
+      const next = value[0] ? Number(value[0]) : undefined;
+      if (next && next !== fontWeight) {
+        applyEdit({ fontWeight: next }, true);
+      }
+    },
+    [applyEdit, fontWeight]
+  );
+
+  const onSizeChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        const clamped = Math.min(MAX_TEXT_FONT_SIZE, Math.max(MIN_TEXT_FONT_SIZE, Math.round(valueAsNumber)));
+        applyEdit({ fontSize: clamped }, true);
+      }
+    },
+    [applyEdit]
+  );
+
+  const onLineHeightChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        applyEdit({ lineHeight: Math.max(0.5, Math.round(valueAsNumber * 10) / 10) }, true);
+      }
+    },
+    [applyEdit]
+  );
+
+  const onAlign = useCallback((next: TextAlign) => applyEdit({ align: next }, true), [applyEdit]);
+  const onColorChange = useCallback((hex: string) => applyEdit({ color: hex }, false), [applyEdit]);
+  const onColorChangeEnd = useCallback((hex: string) => applyEdit({ color: hex }, true), [applyEdit]);
+
+  return (
+    <HStack align="center" gap="3">
+      <Select
+        aria-label={t('widgets.canvas.toolOptions.textFont')}
+        collection={familyCollection}
+        positioning={SELECT_POSITIONING}
+        size="xs"
+        triggerProps={FAMILY_TRIGGER_PROPS}
+        value={familyValue}
+        valueText={familyLabel}
+        onValueChange={onFamilyChange}
+      />
+
+      <NumberInput.Root
+        max={MAX_TEXT_FONT_SIZE}
+        min={MIN_TEXT_FONT_SIZE}
+        size="xs"
+        value={String(Math.round(fontSize))}
+        w="4.5rem"
+        onValueChange={onSizeChange}
+      >
+        <NumberInput.Control />
+        <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.textSize')} fontSize="xs" />
+      </NumberInput.Root>
+
+      <Select
+        aria-label={t('widgets.canvas.toolOptions.textWeight')}
+        collection={weightCollection}
+        positioning={SELECT_POSITIONING}
+        size="xs"
+        triggerProps={WEIGHT_TRIGGER_PROPS}
+        value={weightValue}
+        valueText={String(fontWeight)}
+        onValueChange={onWeightChange}
+      />
+
+      <NumberInput.Root
+        max={4}
+        min={0.5}
+        size="xs"
+        step={0.1}
+        value={lineHeight.toFixed(1)}
+        w="4.5rem"
+        onValueChange={onLineHeightChange}
+      >
+        <NumberInput.Control />
+        <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.textLineHeight')} fontSize="xs" />
+      </NumberInput.Root>
+
+      <HStack align="center" gap="0.5">
+        {ALIGN_VALUES.map((value) => (
+          <AlignButton key={value} active={align === value} value={value} onSelect={onAlign} />
+        ))}
+      </HStack>
+
+      <ColorPicker
+        aria-label={t('widgets.canvas.toolOptions.textColor')}
+        value={color}
+        onValueChange={onColorChange}
+        onValueChangeEnd={onColorChangeEnd}
+      />
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ToolOptionsBar.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ToolOptionsBar.test.ts
new file mode 100644
index 00000000000..a3bb5f49ca9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ToolOptionsBar.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveCanvasOptionsContent, TOOL_OPTIONS_COMPONENTS } from './ToolOptionsBar';
+
+describe('TOOL_OPTIONS_COMPONENTS', () => {
+  it('has an entry for exactly the tools with dedicated options today (bbox, brush, eraser, gradient, lasso, move, shape, text, transform)', () => {
+    expect(Object.keys(TOOL_OPTIONS_COMPONENTS).sort()).toEqual([
+      'bbox',
+      'brush',
+      'eraser',
+      'gradient',
+      'lasso',
+      'move',
+      'shape',
+      'text',
+      'transform',
+    ]);
+  });
+
+  it('has no entry for the view tool — the bar shows only the doc info for it', () => {
+    expect(TOOL_OPTIONS_COMPONENTS.view).toBeUndefined();
+  });
+
+  it('has no entry for tools not yet implemented by the engine', () => {
+    for (const toolId of ['colorPicker', 'sam'] as const) {
+      expect(TOOL_OPTIONS_COMPONENTS[toolId]).toBeUndefined();
+    }
+  });
+
+  it('every registered entry is a defined component function', () => {
+    const components = Object.values(TOOL_OPTIONS_COMPONENTS);
+    expect(components.length).toBeGreaterThan(0);
+    for (const component of components) {
+      expect(typeof component).toBe('function');
+    }
+  });
+
+  it('gives an active canvas operation priority over the active or temporary tool', () => {
+    expect(resolveCanvasOptionsContent({ status: 'active' }, 'sam')).toBe('operation');
+    expect(resolveCanvasOptionsContent({ status: 'active' }, 'view')).toBe('operation');
+    expect(resolveCanvasOptionsContent({ status: 'idle' }, 'brush')).toBe('brush');
+    expect(resolveCanvasOptionsContent({ status: 'idle' }, 'view')).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ToolOptionsBar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ToolOptionsBar.tsx
new file mode 100644
index 00000000000..cd674411589
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/ToolOptionsBar.tsx
@@ -0,0 +1,119 @@
+import type { ToolId } from '@workbench/canvas-engine/types';
+import type { CanvasOperationState } from '@workbench/canvas-operations/operationController';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { ComponentType } from 'react';
+
+import { HStack, Text } from '@chakra-ui/react';
+import { BboxDetailsBar } from '@workbench/widgets/canvas/BboxDetailsBar';
+import { CanvasFloatingBarDivider } from '@workbench/widgets/canvas/CanvasFloatingBar';
+import { useCanvasActiveTool, useCanvasOperation, useCanvasZoom } from '@workbench/widgets/canvas/engineStoreHooks';
+import { formatZoomPercent } from '@workbench/widgets/canvas/zoomOptions';
+
+import { BboxOptions } from './BboxOptions';
+import { BrushOptions } from './BrushOptions';
+import { CanvasOperationBar } from './CanvasOperationBar';
+import { CanvasOptionsBar } from './CanvasOptionsBar';
+import { EraserOptions } from './EraserOptions';
+import { GradientOptions } from './GradientOptions';
+import { LassoOptions } from './LassoOptions';
+import { MoveOptions } from './MoveOptions';
+import { ShapeOptions } from './ShapeOptions';
+import { TextOptions } from './TextOptions';
+import { TransformOptions } from './TransformOptions';
+
+export type CanvasToolOptionsEngine = Pick<
+  CanvasEngineHandle,
+  'document' | 'layers' | 'projectId' | 'selection' | 'stores' | 'tools' | 'viewport'
+>;
+
+/** Props every per-tool options component receives — just the shared engine handle. */
+export interface ToolOptionsComponentProps {
+  engine: CanvasToolOptionsEngine;
+}
+
+/**
+ * Contextual options content per active tool. Tools without an entry here
+ * (view, and anything not yet implemented) render no controls — the bar still
+ * shows the document info on the right.
+ */
+export const TOOL_OPTIONS_COMPONENTS: Partial<Record<ToolId, ComponentType<ToolOptionsComponentProps>>> = {
+  bbox: BboxOptions,
+  brush: BrushOptions,
+  eraser: EraserOptions,
+  gradient: GradientOptions,
+  lasso: LassoOptions,
+  move: MoveOptions,
+  shape: ShapeOptions,
+  text: TextOptions,
+  transform: TransformOptions,
+};
+
+export const resolveCanvasOptionsContent = (
+  operation: Pick<CanvasOperationState, 'status'>,
+  activeTool: ToolId
+): 'operation' | ToolId | null => {
+  if (operation.status === 'active') {
+    return 'operation';
+  }
+  return TOOL_OPTIONS_COMPONENTS[activeTool] ? activeTool : null;
+};
+
+/**
+ * The canvas's floating tool-options bar (bottom-center over the surface):
+ * contextual controls for the active tool on the left, then the document
+ * dimensions / zoom read-out on the right (absorbed from the former floating HUD).
+ * Tool options read and write the engine's
+ * transient option stores directly (`useBrushOptions` / `useEraserOptions` +
+ * `engine.stores.*.set(...)`) — there is no React state mirror. Positioned by
+ * {@link CanvasWidgetView}; shares its look with the staging bar via
+ * {@link CanvasFloatingBar}.
+ */
+export const ToolOptionsBar = ({
+  documentHeight,
+  documentWidth,
+  engine,
+}: {
+  documentHeight: number | null;
+  documentWidth: number | null;
+  engine: CanvasToolOptionsEngine;
+}) => {
+  const activeTool = useCanvasActiveTool(engine);
+  const operation = useCanvasOperation(engine);
+  const zoom = useCanvasZoom(engine);
+  const content = resolveCanvasOptionsContent(operation, activeTool);
+  if (content === 'operation' && operation.status === 'active') {
+    return <CanvasOperationBar engine={engine} isExternalInteractionLocked={false} operation={operation} />;
+  }
+  const OptionsComponent = content && content !== 'operation' ? TOOL_OPTIONS_COMPONENTS[content] : undefined;
+  const hasDocument = documentWidth !== null && documentHeight !== null;
+  const hasBboxDetails = activeTool === 'bbox';
+  const hasToolControls = OptionsComponent !== undefined || hasBboxDetails;
+
+  return (
+    <CanvasOptionsBar>
+      {hasToolControls ? (
+        <HStack align="center" gap="3" minW="0" overflow="hidden">
+          {hasBboxDetails ? <BboxDetailsBar engine={engine} /> : null}
+          {hasBboxDetails && OptionsComponent ? <CanvasFloatingBarDivider /> : null}
+          {OptionsComponent ? <OptionsComponent engine={engine} /> : null}
+        </HStack>
+      ) : null}
+      {hasToolControls && hasDocument ? <CanvasFloatingBarDivider /> : null}
+      {hasDocument ? (
+        <HStack
+          align="center"
+          color="fg.muted"
+          flexShrink="0"
+          fontSize="2xs"
+          fontVariantNumeric="tabular-nums"
+          gap="2"
+          px="1"
+        >
+          <Text>
+            {documentWidth} × {documentHeight} @ {formatZoomPercent(zoom)}
+          </Text>
+        </HStack>
+      ) : null}
+    </CanvasOptionsBar>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/TransformOptions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/TransformOptions.tsx
new file mode 100644
index 00000000000..1f8b35d89b1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/TransformOptions.tsx
@@ -0,0 +1,175 @@
+import type { NumberInput as ChakraNumberInput } from '@chakra-ui/react';
+import type { LayerTransform } from '@workbench/canvas-engine/transform/transformMath';
+
+import { HStack, NumberInput, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { useTransformSession } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { ToolOptionsComponentProps } from './ToolOptionsBar';
+
+const RAD_TO_DEG = 180 / Math.PI;
+const DEG_TO_RAD = Math.PI / 180;
+
+/** Rounds to 2 decimals for display without trailing float noise. */
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+
+/**
+ * Transform tool options: numeric X / Y (document px), width/height scale
+ * (percent), and rotation (degrees) of the active session, plus Apply / Cancel.
+ *
+ * Scale is shown as a PERCENT of the layer's native size rather than absolute
+ * W/H pixels: the session carries only the transform (not the source pixel
+ * dimensions), so a percent is the resolution-independent, self-contained
+ * representation. Edits update the session preview through the engine (no
+ * dispatch until Apply); the whole session is one undo entry. Disabled with no
+ * session.
+ */
+export const TransformOptions = ({ engine }: ToolOptionsComponentProps) => {
+  const { t } = useTranslation();
+  const session = useTransformSession(engine);
+  const transform = session?.transform ?? null;
+
+  const patch = useCallback(
+    (next: Partial<LayerTransform>) => {
+      if (!transform) {
+        return;
+      }
+      engine.layers.updateTransformSession({ ...transform, ...next });
+    },
+    [engine, transform]
+  );
+
+  const onX = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        patch({ x: Math.round(valueAsNumber) });
+      }
+    },
+    [patch]
+  );
+  const onY = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        patch({ y: Math.round(valueAsNumber) });
+      }
+    },
+    [patch]
+  );
+  const onScaleX = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber) && valueAsNumber !== 0) {
+        patch({ scaleX: valueAsNumber / 100 });
+      }
+    },
+    [patch]
+  );
+  const onScaleY = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber) && valueAsNumber !== 0) {
+        patch({ scaleY: valueAsNumber / 100 });
+      }
+    },
+    [patch]
+  );
+  const onRotation = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        patch({ rotation: valueAsNumber * DEG_TO_RAD });
+      }
+    },
+    [patch]
+  );
+
+  const onApply = useCallback(() => engine.layers.applyTransform(), [engine]);
+  const onCancel = useCallback(() => engine.layers.cancelTransform(), [engine]);
+
+  const disabled = !transform;
+
+  return (
+    <HStack align="center" gap="3">
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.positionX')}
+        </Text>
+        <NumberInput.Root
+          disabled={disabled}
+          size="xs"
+          value={transform ? String(Math.round(transform.x)) : ''}
+          w="4.5rem"
+          onValueChange={onX}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.positionX')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.positionY')}
+        </Text>
+        <NumberInput.Root
+          disabled={disabled}
+          size="xs"
+          value={transform ? String(Math.round(transform.y)) : ''}
+          w="4.5rem"
+          onValueChange={onY}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.positionY')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.scaleWidth')}
+        </Text>
+        <NumberInput.Root
+          disabled={disabled}
+          size="xs"
+          value={transform ? String(round2(transform.scaleX * 100)) : ''}
+          w="4.5rem"
+          onValueChange={onScaleX}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.scaleWidth')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.scaleHeight')}
+        </Text>
+        <NumberInput.Root
+          disabled={disabled}
+          size="xs"
+          value={transform ? String(round2(transform.scaleY * 100)) : ''}
+          w="4.5rem"
+          onValueChange={onScaleY}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.scaleHeight')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <HStack align="center" gap="1.5">
+        <Text color="fg.muted" fontSize="2xs">
+          {t('widgets.canvas.toolOptions.rotation')}
+        </Text>
+        <NumberInput.Root
+          disabled={disabled}
+          size="xs"
+          value={transform ? String(round2(transform.rotation * RAD_TO_DEG)) : ''}
+          w="4.5rem"
+          onValueChange={onRotation}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.canvas.toolOptions.rotation')} fontSize="xs" />
+        </NumberInput.Root>
+      </HStack>
+      <Button disabled={disabled} size="xs" variant="solid" onClick={onApply}>
+        {t('widgets.canvas.toolOptions.applyTransform')}
+      </Button>
+      <Button disabled={disabled} size="xs" variant="ghost" onClick={onCancel}>
+        {t('widgets.canvas.toolOptions.cancelTransform')}
+      </Button>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/operationUIEngine.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/operationUIEngine.ts
new file mode 100644
index 00000000000..9e84b09f25b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/operationUIEngine.ts
@@ -0,0 +1,4 @@
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+
+/** Narrow UI view of application-owned filter and Select Object coordination. */
+export type CanvasOperationUIEngine = Pick<CanvasEngineHandle, 'projectId' | 'stores'>;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/useBboxEditor.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/useBboxEditor.ts
new file mode 100644
index 00000000000..ba0155949b2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/tool-options/useBboxEditor.ts
@@ -0,0 +1,71 @@
+import type { CanvasCoreStoreCapability, CanvasLayerCapability } from '@workbench/canvas-engine/api';
+import type { Rect } from '@workbench/canvas-engine/types';
+
+import { bboxEquals, roundBbox } from '@workbench/canvas-engine/tools/bboxHitTest';
+import { useBboxGrid, useBboxOptions } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export type BboxEditorEngine = CanvasCoreStoreCapability & { readonly layers: CanvasLayerCapability };
+
+const bboxEqualsSelected = (a: Rect | null, b: Rect | null): boolean =>
+  a === b || (!!a && !!b && a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height);
+
+export const useBboxEditor = (engine: BboxEditorEngine) => {
+  const { t } = useTranslation();
+  const bbox = useActiveProjectSelector((project) => project.canvas.document.bbox, bboxEqualsSelected);
+  const options = useBboxOptions(engine);
+  const grid = useBboxGrid(engine);
+
+  const commitBbox = useCallback(
+    (next: Rect) => {
+      const rounded = roundBbox(next);
+      if (bboxEquals(rounded, bbox)) {
+        return;
+      }
+      engine.layers.commitStructural(
+        t('widgets.canvas.toolOptions.setFrame'),
+        { bbox: rounded, type: 'setCanvasBbox' },
+        { bbox: roundBbox(bbox), type: 'setCanvasBbox' }
+      );
+    },
+    [bbox, engine, t]
+  );
+
+  const setWidth = useCallback(
+    (value: number) => {
+      const width = Math.max(1, Math.round(value / grid) * grid);
+      const height =
+        options.aspectLocked && options.aspectRatio > 0
+          ? Math.max(1, Math.round(width / options.aspectRatio))
+          : bbox.height;
+      commitBbox({ height, width, x: bbox.x, y: bbox.y });
+    },
+    [bbox, commitBbox, grid, options.aspectLocked, options.aspectRatio]
+  );
+
+  const setHeight = useCallback(
+    (value: number) => {
+      const height = Math.max(1, Math.round(value / grid) * grid);
+      const width =
+        options.aspectLocked && options.aspectRatio > 0
+          ? Math.max(1, Math.round(height * options.aspectRatio))
+          : bbox.width;
+      commitBbox({ height, width, x: bbox.x, y: bbox.y });
+    },
+    [bbox, commitBbox, grid, options.aspectLocked, options.aspectRatio]
+  );
+
+  const setX = useCallback(
+    (value: number) => commitBbox({ ...bbox, x: Math.round(value / grid) * grid }),
+    [bbox, commitBbox, grid]
+  );
+
+  const setY = useCallback(
+    (value: number) => commitBbox({ ...bbox, y: Math.round(value / grid) * grid }),
+    [bbox, commitBbox, grid]
+  );
+
+  return { bbox, commitBbox, grid, options, setHeight, setWidth, setX, setY };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/useCanvasEngine.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/useCanvasEngine.ts
new file mode 100644
index 00000000000..7af53db0585
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/useCanvasEngine.ts
@@ -0,0 +1,61 @@
+/**
+ * Resolves the shared {@link CanvasEngine} for the active project.
+ *
+ * The engine is a per-project resource shared with the layers widget via the
+ * ref-counted {@link getOrCreateEngine | engine registry}. Acquisition and
+ * release are a genuine component-lifecycle concern keyed on the project id —
+ * the one place a `useEffect` is unavoidable here (there is no ref-callback for
+ * "this component"). The registry's grace-period disposal absorbs the
+ * mount/unmount churn (StrictMode double-mount, quick re-layout) so the same
+ * warm engine is handed back rather than rebuilt.
+ *
+ * Returns `null` for the first render (before the acquiring effect runs); the
+ * surface mounts once the engine is available, and its ref callback attaches
+ * then.
+ */
+
+import type { ImageResolver } from '@workbench/canvas-engine/render/rasterizers';
+
+import { canvasApplicationPort } from '@workbench/canvas-operations/applicationPort';
+import { getOrCreateEngine, releaseEngine } from '@workbench/canvas-operations/engineRegistry';
+import { createCanvasProjectMutationPort } from '@workbench/canvasProjectMutationPort';
+import { getImageFullUrl } from '@workbench/gallery/api';
+import { useActiveProjectId, useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useEffect, useState } from 'react';
+
+/** Registry-owned application engine handle; consumers narrow this to the capabilities they use. */
+export type CanvasEngineHandle = ReturnType<typeof getOrCreateEngine>;
+
+/** Fetches a persisted image asset to a `Blob` for the engine's rasterizers. */
+const createImageResolver = (): ImageResolver => async (imageName, signal) => {
+  const response = await fetch(getImageFullUrl(imageName), { signal });
+  if (!response.ok) {
+    throw new Error(`Failed to load canvas image "${imageName}" (${response.status})`);
+  }
+  return response.blob();
+};
+
+/** Acquires (and releases) the active project's canvas engine. */
+export const useCanvasEngine = (): CanvasEngineHandle | null => {
+  const store = useWorkbenchStore();
+  const projectId = useActiveProjectId();
+  const [engine, setEngine] = useState<CanvasEngineHandle | null>(null);
+
+  useEffect(() => {
+    const acquired = getOrCreateEngine(projectId, {
+      getMainModelBase: () => canvasApplicationPort.getSelectedModelBase(store.getState(), projectId),
+      imageResolver: createImageResolver(),
+      mutationPort: createCanvasProjectMutationPort(store, projectId),
+      reportError: (report) => store.dispatch({ ...report, type: 'recordError' }),
+    });
+    // Surfacing an effect-acquired external resource is the one legitimate
+    // synchronous setState-in-effect: acquire/release must live in the effect
+    // (balanced ref-count, StrictMode-safe via the registry's grace period),
+    // and the surface can only attach once the handle reaches render.
+    // eslint-disable-next-line react/react-compiler
+    setEngine(acquired);
+    return () => releaseEngine(projectId);
+  }, [projectId, store]);
+
+  return engine;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/useCanvasGallerySave.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/useCanvasGallerySave.ts
new file mode 100644
index 00000000000..f45c603b690
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/useCanvasGallerySave.ts
@@ -0,0 +1,62 @@
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+
+import { saveCanvasToGallery, type CanvasGallerySaveRegion } from '@workbench/canvas-operations/saveCanvasToGallery';
+import { useNotify } from '@workbench/useNotify';
+import { useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { useCallback, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { getCanvasGallerySaveErrorAction, withMatchingCanvasProject } from './canvasGallerySaveState';
+
+type CanvasGallerySaveEngine = Pick<CanvasEngineHandle, 'document' | 'exports' | 'lifecycle' | 'projectId'>;
+
+export const useCanvasGallerySave = (
+  engine: CanvasGallerySaveEngine | null
+): { isSaving: boolean; save: (region: CanvasGallerySaveRegion) => Promise<void> } => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const store = useWorkbenchStore();
+  const isSavingRef = useRef(false);
+  const [isSaving, setIsSaving] = useState(false);
+
+  const save = useCallback(
+    async (region: CanvasGallerySaveRegion): Promise<void> => {
+      if (isSavingRef.current) {
+        return;
+      }
+
+      const project = store.getSnapshot().activeProject;
+
+      await withMatchingCanvasProject(engine, project.id, async (matchedEngine) => {
+        isSavingRef.current = true;
+        setIsSaving(true);
+
+        try {
+          const result = await saveCanvasToGallery({ engine: matchedEngine, project, region });
+
+          if (result.status === 'saved') {
+            store.dispatch({ projectId: project.id, type: 'touchGalleryImagesRefresh' });
+            notify.success(
+              t('widgets.canvas.contextMenu.saved'),
+              t('widgets.canvas.contextMenu.savedDescription', { name: result.imageName })
+            );
+          } else if (result.status === 'empty') {
+            notify.info(t('widgets.canvas.contextMenu.empty'));
+          } else if (result.status === 'stale') {
+            notify.info(t('widgets.canvas.contextMenu.stale'));
+          } else {
+            notify.info(t('widgets.canvas.contextMenu.notReady'));
+          }
+        } catch (error: unknown) {
+          store.dispatch(getCanvasGallerySaveErrorAction(error, project.id, t('widgets.canvas.contextMenu.saveError')));
+        } finally {
+          isSavingRef.current = false;
+          setIsSaving(false);
+        }
+      });
+    },
+    [engine, notify, store, t]
+  );
+
+  return { isSaving, save };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/zoomOptions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/zoomOptions.test.ts
new file mode 100644
index 00000000000..7736f790347
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/zoomOptions.test.ts
@@ -0,0 +1,37 @@
+import { ZOOM_SNAP_CANDIDATES } from '@workbench/canvas-engine/math/snapping';
+import { describe, expect, it } from 'vitest';
+
+import { formatZoomPercent, zoomMenuOptions } from './zoomOptions';
+
+describe('formatZoomPercent', () => {
+  it('renders whole percentages', () => {
+    expect(formatZoomPercent(1)).toBe('100%');
+    expect(formatZoomPercent(0.25)).toBe('25%');
+    expect(formatZoomPercent(2)).toBe('200%');
+  });
+
+  it('rounds to the nearest whole percent', () => {
+    expect(formatZoomPercent(0.333)).toBe('33%');
+    expect(formatZoomPercent(0.675)).toBe('68%');
+  });
+});
+
+describe('zoomMenuOptions', () => {
+  it('covers every snap candidate', () => {
+    const options = zoomMenuOptions();
+    expect(options).toHaveLength(ZOOM_SNAP_CANDIDATES.length);
+    expect(new Set(options.map((option) => option.value))).toEqual(new Set(ZOOM_SNAP_CANDIDATES));
+  });
+
+  it('is ordered from largest to smallest zoom', () => {
+    const values = zoomMenuOptions().map((option) => option.value);
+    expect(values).toEqual([...values].sort((a, b) => b - a));
+    expect(values[0]).toBe(Math.max(...ZOOM_SNAP_CANDIDATES));
+  });
+
+  it('pairs each value with its formatted label', () => {
+    for (const option of zoomMenuOptions()) {
+      expect(option.label).toBe(formatZoomPercent(option.value));
+    }
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/canvas/zoomOptions.ts b/invokeai/frontend/webv2/src/workbench/widgets/canvas/zoomOptions.ts
new file mode 100644
index 00000000000..78e8db90cce
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/canvas/zoomOptions.ts
@@ -0,0 +1,22 @@
+/**
+ * Pure zoom-menu helpers for the canvas HUD.
+ *
+ * The option set is derived from the engine's single source of truth for zoom
+ * snap points (`ZOOM_SNAP_CANDIDATES`), so the HUD and the viewport's wheel
+ * snapping always agree. No React, no side effects — unit-testable in node.
+ */
+
+import { ZOOM_SNAP_CANDIDATES } from '@workbench/canvas-engine/math/snapping';
+
+/** Formats a zoom factor as a rounded whole-percent label (e.g. `1` → `"100%"`). */
+export const formatZoomPercent = (zoom: number): string => `${Math.round(zoom * 100)}%`;
+
+/** A single zoom-menu entry: the factor to apply and its display label. */
+export interface ZoomMenuOption {
+  value: number;
+  label: string;
+}
+
+/** The selectable zoom levels for the HUD menu, largest first (matches snap points top-down). */
+export const zoomMenuOptions = (): ZoomMenuOption[] =>
+  [...ZOOM_SNAP_CANDIDATES].sort((a, b) => b - a).map((value) => ({ label: formatZoomPercent(value), value }));
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/DiagnosticsHeaderActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/DiagnosticsHeaderActions.tsx
new file mode 100644
index 00000000000..c5492af3722
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/DiagnosticsHeaderActions.tsx
@@ -0,0 +1,26 @@
+import { Badge } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { clearProjectDiagnostics, useProjectDiagnostics } from '@workbench/diagnostics/logger';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { BugIcon } from 'lucide-react';
+import { useCallback } from 'react';
+
+export const DiagnosticsHeaderActions = () => {
+  const projectId = useActiveProjectSelector((project) => project.id);
+  const entries = useProjectDiagnostics(projectId);
+  const clearEntries = useCallback(() => clearProjectDiagnostics(projectId), [projectId]);
+
+  return (
+    <>
+      {entries.length ? (
+        <Badge colorPalette="red" size="xs">
+          <BugIcon />
+          {entries.length}
+        </Badge>
+      ) : null}
+      <Button disabled={entries.length === 0} size="2xs" variant="outline" onClick={clearEntries}>
+        Clear
+      </Button>
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/DiagnosticsWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/DiagnosticsWidgetView.tsx
new file mode 100644
index 00000000000..dcf0e02273e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/DiagnosticsWidgetView.tsx
@@ -0,0 +1,147 @@
+import type { DiagnosticEntry } from '@workbench/diagnostics/logger';
+import type { WidgetViewProps } from '@workbench/types';
+
+import { Badge, Box, HStack, Stack, Text } from '@chakra-ui/react';
+import { Button, Panel } from '@workbench/components/ui';
+import { clearProjectDiagnostics, useProjectDiagnostics } from '@workbench/diagnostics/logger';
+import { StatusWidgetChip } from '@workbench/widget-frame';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { BugIcon, ClipboardListIcon } from 'lucide-react';
+import { memo, useCallback, useState } from 'react';
+
+export const DiagnosticsWidgetView = ({ presentation, region }: WidgetViewProps) => {
+  const projectId = useActiveProjectSelector((project) => project.id);
+  const entries = useProjectDiagnostics(projectId);
+  const label = entries.length === 0 ? 'Clean' : `${entries.length} event${entries.length === 1 ? '' : 's'}`;
+
+  if (region === 'bottom' && presentation !== 'expanded') {
+    return (
+      <StatusWidgetChip icon={entries.length > 0 ? BugIcon : ClipboardListIcon}>Diagnostics: {label}</StatusWidgetChip>
+    );
+  }
+
+  return <DiagnosticsPanel entries={entries} projectId={projectId} />;
+};
+
+const DiagnosticsPanel = ({ entries, projectId }: { entries: DiagnosticEntry[]; projectId: string }) => {
+  const copyAll = useCallback(() => void navigator.clipboard?.writeText(JSON.stringify(entries, null, 2)), [entries]);
+  const clearEntries = useCallback(() => clearProjectDiagnostics(projectId), [projectId]);
+
+  return (
+    <Stack gap="3" p="2">
+      <HStack justify="space-between">
+        <Text color="fg.subtle" fontSize="2xs">
+          Project-scoped diagnostic events from workbench and widget loggers.
+        </Text>
+        <HStack gap="2">
+          <Button disabled={entries.length === 0} size="2xs" variant="outline" onClick={copyAll}>
+            Copy JSON
+          </Button>
+          <Button disabled={entries.length === 0} size="2xs" variant="outline" onClick={clearEntries}>
+            Clear
+          </Button>
+        </HStack>
+      </HStack>
+      {entries.length === 0 ? (
+        <Text color="fg.subtle" fontSize="2xs">
+          Logger events and performance timings will appear here without covering the workbench.
+        </Text>
+      ) : (
+        <Stack gap="2">
+          {entries.map((entry) => (
+            <DiagnosticsEntryRow key={entry.id} entry={entry} />
+          ))}
+        </Stack>
+      )}
+    </Stack>
+  );
+};
+
+const DiagnosticsEntryRow = memo(({ entry }: { entry: DiagnosticEntry }) => {
+  const [isRawVisible, setIsRawVisible] = useState(false);
+  const copyEntry = useCallback(() => void navigator.clipboard?.writeText(JSON.stringify(entry, null, 2)), [entry]);
+  const toggleRaw = useCallback(() => setIsRawVisible((current) => !current), []);
+
+  return (
+    <Panel gap="2" p="2">
+      <Stack gap="2">
+        <HStack align="start" gap="2" justify="space-between">
+          <Stack gap="1" minW="0">
+            <HStack gap="1.5" wrap="wrap">
+              <Badge colorPalette={getLevelColorPalette(entry.level)} size="xs">
+                {entry.level}
+              </Badge>
+              <Badge colorPalette="gray" size="xs">
+                {entry.namespace}
+              </Badge>
+              {entry.durationMs !== undefined ? (
+                <Badge colorPalette="purple" size="xs">
+                  {entry.durationMs.toFixed(1)}ms
+                </Badge>
+              ) : null}
+              <Text color="fg.muted" fontFamily="mono" fontSize="2xs">
+                {formatSource(entry)}
+              </Text>
+            </HStack>
+            <Text color="fg" fontSize="xs" fontWeight="600">
+              {entry.message || '(no message)'}
+            </Text>
+            <Text color="fg.subtle" fontSize="2xs">
+              {new Date(entry.createdAt).toLocaleTimeString()}
+            </Text>
+          </Stack>
+          <Button size="2xs" variant="outline" onClick={copyEntry}>
+            Copy
+          </Button>
+        </HStack>
+        <Button alignSelf="start" size="2xs" variant="ghost" onClick={toggleRaw}>
+          {isRawVisible ? 'Hide raw entry' : 'Raw entry'}
+        </Button>
+        {isRawVisible ? (
+          <Box
+            as="pre"
+            bg="bg.inset"
+            borderColor="border.subtle"
+            borderWidth="1px"
+            color="fg.muted"
+            fontFamily="mono"
+            fontSize="2xs"
+            maxH="16rem"
+            overflow="auto"
+            p="2"
+            rounded="md"
+            whiteSpace="pre-wrap"
+          >
+            {JSON.stringify(entry, null, 2)}
+          </Box>
+        ) : null}
+      </Stack>
+    </Panel>
+  );
+});
+
+DiagnosticsEntryRow.displayName = 'DiagnosticsEntryRow';
+
+const formatSource = (entry: DiagnosticEntry): string => {
+  if (entry.source.kind === 'widget') {
+    return `${entry.source.typeId}:${entry.source.instanceId}:${entry.source.region}`;
+  }
+
+  return `workbench:${entry.source.area}`;
+};
+
+const getLevelColorPalette = (level: DiagnosticEntry['level']): string => {
+  switch (level) {
+    case 'fatal':
+    case 'error':
+      return 'red';
+    case 'warn':
+      return 'orange';
+    case 'info':
+      return 'blue';
+    case 'debug':
+      return 'purple';
+    case 'trace':
+      return 'gray';
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/index.ts
new file mode 100644
index 00000000000..ce0f8e68a7a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/diagnostics/index.ts
@@ -0,0 +1,19 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { BugIcon } from 'lucide-react';
+
+import { DiagnosticsHeaderActions } from './DiagnosticsHeaderActions';
+import { DiagnosticsWidgetView } from './DiagnosticsWidgetView';
+
+export const diagnosticsWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['bottom', 'right'],
+  bottomPanel: 'expandable',
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  headerActions: DiagnosticsHeaderActions,
+  icon: BugIcon,
+  id: 'diagnostics',
+  label: (t) => t('widgets.labels.diagnostics'),
+  version: 1,
+  view: DiagnosticsWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryBoardMenu.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryBoardMenu.tsx
new file mode 100644
index 00000000000..a43d17a6414
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryBoardMenu.tsx
@@ -0,0 +1,332 @@
+/* eslint-disable react/react-compiler */
+import type { GalleryBoard } from '@workbench/gallery/api';
+
+import { Dialog, HStack, Icon, Input, Menu, Portal, Stack, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { ArchiveIcon, DownloadIcon, PencilIcon, Trash2Icon, type LucideIcon } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useGalleryWidget } from './GalleryWidgetContext';
+
+const MENU_CONTENT_PADDING_X = '0';
+
+export interface GalleryBoardMenuTarget {
+  board: GalleryBoard;
+  x: number;
+  y: number;
+}
+
+/**
+ * Cursor-anchored actions menu for a single board row (download, rename,
+ * archive, delete) so boards can be managed without selecting them first.
+ * Opened from the board dropdown via right-click or the row's hover actions
+ * button; the dropdown stays open underneath (see onActiveChange).
+ */
+export const GalleryBoardMenu = ({
+  target,
+  onActiveChange,
+  onClose,
+}: {
+  target: GalleryBoardMenuTarget | null;
+  /** Reports whether the menu or one of its dialogs is showing, so the host dropdown can stay open. */
+  onActiveChange?: (isActive: boolean) => void;
+  onClose: () => void;
+}) => {
+  const { t } = useTranslation();
+  const { actions, gallery } = useGalleryWidget();
+  const [renameTarget, setRenameTarget] = useState<GalleryBoard | null>(null);
+  const [deleteTarget, setDeleteTarget] = useState<GalleryBoard | null>(null);
+  const [renameValue, setRenameValue] = useState('');
+  const targetRef = useRef(target);
+
+  targetRef.current = target;
+
+  const board = target?.board ?? null;
+  // Project boards can be downloaded but never renamed, archived, or deleted.
+  const isManagedBoard = board !== null && board.kind === 'board' && board.id !== gallery.projectBoardId;
+  const isActive = target !== null || renameTarget !== null || deleteTarget !== null;
+
+  useEffect(() => {
+    onActiveChange?.(isActive);
+  }, [isActive, onActiveChange]);
+
+  const positioning = useMemo(
+    () => ({
+      getAnchorRect: () => {
+        const currentTarget = targetRef.current;
+
+        return currentTarget ? { height: 1, width: 1, x: currentTarget.x, y: currentTarget.y } : null;
+      },
+      placement: 'bottom-start' as const,
+    }),
+    []
+  );
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  const submitRename = useCallback(() => {
+    const trimmedName = renameValue.trim();
+
+    if (renameTarget && trimmedName && trimmedName !== renameTarget.name) {
+      void actions.renameBoard(renameTarget.id, trimmedName);
+    }
+
+    setRenameTarget(null);
+  }, [actions, renameTarget, renameValue]);
+
+  const handleRenameDialogOpenChange = useCallback((event: { open: boolean }) => {
+    if (!event.open) {
+      setRenameTarget(null);
+    }
+  }, []);
+
+  const handleRenameValueChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+    setRenameValue(event.currentTarget.value);
+  }, []);
+
+  const handleRenameKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'Enter') {
+        event.preventDefault();
+        submitRename();
+      }
+    },
+    [submitRename]
+  );
+
+  const handleCancelRename = useCallback(() => setRenameTarget(null), []);
+
+  const handleDeleteDialogOpenChange = useCallback((event: { open: boolean }) => {
+    if (!event.open) {
+      setDeleteTarget(null);
+    }
+  }, []);
+
+  const handleCancelDelete = useCallback(() => setDeleteTarget(null), []);
+
+  const handleDeleteBoardOnly = useCallback(() => {
+    if (deleteTarget) {
+      void actions.deleteBoard(deleteTarget.id, false);
+    }
+
+    setDeleteTarget(null);
+  }, [actions, deleteTarget]);
+
+  const handleDeleteBoardAndImages = useCallback(() => {
+    if (deleteTarget) {
+      void actions.deleteBoard(deleteTarget.id, true);
+    }
+
+    setDeleteTarget(null);
+  }, [actions, deleteTarget]);
+
+  return (
+    <>
+      <Menu.Root
+        key={board ? board.id : 'closed'}
+        lazyMount
+        open={target !== null}
+        positioning={positioning}
+        unmountOnExit
+        onOpenChange={handleOpenChange}
+      >
+        <Portal>
+          <Menu.Positioner>
+            {board && (
+              <Menu.Content minW="12rem" py="1" px={MENU_CONTENT_PADDING_X}>
+                <BoardDownloadMenuItem boardId={board.id} />
+                {isManagedBoard && (
+                  <>
+                    <BoardRenameMenuItem board={board} onRename={setRenameTarget} onRenameValue={setRenameValue} />
+                    <BoardArchiveMenuItem archived={board.archived} boardId={board.id} />
+                    <Menu.Separator borderColor="border.subtle" />
+                    <BoardDeleteMenuItem board={board} onDelete={setDeleteTarget} />
+                  </>
+                )}
+              </Menu.Content>
+            )}
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <Dialog.Root
+        initialFocusEl={undefined}
+        open={renameTarget !== null}
+        onOpenChange={handleRenameDialogOpenChange}
+        size="sm"
+      >
+        <Portal>
+          <Dialog.Backdrop />
+          <Dialog.Positioner>
+            <Dialog.Content>
+              <Dialog.Header>
+                <Dialog.Title fontSize="sm">{t('widgets.gallery.renameBoard')}</Dialog.Title>
+              </Dialog.Header>
+              <Dialog.Body>
+                <Input
+                  aria-label={t('widgets.gallery.boardName')}
+                  autoFocus
+                  size="sm"
+                  value={renameValue}
+                  onChange={handleRenameValueChange}
+                  onKeyDown={handleRenameKeyDown}
+                />
+              </Dialog.Body>
+              <Dialog.Footer gap="2">
+                <Button size="xs" variant="outline" onClick={handleCancelRename}>
+                  {t('common.cancel')}
+                </Button>
+                <Button disabled={renameValue.trim().length === 0} size="xs" onClick={submitRename}>
+                  {t('common.rename')}
+                </Button>
+              </Dialog.Footer>
+            </Dialog.Content>
+          </Dialog.Positioner>
+        </Portal>
+      </Dialog.Root>
+      <Dialog.Root open={deleteTarget !== null} role="alertdialog" onOpenChange={handleDeleteDialogOpenChange}>
+        <Portal>
+          <Dialog.Backdrop />
+          <Dialog.Positioner>
+            <Dialog.Content>
+              <Dialog.Header>
+                <Dialog.Title fontSize="sm">
+                  {t('widgets.gallery.deleteBoardQuestion', { name: deleteTarget?.name ?? '' })}
+                </Dialog.Title>
+              </Dialog.Header>
+              <Dialog.Body>
+                <Stack gap="2">
+                  <Text color="fg.subtle" fontSize="xs">
+                    {t('widgets.gallery.deleteBoardDescription')}
+                  </Text>
+                  <Text color="fg.subtle" fontSize="2xs">
+                    {t('widgets.gallery.boardItemCounts', {
+                      assets: deleteTarget?.assetCount ?? 0,
+                      images: deleteTarget?.imageCount ?? 0,
+                    })}
+                  </Text>
+                </Stack>
+              </Dialog.Body>
+              <Dialog.Footer gap="2">
+                <Button size="xs" variant="outline" onClick={handleCancelDelete}>
+                  {t('common.cancel')}
+                </Button>
+                <Button colorPalette="red" size="xs" variant="outline" onClick={handleDeleteBoardOnly}>
+                  {t('widgets.gallery.deleteBoardOnly')}
+                </Button>
+                <Button colorPalette="red" size="xs" onClick={handleDeleteBoardAndImages}>
+                  {t('widgets.gallery.deleteBoardAndImages')}
+                </Button>
+              </Dialog.Footer>
+            </Dialog.Content>
+          </Dialog.Positioner>
+        </Portal>
+      </Dialog.Root>
+    </>
+  );
+};
+
+const BoardDownloadMenuItem = ({ boardId }: { boardId: string }) => {
+  const { t } = useTranslation();
+  const { actions } = useGalleryWidget();
+  const handleClick = useCallback(() => void actions.downloadBoard(boardId), [actions, boardId]);
+
+  return (
+    <BoardMenuItem
+      icon={DownloadIcon}
+      label={t('widgets.gallery.downloadBoard')}
+      value="download-board"
+      onClick={handleClick}
+    />
+  );
+};
+
+const BoardRenameMenuItem = ({
+  board,
+  onRename,
+  onRenameValue,
+}: {
+  board: GalleryBoard;
+  onRename: React.Dispatch<React.SetStateAction<GalleryBoard | null>>;
+  onRenameValue: React.Dispatch<React.SetStateAction<string>>;
+}) => {
+  const { t } = useTranslation();
+  const handleClick = useCallback(() => {
+    onRenameValue(board.name);
+    onRename(board);
+  }, [board, onRename, onRenameValue]);
+
+  return (
+    <BoardMenuItem
+      icon={PencilIcon}
+      label={t('widgets.gallery.renameBoard')}
+      value="rename-board"
+      onClick={handleClick}
+    />
+  );
+};
+
+const BoardArchiveMenuItem = ({ archived, boardId }: { archived: boolean; boardId: string }) => {
+  const { t } = useTranslation();
+  const { actions } = useGalleryWidget();
+  const handleClick = useCallback(() => void actions.archiveBoard(boardId, !archived), [actions, archived, boardId]);
+
+  return (
+    <BoardMenuItem
+      icon={ArchiveIcon}
+      label={archived ? t('widgets.gallery.unarchiveBoard') : t('widgets.gallery.archiveBoard')}
+      value="toggle-archived"
+      onClick={handleClick}
+    />
+  );
+};
+
+const BoardDeleteMenuItem = ({
+  board,
+  onDelete,
+}: {
+  board: GalleryBoard;
+  onDelete: React.Dispatch<React.SetStateAction<GalleryBoard | null>>;
+}) => {
+  const { t } = useTranslation();
+  const handleClick = useCallback(() => onDelete(board), [board, onDelete]);
+
+  return (
+    <BoardMenuItem
+      color="fg.error"
+      icon={Trash2Icon}
+      label={t('widgets.gallery.deleteBoard')}
+      value="delete-board"
+      onClick={handleClick}
+    />
+  );
+};
+
+const BoardMenuItem = ({
+  color,
+  icon,
+  label,
+  value,
+  onClick,
+}: {
+  color?: string;
+  icon: LucideIcon;
+  label: string;
+  value: string;
+  onClick: () => void;
+}) => (
+  <Menu.Item color={color} value={value} onClick={onClick}>
+    <HStack gap="2" minW="0" w="full">
+      <Icon as={icon} boxSize="3.5" color={color ?? 'fg.subtle'} flexShrink={0} />
+      <Text flex="1" fontSize="xs">
+        {label}
+      </Text>
+    </HStack>
+  </Menu.Item>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryBoardSelect.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryBoardSelect.tsx
new file mode 100644
index 00000000000..858ad265061
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryBoardSelect.tsx
@@ -0,0 +1,614 @@
+import type { GalleryBoard } from '@workbench/gallery/api';
+
+import {
+  Badge,
+  Flex,
+  HStack,
+  Icon,
+  Image,
+  Input,
+  InputGroup,
+  Menu,
+  Portal,
+  ScrollArea,
+  Stack,
+  Text,
+} from '@chakra-ui/react';
+import { useDndContext, useDndMonitor, useDroppable, type DragEndEvent, type DragStartEvent } from '@dnd-kit/core';
+import { Button, CloseButton, IconButton } from '@workbench/components/ui';
+import {
+  ArchiveIcon,
+  ArrowDownAZIcon,
+  ArrowUpAZIcon,
+  CalendarIcon,
+  ChevronDownIcon,
+  ImageIcon,
+  MoreVerticalIcon,
+  PinIcon,
+  PlusIcon,
+  type LucideIcon,
+  SearchIcon,
+  XIcon,
+} from 'lucide-react';
+import {
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type KeyboardEvent,
+  type MouseEvent,
+  type PointerEvent,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { GalleryBoardMenu, type GalleryBoardMenuTarget } from './GalleryBoardMenu';
+import {
+  getGalleryBoardDropData,
+  getGalleryBoardDropId,
+  getGalleryImageNamesOutsideBoard,
+  isGalleryBoardDropData,
+  isGalleryImageDragData,
+} from './galleryDnd';
+import { getBoardCounts } from './galleryStateView';
+import { useGalleryWidget } from './GalleryWidgetContext';
+
+export const GalleryBoardSelect = () => {
+  const { t } = useTranslation();
+  const { actions, gallery, imageActions, projectName } = useGalleryWidget();
+  const { active } = useDndContext();
+  const [isOpen, setIsOpen] = useState(false);
+  const [boardSearchTerm, setBoardSearchTerm] = useState('');
+  const [boardMenuTarget, setBoardMenuTarget] = useState<GalleryBoardMenuTarget | null>(null);
+  const boardMenuActiveRef = useRef(false);
+  const dragOpenedMenuRef = useRef(false);
+  const isGalleryImageDragActive = isGalleryImageDragData(active?.data.current);
+  const trimmedSearchTerm = boardSearchTerm.trim();
+  const normalizedSearchTerm = trimmedSearchTerm.toLowerCase();
+  const matchesSearch = useCallback(
+    (name: string) => !normalizedSearchTerm || name.toLowerCase().includes(normalizedSearchTerm),
+    [normalizedSearchTerm]
+  );
+
+  const selectedBoard = gallery.boards.find((board) => board.id === gallery.selectedBoardId) ?? null;
+  const uncategorizedBoard = gallery.boards.find((board) => board.kind === 'uncategorized') ?? null;
+  const projectBoard = gallery.projectBoardId
+    ? (gallery.boards.find((board) => board.id === gallery.projectBoardId) ?? null)
+    : null;
+  const projectRowName = projectBoard?.name ?? projectName;
+  const dateBoards = gallery.boards.filter((board) => board.kind === 'date' && matchesSearch(board.name));
+  const regularBoards = gallery.boards.filter(
+    (board) => board.kind === 'board' && board.id !== gallery.projectBoardId && matchesSearch(board.name)
+  );
+  const showProjectRow = matchesSearch(projectRowName);
+  const showUncategorizedRow = uncategorizedBoard !== null && matchesSearch(uncategorizedBoard.name);
+  const hasAnyMatch = showProjectRow || showUncategorizedRow || dateBoards.length > 0 || regularBoards.length > 0;
+  const hasExactMatch =
+    gallery.boards.some((board) => board.name.toLowerCase() === normalizedSearchTerm) ||
+    projectRowName.toLowerCase() === normalizedSearchTerm;
+  const canCreateFromSearch = trimmedSearchTerm.length > 0 && !hasExactMatch;
+
+  const closeAndReset = useCallback(() => {
+    setIsOpen(false);
+    setBoardSearchTerm('');
+  }, []);
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const dragData = event.active.data.current;
+      const dropData = event.over?.data.current;
+
+      if (isGalleryImageDragData(dragData) && isGalleryBoardDropData(dropData) && dropData.boardKind === 'board') {
+        const imageNames = getGalleryImageNamesOutsideBoard(dragData, dropData.boardId);
+
+        if (imageNames.length > 0) {
+          void imageActions.moveImagesToBoard(imageNames, dropData.boardId);
+        }
+      }
+
+      if (dragOpenedMenuRef.current) {
+        dragOpenedMenuRef.current = false;
+        closeAndReset();
+      }
+    },
+    [closeAndReset, imageActions]
+  );
+
+  const handleDragCancel = useCallback(() => {
+    if (dragOpenedMenuRef.current) {
+      dragOpenedMenuRef.current = false;
+      closeAndReset();
+    }
+  }, [closeAndReset]);
+
+  const handleDragStart = useCallback((event: DragStartEvent) => {
+    if (!isGalleryImageDragData(event.active.data.current)) {
+      return;
+    }
+
+    dragOpenedMenuRef.current = true;
+    setBoardMenuTarget(null);
+    setBoardSearchTerm('');
+    setIsOpen(true);
+  }, []);
+
+  useDndMonitor({
+    onDragCancel: handleDragCancel,
+    onDragEnd: handleDragEnd,
+    onDragStart: handleDragStart,
+  });
+
+  const createBoardFromSearch = useCallback(() => {
+    if (!canCreateFromSearch) {
+      return;
+    }
+
+    closeAndReset();
+    void actions.createBoard(trimmedSearchTerm);
+  }, [actions, canCreateFromSearch, closeAndReset, trimmedSearchTerm]);
+
+  const openBoardMenu = useCallback((board: GalleryBoard, x: number, y: number) => {
+    setBoardMenuTarget({ board, x, y });
+  }, []);
+
+  const clearSearch = useCallback(() => {
+    setBoardSearchTerm('');
+  }, []);
+
+  const clearSearchButton = useMemo(
+    () =>
+      boardSearchTerm ? (
+        <CloseButton aria-label={t('common.clearSearch')} size="2xs" onClick={clearSearch} me="-2">
+          <XIcon />
+        </CloseButton>
+      ) : null,
+    [boardSearchTerm, clearSearch, t]
+  );
+
+  const searchStartElement = useMemo(() => <Icon as={SearchIcon} size="xs" />, []);
+  const menuPositioning = useMemo(() => ({ placement: 'bottom-start' as const }), []);
+
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (event.open) {
+        setIsOpen(true);
+        return;
+      }
+
+      if (boardMenuActiveRef.current || isGalleryImageDragActive) {
+        return;
+      }
+
+      closeAndReset();
+    },
+    [closeAndReset, isGalleryImageDragActive]
+  );
+
+  const handleSearchChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
+    setBoardSearchTerm(event.currentTarget.value);
+  }, []);
+
+  const handleSearchKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLInputElement>) => {
+      event.stopPropagation();
+
+      if (event.key === 'Enter' && !hasAnyMatch) {
+        event.preventDefault();
+        createBoardFromSearch();
+      }
+    },
+    [createBoardFromSearch, hasAnyMatch]
+  );
+
+  const handleSelectProjectBoard = useCallback(() => {
+    closeAndReset();
+    void actions.selectProjectBoard();
+  }, [actions, closeAndReset]);
+
+  const handleBoardMenuActiveChange = useCallback((isActive: boolean) => {
+    boardMenuActiveRef.current = isActive;
+  }, []);
+
+  const handleBoardMenuClose = useCallback(() => setBoardMenuTarget(null), []);
+
+  return (
+    <>
+      <Menu.Root open={isOpen} positioning={menuPositioning} onOpenChange={handleOpenChange}>
+        <Menu.Trigger asChild>
+          <Button minW="0" size="sm" variant="outline" w="full" px="1">
+            {selectedBoard ? (
+              <BoardOptionContent
+                badge={selectedBoard.id === gallery.projectBoardId ? t('common.project') : undefined}
+                badgeColor={selectedBoard.id === gallery.projectBoardId ? 'blue' : undefined}
+                board={selectedBoard}
+                isSelected={false}
+              />
+            ) : (
+              <Text fontSize="xs" me="auto">
+                {t('widgets.gallery.loadingBoard')}
+              </Text>
+            )}
+            <Icon as={ChevronDownIcon} boxSize="3" flexShrink={0} />
+          </Button>
+        </Menu.Trigger>
+        <Portal>
+          <Menu.Positioner>
+            <Menu.Content
+              maxH="min(30rem, calc(100vh - 6rem))"
+              minW="min(22rem, calc(100vw - 2rem))"
+              overflow="hidden"
+              p="0"
+            >
+              <Stack gap="2" p="2">
+                <InputGroup startElement={searchStartElement} endElement={clearSearchButton}>
+                  <Input
+                    aria-label={t('widgets.gallery.searchOrCreateBoards')}
+                    placeholder={t('widgets.gallery.searchOrCreateBoards')}
+                    size="sm"
+                    value={boardSearchTerm}
+                    onChange={handleSearchChange}
+                    onKeyDown={handleSearchKeyDown}
+                  />
+                </InputGroup>
+                <BoardListControls />
+              </Stack>
+              <Menu.Separator borderColor="border.subtle" m="0" />
+              <ScrollArea.Root maxH="20rem" size="xs" variant="hover" w="full">
+                <ScrollArea.Viewport maxH="inherit" w="full">
+                  <ScrollArea.Content py="1">
+                    {showProjectRow &&
+                      (projectBoard ? (
+                        <BoardRow
+                          badge={t('common.project')}
+                          badgeColor="blue"
+                          board={projectBoard}
+                          isSelected={projectBoard.id === gallery.selectedBoardId}
+                          onOpenMenu={openBoardMenu}
+                          onSelectBoard={actions.selectBoard}
+                          onSelectComplete={closeAndReset}
+                        />
+                      ) : (
+                        <Menu.Item value="__project-board__" onClick={handleSelectProjectBoard}>
+                          <HStack gap="2" minW="0" w="full">
+                            <BoardCoverIcon icon={PinIcon} />
+                            <Text flex="1" fontSize="xs" fontWeight="500" minW="0" truncate>
+                              {projectRowName}
+                            </Text>
+                            <Badge colorPalette="blue" flexShrink={0} size="xs" variant="subtle">
+                              {t('common.project')}
+                            </Badge>
+                          </HStack>
+                        </Menu.Item>
+                      ))}
+                    {showUncategorizedRow && uncategorizedBoard && (
+                      <BoardRow
+                        board={uncategorizedBoard}
+                        isSelected={uncategorizedBoard.id === gallery.selectedBoardId}
+                        onOpenMenu={openBoardMenu}
+                        onSelectBoard={actions.selectBoard}
+                        onSelectComplete={closeAndReset}
+                      />
+                    )}
+                    {dateBoards.length > 0 && (
+                      <>
+                        <BoardGroupLabel>{t('widgets.gallery.boardGroups.byDate')}</BoardGroupLabel>
+                        {dateBoards.map((board) => (
+                          <BoardRow
+                            key={board.id}
+                            board={board}
+                            isSelected={board.id === gallery.selectedBoardId}
+                            onSelectBoard={actions.selectBoard}
+                            onSelectComplete={closeAndReset}
+                          />
+                        ))}
+                      </>
+                    )}
+                    {(regularBoards.length > 0 || canCreateFromSearch) && (
+                      <BoardGroupLabel>{t('widgets.gallery.boardGroups.boards')}</BoardGroupLabel>
+                    )}
+                    {regularBoards.map((board) => (
+                      <BoardRow
+                        key={board.id}
+                        badge={board.archived ? t('common.archived') : undefined}
+                        badgeColor="gray"
+                        board={board}
+                        isSelected={board.id === gallery.selectedBoardId}
+                        onOpenMenu={openBoardMenu}
+                        onSelectBoard={actions.selectBoard}
+                        onSelectComplete={closeAndReset}
+                      />
+                    ))}
+                    {!hasAnyMatch && !canCreateFromSearch && (
+                      <Text color="fg.subtle" fontSize="2xs" px="3" py="2">
+                        {t('widgets.gallery.noBoardsMatchSearch')}
+                      </Text>
+                    )}
+                    {canCreateFromSearch && (
+                      <Menu.Item value="__create-board__" onClick={createBoardFromSearch}>
+                        <HStack gap="2" minW="0" w="full">
+                          <BoardCoverIcon icon={PlusIcon} />
+                          <Text flex="1" fontSize="xs" fontWeight="600" minW="0" truncate>
+                            {t('widgets.gallery.createBoardNamed', { name: trimmedSearchTerm })}
+                          </Text>
+                        </HStack>
+                      </Menu.Item>
+                    )}
+                  </ScrollArea.Content>
+                </ScrollArea.Viewport>
+                <ScrollArea.Scrollbar>
+                  <ScrollArea.Thumb />
+                </ScrollArea.Scrollbar>
+              </ScrollArea.Root>
+            </Menu.Content>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <GalleryBoardMenu
+        target={boardMenuTarget}
+        onActiveChange={handleBoardMenuActiveChange}
+        onClose={handleBoardMenuClose}
+      />
+    </>
+  );
+};
+
+const BoardListControls = () => {
+  const { t } = useTranslation();
+  const { actions, gallery } = useGalleryWidget();
+  const { boardOrderBy, boardOrderDir, showArchivedBoards, showDateBoards } = gallery.settings;
+  const isAscending = boardOrderDir === 'ASC';
+  const handleOrderByName = useCallback(() => actions.updateSettings({ boardOrderBy: 'board_name' }), [actions]);
+  const handleOrderByCreated = useCallback(() => actions.updateSettings({ boardOrderBy: 'created_at' }), [actions]);
+
+  const handleToggleOrderDir = useCallback(
+    () => actions.updateSettings({ boardOrderDir: isAscending ? 'DESC' : 'ASC' }),
+    [actions, isAscending]
+  );
+
+  const handleToggleDateBoards = useCallback(
+    () => actions.updateSettings({ showDateBoards: !showDateBoards }),
+    [actions, showDateBoards]
+  );
+
+  const handleToggleArchivedBoards = useCallback(
+    () => actions.updateSettings({ showArchivedBoards: !showArchivedBoards }),
+    [actions, showArchivedBoards]
+  );
+
+  return (
+    <HStack gap="1" justify="space-between">
+      <HStack gap="1">
+        <Button size="2xs" variant={boardOrderBy === 'board_name' ? 'solid' : 'outline'} onClick={handleOrderByName}>
+          {t('common.name')}
+        </Button>
+        <Button size="2xs" variant={boardOrderBy === 'created_at' ? 'solid' : 'outline'} onClick={handleOrderByCreated}>
+          {t('common.created')}
+        </Button>
+        <IconButton
+          aria-label={
+            isAscending ? t('widgets.gallery.sortBoardsDescending') : t('widgets.gallery.sortBoardsAscending')
+          }
+          size="2xs"
+          variant="outline"
+          onClick={handleToggleOrderDir}
+        >
+          {isAscending ? <ArrowUpAZIcon /> : <ArrowDownAZIcon />}
+        </IconButton>
+      </HStack>
+      <HStack gap="1">
+        <IconButton
+          aria-label={showDateBoards ? t('widgets.gallery.hideDateBoards') : t('widgets.gallery.showDateBoards')}
+          aria-pressed={showDateBoards}
+          size="2xs"
+          title={showDateBoards ? t('widgets.gallery.hideDateBoards') : t('widgets.gallery.showDateBoards')}
+          variant={showDateBoards ? 'solid' : 'outline'}
+          onClick={handleToggleDateBoards}
+        >
+          <CalendarIcon />
+        </IconButton>
+        <IconButton
+          aria-label={
+            showArchivedBoards ? t('widgets.gallery.hideArchivedBoards') : t('widgets.gallery.showArchivedBoards')
+          }
+          aria-pressed={showArchivedBoards}
+          size="2xs"
+          title={showArchivedBoards ? t('widgets.gallery.hideArchivedBoards') : t('widgets.gallery.showArchivedBoards')}
+          variant={showArchivedBoards ? 'solid' : 'outline'}
+          onClick={handleToggleArchivedBoards}
+        >
+          <ArchiveIcon />
+        </IconButton>
+      </HStack>
+    </HStack>
+  );
+};
+
+const BoardGroupLabel = ({ children }: { children: string }) => (
+  <Text color="fg.subtle" fontSize="2xs" fontWeight="700" px="3" pb="0.5" pt="2" textTransform="uppercase">
+    {children}
+  </Text>
+);
+
+const BoardRow = ({
+  badge,
+  badgeColor,
+  board,
+  isSelected,
+  onOpenMenu,
+  onSelectBoard,
+  onSelectComplete,
+}: {
+  badge?: string;
+  badgeColor?: 'blue' | 'gray';
+  board: GalleryBoard;
+  isSelected: boolean;
+  onOpenMenu?: (board: GalleryBoard, x: number, y: number) => void;
+  onSelectBoard: (boardId: string) => void;
+  onSelectComplete: () => void;
+}) => {
+  const { t } = useTranslation();
+  const { active } = useDndContext();
+  const dragData = active?.data.current;
+
+  const canDropImages =
+    board.kind === 'board' &&
+    isGalleryImageDragData(dragData) &&
+    getGalleryImageNamesOutsideBoard(dragData, board.id).length > 0;
+
+  const { isOver, setNodeRef } = useDroppable({
+    data: getGalleryBoardDropData(board.id, board.kind),
+    disabled: !canDropImages,
+    id: getGalleryBoardDropId(board.id),
+  });
+
+  const hoverCss = useMemo(
+    () => (onOpenMenu ? { '&:hover .board-row-actions': { opacity: 1 } } : undefined),
+    [onOpenMenu]
+  );
+
+  const handleSelect = useCallback(() => {
+    onSelectComplete();
+    onSelectBoard(board.id);
+  }, [board.id, onSelectBoard, onSelectComplete]);
+
+  const handleContextMenu = useCallback(
+    (event: MouseEvent) => {
+      if (!onOpenMenu) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      onOpenMenu(board, event.clientX, event.clientY);
+    },
+    [board, onOpenMenu]
+  );
+
+  const handleActionsClick = useCallback(
+    (event: MouseEvent<HTMLButtonElement>) => {
+      if (!onOpenMenu) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      const rect = event.currentTarget.getBoundingClientRect();
+
+      onOpenMenu(board, rect.left, rect.bottom);
+    },
+    [board, onOpenMenu]
+  );
+
+  const stopPropagation = useCallback((event: MouseEvent | PointerEvent) => event.stopPropagation(), []);
+
+  return (
+    <Menu.Item
+      ref={setNodeRef}
+      bg={isOver ? 'accent.subtle' : undefined}
+      css={hoverCss}
+      outline={canDropImages ? '1px dashed' : undefined}
+      outlineColor={canDropImages ? 'accent.solid' : undefined}
+      value={board.id}
+      onClick={handleSelect}
+      onContextMenu={onOpenMenu ? handleContextMenu : undefined}
+    >
+      <BoardOptionContent badge={badge} badgeColor={badgeColor} board={board} isSelected={isSelected} showOwner />
+      {onOpenMenu && (
+        <IconButton
+          aria-label={t('widgets.gallery.boardActionsForBoard', { name: board.name })}
+          className="board-row-actions"
+          flexShrink={0}
+          opacity={0}
+          size="2xs"
+          transition="opacity var(--wb-motion-duration-medium) ease"
+          variant="ghost"
+          onClick={handleActionsClick}
+          onPointerDown={stopPropagation}
+          onPointerUp={stopPropagation}
+        >
+          <MoreVerticalIcon />
+        </IconButton>
+      )}
+    </Menu.Item>
+  );
+};
+
+const BoardOptionContent = ({
+  badge,
+  badgeColor = 'gray',
+  board,
+  isSelected,
+  showOwner = false,
+}: {
+  badge?: string;
+  badgeColor?: 'blue' | 'gray';
+  board: GalleryBoard;
+  isSelected: boolean;
+  /** Render the owner line (admins on multi-user backends); off in the compact trigger. */
+  showOwner?: boolean;
+}) => {
+  const counts = getBoardCounts(board);
+
+  return (
+    <HStack gap="2" minW="0" w="full">
+      <BoardCover board={board} />
+      <Stack gap="1" minW="0">
+        <Text fontSize="xs" fontWeight={isSelected ? '700' : '500'} minW="0" lineHeight={1} truncate>
+          {board.name}
+        </Text>
+        {showOwner && board.ownerName ? (
+          <Text color="fg.subtle" fontSize="2xs" minW="0" lineHeight={1} truncate>
+            {board.ownerName}
+          </Text>
+        ) : null}
+      </Stack>
+      <Flex ms="auto">
+        {badge && (
+          <Badge colorPalette={badgeColor} flexShrink={0} size="xs" variant="subtle">
+            {badge}
+          </Badge>
+        )}
+        <Badge flexShrink={0} size="xs" variant={isSelected ? 'solid' : 'subtle'}>
+          {counts.imageCount} | {counts.assetCount}
+        </Badge>
+      </Flex>
+    </HStack>
+  );
+};
+
+const BoardCoverIcon = ({ icon }: { icon: LucideIcon }) => (
+  <Flex
+    align="center"
+    bg="bg.emphasized"
+    borderWidth="1px"
+    borderColor="border.subtle"
+    boxSize="7"
+    color="fg.subtle"
+    flexShrink={0}
+    justify="center"
+    rounded="md"
+  >
+    <Icon as={icon} boxSize="4" />
+  </Flex>
+);
+
+const BoardCover = ({ board }: { board: GalleryBoard }) => {
+  if (board.coverThumbnailUrl) {
+    return (
+      <Image
+        alt=""
+        bg="bg.emphasized"
+        borderWidth="1px"
+        borderColor="border.subtle"
+        boxSize="7"
+        flexShrink={0}
+        objectFit="cover"
+        rounded="md"
+        src={board.coverThumbnailUrl}
+      />
+    );
+  }
+
+  return <BoardCoverIcon icon={board.kind === 'date' ? CalendarIcon : ImageIcon} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryImageGrid.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryImageGrid.tsx
new file mode 100644
index 00000000000..96493e01570
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryImageGrid.tsx
@@ -0,0 +1,779 @@
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { GalleryThumbnailFit } from '@workbench/gallery/settings';
+
+import { Badge, Box, Flex, ProgressCircle, ScrollArea, Skeleton, Spinner, Text } from '@chakra-ui/react';
+import { useDraggable } from '@dnd-kit/core';
+import { CSS } from '@dnd-kit/utilities';
+import { useQueueItemProgressImage } from '@workbench/backend/progressImageStore';
+import { useQueueItemProgress } from '@workbench/backend/progressStore';
+import { IconButton } from '@workbench/components/ui';
+import { ImageContextMenu, type ImageContextMenuTarget } from '@workbench/image-actions';
+import { StreamingImageFrame } from '@workbench/images/StreamingImageFrame';
+import { progressImageToStreamingSource } from '@workbench/images/streamingImageSource';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { StarIcon, UploadIcon } from 'lucide-react';
+import {
+  useEffect,
+  useEffectEvent,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type DragEvent,
+  type MouseEvent,
+} from 'react';
+import { useVirtualizer } from 'react-hook-tanstack-virtual';
+import { useTranslation } from 'react-i18next';
+
+import type { GalleryImageDragImage } from './galleryDnd';
+import type { GalleryQueuePlaceholder } from './galleryStateView';
+
+import { getGalleryImageDragData, getGalleryImageDragId } from './galleryDnd';
+import { useGalleryWidget } from './GalleryWidgetContext';
+
+const GRID_GAP_PX = 4;
+const THUMBNAIL_HOVER_CSS = {
+  '&:hover .gallery-thumb-overlay': { opacity: 1 },
+} as const;
+const THUMBNAIL_BUTTON_STYLE = {
+  background: 'transparent',
+  border: 0,
+  cursor: 'pointer',
+  display: 'block',
+  height: '100%',
+  inset: 0,
+  minWidth: 0,
+  padding: 0,
+  position: 'absolute',
+  width: '100%',
+} as const;
+
+const viewportWidthCache = new Map<'stacked' | 'wide', number>();
+
+const getGalleryColumnCount = (imageDensityPercent: number, layout: 'stacked' | 'wide'): number => {
+  const min = 2;
+  const max = layout === 'wide' ? 10 : 6;
+  const percent = Math.min(100, Math.max(0, imageDensityPercent));
+
+  return Math.round(min + ((max - min) * percent) / 100);
+};
+
+const dragEventContainsFiles = (event: DragEvent): boolean => Array.from(event.dataTransfer.types).includes('Files');
+
+type GridCell =
+  | { kind: 'image'; image: GalleryImage; imageIndex: number }
+  | { kind: 'placeholder'; placeholder: GalleryQueuePlaceholder };
+
+export const GalleryImageGrid = ({ layout }: { layout: 'stacked' | 'wide' }) => {
+  const { t } = useTranslation();
+  const { actions, gallery, imageActions, runtime } = useGalleryWidget();
+  const dispatch = useWorkbenchDispatch();
+  const [contextMenuTarget, setContextMenuTarget] = useState<ImageContextMenuTarget | null>(null);
+  const [isDropActive, setIsDropActive] = useState(false);
+  const [viewportWidth, setViewportWidth] = useState(() => viewportWidthCache.get(layout) ?? 0);
+  const dragDepthRef = useRef(0);
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+  const { imageDensityPercent, imageOrderDir, paginationMode, showImageDimensions, starredFirst, thumbnailFit } =
+    gallery.settings;
+  const antialiasProgressImages = useActiveProjectSelector((project) => project.settings.antialiasProgressImages);
+  const columnCount = getGalleryColumnCount(imageDensityPercent, layout);
+  const selectedNames = useMemo(() => new Set(gallery.selectedImageNames), [gallery.selectedImageNames]);
+  const isComparisonActive =
+    gallery.compareImageName !== null &&
+    gallery.selectedImageName !== null &&
+    gallery.compareImageName !== gallery.selectedImageName;
+  const selectedBoardName =
+    gallery.boards.find((board) => board.id === gallery.selectedBoardId)?.name ??
+    t('widgets.gallery.selectedBoardFallback');
+  const isEmpty = gallery.images.length === 0 && gallery.pendingPlaceholders.length === 0;
+
+  // Fresh generations are unstarred, so with newest-first ordering they land
+  // right after the starred block — pending placeholders go there too.
+  const leadingStarredCount = useMemo(() => {
+    if (imageOrderDir !== 'DESC' || !starredFirst) {
+      return 0;
+    }
+
+    let count = 0;
+
+    while (count < gallery.images.length && gallery.images[count].starred) {
+      count += 1;
+    }
+
+    return count;
+  }, [gallery.images, imageOrderDir, starredFirst]);
+
+  const cells = useMemo<GridCell[]>(() => {
+    const imageCells: GridCell[] = gallery.images.map((image, imageIndex) => ({
+      image,
+      imageIndex,
+      kind: 'image',
+    }));
+    const placeholderCells: GridCell[] = gallery.pendingPlaceholders.map((placeholder) => ({
+      kind: 'placeholder',
+      placeholder,
+    }));
+
+    if (imageOrderDir !== 'DESC') {
+      return [...imageCells, ...placeholderCells];
+    }
+
+    return [...imageCells.slice(0, leadingStarredCount), ...placeholderCells, ...imageCells.slice(leadingStarredCount)];
+  }, [gallery.images, gallery.pendingPlaceholders, imageOrderDir, leadingStarredCount]);
+
+  const getCellIndexForImage = (imageIndex: number): number =>
+    imageOrderDir === 'DESC' && imageIndex >= leadingStarredCount
+      ? imageIndex + gallery.pendingPlaceholders.length
+      : imageIndex;
+
+  const rowCount = Math.ceil(cells.length / columnCount);
+
+  const cellSizePx =
+    viewportWidth > 0 ? Math.max(1, (viewportWidth - GRID_GAP_PX * (columnCount - 1)) / columnCount) : 96;
+
+  const rowHeightPx = cellSizePx + GRID_GAP_PX;
+
+  const virtualizer = useVirtualizer({
+    count: rowCount,
+    estimateSize: () => rowHeightPx,
+    getScrollElement: () => viewportRef.current,
+    overscan: 4,
+  });
+
+  const measureVirtualizer = useEffectEvent(() => {
+    virtualizer.measure();
+  });
+
+  useLayoutEffect(() => {
+    const viewport = viewportRef.current;
+
+    if (!viewport) {
+      return;
+    }
+
+    const setMeasuredWidth = (width: number) => {
+      if (width <= 0) {
+        return;
+      }
+
+      viewportWidthCache.set(layout, width);
+      setViewportWidth((currentWidth) => (currentWidth === width ? currentWidth : width));
+    };
+
+    const observer = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width;
+
+      if (typeof width === 'number') {
+        setMeasuredWidth(width);
+      }
+    });
+
+    setMeasuredWidth(viewport.clientWidth);
+    observer.observe(viewport);
+
+    return () => observer.disconnect();
+  }, [isEmpty, layout]);
+
+  useEffect(() => {
+    measureVirtualizer();
+  }, [rowHeightPx]);
+
+  const virtualRows = virtualizer.virtualItems;
+  const lastVisibleRowIndex = virtualRows[virtualRows.length - 1]?.index ?? 0;
+
+  useEffect(() => {
+    if (paginationMode === 'infinite' && rowCount > 0 && lastVisibleRowIndex >= rowCount - 2) {
+      actions.loadMore();
+    }
+  }, [actions, lastVisibleRowIndex, paginationMode, rowCount]);
+
+  const activeContextMenuTarget = useMemo(() => {
+    const primaryTargetImageName = contextMenuTarget?.images[0]?.imageName;
+
+    if (!primaryTargetImageName) {
+      return contextMenuTarget;
+    }
+
+    return gallery.images.some((image) => image.imageName === primaryTargetImageName) ? contextMenuTarget : null;
+  }, [contextMenuTarget, gallery.images]);
+
+  const handleThumbnailClick = useCallback(
+    (image: GalleryImage, event: MouseEvent) => {
+      if (event.shiftKey) {
+        const targetIndex = gallery.images.findIndex((candidate) => candidate.imageName === image.imageName);
+        const anchorIndex = gallery.images.findIndex((candidate) => candidate.imageName === gallery.selectedImageName);
+
+        if (targetIndex !== -1 && anchorIndex !== -1 && targetIndex !== anchorIndex) {
+          const start = Math.min(anchorIndex, targetIndex);
+          const end = Math.max(anchorIndex, targetIndex);
+
+          actions.selectImageRange(
+            gallery.images.slice(start, end + 1).map((candidate) => candidate.imageName),
+            image
+          );
+          return;
+        }
+      }
+
+      if (event.ctrlKey || event.metaKey) {
+        actions.toggleImageInSelection(image);
+      } else {
+        actions.selectImage(image);
+      }
+    },
+    [actions, gallery.images, gallery.selectedImageName]
+  );
+
+  const handleThumbnailContextMenu = useCallback(
+    (image: GalleryImage, x: number, y: number) => {
+      if (selectedNames.has(image.imageName) && selectedNames.size > 1) {
+        const selectionImages = [
+          image,
+          ...gallery.images.filter(
+            (candidate) => candidate.imageName !== image.imageName && selectedNames.has(candidate.imageName)
+          ),
+        ];
+
+        setContextMenuTarget({ images: selectionImages, x, y });
+        return;
+      }
+
+      setContextMenuTarget({ images: [image], x, y });
+    },
+    [gallery.images, selectedNames]
+  );
+
+  const getDragImages = useCallback(
+    (image: GalleryImage): GalleryImageDragImage[] => {
+      if (selectedNames.has(image.imageName) && selectedNames.size > 1) {
+        return gallery.images
+          .filter((candidate) => selectedNames.has(candidate.imageName))
+          .map((candidate) => ({
+            boardId: candidate.boardId,
+            imageName: candidate.imageName,
+          }));
+      }
+
+      return [{ boardId: image.boardId, imageName: image.imageName }];
+    },
+    [gallery.images, selectedNames]
+  );
+
+  const handleDragEnter = useCallback((event: DragEvent) => {
+    if (!dragEventContainsFiles(event)) {
+      return;
+    }
+
+    event.preventDefault();
+    dragDepthRef.current += 1;
+    setIsDropActive(true);
+  }, []);
+
+  const handleDragLeave = useCallback((event: DragEvent) => {
+    if (!dragEventContainsFiles(event)) {
+      return;
+    }
+
+    dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+
+    if (dragDepthRef.current === 0) {
+      setIsDropActive(false);
+    }
+  }, []);
+
+  const handleDragOver = useCallback((event: DragEvent) => {
+    if (dragEventContainsFiles(event)) {
+      event.preventDefault();
+    }
+  }, []);
+
+  const handleDrop = useCallback(
+    (event: DragEvent) => {
+      event.preventDefault();
+      dragDepthRef.current = 0;
+      setIsDropActive(false);
+
+      const files = Array.from(event.dataTransfer.files);
+
+      if (files.length > 0) {
+        void actions.uploadFiles(files);
+      }
+    },
+    [actions]
+  );
+
+  const handleShowProgressImages = useCallback(() => {
+    dispatch({
+      settings: { showProgressImagesInViewer: true },
+      type: 'setActiveProjectSettings',
+    });
+  }, [dispatch]);
+
+  const handleToggleStarred = useCallback(
+    (image: GalleryImage) => void imageActions.setImagesStarred([image.imageName], !image.starred),
+    [imageActions]
+  );
+
+  const handleCloseContextMenu = useCallback(() => setContextMenuTarget(null), []);
+
+  const navigate = useEffectEvent((direction: 'down' | 'left' | 'right' | 'up') => {
+    const imageCount = gallery.images.length;
+
+    if (imageCount === 0) {
+      return;
+    }
+
+    const selectedIndex = gallery.images.findIndex((image) => image.imageName === gallery.selectedImageName);
+    const fallbackIndex = selectedIndex === -1 ? 0 : selectedIndex;
+    const delta =
+      direction === 'right' ? 1 : direction === 'left' ? -1 : direction === 'down' ? columnCount : -columnCount;
+    const nextIndex = Math.min(imageCount - 1, Math.max(0, fallbackIndex + delta));
+    const nextImage = gallery.images[nextIndex];
+
+    if (nextImage && (nextIndex !== selectedIndex || selectedIndex === -1)) {
+      actions.selectImage(nextImage);
+      virtualizer.scrollToIndex(Math.floor(getCellIndexForImage(nextIndex) / columnCount));
+    }
+  });
+
+  const executeGalleryHotkey = useEffectEvent((commandId: string) => {
+    if (commandId === 'gallery.selectAllOnPage') {
+      const primaryImage = gallery.images[0];
+
+      if (primaryImage) {
+        actions.selectImageRange(
+          gallery.images.map((image) => image.imageName),
+          primaryImage
+        );
+      }
+      return;
+    }
+
+    if (commandId === 'gallery.clearSelection') {
+      dispatch({
+        type: 'patchWidgetValues',
+        values: {
+          selectedImage: null,
+          selectedImageName: null,
+          selectedImageNames: [],
+        },
+        widgetId: 'gallery',
+      });
+      return;
+    }
+
+    if (commandId === 'gallery.deleteSelection' && gallery.selectedImageNames.length > 0) {
+      void imageActions.deleteImages(gallery.selectedImageNames);
+      return;
+    }
+
+    if (commandId === 'gallery.starImage') {
+      const imageNames = gallery.selectedImageNames.length
+        ? gallery.selectedImageNames
+        : gallery.selectedImageName
+          ? [gallery.selectedImageName]
+          : [];
+      const selectedImages = gallery.images.filter((image) => imageNames.includes(image.imageName));
+
+      if (selectedImages.length > 0) {
+        const shouldStar = selectedImages.some((image) => !image.starred);
+
+        void imageActions.setImagesStarred(imageNames, shouldStar);
+      }
+    }
+  });
+
+  useEffect(() => {
+    const directions = [
+      ['gallery.selectAllOnPage', t('widgets.gallery.commands.selectAllOnPage'), null, ['mod+a']],
+      ['gallery.clearSelection', t('widgets.gallery.commands.clearSelection'), null, ['esc']],
+      ['gallery.galleryNavUp', t('widgets.gallery.commands.navigationUp'), 'up', ['arrowup']],
+      ['gallery.galleryNavRight', t('widgets.gallery.commands.navigationRight'), 'right', ['arrowright']],
+      ['gallery.galleryNavDown', t('widgets.gallery.commands.navigationDown'), 'down', ['arrowdown']],
+      ['gallery.galleryNavLeft', t('widgets.gallery.commands.navigationLeft'), 'left', ['arrowleft']],
+      ['gallery.galleryNavUpAlt', t('widgets.gallery.commands.navigationUp'), 'up', ['alt+arrowup']],
+      ['gallery.galleryNavRightAlt', t('widgets.gallery.commands.navigationRight'), 'right', ['alt+arrowright']],
+      ['gallery.galleryNavDownAlt', t('widgets.gallery.commands.navigationDown'), 'down', ['alt+arrowdown']],
+      ['gallery.galleryNavLeftAlt', t('widgets.gallery.commands.navigationLeft'), 'left', ['alt+arrowleft']],
+      ['gallery.deleteSelection', t('widgets.gallery.commands.deleteSelection'), null, ['delete', 'backspace']],
+      ['gallery.starImage', t('widgets.gallery.commands.toggleStarImage'), null, ['.']],
+    ] as const;
+    const disposers = directions.flatMap(([id, title, direction, defaultKeys]) => [
+      runtime.commands.register({
+        handler: () => (direction ? navigate(direction) : executeGalleryHotkey(id)),
+        id,
+        title,
+      }),
+      runtime.hotkeys.register({
+        commandId: id,
+        defaultKeys: [...defaultKeys],
+        id,
+        title,
+      }),
+    ]);
+
+    return () => {
+      disposers.forEach((dispose) => dispose());
+    };
+  }, [runtime.commands, runtime.hotkeys, t]);
+
+  return (
+    <Box
+      flex="1"
+      maxW="full"
+      minH="0"
+      minW="0"
+      position="relative"
+      w="full"
+      onDragEnter={handleDragEnter}
+      onDragLeave={handleDragLeave}
+      onDragOver={handleDragOver}
+      onDrop={handleDrop}
+    >
+      {isEmpty ? (
+        <Flex align="center" color="fg.subtle" h="full" justify="center" minH="8rem">
+          <Text fontSize="2xs">
+            {gallery.isLoading ? t('widgets.gallery.loadingBackendGallery') : t('widgets.gallery.noImagesMatch')}
+          </Text>
+        </Flex>
+      ) : (
+        <ScrollArea.Root h="full" minH="0" size="xs" variant="hover" w="full">
+          <ScrollArea.Viewport
+            ref={viewportRef}
+            aria-label={t('widgets.gallery.imagesAriaLabel')}
+            h="full"
+            role="listbox"
+            tabIndex={0}
+            w="full"
+          >
+            <ScrollArea.Content>
+              <Box h={`${virtualizer.totalSize}px`} position="relative" w="full">
+                {virtualRows.map((virtualRow) => (
+                  <Box
+                    key={virtualRow.key}
+                    display="grid"
+                    gap={`${GRID_GAP_PX}px`}
+                    gridTemplateColumns={`repeat(${columnCount}, minmax(0, 1fr))`}
+                    left="0"
+                    position="absolute"
+                    top="0"
+                    transform={`translateY(${virtualRow.start}px)`}
+                    w="full"
+                  >
+                    {cells
+                      .slice(virtualRow.index * columnCount, (virtualRow.index + 1) * columnCount)
+                      .map((cell) =>
+                        cell.kind === 'placeholder' ? (
+                          <GalleryQueuePlaceholderCell
+                            key={cell.placeholder.id}
+                            antialiasProgressImages={antialiasProgressImages}
+                            fit={thumbnailFit}
+                            placeholder={cell.placeholder}
+                            onClick={handleShowProgressImages}
+                          />
+                        ) : (
+                          <GalleryThumbnailCell
+                            key={cell.image.imageName}
+                            alwaysShowDimensions={showImageDimensions}
+                            compareRole={
+                              isComparisonActive && cell.image.imageName === gallery.selectedImageName
+                                ? t('widgets.preview.viewing')
+                                : isComparisonActive && cell.image.imageName === gallery.compareImageName
+                                  ? t('widgets.preview.compare')
+                                  : null
+                            }
+                            fit={thumbnailFit}
+                            getDragImages={getDragImages}
+                            image={cell.image}
+                            isPrimary={cell.image.imageName === gallery.selectedImageName}
+                            isSelected={selectedNames.has(cell.image.imageName)}
+                            onClick={handleThumbnailClick}
+                            onContextMenu={handleThumbnailContextMenu}
+                            onToggleStarred={handleToggleStarred}
+                          />
+                        )
+                      )}
+                  </Box>
+                ))}
+              </Box>
+              {paginationMode === 'infinite' && gallery.isLoading && gallery.images.length > 0 && (
+                <Flex align="center" justify="center" py="2">
+                  <Spinner color="fg.subtle" size="xs" />
+                </Flex>
+              )}
+            </ScrollArea.Content>
+          </ScrollArea.Viewport>
+          <ScrollArea.Scrollbar>
+            <ScrollArea.Thumb />
+          </ScrollArea.Scrollbar>
+        </ScrollArea.Root>
+      )}
+      {isDropActive && (
+        <Flex
+          align="center"
+          bg="bg.muted/80"
+          borderColor="accent.solid"
+          borderStyle="dashed"
+          borderWidth="2px"
+          direction="column"
+          gap="2"
+          inset="0"
+          justify="center"
+          pointerEvents="none"
+          position="absolute"
+          rounded="md"
+          zIndex="1"
+        >
+          <UploadIcon size="20" />
+          <Text fontSize="xs" fontWeight="600">
+            {t('widgets.gallery.dropImagesToUploadToBoard', { name: selectedBoardName })}
+          </Text>
+        </Flex>
+      )}
+      <ImageContextMenu
+        actions={imageActions}
+        boards={gallery.boards}
+        target={activeContextMenuTarget}
+        onClose={handleCloseContextMenu}
+      />
+    </Box>
+  );
+};
+
+const GalleryQueuePlaceholderCell = ({
+  antialiasProgressImages,
+  fit,
+  onClick,
+  placeholder,
+}: {
+  antialiasProgressImages: boolean;
+  fit: GalleryThumbnailFit;
+  onClick: () => void;
+  placeholder: GalleryQueuePlaceholder;
+}) => {
+  const { t } = useTranslation();
+  const progressImage = useQueueItemProgressImage(placeholder.queueItemId, placeholder.itemIndex);
+  const progress = useQueueItemProgress(placeholder.queueItemId);
+  const isActive = progress?.activeItemIndex === placeholder.itemIndex;
+  const percentage = typeof progress?.percentage === 'number' ? Math.round(progress.percentage * 100) : null;
+
+  return (
+    <Box
+      as="button"
+      aria-label={t('widgets.preview.showInProgressDiffusion')}
+      aspectRatio={1}
+      bg="bg"
+      borderColor={isActive ? 'accent.solid' : 'border.subtle'}
+      borderWidth="1px"
+      cursor="pointer"
+      minW="0"
+      rounded="md"
+      overflow="hidden"
+      position="relative"
+      w="full"
+      onClick={onClick}
+    >
+      <StreamingImageFrame
+        fit={fit === 'aspect' ? 'contain' : 'cover'}
+        h="full"
+        liveImage={progressImageToStreamingSource(progressImage)}
+        shouldAntialiasLiveImage={antialiasProgressImages}
+        w="full"
+      >
+        <Skeleton h="full" w="full" />
+      </StreamingImageFrame>
+      {isActive ? <GalleryPlaceholderCircularProgress percentage={percentage} /> : null}
+    </Box>
+  );
+};
+
+const GalleryPlaceholderCircularProgress = ({ percentage }: { percentage: number | null }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Flex
+      align="center"
+      aria-label={
+        percentage === null
+          ? t('widgets.gallery.generationProgress')
+          : t('widgets.gallery.generationProgressPercent', { percentage })
+      }
+      justify="center"
+      alignItems="center"
+      pointerEvents="none"
+      position="absolute"
+      inset="0"
+      zIndex="1"
+    >
+      <ProgressCircle.Root value={percentage} size="xs" bg="bg/85" rounded="full" borderWidth={1} p={0.5}>
+        <ProgressCircle.Circle>
+          <ProgressCircle.Track />
+          <ProgressCircle.Range />
+        </ProgressCircle.Circle>
+      </ProgressCircle.Root>
+    </Flex>
+  );
+};
+
+const GalleryThumbnail = ({
+  alwaysShowDimensions,
+  compareRole,
+  dragImages,
+  fit,
+  image,
+  isPrimary,
+  isSelected,
+  onClick,
+  onContextMenu,
+  onToggleStarred,
+}: {
+  alwaysShowDimensions: boolean;
+  compareRole: string | null;
+  dragImages: GalleryImageDragImage[];
+  fit: GalleryThumbnailFit;
+  image: GalleryImage;
+  isPrimary: boolean;
+  isSelected: boolean;
+  onClick: (image: GalleryImage, event: MouseEvent) => void;
+  onContextMenu: (image: GalleryImage, x: number, y: number) => void;
+  onToggleStarred: (image: GalleryImage) => void;
+}) => {
+  const { t } = useTranslation();
+  const isCompared = compareRole !== null;
+
+  const { isDragging, listeners, setNodeRef, transform } = useDraggable({
+    data: getGalleryImageDragData(dragImages),
+    id: getGalleryImageDragId(image.imageName),
+  });
+
+  const containerStyle = useMemo(() => ({ transform: CSS.Transform.toString(transform) }), [transform]);
+
+  const imageStyle = useMemo(
+    () =>
+      ({
+        display: 'block',
+        height: '100%',
+        inset: 0,
+        maxWidth: 'none',
+        objectFit: fit === 'aspect' ? 'contain' : 'cover',
+        position: 'absolute',
+        width: '100%',
+      }) as const,
+    [fit]
+  );
+
+  const handleContextMenu = useCallback(
+    (event: MouseEvent) => {
+      event.preventDefault();
+      onContextMenu(image, event.clientX, event.clientY);
+    },
+    [image, onContextMenu]
+  );
+
+  const handleClick = useCallback((event: MouseEvent) => onClick(image, event), [image, onClick]);
+
+  const handleToggleStarred = useCallback(
+    (event: MouseEvent<HTMLButtonElement>) => {
+      event.stopPropagation();
+      onToggleStarred(image);
+    },
+    [image, onToggleStarred]
+  );
+
+  return (
+    <Box
+      ref={setNodeRef}
+      {...listeners}
+      aspectRatio={1}
+      bg="bg"
+      borderWidth="2px"
+      borderColor={isSelected || isCompared ? 'accent.solid' : 'border.subtle'}
+      boxShadow={isCompared ? 'inset 0 0 0 1px {colors.accent.solid}' : undefined}
+      css={THUMBNAIL_HOVER_CSS}
+      minW="0"
+      opacity={isDragging ? 0.55 : undefined}
+      overflow="hidden"
+      role="option"
+      aria-selected={isSelected}
+      position="relative"
+      rounded="md"
+      style={containerStyle}
+      touchAction="none"
+      w="full"
+      zIndex={isDragging ? 2 : undefined}
+      onContextMenu={handleContextMenu}
+    >
+      <button
+        aria-label={t('widgets.gallery.selectImageForPreview', { name: image.imageName })}
+        style={THUMBNAIL_BUTTON_STYLE}
+        tabIndex={isPrimary ? 0 : -1}
+        type="button"
+        onClick={handleClick}
+      >
+        <img alt={image.imageName} draggable={false} src={image.thumbnailUrl || image.imageUrl} style={imageStyle} />
+      </button>
+      {compareRole && (
+        <Badge
+          insetInlineStart="1"
+          pointerEvents="none"
+          position="absolute"
+          size="xs"
+          top="1"
+          variant="solid"
+          zIndex="1"
+        >
+          {compareRole}
+        </Badge>
+      )}
+      <IconButton
+        aria-label={
+          image.starred
+            ? t('widgets.gallery.unstarImage', { name: image.imageName })
+            : t('widgets.gallery.starImage', { name: image.imageName })
+        }
+        className="gallery-thumb-overlay"
+        colorPalette={image.starred ? 'yellow' : 'gray'}
+        insetInlineEnd="1"
+        opacity={image.starred ? 1 : 0}
+        position="absolute"
+        size="2xs"
+        top="1"
+        transition="opacity var(--wb-motion-duration-medium) ease"
+        variant="solid"
+        zIndex="1"
+        onClick={handleToggleStarred}
+      >
+        <StarIcon fill={image.starred ? 'currentColor' : 'none'} />
+      </IconButton>
+      {image.width > 0 && image.height > 0 && (
+        <Badge
+          bottom="1"
+          className="gallery-thumb-overlay"
+          insetInlineStart="1"
+          opacity={alwaysShowDimensions ? 1 : 0}
+          pointerEvents="none"
+          position="absolute"
+          size="xs"
+          transition="opacity var(--wb-motion-duration-medium) ease"
+          variant="solid"
+          zIndex="1"
+        >
+          {image.width}x{image.height}
+        </Badge>
+      )}
+    </Box>
+  );
+};
+
+const GalleryThumbnailCell = ({
+  image,
+  getDragImages,
+  ...props
+}: Omit<Parameters<typeof GalleryThumbnail>[0], 'dragImages'> & {
+  getDragImages: (image: GalleryImage) => GalleryImageDragImage[];
+}) => {
+  const dragImages = useMemo(() => getDragImages(image), [getDragImages, image]);
+
+  return <GalleryThumbnail {...props} dragImages={dragImages} image={image} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryPanelContent.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryPanelContent.tsx
new file mode 100644
index 00000000000..2b9856b98e9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryPanelContent.tsx
@@ -0,0 +1,11 @@
+import { Stack } from '@chakra-ui/react';
+
+import { GalleryImageGrid } from './GalleryImageGrid';
+import { GalleryToolbar } from './GalleryToolbar';
+
+export const GalleryPanelContent = ({ layout }: { layout: 'stacked' | 'wide' }) => (
+  <Stack gap="3" p={layout === 'stacked' ? '2' : '3'} h="full" maxW="full" minH="0" minW="0" w="full">
+    <GalleryToolbar layout={layout} />
+    <GalleryImageGrid layout={layout} />
+  </Stack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryToolbar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryToolbar.tsx
new file mode 100644
index 00000000000..f5993c2db8a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryToolbar.tsx
@@ -0,0 +1,353 @@
+import type { GalleryView } from '@workbench/gallery/api';
+
+import {
+  Box,
+  HStack,
+  Icon,
+  Input,
+  InputGroup,
+  Menu,
+  Portal,
+  Slider,
+  Spacer,
+  Stack,
+  Switch,
+  Text,
+} from '@chakra-ui/react';
+import { Button, CloseButton, IconButton, Tabs } from '@workbench/components/ui';
+import { isDateBoardId } from '@workbench/gallery/api';
+import { SearchIcon, SettingsIcon, UploadIcon } from 'lucide-react';
+import { useCallback, useMemo, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { GalleryBoardSelect } from './GalleryBoardSelect';
+import { useGalleryWidget } from './GalleryWidgetContext';
+
+const ACCEPTED_UPLOAD_EXTENSIONS = 'image/png,image/jpeg,image/webp';
+const galleryViewTabs = [
+  { labelKey: 'common.images', value: 'images' },
+  { labelKey: 'common.assets', value: 'assets' },
+] satisfies { labelKey: string; value: GalleryView }[];
+
+const UPLOAD_INPUT_STYLE = { display: 'none' } as const;
+const GALLERY_SETTINGS_POSITIONING = { placement: 'bottom-end' } as const;
+const SEARCH_START_ELEMENT = <Icon as={SearchIcon} size="sm" />;
+
+export const GalleryToolbar = ({ layout }: { layout: 'stacked' | 'wide' }) => {
+  const { t } = useTranslation();
+  const { actions, gallery } = useGalleryWidget();
+  const isWide = layout === 'wide';
+
+  const handleViewChange = useCallback(
+    (event: { value: string }) => actions.setView(event.value as GalleryView),
+    [actions]
+  );
+
+  const handleClearSearch = useCallback(() => actions.setSearchTerm(''), [actions]);
+
+  const handleSearchChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => actions.setSearchTerm(event.currentTarget.value),
+    [actions]
+  );
+
+  const searchClearButton = useMemo(
+    () =>
+      gallery.searchTerm ? (
+        <CloseButton size="2xs" aria-label={t('common.clearSearch')} onClick={handleClearSearch} me="-2" />
+      ) : null,
+    [gallery.searchTerm, handleClearSearch, t]
+  );
+
+  const viewTabs = useMemo(
+    () => (
+      <Tabs.Root size="sm" variant="subtle" value={gallery.galleryView} onValueChange={handleViewChange}>
+        <Tabs.List>
+          {galleryViewTabs.map((item) => (
+            <Tabs.Trigger key={item.value} value={item.value} fontSize="xs">
+              {t(item.labelKey)}
+            </Tabs.Trigger>
+          ))}
+        </Tabs.List>
+      </Tabs.Root>
+    ),
+    [gallery.galleryView, handleViewChange, t]
+  );
+
+  const toolbarActions = useMemo(
+    () => (
+      <HStack gap="2">
+        <GalleryUploadButton />
+        <GallerySettingsMenu />
+      </HStack>
+    ),
+    []
+  );
+
+  const searchInput = useMemo(
+    () => (
+      <InputGroup startElement={SEARCH_START_ELEMENT} endElement={searchClearButton}>
+        <Input
+          aria-label={t('widgets.gallery.searchImagesAriaLabel')}
+          placeholder={t('widgets.gallery.searchImagesPlaceholder')}
+          size="xs"
+          value={gallery.searchTerm}
+          onChange={handleSearchChange}
+        />
+      </InputGroup>
+    ),
+    [gallery.searchTerm, handleSearchChange, searchClearButton, t]
+  );
+
+  return (
+    <Stack gap="2">
+      {isWide ? (
+        <HStack gap="2">
+          <Box flex="1" maxW="16rem" minW="10rem">
+            <GalleryBoardSelect />
+          </Box>
+          {viewTabs}
+          <Spacer />
+          <Box flex="1" maxW="20rem" minW="12rem">
+            {searchInput}
+          </Box>
+          {toolbarActions}
+        </HStack>
+      ) : (
+        <>
+          <GalleryBoardSelect />
+          <HStack justify="space-between">
+            {viewTabs}
+            {toolbarActions}
+          </HStack>
+        </>
+      )}
+      {!isWide && searchInput}
+    </Stack>
+  );
+};
+
+const GalleryUploadButton = () => {
+  const { t } = useTranslation();
+  const { actions, gallery } = useGalleryWidget();
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const selectedBoard = gallery.boards.find((board) => board.id === gallery.selectedBoardId);
+  const isVirtualTarget = isDateBoardId(gallery.selectedBoardId);
+
+  const handleFileChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const files = Array.from(event.currentTarget.files ?? []);
+
+      event.currentTarget.value = '';
+
+      if (files.length > 0) {
+        void actions.uploadFiles(files);
+      }
+    },
+    [actions]
+  );
+
+  const handleUploadClick = useCallback(() => fileInputRef.current?.click(), []);
+
+  return (
+    <>
+      <input
+        accept={ACCEPTED_UPLOAD_EXTENSIONS}
+        multiple
+        ref={fileInputRef}
+        style={UPLOAD_INPUT_STYLE}
+        type="file"
+        onChange={handleFileChange}
+      />
+      <IconButton
+        aria-label={
+          isVirtualTarget
+            ? t('widgets.gallery.uploadsUnavailableForDateBoards')
+            : t('widgets.gallery.uploadImagesToBoard', {
+                name: selectedBoard?.name ?? t('widgets.gallery.selectedBoardFallback'),
+              })
+        }
+        disabled={isVirtualTarget}
+        size="xs"
+        variant="outline"
+        onClick={handleUploadClick}
+      >
+        <UploadIcon />
+      </IconButton>
+    </>
+  );
+};
+
+const GallerySettingsMenu = () => {
+  const { t } = useTranslation();
+  const { actions, gallery } = useGalleryWidget();
+  const { imageDensityPercent, imageOrderDir, paginationMode, showImageDimensions, starredFirst, thumbnailFit } =
+    gallery.settings;
+  const handleDensityKeyDown = useCallback((event: React.KeyboardEvent) => event.stopPropagation(), []);
+  const handleDensityChange = useCallback(
+    (event: { value: number[] }) =>
+      actions.updateSettings({ imageDensityPercent: event.value[0] ?? imageDensityPercent }),
+    [actions, imageDensityPercent]
+  );
+  const handleSquareFit = useCallback(() => actions.updateSettings({ thumbnailFit: 'square' }), [actions]);
+  const handleAspectFit = useCallback(() => actions.updateSettings({ thumbnailFit: 'aspect' }), [actions]);
+  const handleShowDimensionsChange = useCallback(
+    (showImageDimensions: boolean) => actions.updateSettings({ showImageDimensions }),
+    [actions]
+  );
+  const handleNewestFirst = useCallback(() => actions.updateSettings({ imageOrderDir: 'DESC' }), [actions]);
+  const handleOldestFirst = useCallback(() => actions.updateSettings({ imageOrderDir: 'ASC' }), [actions]);
+  const handleStarredFirstChange = useCallback(
+    (starredFirst: boolean) => actions.updateSettings({ starredFirst }),
+    [actions]
+  );
+  const handleInfinitePagination = useCallback(() => actions.updateSettings({ paginationMode: 'infinite' }), [actions]);
+  const handlePaginatedPagination = useCallback(
+    () => actions.updateSettings({ paginationMode: 'paginated' }),
+    [actions]
+  );
+  const densityAriaLabel = useMemo(() => [t('widgets.gallery.imageDensity')], [t]);
+  const densityValue = useMemo(() => [imageDensityPercent], [imageDensityPercent]);
+
+  return (
+    <Menu.Root positioning={GALLERY_SETTINGS_POSITIONING}>
+      <Menu.Trigger asChild>
+        <IconButton aria-label={t('widgets.gallery.settings')} size="xs" variant="outline">
+          <SettingsIcon />
+        </IconButton>
+      </Menu.Trigger>
+      <Portal>
+        <Menu.Positioner>
+          <Menu.Content minW="14rem" p="3">
+            <Stack gap="3">
+              <Stack gap="2">
+                <HStack justify="space-between">
+                  <SettingLabel>{t('widgets.gallery.settingsGridDensity')}</SettingLabel>
+                  <Text color="fg.subtle" fontSize="2xs">
+                    {imageDensityPercent}%
+                  </Text>
+                </HStack>
+                <Slider.Root
+                  aria-label={densityAriaLabel}
+                  max={100}
+                  min={0}
+                  step={1}
+                  value={densityValue}
+                  onKeyDown={handleDensityKeyDown}
+                  onValueChange={handleDensityChange}
+                >
+                  <Slider.Control>
+                    <Slider.Track>
+                      <Slider.Range />
+                    </Slider.Track>
+                    <Slider.Thumbs />
+                  </Slider.Control>
+                </Slider.Root>
+              </Stack>
+              <Stack gap="2">
+                <SettingLabel>{t('widgets.gallery.settingsThumbnails')}</SettingLabel>
+                <HStack gap="1">
+                  <Button
+                    flex="1"
+                    size="2xs"
+                    variant={thumbnailFit === 'square' ? 'solid' : 'outline'}
+                    onClick={handleSquareFit}
+                  >
+                    {t('widgets.gallery.thumbnailFitSquare')}
+                  </Button>
+                  <Button
+                    flex="1"
+                    size="2xs"
+                    variant={thumbnailFit === 'aspect' ? 'solid' : 'outline'}
+                    onClick={handleAspectFit}
+                  >
+                    {t('widgets.gallery.thumbnailFitAspect')}
+                  </Button>
+                </HStack>
+                <SettingSwitch
+                  checked={showImageDimensions}
+                  label={t('widgets.gallery.alwaysShowDimensions')}
+                  onChange={handleShowDimensionsChange}
+                />
+              </Stack>
+              <Stack gap="2">
+                <SettingLabel>{t('widgets.gallery.imageSort')}</SettingLabel>
+                <HStack gap="1">
+                  <Button
+                    flex="1"
+                    size="2xs"
+                    variant={imageOrderDir === 'DESC' ? 'solid' : 'outline'}
+                    onClick={handleNewestFirst}
+                  >
+                    {t('widgets.gallery.newest')}
+                  </Button>
+                  <Button
+                    flex="1"
+                    size="2xs"
+                    variant={imageOrderDir === 'ASC' ? 'solid' : 'outline'}
+                    onClick={handleOldestFirst}
+                  >
+                    {t('widgets.gallery.oldest')}
+                  </Button>
+                </HStack>
+                <SettingSwitch
+                  checked={starredFirst}
+                  label={t('widgets.gallery.showStarredImagesFirst')}
+                  onChange={handleStarredFirstChange}
+                />
+              </Stack>
+              <Stack gap="2">
+                <SettingLabel>{t('widgets.gallery.pagination')}</SettingLabel>
+                <HStack gap="1">
+                  <Button
+                    flex="1"
+                    size="2xs"
+                    variant={paginationMode === 'infinite' ? 'solid' : 'outline'}
+                    onClick={handleInfinitePagination}
+                  >
+                    {t('widgets.gallery.infinite')}
+                  </Button>
+                  <Button
+                    flex="1"
+                    size="2xs"
+                    variant={paginationMode === 'paginated' ? 'solid' : 'outline'}
+                    onClick={handlePaginatedPagination}
+                  >
+                    {t('common.pages')}
+                  </Button>
+                </HStack>
+              </Stack>
+            </Stack>
+          </Menu.Content>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
+
+const SettingSwitch = ({
+  checked,
+  label,
+  onChange,
+}: {
+  checked: boolean;
+  label: string;
+  onChange: (checked: boolean) => void;
+}) => {
+  const handleCheckedChange = useCallback((event: { checked: boolean }) => onChange(event.checked), [onChange]);
+
+  return (
+    <Switch.Root checked={checked} size="sm" onCheckedChange={handleCheckedChange}>
+      <Switch.HiddenInput />
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Switch.Label fontSize="2xs">{label}</Switch.Label>
+    </Switch.Root>
+  );
+};
+
+const SettingLabel = ({ children }: { children: string }) => (
+  <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+    {children}
+  </Text>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetContext.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetContext.tsx
new file mode 100644
index 00000000000..9451c0c0980
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetContext.tsx
@@ -0,0 +1,53 @@
+import type { GalleryImage, GalleryView } from '@workbench/gallery/api';
+import type { GallerySettings } from '@workbench/gallery/settings';
+import type { ImageActions } from '@workbench/image-actions';
+import type { WidgetRuntimeApi } from '@workbench/types';
+
+import { createContext, use } from 'react';
+
+import type { GalleryStateView } from './galleryStateView';
+
+/**
+ * Gallery-widget intents. The provider (GalleryWidgetView) is the only place
+ * that knows whether an intent maps to a workbench dispatch, a backend call,
+ * or both. Image-level operations (star, delete, move, ...) live in the shared
+ * ImageActions contract instead so other widgets reuse them.
+ */
+export interface GalleryActions {
+  archiveBoard: (boardId: string, archived: boolean) => Promise<void>;
+  createBoard: (boardName: string) => Promise<void>;
+  deleteBoard: (boardId: string, includeImages: boolean) => Promise<void>;
+  downloadBoard: (boardId: string) => Promise<void>;
+  loadMore: () => void;
+  refresh: () => void;
+  renameBoard: (boardId: string, boardName: string) => Promise<void>;
+  selectBoard: (boardId: string) => void;
+  selectImage: (image: GalleryImage) => void;
+  selectImageRange: (imageNames: string[], primaryImage: GalleryImage) => void;
+  selectProjectBoard: () => Promise<void>;
+  setSearchTerm: (searchTerm: string) => void;
+  setView: (galleryView: GalleryView) => void;
+  toggleImageInSelection: (image: GalleryImage) => void;
+  updateSettings: (settings: Partial<GallerySettings>) => void;
+  uploadFiles: (files: File[]) => Promise<void>;
+}
+
+export interface GalleryWidgetContextValue {
+  gallery: GalleryStateView;
+  actions: GalleryActions;
+  imageActions: ImageActions;
+  projectName: string;
+  runtime: WidgetRuntimeApi;
+}
+
+export const GalleryWidgetContext = createContext<GalleryWidgetContextValue | null>(null);
+
+export const useGalleryWidget = (): GalleryWidgetContextValue => {
+  const value = use(GalleryWidgetContext);
+
+  if (!value) {
+    throw new Error('useGalleryWidget must be used within the gallery widget.');
+  }
+
+  return value;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetFooter.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetFooter.tsx
new file mode 100644
index 00000000000..6f00d4bf65d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetFooter.tsx
@@ -0,0 +1,71 @@
+import type { WidgetViewProps } from '@workbench/types';
+
+import { ButtonGroup, HStack, Pagination } from '@chakra-ui/react';
+import { IconButton } from '@workbench/components/ui';
+import { getGallerySettings } from '@workbench/gallery/settings';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { getGalleryPage, getGalleryTotalImages } from './galleryStateView';
+import { GALLERY_PAGE_SIZE } from './useGalleryData';
+
+const PAGINATION_ITEM_VARIANT = { _selected: 'outline', base: 'ghost' } as const;
+
+/**
+ * Widget-chrome footer: page navigation for the gallery's paginated mode.
+ * Reads everything from the gallery widget's persisted values so it stays
+ * decoupled from the view's data fetching.
+ */
+export const GalleryWidgetFooter = (_props: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const galleryValues = useActiveProjectSelector((project) => getProjectWidgetValues(project, 'gallery'));
+  const dispatch = useWorkbenchDispatch();
+  const settings = getGallerySettings(galleryValues);
+  const page = getGalleryPage(galleryValues);
+  const totalImages = getGalleryTotalImages(galleryValues);
+  const handlePageChange = useCallback(
+    (event: { page: number }) => dispatch({ page: event.page - 1, type: 'setGalleryPage' }),
+    [dispatch]
+  );
+  const renderPaginationItem = useCallback(
+    (paginationPage: { value: number }) => (
+      <IconButton aria-label={t('common.pageNumber', { page: paginationPage.value })} variant={PAGINATION_ITEM_VARIANT}>
+        {paginationPage.value}
+      </IconButton>
+    ),
+    [t]
+  );
+
+  if (settings.paginationMode !== 'paginated' || totalImages === null || totalImages <= GALLERY_PAGE_SIZE) {
+    return null;
+  }
+
+  return (
+    <HStack justify="center" py="1" w="full">
+      <Pagination.Root
+        count={totalImages}
+        page={page + 1}
+        pageSize={GALLERY_PAGE_SIZE}
+        siblingCount={1}
+        onPageChange={handlePageChange}
+      >
+        <ButtonGroup gap="1" size="2xs" variant="ghost">
+          <Pagination.PrevTrigger asChild>
+            <IconButton aria-label={t('common.previousPage')}>
+              <ChevronLeftIcon />
+            </IconButton>
+          </Pagination.PrevTrigger>
+          <Pagination.Items render={renderPaginationItem} />
+          <Pagination.NextTrigger asChild>
+            <IconButton aria-label={t('common.nextPage')}>
+              <ChevronRightIcon />
+            </IconButton>
+          </Pagination.NextTrigger>
+        </ButtonGroup>
+      </Pagination.Root>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetView.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetView.test.ts
new file mode 100644
index 00000000000..bce1cf1c025
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetView.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { shouldPublishGalleryTotal } from './GalleryWidgetView';
+
+describe('shouldPublishGalleryTotal', () => {
+  it('publishes finite totals that differ from known state and have not already been published', () => {
+    expect(shouldPublishGalleryTotal({ knownTotalImages: null, lastPublishedTotal: null, total: 12 })).toBe(true);
+    expect(shouldPublishGalleryTotal({ knownTotalImages: 8, lastPublishedTotal: null, total: 12 })).toBe(true);
+  });
+
+  it('does not republish the same in-flight total while known state catches up', () => {
+    expect(shouldPublishGalleryTotal({ knownTotalImages: null, lastPublishedTotal: 12, total: 12 })).toBe(false);
+  });
+
+  it('does not publish non-finite or already-known totals', () => {
+    expect(shouldPublishGalleryTotal({ knownTotalImages: 12, lastPublishedTotal: null, total: 12 })).toBe(false);
+    expect(shouldPublishGalleryTotal({ knownTotalImages: null, lastPublishedTotal: null, total: null })).toBe(false);
+    expect(shouldPublishGalleryTotal({ knownTotalImages: null, lastPublishedTotal: null, total: Number.NaN })).toBe(
+      false
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetView.tsx
new file mode 100644
index 00000000000..e60ae0af49c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/GalleryWidgetView.tsx
@@ -0,0 +1,281 @@
+/* eslint-disable react/react-compiler */
+import type { GeneratedImageContract, WidgetViewProps } from '@workbench/types';
+
+import { getGallerySettings, type GallerySettings } from '@workbench/gallery/settings';
+import { useImageActions } from '@workbench/image-actions';
+import { StatusWidgetChip } from '@workbench/widget-frame';
+import { createGenerateFormValuesSelector } from '@workbench/widgets/generate/generateFormViewModel';
+import {
+  useActiveProjectId,
+  useActiveProjectName,
+  useActiveProjectSelector,
+  useWidgetValuesSelector,
+  useWorkbenchDispatch,
+} from '@workbench/WorkbenchContext';
+import { areArraysEqual, createStableSelector } from '@workbench/workbenchSelectors';
+import { ImageIcon } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { GalleryPanelContent } from './GalleryPanelContent';
+import {
+  getGalleryCompareImage,
+  getGalleryPage,
+  getGalleryProjectBoardId,
+  getGalleryImagesRefreshToken,
+  getGalleryRecentImagesKey,
+  getGalleryRefreshToken,
+  getGallerySearchTerm,
+  getGallerySelectedBoardId,
+  getGallerySelectedImageNames,
+  getGalleryStateView,
+  getGalleryTotalImages,
+  getGalleryView,
+} from './galleryStateView';
+import { GalleryWidgetContext, type GalleryWidgetContextValue } from './GalleryWidgetContext';
+import { useGalleryActions } from './useGalleryActions';
+import { GALLERY_PAGE_SIZE, useGalleryData } from './useGalleryData';
+
+interface GalleryWidgetSelectedValues extends Record<string, unknown>, GallerySettings {
+  compareImage: GeneratedImageContract | null;
+  galleryImagesRefreshToken: string;
+  galleryPage: number;
+  galleryRefreshToken: string;
+  galleryTotalImages: number | null;
+  galleryView: ReturnType<typeof getGalleryView>;
+  projectBoardId: string | null;
+  recentImages: GeneratedImageContract[] | undefined;
+  searchTerm: string;
+  selectedBoardId: string;
+  selectedImageName: string | null;
+  selectedImageNames: string[];
+}
+
+const areGallerySettingsEqual = (left: GallerySettings, right: GallerySettings): boolean =>
+  left.boardOrderBy === right.boardOrderBy &&
+  left.boardOrderDir === right.boardOrderDir &&
+  left.imageDensityPercent === right.imageDensityPercent &&
+  left.imageOrderDir === right.imageOrderDir &&
+  left.paginationMode === right.paginationMode &&
+  left.showArchivedBoards === right.showArchivedBoards &&
+  left.showDateBoards === right.showDateBoards &&
+  left.showImageDimensions === right.showImageDimensions &&
+  left.starredFirst === right.starredFirst &&
+  left.thumbnailFit === right.thumbnailFit;
+
+const areGalleryWidgetSelectedValuesEqual = (
+  left: GalleryWidgetSelectedValues,
+  right: GalleryWidgetSelectedValues
+): boolean =>
+  left.compareImage === right.compareImage &&
+  left.galleryImagesRefreshToken === right.galleryImagesRefreshToken &&
+  left.galleryPage === right.galleryPage &&
+  left.galleryRefreshToken === right.galleryRefreshToken &&
+  left.galleryTotalImages === right.galleryTotalImages &&
+  left.galleryView === right.galleryView &&
+  left.projectBoardId === right.projectBoardId &&
+  left.recentImages === right.recentImages &&
+  left.searchTerm === right.searchTerm &&
+  left.selectedBoardId === right.selectedBoardId &&
+  left.selectedImageName === right.selectedImageName &&
+  areArraysEqual(left.selectedImageNames, right.selectedImageNames) &&
+  areGallerySettingsEqual(left, right);
+
+const selectGalleryWidgetValues = createStableSelector(
+  (values: Record<string, unknown>): GalleryWidgetSelectedValues => {
+    const settings = getGallerySettings(values);
+
+    return {
+      ...settings,
+      compareImage: getGalleryCompareImage(values),
+      galleryImagesRefreshToken: getGalleryImagesRefreshToken(values),
+      galleryPage: getGalleryPage(values),
+      galleryRefreshToken: getGalleryRefreshToken(values),
+      galleryTotalImages: getGalleryTotalImages(values),
+      galleryView: getGalleryView(values),
+      projectBoardId: getGalleryProjectBoardId(values),
+      recentImages: Array.isArray(values.recentImages) ? (values.recentImages as GeneratedImageContract[]) : undefined,
+      searchTerm: getGallerySearchTerm(values),
+      selectedBoardId: getGallerySelectedBoardId(values, []),
+      selectedImageName: typeof values.selectedImageName === 'string' ? values.selectedImageName : null,
+      selectedImageNames: getGallerySelectedImageNames(values),
+    };
+  },
+  areGalleryWidgetSelectedValuesEqual
+);
+
+const selectGenerateRecallValues = createGenerateFormValuesSelector();
+
+export const shouldPublishGalleryTotal = ({
+  knownTotalImages,
+  lastPublishedTotal,
+  total,
+}: {
+  knownTotalImages: number | null;
+  lastPublishedTotal: number | null;
+  total: number | null;
+}): boolean =>
+  typeof total === 'number' && Number.isFinite(total) && total !== knownTotalImages && total !== lastPublishedTotal;
+
+export const GalleryWidgetView = ({ presentation, region, runtime }: WidgetViewProps) => {
+  const dispatch = useWorkbenchDispatch();
+  const projectId = useActiveProjectId();
+  const galleryValues = useWidgetValuesSelector('gallery', selectGalleryWidgetValues);
+  const generateValues = useWidgetValuesSelector('generate', selectGenerateRecallValues);
+  const projectName = useActiveProjectName();
+  const queueItems = useActiveProjectSelector((project) => project.queue.items);
+  const galleryView = getGalleryView(galleryValues);
+  const searchTerm = getGallerySearchTerm(galleryValues);
+  const recentImagesKey = getGalleryRecentImagesKey(galleryValues);
+  const refreshToken = getGalleryRefreshToken(galleryValues);
+  const imageRefreshToken = getGalleryImagesRefreshToken(galleryValues);
+  const page = getGalleryPage(galleryValues);
+  const knownTotalImages = getGalleryTotalImages(galleryValues);
+  const settings = getGallerySettings(galleryValues);
+  const onError = useCallback(
+    (message: string) =>
+      dispatch({ area: 'gallery-data', message, namespace: 'gallery', projectId, type: 'recordError' }),
+    [dispatch, projectId]
+  );
+
+  const data = useGalleryData({
+    galleryView,
+    imageRefreshToken,
+    onError,
+    page,
+    recentImagesKey,
+    refreshToken,
+    searchTerm,
+    selectedBoardId: getGallerySelectedBoardId(galleryValues, []),
+    settings,
+  });
+
+  const { loadMore, patchImages, total } = data;
+  const selectedBoardId = getGallerySelectedBoardId(galleryValues, data.boards);
+  const gallery = getGalleryStateView(galleryValues, data.boards, data.images, data.isLoadingImages, queueItems);
+
+  const onStarredChange = useCallback(
+    (imageNames: string[], starred: boolean) => {
+      patchImages((images) =>
+        images.map((image) => (imageNames.includes(image.imageName) ? { ...image, starred } : image))
+      );
+    },
+    [patchImages]
+  );
+
+  const galleryImagesRef = useRef(gallery.images);
+  const selectedImageNameRef = useRef(gallery.selectedImageName);
+  const lastPublishedTotalRef = useRef<number | null>(null);
+  const knownTotalImagesRef = useRef(knownTotalImages);
+
+  galleryImagesRef.current = gallery.images;
+  selectedImageNameRef.current = gallery.selectedImageName;
+  knownTotalImagesRef.current = knownTotalImages;
+
+  // After a deletion that takes out the previewed image, move the selection to
+  // the image that now occupies the old index, else the one before it.
+  const onImagesDeleted = useCallback(
+    (imageNames: string[]) => {
+      const deletedNames = new Set(imageNames);
+      const images = galleryImagesRef.current;
+      const anchorName = selectedImageNameRef.current;
+
+      if (!anchorName || !deletedNames.has(anchorName)) {
+        return;
+      }
+
+      const anchorIndex = images.findIndex((image) => image.imageName === anchorName);
+
+      if (anchorIndex === -1) {
+        return;
+      }
+
+      const remaining = images.filter((image) => !deletedNames.has(image.imageName));
+      const remainingBeforeAnchor = images
+        .slice(0, anchorIndex)
+        .filter((image) => !deletedNames.has(image.imageName)).length;
+      const nextImage = remaining[remainingBeforeAnchor] ?? remaining[remainingBeforeAnchor - 1] ?? null;
+
+      if (nextImage) {
+        dispatch({ image: nextImage, type: 'selectGalleryImage' });
+      }
+    },
+    [dispatch]
+  );
+
+  const imageActions = useImageActions({
+    boards: data.boards,
+    dispatch,
+    generateValues,
+    onImagesDeleted,
+    onStarredChange,
+    projectId,
+  });
+
+  const actions = useGalleryActions({
+    boards: data.boards,
+    dispatch,
+    loadMore,
+    projectBoardId: getGalleryProjectBoardId(galleryValues),
+    projectName,
+    selectedBoardId,
+  });
+
+  const contextValue = useMemo<GalleryWidgetContextValue>(
+    () => ({ actions, gallery, imageActions, projectName, runtime }),
+    [actions, gallery, imageActions, projectName, runtime]
+  );
+
+  const isWidePlacement = region === 'center' || (region === 'bottom' && presentation === 'expanded');
+
+  // Publish the backend total into widget values so the manifest footer can
+  // render page navigation without its own fetch, and clamp the page when the
+  // query shrinks (e.g. after deletions).
+  //
+  // The effect reacts only to this instance's fetched `total` — the published
+  // state (`knownTotalImages`) is read through a ref on purpose. Several
+  // gallery views can be mounted at once (e.g. the bottom status chip plus an
+  // expanded gallery), and if each instance re-published whenever the shared
+  // state disagreed with its own in-flight total, two instances mid-refetch
+  // would dispatch in a loop until React aborts with "maximum update depth".
+  useEffect(() => {
+    if (typeof total !== 'number' || !Number.isFinite(total)) {
+      return;
+    }
+
+    const lastPublishedTotal = lastPublishedTotalRef.current;
+
+    lastPublishedTotalRef.current = total;
+
+    if (
+      shouldPublishGalleryTotal({
+        knownTotalImages: knownTotalImagesRef.current,
+        lastPublishedTotal,
+        total,
+      })
+    ) {
+      dispatch({ totalImages: total, type: 'setGalleryPageInfo' });
+    }
+  }, [dispatch, total]);
+
+  useEffect(() => {
+    if (settings.paginationMode !== 'paginated' || total === null) {
+      return;
+    }
+
+    const maxPage = Math.max(0, Math.ceil(total / GALLERY_PAGE_SIZE) - 1);
+
+    if (page > maxPage) {
+      dispatch({ page: maxPage, type: 'setGalleryPage' });
+    }
+  }, [dispatch, page, settings.paginationMode, total]);
+
+  if (region === 'bottom' && presentation !== 'expanded') {
+    return <StatusWidgetChip icon={ImageIcon}>Gallery: {total ?? gallery.images.length}</StatusWidgetChip>;
+  }
+
+  return (
+    <GalleryWidgetContext value={contextValue}>
+      <GalleryPanelContent layout={isWidePlacement ? 'wide' : 'stacked'} />
+    </GalleryWidgetContext>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryDnd.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryDnd.test.ts
new file mode 100644
index 00000000000..b9bb1f188c9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryDnd.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  getGalleryBoardDropData,
+  getGalleryImageDragData,
+  getGalleryImageNamesOutsideBoard,
+  isGalleryBoardDropData,
+  isGalleryImageDragData,
+} from './galleryDnd';
+
+describe('galleryDnd', () => {
+  it('keeps only images outside the target board', () => {
+    const dragData = getGalleryImageDragData([
+      { boardId: 'board-a', imageName: 'own.png' },
+      { boardId: 'board-b', imageName: 'other.png' },
+      { boardId: 'none', imageName: 'uncategorized.png' },
+    ]);
+
+    expect(getGalleryImageNamesOutsideBoard(dragData, 'board-a')).toEqual(['other.png', 'uncategorized.png']);
+  });
+
+  it('recognizes gallery image drag data', () => {
+    expect(isGalleryImageDragData(getGalleryImageDragData([{ boardId: 'none', imageName: 'image.png' }]))).toBe(true);
+    expect(isGalleryImageDragData({ images: [{ boardId: 'none' }], kind: 'gallery-image' })).toBe(false);
+  });
+
+  it('recognizes gallery board drop data', () => {
+    expect(isGalleryBoardDropData(getGalleryBoardDropData('board-a', 'board'))).toBe(true);
+    expect(isGalleryBoardDropData({ boardId: 'board-a', boardKind: 'generated', kind: 'gallery-board' })).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryDnd.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryDnd.ts
new file mode 100644
index 00000000000..9db90b86a4e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryDnd.ts
@@ -0,0 +1,54 @@
+import type { GalleryBoardKind } from '@workbench/gallery/api';
+
+export interface GalleryImageDragImage {
+  boardId: string;
+  imageName: string;
+}
+
+export interface GalleryImageDragData {
+  kind: 'gallery-image';
+  images: GalleryImageDragImage[];
+}
+
+export interface GalleryBoardDropData {
+  boardId: string;
+  boardKind: GalleryBoardKind;
+  kind: 'gallery-board';
+}
+
+export const getGalleryImageDragId = (imageName: string): string => `gallery-image:${imageName}`;
+
+export const getGalleryBoardDropId = (boardId: string): string => `gallery-board:${boardId}`;
+
+export const getGalleryImageDragData = (images: GalleryImageDragImage[]): GalleryImageDragData => ({
+  images,
+  kind: 'gallery-image',
+});
+
+export const getGalleryBoardDropData = (boardId: string, boardKind: GalleryBoardKind): GalleryBoardDropData => ({
+  boardId,
+  boardKind,
+  kind: 'gallery-board',
+});
+
+export const isGalleryImageDragData = (value: unknown): value is GalleryImageDragData =>
+  isRecord(value) &&
+  value.kind === 'gallery-image' &&
+  Array.isArray(value.images) &&
+  value.images.every(
+    (image) => isRecord(image) && typeof image.imageName === 'string' && typeof image.boardId === 'string'
+  );
+
+export const isGalleryBoardDropData = (value: unknown): value is GalleryBoardDropData =>
+  isRecord(value) &&
+  value.kind === 'gallery-board' &&
+  typeof value.boardId === 'string' &&
+  isGalleryBoardKind(value.boardKind);
+
+export const getGalleryImageNamesOutsideBoard = (dragData: GalleryImageDragData, boardId: string): string[] =>
+  dragData.images.filter((image) => image.boardId !== boardId).map((image) => image.imageName);
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+const isGalleryBoardKind = (value: unknown): value is GalleryBoardKind =>
+  value === 'board' || value === 'date' || value === 'uncategorized';
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryStateView.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryStateView.test.ts
new file mode 100644
index 00000000000..c5f6c74fee5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryStateView.test.ts
@@ -0,0 +1,219 @@
+import type { GalleryBoard } from '@workbench/gallery/api';
+import type { GeneratedImageContract, QueueItem, QueueItemStatus } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getBoardCounts,
+  getGalleryImagesRefreshToken,
+  getGalleryQueuePlaceholders,
+  getGallerySelectedBoardId,
+  getGalleryStateView,
+} from './galleryStateView';
+
+const boards: GalleryBoard[] = [
+  { archived: false, assetCount: 0, id: 'none', imageCount: 1, kind: 'uncategorized', name: 'Uncategorized' },
+  { archived: false, assetCount: 0, id: 'board-1', imageCount: 2, kind: 'board', name: 'Board 1' },
+];
+
+const createImage = (imageName: string): GeneratedImageContract => ({
+  height: 768,
+  imageName,
+  imageUrl: `/api/v1/images/i/${imageName}/full`,
+  queuedAt: '2026-06-09T00:00:00.000Z',
+  sourceQueueItemId: 'queue-item-1',
+  thumbnailUrl: `/api/v1/images/i/${imageName}/thumbnail`,
+  width: 512,
+});
+
+const createQueueItem = ({
+  backendItemIds,
+  batchCount = 1,
+  boardId = 'none',
+  completedBackendItemIds,
+  cancelledBackendItemIds,
+  destination = 'gallery',
+  status = 'pending',
+}: {
+  backendItemIds?: number[];
+  batchCount?: number;
+  boardId?: string;
+  completedBackendItemIds?: number[];
+  cancelledBackendItemIds?: number[];
+  destination?: 'gallery' | 'canvas';
+  status?: QueueItemStatus;
+}): QueueItem =>
+  ({
+    backendItemIds,
+    cancellable: true,
+    cancelledBackendItemIds,
+    completedBackendItemIds,
+    id: `queue-item-${status}-${boardId}`,
+    snapshot: {
+      destination,
+      widgetStates: {
+        gallery: { id: 'gallery', label: 'Gallery', values: { selectedBoardId: boardId }, version: 1 },
+        generate: { id: 'generate', label: 'Generate', values: { batchCount, height: 768, width: 512 }, version: 1 },
+      },
+    },
+    status,
+  }) as unknown as QueueItem;
+
+describe('gallery state view', () => {
+  it('preserves a selected backend board id while boards are still loading', () => {
+    const values = { selectedBoardId: 'board-1' };
+
+    expect(getGallerySelectedBoardId(values, [])).toBe('board-1');
+    expect(getGalleryStateView(values, [], null, false).selectedBoardId).toBe('board-1');
+  });
+
+  it('falls back to uncategorized after loaded boards do not contain the selected board', () => {
+    const values = { selectedBoardId: 'missing-board' };
+
+    expect(getGallerySelectedBoardId(values, boards)).toBe('none');
+    expect(getGalleryStateView(values, boards, [], false).selectedBoardId).toBe('none');
+  });
+
+  it('does not render local fallback images while backend images are loading', () => {
+    const values = { recentImages: [createImage('local-fallback.png')], selectedBoardId: 'none' };
+    const gallery = getGalleryStateView(values, boards, null, true);
+
+    expect(gallery.images).toEqual([]);
+    expect(gallery.isLoading).toBe(true);
+  });
+
+  it('exposes both image and asset counts for board labels', () => {
+    expect(getBoardCounts(boards[1])).toEqual({ assetCount: 0, imageCount: 2 });
+  });
+
+  it('parses persisted gallery settings with safe defaults', () => {
+    const gallery = getGalleryStateView({ boardOrderBy: 'board_name', starredFirst: false }, boards, [], false);
+
+    expect(gallery.settings).toEqual({
+      boardOrderBy: 'board_name',
+      boardOrderDir: 'DESC',
+      imageDensityPercent: 50,
+      imageOrderDir: 'DESC',
+      paginationMode: 'infinite',
+      showArchivedBoards: false,
+      showDateBoards: false,
+      showImageDimensions: false,
+      starredFirst: false,
+      thumbnailFit: 'square',
+    });
+  });
+
+  it('falls back to the full gallery refresh token when image refresh token is absent', () => {
+    expect(getGalleryImagesRefreshToken({ galleryRefreshToken: 'full-refresh' })).toBe('full-refresh');
+    expect(
+      getGalleryImagesRefreshToken({ galleryImagesRefreshToken: 'image-refresh', galleryRefreshToken: 'full-refresh' })
+    ).toBe('image-refresh');
+  });
+
+  it('derives the multi-selection from persisted values with a single-selection fallback', () => {
+    expect(
+      getGalleryStateView({ selectedImageNames: ['a.png', 'b.png', 7] }, boards, [], false).selectedImageNames
+    ).toEqual(['a.png', 'b.png']);
+    expect(getGalleryStateView({ selectedImageName: 'a.png' }, boards, [], false).selectedImageNames).toEqual([
+      'a.png',
+    ]);
+  });
+
+  it('restores the selection set from a visible primary image after tab switches clear it', () => {
+    const image = createImage('selected.png');
+    const gallery = getGalleryStateView(
+      { selectedImageName: image.imageName, selectedImageNames: [] },
+      boards,
+      [{ ...image, boardId: 'none', imageCategory: 'general', starred: false }],
+      false
+    );
+
+    expect(gallery.selectedImageName).toBe(image.imageName);
+    expect(gallery.selectedImageNames).toEqual([image.imageName]);
+  });
+
+  it('creates placeholders for in-flight gallery queue items on the viewed board', () => {
+    const queueItems = [
+      createQueueItem({ batchCount: 2, boardId: 'board-1', status: 'pending' }),
+      createQueueItem({ backendItemIds: [11, 12, 13], boardId: 'board-1', status: 'running' }),
+    ];
+    const placeholders = getGalleryQueuePlaceholders(queueItems, {
+      galleryView: 'images',
+      searchTerm: '',
+      selectedBoardId: 'board-1',
+    });
+
+    expect(placeholders).toHaveLength(5);
+    expect(placeholders[0]).toMatchObject({
+      height: 768,
+      itemIndex: 1,
+      queueItemId: 'queue-item-pending-board-1',
+      width: 512,
+    });
+  });
+
+  it('skips completed backend item slots when creating placeholders', () => {
+    const queueItems = [
+      createQueueItem({
+        backendItemIds: [11, 12, 13],
+        boardId: 'board-1',
+        completedBackendItemIds: [11],
+        status: 'running',
+      }),
+    ];
+
+    const placeholders = getGalleryQueuePlaceholders(queueItems, {
+      galleryView: 'images',
+      searchTerm: '',
+      selectedBoardId: 'board-1',
+    });
+
+    expect(placeholders.map((placeholder) => placeholder.itemIndex)).toEqual([2, 3]);
+  });
+
+  it('skips cancelled backend item slots when creating placeholders', () => {
+    const queueItems = [
+      createQueueItem({
+        backendItemIds: [11, 12, 13],
+        boardId: 'board-1',
+        cancelledBackendItemIds: [12],
+        completedBackendItemIds: [11],
+        status: 'running',
+      }),
+    ];
+
+    const placeholders = getGalleryQueuePlaceholders(queueItems, {
+      galleryView: 'images',
+      searchTerm: '',
+      selectedBoardId: 'board-1',
+    });
+
+    expect(placeholders.map((placeholder) => placeholder.itemIndex)).toEqual([3]);
+  });
+
+  it('does not create placeholders for other boards, finished items, or canvas runs', () => {
+    const queueItems = [
+      createQueueItem({ boardId: 'board-2', status: 'pending' }),
+      createQueueItem({ boardId: 'board-1', status: 'completed' }),
+      createQueueItem({ boardId: 'board-1', destination: 'canvas', status: 'pending' }),
+    ];
+
+    expect(
+      getGalleryQueuePlaceholders(queueItems, { galleryView: 'images', searchTerm: '', selectedBoardId: 'board-1' })
+    ).toEqual([]);
+  });
+
+  it('hides placeholders while searching or browsing assets', () => {
+    const queueItems = [createQueueItem({ boardId: 'none', status: 'pending' })];
+
+    expect(
+      getGalleryQueuePlaceholders(queueItems, { galleryView: 'images', searchTerm: 'cat', selectedBoardId: 'none' })
+    ).toEqual([]);
+    expect(
+      getGalleryQueuePlaceholders(queueItems, { galleryView: 'assets', searchTerm: '', selectedBoardId: 'none' })
+    ).toEqual([]);
+    expect(
+      getGalleryStateView({ selectedBoardId: 'none' }, boards, [], false, queueItems).pendingPlaceholders
+    ).toHaveLength(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryStateView.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryStateView.ts
new file mode 100644
index 00000000000..f5bdb63ac60
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/galleryStateView.ts
@@ -0,0 +1,228 @@
+import type { GalleryBoard, GalleryImage, GalleryView } from '@workbench/gallery/api';
+import type { GeneratedImageContract, QueueItem } from '@workbench/types';
+
+import { getGallerySettings, type GallerySettings } from '@workbench/gallery/settings';
+import { sanitizeBatchCount } from '@workbench/generation/batch';
+
+const UNCATEGORIZED_BOARD: GalleryBoard = {
+  archived: false,
+  assetCount: 0,
+  id: 'none',
+  imageCount: 0,
+  kind: 'uncategorized',
+  name: 'Uncategorized',
+};
+
+/**
+ * A grid cell standing in for an image that an in-flight queue item will
+ * deliver to the currently viewed board once generation completes.
+ */
+export interface GalleryQueuePlaceholder {
+  id: string;
+  queueItemId: string;
+  itemIndex: number;
+  width: number;
+  height: number;
+}
+
+export interface GalleryStateView {
+  boards: GalleryBoard[];
+  compareImageName: string | null;
+  galleryView: GalleryView;
+  images: GalleryImage[];
+  isLoading: boolean;
+  pendingPlaceholders: GalleryQueuePlaceholder[];
+  projectBoardId: string | null;
+  searchTerm: string;
+  selectedBoardId: string;
+  selectedImageName: string | null;
+  selectedImageNames: string[];
+  settings: GallerySettings;
+}
+
+export const getGalleryView = (values: Record<string, unknown>): GalleryView =>
+  values.galleryView === 'assets' ? 'assets' : 'images';
+
+export const getGallerySearchTerm = (values: Record<string, unknown>): string =>
+  typeof values.searchTerm === 'string' ? values.searchTerm : '';
+
+export const getGallerySelectedBoardId = (values: Record<string, unknown>, backendBoards: GalleryBoard[]): string => {
+  const selectedBoardId = typeof values.selectedBoardId === 'string' ? values.selectedBoardId : 'none';
+
+  if (backendBoards.length === 0 || backendBoards.some((board) => board.id === selectedBoardId)) {
+    return selectedBoardId;
+  }
+
+  return 'none';
+};
+
+export const getGallerySelectedImageNames = (values: Record<string, unknown>): string[] => {
+  if (Array.isArray(values.selectedImageNames)) {
+    return (values.selectedImageNames as unknown[]).filter((name): name is string => typeof name === 'string');
+  }
+
+  return typeof values.selectedImageName === 'string' ? [values.selectedImageName] : [];
+};
+
+export const getGalleryPage = (values: Record<string, unknown>): number =>
+  typeof values.galleryPage === 'number' && Number.isFinite(values.galleryPage)
+    ? Math.max(0, Math.floor(values.galleryPage))
+    : 0;
+
+export const getGalleryTotalImages = (values: Record<string, unknown>): number | null =>
+  typeof values.galleryTotalImages === 'number' && Number.isFinite(values.galleryTotalImages)
+    ? Math.max(0, values.galleryTotalImages)
+    : null;
+
+export const getGalleryRefreshToken = (values: Record<string, unknown>): string =>
+  typeof values.galleryRefreshToken === 'string' ? values.galleryRefreshToken : '';
+
+export const getGalleryImagesRefreshToken = (values: Record<string, unknown>): string =>
+  typeof values.galleryImagesRefreshToken === 'string'
+    ? values.galleryImagesRefreshToken
+    : getGalleryRefreshToken(values);
+
+export const getGalleryProjectBoardId = (values: Record<string, unknown>): string | null =>
+  typeof values.projectBoardId === 'string' ? values.projectBoardId : null;
+
+export const getGalleryCompareImage = (values: Record<string, unknown>): GeneratedImageContract | null => {
+  const compareImage = values.compareImage;
+
+  if (
+    compareImage &&
+    typeof compareImage === 'object' &&
+    typeof (compareImage as GeneratedImageContract).imageName === 'string'
+  ) {
+    return compareImage as GeneratedImageContract;
+  }
+
+  return null;
+};
+
+export const getGalleryRecentImagesKey = (values: Record<string, unknown>): string => {
+  if (!Array.isArray(values.recentImages)) {
+    return '';
+  }
+
+  return (values.recentImages as GeneratedImageContract[]).map((image) => image.imageName).join('\0');
+};
+
+const getFiniteNumber = (value: unknown, fallback: number): number =>
+  typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+
+export const getGalleryQueuePlaceholders = (
+  queueItems: QueueItem[],
+  {
+    galleryView,
+    searchTerm,
+    selectedBoardId,
+  }: { galleryView: GalleryView; searchTerm: string; selectedBoardId: string }
+): GalleryQueuePlaceholder[] => {
+  if (galleryView !== 'images' || searchTerm.trim() !== '') {
+    return [];
+  }
+
+  const placeholders: GalleryQueuePlaceholder[] = [];
+
+  for (const item of queueItems) {
+    if (item.status !== 'pending' && item.status !== 'running') {
+      continue;
+    }
+
+    if (item.snapshot.destination !== 'gallery') {
+      continue;
+    }
+
+    const galleryValues = item.snapshot.widgetStates.gallery?.values ?? {};
+    const targetBoardId = typeof galleryValues.selectedBoardId === 'string' ? galleryValues.selectedBoardId : 'none';
+
+    if (targetBoardId !== selectedBoardId) {
+      continue;
+    }
+
+    const generateValues = item.snapshot.widgetStates.generate?.values ?? {};
+    const expectedImageCount = item.backendItemIds?.length
+      ? item.backendItemIds.length
+      : sanitizeBatchCount(generateValues.batchCount);
+    const width = getFiniteNumber(generateValues.width, 1024);
+    const height = getFiniteNumber(generateValues.height, 1024);
+    const completedBackendItemIds = new Set(item.completedBackendItemIds ?? []);
+    const cancelledBackendItemIds = new Set(item.cancelledBackendItemIds ?? []);
+
+    if (item.backendItemIds?.length) {
+      for (let index = 0; index < item.backendItemIds.length; index += 1) {
+        const backendItemId = item.backendItemIds[index];
+
+        if (
+          backendItemId === undefined ||
+          completedBackendItemIds.has(backendItemId) ||
+          cancelledBackendItemIds.has(backendItemId)
+        ) {
+          continue;
+        }
+
+        placeholders.push({ height, id: `${item.id}:${index}`, itemIndex: index + 1, queueItemId: item.id, width });
+      }
+
+      continue;
+    }
+
+    for (let index = 0; index < expectedImageCount; index++) {
+      placeholders.push({ height, id: `${item.id}:${index}`, itemIndex: index + 1, queueItemId: item.id, width });
+    }
+  }
+
+  return placeholders;
+};
+
+export const getGalleryStateView = (
+  values: Record<string, unknown>,
+  backendBoards: GalleryBoard[],
+  backendImages: GalleryImage[] | null,
+  isLoading: boolean,
+  queueItems: QueueItem[] = []
+): GalleryStateView => {
+  const localImages = Array.isArray(values.recentImages)
+    ? (values.recentImages as GeneratedImageContract[]).map((image) => ({
+        ...image,
+        boardId: 'none',
+        imageCategory: 'general' as const,
+        starred: false,
+      }))
+    : [];
+  const images = backendImages ?? (isLoading ? [] : localImages);
+  const selectedImageName = typeof values.selectedImageName === 'string' ? values.selectedImageName : null;
+  const visibleSelectedImageName = images.some((image) => image.imageName === selectedImageName)
+    ? selectedImageName
+    : null;
+  const selectedImageNames = getGallerySelectedImageNames(values);
+  const galleryView = getGalleryView(values);
+  const settings = getGallerySettings(values);
+  const searchTerm = getGallerySearchTerm(values);
+  const boards = backendBoards.length ? backendBoards : [{ ...UNCATEGORIZED_BOARD, imageCount: images.length }];
+  const selectedBoardId = getGallerySelectedBoardId(values, backendBoards);
+  const compareImage = getGalleryCompareImage(values);
+
+  return {
+    boards,
+    compareImageName: compareImage?.imageName ?? null,
+    galleryView,
+    images,
+    isLoading,
+    pendingPlaceholders: getGalleryQueuePlaceholders(queueItems, { galleryView, searchTerm, selectedBoardId }),
+    projectBoardId: getGalleryProjectBoardId(values),
+    searchTerm,
+    selectedBoardId,
+    selectedImageName: visibleSelectedImageName,
+    selectedImageNames:
+      visibleSelectedImageName && !selectedImageNames.includes(visibleSelectedImageName)
+        ? [visibleSelectedImageName, ...selectedImageNames]
+        : selectedImageNames,
+    settings,
+  };
+};
+
+export const getBoardCounts = (board: GalleryBoard): { assetCount: number; imageCount: number } => ({
+  assetCount: board.assetCount,
+  imageCount: board.imageCount,
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/index.ts
new file mode 100644
index 00000000000..da0b1c4de2d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/index.ts
@@ -0,0 +1,20 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { ImageIcon } from 'lucide-react';
+
+import { GalleryWidgetFooter } from './GalleryWidgetFooter';
+import { GalleryWidgetView } from './GalleryWidgetView';
+
+export const galleryWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['left', 'right', 'center', 'bottom'],
+  bottomPanel: 'expandable',
+  chrome: { header: 'hidden' },
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  footer: GalleryWidgetFooter,
+  icon: ImageIcon,
+  id: 'gallery',
+  label: (t) => t('widgets.labels.gallery'),
+  version: 1,
+  view: GalleryWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/useGalleryActions.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/useGalleryActions.ts
new file mode 100644
index 00000000000..3666a778c27
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/useGalleryActions.ts
@@ -0,0 +1,171 @@
+import type { WorkbenchAction } from '@workbench/workbenchState';
+
+import {
+  createGalleryBoard,
+  deleteGalleryBoard,
+  downloadGalleryArchive,
+  updateGalleryBoard,
+  uploadGalleryImage,
+  type GalleryBoard,
+} from '@workbench/gallery/api';
+import { saveBlobToDisk } from '@workbench/image-actions';
+import { useMemo, type Dispatch } from 'react';
+
+import type { GalleryActions } from './GalleryWidgetContext';
+
+const ACCEPTED_UPLOAD_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
+
+const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+export const useGalleryActions = ({
+  boards,
+  dispatch,
+  loadMore,
+  projectBoardId,
+  projectName,
+  selectedBoardId,
+}: {
+  boards: GalleryBoard[];
+  dispatch: Dispatch<WorkbenchAction>;
+  loadMore: () => void;
+  projectBoardId: string | null;
+  projectName: string;
+  selectedBoardId: string;
+}): GalleryActions => {
+  return useMemo<GalleryActions>(() => {
+    const recordError = (error: unknown) =>
+      dispatch({ area: 'gallery-actions', message: toErrorMessage(error), namespace: 'gallery', type: 'recordError' });
+    const recordSuccess = (title: string, message?: string) =>
+      dispatch({ kind: 'success', message, title, type: 'recordNotice' });
+    const refresh = () => dispatch({ type: 'touchGalleryRefresh' });
+    const getBoardName = (boardId: string) => boards.find((board) => board.id === boardId)?.name ?? 'Uncategorized';
+
+    return {
+      archiveBoard: async (boardId, archived) => {
+        try {
+          await updateGalleryBoard(boardId, { archived });
+          recordSuccess(`${archived ? 'Archived' : 'Unarchived'} board "${getBoardName(boardId)}"`);
+
+          if (archived && boardId === selectedBoardId) {
+            dispatch({ boardId: 'none', type: 'selectGalleryBoard' });
+          }
+
+          refresh();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      createBoard: async (boardName) => {
+        try {
+          const board = await createGalleryBoard(boardName);
+
+          dispatch({ boardId: board.id, type: 'selectGalleryBoard' });
+          recordSuccess(`Created board "${board.name}"`);
+          refresh();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      deleteBoard: async (boardId, includeImages) => {
+        try {
+          const boardName = getBoardName(boardId);
+
+          await deleteGalleryBoard(boardId, includeImages);
+          recordSuccess(
+            `Deleted board "${boardName}"`,
+            includeImages ? 'Its images were permanently deleted.' : 'Its images were moved to Uncategorized.'
+          );
+
+          if (boardId === selectedBoardId) {
+            dispatch({ boardId: 'none', type: 'selectGalleryBoard' });
+          }
+
+          refresh();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      downloadBoard: async (boardId) => {
+        try {
+          dispatch({
+            kind: 'info',
+            message: `Preparing an archive of "${getBoardName(boardId)}".`,
+            title: 'Preparing download',
+            type: 'recordNotice',
+          });
+
+          const { blob, fileName } = await downloadGalleryArchive({ boardId });
+
+          saveBlobToDisk(blob, fileName);
+          recordSuccess('Download ready');
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      loadMore,
+      refresh,
+      renameBoard: async (boardId, boardName) => {
+        try {
+          await updateGalleryBoard(boardId, { name: boardName });
+          recordSuccess(`Renamed board to "${boardName}"`);
+          refresh();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      selectBoard: (boardId) => dispatch({ boardId, type: 'selectGalleryBoard' }),
+      selectImage: (image) => dispatch({ image, type: 'selectGalleryImage' }),
+      selectImageRange: (imageNames, primaryImage) =>
+        dispatch({ imageNames, primaryImage, type: 'setGalleryMultiSelection' }),
+      selectProjectBoard: async () => {
+        if (projectBoardId && boards.some((board) => board.id === projectBoardId)) {
+          dispatch({ boardId: projectBoardId, type: 'selectGalleryBoard' });
+          return;
+        }
+
+        if (boards.length === 0) {
+          return;
+        }
+
+        try {
+          const board = await createGalleryBoard(projectName);
+
+          dispatch({ boardId: board.id, type: 'setGalleryProjectBoardId' });
+          dispatch({ boardId: board.id, type: 'selectGalleryBoard' });
+          recordSuccess(`Created project board "${board.name}"`);
+          refresh();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+      setSearchTerm: (searchTerm) => dispatch({ searchTerm, type: 'setGallerySearchTerm' }),
+      setView: (galleryView) => dispatch({ galleryView, type: 'setGalleryView' }),
+      toggleImageInSelection: (image) => dispatch({ image, type: 'toggleGalleryImageInSelection' }),
+      updateSettings: (settings) => dispatch({ settings, type: 'updateGallerySettings' }),
+      uploadFiles: async (files) => {
+        const accepted = files.filter((file) => ACCEPTED_UPLOAD_TYPES.has(file.type));
+
+        if (accepted.length === 0) {
+          dispatch({
+            area: 'gallery-upload',
+            message: 'No supported image files to upload (PNG, JPEG, or WebP).',
+            namespace: 'gallery',
+            type: 'recordError',
+          });
+          return;
+        }
+
+        try {
+          await Promise.all(accepted.map((file) => uploadGalleryImage(file, selectedBoardId)));
+          recordSuccess(
+            `Uploaded ${accepted.length} ${accepted.length === 1 ? 'image' : 'images'}`,
+            `Added to ${getBoardName(selectedBoardId)} as assets.`
+          );
+          refresh();
+        } catch (error: unknown) {
+          recordError(error);
+        }
+      },
+    };
+  }, [boards, dispatch, loadMore, projectBoardId, projectName, selectedBoardId]);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/gallery/useGalleryData.ts b/invokeai/frontend/webv2/src/workbench/widgets/gallery/useGalleryData.ts
new file mode 100644
index 00000000000..9b858ec5008
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/gallery/useGalleryData.ts
@@ -0,0 +1,283 @@
+/* eslint-disable react/react-compiler */
+import type { GallerySettings } from '@workbench/gallery/settings';
+
+import {
+  listGalleryBoards,
+  listGalleryDateBoards,
+  listGalleryImages,
+  type GalleryBoard,
+  type GalleryImage,
+  type GalleryView,
+} from '@workbench/gallery/api';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export const GALLERY_PAGE_SIZE = 60;
+
+const GALLERY_CACHE_TTL_MS = 60_000;
+const GALLERY_BOARDS_CACHE_LIMIT = 8;
+const GALLERY_IMAGES_CACHE_LIMIT = 24;
+const GALLERY_INFINITE_WINDOW_CACHE_LIMIT = 24;
+
+interface CacheEntry<T> {
+  cachedAt: number;
+  value: T;
+}
+
+interface BoardsResult {
+  boards: GalleryBoard[];
+  key: string;
+}
+
+interface BackendImagesResult {
+  /** Query identity without the pagination window — results stay visible while the window changes. */
+  baseKey: string;
+  /** Full identity including the pagination window and refresh token. */
+  fetchKey: string;
+  images: GalleryImage[];
+  total: number;
+}
+
+const boardsCache = new Map<string, CacheEntry<GalleryBoard[]>>();
+const imageResultByFetchKeyCache = new Map<string, CacheEntry<BackendImagesResult>>();
+const imageResultByBaseKeyCache = new Map<string, CacheEntry<BackendImagesResult>>();
+const infiniteWindowCache = new Map<string, number>();
+
+const isCacheEntryFresh = <T>(entry: CacheEntry<T> | undefined): boolean =>
+  entry !== undefined && Date.now() - entry.cachedAt < GALLERY_CACHE_TTL_MS;
+
+const setLimitedMapEntry = <T>(cache: Map<string, T>, key: string, value: T, limit: number): void => {
+  cache.delete(key);
+  cache.set(key, value);
+
+  while (cache.size > limit) {
+    const oldestKey = cache.keys().next().value;
+
+    if (oldestKey === undefined) {
+      return;
+    }
+
+    cache.delete(oldestKey);
+  }
+};
+
+const cacheBoards = (key: string, boards: GalleryBoard[]): void => {
+  setLimitedMapEntry(boardsCache, key, { cachedAt: Date.now(), value: boards }, GALLERY_BOARDS_CACHE_LIMIT);
+};
+
+const cacheImageResult = (result: BackendImagesResult): void => {
+  const entry = { cachedAt: Date.now(), value: result };
+
+  setLimitedMapEntry(imageResultByFetchKeyCache, result.fetchKey, entry, GALLERY_IMAGES_CACHE_LIMIT);
+  setLimitedMapEntry(imageResultByBaseKeyCache, result.baseKey, entry, GALLERY_IMAGES_CACHE_LIMIT);
+};
+
+const getCachedPageCount = (baseKey: string): number => Math.max(1, infiniteWindowCache.get(baseKey) ?? 1);
+
+const cachePageCount = (baseKey: string, pageCount: number): void => {
+  setLimitedMapEntry(infiniteWindowCache, baseKey, Math.max(1, pageCount), GALLERY_INFINITE_WINDOW_CACHE_LIMIT);
+};
+
+export interface GalleryData {
+  boards: GalleryBoard[];
+  /** True while more items exist beyond the loaded infinite-scroll window. */
+  hasMore: boolean;
+  images: GalleryImage[] | null;
+  isLoadingImages: boolean;
+  /** Grow the infinite-scroll window by one page. No-op while fetching, when exhausted, or in paginated mode. */
+  loadMore: () => void;
+  /** Optimistically patch the currently loaded image list (e.g. star toggles). */
+  patchImages: (getImages: (images: GalleryImage[]) => GalleryImage[]) => void;
+  /** Backend total for the current query, or null while unknown. */
+  total: number | null;
+}
+
+export const useGalleryData = ({
+  galleryView,
+  imageRefreshToken,
+  onError,
+  page,
+  recentImagesKey,
+  refreshToken,
+  searchTerm,
+  selectedBoardId,
+  settings,
+}: {
+  galleryView: GalleryView;
+  imageRefreshToken: string;
+  onError: (message: string) => void;
+  page: number;
+  recentImagesKey: string;
+  refreshToken: string;
+  searchTerm: string;
+  selectedBoardId: string;
+  settings: GallerySettings;
+}): GalleryData => {
+  const {
+    boardOrderBy,
+    boardOrderDir,
+    imageOrderDir,
+    paginationMode,
+    showArchivedBoards,
+    showDateBoards,
+    starredFirst,
+  } = settings;
+  const boardsKey = [
+    String(showArchivedBoards),
+    boardOrderBy,
+    boardOrderDir,
+    String(showDateBoards),
+    refreshToken,
+  ].join('\0');
+  const cachedBoardsEntry = boardsCache.get(boardsKey);
+  const isBoardsCacheFresh = isCacheEntryFresh(cachedBoardsEntry);
+  const [boardsResult, setBoardsResult] = useState<BoardsResult | null>(() =>
+    cachedBoardsEntry ? { boards: cachedBoardsEntry.value, key: boardsKey } : null
+  );
+  const boards = boardsResult?.key === boardsKey ? boardsResult.boards : (cachedBoardsEntry?.value ?? []);
+  const boardId =
+    boards.length === 0 || boards.some((board) => board.id === selectedBoardId) ? selectedBoardId : 'none';
+  const baseKey = [galleryView, boardId, searchTerm.trim(), imageOrderDir, String(starredFirst)].join('\0');
+  const cachedPageCount = getCachedPageCount(baseKey);
+  const [infiniteWindow, setInfiniteWindow] = useState<{ baseKey: string; pageCount: number }>(() => ({
+    baseKey,
+    pageCount: cachedPageCount,
+  }));
+  const isPaginated = paginationMode === 'paginated';
+  const pageCount = infiniteWindow.baseKey === baseKey ? infiniteWindow.pageCount : cachedPageCount;
+  const offset = isPaginated ? page * GALLERY_PAGE_SIZE : 0;
+  const limit = isPaginated ? GALLERY_PAGE_SIZE : pageCount * GALLERY_PAGE_SIZE;
+  const fetchKey = [baseKey, String(offset), String(limit), imageRefreshToken, recentImagesKey].join('\0');
+  const exactCachedImageResultEntry = imageResultByFetchKeyCache.get(fetchKey);
+  const baseCachedImageResultEntry = imageResultByBaseKeyCache.get(baseKey);
+  const cachedImageResultEntry = exactCachedImageResultEntry ?? baseCachedImageResultEntry;
+  const isExactImageCacheFresh = isCacheEntryFresh(exactCachedImageResultEntry);
+  const [result, setResult] = useState<BackendImagesResult | null>(() => cachedImageResultEntry?.value ?? null);
+  const [loadingFetchKey, setLoadingFetchKey] = useState<string | null>(null);
+  const stateResult = result !== null && result.baseKey === baseKey ? result : null;
+  const visibleResult = exactCachedImageResultEntry?.value ?? stateResult ?? baseCachedImageResultEntry?.value ?? null;
+  const images = visibleResult !== null && visibleResult.baseKey === baseKey ? visibleResult.images : null;
+  const total = visibleResult !== null && visibleResult.baseKey === baseKey ? visibleResult.total : null;
+  const isLoadingImages = loadingFetchKey === fetchKey || (!isExactImageCacheFresh && result?.fetchKey !== fetchKey);
+  const hasMore = !isPaginated && total !== null && images !== null && images.length < total;
+  const hasMoreRef = useRef(hasMore);
+  const isLoadingRef = useRef(isLoadingImages);
+  const visibleResultRef = useRef(visibleResult);
+
+  hasMoreRef.current = hasMore;
+  isLoadingRef.current = isLoadingImages;
+  visibleResultRef.current = visibleResult;
+
+  useEffect(() => {
+    if (isBoardsCacheFresh) {
+      return;
+    }
+
+    let isStale = false;
+
+    Promise.all([
+      listGalleryBoards({ includeArchived: showArchivedBoards, orderBy: boardOrderBy, orderDir: boardOrderDir }),
+      showDateBoards ? listGalleryDateBoards() : Promise.resolve([]),
+    ])
+      .then(([backendBoards, dateBoards]) => {
+        if (!isStale) {
+          const nextBoards = [...backendBoards, ...dateBoards];
+
+          cacheBoards(boardsKey, nextBoards);
+          setBoardsResult({ boards: nextBoards, key: boardsKey });
+        }
+      })
+      .catch((error: unknown) => {
+        onError(error instanceof Error ? error.message : String(error));
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [boardOrderBy, boardOrderDir, boardsKey, isBoardsCacheFresh, onError, showArchivedBoards, showDateBoards]);
+
+  useEffect(() => {
+    if (isExactImageCacheFresh) {
+      return;
+    }
+
+    let isStale = false;
+
+    setLoadingFetchKey(fetchKey);
+    listGalleryImages({
+      boardId,
+      galleryView,
+      limit,
+      offset,
+      orderDir: imageOrderDir,
+      searchTerm,
+      starredFirst,
+    })
+      .then((backendPage) => {
+        if (!isStale) {
+          const nextResult = { baseKey, fetchKey, images: backendPage.images, total: backendPage.total };
+
+          cacheImageResult(nextResult);
+          setResult(nextResult);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!isStale) {
+          const fallbackResult = visibleResultRef.current?.baseKey === baseKey ? visibleResultRef.current : null;
+
+          setResult(fallbackResult ? { ...fallbackResult, fetchKey } : { baseKey, fetchKey, images: [], total: 0 });
+          onError(error instanceof Error ? error.message : String(error));
+        }
+      })
+      .finally(() => {
+        if (!isStale) {
+          setLoadingFetchKey((currentFetchKey) => (currentFetchKey === fetchKey ? null : currentFetchKey));
+        }
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [
+    baseKey,
+    boardId,
+    fetchKey,
+    galleryView,
+    imageOrderDir,
+    isExactImageCacheFresh,
+    limit,
+    offset,
+    onError,
+    searchTerm,
+    starredFirst,
+  ]);
+
+  const patchImages = useCallback((getImages: (images: GalleryImage[]) => GalleryImage[]) => {
+    const currentResult = visibleResultRef.current;
+
+    if (currentResult === null) {
+      return;
+    }
+
+    const nextResult = { ...currentResult, images: getImages(currentResult.images) };
+
+    cacheImageResult(nextResult);
+    setResult(nextResult);
+  }, []);
+
+  const loadMore = useCallback(() => {
+    if (!hasMoreRef.current || isLoadingRef.current) {
+      return;
+    }
+
+    setInfiniteWindow((currentWindow) => {
+      const nextPageCount =
+        currentWindow.baseKey === baseKey ? currentWindow.pageCount + 1 : getCachedPageCount(baseKey) + 1;
+
+      cachePageCount(baseKey, nextPageCount);
+
+      return { baseKey, pageCount: nextPageCount };
+    });
+  }, [baseKey]);
+
+  return { boards, hasMore, images, isLoadingImages, loadMore, patchImages, total };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateAdvancedFields.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateAdvancedFields.tsx
new file mode 100644
index 00000000000..d8342012468
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateAdvancedFields.tsx
@@ -0,0 +1,227 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type { GenerateModelConfig, GenerateSettings, VaePrecision } from '@workbench/generation/types';
+import type { ChangeEvent } from 'react';
+
+import { Badge, HStack, InputGroup, NativeSelect, NumberInput, Switch } from '@chakra-ui/react';
+import { Field } from '@workbench/components/ui';
+import { getDefaultGenerateSettings, getGenerationUiPolicy } from '@workbench/generation/baseGenerationPolicies';
+import { isVaeModelConfig } from '@workbench/generation/settings';
+import { ModelSelect } from '@workbench/models/components';
+import { useTranslation } from 'react-i18next';
+
+import { GenerateCollapsibleSection } from './shared/GenerateCollapsibleSection';
+import { ModelDefaultButton } from './shared/ModelDefaultButton';
+
+interface GenerateAdvancedFieldsProps {
+  settings: GenerateSettings;
+  selectedModel: GenerateModelConfig | undefined;
+  onCommit: (patch: Partial<GenerateSettings>) => void;
+  onCommitImmediate: (patch: Partial<GenerateSettings>) => void;
+}
+
+const SeamlessSwitch = ({
+  checked,
+  label,
+  onCheckedChange,
+}: {
+  checked: boolean;
+  label: string;
+  onCheckedChange: (checked: boolean) => void;
+}) => (
+  <Switch.Root checked={checked} flex="1" size="sm" onCheckedChange={(event) => onCheckedChange(event.checked)}>
+    <Switch.HiddenInput />
+    <Switch.Control _checked={{ bg: 'accent.solid' }}>
+      <Switch.Thumb />
+    </Switch.Control>
+    <Switch.Label fontSize="xs">{label}</Switch.Label>
+  </Switch.Root>
+);
+
+export const GenerateAdvancedFields = ({
+  onCommit,
+  onCommitImmediate,
+  selectedModel,
+  settings,
+}: GenerateAdvancedFieldsProps) => {
+  const { t } = useTranslation();
+  const modelBase = selectedModel?.base;
+  const modelDefaults = selectedModel ? getDefaultGenerateSettings(selectedModel) : null;
+  const policy = getGenerationUiPolicy(selectedModel, settings);
+  const clipSkipMax = policy.clipSkipMax ?? 0;
+
+  const updateNumber =
+    (key: 'cfgRescaleMultiplier' | 'clipSkip', max: number) =>
+    ({ valueAsNumber }: NumberInput.ValueChangeDetails) => {
+      if (!Number.isFinite(valueAsNumber)) {
+        return;
+      }
+
+      onCommit({ [key]: Math.min(max, Math.max(0, valueAsNumber)) });
+    };
+
+  const customVae = policy.sdVaeVisible && Boolean(settings.vae?.key);
+
+  if (
+    !policy.sdVaeVisible &&
+    !policy.vaePrecisionVisible &&
+    !policy.colorCompensationVisible &&
+    !policy.seamlessVisible &&
+    !policy.clipSkipMax &&
+    !policy.cfgRescaleVisible
+  ) {
+    return null;
+  }
+
+  const badges = (
+    <>
+      {settings.seamlessXAxis && <Badge size="xs">{t('widgets.generate.tileX')}</Badge>}
+      {settings.seamlessYAxis && <Badge size="xs">{t('widgets.generate.tileY')}</Badge>}
+      {settings.colorCompensation && <Badge size="xs">{t('widgets.generate.colorCompensation')}</Badge>}
+      {customVae && (
+        <Badge maxW="32" size="xs" truncate>
+          {settings.vae?.name}
+        </Badge>
+      )}
+    </>
+  );
+
+  return (
+    <GenerateCollapsibleSection label={t('widgets.generate.advanced')} defaultOpen={false} badges={badges}>
+      {policy.sdVaeVisible || policy.vaePrecisionVisible ? (
+        <HStack alignItems="flex-start" gap="2" p="2">
+          {policy.sdVaeVisible ? (
+            <Field
+              flex="2"
+              label={t('widgets.generate.vae')}
+              helpText={settings.vae ? undefined : t('widgets.generate.usingBundledVae')}
+            >
+              <HStack gap="1">
+                <ModelSelect
+                  filter={(model) => model.base === modelBase}
+                  modelTypes={['vae']}
+                  size="xs"
+                  placeholder={t('widgets.generate.modelDefault')}
+                  value={settings.vae?.key ?? null}
+                  onChange={(model) => onCommitImmediate({ vae: isVaeModelConfig(model) ? model : null })}
+                />
+                <ModelDefaultButton
+                  disabled={!settings.vae}
+                  label={t('widgets.generate.useModelDefaultVae')}
+                  onClick={() => onCommitImmediate({ vae: null })}
+                />
+              </HStack>
+            </Field>
+          ) : null}
+          {policy.vaePrecisionVisible ? (
+            <Field flex="1" label={t('widgets.generate.vaePrecision')}>
+              <HStack gap="1">
+                <NativeSelect.Root flex="1" size="xs">
+                  <NativeSelect.Field
+                    aria-label={t('widgets.generate.vaePrecision')}
+                    value={settings.vaePrecision}
+                    onChange={(event: ChangeEvent<HTMLSelectElement>) =>
+                      onCommit({ vaePrecision: event.currentTarget.value as VaePrecision })
+                    }
+                  >
+                    <option value="fp16">FP16</option>
+                    <option value="fp32">FP32</option>
+                  </NativeSelect.Field>
+                  <NativeSelect.Indicator />
+                </NativeSelect.Root>
+                <ModelDefaultButton
+                  disabled={!modelDefaults || settings.vaePrecision === modelDefaults.vaePrecision}
+                  label={t('widgets.generate.useModelDefaultVaePrecision')}
+                  onClick={() => {
+                    if (modelDefaults) {
+                      onCommit({ vaePrecision: modelDefaults.vaePrecision });
+                    }
+                  }}
+                />
+              </HStack>
+            </Field>
+          ) : null}
+        </HStack>
+      ) : null}
+
+      {policy.clipSkipMax || policy.cfgRescaleVisible ? (
+        <HStack gap="2" p="2">
+          {policy.clipSkipMax ? (
+            <Field label={t('widgets.generate.clipSkip')}>
+              <NumberInput.Root
+                max={clipSkipMax}
+                min={0}
+                size="xs"
+                value={String(settings.clipSkip)}
+                onValueChange={updateNumber('clipSkip', clipSkipMax)}
+              >
+                <NumberInput.Control />
+                <NumberInput.Input />
+              </NumberInput.Root>
+            </Field>
+          ) : null}
+          {policy.cfgRescaleVisible ? (
+            <Field label={t('widgets.generate.cfgRescale')}>
+              <NumberInput.Root
+                max={0.99}
+                min={0}
+                size="xs"
+                step={0.05}
+                value={String(settings.cfgRescaleMultiplier)}
+                onValueChange={updateNumber('cfgRescaleMultiplier', 0.99)}
+              >
+                <InputGroup
+                  endElement={
+                    <ModelDefaultButton
+                      disabled={!modelDefaults || settings.cfgRescaleMultiplier === modelDefaults.cfgRescaleMultiplier}
+                      label={t('widgets.generate.useModelDefaultCfgRescale')}
+                      onClick={() => {
+                        if (modelDefaults) {
+                          onCommit({ cfgRescaleMultiplier: modelDefaults.cfgRescaleMultiplier });
+                        }
+                      }}
+                    />
+                  }
+                  endElementProps={{ pointerEvents: 'auto' }}
+                >
+                  <NumberInput.Input />
+                </InputGroup>
+              </NumberInput.Root>
+            </Field>
+          ) : null}
+        </HStack>
+      ) : null}
+
+      {policy.colorCompensationVisible ? (
+        <Field label={t('widgets.generate.colorCompensation')} p="2">
+          <Switch.Root
+            checked={settings.colorCompensation}
+            size="sm"
+            onCheckedChange={(event) => onCommit({ colorCompensation: event.checked })}
+          >
+            <Switch.HiddenInput />
+            <Switch.Control _checked={{ bg: 'accent.solid' }}>
+              <Switch.Thumb />
+            </Switch.Control>
+          </Switch.Root>
+        </Field>
+      ) : null}
+
+      {policy.seamlessVisible ? (
+        <Field label={t('widgets.generate.seamlessTiling')} p="2">
+          <HStack gap="4">
+            <SeamlessSwitch
+              checked={settings.seamlessXAxis}
+              label={t('widgets.generate.xAxis')}
+              onCheckedChange={(checked) => onCommit({ seamlessXAxis: checked })}
+            />
+            <SeamlessSwitch
+              checked={settings.seamlessYAxis}
+              label={t('widgets.generate.yAxis')}
+              onCheckedChange={(checked) => onCommit({ seamlessYAxis: checked })}
+            />
+          </HStack>
+        </Field>
+      ) : null}
+    </GenerateCollapsibleSection>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateCanvasCompositingSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateCanvasCompositingSection.tsx
new file mode 100644
index 00000000000..fa78578e0c6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateCanvasCompositingSection.tsx
@@ -0,0 +1,202 @@
+/**
+ * Canvas compositing settings for the generate widget.
+ *
+ * Denoising strength USED to live here; it moved to the layers panel's
+ * Photoshop-style header (`widgets/layers/LayersPanelHeader.tsx`). This section
+ * holds the rest of the legacy canvas compositing controls — infill method,
+ * coherence pass mode / edge size / min denoise, and mask blur — persisted
+ * per-project in the canvas widget's own `state.values` (same store as
+ * `denoisingStrength`), read back by `prepareCanvasInvocation` and threaded into
+ * the pure graph compiler. Rendered only when the active invocation source is
+ * the canvas (the generate widget is shared with the Generate tab).
+ */
+
+import type { NumberInput as ChakraNumberInput, SelectValueChangeDetails } from '@chakra-ui/react';
+import type { CanvasCoherenceMode, CanvasInfillMethod } from '@workbench/widgets/canvas/invoke/canvasCompositing';
+
+import { createListCollection, NumberInput, Stack } from '@chakra-ui/react';
+import { Field, Select } from '@workbench/components/ui';
+import {
+  CANVAS_COHERENCE_EDGE_SIZE_MAX,
+  CANVAS_COMPOSITING_KEYS,
+  CANVAS_MASK_BLUR_MAX,
+  readCanvasCompositingSettings,
+} from '@workbench/widgets/canvas/invoke/canvasCompositing';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { GenerateCollapsibleSection } from './shared/GenerateCollapsibleSection';
+
+const INFILL_METHODS: readonly CanvasInfillMethod[] = ['patchmatch', 'lama', 'cv2', 'color', 'tile'];
+const COHERENCE_MODES: readonly CanvasCoherenceMode[] = ['Gaussian Blur', 'Box Blur', 'Staged'];
+
+const SELECT_POSITIONING = { placement: 'bottom-end', sameWidth: false } as const;
+
+export const GenerateCanvasCompositingSection = () => {
+  const sourceId = useActiveProjectSelector((project) => project.invocation.sourceId);
+  if (sourceId !== 'canvas') {
+    return null;
+  }
+  return <CanvasCompositingControls />;
+};
+
+const selectCanvasValues = (project: Parameters<typeof getProjectWidgetValues>[0]): Record<string, unknown> =>
+  getProjectWidgetValues(project, 'canvas');
+
+const CanvasCompositingControls = () => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const values = useActiveProjectSelector(selectCanvasValues);
+  const settings = useMemo(() => readCanvasCompositingSettings(values), [values]);
+
+  const patch = useCallback(
+    (partial: Record<string, unknown>) => {
+      dispatch({ type: 'patchWidgetValues', values: partial, widgetId: 'canvas' });
+    },
+    [dispatch]
+  );
+
+  const infillCollection = useMemo(
+    () =>
+      createListCollection({
+        items: INFILL_METHODS.map((method) => ({
+          label: t(`widgets.generate.compositingOptions.infillMethods.${method}`),
+          value: method,
+        })),
+      }),
+    [t]
+  );
+
+  const coherenceCollection = useMemo(
+    () =>
+      createListCollection({
+        items: COHERENCE_MODES.map((mode) => ({
+          label: t(`widgets.generate.compositingOptions.coherenceModes.${mode}`),
+          value: mode,
+        })),
+      }),
+    [t]
+  );
+
+  const infillValue = useMemo(() => [settings.infillMethod], [settings.infillMethod]);
+  const coherenceValue = useMemo(() => [settings.coherenceMode], [settings.coherenceMode]);
+
+  const handleInfillChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const method = value[0] as CanvasInfillMethod | undefined;
+      if (method) {
+        patch({ [CANVAS_COMPOSITING_KEYS.infillMethod]: method });
+      }
+    },
+    [patch]
+  );
+
+  const handleCoherenceModeChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const mode = value[0] as CanvasCoherenceMode | undefined;
+      if (mode) {
+        patch({ [CANVAS_COMPOSITING_KEYS.coherenceMode]: mode });
+      }
+    },
+    [patch]
+  );
+
+  const handleEdgeSizeChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        patch({ [CANVAS_COMPOSITING_KEYS.coherenceEdgeSize]: valueAsNumber });
+      }
+    },
+    [patch]
+  );
+
+  const handleMinDenoiseChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        patch({ [CANVAS_COMPOSITING_KEYS.coherenceMinDenoise]: valueAsNumber });
+      }
+    },
+    [patch]
+  );
+
+  const handleMaskBlurChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        patch({ [CANVAS_COMPOSITING_KEYS.maskBlur]: valueAsNumber });
+      }
+    },
+    [patch]
+  );
+
+  const opt = (key: string) => t(`widgets.generate.compositingOptions.${key}`);
+
+  return (
+    <GenerateCollapsibleSection label={t('widgets.generate.compositing')}>
+      <Stack gap="2" p="2">
+        <Field label={opt('infillMethod')}>
+          <Select
+            aria-label={opt('infillMethod')}
+            collection={infillCollection}
+            positioning={SELECT_POSITIONING}
+            size="xs"
+            value={infillValue}
+            valueText={opt(`infillMethods.${settings.infillMethod}`)}
+            onValueChange={handleInfillChange}
+          />
+        </Field>
+        <Field label={opt('coherenceMode')}>
+          <Select
+            aria-label={opt('coherenceMode')}
+            collection={coherenceCollection}
+            positioning={SELECT_POSITIONING}
+            size="xs"
+            value={coherenceValue}
+            valueText={opt(`coherenceModes.${settings.coherenceMode}`)}
+            onValueChange={handleCoherenceModeChange}
+          />
+        </Field>
+        <Field label={opt('coherenceEdgeSize')}>
+          <NumberInput.Root
+            max={CANVAS_COHERENCE_EDGE_SIZE_MAX}
+            min={0}
+            size="xs"
+            step={1}
+            value={String(settings.coherenceEdgeSize)}
+            onValueChange={handleEdgeSizeChange}
+          >
+            <NumberInput.Control />
+            <NumberInput.Input aria-label={opt('coherenceEdgeSize')} />
+          </NumberInput.Root>
+        </Field>
+        <Field label={opt('coherenceMinDenoise')}>
+          <NumberInput.Root
+            max={1}
+            min={0}
+            size="xs"
+            step={0.01}
+            value={settings.coherenceMinDenoise.toFixed(2)}
+            onValueChange={handleMinDenoiseChange}
+          >
+            <NumberInput.Control />
+            <NumberInput.Input aria-label={opt('coherenceMinDenoise')} />
+          </NumberInput.Root>
+        </Field>
+        <Field label={opt('maskBlur')}>
+          <NumberInput.Root
+            max={CANVAS_MASK_BLUR_MAX}
+            min={0}
+            size="xs"
+            step={1}
+            value={String(settings.maskBlur)}
+            onValueChange={handleMaskBlurChange}
+          >
+            <NumberInput.Control />
+            <NumberInput.Input aria-label={opt('maskBlur')} />
+          </NumberInput.Root>
+        </Field>
+      </Stack>
+    </GenerateCollapsibleSection>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateComponentsSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateComponentsSection.tsx
new file mode 100644
index 00000000000..78ee742fdd7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateComponentsSection.tsx
@@ -0,0 +1,128 @@
+import type { ComponentModelConfig, GenerateModelConfig, GenerateSettings } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+
+import { Stack } from '@chakra-ui/react';
+import { Field } from '@workbench/components/ui';
+import {
+  getComponentSectionPolicy,
+  type ComponentPolicyContext,
+  type ComponentSlotPolicy,
+} from '@workbench/generation/baseGenerationPolicies';
+import { isMainModelConfig, isModelIdentifierConfig, isVaeModelConfig } from '@workbench/generation/settings';
+import { ModelSelect } from '@workbench/models/components';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { GenerateCollapsibleSection } from './shared/GenerateCollapsibleSection';
+
+interface GenerateComponentsSectionProps {
+  settings: GenerateSettings;
+  selectedModel: GenerateModelConfig | undefined;
+  onCommit: (patch: Partial<GenerateSettings>) => void;
+}
+
+const toComponentModel = (model: ModelConfig | null): ComponentModelConfig | null =>
+  isModelIdentifierConfig(model) ? model : null;
+
+const getComponentPolicyContext = (model: GenerateModelConfig, settings: GenerateSettings): ComponentPolicyContext => ({
+  model,
+  settings,
+  selectedComponents: {
+    clipEmbedModel: settings.clipEmbedModel,
+    clipGEmbedModel: settings.clipGEmbedModel,
+    clipLEmbedModel: settings.clipLEmbedModel,
+    componentSourceModel: settings.componentSourceModel,
+    qwen3EncoderModel: settings.qwen3EncoderModel,
+    qwenVLEncoderModel: settings.qwenVLEncoderModel,
+    t5EncoderModel: settings.t5EncoderModel,
+    vae: settings.vae,
+  },
+});
+
+const ComponentPicker = ({
+  ctx,
+  onChange,
+  slot,
+}: {
+  ctx: ComponentPolicyContext;
+  onChange: (model: ModelConfig | null) => void;
+  slot: ComponentSlotPolicy;
+}) => {
+  const value = ctx.selectedComponents[slot.key];
+  const filter = useCallback((model: ModelConfig) => slot.filter?.(model, ctx) ?? false, [ctx, slot]);
+  const modelTypes = useMemo(() => [...slot.modelTypes], [slot.modelTypes]);
+  const selectedValue = value && (!filter || filter(value as ModelConfig)) ? value.key : null;
+
+  return (
+    <Field label={slot.label} helpText={slot.helpText}>
+      <ModelSelect
+        filter={slot.filter ? filter : undefined}
+        isClearable
+        modelTypes={modelTypes}
+        placeholder={slot.placeholder ?? 'Model default'}
+        size="xs"
+        value={selectedValue}
+        onChange={onChange}
+      />
+    </Field>
+  );
+};
+
+export const GenerateComponentsSection = ({ onCommit, selectedModel, settings }: GenerateComponentsSectionProps) => {
+  const { t } = useTranslation();
+  const ctx = useMemo(
+    () => (selectedModel ? getComponentPolicyContext(selectedModel, settings) : null),
+    [selectedModel, settings]
+  );
+
+  const commitSlotValue = useCallback(
+    (slot: ComponentSlotPolicy, model: ModelConfig | null) => {
+      if (slot.valueKind === 'main') {
+        onCommit({ [slot.key]: isMainModelConfig(model) ? model : null });
+        return;
+      }
+
+      if (slot.valueKind === 'vae') {
+        onCommit({ [slot.key]: isVaeModelConfig(model) ? model : null });
+        return;
+      }
+
+      onCommit({ [slot.key]: toComponentModel(model) });
+    },
+    [onCommit]
+  );
+
+  if (!selectedModel || selectedModel.type === 'external_image_generator') {
+    return null;
+  }
+
+  const policy = getComponentSectionPolicy(selectedModel, settings);
+
+  if (policy.slots.length === 0) {
+    return null;
+  }
+
+  return (
+    <GenerateCollapsibleSection label={t('widgets.generate.components')} defaultOpen={policy.defaultOpen}>
+      <Stack gap="2" p="2">
+        {policy.slots.map((slot) => (
+          <ComponentPickerRow key={slot.key} commitSlotValue={commitSlotValue} ctx={ctx!} slot={slot} />
+        ))}
+      </Stack>
+    </GenerateCollapsibleSection>
+  );
+};
+
+const ComponentPickerRow = ({
+  commitSlotValue,
+  ctx,
+  slot,
+}: {
+  commitSlotValue: (slot: ComponentSlotPolicy, model: ModelConfig | null) => void;
+  ctx: ComponentPolicyContext;
+  slot: ComponentSlotPolicy;
+}) => {
+  const onChange = useCallback((model: ModelConfig | null) => commitSlotValue(slot, model), [commitSlotValue, slot]);
+
+  return <ComponentPicker ctx={ctx} slot={slot} onChange={onChange} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateConceptsSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateConceptsSection.tsx
new file mode 100644
index 00000000000..4ea747a33e9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateConceptsSection.tsx
@@ -0,0 +1,304 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type { GenerateLora, GenerateModelConfig, GenerateSettings, LoraModelConfig } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+
+import { Badge, HStack, InputGroup, NumberInput, Slider, Stack, Switch, Text } from '@chakra-ui/react';
+import { Field, IconButton, Tooltip } from '@workbench/components/ui';
+import {
+  DEFAULT_LORA_WEIGHT_CONFIG,
+  getDefaultLoraWeight,
+  isLoraCompatibleWithModel,
+  isLoraModelConfig,
+  syncGenerateLorasWithModels,
+} from '@workbench/generation/settings';
+import { getModelBaseColorPalette, getModelBaseLabel } from '@workbench/models/baseIdentity';
+import { ModelSelect } from '@workbench/models/components';
+import { Trash2Icon } from 'lucide-react';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { GenerateSettingsUpdate } from './generateDebounce';
+
+import { useRegisterGenerateDraftFlusher } from './generateDraftRegistry';
+import { GenerateCollapsibleSection } from './shared/GenerateCollapsibleSection';
+import { ModelDefaultButton } from './shared/ModelDefaultButton';
+import { useDebouncedDraftValue } from './useDebouncedDraftValue';
+
+interface GenerateConceptsSectionProps {
+  settings: GenerateSettings;
+  loraModels: LoraModelConfig[];
+  projectId: string;
+  selectedModel: GenerateModelConfig | undefined;
+  onCommit: (update: GenerateSettingsUpdate) => void;
+  onCommitImmediate: (patch: Partial<GenerateSettings>) => void;
+}
+
+const LORA_WEIGHT_MARKS = [
+  { label: '-1', value: -1 },
+  { label: '0', value: 0 },
+  { label: '1', value: 1 },
+  { label: '2', value: 2 },
+];
+const LORA_WEIGHT_DEBOUNCE_MS = 250;
+
+const isCompatibleLora = (lora: GenerateLora, selectedModel: GenerateModelConfig | undefined): boolean =>
+  Boolean(selectedModel && isLoraCompatibleWithModel(lora.model, selectedModel));
+
+export const GenerateConceptsSection = ({
+  loraModels,
+  onCommit,
+  onCommitImmediate,
+  projectId,
+  selectedModel,
+  settings,
+}: GenerateConceptsSectionProps) => {
+  const { t } = useTranslation();
+  const loras = useMemo(() => syncGenerateLorasWithModels(settings.loras, loraModels), [loraModels, settings.loras]);
+  const selectedLoraKeys = useMemo(() => new Set(loras.map((lora) => lora.model.key)), [loras]);
+
+  const activeCount = selectedModel
+    ? loras.filter((lora) => lora.isEnabled && isLoraCompatibleWithModel(lora.model, selectedModel)).length
+    : 0;
+
+  const addLora = (model: ModelConfig | null) => {
+    if (!isLoraModelConfig(model) || selectedLoraKeys.has(model.key)) {
+      return;
+    }
+
+    onCommitImmediate({
+      loras: [...loras, { isEnabled: true, model, weight: getDefaultLoraWeight(model) }],
+    });
+  };
+
+  const updateLora = (modelKey: string, patch: Partial<Pick<GenerateLora, 'isEnabled' | 'weight'>>) => {
+    onCommit((settings) => {
+      const latestLoras = syncGenerateLorasWithModels(settings.loras, loraModels);
+      const hasLora = latestLoras.some((lora) => lora.model.key === modelKey);
+
+      if (!hasLora) {
+        return settings;
+      }
+
+      return {
+        ...settings,
+        loras: latestLoras.map((lora) => (lora.model.key === modelKey ? { ...lora, ...patch } : lora)),
+      };
+    });
+  };
+
+  const removeLora = (modelKey: string) => {
+    onCommitImmediate({ loras: loras.filter((lora) => lora.model.key !== modelKey) });
+  };
+
+  const badges =
+    activeCount > 0 ? (
+      <Badge colorPalette="green" size="xs" variant="surface">
+        {t('widgets.generate.activeCount', { count: activeCount })}
+      </Badge>
+    ) : loras.length > 0 ? (
+      <Badge size="xs" variant="surface">
+        {t('widgets.generate.offCount', { count: loras.length })}
+      </Badge>
+    ) : null;
+
+  return (
+    <GenerateCollapsibleSection label={t('widgets.generate.concepts')} defaultOpen badges={badges}>
+      <Stack gap="2" p="2">
+        <Field
+          label={t('widgets.generate.addConcept')}
+          helpText={selectedModel ? undefined : t('widgets.generate.selectMainModelBeforeConcepts')}
+        >
+          <ModelSelect
+            excludeKeys={selectedLoraKeys}
+            filter={(model) =>
+              Boolean(selectedModel && isLoraModelConfig(model) && isLoraCompatibleWithModel(model, selectedModel))
+            }
+            modelTypes={['lora']}
+            placeholder={
+              selectedModel ? t('widgets.generate.searchCompatibleConcepts') : t('widgets.generate.selectModelFirst')
+            }
+            size="xs"
+            value={null}
+            onChange={addLora}
+          />
+        </Field>
+
+        {loras.length === 0 ? (
+          <Text color="fg.subtle" fontSize="2xs">
+            {t('widgets.generate.addConceptsHelp')}
+          </Text>
+        ) : (
+          <Stack gap="2">
+            {loras.map((lora) => (
+              <LoraRow
+                key={lora.model.key}
+                isCompatible={isCompatibleLora(lora, selectedModel)}
+                lora={lora}
+                projectId={projectId}
+                onRemove={() => removeLora(lora.model.key)}
+                onToggle={(isEnabled) => updateLora(lora.model.key, { isEnabled })}
+                onWeightChange={(weight) => updateLora(lora.model.key, { weight })}
+              />
+            ))}
+          </Stack>
+        )}
+      </Stack>
+    </GenerateCollapsibleSection>
+  );
+};
+
+const LoraRow = ({
+  isCompatible,
+  lora,
+  onRemove,
+  projectId,
+  onToggle,
+  onWeightChange,
+}: {
+  isCompatible: boolean;
+  lora: GenerateLora;
+  onRemove: () => void;
+  projectId: string;
+  onToggle: (isEnabled: boolean) => void;
+  onWeightChange: (weight: number) => void;
+}) => {
+  const { t } = useTranslation();
+  const isActive = lora.isEnabled && isCompatible;
+  const defaultWeight = getDefaultLoraWeight(lora.model);
+
+  const {
+    draftValue: draftWeight,
+    flushDraftValue,
+    setDraftValue: setWeight,
+  } = useDebouncedDraftValue({
+    delayMs: LORA_WEIGHT_DEBOUNCE_MS,
+    onCommit: onWeightChange,
+    resetKey: projectId,
+    value: lora.weight,
+  });
+
+  useRegisterGenerateDraftFlusher(flushDraftValue);
+
+  return (
+    <Stack
+      bg="bg.subtle"
+      borderColor={isActive ? 'border.emphasized' : 'border.subtle'}
+      borderWidth="1px"
+      gap="2"
+      opacity={isCompatible ? 1 : 0.68}
+      p="2"
+      rounded="md"
+    >
+      <HStack gap="2" minW="0">
+        <Stack flex="1" gap="0.5" minW="0">
+          <HStack gap="1.5" minW="0">
+            <Text color={isActive ? 'fg' : 'fg.muted'} fontSize="xs" fontWeight="medium" minW="0" truncate>
+              {lora.model.name}
+            </Text>
+            <Badge colorPalette={getModelBaseColorPalette(lora.model.base)} flexShrink={0} size="xs" variant="surface">
+              {getModelBaseLabel(lora.model.base)}
+            </Badge>
+            {!isCompatible ? (
+              <Badge colorPalette="orange" flexShrink={0} size="xs" variant="surface">
+                {t('widgets.generate.incompatible')}
+              </Badge>
+            ) : null}
+          </HStack>
+          {lora.model.trigger_phrases?.length ? (
+            <Text color="fg.subtle" fontSize="2xs" truncate>
+              {lora.model.trigger_phrases.join(', ')}
+            </Text>
+          ) : null}
+        </Stack>
+
+        <HStack flexShrink="0" gap="1">
+          <Switch.Root
+            aria-label={
+              isActive
+                ? t('widgets.generate.disableConcept', { name: lora.model.name })
+                : t('widgets.generate.enableConcept', { name: lora.model.name })
+            }
+            checked={isActive}
+            disabled={!isCompatible}
+            size="sm"
+            onCheckedChange={(event) => onToggle(event.checked)}
+          >
+            <Switch.HiddenInput />
+            <Switch.Control _checked={{ bg: 'accent.solid' }}>
+              <Switch.Thumb />
+            </Switch.Control>
+          </Switch.Root>
+
+          <Tooltip content={t('widgets.generate.removeConcept')}>
+            <IconButton
+              aria-label={t('widgets.generate.removeConceptNamed', { name: lora.model.name })}
+              color="fg.muted"
+              size="2xs"
+              variant="ghost"
+              onClick={onRemove}
+            >
+              <Trash2Icon />
+            </IconButton>
+          </Tooltip>
+        </HStack>
+      </HStack>
+
+      <HStack gap="2">
+        <Slider.Root
+          aria-label={[t('widgets.generate.conceptWeight', { name: lora.model.name })]}
+          disabled={!isActive}
+          flex="1"
+          size="sm"
+          max={DEFAULT_LORA_WEIGHT_CONFIG.sliderMax}
+          min={DEFAULT_LORA_WEIGHT_CONFIG.sliderMin}
+          minW="0"
+          step={DEFAULT_LORA_WEIGHT_CONFIG.coarseStep}
+          value={[draftWeight]}
+          onValueChange={({ value }) => {
+            const nextWeight = value[0];
+
+            if (Number.isFinite(nextWeight)) {
+              setWeight(nextWeight as number);
+            }
+          }}
+        >
+          <Slider.Control>
+            <Slider.Track>
+              <Slider.Range />
+            </Slider.Track>
+            <Slider.Thumbs />
+          </Slider.Control>
+          <Slider.Marks marks={LORA_WEIGHT_MARKS} />
+        </Slider.Root>
+
+        <NumberInput.Root
+          max={DEFAULT_LORA_WEIGHT_CONFIG.numberInputMax}
+          min={DEFAULT_LORA_WEIGHT_CONFIG.numberInputMin}
+          size="xs"
+          step={DEFAULT_LORA_WEIGHT_CONFIG.coarseStep}
+          value={String(draftWeight)}
+          w="20"
+          disabled={!isActive}
+          onValueChange={({ valueAsNumber }) => {
+            if (Number.isFinite(valueAsNumber)) {
+              setWeight(valueAsNumber);
+            }
+          }}
+        >
+          <InputGroup
+            endElement={
+              <ModelDefaultButton
+                disabled={!isActive || draftWeight === defaultWeight}
+                label={t('widgets.generate.useConceptDefaultWeight')}
+                onClick={() => setWeight(defaultWeight)}
+              />
+            }
+            endElementProps={{ pointerEvents: 'auto' }}
+          >
+            <NumberInput.Input aria-label={t('widgets.generate.conceptWeight', { name: lora.model.name })} />
+          </InputGroup>
+        </NumberInput.Root>
+      </HStack>
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateDimensionFields.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateDimensionFields.tsx
new file mode 100644
index 00000000000..f5a949dd39f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateDimensionFields.tsx
@@ -0,0 +1,421 @@
+/* eslint-disable react/react-compiler, react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type { SelectValueChangeDetails } from '@chakra-ui/react';
+import type { AspectRatioId, GenerateModelConfig, GenerateSettings } from '@workbench/generation/types';
+
+import { Badge, Box, createListCollection, HStack, Icon, InputGroup, NumberInput, Stack, Text } from '@chakra-ui/react';
+import { Field, IconButton, Select, Tooltip } from '@workbench/components/ui';
+import { getDefaultGenerateSettings, getGenerationDimensions } from '@workbench/generation/baseGenerationPolicies';
+import {
+  ASPECT_RATIO_MAP,
+  ASPECT_RATIO_OPTIONS,
+  calculateNewSize,
+  clampDimension,
+  isAspectRatioId,
+  MAX_DIMENSION,
+  MIN_DIMENSION,
+} from '@workbench/generation/settings';
+import { ArrowLeftRightIcon, LockIcon, LockOpenIcon, RulerDimensionLineIcon, ScalingIcon } from 'lucide-react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { AspectRatioPreview } from './shared/AspectRatioPreview';
+import { GenerateCollapsibleSection } from './shared/GenerateCollapsibleSection';
+import { ModelDefaultButton } from './shared/ModelDefaultButton';
+
+interface GenerateDimensionFieldsProps {
+  settings: GenerateSettings;
+  projectId: string;
+  selectedModel: GenerateModelConfig | undefined;
+  onCommit: (patch: Partial<GenerateSettings>) => void;
+}
+
+type Dimensions = Pick<GenerateSettings, 'height' | 'width'>;
+type AspectRatioOption = { id: AspectRatioId; ratio: number };
+
+/** The ratio to enforce, preferring the stored value and falling back to the current dimensions. */
+const getActiveRatio = (settings: GenerateSettings): number =>
+  settings.aspectRatioValue > 0
+    ? settings.aspectRatioValue
+    : settings.height > 0
+      ? settings.width / settings.height
+      : 1;
+
+const getAspectRatioOptionRatio = (id: AspectRatioId, fallbackRatio: number): number =>
+  id === 'Free' ? fallbackRatio : ASPECT_RATIO_MAP[id].ratio;
+
+export const GenerateDimensionFields = ({
+  onCommit,
+  projectId,
+  selectedModel,
+  settings,
+}: GenerateDimensionFieldsProps) => {
+  const { t } = useTranslation();
+  const [draftDimensions, setDraftDimensions] = useState<Dimensions | null>(null);
+  const modelDefaults = selectedModel ? getDefaultGenerateSettings(selectedModel) : null;
+  const dimensions = getGenerationDimensions(selectedModel);
+  const dimensionGrid = dimensions.grid;
+  const isRatioConstrained = settings.aspectRatioId !== 'Free' || settings.aspectRatioIsLocked;
+  const displayDimensions = draftDimensions ?? { height: settings.height, width: settings.width };
+  const onCommitRef = useRef(onCommit);
+  const pendingDimensionsRef = useRef<Dimensions | null>(null);
+  const projectIdRef = useRef(projectId);
+  const previousSettingsDimensionsRef = useRef<Dimensions>({ height: settings.height, width: settings.width });
+  const dimensionRatio = displayDimensions.height > 0 ? displayDimensions.width / displayDimensions.height : 1;
+
+  const aspectRatioOptions = useMemo<AspectRatioOption[]>(
+    () =>
+      ASPECT_RATIO_OPTIONS.map((id) => ({
+        id,
+        ratio: getAspectRatioOptionRatio(id, dimensionRatio),
+      })),
+    [dimensionRatio]
+  );
+
+  const aspectRatioCollection = useMemo(
+    () =>
+      createListCollection({
+        itemToString: (item: AspectRatioOption) => item.id,
+        itemToValue: (item: AspectRatioOption) => item.id,
+        items: aspectRatioOptions,
+      }),
+    [aspectRatioOptions]
+  );
+
+  const activeAspectRatioPreviewRatio = getAspectRatioOptionRatio(settings.aspectRatioId, dimensionRatio);
+
+  useEffect(() => {
+    onCommitRef.current = onCommit;
+  }, [onCommit]);
+
+  const commitDimensions = useCallback((dimensions: Dimensions) => {
+    pendingDimensionsRef.current = dimensions;
+    onCommitRef.current(dimensions);
+  }, []);
+
+  useLayoutEffect(() => {
+    if (projectIdRef.current === projectId) {
+      return;
+    }
+
+    projectIdRef.current = projectId;
+    pendingDimensionsRef.current = null;
+    previousSettingsDimensionsRef.current = { height: settings.height, width: settings.width };
+    setDraftDimensions(null);
+  }, [projectId, settings.height, settings.width]);
+
+  useEffect(() => {
+    const previousSettingsDimensions = previousSettingsDimensionsRef.current;
+    previousSettingsDimensionsRef.current = { height: settings.height, width: settings.width };
+
+    if (!draftDimensions) {
+      return;
+    }
+
+    if (settings.width === draftDimensions.width && settings.height === draftDimensions.height) {
+      pendingDimensionsRef.current = null;
+      setDraftDimensions(null);
+      return;
+    }
+
+    if (settings.width === previousSettingsDimensions.width && settings.height === previousSettingsDimensions.height) {
+      return;
+    }
+
+    pendingDimensionsRef.current = null;
+    setDraftDimensions(null);
+  }, [draftDimensions, settings.height, settings.width]);
+
+  const getNextDimensions = (key: 'height' | 'width', value: number, shouldSnap: boolean): Dimensions => {
+    const nextValue = shouldSnap ? clampDimension(value, dimensionGrid) : value;
+
+    if (!isRatioConstrained) {
+      return { ...displayDimensions, [key]: nextValue };
+    }
+
+    const ratio = getActiveRatio({ ...settings, ...displayDimensions });
+
+    return key === 'width'
+      ? { height: shouldSnap ? clampDimension(nextValue / ratio, dimensionGrid) : nextValue / ratio, width: nextValue }
+      : { height: nextValue, width: shouldSnap ? clampDimension(nextValue * ratio, dimensionGrid) : nextValue * ratio };
+  };
+
+  const setDimension =
+    (key: 'height' | 'width') =>
+    ({ valueAsNumber }: NumberInput.ValueChangeDetails) => {
+      const value = valueAsNumber;
+
+      if (!Number.isFinite(value) || value <= 0) {
+        return;
+      }
+
+      setDraftDimensions(getNextDimensions(key, value, false));
+    };
+
+  const commitDimension =
+    (key: 'height' | 'width') =>
+    ({ valueAsNumber }: NumberInput.ValueChangeDetails) => {
+      const value = valueAsNumber;
+
+      if (!Number.isFinite(value) || value <= 0) {
+        return;
+      }
+
+      const dimensions = getNextDimensions(key, value, true);
+
+      setDraftDimensions(dimensions);
+      commitDimensions(dimensions);
+    };
+
+  const snapDimension = (key: 'height' | 'width') => () => {
+    const snapped = clampDimension(displayDimensions[key], dimensionGrid);
+
+    if (snapped !== displayDimensions[key]) {
+      const dimensions = getNextDimensions(key, snapped, true);
+
+      setDraftDimensions(dimensions);
+      commitDimensions(dimensions);
+    }
+  };
+
+  const setDimensionToModelDefault = (key: 'height' | 'width') => {
+    if (!modelDefaults) {
+      return;
+    }
+
+    const dimensions = getNextDimensions(key, modelDefaults[key], true);
+
+    setDraftDimensions(dimensions);
+    commitDimensions(dimensions);
+  };
+
+  const commitSettings = (patch: Partial<GenerateSettings>) => {
+    pendingDimensionsRef.current = null;
+    setDraftDimensions(null);
+    onCommit(patch);
+  };
+
+  const setAspectRatioId = ({ value }: SelectValueChangeDetails<AspectRatioOption>) => {
+    const id = value[0];
+
+    if (!isAspectRatioId(id)) {
+      return;
+    }
+
+    if (id === 'Free') {
+      commitSettings({
+        aspectRatioId: 'Free',
+        aspectRatioIsLocked: false,
+        aspectRatioValue: displayDimensions.height > 0 ? displayDimensions.width / displayDimensions.height : 1,
+        ...displayDimensions,
+      });
+      return;
+    }
+
+    const ratio = ASPECT_RATIO_MAP[id].ratio;
+
+    commitSettings({
+      aspectRatioId: id,
+      aspectRatioIsLocked: true,
+      aspectRatioValue: ratio,
+      ...calculateNewSize(ratio, displayDimensions.width * displayDimensions.height, dimensionGrid),
+    });
+  };
+
+  const toggleLock = () => {
+    commitSettings({
+      aspectRatioIsLocked: !settings.aspectRatioIsLocked,
+      // Locking in Free mode captures the current ratio so further edits preserve it.
+      aspectRatioValue:
+        !settings.aspectRatioIsLocked && settings.aspectRatioId === 'Free' && displayDimensions.height > 0
+          ? displayDimensions.width / displayDimensions.height
+          : settings.aspectRatioValue,
+      ...displayDimensions,
+    });
+  };
+
+  const swapDimensions = () => {
+    const inverseId: AspectRatioId =
+      settings.aspectRatioId === 'Free' ? 'Free' : ASPECT_RATIO_MAP[settings.aspectRatioId].inverseId;
+
+    commitSettings({
+      aspectRatioId: inverseId,
+      aspectRatioValue: settings.aspectRatioValue > 0 ? 1 / settings.aspectRatioValue : 1,
+      height: displayDimensions.width,
+      width: displayDimensions.height,
+    });
+  };
+
+  const optimizeSize = () => {
+    const optimal = dimensions.optimal;
+    const ratio = isRatioConstrained
+      ? getActiveRatio({ ...settings, ...displayDimensions })
+      : displayDimensions.height > 0
+        ? displayDimensions.width / displayDimensions.height
+        : 1;
+
+    commitSettings(calculateNewSize(ratio, optimal * optimal, dimensionGrid));
+  };
+
+  const badges = (
+    <>
+      <Badge size="xs">
+        {displayDimensions.width}x{displayDimensions.height}
+      </Badge>
+      {settings.aspectRatioIsLocked && (
+        <Badge size="xs">
+          <Icon as={LockIcon} boxSize="3" />
+        </Badge>
+      )}
+    </>
+  );
+
+  return (
+    <GenerateCollapsibleSection label={t('widgets.generate.dimensions')} badges={badges} defaultOpen>
+      <Field label={t('widgets.generate.aspectRatio')} p="2">
+        <HStack gap="1">
+          <Select
+            collection={aspectRatioCollection}
+            contentProps={{ maxH: '18rem' }}
+            flex="1"
+            renderItem={(option) => (
+              <HStack as="span" gap="2">
+                <AspectRatioPreview boxSize="6" ratio={option.ratio} />
+                <Text as="span" fontSize="xs">
+                  {option.id}
+                </Text>
+              </HStack>
+            )}
+            size="xs"
+            value={[settings.aspectRatioId]}
+            valueText={
+              <HStack as="span" gap="2" minW="0">
+                <AspectRatioPreview boxSize="5" ratio={activeAspectRatioPreviewRatio} />
+                <Text as="span" fontSize="xs" truncate>
+                  {settings.aspectRatioId}
+                </Text>
+              </HStack>
+            }
+            onValueChange={setAspectRatioId}
+          />
+          <Tooltip
+            content={
+              settings.aspectRatioIsLocked
+                ? t('widgets.generate.unlockAspectRatio')
+                : t('widgets.generate.lockAspectRatio')
+            }
+          >
+            <IconButton
+              aria-label={
+                settings.aspectRatioIsLocked
+                  ? t('widgets.generate.unlockAspectRatio')
+                  : t('widgets.generate.lockAspectRatio')
+              }
+              size="xs"
+              variant={settings.aspectRatioIsLocked ? 'solid' : 'outline'}
+              onClick={toggleLock}
+            >
+              {settings.aspectRatioIsLocked ? <LockIcon /> : <LockOpenIcon />}
+            </IconButton>
+          </Tooltip>
+          <Tooltip content={t('widgets.generate.swapWidthAndHeight')}>
+            <IconButton
+              aria-label={t('widgets.generate.swapWidthAndHeight')}
+              size="xs"
+              variant="outline"
+              onClick={swapDimensions}
+            >
+              <ArrowLeftRightIcon />
+            </IconButton>
+          </Tooltip>
+          <Tooltip content={t('widgets.generate.setOptimalSizeDescription')}>
+            <IconButton
+              aria-label={t('widgets.generate.setOptimalSize')}
+              size="xs"
+              variant="outline"
+              onClick={optimizeSize}
+            >
+              <ScalingIcon />
+            </IconButton>
+          </Tooltip>
+        </HStack>
+      </Field>
+      <HStack alignItems="flex-start" gap="2" p="2">
+        <Stack w="full">
+          <Field
+            label={t('widgets.generate.width')}
+            helpText={t('widgets.generate.multipleOf', { value: dimensionGrid })}
+          >
+            <NumberInput.Root
+              size="xs"
+              allowMouseWheel
+              max={MAX_DIMENSION}
+              min={MIN_DIMENSION}
+              value={String(displayDimensions.width)}
+              step={dimensionGrid}
+              onBlur={snapDimension('width')}
+              onValueCommit={commitDimension('width')}
+              onValueChange={setDimension('width')}
+            >
+              <InputGroup
+                endElement={
+                  <ModelDefaultButton
+                    disabled={!modelDefaults || displayDimensions.width === modelDefaults.width}
+                    label={t('widgets.generate.useModelDefaultWidth')}
+                    onClick={() => setDimensionToModelDefault('width')}
+                  />
+                }
+                endElementProps={{ pointerEvents: 'auto' }}
+                startElementProps={{ pointerEvents: 'auto' }}
+                startElement={
+                  <NumberInput.Scrubber>
+                    <Icon as={RulerDimensionLineIcon} boxSize="3" />
+                  </NumberInput.Scrubber>
+                }
+              >
+                <NumberInput.Input />
+              </InputGroup>
+            </NumberInput.Root>
+          </Field>
+          <Field
+            label={t('widgets.generate.height')}
+            helpText={t('widgets.generate.multipleOf', { value: dimensionGrid })}
+          >
+            <NumberInput.Root
+              size="xs"
+              allowMouseWheel
+              max={MAX_DIMENSION}
+              min={MIN_DIMENSION}
+              value={String(displayDimensions.height)}
+              step={dimensionGrid}
+              onBlur={snapDimension('height')}
+              onValueCommit={commitDimension('height')}
+              onValueChange={setDimension('height')}
+            >
+              <InputGroup
+                endElement={
+                  <ModelDefaultButton
+                    disabled={!modelDefaults || displayDimensions.height === modelDefaults.height}
+                    label={t('widgets.generate.useModelDefaultHeight')}
+                    onClick={() => setDimensionToModelDefault('height')}
+                  />
+                }
+                endElementProps={{ pointerEvents: 'auto' }}
+                startElementProps={{ pointerEvents: 'auto' }}
+                startElement={
+                  <NumberInput.Scrubber>
+                    <Icon as={RulerDimensionLineIcon} boxSize="3" rotate="90" />
+                  </NumberInput.Scrubber>
+                }
+              >
+                <NumberInput.Input />
+              </InputGroup>
+            </NumberInput.Root>
+          </Field>
+        </Stack>
+        <Box w="1/3" aspectRatio="1/1" borderColor="bg.emphasized" borderWidth={1} p={1} rounded="sm">
+          <AspectRatioPreview boxSize="full" ratio={dimensionRatio} />
+        </Box>
+      </HStack>
+    </GenerateCollapsibleSection>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateModelFields.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateModelFields.tsx
new file mode 100644
index 00000000000..1a855a0e63d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateModelFields.tsx
@@ -0,0 +1,279 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type { GenerateModelConfig, GenerateSettings, VaeModelConfig } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type { ChangeEvent } from 'react';
+
+import { HStack, Icon, InputGroup, NativeSelect, NumberInput, Stack } from '@chakra-ui/react';
+import { Button, IconButton, Field, Tooltip } from '@workbench/components/ui';
+import {
+  getDefaultGenerateSettings,
+  getGenerationModelPolicy,
+  getSettingsWithCompatibleModelSelections,
+  getSettingsWithModelDefaults,
+  isGenerateModelSelectable,
+} from '@workbench/generation/baseGenerationPolicies';
+import {
+  getModelDefaultVae,
+  hasModelDefaultVae,
+  isGenerateModelConfig,
+  SEED_MAX,
+} from '@workbench/generation/settings';
+import { ModelSelect } from '@workbench/models/components';
+import { useNotify } from '@workbench/useNotify';
+import { ArrowRightLeft, DicesIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import { GenerateCollapsibleSection } from './shared/GenerateCollapsibleSection';
+import { ModelDefaultButton } from './shared/ModelDefaultButton';
+
+const formatClearedSettings = (labels: readonly string[]) =>
+  labels.length <= 1 ? labels[0] : `${labels.slice(0, -1).join(', ')} and ${labels[labels.length - 1]}`;
+
+interface GenerateModelFieldsProps {
+  settings: GenerateSettings;
+  models: readonly ModelConfig[];
+  selectedModel: GenerateModelConfig | undefined;
+  vaeModels: VaeModelConfig[];
+  onCommit: (patch: Partial<GenerateSettings>) => void;
+  onCommitSettings: (nextSettings: GenerateSettings) => void;
+}
+
+const MODEL_DEFAULT_VALUE_KEYS = [
+  'aspectRatioId',
+  'aspectRatioIsLocked',
+  'aspectRatioValue',
+  'cfgRescaleMultiplier',
+  'cfgScale',
+  'height',
+  'modelKey',
+  'scheduler',
+  'steps',
+  'vaePrecision',
+  'width',
+] as const satisfies readonly (keyof GenerateSettings)[];
+
+const settingsMatchModelDefaults = (settings: GenerateSettings, modelDefaultSettings: GenerateSettings) =>
+  MODEL_DEFAULT_VALUE_KEYS.every((key) => Object.is(settings[key], modelDefaultSettings[key])) &&
+  settings.vae?.key === modelDefaultSettings.vae?.key &&
+  settings.loras.length === modelDefaultSettings.loras.length &&
+  settings.loras.every((lora, index) => lora.isEnabled === modelDefaultSettings.loras[index]?.isEnabled);
+
+export const GenerateModelFields = ({
+  models,
+  onCommit,
+  onCommitSettings,
+  selectedModel,
+  settings,
+  vaeModels,
+}: GenerateModelFieldsProps) => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const modelDefaults = selectedModel ? getDefaultGenerateSettings(selectedModel) : null;
+  const policy = getGenerationModelPolicy(selectedModel, settings);
+
+  const getModelDefaultSettings = (model: GenerateModelConfig) => {
+    const nextSettings = getSettingsWithModelDefaults(settings, model);
+
+    return hasModelDefaultVae(model) ? { ...nextSettings, vae: getModelDefaultVae(model, vaeModels) } : nextSettings;
+  };
+
+  const modelDefaultSettings = selectedModel ? getModelDefaultSettings(selectedModel) : null;
+  const modelDefaultsAreApplied = modelDefaultSettings
+    ? settingsMatchModelDefaults(settings, modelDefaultSettings)
+    : false;
+
+  const commitNumber = (key: 'cfgScale' | 'seed' | 'steps', value: number) => {
+    if (!Number.isFinite(value)) {
+      return;
+    }
+
+    onCommit({ [key]: value });
+  };
+
+  const updateNumberInput =
+    (key: 'cfgScale' | 'seed' | 'steps') =>
+    ({ valueAsNumber }: NumberInput.ValueChangeDetails) => {
+      commitNumber(key, valueAsNumber);
+    };
+
+  const selectModel = (model: GenerateModelConfig) => {
+    const result = getSettingsWithCompatibleModelSelections(settings, model, models);
+
+    onCommitSettings(result.settings);
+
+    if (result.clearedLabels.length > 0) {
+      notify.info(
+        t('widgets.generate.incompatibleSettingsCleared'),
+        t('widgets.generate.incompatibleSettingsClearedDescription', {
+          count: result.clearedLabels.length,
+          labels: formatClearedSettings(result.clearedLabels),
+          name: model.name,
+        })
+      );
+    }
+  };
+
+  const applyModelDefaults = (model: GenerateModelConfig) => {
+    onCommitSettings(getModelDefaultSettings(model));
+  };
+
+  return (
+    <GenerateCollapsibleSection label={t('widgets.generate.model')} defaultOpen>
+      <Stack gap="2" p="2">
+        <Field label={t('widgets.generate.model')}>
+          <HStack gap="1">
+            <ModelSelect
+              filter={(model) => isGenerateModelConfig(model) && isGenerateModelSelectable(model)}
+              isClearable={false}
+              modelTypes={['main', 'external_image_generator']}
+              placeholder={t('widgets.generate.selectModel')}
+              value={selectedModel?.key ?? null}
+              size="xs"
+              onChange={(model) => {
+                if (isGenerateModelConfig(model) && isGenerateModelSelectable(model)) {
+                  selectModel(model);
+                }
+              }}
+            />
+            <ModelDefaultButton
+              active={Boolean(modelDefaultSettings && !modelDefaultsAreApplied)}
+              disabled={!selectedModel}
+              onClick={() => {
+                if (selectedModel) {
+                  applyModelDefaults(selectedModel);
+                }
+              }}
+            />
+          </HStack>
+        </Field>
+        <HStack gap="2">
+          <Field label={t('widgets.generate.steps')}>
+            <NumberInput.Root
+              size="xs"
+              value={String(settings.steps)}
+              onValueChange={updateNumberInput('steps')}
+              min={1}
+              allowMouseWheel
+            >
+              <InputGroup
+                startElementProps={{ pointerEvents: 'auto' }}
+                startElement={
+                  <NumberInput.Scrubber>
+                    <Icon as={ArrowRightLeft} boxSize="3" />
+                  </NumberInput.Scrubber>
+                }
+                endElement={
+                  <ModelDefaultButton
+                    disabled={!modelDefaults || settings.steps === modelDefaults.steps}
+                    label={t('widgets.generate.useModelDefaultSteps')}
+                    onClick={() => {
+                      if (modelDefaults) {
+                        onCommit({ steps: modelDefaults.steps });
+                      }
+                    }}
+                  />
+                }
+                endElementProps={{ pointerEvents: 'auto' }}
+              >
+                <NumberInput.Input />
+              </InputGroup>
+            </NumberInput.Root>
+          </Field>
+          <Field label={policy.ui.guidanceLabel}>
+            <NumberInput.Root
+              size="xs"
+              value={String(settings.cfgScale)}
+              onValueChange={updateNumberInput('cfgScale')}
+              min={0}
+              max={10}
+              step={0.5}
+            >
+              <InputGroup
+                endElement={
+                  <ModelDefaultButton
+                    disabled={!modelDefaults || settings.cfgScale === modelDefaults.cfgScale}
+                    label={t('widgets.generate.useModelDefaultField', { field: policy.ui.guidanceLabel })}
+                    onClick={() => {
+                      if (modelDefaults) {
+                        onCommit({ cfgScale: modelDefaults.cfgScale });
+                      }
+                    }}
+                  />
+                }
+                endElementProps={{ pointerEvents: 'auto' }}
+              >
+                <NumberInput.Input />
+              </InputGroup>
+            </NumberInput.Root>
+          </Field>
+          {policy.ui.schedulerVisible ? (
+            <Field label={t('widgets.generate.scheduler')}>
+              <HStack gap="1">
+                <NativeSelect.Root flex="1" size="xs">
+                  <NativeSelect.Field
+                    aria-label={t('widgets.generate.scheduler')}
+                    value={settings.scheduler}
+                    onChange={(event: ChangeEvent<HTMLSelectElement>) =>
+                      onCommit({ scheduler: event.currentTarget.value })
+                    }
+                  >
+                    {policy.scheduler.options.map((option) => (
+                      <option key={option.value} value={option.value}>
+                        {option.label}
+                      </option>
+                    ))}
+                  </NativeSelect.Field>
+                  <NativeSelect.Indicator />
+                </NativeSelect.Root>
+                <ModelDefaultButton
+                  disabled={!modelDefaults || settings.scheduler === modelDefaults.scheduler}
+                  label={t('widgets.generate.useModelDefaultScheduler')}
+                  onClick={() => {
+                    if (modelDefaults) {
+                      onCommit({ scheduler: modelDefaults.scheduler });
+                    }
+                  }}
+                />
+              </HStack>
+            </Field>
+          ) : null}
+        </HStack>
+        {policy.ui.seedVisible ? (
+          <Field label={t('common.seed')}>
+            <HStack gap="2">
+              <NumberInput.Root
+                size="xs"
+                value={String(settings.seed)}
+                onValueChange={updateNumberInput('seed')}
+                min={0}
+                max={SEED_MAX}
+                w="full"
+                disabled={settings.shouldRandomizeSeed}
+              >
+                <NumberInput.Input />
+              </NumberInput.Root>
+              <Tooltip content={t('widgets.generate.shuffleSeed')}>
+                <IconButton
+                  aria-label={t('widgets.generate.shuffleSeed')}
+                  disabled={settings.shouldRandomizeSeed}
+                  size="xs"
+                  variant="outline"
+                  onClick={() => onCommit({ seed: Math.floor(Math.random() * SEED_MAX) })}
+                >
+                  <DicesIcon />
+                </IconButton>
+              </Tooltip>
+              <Button
+                size="xs"
+                variant={settings.shouldRandomizeSeed ? 'solid' : 'outline'}
+                onClick={() => onCommit({ shouldRandomizeSeed: !settings.shouldRandomizeSeed })}
+              >
+                {t('widgets.generate.random')}
+              </Button>
+            </HStack>
+          </Field>
+        ) : null}
+      </Stack>
+    </GenerateCollapsibleSection>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateSettingsForm.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateSettingsForm.tsx
new file mode 100644
index 00000000000..00798f42be7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateSettingsForm.tsx
@@ -0,0 +1,310 @@
+/* eslint-disable react/react-compiler */
+import type {
+  GenerateModelConfig,
+  GenerateSettings,
+  LoraModelConfig,
+  VaeModelConfig,
+} from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+
+import { Stack, Text } from '@chakra-ui/react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+import { GenerateAdvancedFields } from './GenerateAdvancedFields';
+import { GenerateCanvasCompositingSection } from './GenerateCanvasCompositingSection';
+import { GenerateComponentsSection } from './GenerateComponentsSection';
+import { GenerateConceptsSection } from './GenerateConceptsSection';
+import {
+  applyGenerateSettingsPatch,
+  applyGenerateSettingsUpdate,
+  getChangedGenerateSettingsPatch,
+  type GenerateSettingsUpdate,
+  mergeGenerateSettingsUpdate,
+  type PendingGenerateSettingsUpdate,
+} from './generateDebounce';
+import { GenerateDimensionFields } from './GenerateDimensionFields';
+import { useRegisterGenerateDraftFlusher } from './generateDraftRegistry';
+import { getSettingsWithLatestPromptFields } from './generateFormViewModel';
+import { GenerateModelFields } from './GenerateModelFields';
+import { GeneratePromptFields } from './promptFields';
+import { GenerateReferenceImagesSection } from './reference-images/GenerateReferenceImagesSection';
+
+const GENERATE_INPUT_DEBOUNCE_MS = 250;
+
+interface GenerateSettingsFormProps {
+  isLoadingModels: boolean;
+  loadError: string | null;
+  settings: GenerateSettings;
+  loraModels: LoraModelConfig[];
+  models: readonly ModelConfig[];
+  projectId: string;
+  selectedModel: GenerateModelConfig | undefined;
+  supportedModels: GenerateModelConfig[];
+  vaeModels: VaeModelConfig[];
+  onCommitSettings: (nextSettings: GenerateSettings) => void;
+  onPatchSettings: (patch: Partial<GenerateSettings>) => void;
+}
+
+export const GenerateSettingsForm = ({
+  isLoadingModels,
+  loadError,
+  loraModels,
+  models,
+  onCommitSettings,
+  onPatchSettings,
+  projectId,
+  selectedModel,
+  settings,
+  supportedModels,
+  vaeModels,
+}: GenerateSettingsFormProps) => {
+  const [draftSettings, setDraftSettings] = useState(settings);
+  const draftSettingsRef = useRef(settings);
+  const latestSettingsRef = useRef(settings);
+  const pendingUpdateRef = useRef<PendingGenerateSettingsUpdate>(null);
+  const projectIdRef = useRef(projectId);
+  const timeoutRef = useRef<number | null>(null);
+  const onCommitSettingsRef = useRef(onCommitSettings);
+  const onPatchSettingsRef = useRef(onPatchSettings);
+
+  onCommitSettingsRef.current = onCommitSettings;
+  onPatchSettingsRef.current = onPatchSettings;
+
+  const setDraft = (nextSettings: GenerateSettings) => {
+    draftSettingsRef.current = nextSettings;
+    setDraftSettings(nextSettings);
+  };
+
+  const clearPendingUpdate = () => {
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    pendingUpdateRef.current = null;
+  };
+
+  useLayoutEffect(() => {
+    if (projectIdRef.current !== projectId) {
+      projectIdRef.current = projectId;
+      clearPendingUpdate();
+      latestSettingsRef.current = settings;
+      setDraft(settings);
+      return;
+    }
+
+    latestSettingsRef.current = settings;
+    setDraft(applyGenerateSettingsUpdate(settings, pendingUpdateRef.current));
+  }, [projectId, settings]);
+
+  const flushPendingUpdate = (shouldUpdateDraft = true) => {
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    const updateToCommit = pendingUpdateRef.current;
+
+    pendingUpdateRef.current = null;
+
+    if (updateToCommit) {
+      const previousSettings = latestSettingsRef.current;
+      const settingsToCommit = applyGenerateSettingsUpdate(latestSettingsRef.current, updateToCommit);
+
+      latestSettingsRef.current = settingsToCommit;
+
+      if (shouldUpdateDraft) {
+        setDraft(settingsToCommit);
+      }
+
+      onPatchSettingsRef.current(getChangedGenerateSettingsPatch(previousSettings, settingsToCommit));
+    }
+  };
+
+  useRegisterGenerateDraftFlusher(flushPendingUpdate);
+
+  useEffect(
+    () => () => {
+      if (timeoutRef.current !== null) {
+        window.clearTimeout(timeoutRef.current);
+      }
+
+      flushPendingUpdate(false);
+    },
+    []
+  );
+
+  const scheduleCommitUpdate = (update: GenerateSettingsUpdate) => {
+    pendingUpdateRef.current = mergeGenerateSettingsUpdate(pendingUpdateRef.current, update);
+
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+    }
+
+    timeoutRef.current = window.setTimeout(() => {
+      timeoutRef.current = null;
+      flushPendingUpdate();
+    }, GENERATE_INPUT_DEBOUNCE_MS);
+  };
+
+  const commit = useCallback((update: GenerateSettingsUpdate) => {
+    const nextSettings = applyGenerateSettingsUpdate(
+      draftSettingsRef.current,
+      mergeGenerateSettingsUpdate(null, update)
+    );
+
+    setDraft(nextSettings);
+    scheduleCommitUpdate(update);
+  }, []);
+
+  const commitDebouncedDraftUpdate = useCallback((update: GenerateSettingsUpdate) => {
+    const pendingUpdate = mergeGenerateSettingsUpdate(pendingUpdateRef.current, update);
+    const previousSettings = latestSettingsRef.current;
+    const nextSettings = applyGenerateSettingsUpdate(latestSettingsRef.current, pendingUpdate);
+
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    pendingUpdateRef.current = null;
+    latestSettingsRef.current = nextSettings;
+    setDraft(nextSettings);
+    onPatchSettingsRef.current(getChangedGenerateSettingsPatch(previousSettings, nextSettings));
+  }, []);
+
+  const commitPromptDraftPatch = useCallback((patch: Partial<GenerateSettings>) => {
+    const pendingUpdate = mergeGenerateSettingsUpdate(pendingUpdateRef.current, patch);
+    const previousSettings = latestSettingsRef.current;
+    const nextSettings = applyGenerateSettingsUpdate(latestSettingsRef.current, pendingUpdate);
+
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    pendingUpdateRef.current = null;
+    latestSettingsRef.current = nextSettings;
+    onPatchSettingsRef.current(getChangedGenerateSettingsPatch(previousSettings, nextSettings));
+  }, []);
+
+  const commitSettingsImmediately = useCallback(
+    (nextSettings: GenerateSettings) => {
+      const previousSettings = latestSettingsRef.current;
+      const settingsToCommit = getSettingsWithLatestPromptFields(
+        nextSettings,
+        applyGenerateSettingsUpdate(latestSettingsRef.current, pendingUpdateRef.current)
+      );
+
+      if (timeoutRef.current !== null) {
+        window.clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+
+      pendingUpdateRef.current = null;
+      latestSettingsRef.current = settingsToCommit;
+      setDraft(settingsToCommit);
+
+      if (!Object.is(previousSettings, settingsToCommit)) {
+        onCommitSettings(settingsToCommit);
+      }
+    },
+    [onCommitSettings]
+  );
+
+  const commitPatchImmediately = useCallback((patch: Partial<GenerateSettings>) => {
+    const previousSettings = latestSettingsRef.current;
+    const nextSettings = applyGenerateSettingsPatch(
+      applyGenerateSettingsUpdate(latestSettingsRef.current, pendingUpdateRef.current),
+      patch
+    );
+
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    pendingUpdateRef.current = null;
+    latestSettingsRef.current = nextSettings;
+    setDraft(nextSettings);
+    onPatchSettingsRef.current(getChangedGenerateSettingsPatch(previousSettings, nextSettings));
+  }, []);
+
+  return (
+    <Stack gap="1" px={1}>
+      <GeneratePromptFields
+        projectId={projectId}
+        selectedModel={selectedModel}
+        settings={draftSettings}
+        onCommit={commitPromptDraftPatch}
+        onCommitImmediate={commitPatchImmediately}
+      />
+
+      <GenerateReferenceImagesSection
+        models={models}
+        selectedModel={selectedModel}
+        settings={draftSettings}
+        onCommit={commit}
+        onCommitImmediate={commitPatchImmediately}
+      />
+
+      <GenerateDimensionFields
+        projectId={projectId}
+        selectedModel={selectedModel}
+        settings={draftSettings}
+        onCommit={commit}
+      />
+
+      <GenerateCanvasCompositingSection />
+
+      <GenerateModelFields
+        models={models}
+        selectedModel={selectedModel}
+        settings={draftSettings}
+        vaeModels={vaeModels}
+        onCommit={commit}
+        onCommitSettings={commitSettingsImmediately}
+      />
+
+      <GenerateConceptsSection
+        loraModels={loraModels}
+        projectId={projectId}
+        selectedModel={selectedModel}
+        settings={draftSettings}
+        onCommit={commitDebouncedDraftUpdate}
+        onCommitImmediate={commitPatchImmediately}
+      />
+
+      <GenerateComponentsSection
+        selectedModel={selectedModel}
+        settings={draftSettings}
+        onCommit={commitPatchImmediately}
+      />
+
+      <GenerateAdvancedFields
+        selectedModel={selectedModel}
+        settings={draftSettings}
+        onCommit={commit}
+        onCommitImmediate={commitPatchImmediately}
+      />
+
+      {isLoadingModels ? (
+        <Text color="fg.subtle" fontSize="2xs">
+          Loading backend models...
+        </Text>
+      ) : loadError ? (
+        <Text color="fg.error" fontSize="2xs">
+          {loadError}
+        </Text>
+      ) : supportedModels.length === 0 ? (
+        <Text color="fg.subtle" fontSize="2xs">
+          No supported generation models were found on the backend.
+        </Text>
+      ) : selectedModel ? null : (
+        <Text color="fg.error" fontSize="2xs">
+          Select a model to enable invocation.
+        </Text>
+      )}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateWidgetView.tsx
new file mode 100644
index 00000000000..a3822e70bc2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/GenerateWidgetView.tsx
@@ -0,0 +1,143 @@
+import type {
+  GenerateModelConfig,
+  GenerateSettings,
+  LoraModelConfig,
+  VaeModelConfig,
+} from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+
+import {
+  getAutoFlux2ComponentSourceModel,
+  getDefaultGenerateSettings,
+  isSupportedGenerateModel,
+} from '@workbench/generation/baseGenerationPolicies';
+import {
+  isLoraModelConfig,
+  normalizeGenerateSettings,
+  normalizeGenerateWidgetValues,
+  syncGenerateWidgetValuesWithModels,
+} from '@workbench/generation/settings';
+import { ensureModelsLoaded, useModelsSelector } from '@workbench/models/modelsStore';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useCallback, useEffect, useMemo } from 'react';
+
+import { areProjectGenerateFormValuesEqual, getGenerateFormCommitPatch } from './generateFormViewModel';
+import { GenerateSettingsForm } from './GenerateSettingsForm';
+
+const getSettingsWithAutoComponentSource = (
+  nextSettings: GenerateSettings,
+  model: GenerateModelConfig,
+  models: readonly ModelConfig[]
+): GenerateSettings => {
+  const componentSourceModel = getAutoFlux2ComponentSourceModel(model, nextSettings, models);
+
+  if (componentSourceModel === undefined || componentSourceModel?.key === nextSettings.componentSourceModel?.key) {
+    return nextSettings;
+  }
+
+  return { ...nextSettings, componentSourceModel };
+};
+
+export const GenerateWidgetView = () => {
+  const storedSelection = useActiveProjectSelector(
+    (project) => ({ projectId: project.id, values: getProjectWidgetValues(project, 'generate') }),
+    areProjectGenerateFormValuesEqual
+  );
+  const projectId = storedSelection.projectId;
+  const storedValues = storedSelection.values;
+  const dispatch = useWorkbenchDispatch();
+  const error = useModelsSelector((snapshot) => snapshot.error);
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const status = useModelsSelector((snapshot) => snapshot.status);
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  const supportedModels = useMemo<GenerateModelConfig[]>(() => models.filter(isSupportedGenerateModel), [models]);
+  const loraModels = useMemo(
+    () => models.filter((model): model is ModelConfig & LoraModelConfig => isLoraModelConfig(model)),
+    [models]
+  );
+  const vaeModels = useMemo(
+    () => models.filter((model): model is ModelConfig & VaeModelConfig => model.type === 'vae'),
+    [models]
+  );
+  const normalizedSettings = normalizeGenerateSettings(storedValues);
+  const selectedModel = supportedModels.find((model) => model.key === normalizedSettings?.modelKey);
+  const settings = normalizedSettings ?? getDefaultGenerateSettings(selectedModel ?? supportedModels[0]);
+
+  useEffect(() => {
+    const model = selectedModel ?? supportedModels[0];
+
+    if (!model) {
+      return;
+    }
+
+    const storedWidgetValues = normalizeGenerateWidgetValues(storedValues);
+    const syncedWidgetValues = storedWidgetValues
+      ? syncGenerateWidgetValuesWithModels(storedWidgetValues, models)
+      : null;
+    const baseSettings = syncedWidgetValues ?? (selectedModel ? settings : getDefaultGenerateSettings(model));
+    const nextSettings = getSettingsWithAutoComponentSource(baseSettings, model, models);
+
+    if (
+      storedWidgetValues &&
+      storedWidgetValues.model.key === model.key &&
+      syncedWidgetValues === storedWidgetValues &&
+      nextSettings === baseSettings
+    ) {
+      return;
+    }
+
+    dispatch({
+      projectId,
+      type: 'patchGenerateSettings',
+      values: getGenerateFormCommitPatch({ ...nextSettings, model }),
+    });
+  }, [dispatch, models, projectId, selectedModel, settings, storedValues, supportedModels]);
+
+  const commitSettings = useCallback(
+    (nextSettings: GenerateSettings) => {
+      const model = supportedModels.find((candidate) => candidate.key === nextSettings.modelKey);
+
+      if (!model) {
+        return;
+      }
+
+      dispatch({
+        projectId,
+        type: 'patchGenerateSettings',
+        values: getGenerateFormCommitPatch({
+          ...getSettingsWithAutoComponentSource(nextSettings, model, models),
+          model,
+        }),
+      });
+    },
+    [dispatch, models, projectId, supportedModels]
+  );
+
+  const patchSettings = useCallback(
+    (values: Partial<GenerateSettings>) => {
+      dispatch({ projectId, type: 'patchGenerateSettings', values });
+    },
+    [dispatch, projectId]
+  );
+
+  return (
+    <GenerateSettingsForm
+      isLoadingModels={status === 'idle' || status === 'loading'}
+      loadError={error}
+      loraModels={loraModels}
+      models={models}
+      projectId={projectId}
+      selectedModel={selectedModel}
+      settings={settings}
+      supportedModels={supportedModels}
+      vaeModels={vaeModels}
+      onCommitSettings={commitSettings}
+      onPatchSettings={patchSettings}
+    />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/generateDebounce.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateDebounce.ts
new file mode 100644
index 00000000000..7c492804ef5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateDebounce.ts
@@ -0,0 +1,53 @@
+import type { GenerateSettings } from '@workbench/generation/types';
+
+export type GenerateSettingsUpdate = Partial<GenerateSettings> | ((settings: GenerateSettings) => GenerateSettings);
+
+export type PendingGenerateSettingsUpdate = ((settings: GenerateSettings) => GenerateSettings) | null;
+
+export const applyGenerateSettingsPatch = (
+  settings: GenerateSettings,
+  patch: Partial<GenerateSettings> | null
+): GenerateSettings => (patch ? { ...settings, ...patch } : settings);
+
+const getGenerateSettingsUpdater = (
+  update: GenerateSettingsUpdate
+): ((settings: GenerateSettings) => GenerateSettings) => {
+  if (typeof update === 'function') {
+    return update;
+  }
+
+  return (settings) => applyGenerateSettingsPatch(settings, update);
+};
+
+export const mergeGenerateSettingsUpdate = (
+  pendingUpdate: PendingGenerateSettingsUpdate,
+  update: GenerateSettingsUpdate
+): PendingGenerateSettingsUpdate => {
+  const updater = getGenerateSettingsUpdater(update);
+
+  if (!pendingUpdate) {
+    return updater;
+  }
+
+  return (settings) => updater(pendingUpdate(settings));
+};
+
+export const applyGenerateSettingsUpdate = (
+  settings: GenerateSettings,
+  update: PendingGenerateSettingsUpdate
+): GenerateSettings => (update ? update(settings) : settings);
+
+export const getChangedGenerateSettingsPatch = (
+  current: GenerateSettings,
+  next: GenerateSettings
+): Partial<GenerateSettings> => {
+  const patch: Partial<GenerateSettings> = {};
+
+  for (const key of Object.keys(next) as Array<keyof GenerateSettings>) {
+    if (!Object.is(current[key], next[key])) {
+      patch[key] = next[key] as never;
+    }
+  }
+
+  return patch;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/generateDraftRegistry.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateDraftRegistry.ts
new file mode 100644
index 00000000000..c837efc6988
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateDraftRegistry.ts
@@ -0,0 +1,27 @@
+import { useEffect, useEffectEvent } from 'react';
+
+type DraftFlusher = () => void;
+
+const draftFlushers = new Set<DraftFlusher>();
+
+export const flushGenerateDrafts = (): void => {
+  const flushers = Array.from(draftFlushers);
+
+  for (const flushDraft of flushers) {
+    flushDraft();
+  }
+};
+
+export const useRegisterGenerateDraftFlusher = (flushDraft: DraftFlusher): void => {
+  const flushLatestDraft = useEffectEvent(flushDraft);
+
+  useEffect(() => {
+    const registeredFlushDraft = () => flushLatestDraft();
+
+    draftFlushers.add(registeredFlushDraft);
+
+    return () => {
+      draftFlushers.delete(registeredFlushDraft);
+    };
+  }, []);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/generateFormViewModel.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateFormViewModel.test.ts
new file mode 100644
index 00000000000..d54754930bc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateFormViewModel.test.ts
@@ -0,0 +1,114 @@
+import type { GenerateSettings } from '@workbench/generation/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  areGenerateFormValuesEqual,
+  areProjectGenerateFormValuesEqual,
+  getGenerateFormCommitPatch,
+  getSettingsWithLatestPromptFields,
+} from './generateFormViewModel';
+
+const createSettings = (overrides: Partial<GenerateSettings> = {}): GenerateSettings =>
+  ({
+    aspectRatioId: '1:1',
+    aspectRatioIsLocked: false,
+    aspectRatioValue: 1,
+    batchCount: 1,
+    cfgRescaleMultiplier: 0,
+    cfgScale: 7,
+    clipEmbedModel: null,
+    clipGEmbedModel: null,
+    clipLEmbedModel: null,
+    clipSkip: 0,
+    colorCompensation: false,
+    componentSourceModel: null,
+    height: 1024,
+    loras: [],
+    modelKey: 'model-a',
+    negativePrompt: 'old negative',
+    negativePromptEnabled: true,
+    negativePromptHeightPx: 56,
+    positivePrompt: 'old positive',
+    positivePromptHeightPx: 96,
+    qwen3EncoderModel: null,
+    qwenVLEncoderModel: null,
+    scheduler: 'euler_a',
+    seamlessXAxis: false,
+    seamlessYAxis: false,
+    seed: 123,
+    shouldRandomizeSeed: false,
+    steps: 30,
+    t5EncoderModel: null,
+    vae: null,
+    vaePrecision: 'fp32',
+    width: 1024,
+    ...overrides,
+  }) as GenerateSettings;
+
+describe('getSettingsWithLatestPromptFields', () => {
+  it('preserves latest prompt fields when committing a full settings object', () => {
+    const staleFullSettings = createSettings({ cfgScale: 9, modelKey: 'model-b', positivePrompt: 'stale positive' });
+    const latestSettings = createSettings({
+      negativePrompt: 'latest negative',
+      negativePromptEnabled: false,
+      negativePromptHeightPx: 72,
+      positivePrompt: 'latest positive',
+      positivePromptHeightPx: 144,
+    });
+
+    expect(getSettingsWithLatestPromptFields(staleFullSettings, latestSettings)).toMatchObject({
+      cfgScale: 9,
+      modelKey: 'model-b',
+      negativePrompt: 'latest negative',
+      negativePromptEnabled: false,
+      negativePromptHeightPx: 72,
+      positivePrompt: 'latest positive',
+      positivePromptHeightPx: 144,
+    });
+  });
+});
+
+describe('areGenerateFormValuesEqual', () => {
+  it('ignores values owned by prompt fields and topbar batch count', () => {
+    expect(
+      areGenerateFormValuesEqual(
+        { batchCount: 1, positivePrompt: 'first', steps: 30 },
+        { batchCount: 4, positivePrompt: 'second', steps: 30 }
+      )
+    ).toBe(true);
+  });
+
+  it('detects changes rendered by the form', () => {
+    expect(areGenerateFormValuesEqual({ batchCount: 1, steps: 30 }, { batchCount: 1, steps: 40 })).toBe(false);
+  });
+});
+
+describe('areProjectGenerateFormValuesEqual', () => {
+  it('treats a project switch as a value change even when only ignored form fields differ', () => {
+    expect(
+      areProjectGenerateFormValuesEqual(
+        { projectId: 'project-a', values: { positivePrompt: 'project a', steps: 30 } },
+        { projectId: 'project-b', values: { positivePrompt: 'project b', steps: 30 } }
+      )
+    ).toBe(false);
+  });
+
+  it('still ignores prompt-owned and topbar-owned values within the same project', () => {
+    expect(
+      areProjectGenerateFormValuesEqual(
+        { projectId: 'project-a', values: { batchCount: 1, positivePrompt: 'first', steps: 30 } },
+        { projectId: 'project-a', values: { batchCount: 4, positivePrompt: 'second', steps: 30 } }
+      )
+    ).toBe(true);
+  });
+});
+
+describe('getGenerateFormCommitPatch', () => {
+  it('omits topbar-owned batch count from full form commits', () => {
+    const patch = getGenerateFormCommitPatch(createSettings({ batchCount: 8, positivePrompt: 'keep prompt' }));
+
+    expect(patch.batchCount).toBeUndefined();
+    expect(patch.positivePrompt).toBe('keep prompt');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/generateFormViewModel.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateFormViewModel.ts
new file mode 100644
index 00000000000..ea858e4b816
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/generateFormViewModel.ts
@@ -0,0 +1,74 @@
+import type { GenerateSettings, GenerateWidgetValues } from '@workbench/generation/types';
+
+import { createStableSelector } from '@workbench/workbenchSelectors';
+
+const PROMPT_FORM_KEYS = [
+  'negativePrompt',
+  'negativePromptEnabled',
+  'negativePromptHeightPx',
+  'positivePrompt',
+  'positivePromptHeightPx',
+] as const satisfies readonly (keyof GenerateSettings)[];
+const EXTERNAL_GENERATE_FORM_KEYS = [
+  ...PROMPT_FORM_KEYS,
+  'batchCount',
+] as const satisfies readonly (keyof GenerateSettings)[];
+const EXTERNAL_GENERATE_FORM_KEY_SET = new Set<string>(EXTERNAL_GENERATE_FORM_KEYS);
+
+export const areGenerateFormValuesEqual = (left: Record<string, unknown>, right: Record<string, unknown>): boolean => {
+  if (left === right) {
+    return true;
+  }
+
+  const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+
+  for (const key of keys) {
+    if (EXTERNAL_GENERATE_FORM_KEY_SET.has(key)) {
+      continue;
+    }
+
+    if (!Object.is(left[key], right[key])) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+export interface ProjectGenerateFormValuesSelection {
+  projectId: string;
+  values: Record<string, unknown>;
+}
+
+export const areProjectGenerateFormValuesEqual = (
+  left: ProjectGenerateFormValuesSelection,
+  right: ProjectGenerateFormValuesSelection
+): boolean => left.projectId === right.projectId && areGenerateFormValuesEqual(left.values, right.values);
+
+export const createGenerateFormValuesSelector = () =>
+  createStableSelector((values: Record<string, unknown>) => values, areGenerateFormValuesEqual);
+
+export const getSettingsWithLatestPromptFields = (
+  settings: GenerateSettings,
+  latestSettings: GenerateSettings
+): GenerateSettings => {
+  let nextSettings = settings;
+
+  for (const key of PROMPT_FORM_KEYS) {
+    if (!Object.is(nextSettings[key], latestSettings[key])) {
+      nextSettings = { ...nextSettings, [key]: latestSettings[key] };
+    }
+  }
+
+  return nextSettings;
+};
+
+export const getGenerateFormCommitPatch = (
+  settings: GenerateSettings & Partial<Pick<GenerateWidgetValues, 'model'>>
+): Partial<GenerateWidgetValues> => {
+  const patch: Partial<GenerateWidgetValues> = { ...settings };
+
+  delete patch.batchCount;
+
+  return patch;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/index.ts
new file mode 100644
index 00000000000..6d1b097965b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/index.ts
@@ -0,0 +1,17 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { SlidersHorizontalIcon } from 'lucide-react';
+
+import { GenerateWidgetView } from './GenerateWidgetView';
+
+export const generateWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['left'],
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  graphBearing: { defaultGraphId: 'generate-graph', sourceId: 'generate', surfaces: ['left'] },
+  icon: SlidersHorizontalIcon,
+  id: 'generate',
+  label: (t) => t('widgets.labels.generate'),
+  version: 1,
+  view: GenerateWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/GeneratePromptFields.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/GeneratePromptFields.tsx
new file mode 100644
index 00000000000..b5b76c23357
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/GeneratePromptFields.tsx
@@ -0,0 +1,118 @@
+import type { GenerateModelConfig, GenerateSettings } from '@workbench/generation/types';
+import type { PromptHistoryItem } from '@workbench/types';
+
+import { Stack } from '@chakra-ui/react';
+import { getPromptPolicy } from '@workbench/generation/baseGenerationPolicies';
+import { useActiveProjectSelector, useWidgetValuesSelector } from '@workbench/WorkbenchContext';
+import { useCallback } from 'react';
+
+import { NegativePromptField } from './NegativePromptField';
+import { PositivePromptField } from './PositivePromptField';
+
+interface GeneratePromptFieldsProps {
+  settings: GenerateSettings;
+  projectId: string;
+  selectedModel: GenerateModelConfig | undefined;
+  onCommit: (patch: Partial<GenerateSettings>) => void;
+  onCommitImmediate: (patch: Partial<GenerateSettings>) => void;
+}
+
+interface GeneratePromptValues {
+  negativePrompt: string;
+  negativePromptEnabled: boolean;
+  negativePromptHeightPx: number;
+  positivePrompt: string;
+  positivePromptHeightPx: number;
+}
+
+const getPromptValues = (values: Record<string, unknown>): GeneratePromptValues => ({
+  negativePrompt: typeof values.negativePrompt === 'string' ? values.negativePrompt : '',
+  negativePromptEnabled: values.negativePromptEnabled !== false,
+  negativePromptHeightPx: typeof values.negativePromptHeightPx === 'number' ? values.negativePromptHeightPx : 56,
+  positivePrompt: typeof values.positivePrompt === 'string' ? values.positivePrompt : '',
+  positivePromptHeightPx: typeof values.positivePromptHeightPx === 'number' ? values.positivePromptHeightPx : 96,
+});
+
+const arePromptValuesEqual = (left: GeneratePromptValues, right: GeneratePromptValues): boolean =>
+  left.positivePrompt === right.positivePrompt &&
+  left.negativePrompt === right.negativePrompt &&
+  left.positivePromptHeightPx === right.positivePromptHeightPx &&
+  left.negativePromptHeightPx === right.negativePromptHeightPx &&
+  left.negativePromptEnabled === right.negativePromptEnabled;
+
+export const GeneratePromptFields = ({
+  onCommit,
+  onCommitImmediate,
+  projectId,
+  selectedModel,
+  settings,
+}: GeneratePromptFieldsProps) => {
+  const showSyntaxHighlighting = useActiveProjectSelector((project) => project.settings.showPromptSyntaxHighlighting);
+  const promptValues = useWidgetValuesSelector('generate', getPromptValues, arePromptValuesEqual);
+  const promptPolicy = getPromptPolicy(selectedModel, settings);
+
+  const usePromptHistoryItem = useCallback(
+    (prompt: PromptHistoryItem) => {
+      onCommitImmediate(
+        promptPolicy.negativeVisible
+          ? {
+              negativePrompt: prompt.negativePrompt ?? '',
+              negativePromptEnabled: prompt.negativePrompt ? true : promptValues.negativePromptEnabled,
+              positivePrompt: prompt.positivePrompt,
+            }
+          : { positivePrompt: prompt.positivePrompt }
+      );
+    },
+    [onCommitImmediate, promptPolicy.negativeVisible, promptValues.negativePromptEnabled]
+  );
+
+  const handlePositivePromptChange = useCallback((positivePrompt: string) => onCommit({ positivePrompt }), [onCommit]);
+
+  const handlePositivePromptResizeEnd = useCallback(
+    (positivePromptHeightPx: number) => onCommitImmediate({ positivePromptHeightPx }),
+    [onCommitImmediate]
+  );
+
+  const handleNegativePromptEnabledChange = useCallback(
+    (negativePromptEnabled: boolean) => onCommitImmediate({ negativePromptEnabled }),
+    [onCommitImmediate]
+  );
+
+  const handleNegativePromptChange = useCallback((negativePrompt: string) => onCommit({ negativePrompt }), [onCommit]);
+
+  const handleNegativePromptResizeEnd = useCallback(
+    (negativePromptHeightPx: number) => onCommitImmediate({ negativePromptHeightPx }),
+    [onCommitImmediate]
+  );
+
+  return (
+    <Stack gap="1" py="2">
+      <PositivePromptField
+        heightPx={promptValues.positivePromptHeightPx}
+        value={promptValues.positivePrompt}
+        loras={settings.loras}
+        projectId={projectId}
+        selectedModel={selectedModel}
+        showSyntaxHighlighting={showSyntaxHighlighting}
+        onChange={handlePositivePromptChange}
+        onResizeEnd={handlePositivePromptResizeEnd}
+        onUsePrompt={usePromptHistoryItem}
+      />
+      {promptPolicy.negativeVisible ? (
+        <NegativePromptField
+          heightPx={promptValues.negativePromptHeightPx}
+          isEnabled={promptValues.negativePromptEnabled}
+          loras={settings.loras}
+          projectId={projectId}
+          selectedModel={selectedModel}
+          helpText={promptPolicy.negativeHelpText}
+          showSyntaxHighlighting={showSyntaxHighlighting}
+          value={promptValues.negativePrompt}
+          onEnabledChange={handleNegativePromptEnabledChange}
+          onChange={handleNegativePromptChange}
+          onResizeEnd={handleNegativePromptResizeEnd}
+        />
+      ) : null}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/NegativePromptField.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/NegativePromptField.tsx
new file mode 100644
index 00000000000..8f3ce68494b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/NegativePromptField.tsx
@@ -0,0 +1,191 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop */
+import type { GenerateLora, GenerateModelConfig } from '@workbench/generation/types';
+import type { ChangeEvent, KeyboardEvent } from 'react';
+
+import { HStack, Switch } from '@chakra-ui/react';
+import { Field } from '@workbench/components/ui';
+import { useRegisterGenerateDraftFlusher } from '@workbench/widgets/generate/generateDraftRegistry';
+import { useDebouncedDraftValue } from '@workbench/widgets/generate/useDebouncedDraftValue';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { AddPromptTriggerButton, PromptTriggerPopover } from './PositivePromptActions';
+import { PROMPT_ATTENTION_TARGET_PROPS } from './promptAttentionHotkeys';
+import { insertPromptText, type PromptTextRange } from './promptFocus';
+import { resetPromptHistoryNavigation } from './promptHistoryNavigation';
+import { PromptTextarea } from './PromptTextarea';
+
+const PROMPT_INPUT_DEBOUNCE_MS = 250;
+
+interface NegativePromptFieldProps {
+  heightPx: number;
+  helpText?: string;
+  isEnabled: boolean;
+  loras: GenerateLora[];
+  projectId: string;
+  selectedModel: GenerateModelConfig | undefined;
+  showSyntaxHighlighting: boolean;
+  value: string;
+  onChange: (value: string) => void;
+  onEnabledChange: (isEnabled: boolean) => void;
+  onResizeEnd: (heightPx: number) => void;
+}
+
+type PromptTriggerPickerState = {
+  anchorRect: { height: number; width: number; x: number; y: number };
+  range?: PromptTextRange;
+};
+
+export const NegativePromptField = ({
+  heightPx,
+  helpText,
+  isEnabled,
+  loras,
+  onChange,
+  onEnabledChange,
+  onResizeEnd,
+  projectId,
+  selectedModel,
+  showSyntaxHighlighting,
+  value,
+}: NegativePromptFieldProps) => {
+  const { t } = useTranslation();
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+  const [triggerPickerState, setTriggerPickerState] = useState<PromptTriggerPickerState | null>(null);
+  const { draftValue, flushDraftValue, setDraftValue } = useDebouncedDraftValue({
+    delayMs: PROMPT_INPUT_DEBOUNCE_MS,
+    onCommit: onChange,
+    resetKey: projectId,
+    value,
+  });
+
+  useRegisterGenerateDraftFlusher(flushDraftValue);
+
+  const commitPromptChange = useCallback(
+    (nextValue: string) => {
+      resetPromptHistoryNavigation();
+      setDraftValue(nextValue);
+    },
+    [setDraftValue]
+  );
+
+  const openPromptTriggerPicker = useCallback((anchorElement: HTMLElement, range?: PromptTextRange) => {
+    const rect = anchorElement.getBoundingClientRect();
+
+    setTriggerPickerState({
+      anchorRect: { height: rect.height, width: rect.width, x: rect.x, y: rect.y },
+      range,
+    });
+  }, []);
+
+  const handlePromptKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>) => {
+      if (event.key !== '<' || event.altKey || event.ctrlKey || event.metaKey) {
+        return;
+      }
+
+      event.preventDefault();
+      openPromptTriggerPicker(event.currentTarget, {
+        end: event.currentTarget.selectionEnd,
+        start: event.currentTarget.selectionStart,
+      });
+    },
+    [openPromptTriggerPicker]
+  );
+
+  const closePromptTriggerPicker = useCallback(() => setTriggerPickerState(null), []);
+
+  const selectPromptTrigger = useCallback(
+    (trigger: string) => {
+      insertPromptText({
+        onChange: commitPromptChange,
+        range: triggerPickerState?.range,
+        textarea: textareaRef.current,
+        text: trigger,
+        value: draftValue,
+      });
+      closePromptTriggerPicker();
+    },
+    [closePromptTriggerPicker, commitPromptChange, draftValue, triggerPickerState?.range]
+  );
+
+  const handleOpenPromptTriggerPicker = useCallback(
+    (anchorElement: HTMLElement) => openPromptTriggerPicker(anchorElement),
+    [openPromptTriggerPicker]
+  );
+
+  const handleEnabledChange = useCallback(
+    (event: { checked: boolean }) => onEnabledChange(event.checked),
+    [onEnabledChange]
+  );
+
+  const handleTextareaRef = useCallback((element: HTMLTextAreaElement | null) => {
+    textareaRef.current = element;
+  }, []);
+
+  const handlePromptChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => commitPromptChange(event.currentTarget.value),
+    [commitPromptChange]
+  );
+
+  const labelEnd = useMemo(
+    () => (
+      <HStack gap="0.5">
+        {isEnabled ? (
+          <AddPromptTriggerButton
+            isOpen={triggerPickerState !== null}
+            onOpenPromptTriggerPicker={handleOpenPromptTriggerPicker}
+          />
+        ) : null}
+        <Switch.Root checked={isEnabled} size="sm" onCheckedChange={handleEnabledChange}>
+          <Switch.HiddenInput />
+          <Switch.Control _checked={{ bg: 'accent.solid' }}>
+            <Switch.Thumb />
+          </Switch.Control>
+          <Switch.Label srOnly>{t('widgets.generate.enableNegativePrompt')}</Switch.Label>
+        </Switch.Root>
+      </HStack>
+    ),
+    [handleEnabledChange, handleOpenPromptTriggerPicker, isEnabled, t, triggerPickerState]
+  );
+
+  const triggerPickerPositioning = useMemo(
+    () => ({ getAnchorRect: () => triggerPickerState?.anchorRect ?? null }),
+    [triggerPickerState]
+  );
+
+  return (
+    <Field label={t('widgets.generate.negativePrompt')} labelEnd={labelEnd} helpText={isEnabled ? helpText : undefined}>
+      {isEnabled ? (
+        <>
+          <PromptTextarea
+            {...PROMPT_ATTENTION_TARGET_PROPS}
+            aria-label={t('widgets.generate.negativePrompt')}
+            defaultHeightPx={heightPx}
+            maxHeightPx={240}
+            minHeightPx={56}
+            resizeHandleAriaLabel={t('widgets.generate.resizeNegativePrompt')}
+            size="xs"
+            fontFamily="mono"
+            showSyntaxHighlighting={showSyntaxHighlighting}
+            textareaRef={handleTextareaRef}
+            value={draftValue}
+            onChange={handlePromptChange}
+            onKeyDown={handlePromptKeyDown}
+            onResizeEnd={onResizeEnd}
+          />
+          {triggerPickerState ? (
+            <PromptTriggerPopover
+              loras={loras}
+              open
+              positioning={triggerPickerPositioning}
+              selectedModel={selectedModel}
+              onClose={closePromptTriggerPicker}
+              onSelect={selectPromptTrigger}
+            />
+          ) : null}
+        </>
+      ) : null}
+    </Field>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PositivePromptActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PositivePromptActions.tsx
new file mode 100644
index 00000000000..b611748f179
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PositivePromptActions.tsx
@@ -0,0 +1,759 @@
+/* eslint-disable react/react-compiler */
+import type { GenerateLora, GenerateModelConfig } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type { PromptHistoryItem } from '@workbench/types';
+import type { ChangeEvent, MouseEvent } from 'react';
+
+import { HStack, Icon, Image, Input, Popover, Portal, Separator, Stack, Text } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, IconButton, Scrollable, Tooltip } from '@workbench/components/ui';
+import { filterPromptHistory } from '@workbench/generation/promptHistory';
+import { expandPrompt, imageToPrompt } from '@workbench/generation/promptUtilities';
+import { getSelectedGalleryImage } from '@workbench/image-actions';
+import { ModelSelect } from '@workbench/models/components/ModelSelect';
+import { ensureModelsLoaded, useModelsSelector } from '@workbench/models/modelsStore';
+import {
+  shallowEqual,
+  useActiveProjectId,
+  useActiveProjectSelector,
+  useWorkbenchDispatch,
+} from '@workbench/WorkbenchContext';
+import {
+  BookDashedIcon,
+  CurlyBracesIcon,
+  HistoryIcon,
+  ImageUpIcon,
+  PlusIcon,
+  SparklesIcon,
+  TrashIcon,
+  Undo2Icon,
+} from 'lucide-react';
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const DISABLED_PROMPT_ACTIONS = [
+  { icon: BookDashedIcon, labelKey: 'widgets.generate.promptTemplate' },
+  { icon: CurlyBracesIcon, labelKey: 'widgets.generate.showDynamicPrompts' },
+];
+const POPOVER_POSITIONING_BOTTOM_END = { placement: 'bottom-end' } as const;
+const TEXT_LLM_MODEL_TYPES = ['text_llm'];
+const LLAVA_MODEL_TYPES = ['llava_onevision'];
+
+interface PositivePromptActionsProps {
+  loras: GenerateLora[];
+  isPromptTriggerPickerOpen: boolean;
+  onUsePrompt: (prompt: PromptHistoryItem) => void;
+  positivePrompt: string;
+  selectedModel: GenerateModelConfig | undefined;
+  projectId: string;
+  onOpenPromptTriggerPicker: (anchorElement: HTMLElement) => void;
+  onPositivePromptChangeImmediate: (prompt: string) => void;
+}
+
+export const PositivePromptActions = ({
+  isPromptTriggerPickerOpen,
+  onOpenPromptTriggerPicker,
+  onPositivePromptChangeImmediate,
+  onUsePrompt,
+  positivePrompt,
+  projectId,
+}: PositivePromptActionsProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <HStack gap="0.5">
+      <AddPromptTriggerButton
+        isOpen={isPromptTriggerPickerOpen}
+        onOpenPromptTriggerPicker={onOpenPromptTriggerPicker}
+      />
+      {DISABLED_PROMPT_ACTIONS.map(({ icon: ActionIcon, labelKey }) => (
+        <Tooltip key={labelKey} content={t(labelKey)}>
+          <IconButton aria-label={t(labelKey)} disabled size="2xs" variant="ghost">
+            <ActionIcon />
+          </IconButton>
+        </Tooltip>
+      ))}
+      <ExpandPromptButton
+        positivePrompt={positivePrompt}
+        projectId={projectId}
+        onPositivePromptChange={onPositivePromptChangeImmediate}
+      />
+      <ImageToPromptButton projectId={projectId} onPositivePromptChange={onPositivePromptChangeImmediate} />
+      <PositivePromptHistoryButton onUsePrompt={onUsePrompt} />
+    </HStack>
+  );
+};
+
+type PromptTriggerOption = {
+  group: string;
+  label: string;
+  value: string;
+};
+
+const getTriggerPhrases = (model: unknown): string[] => {
+  if (!model || typeof model !== 'object') {
+    return [];
+  }
+
+  const triggerPhrases = (model as { trigger_phrases?: unknown }).trigger_phrases;
+
+  return Array.isArray(triggerPhrases)
+    ? triggerPhrases.filter((phrase): phrase is string => typeof phrase === 'string' && phrase.trim().length > 0)
+    : [];
+};
+
+const getPromptTriggerOptions = ({
+  compatibleEmbeddingsLabel,
+  loras,
+  mainModelLabel,
+  models,
+  selectedModel,
+}: {
+  compatibleEmbeddingsLabel: string;
+  loras: GenerateLora[];
+  mainModelLabel: string;
+  models: readonly ModelConfig[];
+  selectedModel: GenerateModelConfig | undefined;
+}): PromptTriggerOption[] => {
+  const options: PromptTriggerOption[] = [];
+
+  for (const phrase of getTriggerPhrases(selectedModel)) {
+    options.push({ group: selectedModel?.name ?? mainModelLabel, label: phrase, value: phrase });
+  }
+
+  for (const lora of loras) {
+    if (!lora.isEnabled) {
+      continue;
+    }
+
+    for (const phrase of getTriggerPhrases(lora.model)) {
+      options.push({ group: lora.model.name, label: phrase, value: phrase });
+    }
+  }
+
+  if (selectedModel) {
+    for (const model of models) {
+      if (model.type === 'embedding' && model.base === selectedModel.base) {
+        options.push({ group: compatibleEmbeddingsLabel, label: model.name, value: `<${model.name}>` });
+      }
+    }
+  }
+
+  const seen = new Set<string>();
+
+  return options.filter((option) => {
+    const key = `${option.group}:${option.value}`;
+
+    if (seen.has(key)) {
+      return false;
+    }
+
+    seen.add(key);
+    return true;
+  });
+};
+
+export const AddPromptTriggerButton = ({
+  isOpen,
+  onOpenPromptTriggerPicker,
+}: {
+  isOpen: boolean;
+  onOpenPromptTriggerPicker: (anchorElement: HTMLElement) => void;
+}) => {
+  const { t } = useTranslation();
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLButtonElement>) => onOpenPromptTriggerPicker(event.currentTarget),
+    [onOpenPromptTriggerPicker]
+  );
+
+  return (
+    <Tooltip content={t('widgets.generate.addPromptTrigger')}>
+      <IconButton
+        aria-label={t('widgets.generate.addPromptTrigger')}
+        disabled={isOpen}
+        size="2xs"
+        variant="ghost"
+        onClick={handleClick}
+      >
+        <PlusIcon />
+      </IconButton>
+    </Tooltip>
+  );
+};
+
+export const PromptTriggerPopover = ({
+  loras,
+  onClose,
+  onSelect,
+  open,
+  positioning,
+  selectedModel,
+}: Pick<PositivePromptActionsProps, 'loras' | 'selectedModel'> & {
+  open: boolean;
+  positioning: { getAnchorRect: () => { height: number; width: number; x: number; y: number } | null };
+  onClose: () => void;
+  onSelect: (trigger: string) => void;
+}) => {
+  const { t } = useTranslation();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const [searchTerm, setSearchTerm] = useState('');
+
+  const options = useMemo(
+    () =>
+      getPromptTriggerOptions({
+        compatibleEmbeddingsLabel: t('widgets.generate.compatibleEmbeddings'),
+        loras,
+        mainModelLabel: t('widgets.generate.mainModel'),
+        models,
+        selectedModel,
+      }),
+    [loras, models, selectedModel, t]
+  );
+
+  const filteredOptions = useMemo(
+    () =>
+      options.filter((option) => {
+        const query = searchTerm.trim().toLowerCase();
+
+        return !query || option.label.toLowerCase().includes(query) || option.group.toLowerCase().includes(query);
+      }),
+    [options, searchTerm]
+  );
+
+  const groupedOptions = useMemo(
+    () =>
+      filteredOptions.reduce<Array<{ group: string; options: PromptTriggerOption[] }>>((groups, option) => {
+        const existingGroup = groups.find((group) => group.group === option.group);
+
+        if (existingGroup) {
+          existingGroup.options.push(option);
+        } else {
+          groups.push({ group: option.group, options: [option] });
+        }
+
+        return groups;
+      }, []),
+    [filteredOptions]
+  );
+
+  const popoverPositioning = useMemo(() => ({ ...positioning, placement: 'bottom-start' as const }), [positioning]);
+
+  const handleOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (event.open) {
+        setSearchTerm('');
+      } else {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  const handleSearchChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
+    setSearchTerm(event.currentTarget.value);
+  }, []);
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  return (
+    <Popover.Root lazyMount open={open} positioning={popoverPositioning} unmountOnExit onOpenChange={handleOpenChange}>
+      <Portal>
+        <Popover.Positioner>
+          <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="22rem">
+            <Popover.Body p="2.5">
+              <Stack gap="2" h="18rem">
+                <Input
+                  aria-label={t('widgets.generate.searchPromptTriggers')}
+                  disabled={options.length === 0}
+                  placeholder={t('widgets.generate.searchPromptTriggers')}
+                  size="xs"
+                  value={searchTerm}
+                  onChange={handleSearchChange}
+                />
+                <Separator />
+                <Scrollable flex="1" label={t('widgets.generate.promptTriggerOptions')} minH="0">
+                  {options.length === 0 ? (
+                    <PromptHistoryEmptyText>{t('widgets.generate.noPromptTriggersAvailable')}</PromptHistoryEmptyText>
+                  ) : filteredOptions.length === 0 ? (
+                    <PromptHistoryEmptyText>{t('widgets.generate.noMatchingTriggers')}</PromptHistoryEmptyText>
+                  ) : (
+                    <Stack gap="2">
+                      {groupedOptions.map((group) => (
+                        <Stack key={group.group} gap="0">
+                          <Text color="fg.subtle" fontSize="2xs" fontWeight="700" px="2" textTransform="uppercase">
+                            {group.group}
+                          </Text>
+                          {group.options.map((option, index) => (
+                            <PromptTriggerOptionButton
+                              key={`${option.group}-${option.value}-${index}`}
+                              onSelect={onSelect}
+                              option={option}
+                            />
+                          ))}
+                        </Stack>
+                      ))}
+                    </Stack>
+                  )}
+                </Scrollable>
+              </Stack>
+            </Popover.Body>
+          </Popover.Content>
+        </Popover.Positioner>
+      </Portal>
+    </Popover.Root>
+  );
+};
+
+const PromptTriggerOptionButton = ({
+  onSelect,
+  option,
+}: {
+  onSelect: (trigger: string) => void;
+  option: PromptTriggerOption;
+}) => {
+  const handleClick = useCallback(() => onSelect(option.value), [onSelect, option.value]);
+
+  return (
+    <Button
+      alignItems="start"
+      h="auto"
+      justifyContent="start"
+      px="2"
+      py="1.5"
+      size="xs"
+      transitionDuration="faster"
+      variant="ghost"
+      onClick={handleClick}
+    >
+      <Text color="fg" fontSize="xs" textAlign="start" wordBreak="break-word">
+        {option.label}
+      </Text>
+    </Button>
+  );
+};
+
+const ExpandPromptButton = ({
+  onPositivePromptChange,
+  positivePrompt,
+  projectId,
+}: {
+  positivePrompt: string;
+  projectId: string;
+  onPositivePromptChange: (prompt: string) => void;
+}) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const activeProjectId = useActiveProjectId();
+  const activeProjectIdRef = useRef(activeProjectId);
+  const triggerId = useId();
+  const [isOpen, setIsOpen] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [selectedModelKey, setSelectedModelKey] = useState<string | null>(null);
+  const textLlmModels = models.filter((model) => model.type === 'text_llm');
+  const selectedModel = selectedModelKey ? textLlmModels.find((model) => model.key === selectedModelKey) : null;
+
+  activeProjectIdRef.current = activeProjectId;
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  const runExpandPrompt = useCallback(async () => {
+    if (!selectedModel || !positivePrompt.trim()) {
+      return;
+    }
+
+    setIsLoading(true);
+
+    try {
+      const result = await expandPrompt({ model_key: selectedModel.key, prompt: positivePrompt });
+
+      if (result.expanded_prompt && activeProjectIdRef.current === projectId) {
+        onPositivePromptChange(result.expanded_prompt);
+      }
+
+      setIsOpen(false);
+    } catch (error) {
+      dispatch({
+        area: 'expand-prompt',
+        message: getApiErrorMessage(error, t('widgets.generate.couldNotExpandPrompt')),
+        namespace: 'generation',
+        projectId,
+        type: 'recordError',
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [dispatch, onPositivePromptChange, positivePrompt, projectId, selectedModel, t]);
+
+  const popoverIds = useMemo(() => ({ trigger: triggerId }), [triggerId]);
+  const handleOpenChange = useCallback((event: { open: boolean }) => setIsOpen(event.open), []);
+  const handleModelChange = useCallback((model: ModelConfig | null) => setSelectedModelKey(model?.key ?? null), []);
+  const handleRunExpandPrompt = useCallback(() => void runExpandPrompt(), [runExpandPrompt]);
+
+  return (
+    <Popover.Root
+      ids={popoverIds}
+      lazyMount
+      open={isOpen}
+      positioning={POPOVER_POSITIONING_BOTTOM_END}
+      onOpenChange={handleOpenChange}
+    >
+      <Tooltip
+        content={
+          textLlmModels.length === 0 ? t('widgets.generate.noTextLlmInstalled') : t('widgets.generate.expandPrompt')
+        }
+        ids={popoverIds}
+      >
+        <Popover.Trigger asChild>
+          <IconButton
+            aria-label={t('widgets.generate.expandPrompt')}
+            disabled={isLoading || !positivePrompt.trim()}
+            size="2xs"
+            variant="ghost"
+          >
+            <SparklesIcon />
+          </IconButton>
+        </Popover.Trigger>
+      </Tooltip>
+      <Portal>
+        <Popover.Positioner>
+          <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="22rem">
+            <Popover.Body p="2.5">
+              <Stack gap="2.5">
+                <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+                  {t('widgets.generate.expandPrompt')}
+                </Text>
+                {textLlmModels.length === 0 ? (
+                  <Text color="fg.subtle" fontSize="xs">
+                    {t('widgets.generate.installTextLlmToExpandPrompts')}
+                  </Text>
+                ) : (
+                  <>
+                    <ModelSelect
+                      isClearable={false}
+                      modelTypes={TEXT_LLM_MODEL_TYPES}
+                      placeholder={t('widgets.generate.selectTextLlm')}
+                      size="xs"
+                      value={selectedModelKey}
+                      onChange={handleModelChange}
+                    />
+                    <Button
+                      disabled={!selectedModel || !positivePrompt.trim()}
+                      loading={isLoading}
+                      size="xs"
+                      onClick={handleRunExpandPrompt}
+                    >
+                      {t('widgets.generate.expand')}
+                    </Button>
+                  </>
+                )}
+              </Stack>
+            </Popover.Body>
+          </Popover.Content>
+        </Popover.Positioner>
+      </Portal>
+    </Popover.Root>
+  );
+};
+
+const ImageToPromptButton = ({
+  onPositivePromptChange,
+  projectId,
+}: {
+  projectId: string;
+  onPositivePromptChange: (prompt: string) => void;
+}) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const selectedImage = useActiveProjectSelector(getSelectedGalleryImage, shallowEqual);
+  const activeProjectId = useActiveProjectId();
+  const activeProjectIdRef = useRef(activeProjectId);
+  const triggerId = useId();
+  const [isOpen, setIsOpen] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [selectedModelKey, setSelectedModelKey] = useState<string | null>(null);
+  const llavaModels = models.filter((model) => model.type === 'llava_onevision');
+  const selectedModel = selectedModelKey ? llavaModels.find((model) => model.key === selectedModelKey) : null;
+
+  activeProjectIdRef.current = activeProjectId;
+
+  useEffect(() => {
+    ensureModelsLoaded();
+  }, []);
+
+  const runImageToPrompt = useCallback(async () => {
+    if (!selectedImage || !selectedModel) {
+      return;
+    }
+
+    setIsLoading(true);
+
+    try {
+      const result = await imageToPrompt({ image_name: selectedImage.imageName, model_key: selectedModel.key });
+
+      if (result.prompt && activeProjectIdRef.current === projectId) {
+        onPositivePromptChange(result.prompt);
+      }
+
+      setIsOpen(false);
+    } catch (error) {
+      dispatch({
+        area: 'image-to-prompt',
+        message: getApiErrorMessage(error, t('widgets.generate.couldNotGeneratePromptFromImage')),
+        namespace: 'generation',
+        projectId,
+        type: 'recordError',
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [dispatch, onPositivePromptChange, projectId, selectedImage, selectedModel, t]);
+
+  const popoverIds = useMemo(() => ({ trigger: triggerId }), [triggerId]);
+  const handleOpenChange = useCallback((event: { open: boolean }) => setIsOpen(event.open), []);
+  const handleModelChange = useCallback((model: ModelConfig | null) => setSelectedModelKey(model?.key ?? null), []);
+  const handleRunImageToPrompt = useCallback(() => void runImageToPrompt(), [runImageToPrompt]);
+
+  return (
+    <Popover.Root
+      ids={popoverIds}
+      lazyMount
+      open={isOpen}
+      positioning={POPOVER_POSITIONING_BOTTOM_END}
+      onOpenChange={handleOpenChange}
+    >
+      <Tooltip
+        content={
+          llavaModels.length === 0 ? t('widgets.generate.noVisionModelInstalled') : t('widgets.generate.imageToPrompt')
+        }
+        ids={popoverIds}
+      >
+        <Popover.Trigger asChild>
+          <IconButton aria-label={t('widgets.generate.imageToPrompt')} disabled={isLoading} size="2xs" variant="ghost">
+            <ImageUpIcon />
+          </IconButton>
+        </Popover.Trigger>
+      </Tooltip>
+      <Portal>
+        <Popover.Positioner>
+          <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="22rem">
+            <Popover.Body p="2.5">
+              <Stack gap="2.5">
+                <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+                  {t('widgets.generate.imageToPrompt')}
+                </Text>
+                {llavaModels.length === 0 ? (
+                  <Text color="fg.subtle" fontSize="xs">
+                    {t('widgets.generate.installVisionModelToGeneratePrompts')}
+                  </Text>
+                ) : (
+                  <>
+                    <ModelSelect
+                      isClearable={false}
+                      modelTypes={LLAVA_MODEL_TYPES}
+                      placeholder={t('widgets.generate.selectVisionModel')}
+                      size="xs"
+                      value={selectedModelKey}
+                      onChange={handleModelChange}
+                    />
+                    {selectedImage ? (
+                      <HStack gap="2">
+                        <Image
+                          alt={selectedImage.imageName}
+                          boxSize="10"
+                          flexShrink="0"
+                          objectFit="cover"
+                          rounded="md"
+                          src={selectedImage.thumbnailUrl || selectedImage.imageUrl}
+                        />
+                        <Text color="fg.subtle" fontSize="xs" truncate>
+                          {selectedImage.imageName}
+                        </Text>
+                      </HStack>
+                    ) : (
+                      <Text color="fg.subtle" fontSize="xs">
+                        {t('widgets.generate.selectImageFirst')}
+                      </Text>
+                    )}
+                    <Button
+                      disabled={!selectedImage || !selectedModel}
+                      loading={isLoading}
+                      size="xs"
+                      onClick={handleRunImageToPrompt}
+                    >
+                      {t('widgets.generate.generatePrompt')}
+                    </Button>
+                  </>
+                )}
+              </Stack>
+            </Popover.Body>
+          </Popover.Content>
+        </Popover.Positioner>
+      </Portal>
+    </Popover.Root>
+  );
+};
+
+const PositivePromptHistoryButton = ({ onUsePrompt }: Pick<PositivePromptActionsProps, 'onUsePrompt'>) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const promptHistory = useActiveProjectSelector((project) => project.promptHistory);
+  const historyTriggerId = useId();
+  const [isOpen, setIsOpen] = useState(false);
+  const [searchTerm, setSearchTerm] = useState('');
+  const filteredPrompts = filterPromptHistory(promptHistory, searchTerm);
+  const popoverIds = useMemo(() => ({ trigger: historyTriggerId }), [historyTriggerId]);
+  const handleOpenChange = useCallback((event: { open: boolean }) => setIsOpen(event.open), []);
+
+  const onChangeSearchTerm = useCallback((event: ChangeEvent<HTMLInputElement>) => {
+    setSearchTerm(event.currentTarget.value);
+  }, []);
+
+  const usePrompt = useCallback(
+    (prompt: PromptHistoryItem) => {
+      onUsePrompt(prompt);
+      setIsOpen(false);
+    },
+    [onUsePrompt]
+  );
+
+  const clearPromptHistory = useCallback(() => dispatch({ type: 'clearPromptHistory' }), [dispatch]);
+
+  return (
+    <Popover.Root
+      ids={popoverIds}
+      lazyMount
+      open={isOpen}
+      positioning={POPOVER_POSITIONING_BOTTOM_END}
+      onOpenChange={handleOpenChange}
+    >
+      <Tooltip content={t('widgets.generate.promptHistory')} ids={popoverIds}>
+        <Popover.Trigger asChild>
+          <IconButton aria-label={t('widgets.generate.promptHistory')} size="2xs" variant="ghost">
+            <HistoryIcon />
+          </IconButton>
+        </Popover.Trigger>
+      </Tooltip>
+      <Portal>
+        <Popover.Positioner>
+          <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="24rem">
+            <Popover.Body p="2.5">
+              <Stack gap="2" h="18rem">
+                <HStack justify="space-between">
+                  <Input
+                    aria-label={t('widgets.generate.searchPromptHistory')}
+                    disabled={promptHistory.length === 0}
+                    placeholder={t('widgets.generate.searchPromptHistory')}
+                    size="xs"
+                    value={searchTerm}
+                    onChange={onChangeSearchTerm}
+                  />
+                  <Button disabled={promptHistory.length === 0} size="xs" variant="ghost" onClick={clearPromptHistory}>
+                    <Icon as={TrashIcon} boxSize="3" />
+                    {t('common.clear')}
+                  </Button>
+                </HStack>
+                <Separator />
+                <Scrollable flex="1" label={t('widgets.generate.promptHistoryEntries')} minH="0">
+                  {promptHistory.length === 0 ? (
+                    <PromptHistoryEmptyText>{t('widgets.generate.noPromptHistoryYet')}</PromptHistoryEmptyText>
+                  ) : filteredPrompts.length === 0 ? (
+                    <PromptHistoryEmptyText>{t('widgets.generate.noMatchingPrompts')}</PromptHistoryEmptyText>
+                  ) : (
+                    <Stack gap="1">
+                      {filteredPrompts.map((prompt, index) => (
+                        <PromptHistoryItemWithSeparator
+                          key={`${prompt.positivePrompt}-${prompt.negativePrompt ?? ''}-${index}`}
+                          prompt={prompt}
+                          onUsePrompt={usePrompt}
+                        />
+                      ))}
+                    </Stack>
+                  )}
+                </Scrollable>
+                <Text color="fg.subtle" fontSize="2xs" textAlign="center">
+                  {t('widgets.generate.promptHistoryKeyboardHelp')}
+                </Text>
+              </Stack>
+            </Popover.Body>
+          </Popover.Content>
+        </Popover.Positioner>
+      </Portal>
+    </Popover.Root>
+  );
+};
+
+const PromptHistoryItemWithSeparator = ({
+  onUsePrompt,
+  prompt,
+}: {
+  onUsePrompt: (prompt: PromptHistoryItem) => void;
+  prompt: PromptHistoryItem;
+}) => (
+  <>
+    <PromptHistoryItemRow prompt={prompt} onUsePrompt={onUsePrompt} />
+    <Separator />
+  </>
+);
+
+const PromptHistoryEmptyText = ({ children }: { children: string }) => (
+  <HStack h="full" justify="center" minH="9rem">
+    <Text color="fg.subtle" fontSize="xs">
+      {children}
+    </Text>
+  </HStack>
+);
+
+const PromptHistoryItemRow = ({
+  onUsePrompt,
+  prompt,
+}: {
+  onUsePrompt: (prompt: PromptHistoryItem) => void;
+  prompt: PromptHistoryItem;
+}) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const handleUsePrompt = useCallback(() => onUsePrompt(prompt), [onUsePrompt, prompt]);
+  const handleDelete = useCallback(() => dispatch({ prompt, type: 'removePromptFromHistory' }), [dispatch, prompt]);
+
+  return (
+    <HStack align="start" gap="1.5" pr="1">
+      <IconButton aria-label={t('widgets.generate.usePrompt')} size="2xs" variant="ghost" onClick={handleUsePrompt}>
+        <Icon as={Undo2Icon} boxSize="3.5" />
+      </IconButton>
+      <Stack flex="1" gap="0.5" minW="0">
+        {prompt.positivePrompt ? (
+          <Text color="fg" fontSize="2xs" wordBreak="break-word">
+            <Text as="span" color="fg.subtle" fontWeight="600">
+              {t('common.prompt')}:
+            </Text>{' '}
+            {prompt.positivePrompt}
+          </Text>
+        ) : null}
+        {prompt.negativePrompt ? (
+          <Text color="fg" fontSize="2xs" wordBreak="break-word">
+            <Text as="span" color="fg.subtle" fontWeight="600">
+              {t('common.negative')}:
+            </Text>{' '}
+            {prompt.negativePrompt}
+          </Text>
+        ) : null}
+      </Stack>
+
+      <IconButton
+        aria-label={t('widgets.generate.deletePromptHistoryItem')}
+        colorPalette="red"
+        size="2xs"
+        variant="ghost"
+        onClick={handleDelete}
+      >
+        <Icon as={TrashIcon} boxSize="3.5" />
+      </IconButton>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PositivePromptField.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PositivePromptField.tsx
new file mode 100644
index 00000000000..c1042bf2864
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PositivePromptField.tsx
@@ -0,0 +1,198 @@
+import type { GenerateLora, GenerateModelConfig } from '@workbench/generation/types';
+import type { PromptHistoryItem } from '@workbench/types';
+import type { ChangeEvent, KeyboardEvent } from 'react';
+
+import { Field } from '@workbench/components/ui';
+import { useRegisterGenerateDraftFlusher } from '@workbench/widgets/generate/generateDraftRegistry';
+import { useDebouncedDraftValue } from '@workbench/widgets/generate/useDebouncedDraftValue';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { PositivePromptActions, PromptTriggerPopover } from './PositivePromptActions';
+import { PROMPT_ATTENTION_TARGET_PROPS } from './promptAttentionHotkeys';
+import { insertPromptText, type PromptTextRange, registerPositivePromptElement } from './promptFocus';
+import { resetPromptHistoryNavigation } from './promptHistoryNavigation';
+import { PromptTextarea } from './PromptTextarea';
+
+const PROMPT_INPUT_DEBOUNCE_MS = 250;
+
+interface PositivePromptFieldProps {
+  heightPx: number;
+  loras: GenerateLora[];
+  projectId: string;
+  selectedModel: GenerateModelConfig | undefined;
+  showSyntaxHighlighting: boolean;
+  value: string;
+  onChange: (value: string) => void;
+  onResizeEnd: (heightPx: number) => void;
+  onUsePrompt: (prompt: PromptHistoryItem) => void;
+}
+
+type PromptTriggerPickerState = {
+  anchorRect: { height: number; width: number; x: number; y: number };
+  range?: PromptTextRange;
+};
+
+export const PositivePromptField = ({
+  heightPx,
+  loras,
+  onChange,
+  onResizeEnd,
+  onUsePrompt,
+  projectId,
+  selectedModel,
+  showSyntaxHighlighting,
+  value,
+}: PositivePromptFieldProps) => {
+  const { t } = useTranslation();
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+  const [triggerPickerState, setTriggerPickerState] = useState<PromptTriggerPickerState | null>(null);
+  const { commitDraftValue, draftValue, flushDraftValue, replaceDraftValue, setDraftValue } = useDebouncedDraftValue({
+    delayMs: PROMPT_INPUT_DEBOUNCE_MS,
+    onCommit: onChange,
+    resetKey: projectId,
+    value,
+  });
+
+  useRegisterGenerateDraftFlusher(flushDraftValue);
+
+  const commitPromptChange = useCallback(
+    (nextValue: string) => {
+      resetPromptHistoryNavigation();
+      setDraftValue(nextValue);
+    },
+    [setDraftValue]
+  );
+
+  const commitPromptChangeImmediately = useCallback(
+    (nextValue: string) => {
+      resetPromptHistoryNavigation();
+      commitDraftValue(nextValue);
+    },
+    [commitDraftValue]
+  );
+
+  const openPromptTriggerPicker = useCallback((anchorElement: HTMLElement, range?: PromptTextRange) => {
+    const rect = anchorElement.getBoundingClientRect();
+
+    setTriggerPickerState({
+      anchorRect: { height: rect.height, width: rect.width, x: rect.x, y: rect.y },
+      range,
+    });
+  }, []);
+
+  const handlePromptKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>) => {
+      if (event.key !== '<' || event.altKey || event.ctrlKey || event.metaKey) {
+        return;
+      }
+
+      event.preventDefault();
+      openPromptTriggerPicker(event.currentTarget, {
+        end: event.currentTarget.selectionEnd,
+        start: event.currentTarget.selectionStart,
+      });
+    },
+    [openPromptTriggerPicker]
+  );
+
+  const closePromptTriggerPicker = useCallback(() => setTriggerPickerState(null), []);
+
+  const selectPromptTrigger = useCallback(
+    (trigger: string) => {
+      insertPromptText({
+        onChange: commitPromptChange,
+        range: triggerPickerState?.range,
+        textarea: textareaRef.current,
+        text: trigger,
+        value: draftValue,
+      });
+      closePromptTriggerPicker();
+    },
+    [closePromptTriggerPicker, commitPromptChange, draftValue, triggerPickerState?.range]
+  );
+
+  const handleUsePrompt = useCallback(
+    (prompt: PromptHistoryItem) => {
+      replaceDraftValue(prompt.positivePrompt);
+      onUsePrompt(prompt);
+    },
+    [onUsePrompt, replaceDraftValue]
+  );
+
+  const handleTextareaRef = useCallback((element: HTMLTextAreaElement | null) => {
+    textareaRef.current = element;
+    registerPositivePromptElement(element);
+  }, []);
+
+  const handleOpenPromptTriggerPicker = useCallback(
+    (anchorElement: HTMLElement) => openPromptTriggerPicker(anchorElement),
+    [openPromptTriggerPicker]
+  );
+
+  const labelEnd = useMemo(
+    () => (
+      <PositivePromptActions
+        isPromptTriggerPickerOpen={triggerPickerState !== null}
+        loras={loras}
+        positivePrompt={draftValue}
+        projectId={projectId}
+        selectedModel={selectedModel}
+        onOpenPromptTriggerPicker={handleOpenPromptTriggerPicker}
+        onPositivePromptChangeImmediate={commitPromptChangeImmediately}
+        onUsePrompt={handleUsePrompt}
+      />
+    ),
+    [
+      commitPromptChangeImmediately,
+      draftValue,
+      handleOpenPromptTriggerPicker,
+      handleUsePrompt,
+      loras,
+      projectId,
+      selectedModel,
+      triggerPickerState,
+    ]
+  );
+
+  const handlePromptChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => commitPromptChange(event.currentTarget.value),
+    [commitPromptChange]
+  );
+
+  const triggerPickerPositioning = useMemo(
+    () => ({ getAnchorRect: () => triggerPickerState?.anchorRect ?? null }),
+    [triggerPickerState]
+  );
+
+  return (
+    <Field label={t('common.prompt')} labelEnd={labelEnd}>
+      <PromptTextarea
+        {...PROMPT_ATTENTION_TARGET_PROPS}
+        aria-label={t('widgets.generate.positivePrompt')}
+        defaultHeightPx={heightPx}
+        maxHeightPx={360}
+        minHeightPx={96}
+        resizeHandleAriaLabel={t('widgets.generate.resizePositivePrompt')}
+        size="xs"
+        fontFamily="mono"
+        showSyntaxHighlighting={showSyntaxHighlighting}
+        textareaRef={handleTextareaRef}
+        value={draftValue}
+        onChange={handlePromptChange}
+        onKeyDown={handlePromptKeyDown}
+        onResizeEnd={onResizeEnd}
+      />
+      {triggerPickerState ? (
+        <PromptTriggerPopover
+          loras={loras}
+          open
+          positioning={triggerPickerPositioning}
+          selectedModel={selectedModel}
+          onClose={closePromptTriggerPicker}
+          onSelect={selectPromptTrigger}
+        />
+      ) : null}
+    </Field>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PromptTextarea.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PromptTextarea.tsx
new file mode 100644
index 00000000000..674f29543e9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/PromptTextarea.tsx
@@ -0,0 +1,210 @@
+import type { ResizableTextareaProps } from '@workbench/components/ui';
+import type { PromptHighlightKind, PromptHighlightSegment } from '@workbench/generation/prompt/highlight';
+import type { Ref, UIEvent } from 'react';
+
+import { Box } from '@chakra-ui/react';
+import { ResizableTextarea } from '@workbench/components/ui';
+import { buildPromptHighlightSegments } from '@workbench/generation/prompt/highlight';
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+
+const MAX_HIGHLIGHTED_PROMPT_LENGTH = 20_000;
+const PROMPT_TEXTAREA_LINE_HEIGHT = '1.6';
+const PROMPT_TEXTAREA_PX = '2.5';
+const PROMPT_TEXTAREA_PY = '2';
+
+const HIGHLIGHT_STYLE_BY_KIND: Record<
+  PromptHighlightKind,
+  { bg?: string; color: string; textDecoration?: string; textDecorationColor?: string }
+> = {
+  attention: { color: 'accent.solid' },
+  attentionNumeric: { color: 'fg.success' },
+  embedding: { bg: 'bg.warning', color: 'fg.warning' },
+  error: { bg: 'bg.error', color: 'fg.error', textDecoration: 'underline wavy', textDecorationColor: 'fg.error' },
+  escapedParen: { color: 'fg.muted' },
+  group: { color: 'fg.subtle' },
+  promptFunctionArg: { bg: 'accent.subtle/20', color: 'fg' },
+  promptFunctionMethod: { color: 'accent.fg' },
+  punctuation: { color: 'fg.subtle' },
+  text: { color: 'fg' },
+};
+
+const PROMPT_TEXTAREA_FORCED_COLORS_CSS = { '@media (forced-colors: active)': { display: 'none' } };
+const PROMPT_TEXTAREA_HIGHLIGHTED_CSS = {
+  '&::selection': { color: 'transparent', WebkitTextFillColor: 'transparent' },
+  '@media (forced-colors: active)': {
+    WebkitTextFillColor: 'CanvasText',
+    backgroundColor: 'Field',
+    color: 'CanvasText',
+  },
+  WebkitTextFillColor: 'transparent',
+};
+
+interface PromptTextareaProps extends Omit<ResizableTextareaProps, 'underlay'> {
+  showSyntaxHighlighting: boolean;
+  value: string;
+}
+
+const setRef = (ref: Ref<HTMLTextAreaElement> | undefined, element: HTMLTextAreaElement | null): void => {
+  if (!ref) {
+    return;
+  }
+
+  if (typeof ref === 'function') {
+    ref(element);
+    return;
+  }
+
+  (ref as { current: HTMLTextAreaElement | null }).current = element;
+};
+
+const PromptHighlightSpan = ({ segment }: { segment: PromptHighlightSegment }) => {
+  const style = HIGHLIGHT_STYLE_BY_KIND[segment.kind];
+
+  return (
+    <Box
+      as="span"
+      bg={style.bg}
+      borderRadius={style.bg ? '2px' : undefined}
+      color={style.color}
+      textDecoration={style.textDecoration}
+      textDecorationColor={style.textDecorationColor}
+    >
+      {segment.text}
+    </Box>
+  );
+};
+
+export const PromptTextarea = ({
+  fontFamily = 'mono',
+  fontSize,
+  lineHeight,
+  onScroll,
+  showSyntaxHighlighting,
+  textareaRef,
+  value,
+  ...props
+}: PromptTextareaProps) => {
+  const localTextareaRef = useRef<HTMLTextAreaElement | null>(null);
+  const [scroll, setScroll] = useState({ left: 0, top: 0 });
+  const [textareaClientWidth, setTextareaClientWidth] = useState<number | null>(null);
+  const shouldHighlight = showSyntaxHighlighting && value.length > 0 && value.length <= MAX_HIGHLIGHTED_PROMPT_LENGTH;
+  const effectiveFontSize = fontSize ?? 'xs';
+  const effectiveLineHeight = lineHeight ?? PROMPT_TEXTAREA_LINE_HEIGHT;
+
+  const segments = useMemo(
+    () => (shouldHighlight ? buildPromptHighlightSegments(value) : []),
+    [shouldHighlight, value]
+  );
+
+  useLayoutEffect(() => {
+    if (!shouldHighlight || !localTextareaRef.current) {
+      return;
+    }
+
+    const textarea = localTextareaRef.current;
+    const syncClientWidth = () => {
+      const nextWidth = textarea.clientWidth;
+
+      setTextareaClientWidth((currentWidth) => (currentWidth === nextWidth ? currentWidth : nextWidth));
+    };
+    const resizeObserver = new ResizeObserver(syncClientWidth);
+
+    syncClientWidth();
+    resizeObserver.observe(textarea);
+    window.addEventListener('resize', syncClientWidth);
+
+    return () => {
+      resizeObserver.disconnect();
+      window.removeEventListener('resize', syncClientWidth);
+    };
+  }, [shouldHighlight, value]);
+
+  const handleTextareaRef = useCallback(
+    (element: HTMLTextAreaElement | null) => {
+      localTextareaRef.current = element;
+      setRef(textareaRef, element);
+    },
+    [textareaRef]
+  );
+
+  const handleScroll = useCallback(
+    (event: UIEvent<HTMLTextAreaElement>) => {
+      setScroll({ left: event.currentTarget.scrollLeft, top: event.currentTarget.scrollTop });
+      onScroll?.(event);
+    },
+    [onScroll]
+  );
+
+  const underlay = useMemo(
+    () =>
+      shouldHighlight ? (
+        <Box
+          aria-hidden="true"
+          borderColor="transparent"
+          borderRadius="md"
+          borderWidth="1px"
+          color="fg"
+          inset="0"
+          overflow="hidden"
+          pointerEvents="none"
+          position="absolute"
+          zIndex={0}
+          css={PROMPT_TEXTAREA_FORCED_COLORS_CSS}
+        >
+          <Box
+            as="pre"
+            fontFamily={fontFamily}
+            fontSize={effectiveFontSize}
+            lineHeight={effectiveLineHeight}
+            m="0"
+            minH="100%"
+            overflowWrap="break-word"
+            px={PROMPT_TEXTAREA_PX}
+            py={PROMPT_TEXTAREA_PY}
+            transform={`translate(${-scroll.left}px, ${-scroll.top}px)`}
+            whiteSpace="pre-wrap"
+            w={textareaClientWidth ? `${textareaClientWidth}px` : '100%'}
+          >
+            {segments.map((segment) => (
+              <PromptHighlightSpan
+                key={`${segment.range.start}:${segment.range.end}:${segment.kind}`}
+                segment={segment}
+              />
+            ))}
+            {value.endsWith('\n') ? '\u200b' : null}
+          </Box>
+        </Box>
+      ) : null,
+    [
+      effectiveFontSize,
+      effectiveLineHeight,
+      fontFamily,
+      scroll.left,
+      scroll.top,
+      segments,
+      shouldHighlight,
+      textareaClientWidth,
+      value,
+    ]
+  );
+
+  return (
+    <ResizableTextarea
+      {...props}
+      bg={shouldHighlight ? 'transparent' : props.bg}
+      caretColor={shouldHighlight ? 'fg' : props.caretColor}
+      color={shouldHighlight ? 'transparent' : props.color}
+      css={shouldHighlight ? PROMPT_TEXTAREA_HIGHLIGHTED_CSS : props.css}
+      fontFamily={fontFamily}
+      fontSize={effectiveFontSize}
+      lineHeight={effectiveLineHeight}
+      overflowWrap="break-word"
+      px={PROMPT_TEXTAREA_PX}
+      py={PROMPT_TEXTAREA_PY}
+      textareaRef={handleTextareaRef}
+      underlay={underlay}
+      value={value}
+      onScroll={handleScroll}
+    />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/index.ts
new file mode 100644
index 00000000000..7240b6c01a8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/index.ts
@@ -0,0 +1,2 @@
+export { GeneratePromptFields } from './GeneratePromptFields';
+export { focusPositivePrompt } from './promptFocus';
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptAttentionHotkeys.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptAttentionHotkeys.ts
new file mode 100644
index 00000000000..864340c5951
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptAttentionHotkeys.ts
@@ -0,0 +1,60 @@
+import type { PromptAttentionDirection } from '@workbench/generation/prompt/attention';
+
+import { adjustPromptAttention } from '@workbench/generation/prompt/attention';
+
+export const PROMPT_ATTENTION_TARGET_ATTR = 'data-prompt-attention-target';
+export const PROMPT_ATTENTION_TARGET_PROPS = { [PROMPT_ATTENTION_TARGET_ATTR]: 'true' } as const;
+
+const isPromptAttentionTarget = (element: Element | null): element is HTMLTextAreaElement =>
+  element instanceof HTMLTextAreaElement && element.getAttribute(PROMPT_ATTENTION_TARGET_ATTR) === 'true';
+
+const setTextareaValue = (textarea: HTMLTextAreaElement, value: string): void => {
+  const valueSetter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+
+  if (valueSetter) {
+    valueSetter.call(textarea, value);
+  } else {
+    textarea.value = value;
+  }
+
+  textarea.dispatchEvent(new Event('input', { bubbles: true }));
+};
+
+const replaceTextareaValue = (textarea: HTMLTextAreaElement, value: string): void => {
+  textarea.focus();
+  textarea.setSelectionRange(0, textarea.value.length);
+
+  if (typeof document.execCommand === 'function' && document.execCommand('insertText', false, value)) {
+    return;
+  }
+
+  setTextareaValue(textarea, value);
+};
+
+export const adjustFocusedPromptAttention = (
+  direction: PromptAttentionDirection,
+  preferNumericAttentionStyle: boolean
+): boolean => {
+  const textarea = document.activeElement;
+
+  if (!isPromptAttentionTarget(textarea)) {
+    return false;
+  }
+
+  const result = adjustPromptAttention(
+    textarea.value,
+    textarea.selectionStart,
+    textarea.selectionEnd,
+    direction,
+    preferNumericAttentionStyle
+  );
+
+  if (result.prompt === textarea.value) {
+    return false;
+  }
+
+  replaceTextareaValue(textarea, result.prompt);
+  textarea.setSelectionRange(result.selectionStart, result.selectionEnd);
+
+  return true;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptFocus.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptFocus.test.ts
new file mode 100644
index 00000000000..3ef902eb60b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptFocus.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { insertTextAtRange } from './promptFocus';
+
+describe('insertTextAtRange', () => {
+  it('inserts text at a collapsed range', () => {
+    expect(insertTextAtRange('a  cat', 'fluffy', { end: 2, start: 2 })).toEqual({ caret: 8, value: 'a fluffy cat' });
+  });
+
+  it('replaces the selected range with text', () => {
+    expect(insertTextAtRange('a < cat', 'fluffy', { end: 3, start: 2 })).toEqual({ caret: 8, value: 'a fluffy cat' });
+  });
+
+  it('clamps stale ranges to the prompt bounds', () => {
+    expect(insertTextAtRange('cat', ' fluffy', { end: 99, start: 99 })).toEqual({ caret: 10, value: 'cat fluffy' });
+  });
+
+  it('uses the textarea caret when no explicit range is provided', () => {
+    expect(insertTextAtRange('cat', ' fluffy', undefined, 3)).toEqual({ caret: 10, value: 'cat fluffy' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptFocus.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptFocus.ts
new file mode 100644
index 00000000000..14a3bf520ab
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptFocus.ts
@@ -0,0 +1,73 @@
+let positivePromptElement: HTMLTextAreaElement | null = null;
+
+export type PromptTextRange = { end: number; start: number };
+
+export const registerPositivePromptElement = (element: HTMLTextAreaElement | null): void => {
+  positivePromptElement = element;
+};
+
+export const focusPositivePrompt = (): boolean => {
+  if (!positivePromptElement) {
+    return false;
+  }
+
+  positivePromptElement.focus();
+  positivePromptElement.select();
+
+  return true;
+};
+
+export const isPositivePromptFocused = (): boolean =>
+  positivePromptElement !== null && document.activeElement === positivePromptElement;
+
+const clamp = (value: number, min: number, max: number): number => Math.min(Math.max(value, min), max);
+
+export const insertTextAtRange = (
+  value: string,
+  text: string,
+  range: PromptTextRange | undefined,
+  fallbackCaret = value.length
+): { caret: number; value: string } => {
+  const insertionRange = range ?? { end: fallbackCaret, start: fallbackCaret };
+  const start = clamp(Math.min(insertionRange.start, insertionRange.end), 0, value.length);
+  const end = clamp(Math.max(insertionRange.start, insertionRange.end), 0, value.length);
+  const nextValue = `${value.slice(0, start)}${text}${value.slice(end)}`;
+
+  return { caret: start + text.length, value: nextValue };
+};
+
+export const insertPromptText = ({
+  onChange,
+  range,
+  textarea,
+  text,
+  value,
+}: {
+  onChange: (value: string) => void;
+  range?: PromptTextRange;
+  textarea: HTMLTextAreaElement | null;
+  text: string;
+  value: string;
+}): void => {
+  const caret = textarea?.selectionStart ?? value.length;
+  const { caret: nextCaret, value: nextValue } = insertTextAtRange(value, text, range, caret);
+
+  onChange(nextValue);
+
+  window.requestAnimationFrame(() => {
+    textarea?.focus();
+    textarea?.setSelectionRange(nextCaret, nextCaret);
+  });
+};
+
+export const insertPositivePromptText = ({
+  onChange,
+  range,
+  text,
+  value,
+}: {
+  onChange: (value: string) => void;
+  range?: PromptTextRange;
+  text: string;
+  value: string;
+}): void => insertPromptText({ onChange, range, textarea: positivePromptElement, text, value });
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptHistoryNavigation.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptHistoryNavigation.ts
new file mode 100644
index 00000000000..c86b6d76d14
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/promptFields/promptHistoryNavigation.ts
@@ -0,0 +1,135 @@
+import type { GenerateModelConfig } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type { Project } from '@workbench/types';
+import type { WorkbenchAction } from '@workbench/workbenchState';
+import type { Dispatch } from 'react';
+
+import { getPromptPolicy, isSupportedGenerateModel } from '@workbench/generation/baseGenerationPolicies';
+import { normalizeGenerateSettings } from '@workbench/generation/settings';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+
+import { isPositivePromptFocused } from './promptFocus';
+
+type NavigationState = {
+  projectId: string;
+  historyIndex: number;
+  stashedPrompts: {
+    negativePrompt: string;
+    negativePromptEnabled: boolean;
+    positivePrompt: string;
+  };
+};
+
+let navigationState: NavigationState | null = null;
+
+export const resetPromptHistoryNavigation = (): void => {
+  navigationState = null;
+};
+
+const getSelectedGenerateModel = (
+  settings: ReturnType<typeof normalizeGenerateSettings>,
+  models: readonly ModelConfig[] | undefined
+): GenerateModelConfig | undefined => {
+  if (!settings || !models) {
+    return undefined;
+  }
+
+  return models.filter(isSupportedGenerateModel).find((model) => model.key === settings.modelKey);
+};
+
+const applyPromptHistoryIndex = ({
+  dispatch,
+  models,
+  project,
+}: {
+  dispatch: Dispatch<WorkbenchAction>;
+  models: readonly ModelConfig[] | undefined;
+  project: Project;
+}): void => {
+  if (!navigationState) {
+    return;
+  }
+
+  const prompt = project.promptHistory[navigationState.historyIndex];
+  const settings = normalizeGenerateSettings(getProjectWidgetValues(project, 'generate'));
+
+  if (!prompt || !settings) {
+    return;
+  }
+
+  const selectedModel = getSelectedGenerateModel(settings, models);
+  const promptPolicy = getPromptPolicy(selectedModel, settings);
+  const values: Record<string, unknown> = { positivePrompt: prompt.positivePrompt };
+
+  if (promptPolicy.negativeVisible) {
+    values.negativePrompt = prompt.negativePrompt ?? '';
+    values.negativePromptEnabled = prompt.negativePrompt ? true : settings.negativePromptEnabled;
+  }
+
+  dispatch({ projectId: project.id, type: 'patchWidgetValues', values, widgetId: 'generate' });
+};
+
+export const navigatePromptHistory = ({
+  direction,
+  dispatch,
+  models,
+  project,
+}: {
+  direction: -1 | 1;
+  dispatch: Dispatch<WorkbenchAction>;
+  models: readonly ModelConfig[] | undefined;
+  project: Project;
+}): void => {
+  if (navigationState?.projectId !== project.id) {
+    navigationState = null;
+  }
+
+  if (!isPositivePromptFocused() || project.promptHistory.length === 0) {
+    return;
+  }
+
+  const settings = normalizeGenerateSettings(getProjectWidgetValues(project, 'generate'));
+
+  if (!settings) {
+    return;
+  }
+
+  if (direction === -1) {
+    if (!navigationState) {
+      navigationState = {
+        historyIndex: 0,
+        projectId: project.id,
+        stashedPrompts: {
+          negativePrompt: settings.negativePrompt,
+          negativePromptEnabled: settings.negativePromptEnabled,
+          positivePrompt: settings.positivePrompt,
+        },
+      };
+    } else if (navigationState.historyIndex < project.promptHistory.length - 1) {
+      navigationState = { ...navigationState, historyIndex: navigationState.historyIndex + 1 };
+    }
+
+    applyPromptHistoryIndex({ dispatch, models, project });
+    return;
+  }
+
+  if (!navigationState) {
+    return;
+  }
+
+  const nextHistoryIndex = navigationState.historyIndex - 1;
+
+  if (nextHistoryIndex < 0) {
+    dispatch({
+      projectId: project.id,
+      type: 'patchWidgetValues',
+      values: navigationState.stashedPrompts,
+      widgetId: 'generate',
+    });
+    navigationState = null;
+    return;
+  }
+
+  navigationState = { ...navigationState, historyIndex: nextHistoryIndex };
+  applyPromptHistoryIndex({ dispatch, models, project });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/GenerateReferenceImagesSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/GenerateReferenceImagesSection.tsx
new file mode 100644
index 00000000000..aee0fbfaba5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/GenerateReferenceImagesSection.tsx
@@ -0,0 +1,312 @@
+import type {
+  GenerateModelConfig,
+  GenerateReferenceImage,
+  GenerateReferenceImageAsset,
+  GenerateSettings,
+} from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type { GenerateSettingsUpdate } from '@workbench/widgets/generate/generateDebounce';
+import type { ChangeEvent } from 'react';
+
+import { Badge, Box, HStack, Input, Stack, Text } from '@chakra-ui/react';
+import { useDndMonitor, useDroppable } from '@dnd-kit/core';
+import { Button, IconButton, Tooltip } from '@workbench/components/ui';
+import { getGalleryImagesByNames, uploadGalleryImage } from '@workbench/gallery/api';
+import {
+  createReferenceImageId,
+  getDefaultReferenceImageConfig,
+  getGenerationDimensions,
+  getMaxReferenceImages,
+  isReferenceImageSupported,
+} from '@workbench/generation/baseGenerationPolicies';
+import { clampDimension, deriveAspectRatioId } from '@workbench/generation/settings';
+import { isGalleryImageDragData } from '@workbench/widgets/gallery/galleryDnd';
+import { GenerateCollapsibleSection } from '@workbench/widgets/generate/shared/GenerateCollapsibleSection';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { ScanIcon, UploadIcon } from 'lucide-react';
+import { useCallback, useMemo, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { ReferenceImageCard } from './ReferenceImageCard';
+
+const UPLOAD_ZONE_HOVER_STYLES = { bg: 'bg.muted', color: 'fg' };
+
+interface GenerateReferenceImagesSectionProps {
+  models: readonly ModelConfig[];
+  selectedModel: GenerateModelConfig | undefined;
+  settings: GenerateSettings;
+  onCommit: (update: GenerateSettingsUpdate) => void;
+  onCommitImmediate: (patch: Partial<GenerateSettings>) => void;
+}
+
+export const GenerateReferenceImagesSection = ({
+  models,
+  onCommit,
+  onCommitImmediate,
+  selectedModel,
+  settings,
+}: GenerateReferenceImagesSectionProps) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const referenceImages = settings.referenceImages;
+  const isSupported = isReferenceImageSupported(selectedModel);
+  const maxReferenceImages = getMaxReferenceImages(selectedModel);
+  const canAdd = referenceImages.length < maxReferenceImages;
+  const { isOver, setNodeRef } = useDroppable({
+    data: { kind: 'generate-reference-images' },
+    disabled: !canAdd,
+    id: 'generate-reference-images',
+  });
+  const activeCount = referenceImages.filter((image) => image.isEnabled).length;
+  const referenceImageCount = referenceImages.length;
+
+  const appendReferenceImages = useCallback(
+    (images: GenerateReferenceImageAsset[]) => {
+      onCommit((currentSettings) => {
+        const remaining = getMaxReferenceImages(selectedModel) - currentSettings.referenceImages.length;
+
+        if (remaining <= 0 || images.length === 0) {
+          return currentSettings;
+        }
+
+        return {
+          ...currentSettings,
+          referenceImages: [
+            ...currentSettings.referenceImages,
+            ...images.slice(0, remaining).map((image) => ({
+              config: getDefaultReferenceImageConfig(selectedModel, models, image),
+              id: createReferenceImageId(),
+              isEnabled: true,
+            })),
+          ],
+        };
+      });
+    },
+    [models, onCommit, selectedModel]
+  );
+
+  const patchReferenceImage = useCallback(
+    (id: string, patch: Partial<GenerateReferenceImage>) => {
+      onCommit((currentSettings) => ({
+        ...currentSettings,
+        referenceImages: currentSettings.referenceImages.map((referenceImage) =>
+          referenceImage.id === id ? { ...referenceImage, ...patch } : referenceImage
+        ),
+      }));
+    },
+    [onCommit]
+  );
+
+  const removeReferenceImage = useCallback(
+    (id: string) => {
+      onCommit((currentSettings) => ({
+        ...currentSettings,
+        referenceImages: currentSettings.referenceImages.filter((referenceImage) => referenceImage.id !== id),
+      }));
+    },
+    [onCommit]
+  );
+
+  const clearReferenceImages = useCallback(() => onCommitImmediate({ referenceImages: [] }), [onCommitImmediate]);
+
+  const applyReferenceImageSize = useCallback(
+    (image: GenerateReferenceImageAsset) => {
+      if (!selectedModel) {
+        return;
+      }
+
+      const grid = getGenerationDimensions(selectedModel).grid;
+      const width = clampDimension(image.width, grid);
+      const height = clampDimension(image.height, grid);
+
+      onCommitImmediate({
+        aspectRatioId: deriveAspectRatioId(width, height),
+        aspectRatioValue: height > 0 ? width / height : 1,
+        height,
+        width,
+      });
+    },
+    [onCommitImmediate, selectedModel]
+  );
+
+  const uploadFiles = useCallback(
+    async (files: File[]) => {
+      if (!canAdd || files.length === 0) {
+        return;
+      }
+
+      try {
+        const uploaded = await Promise.all(
+          files.slice(0, maxReferenceImages - referenceImageCount).map((file) => uploadGalleryImage(file, 'none'))
+        );
+
+        appendReferenceImages(uploaded);
+        dispatch({ type: 'touchGalleryImagesRefresh' });
+      } catch (error) {
+        dispatch({
+          area: 'reference-images',
+          message: error instanceof Error ? error.message : String(error),
+          namespace: 'generation',
+          type: 'recordError',
+        });
+      }
+    },
+    [appendReferenceImages, canAdd, dispatch, maxReferenceImages, referenceImageCount]
+  );
+
+  const handleUploadZoneClick = useCallback(() => {
+    if (canAdd) {
+      fileInputRef.current?.click();
+    }
+  }, [canAdd]);
+
+  const handleFileInputChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      void uploadFiles(Array.from(event.currentTarget.files ?? []));
+      event.currentTarget.value = '';
+    },
+    [uploadFiles]
+  );
+
+  const addGalleryImages = async (imageNames: string[]) => {
+    if (!canAdd || imageNames.length === 0) {
+      return;
+    }
+
+    const images = await getGalleryImagesByNames(imageNames.slice(0, maxReferenceImages - referenceImageCount));
+
+    if (images.length > 0) {
+      appendReferenceImages(images);
+    }
+  };
+
+  useDndMonitor({
+    onDragEnd: (event) => {
+      const data = event.active.data.current;
+
+      if (event.over?.id === 'generate-reference-images' && isGalleryImageDragData(data) && canAdd) {
+        void addGalleryImages(data.images.map((image) => image.imageName));
+      }
+    },
+  });
+
+  const badges = useMemo(() => {
+    if (!isSupported) {
+      return referenceImageCount > 0 ? (
+        <Badge colorPalette="orange" size="xs" variant="surface">
+          {t('widgets.generate.incompatible')}
+        </Badge>
+      ) : null;
+    }
+
+    if (activeCount > 0) {
+      return (
+        <Badge colorPalette="green" size="xs" variant="surface">
+          {t('widgets.generate.activeCount', { count: activeCount })}
+        </Badge>
+      );
+    }
+
+    return referenceImageCount > 0 ? (
+      <Badge size="xs" variant="surface">
+        {t('widgets.generate.offCount', { count: referenceImageCount })}
+      </Badge>
+    ) : null;
+  }, [activeCount, isSupported, referenceImageCount, t]);
+
+  if (!isSupported && referenceImageCount === 0) {
+    return null;
+  }
+
+  // Leftover reference images on a model that cannot use them (e.g. a persisted
+  // project). No editable cards, no add paths — just the way out.
+  if (!isSupported) {
+    return (
+      <GenerateCollapsibleSection label={t('widgets.generate.referenceImages')} defaultOpen badges={badges}>
+        <HStack gap="2" justify="space-between" p="2">
+          <Text color="fg.muted" fontSize="2xs" minW="0">
+            {t('widgets.generate.referenceImagesUnsupported')}
+          </Text>
+          <Button colorPalette="red" flexShrink="0" size="xs" variant="outline" onClick={clearReferenceImages}>
+            {t('widgets.generate.clearReferenceImages')}
+          </Button>
+        </HStack>
+      </GenerateCollapsibleSection>
+    );
+  }
+
+  return (
+    <GenerateCollapsibleSection label={t('widgets.generate.referenceImages')} defaultOpen badges={badges}>
+      <Stack ref={setNodeRef} bg={isOver ? 'accent.muted' : undefined} gap="2" p="2">
+        <HStack align="stretch" gap="2">
+          <Box
+            as="button"
+            alignItems="center"
+            borderColor={isOver ? 'accent.solid' : 'border.emphasized'}
+            borderStyle="dashed"
+            borderWidth="1px"
+            color="fg.muted"
+            cursor={canAdd ? 'pointer' : 'not-allowed'}
+            display="flex"
+            flex="1"
+            fontSize="2xs"
+            gap="2"
+            justifyContent="center"
+            minH="12"
+            minW="0"
+            opacity={canAdd ? 1 : 0.6}
+            px="3"
+            rounded="md"
+            _hover={canAdd ? UPLOAD_ZONE_HOVER_STYLES : undefined}
+            onClick={handleUploadZoneClick}
+          >
+            <UploadIcon size="14" />
+            {t('widgets.generate.referenceImagesHelp')}
+          </Box>
+          {/* The button is disabled (canvas bbox pulls are not wired up yet), so
+              the tooltip hangs off a wrapper — disabled buttons eat pointer events. */}
+          <Tooltip content={t('widgets.generate.pullBboxIntoReferenceImage')}>
+            <Box display="flex" flexShrink="0">
+              <IconButton
+                aria-label={t('widgets.generate.pullBboxIntoReferenceImage')}
+                disabled
+                h="full"
+                minH="12"
+                minW="12"
+                variant="outline"
+              >
+                <ScanIcon />
+              </IconButton>
+            </Box>
+          </Tooltip>
+        </HStack>
+
+        {referenceImageCount > 0 ? (
+          <Stack gap="2">
+            {referenceImages.map((referenceImage, index) => (
+              <ReferenceImageCard
+                key={referenceImage.id}
+                index={index}
+                referenceImage={referenceImage}
+                selectedModel={selectedModel}
+                onPatch={patchReferenceImage}
+                onRemove={removeReferenceImage}
+                onUseSize={applyReferenceImageSize}
+              />
+            ))}
+          </Stack>
+        ) : null}
+
+        <Input
+          ref={fileInputRef}
+          accept="image/*"
+          display="none"
+          multiple
+          type="file"
+          onChange={handleFileInputChange}
+        />
+      </Stack>
+    </GenerateCollapsibleSection>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageCard.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageCard.tsx
new file mode 100644
index 00000000000..74c0cba9502
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageCard.tsx
@@ -0,0 +1,384 @@
+import type {
+  GenerateModelConfig,
+  GenerateReferenceImage,
+  GenerateReferenceImageAsset,
+  GenerateReferenceImageConfig,
+} from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type { CSSProperties } from 'react';
+
+import { Box, HStack, Icon, Stack, Text } from '@chakra-ui/react';
+import { IconButton, ToggleDot, Tooltip } from '@workbench/components/ui';
+import { ModelSelect } from '@workbench/models/components';
+import { ChevronDownIcon, CropIcon, ImageIcon, RulerIcon, Trash2Icon } from 'lucide-react';
+import { memo, useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { formatWeight, getModeLabelKey } from './referenceImageConfig';
+import { ClipVisionSelect, FieldHeader, FluxReduxControls, IPAdapterControls } from './ReferenceImageControls';
+import { ReferenceImageCropDialog } from './ReferenceImageCropDialog';
+
+/** Reference image config variants that carry a selectable model. */
+type ModelBackedConfig = Extract<
+  GenerateReferenceImageConfig,
+  { type: 'ip_adapter' | 'flux_redux' | 'flux_kontext_reference_image' }
+>;
+
+const THUMBNAIL_ACTIONS_CSS = {
+  '&:focus-within .reference-image-actions, &:hover .reference-image-actions': {
+    opacity: 1,
+  },
+};
+
+const FLUX_MODEL_TYPES = ['ip_adapter', 'flux_redux'];
+const DEFAULT_MODEL_TYPES = ['ip_adapter'];
+const COVER_IMG_STYLE: CSSProperties = {
+  height: '100%',
+  objectFit: 'cover',
+  width: '100%',
+};
+const OVERLAY_GRADIENT_STYLE: CSSProperties = {
+  background: 'linear-gradient(to top, rgba(0, 0, 0, 0.72), transparent)',
+};
+
+interface ReferenceImageCardProps {
+  index: number;
+  referenceImage: GenerateReferenceImage;
+  selectedModel: GenerateModelConfig | undefined;
+  onPatch: (id: string, patch: Partial<GenerateReferenceImage>) => void;
+  onRemove: (id: string) => void;
+  onUseSize: (image: GenerateReferenceImageAsset) => void;
+}
+
+const ReferenceImageCardBase = ({
+  index,
+  onPatch,
+  onRemove,
+  onUseSize,
+  referenceImage,
+  selectedModel,
+}: ReferenceImageCardProps) => {
+  const { t } = useTranslation();
+  const [isCollapsed, setIsCollapsed] = useState(false);
+  const config = referenceImage.config;
+  const isEnabled = referenceImage.isEnabled;
+  const selectedBase = selectedModel?.base;
+  const title = `${t('widgets.generate.referenceImage')} #${index + 1}`;
+  const toggleLabel = isEnabled
+    ? t('widgets.generate.disableReferenceImage')
+    : t('widgets.generate.enableReferenceImage');
+
+  const changeConfig = useCallback(
+    (nextConfig: GenerateReferenceImageConfig) => onPatch(referenceImage.id, { config: nextConfig }),
+    [onPatch, referenceImage.id]
+  );
+
+  const handleToggle = useCallback(
+    (nextEnabled: boolean) => onPatch(referenceImage.id, { isEnabled: nextEnabled }),
+    [onPatch, referenceImage.id]
+  );
+
+  const handleRemove = useCallback(() => onRemove(referenceImage.id), [onRemove, referenceImage.id]);
+
+  const handleCrop = useCallback(
+    (image: GenerateReferenceImageAsset) => changeConfig({ ...config, image }),
+    [changeConfig, config]
+  );
+
+  const expand = useCallback(() => setIsCollapsed(false), []);
+
+  const toggleCollapsed = useCallback(() => setIsCollapsed((previous) => !previous), []);
+
+  return (
+    <Stack
+      bg="bg.subtle"
+      borderColor={isEnabled ? 'border.emphasized' : 'border.subtle'}
+      borderWidth="1px"
+      gap="0"
+      opacity={isEnabled ? 1 : 0.55}
+      rounded="md"
+      transition="opacity var(--wb-motion-duration-slow)"
+    >
+      <HStack gap="2" minW="0" px="2" py="1.5">
+        <ToggleDot checked={isEnabled} label={toggleLabel} onCheckedChange={handleToggle} />
+
+        {isCollapsed ? (
+          <HStack as="button" cursor="pointer" flex="1" gap="2" minW="0" textAlign="left" onClick={expand}>
+            <MiniThumbnail image={config.image} />
+            <Text color="fg.muted" fontSize="xs" minW="0" truncate>
+              <Text as="span" color={isEnabled ? 'fg' : 'fg.muted'} fontWeight="medium">
+                {title}
+              </Text>
+              {config.type === 'ip_adapter' ? (
+                <>
+                  {' · '}
+                  {t(getModeLabelKey(config.method))}{' '}
+                  <Text as="span" color="fg.subtle" fontFamily="mono">
+                    {formatWeight(config.weight)}
+                  </Text>
+                </>
+              ) : null}
+            </Text>
+          </HStack>
+        ) : (
+          <Text color={isEnabled ? 'fg' : 'fg.muted'} flex="1" fontSize="xs" fontWeight="medium" minW="0" truncate>
+            {title}
+          </Text>
+        )}
+
+        <HStack gap="0.5">
+          <IconButton
+            aria-label={
+              isCollapsed ? t('widgets.generate.expandReferenceImage') : t('widgets.generate.collapseReferenceImage')
+            }
+            color="fg.muted"
+            size="2xs"
+            variant="ghost"
+            onClick={toggleCollapsed}
+          >
+            <Box
+              asChild
+              transform={isCollapsed ? 'rotate(-90deg)' : undefined}
+              transition="transform var(--wb-motion-duration-slow)"
+            >
+              <ChevronDownIcon size="14" />
+            </Box>
+          </IconButton>
+          <Tooltip content={t('widgets.generate.removeReferenceImage')}>
+            <IconButton
+              aria-label={t('widgets.generate.removeReferenceImage')}
+              color="fg.muted"
+              size="2xs"
+              variant="ghost"
+              colorPalette="red"
+              onClick={handleRemove}
+            >
+              <Icon as={Trash2Icon} colorPalette="red" />
+            </IconButton>
+          </Tooltip>
+        </HStack>
+      </HStack>
+
+      {isCollapsed ? null : (
+        <HStack align="flex-start" gap="3" pb="2" px="2">
+          <ReferenceImageThumbnail
+            disabled={!isEnabled}
+            image={config.image}
+            onCrop={handleCrop}
+            onUseSize={onUseSize}
+          />
+          <Stack flex="1" gap="2" minW="0">
+            {config.type === 'ip_adapter' ? (
+              <IPAdapterControls
+                key={config.model?.key ?? 'no-model'}
+                config={config}
+                disabled={!isEnabled}
+                onChange={changeConfig}
+              >
+                <ReferenceModelSelector
+                  config={config}
+                  disabled={!isEnabled}
+                  selectedBase={selectedBase}
+                  onConfigChange={changeConfig}
+                />
+              </IPAdapterControls>
+            ) : config.type === 'flux_redux' ? (
+              <>
+                <ReferenceModelSelector
+                  config={config}
+                  disabled={!isEnabled}
+                  selectedBase={selectedBase}
+                  onConfigChange={changeConfig}
+                />
+                <FluxReduxControls config={config} disabled={!isEnabled} onChange={changeConfig} />
+              </>
+            ) : config.type === 'flux_kontext_reference_image' ? (
+              <ReferenceModelSelector
+                config={config}
+                disabled={!isEnabled}
+                selectedBase={selectedBase}
+                onConfigChange={changeConfig}
+              />
+            ) : null}
+          </Stack>
+        </HStack>
+      )}
+    </Stack>
+  );
+};
+
+export const ReferenceImageCard = memo(ReferenceImageCardBase);
+
+const ReferenceModelSelector = ({
+  config,
+  disabled,
+  onConfigChange,
+  selectedBase,
+}: {
+  config: ModelBackedConfig;
+  disabled: boolean;
+  selectedBase: string | undefined;
+  onConfigChange: (config: GenerateReferenceImageConfig) => void;
+}) => {
+  const { t } = useTranslation();
+  const modelTypes = selectedBase === 'flux' ? FLUX_MODEL_TYPES : DEFAULT_MODEL_TYPES;
+
+  const filterModel = useCallback((model: ModelConfig) => model.base === selectedBase, [selectedBase]);
+
+  const selectReferenceModel = useCallback(
+    (model: ModelConfig | null) => {
+      if (!model || model.base !== selectedBase) {
+        return;
+      }
+
+      if (model.type === 'flux_redux') {
+        onConfigChange({
+          image: config.image,
+          imageInfluence: 'highest',
+          model,
+          type: 'flux_redux',
+        });
+        return;
+      }
+
+      if (model.type === 'ip_adapter') {
+        onConfigChange({
+          beginEndStepPct: [0, 1],
+          clipVisionModel: selectedBase === 'flux' ? 'ViT-L' : 'ViT-H',
+          image: config.image,
+          method: 'full',
+          model,
+          type: 'ip_adapter',
+          weight: 1,
+        });
+      }
+    },
+    [config.image, onConfigChange, selectedBase]
+  );
+
+  return (
+    <Stack gap="1">
+      <FieldHeader label={t('widgets.generate.referenceImageModel')} />
+      <HStack gap="2">
+        <ModelSelect
+          disabled={disabled}
+          filter={filterModel}
+          modelTypes={modelTypes}
+          placeholder={t('widgets.generate.selectModel')}
+          size="xs"
+          value={config.model?.key ?? null}
+          onChange={selectReferenceModel}
+        />
+        {config.type === 'ip_adapter' ? (
+          <ClipVisionSelect
+            key={config.model?.key ?? 'no-model'}
+            config={config}
+            disabled={disabled}
+            onChange={onConfigChange}
+          />
+        ) : null}
+      </HStack>
+    </Stack>
+  );
+};
+
+const MiniThumbnail = ({ image }: { image: GenerateReferenceImageAsset | null }) => (
+  <Box bg="bg.muted" borderWidth="1px" flexShrink="0" h="6" overflow="hidden" rounded="sm" w="6">
+    {image ? (
+      <img alt={image.imageName} draggable={false} src={image.thumbnailUrl} style={COVER_IMG_STYLE} />
+    ) : (
+      <Box alignItems="center" color="fg.muted" display="flex" h="full" justifyContent="center" w="full">
+        <ImageIcon size="12" />
+      </Box>
+    )}
+  </Box>
+);
+
+const ReferenceImageThumbnail = ({
+  disabled,
+  image,
+  onCrop,
+  onUseSize,
+}: {
+  disabled: boolean;
+  image: GenerateReferenceImageAsset | null;
+  onCrop: (image: GenerateReferenceImageAsset) => void;
+  onUseSize: (image: GenerateReferenceImageAsset) => void;
+}) => {
+  const { t } = useTranslation();
+  const [isCropOpen, setIsCropOpen] = useState(false);
+
+  const openCrop = useCallback(() => setIsCropOpen(true), []);
+  const closeCrop = useCallback(() => setIsCropOpen(false), []);
+
+  const handleUseSize = useCallback(() => {
+    if (image) {
+      onUseSize(image);
+    }
+  }, [image, onUseSize]);
+
+  return (
+    <>
+      <Box
+        bg="bg.muted"
+        borderWidth="1px"
+        css={THUMBNAIL_ACTIONS_CSS}
+        flexShrink="0"
+        h="20"
+        overflow="hidden"
+        position="relative"
+        rounded="md"
+        w="20"
+      >
+        {image ? (
+          <img alt={image.imageName} draggable={false} src={image.thumbnailUrl} style={COVER_IMG_STYLE} />
+        ) : (
+          <Box alignItems="center" color="fg.muted" display="flex" h="full" justifyContent="center" w="full">
+            <ImageIcon size="24" />
+          </Box>
+        )}
+        {image ? (
+          <HStack
+            bottom="0"
+            className="reference-image-actions"
+            gap="1"
+            justify="center"
+            left="0"
+            opacity="0"
+            p="1"
+            position="absolute"
+            right="0"
+            style={OVERLAY_GRADIENT_STYLE}
+            transition="opacity var(--wb-motion-duration-fast)"
+          >
+            <Tooltip content={t('common.crop')}>
+              <IconButton
+                aria-label={t('common.crop')}
+                disabled={disabled}
+                size="2xs"
+                variant="ghost"
+                onClick={openCrop}
+              >
+                <CropIcon />
+              </IconButton>
+            </Tooltip>
+            <Tooltip content={t('widgets.generate.useSize')}>
+              <IconButton
+                aria-label={t('widgets.generate.useSize')}
+                disabled={disabled}
+                size="2xs"
+                variant="ghost"
+                onClick={handleUseSize}
+              >
+                <RulerIcon />
+              </IconButton>
+            </Tooltip>
+          </HStack>
+        ) : null}
+      </Box>
+      {image ? (
+        <ReferenceImageCropDialog image={image} isOpen={isCropOpen} onApply={onCrop} onClose={closeCrop} />
+      ) : null}
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageControls.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageControls.tsx
new file mode 100644
index 00000000000..f2979eec033
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageControls.tsx
@@ -0,0 +1,457 @@
+import type { SelectValueChangeDetails, SliderValueChangeDetails } from '@chakra-ui/react';
+import type {
+  ClipVisionModel,
+  FluxReduxImageInfluence,
+  GenerateReferenceImageConfig,
+  IPAdapterMethod,
+} from '@workbench/generation/types';
+import type { KeyboardEvent, ReactNode } from 'react';
+
+import {
+  Collapsible,
+  createListCollection,
+  Flex,
+  HStack,
+  NumberInput,
+  SegmentGroup,
+  Stack,
+  Text,
+} from '@chakra-ui/react';
+import { Field, Select, Slider } from '@workbench/components/ui';
+import { ChevronRightIcon } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { StyleMethod } from './referenceImageConfig';
+
+import {
+  CLIP_VISION_MODELS,
+  formatPct,
+  formatWeight,
+  getReferenceMode,
+  isClipVisionModel,
+  isReferenceMode,
+  isStyleMethod,
+  MODE_SEGMENTS,
+  STYLE_VARIANT_OPTIONS,
+} from './referenceImageConfig';
+
+type IPAdapterConfig = Extract<GenerateReferenceImageConfig, { type: 'ip_adapter' }>;
+type ClipVisionOption = { label: ClipVisionModel; value: ClipVisionModel };
+type StyleVariantOption = { description: string; label: string; value: StyleMethod };
+type FluxReduxImageInfluenceOption = { label: string; value: FluxReduxImageInfluence };
+
+const CLIP_VISION_COLLECTION = createListCollection<ClipVisionOption>({
+  items: CLIP_VISION_MODELS.map((model) => ({ label: model, value: model })),
+});
+
+const FLUX_REDUX_IMAGE_INFLUENCE_OPTIONS: FluxReduxImageInfluenceOption[] = [
+  { label: 'Lowest', value: 'lowest' },
+  { label: 'Low', value: 'low' },
+  { label: 'Medium', value: 'medium' },
+  { label: 'High', value: 'high' },
+  { label: 'Highest', value: 'highest' },
+];
+
+const FLUX_REDUX_IMAGE_INFLUENCE_COLLECTION = createListCollection<FluxReduxImageInfluenceOption>({
+  items: FLUX_REDUX_IMAGE_INFLUENCE_OPTIONS,
+});
+
+const isFluxReduxImageInfluence = (value: unknown): value is FluxReduxImageInfluence =>
+  FLUX_REDUX_IMAGE_INFLUENCE_OPTIONS.some((option) => option.value === value);
+
+const renderStyleVariantItem = (option: StyleVariantOption) => (
+  <Stack as="span" gap="0.5" py="0.5">
+    <Text as="span" fontSize="xs">
+      {option.label}
+    </Text>
+    <Text as="span" color="fg.muted" fontSize="2xs" lineHeight="short">
+      {option.description}
+    </Text>
+  </Stack>
+);
+
+const WEIGHT_MARKS = [
+  { label: '0', value: 0 },
+  { label: '1', value: 1 },
+  { label: '2', value: 2 },
+];
+
+const BEGIN_END_MARKS = [
+  { label: '0%', value: 0 },
+  { label: '25%', value: 0.25 },
+  { label: '50%', value: 0.5 },
+  { label: '75%', value: 0.75 },
+  { label: '100%', value: 1 },
+];
+
+const SEGMENT_CHECKED_STYLES = { color: 'accent.contrast' };
+const ADVANCED_TRIGGER_HOVER_STYLES = { color: 'fg' };
+const COLLAPSIBLE_INDICATOR_OPEN_STYLES = { transform: 'rotate(90deg)' };
+
+/** Tiny muted label row above a control, with optional right-aligned content. */
+export const FieldHeader = ({ children, label }: { children?: ReactNode; label: string }) => (
+  <HStack justify="space-between" minH="4">
+    <Text color="fg.muted" fontSize="2xs" fontWeight="medium">
+      {label}
+    </Text>
+    {children}
+  </HStack>
+);
+
+/**
+ * Controls for `ip_adapter` reference image configs. `children` renders inside
+ * the Advanced section (the card passes the model selector through here).
+ */
+export const IPAdapterControls = ({
+  children,
+  config,
+  disabled,
+  onChange,
+}: {
+  children?: ReactNode;
+  config: IPAdapterConfig;
+  disabled: boolean;
+  onChange: (config: GenerateReferenceImageConfig) => void;
+}) => {
+  const { t } = useTranslation();
+  const [draftWeight, setDraftWeight] = useState<number | null>(null);
+  const [draftBeginEndStepPct, setDraftBeginEndStepPct] = useState<[number, number] | null>(null);
+  const mode = getReferenceMode(config.method);
+  const weight = draftWeight ?? config.weight;
+  const sliderWeight = Math.max(0, weight);
+  const beginEndStepPct = draftBeginEndStepPct ?? config.beginEndStepPct;
+  const styleVariantCollection = useMemo(
+    () =>
+      createListCollection<StyleVariantOption>({
+        items: STYLE_VARIANT_OPTIONS.map((option) => ({
+          description: t(option.descriptionKey),
+          label: t(option.labelKey),
+          value: option.value,
+        })),
+      }),
+    [t]
+  );
+  const styleVariantValue = useMemo<StyleMethod[]>(
+    () => [isStyleMethod(config.method) ? config.method : 'style'],
+    [config.method]
+  );
+
+  const commitWeight = useCallback(
+    (nextWeight: number) => {
+      setDraftWeight(null);
+
+      if (nextWeight !== config.weight) {
+        onChange({ ...config, weight: nextWeight });
+      }
+    },
+    [config, onChange]
+  );
+
+  const commitBeginEndStepPct = useCallback(
+    (nextBeginEndStepPct: [number, number]) => {
+      setDraftBeginEndStepPct(null);
+
+      if (
+        nextBeginEndStepPct[0] !== config.beginEndStepPct[0] ||
+        nextBeginEndStepPct[1] !== config.beginEndStepPct[1]
+      ) {
+        onChange({ ...config, beginEndStepPct: nextBeginEndStepPct });
+      }
+    },
+    [config, onChange]
+  );
+
+  const handleModeChange = useCallback(
+    ({ value }: SegmentGroup.ValueChangeDetails) => {
+      if (!isReferenceMode(value)) {
+        return;
+      }
+
+      const nextMethod: IPAdapterMethod =
+        value === 'style' ? (isStyleMethod(config.method) ? config.method : 'style') : value;
+
+      if (nextMethod !== config.method) {
+        onChange({ ...config, method: nextMethod });
+      }
+    },
+    [config, onChange]
+  );
+
+  const handleStyleVariantChange = useCallback(
+    ({ value }: SelectValueChangeDetails<StyleVariantOption>) => {
+      const nextMethod = value[0] as IPAdapterMethod | undefined;
+
+      if (nextMethod && isStyleMethod(nextMethod)) {
+        onChange({ ...config, method: nextMethod });
+      }
+    },
+    [config, onChange]
+  );
+
+  const handleWeightInputChange = useCallback(({ valueAsNumber }: NumberInput.ValueChangeDetails) => {
+    if (Number.isFinite(valueAsNumber)) {
+      setDraftWeight(valueAsNumber);
+    }
+  }, []);
+
+  const handleWeightInputBlur = useCallback(() => commitWeight(weight), [commitWeight, weight]);
+
+  const handleWeightInputKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'Enter') {
+        commitWeight(weight);
+      }
+    },
+    [commitWeight, weight]
+  );
+
+  const handleWeightSliderChange = useCallback(({ value }: SliderValueChangeDetails) => {
+    if (Number.isFinite(value[0])) {
+      setDraftWeight(value[0] as number);
+    }
+  }, []);
+
+  const handleWeightSliderChangeEnd = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      if (Number.isFinite(value[0])) {
+        commitWeight(value[0] as number);
+      }
+    },
+    [commitWeight]
+  );
+
+  const handleStepsChange = useCallback(({ value }: SliderValueChangeDetails) => {
+    const begin = value[0];
+    const end = value[1];
+
+    if (Number.isFinite(begin) && Number.isFinite(end)) {
+      setDraftBeginEndStepPct([begin as number, end as number]);
+    }
+  }, []);
+
+  const handleStepsChangeEnd = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const begin = value[0];
+      const end = value[1];
+
+      if (Number.isFinite(begin) && Number.isFinite(end)) {
+        commitBeginEndStepPct([begin as number, end as number]);
+      }
+    },
+    [commitBeginEndStepPct]
+  );
+
+  const weightSliderValue = useMemo(() => [sliderWeight], [sliderWeight]);
+  const weightAriaLabel = useMemo(() => [t('widgets.generate.weight')], [t]);
+  const stepsAriaLabel = useMemo(() => [t('widgets.generate.activeSteps'), t('widgets.generate.activeSteps')], [t]);
+
+  return (
+    <Stack gap="2">
+      <Stack gap="1">
+        <FieldHeader label={t('widgets.generate.mode')} />
+        <SegmentGroup.Root disabled={disabled} size="xs" value={mode} w="full" onValueChange={handleModeChange}>
+          <SegmentGroup.Indicator bg="accent.solid" />
+          {MODE_SEGMENTS.map((segment) => (
+            <SegmentGroup.Item
+              key={segment.value}
+              flex="1"
+              justifyContent="center"
+              value={segment.value}
+              _checked={SEGMENT_CHECKED_STYLES}
+            >
+              <SegmentGroup.ItemText fontSize="2xs">{t(segment.labelKey)}</SegmentGroup.ItemText>
+              <SegmentGroup.ItemHiddenInput />
+            </SegmentGroup.Item>
+          ))}
+        </SegmentGroup.Root>
+      </Stack>
+
+      <Field align="center" disabled={disabled} gap="3" label={t('widgets.generate.weight')} orientation="horizontal">
+        <Flex align="center" gap="3">
+          <Slider
+            aria-label={weightAriaLabel}
+            formatValue={formatWeight}
+            marks={WEIGHT_MARKS}
+            max={2}
+            min={0}
+            disabled={disabled}
+            size="sm"
+            step={0.05}
+            value={weightSliderValue}
+            onValueChange={handleWeightSliderChange}
+            onValueChangeEnd={handleWeightSliderChangeEnd}
+            w="full"
+          />
+
+          <NumberInput.Root
+            disabled={disabled}
+            max={2}
+            min={-1}
+            size="xs"
+            step={0.05}
+            value={String(weight)}
+            w="20"
+            onValueChange={handleWeightInputChange}
+          >
+            <NumberInput.Control />
+            <NumberInput.Input
+              aria-label={t('widgets.generate.weight')}
+              fontSize="xs"
+              onBlur={handleWeightInputBlur}
+              onKeyDown={handleWeightInputKeyDown}
+            />
+          </NumberInput.Root>
+        </Flex>
+      </Field>
+
+      <Collapsible.Root>
+        <Collapsible.Trigger
+          alignItems="center"
+          color="fg.muted"
+          cursor="pointer"
+          display="flex"
+          fontSize="2xs"
+          fontWeight="medium"
+          gap="1"
+          _hover={ADVANCED_TRIGGER_HOVER_STYLES}
+        >
+          <Collapsible.Indicator
+            _open={COLLAPSIBLE_INDICATOR_OPEN_STYLES}
+            transition="transform var(--wb-motion-duration-slow)"
+          >
+            <ChevronRightIcon size="12" />
+          </Collapsible.Indicator>
+          {t('widgets.generate.advanced')}
+        </Collapsible.Trigger>
+        <Collapsible.Content>
+          <Stack borderTopWidth="1px" gap="2" mt="2" pt="2">
+            {children}
+            {mode === 'style' ? (
+              <Stack gap="1">
+                <FieldHeader label={t('widgets.generate.styleVariant')} />
+                <Select
+                  collection={styleVariantCollection}
+                  deselectable={false}
+                  disabled={disabled}
+                  renderItem={renderStyleVariantItem}
+                  size="xs"
+                  value={styleVariantValue}
+                  w="full"
+                  onValueChange={handleStyleVariantChange}
+                />
+              </Stack>
+            ) : null}
+            <Stack gap="1">
+              <FieldHeader label={t('widgets.generate.activeSteps')}>
+                <Text color="fg.subtle" fontFamily="mono" fontSize="2xs">
+                  {formatPct(beginEndStepPct[0])} – {formatPct(beginEndStepPct[1])}
+                </Text>
+              </FieldHeader>
+              <Slider
+                aria-label={stepsAriaLabel}
+                disabled={disabled}
+                formatValue={formatPct}
+                marks={BEGIN_END_MARKS}
+                max={1}
+                min={0}
+                size="sm"
+                step={0.05}
+                value={beginEndStepPct}
+                onValueChange={handleStepsChange}
+                onValueChangeEnd={handleStepsChangeEnd}
+              />
+            </Stack>
+          </Stack>
+        </Collapsible.Content>
+      </Collapsible.Root>
+    </Stack>
+  );
+};
+
+export const ClipVisionSelect = ({
+  config,
+  disabled,
+  onChange,
+}: {
+  config: IPAdapterConfig;
+  disabled: boolean;
+  onChange: (config: GenerateReferenceImageConfig) => void;
+}) => {
+  const [draftClipVisionModel, setDraftClipVisionModel] = useState<ClipVisionModel | null>(null);
+  const clipVisionModel = draftClipVisionModel ?? config.clipVisionModel;
+  const selectValue = useMemo(() => [clipVisionModel], [clipVisionModel]);
+
+  const handleValueChange = useCallback(
+    ({ value }: SelectValueChangeDetails<ClipVisionOption>) => {
+      const nextClipVisionModel = value[0];
+
+      if (!isClipVisionModel(nextClipVisionModel)) {
+        return;
+      }
+
+      setDraftClipVisionModel(nextClipVisionModel);
+      globalThis.setTimeout(() => {
+        onChange({ ...config, clipVisionModel: nextClipVisionModel });
+        setDraftClipVisionModel(null);
+      }, 0);
+    },
+    [config, onChange]
+  );
+
+  return (
+    <Select
+      collection={CLIP_VISION_COLLECTION}
+      deselectable={false}
+      disabled={disabled}
+      flexShrink="0"
+      size="xs"
+      value={selectValue}
+      w="24"
+      onValueChange={handleValueChange}
+    />
+  );
+};
+
+export const FluxReduxControls = ({
+  config,
+  disabled,
+  onChange,
+}: {
+  config: Extract<GenerateReferenceImageConfig, { type: 'flux_redux' }>;
+  disabled: boolean;
+  onChange: (config: GenerateReferenceImageConfig) => void;
+}) => {
+  const { t } = useTranslation();
+  const imageInfluenceValue = useMemo(() => [config.imageInfluence], [config.imageInfluence]);
+
+  const handleValueChange = useCallback(
+    ({ value }: SelectValueChangeDetails<FluxReduxImageInfluenceOption>) => {
+      const imageInfluence = value[0];
+
+      if (!isFluxReduxImageInfluence(imageInfluence)) {
+        return;
+      }
+
+      onChange({
+        ...config,
+        imageInfluence,
+      });
+    },
+    [config, onChange]
+  );
+
+  return (
+    <Field disabled={disabled} label={t('widgets.generate.imageInfluence')}>
+      <Select
+        collection={FLUX_REDUX_IMAGE_INFLUENCE_COLLECTION}
+        deselectable={false}
+        disabled={disabled}
+        size="xs"
+        value={imageInfluenceValue}
+        w="full"
+        onValueChange={handleValueChange}
+      />
+    </Field>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageCropDialog.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageCropDialog.tsx
new file mode 100644
index 00000000000..068f4d42411
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/ReferenceImageCropDialog.tsx
@@ -0,0 +1,354 @@
+import type { GenerateReferenceImageAsset } from '@workbench/generation/types';
+import type { CSSProperties, PointerEvent } from 'react';
+
+import { Box, Dialog, Portal, Stack, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { uploadGalleryImage } from '@workbench/gallery/api';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+type CropBoxPct = { height: number; width: number; x: number; y: number };
+
+type HandleName = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+
+type DragMode = 'move' | HandleName;
+
+type DragState = { box: CropBoxPct; mode: DragMode; x: number; y: number };
+
+const FULL_CROP_BOX: CropBoxPct = { height: 100, width: 100, x: 0, y: 0 };
+
+/** Matches the legacy cropper's minimum crop dimension, in image pixels. */
+const MIN_CROP_DIMENSION_PX = 64;
+
+const HANDLES: { cursor: string; left: string; name: HandleName; top: string }[] = [
+  { cursor: 'nwse-resize', left: '0%', name: 'nw', top: '0%' },
+  { cursor: 'ns-resize', left: '50%', name: 'n', top: '0%' },
+  { cursor: 'nesw-resize', left: '100%', name: 'ne', top: '0%' },
+  { cursor: 'ew-resize', left: '100%', name: 'e', top: '50%' },
+  { cursor: 'nwse-resize', left: '100%', name: 'se', top: '100%' },
+  { cursor: 'ns-resize', left: '50%', name: 's', top: '100%' },
+  { cursor: 'nesw-resize', left: '0%', name: 'sw', top: '100%' },
+  { cursor: 'ew-resize', left: '0%', name: 'w', top: '50%' },
+];
+
+const THIRDS_OFFSETS = ['33.333%', '66.667%'];
+
+const CONTAIN_IMG_STYLE: CSSProperties = { height: '100%', objectFit: 'contain', width: '100%' };
+
+const clamp = (value: number, min: number, max: number): number => Math.min(max, Math.max(min, value));
+
+const getPointerPct = (event: PointerEvent, element: HTMLElement): { x: number; y: number } => {
+  const rect = element.getBoundingClientRect();
+
+  return {
+    x: ((event.clientX - rect.left) / rect.width) * 100,
+    y: ((event.clientY - rect.top) / rect.height) * 100,
+  };
+};
+
+const resolveDrag = (
+  drag: DragState,
+  point: { x: number; y: number },
+  minWidth: number,
+  minHeight: number
+): CropBoxPct => {
+  const dx = point.x - drag.x;
+  const dy = point.y - drag.y;
+  const box = drag.box;
+
+  if (drag.mode === 'move') {
+    return {
+      ...box,
+      x: clamp(box.x + dx, 0, 100 - box.width),
+      y: clamp(box.y + dy, 0, 100 - box.height),
+    };
+  }
+
+  let left = box.x;
+  let top = box.y;
+  let right = box.x + box.width;
+  let bottom = box.y + box.height;
+
+  if (drag.mode.includes('w')) {
+    left = clamp(left + dx, 0, right - minWidth);
+  }
+
+  if (drag.mode.includes('e')) {
+    right = clamp(right + dx, left + minWidth, 100);
+  }
+
+  if (drag.mode.includes('n')) {
+    top = clamp(top + dy, 0, bottom - minHeight);
+  }
+
+  if (drag.mode.includes('s')) {
+    bottom = clamp(bottom + dy, top + minHeight, 100);
+  }
+
+  return { height: bottom - top, width: right - left, x: left, y: top };
+};
+
+const isFullCropBox = (cropBox: CropBoxPct): boolean =>
+  cropBox.x === 0 && cropBox.y === 0 && cropBox.width === 100 && cropBox.height === 100;
+
+const isDragMode = (value: unknown): value is DragMode =>
+  value === 'move' || HANDLES.some((handle) => handle.name === value);
+
+const exportCroppedImage = async (image: GenerateReferenceImageAsset, cropBox: CropBoxPct): Promise<File> => {
+  const img = new Image();
+  img.crossOrigin = 'anonymous';
+
+  await new Promise<void>((resolve, reject) => {
+    img.onload = () => resolve();
+    img.onerror = () => reject(new Error('Failed to load reference image for cropping.'));
+    img.src = image.imageUrl;
+  });
+
+  const sourceWidth = img.naturalWidth || image.width;
+  const sourceHeight = img.naturalHeight || image.height;
+  const sx = Math.round((cropBox.x / 100) * sourceWidth);
+  const sy = Math.round((cropBox.y / 100) * sourceHeight);
+  const sw = Math.max(1, Math.round((cropBox.width / 100) * sourceWidth));
+  const sh = Math.max(1, Math.round((cropBox.height / 100) * sourceHeight));
+  const canvas = document.createElement('canvas');
+
+  canvas.width = sw;
+  canvas.height = sh;
+  canvas.getContext('2d')?.drawImage(img, sx, sy, sw, sh, 0, 0, sw, sh);
+
+  const blob = await new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (result) => (result ? resolve(result) : reject(new Error('Failed to export cropped image.'))),
+      'image/png'
+    );
+  });
+
+  return new File([blob], `${image.imageName.replace(/\.[^.]+$/, '')}-crop.png`, { type: 'image/png' });
+};
+
+export const ReferenceImageCropDialog = ({
+  image,
+  isOpen,
+  onApply,
+  onClose,
+}: {
+  image: GenerateReferenceImageAsset;
+  isOpen: boolean;
+  onApply: (image: GenerateReferenceImageAsset) => void;
+  onClose: () => void;
+}) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const [cropBox, setCropBox] = useState<CropBoxPct>(FULL_CROP_BOX);
+  const [isApplying, setIsApplying] = useState(false);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const dragRef = useRef<DragState | null>(null);
+  const ratio = image.height > 0 ? image.width / image.height : 1;
+  const minWidthPct = Math.min(100, (MIN_CROP_DIMENSION_PX / Math.max(1, image.width)) * 100);
+  const minHeightPct = Math.min(100, (MIN_CROP_DIMENSION_PX / Math.max(1, image.height)) * 100);
+  const cropWidthPx = Math.max(1, Math.round((cropBox.width / 100) * image.width));
+  const cropHeightPx = Math.max(1, Math.round((cropBox.height / 100) * image.height));
+
+  const cropBoxStyle = useMemo<CSSProperties>(
+    () => ({
+      height: `${cropBox.height}%`,
+      left: `${cropBox.x}%`,
+      top: `${cropBox.y}%`,
+      width: `${cropBox.width}%`,
+    }),
+    [cropBox]
+  );
+
+  const close = useCallback(() => {
+    if (!isApplying) {
+      setCropBox(FULL_CROP_BOX);
+      onClose();
+    }
+  }, [isApplying, onClose]);
+
+  const handleOpenChange = useCallback(
+    (event: Dialog.OpenChangeDetails) => {
+      if (!event.open) {
+        close();
+      }
+    },
+    [close]
+  );
+
+  const beginDrag = useCallback(
+    (event: PointerEvent<HTMLElement>) => {
+      const container = containerRef.current;
+      const mode = (event.currentTarget as HTMLElement).dataset.dragMode;
+
+      if (!container || !isDragMode(mode)) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      container.setPointerCapture(event.pointerId);
+      dragRef.current = { box: cropBox, mode, ...getPointerPct(event, container) };
+    },
+    [cropBox]
+  );
+
+  const moveDrag = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      const container = containerRef.current;
+      const drag = dragRef.current;
+
+      if (!container || !drag) {
+        return;
+      }
+
+      setCropBox(resolveDrag(drag, getPointerPct(event, container), minWidthPct, minHeightPct));
+    },
+    [minHeightPct, minWidthPct]
+  );
+
+  const endDrag = useCallback((event: PointerEvent<HTMLDivElement>) => {
+    dragRef.current = null;
+
+    if (containerRef.current?.hasPointerCapture(event.pointerId)) {
+      containerRef.current.releasePointerCapture(event.pointerId);
+    }
+  }, []);
+
+  const resetCrop = useCallback(() => setCropBox(FULL_CROP_BOX), []);
+
+  const applyCrop = useCallback(async () => {
+    if (isFullCropBox(cropBox)) {
+      close();
+      return;
+    }
+
+    try {
+      setIsApplying(true);
+      const file = await exportCroppedImage(image, cropBox);
+      const croppedImage = await uploadGalleryImage(file, 'none', { isIntermediate: true });
+      dispatch({ type: 'touchGalleryImagesRefresh' });
+      onApply(croppedImage);
+      setCropBox(FULL_CROP_BOX);
+      onClose();
+    } catch (error) {
+      dispatch({
+        area: 'reference-images',
+        message: error instanceof Error ? error.message : String(error),
+        namespace: 'generation',
+        type: 'recordError',
+      });
+    } finally {
+      setIsApplying(false);
+    }
+  }, [close, cropBox, dispatch, image, onApply, onClose]);
+
+  return (
+    <Dialog.Root lazyMount open={isOpen} placement="center" size="lg" unmountOnExit onOpenChange={handleOpenChange}>
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Header>
+              <Dialog.Title fontSize="sm" fontWeight="700">
+                {t('widgets.generate.cropReferenceImage')}
+              </Dialog.Title>
+            </Dialog.Header>
+            <Dialog.Body>
+              <Stack gap="3">
+                <Text color="fg.muted" fontSize="xs">
+                  {t('widgets.generate.cropReferenceImageHelp')}
+                </Text>
+                <Box
+                  ref={containerRef}
+                  aspectRatio={ratio}
+                  bg="bg.muted"
+                  maxH="60vh"
+                  overflow="hidden"
+                  position="relative"
+                  rounded="md"
+                  touchAction="none"
+                  userSelect="none"
+                  w="full"
+                  onPointerCancel={endDrag}
+                  onPointerMove={moveDrag}
+                  onPointerUp={endDrag}
+                >
+                  <img alt={image.imageName} draggable={false} src={image.imageUrl} style={CONTAIN_IMG_STYLE} />
+                  <Box
+                    borderColor="accent.solid"
+                    borderWidth="1.5px"
+                    boxShadow="0 0 0 9999px rgba(0, 0, 0, 0.45)"
+                    cursor="move"
+                    data-drag-mode="move"
+                    position="absolute"
+                    touchAction="none"
+                    style={cropBoxStyle}
+                    onPointerDown={beginDrag}
+                  >
+                    {THIRDS_OFFSETS.map((offset) => (
+                      <Box
+                        key={`v-${offset}`}
+                        bg="whiteAlpha.500"
+                        bottom="0"
+                        left={offset}
+                        pointerEvents="none"
+                        position="absolute"
+                        top="0"
+                        w="1px"
+                      />
+                    ))}
+                    {THIRDS_OFFSETS.map((offset) => (
+                      <Box
+                        key={`h-${offset}`}
+                        bg="whiteAlpha.500"
+                        h="1px"
+                        left="0"
+                        pointerEvents="none"
+                        position="absolute"
+                        right="0"
+                        top={offset}
+                      />
+                    ))}
+                    {HANDLES.map((handle) => (
+                      <Box
+                        key={handle.name}
+                        bg="white"
+                        boxShadow="0 0 0 1px rgba(0, 0, 0, 0.4), 0 1px 3px rgba(0, 0, 0, 0.5)"
+                        cursor={handle.cursor}
+                        data-drag-mode={handle.name}
+                        h="3"
+                        left={handle.left}
+                        position="absolute"
+                        rounded="xs"
+                        top={handle.top}
+                        touchAction="none"
+                        transform="translate(-50%, -50%)"
+                        w="3"
+                        onPointerDown={beginDrag}
+                      />
+                    ))}
+                  </Box>
+                </Box>
+                <Text color="fg.muted" fontFamily="mono" fontSize="2xs">
+                  {cropWidthPx} × {cropHeightPx} px
+                </Text>
+              </Stack>
+            </Dialog.Body>
+            <Dialog.Footer>
+              <Button disabled={isApplying || isFullCropBox(cropBox)} size="sm" variant="outline" onClick={resetCrop}>
+                {t('common.reset')}
+              </Button>
+              <Button disabled={isApplying} size="sm" variant="outline" onClick={close}>
+                {t('common.cancel')}
+              </Button>
+              <Button loading={isApplying} size="sm" onClick={applyCrop}>
+                {t('common.apply')}
+              </Button>
+            </Dialog.Footer>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/referenceImageConfig.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/referenceImageConfig.ts
new file mode 100644
index 00000000000..11dccdfba62
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/reference-images/referenceImageConfig.ts
@@ -0,0 +1,50 @@
+import type { ClipVisionModel, IPAdapterMethod } from '@workbench/generation/types';
+
+/** The coarse mode shown in the segmented control. `style` covers all style method variants. */
+export type ReferenceMode = 'style' | 'composition' | 'full';
+
+export type StyleMethod = Extract<IPAdapterMethod, 'style' | 'style_strong' | 'style_precise'>;
+
+export const MODE_SEGMENTS: { labelKey: string; value: ReferenceMode }[] = [
+  { labelKey: 'widgets.generate.modeStyle', value: 'style' },
+  { labelKey: 'widgets.generate.modeComposition', value: 'composition' },
+  { labelKey: 'widgets.generate.modeBoth', value: 'full' },
+];
+
+export const STYLE_VARIANT_OPTIONS: { descriptionKey: string; labelKey: string; value: StyleMethod }[] = [
+  {
+    descriptionKey: 'widgets.generate.styleVariantStandardDesc',
+    labelKey: 'widgets.generate.styleVariantStandard',
+    value: 'style',
+  },
+  {
+    descriptionKey: 'widgets.generate.styleVariantStrongDesc',
+    labelKey: 'widgets.generate.styleVariantStrong',
+    value: 'style_strong',
+  },
+  {
+    descriptionKey: 'widgets.generate.styleVariantPreciseDesc',
+    labelKey: 'widgets.generate.styleVariantPrecise',
+    value: 'style_precise',
+  },
+];
+
+export const CLIP_VISION_MODELS: ClipVisionModel[] = ['ViT-H', 'ViT-G', 'ViT-L'];
+
+export const isReferenceMode = (value: unknown): value is ReferenceMode =>
+  value === 'style' || value === 'composition' || value === 'full';
+
+export const isStyleMethod = (method: IPAdapterMethod): method is StyleMethod =>
+  method === 'style' || method === 'style_strong' || method === 'style_precise';
+
+export const getReferenceMode = (method: IPAdapterMethod): ReferenceMode => (isStyleMethod(method) ? 'style' : method);
+
+export const getModeLabelKey = (method: IPAdapterMethod): string =>
+  MODE_SEGMENTS.find((segment) => segment.value === getReferenceMode(method))?.labelKey ?? '';
+
+export const isClipVisionModel = (value: unknown): value is ClipVisionModel =>
+  typeof value === 'string' && CLIP_VISION_MODELS.includes(value as ClipVisionModel);
+
+export const formatWeight = (value: number): string => value.toFixed(2);
+
+export const formatPct = (value: number): string => `${Math.round(value * 100)}%`;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/AspectRatioPreview.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/AspectRatioPreview.tsx
new file mode 100644
index 00000000000..274a12ded20
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/AspectRatioPreview.tsx
@@ -0,0 +1,30 @@
+import { Box, Flex } from '@chakra-ui/react';
+
+type Props = {
+  ratio: number; // e.g. 16 / 9
+  boxSize?: string | number;
+};
+
+export const AspectRatioPreview = ({ boxSize = '8', ratio }: Props) => {
+  const normalizedRatio = Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+  const isWide = normalizedRatio >= 1;
+
+  return (
+    <Flex as="span" alignItems="center" boxSize={boxSize} flexShrink={0} justifyContent="center" p="0.5">
+      <Box
+        as="span"
+        aria-hidden="true"
+        bg="bg.subtle"
+        borderColor="fg.muted"
+        borderStyle="dashed"
+        borderWidth="1px"
+        display="block"
+        h={isWide ? `${100 / normalizedRatio}%` : 'full'}
+        minH="1px"
+        minW="1px"
+        rounded="2px"
+        w={isWide ? 'full' : `${normalizedRatio * 100}%`}
+      />
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/GenerateCollapsibleSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/GenerateCollapsibleSection.tsx
new file mode 100644
index 00000000000..33ab3344f14
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/GenerateCollapsibleSection.tsx
@@ -0,0 +1,48 @@
+import { Box, Collapsible, Flex, Text } from '@chakra-ui/react';
+import { ChevronRightIcon } from 'lucide-react';
+
+type Props = {
+  label: string;
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  badges?: React.ReactNode;
+  children: React.ReactNode;
+};
+
+const COLLAPSIBLE_INDICATOR_OPEN_STYLES = { transform: 'rotate(90deg)' };
+
+export const GenerateCollapsibleSection = ({ label, defaultOpen, isOpen, children, badges }: Props) => {
+  return (
+    <Collapsible.Root defaultOpen={defaultOpen} open={isOpen} bg="bg.muted/50" rounded="md" overflow="hidden">
+      <Collapsible.Trigger display="flex" gap={2} w="full" px={2} h="8" alignItems="center">
+        <Collapsible.Indicator
+          _open={COLLAPSIBLE_INDICATOR_OPEN_STYLES}
+          transition="transform var(--wb-motion-duration-slow)"
+        >
+          <ChevronRightIcon size="14" />
+        </Collapsible.Indicator>
+        <Text
+          as="span"
+          fontSize="2xs"
+          truncate
+          letterSpacing="widest"
+          fontWeight="bold"
+          textTransform="uppercase"
+          color="fg.muted"
+          lineHeight="1"
+        >
+          {label}
+        </Text>
+
+        <Flex gap={1} ml="auto" fontFamily="mono">
+          {badges}
+        </Flex>
+      </Collapsible.Trigger>
+      <Collapsible.Content bg="bg.muted">
+        <Box borderTopWidth={1} borderColor="bg.subtle">
+          {children}
+        </Box>
+      </Collapsible.Content>
+    </Collapsible.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/ModelDefaultButton.tsx b/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/ModelDefaultButton.tsx
new file mode 100644
index 00000000000..fedca8e97a1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/shared/ModelDefaultButton.tsx
@@ -0,0 +1,44 @@
+import { Icon } from '@chakra-ui/react';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { SparklesIcon } from 'lucide-react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export const ModelDefaultButton = ({
+  active,
+  disabled,
+  label,
+  onClick,
+}: {
+  active?: boolean;
+  disabled?: boolean;
+  label?: string;
+  onClick: () => void;
+}) => {
+  const { t } = useTranslation();
+  const resolvedLabel = label ?? t('widgets.generate.useModelDefault');
+  const isActive = active ?? !disabled;
+  const handleClick = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      event.preventDefault();
+      event.stopPropagation();
+      onClick();
+    },
+    [onClick]
+  );
+
+  return (
+    <Tooltip content={resolvedLabel}>
+      <IconButton
+        aria-label={resolvedLabel}
+        colorPalette={isActive ? 'brand' : undefined}
+        disabled={disabled}
+        size="2xs"
+        variant="ghost"
+        onClick={handleClick}
+      >
+        <Icon as={SparklesIcon} boxSize="2.5" />
+      </IconButton>
+    </Tooltip>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/generate/useDebouncedDraftValue.ts b/invokeai/frontend/webv2/src/workbench/widgets/generate/useDebouncedDraftValue.ts
new file mode 100644
index 00000000000..77c9cd3b8ca
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/generate/useDebouncedDraftValue.ts
@@ -0,0 +1,145 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+interface UseDebouncedDraftValueOptions<Value> {
+  value: Value;
+  delayMs: number;
+  onCommit: (value: Value) => void;
+  isEqual?: (left: Value, right: Value) => boolean;
+  flushOnUnmount?: boolean;
+  resetKey?: string;
+}
+
+interface DebouncedDraftValue<Value> {
+  draftValue: Value;
+  setDraftValue: (value: Value) => void;
+  commitDraftValue: (value: Value) => void;
+  replaceDraftValue: (value: Value) => void;
+  flushDraftValue: () => void;
+  hasPendingDraft: () => boolean;
+}
+
+export const useDebouncedDraftValue = <Value>({
+  delayMs,
+  flushOnUnmount = true,
+  isEqual = Object.is,
+  onCommit,
+  resetKey,
+  value,
+}: UseDebouncedDraftValueOptions<Value>): DebouncedDraftValue<Value> => {
+  const [draftValue, setDraftValueState] = useState(value);
+  const draftValueRef = useRef(value);
+  const sourceValueRef = useRef(value);
+  const resetKeyRef = useRef(resetKey);
+  const hasPendingDraftRef = useRef(false);
+  const pendingDraftRef = useRef<Value | null>(null);
+  const timeoutRef = useRef<number | null>(null);
+  const flushOnUnmountRef = useRef(flushOnUnmount);
+  const onCommitRef = useRef(onCommit);
+
+  useEffect(() => {
+    flushOnUnmountRef.current = flushOnUnmount;
+    onCommitRef.current = onCommit;
+  });
+
+  const setDraft = (nextValue: Value) => {
+    draftValueRef.current = nextValue;
+    setDraftValueState(nextValue);
+  };
+
+  const clearPendingCommit = () => {
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  };
+
+  const clearPendingDraft = () => {
+    clearPendingCommit();
+    hasPendingDraftRef.current = false;
+    pendingDraftRef.current = null;
+  };
+
+  const flushDraftValue = () => {
+    if (!hasPendingDraftRef.current) {
+      return;
+    }
+
+    const valueToCommit = pendingDraftRef.current as Value;
+
+    clearPendingDraft();
+    onCommitRef.current(valueToCommit);
+  };
+
+  useLayoutEffect(() => {
+    if (resetKeyRef.current !== resetKey) {
+      resetKeyRef.current = resetKey;
+      clearPendingDraft();
+      sourceValueRef.current = value;
+      setDraft(value);
+      return;
+    }
+
+    if (isEqual(sourceValueRef.current, value)) {
+      return;
+    }
+
+    sourceValueRef.current = value;
+
+    if (!hasPendingDraftRef.current) {
+      setDraft(value);
+      return;
+    }
+
+    if (isEqual(pendingDraftRef.current as Value, value)) {
+      clearPendingDraft();
+      setDraft(value);
+      return;
+    }
+
+    clearPendingDraft();
+    setDraft(value);
+  }, [isEqual, resetKey, value]);
+
+  useEffect(
+    () => () => {
+      clearPendingCommit();
+
+      if (flushOnUnmountRef.current) {
+        flushDraftValue();
+        return;
+      }
+
+      clearPendingDraft();
+    },
+    []
+  );
+
+  const setDraftValue = (nextValue: Value) => {
+    setDraft(nextValue);
+    hasPendingDraftRef.current = true;
+    pendingDraftRef.current = nextValue;
+    clearPendingCommit();
+
+    timeoutRef.current = window.setTimeout(flushDraftValue, delayMs);
+  };
+
+  const commitDraftValue = (nextValue: Value) => {
+    clearPendingDraft();
+    setDraft(nextValue);
+    onCommitRef.current(nextValue);
+  };
+
+  const replaceDraftValue = (nextValue: Value) => {
+    clearPendingDraft();
+    setDraft(nextValue);
+  };
+
+  return {
+    commitDraftValue,
+    draftValue,
+    flushDraftValue,
+    hasPendingDraft: () => hasPendingDraftRef.current,
+    replaceDraftValue,
+    setDraftValue,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/AdjustmentsPopover.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/AdjustmentsPopover.tsx
new file mode 100644
index 00000000000..06971e4dc23
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/AdjustmentsPopover.tsx
@@ -0,0 +1,511 @@
+import type { SliderValueChangeDetails } from '@chakra-ui/react';
+import type { CanvasAdjustmentsContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+import type { CanvasStructuralEngine } from '@workbench/widgets/layers/layerOps';
+import type { PointerEvent as ReactPointerEvent } from 'react';
+
+import { createListCollection, HStack, Stack, Text } from '@chakra-ui/react';
+import { DEFAULT_ADJUSTMENTS, buildCurveLut } from '@workbench/canvas-engine/render/adjustments';
+import { Button, Field, Select, Slider } from '@workbench/components/ui';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import {
+  CURVE_PADDING,
+  CURVE_SIZE,
+  curvePointFromSvg,
+  curvePointToSvg,
+  finishCurveDragResult,
+  getCurveGridCoordinates,
+} from './curveEditorMath';
+import { applyStructural, applyStructuralPreview } from './layerOps';
+
+const SELECT_POSITIONING = { placement: 'bottom-end', sameWidth: false } as const;
+
+type CurveChannel = 'r' | 'g' | 'b';
+const CURVE_CHANNELS: readonly CurveChannel[] = ['r', 'g', 'b'];
+
+/** The identity curve control points (diagonal). */
+const IDENTITY_CURVE: [number, number][] = [
+  [0, 0],
+  [255, 255],
+];
+
+const withCurve = (
+  base: CanvasAdjustmentsContract,
+  channel: CurveChannel,
+  points: [number, number][]
+): CanvasAdjustmentsContract => ({
+  ...base,
+  curves: {
+    b: base.curves?.b ?? IDENTITY_CURVE,
+    g: base.curves?.g ?? IDENTITY_CURVE,
+    r: base.curves?.r ?? IDENTITY_CURVE,
+    [channel]: points,
+  },
+});
+
+const formatSigned = (value: number): string => `${value > 0 ? '+' : ''}${Math.round(value * 100)}`;
+
+interface AdjustmentsPopoverProps {
+  engine: CanvasStructuralEngine | null;
+  layer: CanvasRasterLayerContractV2;
+}
+
+/**
+ * Non-destructive raster-adjustment editor (plan §1.3): brightness / contrast /
+ * saturation sliders plus a minimal per-channel curves editor and a reset. All
+ * edits patch the layer's `adjustments` through the canvas undo stack
+ * (`applyStructural` → `updateCanvasLayerConfig`); sliders use the same
+ * draft/commit pattern as opacity (one history entry per drag). The curve math
+ * lives in the pure `render/adjustments` module — this component only manages
+ * control points and previews the LUT.
+ *
+ * Rendered inline inside the per-layer properties popover (round 3): a nested
+ * popover would be an "outside interaction" for its parent and close it, so this
+ * renders as a plain section rather than its own popover.
+ */
+export const AdjustmentsPopover = ({ engine, layer }: AdjustmentsPopoverProps) => {
+  const adjustments = layer.adjustments ?? DEFAULT_ADJUSTMENTS;
+  return <AdjustmentsControls adjustments={adjustments} engine={engine} layer={layer} />;
+};
+
+interface AdjustmentsControlsProps {
+  adjustments: CanvasAdjustmentsContract;
+  engine: CanvasStructuralEngine | null;
+  layer: CanvasRasterLayerContractV2;
+}
+
+type ScalarKey = 'brightness' | 'contrast' | 'saturation';
+
+const AdjustmentsControls = ({ adjustments, engine, layer }: AdjustmentsControlsProps) => {
+  const { t } = useTranslation();
+  const dispatch = useCanvasProjectMutationDispatch();
+
+  const patchLive = useCallback(
+    (next: CanvasAdjustmentsContract) => {
+      applyStructuralPreview(engine, dispatch, {
+        config: { adjustments: next, layerType: 'raster' },
+        id: layer.id,
+        type: 'updateCanvasLayerConfig',
+      });
+    },
+    [dispatch, engine, layer.id]
+  );
+
+  const commit = useCallback(
+    (label: string, next: CanvasAdjustmentsContract, before: CanvasAdjustmentsContract) => {
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { config: { adjustments: next, layerType: 'raster' }, id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: { adjustments: before, layerType: 'raster' }, id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, engine, layer.id]
+  );
+
+  const handleScalarLive = useCallback(
+    (key: ScalarKey, next: number) => patchLive({ ...adjustments, [key]: next }),
+    [adjustments, patchLive]
+  );
+
+  const handleScalarCommit = useCallback(
+    (label: string, key: ScalarKey, next: number, before: CanvasAdjustmentsContract) => {
+      commit(label, { ...before, [key]: next }, before);
+    },
+    [commit]
+  );
+
+  const handleReset = useCallback(() => {
+    commit(t('widgets.layers.adjustments.reset'), { ...DEFAULT_ADJUSTMENTS }, adjustments);
+  }, [adjustments, commit, t]);
+
+  // Live (render-only) during a curve-point drag: preview without pushing history.
+  const handleCurveLive = useCallback(
+    (channel: CurveChannel, points: [number, number][]) => {
+      patchLive(withCurve(adjustments, channel, points));
+    },
+    [adjustments, patchLive]
+  );
+
+  const handleCurveCancel = useCallback((before: CanvasAdjustmentsContract) => patchLive(before), [patchLive]);
+
+  // Single history entry per gesture (drag end, click-add, dbl-click-remove). The
+  // `before` snapshot is captured at gesture start by the editor (during a drag
+  // `adjustments` has already advanced via the live previews), so it undoes the
+  // WHOLE gesture rather than the last frame.
+  const handleCurveCommit = useCallback(
+    (current: CanvasAdjustmentsContract, before: CanvasAdjustmentsContract) => {
+      commit(t('widgets.layers.adjustments.curves'), current, before);
+    },
+    [commit, t]
+  );
+
+  return (
+    <Stack gap="3">
+      <AdjustmentSlider
+        adjustments={adjustments}
+        adjustmentKey="brightness"
+        label={t('widgets.layers.adjustments.brightness')}
+        onCommit={handleScalarCommit}
+        onLive={handleScalarLive}
+      />
+      <AdjustmentSlider
+        adjustments={adjustments}
+        adjustmentKey="contrast"
+        label={t('widgets.layers.adjustments.contrast')}
+        onCommit={handleScalarCommit}
+        onLive={handleScalarLive}
+      />
+      <AdjustmentSlider
+        adjustments={adjustments}
+        adjustmentKey="saturation"
+        label={t('widgets.layers.adjustments.saturation')}
+        onCommit={handleScalarCommit}
+        onLive={handleScalarLive}
+      />
+      <CurvesEditor
+        adjustments={adjustments}
+        onCancel={handleCurveCancel}
+        onCommit={handleCurveCommit}
+        onLive={handleCurveLive}
+      />
+      <Button size="xs" variant="ghost" onClick={handleReset}>
+        {t('widgets.layers.adjustments.reset')}
+      </Button>
+    </Stack>
+  );
+};
+
+interface AdjustmentSliderProps {
+  label: string;
+  adjustmentKey: ScalarKey;
+  adjustments: CanvasAdjustmentsContract;
+  onLive: (key: ScalarKey, next: number) => void;
+  onCommit: (label: string, key: ScalarKey, next: number, before: CanvasAdjustmentsContract) => void;
+}
+
+/** A single -1..1 adjustment slider owning its own draft/before (one history entry per drag). */
+const AdjustmentSlider = ({ adjustmentKey, adjustments, label, onCommit, onLive }: AdjustmentSliderProps) => {
+  const beforeRef = useRef<CanvasAdjustmentsContract | null>(null);
+  const value = adjustments[adjustmentKey] ?? 0;
+  const sliderValue = useMemo(() => [value], [value]);
+  const aria = useMemo(() => [label], [label]);
+
+  const handleChange = useCallback(
+    ({ value: v }: SliderValueChangeDetails) => {
+      const next = v[0];
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      if (beforeRef.current === null) {
+        beforeRef.current = adjustments;
+      }
+      onLive(adjustmentKey, next);
+    },
+    [adjustmentKey, adjustments, onLive]
+  );
+
+  const handleChangeEnd = useCallback(
+    ({ value: v }: SliderValueChangeDetails) => {
+      const next = v[0];
+      const before = beforeRef.current ?? adjustments;
+      beforeRef.current = null;
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      onCommit(label, adjustmentKey, next, before);
+    },
+    [adjustmentKey, adjustments, label, onCommit]
+  );
+
+  return (
+    <Field label={label}>
+      <Slider
+        aria-label={aria}
+        formatValue={formatSigned}
+        max={1}
+        min={-1}
+        size="sm"
+        step={0.01}
+        value={sliderValue}
+        withThumbTooltip
+        onValueChange={handleChange}
+        onValueChangeEnd={handleChangeEnd}
+      />
+    </Field>
+  );
+};
+
+interface CurvesEditorProps {
+  adjustments: CanvasAdjustmentsContract;
+  /** Render-only preview during a point drag (no history entry). */
+  onLive: (channel: CurveChannel, points: [number, number][]) => void;
+  /** Restores the pre-drag snapshot when the browser cancels a gesture. */
+  onCancel: (before: CanvasAdjustmentsContract) => void;
+  /** Commits one history entry for a completed gesture, undoing to `before`. */
+  onCommit: (current: CanvasAdjustmentsContract, before: CanvasAdjustmentsContract) => void;
+}
+
+/** A compact per-channel curves editor (SVG): drag points, click to add, double-click to remove. */
+const CurvesEditor = ({ adjustments, onCancel, onCommit, onLive }: CurvesEditorProps) => {
+  const { t } = useTranslation();
+  const [channel, setChannel] = useState<CurveChannel>('r');
+  const dragIndexRef = useRef<number | null>(null);
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  // A point drag streams render-only previews; `beforeRef` snapshots the
+  // adjustments at drag start and `latestPointsRef` holds the last previewed
+  // points, so pointer-up commits the whole drag as ONE history entry (mirrors
+  // the scalar sliders' live/commit split — no per-frame undo-stack flooding).
+  const beforeRef = useRef<CanvasAdjustmentsContract | null>(null);
+  const latestPointsRef = useRef<[number, number][] | null>(null);
+  const dragTargetRef = useRef<Element | null>(null);
+
+  const points = useMemo<[number, number][]>(() => {
+    const raw = adjustments.curves?.[channel];
+    return raw && raw.length >= 2 ? [...raw].map(([x, y]) => [x, y] as [number, number]) : [...IDENTITY_CURVE];
+  }, [adjustments.curves, channel]);
+
+  const channelCollection = useMemo(
+    () =>
+      createListCollection({
+        items: CURVE_CHANNELS.map((c) => ({ label: t(`widgets.layers.adjustments.channels.${c}`), value: c })),
+      }),
+    [t]
+  );
+
+  const svgPointFromEvent = (event: ReactPointerEvent<SVGElement>): { px: number; py: number } => {
+    const svg = svgRef.current;
+    if (!svg) {
+      return { px: 0, py: 0 };
+    }
+    const rect = svg.getBoundingClientRect();
+    return {
+      px: ((event.clientX - rect.left) / rect.width) * CURVE_SIZE,
+      py: ((event.clientY - rect.top) / rect.height) * CURVE_SIZE,
+    };
+  };
+
+  const lutPath = useMemo(() => {
+    const lut = buildCurveLut(points);
+    let d = '';
+    for (let i = 0; i < 256; i += 4) {
+      const { cx, cy } = curvePointToSvg(i, lut[i]);
+      d += `${i === 0 ? 'M' : 'L'}${cx.toFixed(1)},${cy.toFixed(1)} `;
+    }
+    return d.trim();
+  }, [points]);
+  const gridCoordinates = getCurveGridCoordinates();
+
+  const handleChannelChange = useCallback(
+    ({ value }: { value: string[] }) => setChannel((value[0] as CurveChannel) ?? 'r'),
+    []
+  );
+
+  const handlePointDown = (index: number) => (event: ReactPointerEvent<SVGCircleElement>) => {
+    event.stopPropagation();
+    event.currentTarget.setPointerCapture(event.pointerId);
+    dragIndexRef.current = index;
+    dragTargetRef.current = event.currentTarget;
+    // Snapshot the pre-drag state once, for a single whole-drag history entry.
+    beforeRef.current = adjustments;
+    latestPointsRef.current = null;
+  };
+
+  const handleMove = (event: ReactPointerEvent<SVGSVGElement>) => {
+    const index = dragIndexRef.current;
+    if (index === null) {
+      return;
+    }
+    const { px, py } = svgPointFromEvent(event);
+    const [nx, ny] = curvePointFromSvg(px, py);
+    const isEndpoint = index === 0 || index === points.length - 1;
+    const next = points.map((p, i) => {
+      if (i !== index) {
+        return p;
+      }
+      // Endpoints keep their x anchored (0 / 255); only y moves.
+      return isEndpoint ? ([p[0], ny] as [number, number]) : ([nx, ny] as [number, number]);
+    });
+    // Keep interior x within its neighbours to preserve monotonic ordering.
+    if (!isEndpoint) {
+      const lo = next[index - 1][0] + 1;
+      const hi = next[index + 1][0] - 1;
+      next[index] = [Math.max(lo, Math.min(hi, next[index][0])), next[index][1]];
+    }
+    latestPointsRef.current = next;
+    onLive(channel, next);
+  };
+
+  const finishDrag = (event: ReactPointerEvent<SVGSVGElement>, cancelled: boolean) => {
+    const wasDragging = dragIndexRef.current !== null;
+    const dragTarget = dragTargetRef.current;
+    if (dragTarget?.hasPointerCapture(event.pointerId)) {
+      dragTarget.releasePointerCapture(event.pointerId);
+    }
+    dragIndexRef.current = null;
+    dragTargetRef.current = null;
+    // Commit the whole drag as one history entry (only if the point actually
+    // moved — a click with no move streams no previews and needs no commit).
+    const before = beforeRef.current;
+    const finalPoints = latestPointsRef.current;
+    beforeRef.current = null;
+    latestPointsRef.current = null;
+    if (wasDragging && before && finalPoints) {
+      finishCurveDragResult({
+        before,
+        cancelled,
+        current: withCurve(before, channel, finalPoints),
+        onCommit: (current) => onCommit(current, before),
+        onPreview: onCancel,
+      });
+    }
+  };
+
+  const handleUp = (event: ReactPointerEvent<SVGSVGElement>) => finishDrag(event, false);
+  const handleCancel = (event: ReactPointerEvent<SVGSVGElement>) => finishDrag(event, true);
+
+  const handleAdd = (event: ReactPointerEvent<SVGSVGElement>) => {
+    if (dragIndexRef.current !== null) {
+      return;
+    }
+    const { px, py } = svgPointFromEvent(event);
+    const [nx, ny] = curvePointFromSvg(px, py);
+    if (nx <= 0 || nx >= 255) {
+      return;
+    }
+    const next = [...points, [nx, ny] as [number, number]].sort((a, b) => a[0] - b[0]);
+    onCommit(withCurve(adjustments, channel, next), adjustments);
+  };
+
+  const handleRemove = (index: number) => (event: ReactPointerEvent<SVGCircleElement>) => {
+    event.stopPropagation();
+    if (index === 0 || index === points.length - 1 || points.length <= 2) {
+      return;
+    }
+    onCommit(
+      withCurve(
+        adjustments,
+        channel,
+        points.filter((_, i) => i !== index)
+      ),
+      adjustments
+    );
+  };
+
+  const channelValue = useMemo(() => [channel], [channel]);
+
+  return (
+    <Stack gap="2">
+      <HStack justify="space-between">
+        <Text fontSize="xs" fontWeight="medium">
+          {t('widgets.layers.adjustments.curves')}
+        </Text>
+        <Select
+          aria-label={t('widgets.layers.adjustments.channel')}
+          collection={channelCollection}
+          positioning={SELECT_POSITIONING}
+          size="xs"
+          value={channelValue}
+          valueText={t(`widgets.layers.adjustments.channels.${channel}`)}
+          w="6rem"
+          onValueChange={handleChannelChange}
+        />
+      </HStack>
+      <svg
+        height={CURVE_SIZE}
+        onDoubleClick={handleAdd}
+        onPointerCancel={handleCancel}
+        onPointerMove={handleMove}
+        onPointerUp={handleUp}
+        ref={svgRef}
+        style={{
+          background: 'var(--chakra-colors-bg-inset)',
+          borderRadius: 4,
+          touchAction: 'none',
+          width: '100%',
+        }}
+        viewBox={`0 0 ${CURVE_SIZE} ${CURVE_SIZE}`}
+      >
+        <rect
+          fill="var(--chakra-colors-bg-inset)"
+          height={CURVE_SIZE - CURVE_PADDING * 2}
+          width={CURVE_SIZE - CURVE_PADDING * 2}
+          x={CURVE_PADDING}
+          y={CURVE_PADDING}
+        />
+        <g stroke="var(--chakra-colors-fg-grid)">
+          {gridCoordinates.map((coordinate) => (
+            <g key={coordinate}>
+              <line
+                vectorEffect="non-scaling-stroke"
+                x1={coordinate}
+                x2={coordinate}
+                y1={CURVE_PADDING}
+                y2={CURVE_SIZE - CURVE_PADDING}
+              />
+              <line
+                vectorEffect="non-scaling-stroke"
+                x1={CURVE_PADDING}
+                x2={CURVE_SIZE - CURVE_PADDING}
+                y1={coordinate}
+                y2={coordinate}
+              />
+            </g>
+          ))}
+        </g>
+        <rect
+          fill="none"
+          height={CURVE_SIZE - CURVE_PADDING * 2}
+          stroke="var(--chakra-colors-border-emphasized)"
+          vectorEffect="non-scaling-stroke"
+          width={CURVE_SIZE - CURVE_PADDING * 2}
+          x={CURVE_PADDING}
+          y={CURVE_PADDING}
+        />
+        <line
+          stroke="var(--chakra-colors-fg-muted)"
+          strokeDasharray="4 4"
+          vectorEffect="non-scaling-stroke"
+          x1={CURVE_PADDING}
+          x2={CURVE_SIZE - CURVE_PADDING}
+          y1={CURVE_SIZE - CURVE_PADDING}
+          y2={CURVE_PADDING}
+        />
+        <path
+          d={lutPath}
+          fill="none"
+          stroke="var(--chakra-colors-accent-solid)"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth={2}
+          vectorEffect="non-scaling-stroke"
+        />
+        {points.map((p, i) => {
+          const { cx, cy } = curvePointToSvg(p[0], p[1]);
+          return (
+            <circle
+              cx={cx}
+              cy={cy}
+              fill="var(--chakra-colors-accent-solid)"
+              key={i}
+              onContextMenu={(e) => e.preventDefault()}
+              onDoubleClick={handleRemove(i)}
+              onPointerDown={handlePointDown(i)}
+              r={5}
+              stroke="var(--chakra-colors-bg-inset)"
+              strokeWidth={2}
+              style={{ cursor: 'pointer' }}
+              vectorEffect="non-scaling-stroke"
+            />
+          );
+        })}
+      </svg>
+      <Text color="fg.muted" fontSize="2xs">
+        {t('widgets.layers.adjustments.curvesHint')}
+      </Text>
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/ControlLayerSettings.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/ControlLayerSettings.tsx
new file mode 100644
index 00000000000..0f5a61fe245
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/ControlLayerSettings.tsx
@@ -0,0 +1,447 @@
+import type {
+  NumberInput as ChakraNumberInput,
+  SelectValueChangeDetails,
+  SliderValueChangeDetails,
+} from '@chakra-ui/react';
+import type { CanvasDocumentCapability } from '@workbench/canvas-engine/api';
+import type { ControlAdapterKind } from '@workbench/generation/canvas/addControlLayers';
+import type { CanvasControlAdapterContract, CanvasControlLayerContract } from '@workbench/types';
+import type { LayerFilterOperationEngine } from '@workbench/widgets/layers/LayerFilterOperationButton';
+import type { CanvasStructuralEngine } from '@workbench/widgets/layers/layerOps';
+
+import { createListCollection, HStack, NumberInput, Stack, Switch, Text } from '@chakra-ui/react';
+import { getCanvasOperations } from '@workbench/canvas-operations/createCanvasEngine';
+import { Field, Select, Slider } from '@workbench/components/ui';
+import { isControlKindSupportedForBase } from '@workbench/generation/canvas/addControlLayers';
+import { resolveDefaultFilterForModel } from '@workbench/generation/canvas/controlRecommendations';
+import { getControlValidationReason } from '@workbench/generation/canvas/controlValidation';
+import { useModelsSelector } from '@workbench/models/modelsStore';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useCallback, useMemo, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { getCompatibleControlModels } from './controlModelOptions';
+import { LayerFilterOperationButton } from './LayerFilterOperationButton';
+import { applyStructural, applyStructuralPreview, CONTROL_ADAPTER_DEFAULTS, CONTROL_WEIGHT_BOUNDS } from './layerOps';
+import { runLayerFilterOperation } from './layerPropertiesOperation';
+
+const SELECT_POSITIONING = { placement: 'bottom-end', sameWidth: false } as const;
+
+const CONTROL_ADAPTER_KINDS: readonly ControlAdapterKind[] = [
+  'controlnet',
+  't2i_adapter',
+  'control_lora',
+  'z_image_control',
+];
+const CONTROL_MODES: readonly NonNullable<CanvasControlAdapterContract['controlMode']>[] = [
+  'balanced',
+  'more_prompt',
+  'more_control',
+  'unbalanced',
+];
+
+const formatUnitPercent = (value: number): string => `${Math.round(value * 100)}%`;
+const formatWeight = (value: number): string => value.toFixed(2);
+
+/** The main model's base, read from the generate widget values (drives adapter support). */
+const useSelectedMainModel = () => {
+  const modelKey = useActiveProjectSelector((project) => {
+    const values = getProjectWidgetValues(project, 'generate');
+    const model = values?.model;
+    return model && typeof model === 'object' && 'key' in model ? String((model as { key: unknown }).key) : null;
+  });
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  return useMemo(() => models.find((model) => model.key === modelKey) ?? null, [models, modelKey]);
+};
+
+interface ControlLayerSettingsProps {
+  engine:
+    | (CanvasStructuralEngine & LayerFilterOperationEngine & { readonly document: CanvasDocumentCapability })
+    | null;
+  layer: CanvasControlLayerContract;
+  onOperationStarted(): void;
+}
+
+/**
+ * Per-layer settings for a selected control layer (plan §1.3): adapter kind +
+ * model, weight, begin/end step range, control mode (ControlNet only), the
+ * transparency effect toggle, and a non-destructive filter section (type +
+ * per-type settings + preview/apply/cancel). Adapter edits go through the canvas
+ * undo stack (`updateCanvasLayerConfig`); the filter preview runs on the utility
+ * queue and never mutates the document until "Apply".
+ */
+export const ControlLayerSettings = ({ engine, layer, onOperationStarted }: ControlLayerSettingsProps) => {
+  const { t } = useTranslation();
+  const dispatch = useCanvasProjectMutationDispatch();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const mainModel = useSelectedMainModel();
+  const base = mainModel?.base ?? null;
+  const { adapter } = layer;
+  const weightInputMin = adapter.kind === 'z_image_control' ? 0 : CONTROL_WEIGHT_BOUNDS.inputMin;
+
+  const commitAdapter = useCallback(
+    (next: Partial<CanvasControlAdapterContract>, before: Partial<CanvasControlAdapterContract>, label: string) => {
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { config: { adapter: next, layerType: 'control' }, id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: { adapter: before, layerType: 'control' }, id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, engine, layer.id]
+  );
+
+  // Adapter kinds supported by the selected base. Z-Image Control is only shown
+  // when a compatible Z-Image main model is selected.
+  const kindOptions = useMemo(
+    () =>
+      CONTROL_ADAPTER_KINDS.filter((kind) =>
+        base ? isControlKindSupportedForBase(base, kind) : kind !== 'z_image_control'
+      ),
+    [base]
+  );
+  const kindCollection = useMemo(
+    () =>
+      createListCollection({
+        items: kindOptions.map((kind) => ({ label: t(`widgets.layers.control.kinds.${kind}`), value: kind })),
+      }),
+    [kindOptions, t]
+  );
+
+  // Adapter models matching the current kind + base (mirrors the generate model list).
+  const modelOptions = useMemo(
+    () => getCompatibleControlModels(models, base, adapter.kind),
+    [adapter.kind, base, models]
+  );
+  const modelCollection = useMemo(
+    () => createListCollection({ items: modelOptions.map((model) => ({ label: model.name, value: model.key })) }),
+    [modelOptions]
+  );
+
+  const handleKindChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const kind = value[0] as ControlAdapterKind | undefined;
+      if (!kind || kind === adapter.kind) {
+        return;
+      }
+      // Switching kind clears the model (its base/type no longer matches) and, for
+      // non-ControlNet kinds, drops the control mode.
+      const defaults = CONTROL_ADAPTER_DEFAULTS[kind];
+      commitAdapter(
+        { ...defaults, beginEndStepPct: [...defaults.beginEndStepPct] },
+        { ...adapter, beginEndStepPct: [...adapter.beginEndStepPct] },
+        t('widgets.layers.control.kind')
+      );
+    },
+    [adapter, commitAdapter, t]
+  );
+
+  const handleModelChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const model = value[0] ?? null;
+      if (model !== adapter.model) {
+        commitAdapter({ model }, { model: adapter.model }, t('widgets.layers.control.model'));
+        const selected = models.find((candidate) => candidate.key === model);
+        const recommendation = resolveDefaultFilterForModel(selected);
+        if (recommendation && !layer.filter) {
+          runLayerFilterOperation(
+            () => (engine ? getCanvasOperations(engine).startFilterOperation(layer.id, recommendation) : 'not-ready'),
+            onOperationStarted
+          );
+        }
+      }
+    },
+    [adapter.model, commitAdapter, engine, layer.filter, layer.id, models, onOperationStarted, t]
+  );
+
+  const handleControlModeChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const mode = value[0] as CanvasControlAdapterContract['controlMode'] | undefined;
+      if (mode && mode !== adapter.controlMode) {
+        commitAdapter({ controlMode: mode }, { controlMode: adapter.controlMode }, t('widgets.layers.control.mode'));
+      }
+    },
+    [adapter.controlMode, commitAdapter, t]
+  );
+
+  const weightBeforeRef = useRef<number | null>(null);
+  const handleWeightChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      if (
+        !applyStructuralPreview(engine, dispatch, {
+          config: { adapter: { weight: next }, layerType: 'control' },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        })
+      ) {
+        return;
+      }
+      if (weightBeforeRef.current === null) {
+        weightBeforeRef.current = adapter.weight;
+      }
+    },
+    [adapter.weight, dispatch, engine, layer.id]
+  );
+  const handleWeightChangeEnd = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      const before = weightBeforeRef.current ?? adapter.weight;
+      weightBeforeRef.current = null;
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      commitAdapter({ weight: next }, { weight: before }, t('widgets.layers.control.weight'));
+    },
+    [adapter.weight, commitAdapter, t]
+  );
+  const handleWeightInputChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (
+        !Number.isFinite(valueAsNumber) ||
+        valueAsNumber < weightInputMin ||
+        valueAsNumber > CONTROL_WEIGHT_BOUNDS.inputMax
+      ) {
+        return;
+      }
+      commitAdapter({ weight: valueAsNumber }, { weight: adapter.weight }, t('widgets.layers.control.weight'));
+    },
+    [adapter.weight, commitAdapter, t, weightInputMin]
+  );
+
+  const rangeBeforeRef = useRef<[number, number] | null>(null);
+  const handleRangeChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      if (value.length !== 2) {
+        return;
+      }
+      if (
+        !applyStructuralPreview(engine, dispatch, {
+          config: { adapter: { beginEndStepPct: [value[0]!, value[1]!] }, layerType: 'control' },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        })
+      ) {
+        return;
+      }
+      if (rangeBeforeRef.current === null) {
+        rangeBeforeRef.current = adapter.beginEndStepPct;
+      }
+    },
+    [adapter.beginEndStepPct, dispatch, engine, layer.id]
+  );
+  const handleRangeChangeEnd = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const before = rangeBeforeRef.current ?? adapter.beginEndStepPct;
+      rangeBeforeRef.current = null;
+      if (value.length !== 2) {
+        return;
+      }
+      commitAdapter(
+        { beginEndStepPct: [value[0]!, value[1]!] },
+        { beginEndStepPct: before },
+        t('widgets.layers.control.stepRange')
+      );
+    },
+    [adapter.beginEndStepPct, commitAdapter, t]
+  );
+
+  const handleTransparencyToggle = useCallback(
+    ({ checked }: { checked: boolean }) => {
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.control.transparencyEffect'),
+        {
+          config: { layerType: 'control', withTransparencyEffect: checked },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        },
+        {
+          config: { layerType: 'control', withTransparencyEffect: !checked },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        }
+      );
+    },
+    [dispatch, engine, layer.id, t]
+  );
+
+  const controlModeCollection = useMemo(
+    () =>
+      createListCollection({
+        items: CONTROL_MODES.map((mode) => ({ label: t(`widgets.layers.control.modes.${mode}`), value: mode })),
+      }),
+    [t]
+  );
+
+  const kindValue = useMemo(() => [adapter.kind], [adapter.kind]);
+  const modelValue = useMemo(() => (adapter.model ? [adapter.model] : []), [adapter.model]);
+  const controlModeValue = useMemo(() => [adapter.controlMode ?? 'balanced'], [adapter.controlMode]);
+  const weightValue = useMemo(
+    () => [Math.min(CONTROL_WEIGHT_BOUNDS.sliderMax, Math.max(CONTROL_WEIGHT_BOUNDS.sliderMin, adapter.weight))],
+    [adapter.weight]
+  );
+  const weightInputValue = String(adapter.weight);
+  const rangeValue = useMemo(() => [...adapter.beginEndStepPct], [adapter.beginEndStepPct]);
+  const weightAria = useMemo(() => [t('widgets.layers.control.weight')], [t]);
+  const rangeAria = useMemo(() => [t('widgets.layers.control.beginStep'), t('widgets.layers.control.endStep')], [t]);
+
+  const selectedModelName = modelOptions.find((model) => model.key === adapter.model)?.name;
+  const adapterModel = models.find((model) => model.key === adapter.model) ?? null;
+  const hasContent = engine?.exports.hasExportableLayerContent(layer.id) ?? false;
+  const controlLoraIndex =
+    adapter.kind === 'control_lora' && engine
+      ? (engine.document
+          .getDocument()
+          ?.layers.filter(
+            (candidate) =>
+              candidate.isEnabled &&
+              candidate.type === 'control' &&
+              candidate.adapter.kind === 'control_lora' &&
+              engine.exports.hasExportableLayerContent(candidate.id)
+          )
+          .findIndex((candidate) => candidate.id === layer.id) ?? 0)
+      : 0;
+  const zImageControlIndex =
+    adapter.kind === 'z_image_control' && engine
+      ? (engine.document
+          .getDocument()
+          ?.layers.filter(
+            (candidate) =>
+              candidate.isEnabled &&
+              candidate.type === 'control' &&
+              candidate.adapter.kind === 'z_image_control' &&
+              engine.exports.hasExportableLayerContent(candidate.id)
+          )
+          .findIndex((candidate) => candidate.id === layer.id) ?? 0)
+      : 0;
+  const validationReason =
+    layer.isEnabled && hasContent && mainModel
+      ? getControlValidationReason({
+          adapterModel: adapterModel ? { base: adapterModel.base, type: adapterModel.type } : null,
+          beginEndStepPct: adapter.beginEndStepPct,
+          controlLoraIndex: Math.max(0, controlLoraIndex),
+          kind: adapter.kind,
+          mainBase: mainModel.base,
+          mainVariant: mainModel.variant ?? undefined,
+          weight: adapter.weight,
+          zImageControlIndex: Math.max(0, zImageControlIndex),
+        })
+      : null;
+  return (
+    <Stack borderColor="border.subtle" borderWidth="1px" gap="2" p="2" rounded="md">
+      <HStack gap="2">
+        <Field flex="1" label={t('widgets.layers.control.kind')} minW="0">
+          <Select
+            aria-label={t('widgets.layers.control.kind')}
+            collection={kindCollection}
+            positioning={SELECT_POSITIONING}
+            size="xs"
+            value={kindValue}
+            valueText={t(`widgets.layers.control.kinds.${adapter.kind}`)}
+            onValueChange={handleKindChange}
+          />
+        </Field>
+      </HStack>
+      <Field label={t('widgets.layers.control.model')}>
+        <Select
+          aria-label={t('widgets.layers.control.model')}
+          collection={modelCollection}
+          positioning={SELECT_POSITIONING}
+          size="xs"
+          value={modelValue}
+          valueText={selectedModelName ?? t('widgets.layers.control.selectModel')}
+          onValueChange={handleModelChange}
+        />
+      </Field>
+      <Field label={t('widgets.layers.control.weight')}>
+        <HStack gap="2">
+          <Slider
+            aria-label={weightAria}
+            flex="1"
+            formatValue={formatWeight}
+            max={CONTROL_WEIGHT_BOUNDS.sliderMax}
+            min={CONTROL_WEIGHT_BOUNDS.sliderMin}
+            size="sm"
+            step={CONTROL_WEIGHT_BOUNDS.step}
+            value={weightValue}
+            withThumbTooltip
+            onValueChange={handleWeightChange}
+            onValueChangeEnd={handleWeightChangeEnd}
+          />
+          <NumberInput.Root
+            max={CONTROL_WEIGHT_BOUNDS.inputMax}
+            min={weightInputMin}
+            size="xs"
+            step={CONTROL_WEIGHT_BOUNDS.step}
+            value={weightInputValue}
+            w="20"
+            onValueChange={handleWeightInputChange}
+          >
+            <NumberInput.Control />
+            <NumberInput.Input aria-label={t('widgets.layers.control.weight')} />
+          </NumberInput.Root>
+        </HStack>
+      </Field>
+      <Field label={t('widgets.layers.control.stepRange')}>
+        <Slider
+          aria-label={rangeAria}
+          formatValue={formatUnitPercent}
+          max={1}
+          min={0}
+          size="sm"
+          step={0.01}
+          value={rangeValue}
+          withThumbTooltip
+          onValueChange={handleRangeChange}
+          onValueChangeEnd={handleRangeChangeEnd}
+        />
+      </Field>
+      {adapter.kind === 'controlnet' ? (
+        <Field label={t('widgets.layers.control.mode')}>
+          <Select
+            aria-label={t('widgets.layers.control.mode')}
+            collection={controlModeCollection}
+            positioning={SELECT_POSITIONING}
+            size="xs"
+            value={controlModeValue}
+            valueText={t(`widgets.layers.control.modes.${adapter.controlMode ?? 'balanced'}`)}
+            onValueChange={handleControlModeChange}
+          />
+        </Field>
+      ) : null}
+      <Switch.Root
+        checked={layer.withTransparencyEffect}
+        colorPalette="accent"
+        size="xs"
+        onCheckedChange={handleTransparencyToggle}
+      >
+        <Switch.HiddenInput />
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        <Switch.Label>
+          <Text fontSize="xs">{t('widgets.layers.control.transparencyEffect')}</Text>
+        </Switch.Label>
+      </Switch.Root>
+      <LayerFilterOperationButton
+        engine={engine}
+        layer={layer}
+        onOperationStarted={onOperationStarted}
+        operations={engine ? getCanvasOperations(engine) : null}
+      />
+      {validationReason ? (
+        <Text color="fg.warning" fontSize="2xs" role="alert">
+          {t(`widgets.layers.control.validation.${validationReason}`)}
+        </Text>
+      ) : null}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/DenoisingStrengthWave.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/DenoisingStrengthWave.test.ts
new file mode 100644
index 00000000000..ce7e2856895
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/DenoisingStrengthWave.test.ts
@@ -0,0 +1,34 @@
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { DenoisingStrengthWave, getDenoisingStrengthWavePath } from './DenoisingStrengthWave';
+
+describe('getDenoisingStrengthWavePath', () => {
+  it('renders zero strength as a straight centered line', () => {
+    expect(getDenoisingStrengthWavePath(0, 100, 14, 5)).toBe('M0,7 L100,7');
+  });
+
+  it('increases wave amplitude with denoising strength', () => {
+    const low = getDenoisingStrengthWavePath(0.25, 100, 14, 5);
+    const high = getDenoisingStrengthWavePath(1, 100, 14, 5);
+
+    expect(low).toContain('Q10,4.5 20,7');
+    expect(high).toContain('Q10,0 20,7');
+  });
+
+  it('clamps strength before calculating amplitude', () => {
+    expect(getDenoisingStrengthWavePath(-1, 100, 14, 5)).toBe(getDenoisingStrengthWavePath(0, 100, 14, 5));
+    expect(getDenoisingStrengthWavePath(2, 100, 14, 5)).toBe(getDenoisingStrengthWavePath(1, 100, 14, 5));
+  });
+
+  it('renders one continuous five-segment stroke without value-based dashes', () => {
+    const markup = renderToStaticMarkup(createElement(DenoisingStrengthWave, { value: 0.52 }));
+
+    expect(markup.match(/<path/g)).toHaveLength(1);
+    expect(markup).not.toContain('stroke-dasharray');
+    expect(markup.match(/ Q/g)).toHaveLength(5);
+    expect(markup).toContain('width="56"');
+    expect(markup).not.toContain('position:absolute');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/DenoisingStrengthWave.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/DenoisingStrengthWave.tsx
new file mode 100644
index 00000000000..8d928eeaac1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/DenoisingStrengthWave.tsx
@@ -0,0 +1,53 @@
+const clamp01 = (value: number): number => Math.min(1, Math.max(0, value));
+const LEGACY_WAVE_AMPLITUDE_SCALE = 10;
+
+export const getDenoisingStrengthWavePath = (
+  strength: number,
+  width: number,
+  height: number,
+  segments: number
+): string => {
+  const centerY = height / 2;
+  const amplitude = Math.min(centerY, clamp01(strength) * LEGACY_WAVE_AMPLITUDE_SCALE);
+  if (amplitude === 0) {
+    return `M0,${centerY} L${width},${centerY}`;
+  }
+
+  const segmentWidth = width / segments;
+  let path = `M0,${centerY}`;
+  for (let index = 1; index <= segments; index += 1) {
+    const x = index * segmentWidth;
+    const controlX = x - segmentWidth / 2;
+    const controlY = centerY + (index % 2 === 0 ? amplitude : -amplitude);
+    path += ` Q${controlX},${controlY} ${x},${centerY}`;
+  }
+  return path;
+};
+
+const WAVE_WIDTH = 100;
+const WAVE_HEIGHT = 14;
+const WAVE_SEGMENTS = 5;
+
+/** A value-reactive replacement for the denoising slider's straight track. */
+export const DenoisingStrengthWave = ({ value }: { value: number }) => {
+  const path = getDenoisingStrengthWavePath(value, WAVE_WIDTH, WAVE_HEIGHT, WAVE_SEGMENTS);
+
+  return (
+    <svg
+      aria-hidden
+      height={WAVE_HEIGHT}
+      preserveAspectRatio="none"
+      style={{ display: 'block', flexShrink: 0, marginLeft: 8, pointerEvents: 'none' }}
+      viewBox={`0 0 ${WAVE_WIDTH} ${WAVE_HEIGHT}`}
+      width={56}
+    >
+      <path
+        d={path}
+        fill="none"
+        stroke="var(--chakra-colors-accent-solid)"
+        strokeWidth="1.5"
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/InpaintMaskSettings.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/InpaintMaskSettings.tsx
new file mode 100644
index 00000000000..6897fc3a6a6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/InpaintMaskSettings.tsx
@@ -0,0 +1,265 @@
+import type { SelectValueChangeDetails, SliderValueChangeDetails } from '@chakra-ui/react';
+import type { CanvasInpaintMaskLayerContract, CanvasMaskFillContract } from '@workbench/types';
+import type { CanvasStructuralEngine } from '@workbench/widgets/layers/layerOps';
+
+import { createListCollection, HStack, Stack } from '@chakra-ui/react';
+import { Button, ColorPicker, Field, Select, Slider } from '@workbench/components/ui';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { useCallback, useMemo, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { applyStructural, applyStructuralPreview } from './layerOps';
+
+/** The six mask fill styles, matching `CanvasMaskFillContract['style']` / legacy `zFillStyle`. */
+const MASK_FILL_STYLES: readonly CanvasMaskFillContract['style'][] = [
+  'solid',
+  'grid',
+  'crosshatch',
+  'diagonal',
+  'horizontal',
+  'vertical',
+];
+
+const formatUnitPercent = (value: number): string => `${Math.round(value * 100)}%`;
+
+const noiseConfig = (value: number) => ({ layerType: 'inpaint_mask', noiseLevel: value }) as const;
+const denoiseConfig = (value: number) => ({ layerType: 'inpaint_mask', denoiseLimit: value }) as const;
+
+interface InpaintMaskSettingsProps {
+  engine: CanvasStructuralEngine | null;
+  layer: CanvasInpaintMaskLayerContract;
+}
+
+/**
+ * Per-layer settings for a selected inpaint mask, rendered as a section under the
+ * layers-panel header region (plan §1.3): fill colour + style, noise level and
+ * denoise-limit sliders (0–1), and an in-place mask invert. `noiseLevel` /
+ * `denoiseLimit` are wired to the contract now (consumed by the NEXT task's graph
+ * builder); they have no generation effect yet. Fill/noise/denoise edits go
+ * through the canvas undo stack (`applyStructural` → `updateCanvasLayerConfig`);
+ * invert is an engine pixel op (its own undoable image patch).
+ */
+export const InpaintMaskSettings = ({ engine, layer }: InpaintMaskSettingsProps) => {
+  const { t } = useTranslation();
+  const dispatch = useCanvasProjectMutationDispatch();
+  const fillBeforeRef = useRef<CanvasMaskFillContract | null>(null);
+  const noiseBeforeRef = useRef<number | null>(null);
+  const denoiseBeforeRef = useRef<number | null>(null);
+
+  const fill = layer.mask.fill;
+  const noiseLevel = layer.noiseLevel ?? 0;
+  const denoiseLimit = layer.denoiseLimit ?? 1;
+
+  const styleCollection = useMemo(
+    () =>
+      createListCollection({
+        items: MASK_FILL_STYLES.map((style) => ({
+          label: t(`widgets.layers.maskFill.styles.${style}`),
+          value: style,
+        })),
+      }),
+    [t]
+  );
+
+  const commitFill = useCallback(
+    (next: CanvasMaskFillContract, before: CanvasMaskFillContract) => {
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.maskFill.fill'),
+        { config: { layerType: 'inpaint_mask', mask: { fill: next } }, id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: { layerType: 'inpaint_mask', mask: { fill: before } }, id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, engine, layer.id, t]
+  );
+
+  const handleColorChange = useCallback(
+    (hex: string) => {
+      if (
+        !applyStructuralPreview(engine, dispatch, {
+          config: { layerType: 'inpaint_mask', mask: { fill: { ...fill, color: hex } } },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        })
+      ) {
+        return;
+      }
+      if (fillBeforeRef.current === null) {
+        fillBeforeRef.current = fill;
+      }
+    },
+    [dispatch, engine, fill, layer.id]
+  );
+
+  const handleColorChangeEnd = useCallback(
+    (hex: string) => {
+      const before = fillBeforeRef.current ?? fill;
+      fillBeforeRef.current = null;
+      commitFill({ ...before, color: hex }, before);
+    },
+    [commitFill, fill]
+  );
+
+  const handleStyleChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const style = value[0] as CanvasMaskFillContract['style'] | undefined;
+      if (style && style !== fill.style) {
+        commitFill({ ...fill, style }, fill);
+      }
+    },
+    [commitFill, fill]
+  );
+
+  const handleNoiseChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      if (
+        !applyStructuralPreview(engine, dispatch, {
+          config: noiseConfig(next),
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        })
+      ) {
+        return;
+      }
+      if (noiseBeforeRef.current === null) {
+        noiseBeforeRef.current = noiseLevel;
+      }
+    },
+    [dispatch, engine, layer.id, noiseLevel]
+  );
+
+  const handleNoiseChangeEnd = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      const before = noiseBeforeRef.current ?? noiseLevel;
+      noiseBeforeRef.current = null;
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.maskFill.noiseLevel'),
+        { config: noiseConfig(next), id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: noiseConfig(before), id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, engine, layer.id, noiseLevel, t]
+  );
+
+  const handleDenoiseChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      if (
+        !applyStructuralPreview(engine, dispatch, {
+          config: denoiseConfig(next),
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        })
+      ) {
+        return;
+      }
+      if (denoiseBeforeRef.current === null) {
+        denoiseBeforeRef.current = denoiseLimit;
+      }
+    },
+    [dispatch, denoiseLimit, engine, layer.id]
+  );
+
+  const handleDenoiseChangeEnd = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      const before = denoiseBeforeRef.current ?? denoiseLimit;
+      denoiseBeforeRef.current = null;
+      if (next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.maskFill.denoiseLimit'),
+        { config: denoiseConfig(next), id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: denoiseConfig(before), id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, denoiseLimit, engine, layer.id, t]
+  );
+
+  const handleInvert = useCallback(() => {
+    engine?.layers.invertMask(layer.id);
+  }, [engine, layer.id]);
+
+  const styleValue = useMemo(() => [fill.style], [fill.style]);
+  const colorAria = t('widgets.layers.maskFill.color');
+  const noiseValue = useMemo(() => [noiseLevel], [noiseLevel]);
+  const denoiseValue = useMemo(() => [denoiseLimit], [denoiseLimit]);
+  const noiseAria = useMemo(() => [t('widgets.layers.maskFill.noiseLevel')], [t]);
+  const denoiseAria = useMemo(() => [t('widgets.layers.maskFill.denoiseLimit')], [t]);
+
+  return (
+    <Stack gap="2">
+      <HStack gap="2">
+        <Field flexShrink="0" label={t('widgets.layers.maskFill.color')}>
+          <ColorPicker
+            aria-label={colorAria}
+            value={fill.color}
+            onValueChange={handleColorChange}
+            onValueChangeEnd={handleColorChangeEnd}
+          />
+        </Field>
+        <Field flex="1" label={t('widgets.layers.maskFill.style')} minW="0">
+          <Select
+            aria-label={t('widgets.layers.maskFill.style')}
+            collection={styleCollection}
+            positioning={SELECT_POSITIONING}
+            size="xs"
+            value={styleValue}
+            valueText={t(`widgets.layers.maskFill.styles.${fill.style}`)}
+            onValueChange={handleStyleChange}
+          />
+        </Field>
+      </HStack>
+      <Field label={t('widgets.layers.maskFill.noiseLevel')}>
+        <Slider
+          aria-label={noiseAria}
+          formatValue={formatUnitPercent}
+          max={1}
+          min={0}
+          size="sm"
+          step={0.01}
+          value={noiseValue}
+          withThumbTooltip
+          onValueChange={handleNoiseChange}
+          onValueChangeEnd={handleNoiseChangeEnd}
+        />
+      </Field>
+      <Field label={t('widgets.layers.maskFill.denoiseLimit')}>
+        <Slider
+          aria-label={denoiseAria}
+          formatValue={formatUnitPercent}
+          max={1}
+          min={0}
+          size="sm"
+          step={0.01}
+          value={denoiseValue}
+          withThumbTooltip
+          onValueChange={handleDenoiseChange}
+          onValueChangeEnd={handleDenoiseChangeEnd}
+        />
+      </Field>
+      <Button disabled={!engine} size="xs" variant="outline" onClick={handleInvert}>
+        {t('widgets.layers.maskFill.invert')}
+      </Button>
+    </Stack>
+  );
+};
+
+const SELECT_POSITIONING = { placement: 'bottom-end', sameWidth: false } as const;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerContextMenu.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerContextMenu.tsx
new file mode 100644
index 00000000000..36d1303cf7e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerContextMenu.tsx
@@ -0,0 +1,1142 @@
+import type { BooleanRasterOperation } from '@workbench/canvas-engine/engine';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { GenerateReferenceImage } from '@workbench/generation/types';
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasMaskContract } from '@workbench/types';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { LucideIcon } from 'lucide-react';
+import type { ComponentProps, Dispatch, ReactNode } from 'react';
+
+import { HStack, Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { getSourceContentRect, renderableSourceOf } from '@workbench/canvas-engine/document/sources';
+import { getCanvasOperations } from '@workbench/canvas-operations/createCanvasEngine';
+import { deleteLayerActions, duplicateLayerActions } from '@workbench/canvasLayerOps';
+import { IconButton, MenuContent, RenameDialog, Tooltip } from '@workbench/components/ui';
+import { uploadGalleryImage } from '@workbench/gallery/api';
+import { useNotify } from '@workbench/useNotify';
+import { isCanvasInteractionLocked } from '@workbench/widgets/canvas/canvasInteractionLock';
+import { useCanvasDocumentEditingLocked, useLayerThumbnailVersion } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import {
+  ArrowRightLeftIcon,
+  ArrowUpDownIcon,
+  ChevronRightIcon,
+  CopyIcon,
+  MergeIcon,
+  MoreVerticalIcon,
+  PlusIcon,
+} from 'lucide-react';
+import { Fragment, useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export type LayerContextMenuEngine = Pick<CanvasEngineHandle, 'exports' | 'layers' | 'projectId' | 'stores' | 'tools'>;
+
+import type {
+  LayerContextMenuItem,
+  LayerContextMenuRenderEntry,
+  LayerContextMenuSection,
+  LayerContextSubmenuId,
+} from './layerContextMenuLayout';
+import type { LayerMoveKind } from './layerGroups';
+import type { LayerMenuDialogKind, LayerMenuDialogState } from './layerMenuState';
+import type { LayerPropertiesSection } from './layerPropertiesRequestStore';
+
+import {
+  getLayerContextActions,
+  type LayerConfigPatchKind,
+  type LayerContextAction,
+  type LayerContextActionEffects,
+  type LayerContextActionId,
+  type LayerContextActionState,
+  type LayerType,
+} from './layerContextActions';
+import {
+  getLayerContextMenuLayerLabelKey,
+  getLayerContextMenuLayout,
+  getLayerContextMenuRenderEntries,
+} from './layerContextMenuLayout';
+import { copyBlobToClipboard } from './layerExportActions';
+import { reorderWithinGroupByKind } from './layerGroups';
+import { resolveMenuTargetForRender } from './layerMenuState';
+import {
+  applyStructural,
+  convertRasterToControl,
+  convertRasterToInpaintMask,
+  convertRasterToRegionalGuidance,
+  convertRasterControlLayer,
+  copyControlToInpaintMask,
+  copyControlToRaster,
+  copyControlToRegionalGuidance,
+  copyMaskToRegionalGuidance,
+  copyRasterToControl,
+  copyRasterToInpaintMask,
+  copyRasterToRegionalGuidance,
+  copyRegionalGuidanceToInpaintMask,
+  createLayerId,
+  fitLayerTransformToBbox,
+  getControlTransparencyEffectPatch,
+  getInpaintDenoiseLimitPatch,
+  getInpaintNoisePatch,
+  getRegionalGuidanceAutoNegativePatch,
+  getRegionalGuidanceNegativePromptPatch,
+  getRegionalGuidancePositivePromptPatch,
+  getRegionalGuidanceReferenceImagePatch,
+} from './layerOps';
+import { requestLayerProperties } from './layerPropertiesRequestStore';
+import { RunLayerWorkflowDialog, useLayerWorkflowAvailability } from './RunLayerWorkflowDialog';
+import { useSelectedModelBase } from './useSelectedModelBase';
+
+type MenuPositioning = ComponentProps<typeof Menu.Root>['positioning'];
+type MenuOpenChange = ComponentProps<typeof Menu.Root>['onOpenChange'];
+
+type LayerConfigPatch =
+  | { layerType: 'control'; withTransparencyEffect?: boolean }
+  | {
+      layerType: 'regional_guidance';
+      mask?: Partial<CanvasMaskContract>;
+      positivePrompt?: string | null;
+      negativePrompt?: string | null;
+      autoNegative?: boolean;
+      referenceImages?: GenerateReferenceImage[];
+    }
+  | { layerType: 'inpaint_mask'; noiseLevel?: number; denoiseLimit?: number };
+
+const PANEL_POSITIONING: MenuPositioning = { placement: 'bottom-end' };
+
+const toErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+const assertNever = (value: never): never => {
+  throw new Error(`Unhandled layer action result: ${String(value)}`);
+};
+
+type LayerActionErrorStatus =
+  | 'aborted'
+  | 'busy'
+  | 'disabled'
+  | 'empty'
+  | 'locked'
+  | 'missing'
+  | 'not-ready'
+  | 'over-budget'
+  | 'unsupported';
+
+const LAYER_ACTION_ERROR_KEYS: Record<LayerActionErrorStatus, string> = {
+  aborted: 'widgets.layers.actions.notReady',
+  busy: 'widgets.layers.actions.busy',
+  disabled: 'widgets.layers.actions.disabled',
+  empty: 'widgets.layers.actions.empty',
+  locked: 'widgets.layers.actions.locked',
+  missing: 'widgets.layers.actions.missing',
+  'not-ready': 'widgets.layers.actions.notReady',
+  'over-budget': 'widgets.layers.actions.notReady',
+  unsupported: 'widgets.layers.actions.unsupported',
+};
+
+const hasPureExportableLayerContent = (layer: CanvasLayerContract, document: CanvasDocumentContractV2): boolean => {
+  if (!renderableSourceOf(layer)) {
+    return false;
+  }
+  const contentRect = getSourceContentRect(layer, document);
+  return contentRect.width > 0 && contentRect.height > 0;
+};
+
+interface LayerMenuProps {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  engine: LayerContextMenuEngine | null;
+  index: number;
+  layer: CanvasLayerContract;
+  layers: readonly CanvasLayerContract[];
+  /** Where the menu opens: the panel anchors to its trigger; the canvas uses a
+   * virtual rect at the cursor. */
+  positioning: MenuPositioning;
+  /** Render the panel's ⋯ trigger button. Off in the canvas' controlled, anchored
+   * mode, where there is no trigger DOM. */
+  withTrigger?: boolean;
+  /** Controlled open state (canvas right-click). Undefined ⇒ uncontrolled (panel). */
+  open?: boolean;
+  onOpenChange?: MenuOpenChange;
+  lazyMount?: boolean;
+  unmountOnExit?: boolean;
+  /**
+   * Controlled sibling-dialog state. When provided (canvas right-click), the
+   * parent owns it so dialogs survive the menu closing. Undefined means the menu
+   * keeps this state internally (panel).
+   */
+  dialogKind?: LayerMenuDialogKind | null;
+  onDialogKindChange?: (kind: LayerMenuDialogKind | null) => void;
+  /** Canvas-only items composed immediately before the terminal danger section. */
+  beforeDangerItems?: ReactNode;
+  /** Adds the legacy layer and Canvas group labels on the canvas surface. */
+  showGroupLabels?: boolean;
+}
+
+/**
+ * The shared layer context menu — ONE source of truth for the per-layer items and
+ * their handlers, used by both the layers panel (a ⋯ trigger button) and the
+ * canvas surface (right-click, anchored at the cursor). All actions operate on
+ * `layer.id`, so they behave identically from either surface.
+ *
+ * Legacy-parity items (scoped to what webv2 supports today): rename, duplicate,
+ * rasterize, raster↔control convert, group-aware z-arrange (move to front /
+ * forward / backward / to back — within the layer's type group), merge-down,
+ * visibility + lock toggles, and delete. Merge-down uses global z-adjacency
+ * (compositing order); the arrange actions map to a splice inside the global array.
+ *
+ * Sibling dialogs live beside `Menu.Root` (not inside its portal) so they
+ * survive the menu closing after their action is chosen.
+ */
+const LayerMenu = ({
+  dispatch,
+  engine,
+  index,
+  layer,
+  layers,
+  positioning,
+  withTrigger,
+  open,
+  onOpenChange,
+  lazyMount,
+  unmountOnExit,
+  dialogKind: controlledDialogKind,
+  onDialogKindChange,
+  beforeDangerItems,
+  showGroupLabels,
+}: LayerMenuProps) => {
+  const { t } = useTranslation();
+  const workbenchDispatch = useWorkbenchDispatch();
+  const notify = useNotify();
+  const base = useSelectedModelBase();
+  const workflowAvailability = useLayerWorkflowAvailability();
+  const canvas = useActiveProjectSelector((project) => project.canvas);
+  const queueItems = useActiveProjectSelector((project) => project.queue.items);
+  const { document } = canvas;
+  const { bbox } = document;
+  const documentRect = useMemo(
+    () => ({ height: document.height, width: document.width, x: 0, y: 0 }),
+    [document.height, document.width]
+  );
+  const documentEditingLocked = useCanvasDocumentEditingLocked(engine);
+  const interactionLocked = isCanvasInteractionLocked(canvas, queueItems) || documentEditingLocked;
+  // Re-render when live, not-yet-persisted paint/mask pixels change.
+  useLayerThumbnailVersion(engine, layer.id);
+  const hasSupportedContent = engine
+    ? engine.exports.hasExportableLayerContent(layer.id)
+    : hasPureExportableLayerContent(layer, document);
+  const [internalDialogKind, setInternalDialogKind] = useState<LayerMenuDialogKind | null>(null);
+  // Controlled (canvas) vs. uncontrolled (panel): the canvas parent owns the
+  // dialog kind so its sibling survives menu close; panel rows keep it locally.
+  const dialogKind = controlledDialogKind !== undefined ? controlledDialogKind : internalDialogKind;
+  const setDialogKind = useCallback(
+    (next: LayerMenuDialogKind | null) => {
+      setInternalDialogKind(next);
+      onDialogKindChange?.(next);
+    },
+    [onDialogKindChange]
+  );
+
+  const patchBase = useCallback(
+    (label: string, forward: Partial<CanvasLayerContract>, inverse: Partial<CanvasLayerContract>) => {
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { id: layer.id, patch: forward, type: 'updateCanvasLayer' },
+        { id: layer.id, patch: inverse, type: 'updateCanvasLayer' }
+      );
+    },
+    [dispatch, engine, layer.id]
+  );
+
+  const patchConfig = useCallback(
+    (label: string, forward: LayerConfigPatch, inverse: LayerConfigPatch) => {
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { config: forward, id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: inverse, id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, engine, layer.id]
+  );
+
+  const reorder = useCallback(
+    (kind: LayerMoveKind, label: string) => {
+      const next = reorderWithinGroupByKind(layers, layer.id, kind);
+      if (!next) {
+        return;
+      }
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { orderedIds: next, type: 'reorderCanvasLayers' },
+        { orderedIds: layers.map((entry) => entry.id), type: 'reorderCanvasLayers' }
+      );
+    },
+    [dispatch, engine, layer.id, layers]
+  );
+
+  const actionState = useMemo<LayerContextActionState>(
+    () => ({
+      canRunWorkflow: workflowAvailability.canRunWorkflow,
+      document,
+      hasEngine: engine !== null,
+      hasSupportedContent,
+      hasWorkflowBindings: workflowAvailability.hasWorkflowBindings,
+      index,
+      interactionLocked,
+      layer,
+    }),
+    [
+      document,
+      engine,
+      hasSupportedContent,
+      index,
+      interactionLocked,
+      layer,
+      workflowAvailability.canRunWorkflow,
+      workflowAvailability.hasWorkflowBindings,
+    ]
+  );
+  const actions = useMemo(() => getLayerContextActions(actionState), [actionState]);
+  const menuLayout = useMemo(() => getLayerContextMenuLayout(actions), [actions]);
+
+  const getActionLabel = useCallback(
+    (id: LayerContextActionId) => {
+      const action = actions.find((entry) => entry.id === id);
+      return action ? t(action.labelKey, { defaultValue: action.defaultLabel }) : id;
+    },
+    [actions, t]
+  );
+
+  const makeStatusError = useCallback(
+    (status: LayerActionErrorStatus): Error => new Error(t(LAYER_ACTION_ERROR_KEYS[status])),
+    [t]
+  );
+
+  const handleDuplicate = useCallback(() => {
+    const { forward, inverse } = duplicateLayerActions(layer.id, createLayerId());
+    applyStructural(engine, dispatch, t('widgets.layers.actions.duplicate'), forward, inverse);
+  }, [dispatch, engine, layer.id, t]);
+
+  const handleDelete = useCallback(() => {
+    const { forward, inverse } = deleteLayerActions(layer, index);
+    applyStructural(engine, dispatch, t('widgets.layers.actions.delete'), forward, inverse);
+  }, [dispatch, engine, index, layer, t]);
+
+  const handleMerge = useCallback(() => {
+    // Pixel work: engine-only, and not recorded on the undo history.
+    engine?.layers.mergeLayerDown(layer.id);
+  }, [engine, layer.id]);
+
+  const handleRasterize = useCallback(() => {
+    // Bakes the parametric source to pixels; the engine records ONE undoable
+    // entry (inverse re-converts to the parametric source).
+    engine?.layers.rasterizeLayer(layer.id);
+  }, [engine, layer.id]);
+
+  const addCopy = useCallback(
+    (copied: CanvasLayerContract | null, label: string) => {
+      if (!copied) {
+        throw new Error(t('widgets.layers.actions.copyFailed'));
+      }
+      if (engine) {
+        if (!engine.layers.commitLayerCopy(label, layer.id, copied, index)) {
+          throw new Error(t('widgets.layers.actions.copyFailed'));
+        }
+        return;
+      }
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { index, layer: copied, type: 'addCanvasLayer' },
+        { ids: [copied.id], type: 'removeCanvasLayers' }
+      );
+    },
+    [dispatch, engine, index, layer.id, t]
+  );
+
+  const convert = useCallback(
+    (targetType: CanvasLayerContract['type'], label: string) => {
+      const converted =
+        layer.type === 'raster' && targetType === 'control'
+          ? convertRasterToControl(layer, base)
+          : layer.type === 'raster' && targetType === 'inpaint_mask'
+            ? convertRasterToInpaintMask(layer)
+            : layer.type === 'raster' && targetType === 'regional_guidance'
+              ? convertRasterToRegionalGuidance(layer)
+              : targetType === 'raster'
+                ? convertRasterControlLayer(layer, 'raster')
+                : null;
+      if (!converted) {
+        throw makeStatusError('unsupported');
+      }
+      if (engine) {
+        // Pass the immutable live object: the engine rejects stale menu actions
+        // by identity and clones the inverse contract internally.
+        if (!engine.layers.commitLayerConversion(label, layer, converted)) {
+          throw makeStatusError('not-ready');
+        }
+      } else {
+        // Convert in place, preserving the pixel source + id. The inverse restores
+        // the layer verbatim (adapter/filter config and all).
+        const original = structuredClone(layer);
+        applyStructural(
+          engine,
+          dispatch,
+          label,
+          { id: layer.id, layer: converted, targetType, type: 'convertCanvasLayer' },
+          { id: layer.id, layer: original, targetType: layer.type, type: 'convertCanvasLayer' }
+        );
+      }
+    },
+    [base, dispatch, engine, layer, makeStatusError]
+  );
+
+  const handleToggleVisibility = useCallback(() => {
+    patchBase(
+      t('widgets.layers.actions.toggleVisibility'),
+      { isEnabled: !layer.isEnabled },
+      { isEnabled: layer.isEnabled }
+    );
+  }, [layer.isEnabled, patchBase, t]);
+
+  const handleToggleLock = useCallback(() => {
+    patchBase(t('widgets.layers.actions.toggleLock'), { isLocked: !layer.isLocked }, { isLocked: layer.isLocked });
+  }, [layer.isLocked, patchBase, t]);
+
+  const openRename = useCallback(() => setDialogKind('rename'), [setDialogKind]);
+  const closeDialog = useCallback(() => setDialogKind(null), [setDialogKind]);
+  const openRunWorkflow = useCallback(() => setDialogKind('run-workflow'), [setDialogKind]);
+  const startSelectObject = useCallback(
+    (layerId: string) => {
+      if (!engine) {
+        throw makeStatusError('not-ready');
+      }
+      const result = getCanvasOperations(engine).startSelectObject(layerId);
+      if (result !== 'started') {
+        throw makeStatusError(result);
+      }
+    },
+    [engine, makeStatusError]
+  );
+  const startFilter = useCallback(
+    (layerId: string) => {
+      if (!engine) {
+        throw makeStatusError('not-ready');
+      }
+      const result = getCanvasOperations(engine).startFilterOperation(layerId);
+      if (result !== 'started') {
+        throw makeStatusError(result);
+      }
+    },
+    [engine, makeStatusError]
+  );
+  const submitRename = useCallback(
+    (name: string) => {
+      patchBase(t('widgets.layers.actions.rename'), { name }, { name: layer.name });
+    },
+    [layer.name, patchBase, t]
+  );
+
+  const handleTransform = useCallback(() => {
+    dispatch({ id: layer.id, type: 'setCanvasSelectedLayer' });
+    engine?.tools.setTool('transform');
+  }, [dispatch, engine, layer.id]);
+
+  const handleFitToBbox = useCallback(() => {
+    const transform = fitLayerTransformToBbox(layer, bbox, documentRect);
+    if (!transform) {
+      throw makeStatusError('empty');
+    }
+    patchBase(getActionLabel('fit-to-bbox'), { transform }, { transform: layer.transform });
+  }, [bbox, documentRect, getActionLabel, layer, makeStatusError, patchBase]);
+
+  const handleSaveToAssets = useCallback(async () => {
+    if (!engine) {
+      throw makeStatusError('not-ready');
+    }
+    const result = await engine.exports.exportBakedLayerBlob(layer.id, { includeDisabled: true });
+    if (result.status !== 'ok') {
+      throw makeStatusError(result.status);
+    }
+    const file = new File([result.blob], `layer-${layer.id}.png`, { type: result.blob.type || 'image/png' });
+    await uploadGalleryImage(file, 'none');
+  }, [engine, layer.id, makeStatusError]);
+
+  const handleCopyToClipboard = useCallback(async () => {
+    if (!engine) {
+      throw makeStatusError('not-ready');
+    }
+    const result = await engine.exports.exportBakedLayerBlob(layer.id, { includeDisabled: true });
+    if (result.status !== 'ok') {
+      throw makeStatusError(result.status);
+    }
+    await copyBlobToClipboard(result.blob);
+  }, [engine, layer.id, makeStatusError]);
+
+  const handleCropToBbox = useCallback(async () => {
+    if (!engine) {
+      throw makeStatusError('not-ready');
+    }
+    const result = await engine.layers.cropLayerToBbox(layer.id);
+    switch (result.status) {
+      case 'cropped':
+        notify.success(t('widgets.layers.actions.cropped'));
+        return;
+      case 'missing':
+      case 'locked':
+      case 'empty':
+      case 'not-ready':
+      case 'over-budget':
+        throw makeStatusError(result.status);
+      case 'busy':
+        throw new Error(t('widgets.layers.actions.cropBusy'));
+      case 'unsupported':
+        throw new Error(t('widgets.layers.actions.cropUnsupported'));
+      case 'failed':
+        throw new Error(`${t('widgets.layers.actions.cropFailed')} ${result.message}`);
+      default:
+        return assertNever(result);
+    }
+  }, [engine, layer.id, makeStatusError, notify, t]);
+
+  const handleExtractMaskedArea = useCallback(async () => {
+    if (!engine) {
+      throw makeStatusError('not-ready');
+    }
+    const result = await engine.exports.extractMaskedArea(layer.id);
+    if (result.status !== 'extracted') {
+      throw makeStatusError(result.status);
+    }
+  }, [engine, layer.id, makeStatusError]);
+
+  const handleOpenProperties = useCallback(
+    (section: LayerPropertiesSection) => {
+      workbenchDispatch({ region: 'right', type: 'openRegionWidget', widgetId: 'layers' });
+      requestLayerProperties(layer.id, section);
+    },
+    [layer.id, workbenchDispatch]
+  );
+
+  const handleBooleanRaster = useCallback(
+    async (operation: BooleanRasterOperation) => {
+      if (!engine) {
+        throw makeStatusError('not-ready');
+      }
+      const result = await engine.layers.booleanMergeRasterLayers(layer.id, operation);
+      if (result !== 'merged') {
+        throw makeStatusError(result);
+      }
+    },
+    [engine, layer.id, makeStatusError]
+  );
+
+  const handleCopyToRaster = useCallback(async () => {
+    if (layer.type === 'control') {
+      addCopy(copyControlToRaster(layer, createLayerId()), getActionLabel('copy-to-raster'));
+      return;
+    }
+    if (!engine) {
+      throw makeStatusError('not-ready');
+    }
+    if ((await engine.layers.copyLayerToRaster(layer.id)) === null) {
+      throw new Error(t('widgets.layers.actions.copyFailed'));
+    }
+  }, [addCopy, engine, getActionLabel, layer, makeStatusError, t]);
+
+  const handleCopyToControl = useCallback(() => {
+    if (layer.type === 'raster') {
+      addCopy(copyRasterToControl(layer, createLayerId(), base), getActionLabel('copy-to-control'));
+    }
+  }, [addCopy, base, getActionLabel, layer]);
+
+  const handleCopyToInpaintMask = useCallback(() => {
+    const id = createLayerId();
+    const copied =
+      layer.type === 'raster'
+        ? copyRasterToInpaintMask(layer, id)
+        : layer.type === 'control'
+          ? copyControlToInpaintMask(layer, id)
+          : layer.type === 'regional_guidance'
+            ? copyRegionalGuidanceToInpaintMask(layer, id)
+            : null;
+    addCopy(copied, getActionLabel('copy-to-inpaint-mask'));
+  }, [addCopy, getActionLabel, layer]);
+
+  const handleCopyToRegionalGuidance = useCallback(() => {
+    const id = createLayerId();
+    const copied =
+      layer.type === 'raster'
+        ? copyRasterToRegionalGuidance(layer, id)
+        : layer.type === 'control'
+          ? copyControlToRegionalGuidance(layer, id)
+          : layer.type === 'inpaint_mask'
+            ? copyMaskToRegionalGuidance(layer, id)
+            : null;
+    addCopy(copied, getActionLabel('copy-to-regional-guidance'));
+  }, [addCopy, getActionLabel, layer]);
+
+  const handleCopyTo = useCallback(
+    (target: LayerType): void | Promise<void> => {
+      switch (target) {
+        case 'raster':
+          return handleCopyToRaster();
+        case 'control':
+          return handleCopyToControl();
+        case 'inpaint_mask':
+          return handleCopyToInpaintMask();
+        case 'regional_guidance':
+          return handleCopyToRegionalGuidance();
+      }
+    },
+    [handleCopyToControl, handleCopyToInpaintMask, handleCopyToRaster, handleCopyToRegionalGuidance]
+  );
+
+  const handleLayerConfigAction = useCallback(
+    (id: LayerConfigPatchKind) => {
+      if (id === 'control-transparency-effect' && layer.type === 'control') {
+        const { forward, inverse } = getControlTransparencyEffectPatch(layer);
+        patchConfig(getActionLabel(id), forward, inverse);
+      } else if (id === 'regional-positive-prompt' && layer.type === 'regional_guidance') {
+        const { forward, inverse } = getRegionalGuidancePositivePromptPatch(layer);
+        patchConfig(getActionLabel(id), forward, inverse);
+      } else if (id === 'regional-negative-prompt' && layer.type === 'regional_guidance') {
+        const { forward, inverse } = getRegionalGuidanceNegativePromptPatch(layer);
+        patchConfig(getActionLabel(id), forward, inverse);
+      } else if (id === 'regional-reference-image' && layer.type === 'regional_guidance') {
+        const { forward, inverse } = getRegionalGuidanceReferenceImagePatch(layer, base);
+        patchConfig(getActionLabel(id), forward, inverse);
+      } else if (id === 'regional-auto-negative' && layer.type === 'regional_guidance') {
+        const { forward, inverse } = getRegionalGuidanceAutoNegativePatch(layer);
+        patchConfig(getActionLabel(id), forward, inverse);
+      } else if (id === 'inpaint-noise' && layer.type === 'inpaint_mask') {
+        const { forward, inverse } = getInpaintNoisePatch(layer);
+        patchConfig(getActionLabel(id), forward, inverse);
+      } else if (id === 'inpaint-denoise-limit' && layer.type === 'inpaint_mask') {
+        const { forward, inverse } = getInpaintDenoiseLimitPatch(layer);
+        patchConfig(getActionLabel(id), forward, inverse);
+      }
+    },
+    [base, getActionLabel, layer, patchConfig]
+  );
+
+  const effects = useMemo<LayerContextActionEffects>(
+    () => ({
+      booleanMerge: handleBooleanRaster,
+      convertTo: (target) => {
+        const actionId: LayerContextActionId =
+          target === 'control'
+            ? 'convert-to-control'
+            : target === 'raster'
+              ? 'convert-to-raster'
+              : target === 'inpaint_mask'
+                ? 'convert-to-inpaint-mask'
+                : 'convert-to-regional-guidance';
+        convert(target, getActionLabel(actionId));
+      },
+      copyTo: handleCopyTo,
+      copyToClipboard: handleCopyToClipboard,
+      cropToBbox: handleCropToBbox,
+      delete: handleDelete,
+      duplicate: handleDuplicate,
+      extractMaskedArea: handleExtractMaskedArea,
+      fitToBbox: handleFitToBbox,
+      mergeDown: handleMerge,
+      openProperties: handleOpenProperties,
+      openRename,
+      openRunWorkflow,
+      startSelectObject,
+      startFilter,
+      patchConfig: handleLayerConfigAction,
+      rasterize: handleRasterize,
+      reorder: (kind, actionId) => reorder(kind, getActionLabel(actionId)),
+      saveToAssets: handleSaveToAssets,
+      toggleLock: handleToggleLock,
+      toggleVisibility: handleToggleVisibility,
+      transform: handleTransform,
+    }),
+    [
+      convert,
+      getActionLabel,
+      handleBooleanRaster,
+      handleCopyTo,
+      handleCopyToClipboard,
+      handleCropToBbox,
+      handleDelete,
+      handleDuplicate,
+      handleExtractMaskedArea,
+      handleFitToBbox,
+      handleLayerConfigAction,
+      handleMerge,
+      handleOpenProperties,
+      handleRasterize,
+      handleSaveToAssets,
+      handleToggleLock,
+      handleToggleVisibility,
+      handleTransform,
+      openRename,
+      openRunWorkflow,
+      startSelectObject,
+      startFilter,
+      reorder,
+    ]
+  );
+
+  const runAction = useCallback(
+    (action: LayerContextAction) => {
+      void Promise.resolve()
+        .then(() => action.handler({ ...actionState, effects }))
+        .catch((error: unknown) => {
+          notify.error(t('widgets.layers.actions.actionFailed'), toErrorMessage(error));
+        });
+    },
+    [actionState, effects, notify, t]
+  );
+  const menuRenderEntries = getLayerContextMenuRenderEntries(menuLayout, Boolean(beforeDangerItems));
+  const beforeDangerSlotIndex = menuRenderEntries.findIndex((entry) => entry.kind === 'slot');
+  const isGroupedSurfaceMenu = Boolean(showGroupLabels && beforeDangerItems && beforeDangerSlotIndex >= 0);
+  const layerRenderEntries = isGroupedSurfaceMenu
+    ? menuRenderEntries.slice(0, beforeDangerSlotIndex)
+    : menuRenderEntries;
+  const dangerRenderEntries = isGroupedSurfaceMenu ? menuRenderEntries.slice(beforeDangerSlotIndex + 1) : [];
+
+  return (
+    <>
+      <Menu.Root
+        lazyMount={lazyMount}
+        open={open}
+        positioning={positioning}
+        unmountOnExit={unmountOnExit}
+        onOpenChange={onOpenChange}
+      >
+        {withTrigger ? (
+          <Menu.Trigger asChild>
+            <IconButton
+              aria-label={t('widgets.layers.options')}
+              color="fg.muted"
+              size="2xs"
+              variant="ghost"
+              onClick={stopPropagation}
+            >
+              <MoreVerticalIcon />
+            </IconButton>
+          </Menu.Trigger>
+        ) : null}
+        <Portal>
+          <Menu.Positioner>
+            <MenuContent minW="14rem" py="1">
+              {isGroupedSurfaceMenu ? (
+                <>
+                  <Menu.ItemGroup>
+                    <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                      {t(getLayerContextMenuLayerLabelKey(layer.type))}
+                    </Menu.ItemGroupLabel>
+                    {renderLayerMenuEntries({ entries: layerRenderEntries, runAction, t })}
+                  </Menu.ItemGroup>
+                  <Menu.Separator borderColor="border.subtle" />
+                  <Menu.ItemGroup>
+                    <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                      {t('widgets.labels.canvas')}
+                    </Menu.ItemGroupLabel>
+                    {beforeDangerItems}
+                  </Menu.ItemGroup>
+                  {renderLayerMenuEntries({ entries: dangerRenderEntries, runAction, t })}
+                </>
+              ) : (
+                renderLayerMenuEntries({
+                  beforeDangerItems,
+                  entries: menuRenderEntries,
+                  runAction,
+                  t,
+                })
+              )}
+            </MenuContent>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+      <RenameDialog
+        initialName={layer.name}
+        isOpen={dialogKind === 'rename'}
+        label={t('widgets.layers.actions.rename')}
+        submitLabel={t('widgets.layers.actions.rename')}
+        title={t('widgets.layers.actions.rename')}
+        onClose={closeDialog}
+        onSubmit={submitRename}
+      />
+      {dialogKind === 'run-workflow' ? (
+        <RunLayerWorkflowDialog
+          availability={workflowAvailability}
+          engine={engine}
+          isOpen
+          layerId={layer.id}
+          onClose={closeDialog}
+        />
+      ) : null}
+    </>
+  );
+};
+
+interface LayerRowMenuProps {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  engine: LayerContextMenuEngine | null;
+  index: number;
+  layer: CanvasLayerContract;
+  layers: readonly CanvasLayerContract[];
+}
+
+/** The layers-panel per-row context menu: a ⋯ trigger button, opened below it. */
+export const LayerContextMenu = (props: LayerRowMenuProps) => (
+  <LayerMenu {...props} positioning={PANEL_POSITIONING} withTrigger />
+);
+
+/** The layer + pointer position a canvas right-click resolved to. */
+export interface CanvasLayerContextMenuTarget {
+  layerId: string;
+  x: number;
+  y: number;
+}
+
+/**
+ * The canvas-surface right-click menu: the SAME {@link LayerMenu}, anchored at the
+ * cursor via a 1×1 virtual rect (no trigger DOM), controlled by `target`. The
+ * canvas widget sets `target` to the hit layer + pointer position after selecting
+ * it; `null` closes the menu. The layer and its global index are resolved from
+ * `target.layerId` against the live layer list, so the shared items get the exact
+ * same inputs the panel passes. Keyed by layer id so switching target resets the
+ * menu's sibling-dialog state.
+ *
+ * Choosing a sibling-dialog action closes the menu, which nulls `target`. The
+ * wrapper therefore owns the dialog-in-flight state and keeps rendering against
+ * the last-known (sticky) target until the dialog closes (F1).
+ */
+export const CanvasLayerContextMenu = ({
+  beforeDangerItems,
+  dispatch,
+  engine,
+  layers,
+  target,
+  showGroupLabels,
+  onClose,
+}: {
+  beforeDangerItems?: ReactNode;
+  dispatch: Dispatch<CanvasProjectMutation>;
+  engine: LayerContextMenuEngine | null;
+  layers: readonly CanvasLayerContract[];
+  target: CanvasLayerContextMenuTarget | null;
+  showGroupLabels?: boolean;
+  onClose: () => void;
+}) => {
+  // The layer a pending sibling dialog is anchored to. Captured while the live
+  // target still exists, then retained until the dialog closes.
+  const [dialogState, setDialogState] = useState<LayerMenuDialogState | null>(null);
+  const renderTarget = resolveMenuTargetForRender(target, dialogState);
+
+  const index = renderTarget ? layers.findIndex((entry) => entry.id === renderTarget.layerId) : -1;
+  const layer = index >= 0 ? layers[index] : undefined;
+
+  const anchorX = renderTarget?.x ?? 0;
+  const anchorY = renderTarget?.y ?? 0;
+  const positioning = useMemo<MenuPositioning>(
+    () => ({
+      getAnchorRect: () => ({ height: 1, width: 1, x: anchorX, y: anchorY }),
+      placement: 'bottom-start',
+    }),
+    [anchorX, anchorY]
+  );
+  const handleOpenChange = useCallback(
+    (details: { open: boolean }) => {
+      if (!details.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+  const handleDialogKindChange = useCallback(
+    (kind: LayerMenuDialogKind | null) => {
+      setDialogState(kind && target ? { kind, target } : null);
+    },
+    [target]
+  );
+
+  if (!renderTarget || !layer) {
+    return null;
+  }
+
+  return (
+    <LayerMenu
+      key={renderTarget.layerId}
+      beforeDangerItems={beforeDangerItems}
+      dispatch={dispatch}
+      dialogKind={dialogState?.kind ?? null}
+      engine={engine}
+      index={index}
+      layer={layer}
+      layers={layers}
+      lazyMount
+      // The menu itself is visible only while the live target is set; once a
+      // sibling dialog closes it (target → null), the subtree stays mounted.
+      open={!!target}
+      positioning={positioning}
+      showGroupLabels={showGroupLabels}
+      unmountOnExit
+      onOpenChange={handleOpenChange}
+      onDialogKindChange={handleDialogKindChange}
+    />
+  );
+};
+
+const stopPropagation = (event: { stopPropagation: () => void }): void => event.stopPropagation();
+
+const SUBMENU_META: Record<LayerContextSubmenuId, { defaultLabel: string; icon: LucideIcon; labelKey: string }> = {
+  'add-modifiers': {
+    defaultLabel: 'Add modifiers',
+    icon: PlusIcon,
+    labelKey: 'widgets.layers.menu.addModifiers',
+  },
+  'add-regional': { defaultLabel: 'Add', icon: PlusIcon, labelKey: 'widgets.layers.menu.add' },
+  arrange: { defaultLabel: 'Arrange', icon: ArrowUpDownIcon, labelKey: 'widgets.layers.menu.arrange' },
+  boolean: { defaultLabel: 'Boolean operations', icon: MergeIcon, labelKey: 'widgets.layers.menu.booleanOperations' },
+  'convert-to': { defaultLabel: 'Convert to', icon: ArrowRightLeftIcon, labelKey: 'widgets.layers.menu.convertTo' },
+  'copy-to': { defaultLabel: 'Copy to', icon: CopyIcon, labelKey: 'widgets.layers.menu.copyTo' },
+};
+
+const SUBMENU_POSITIONING = { placement: 'right-start' } as const;
+const QUICK_MENU_TOOLTIP_CONTENT_PROPS = { fontSize: '2xs' } as const;
+const QUICK_MENU_TOOLTIP_POSITIONING_PROPS = { placement: 'top' } as const;
+
+const renderLayerMenuEntries = ({
+  beforeDangerItems,
+  entries,
+  runAction,
+  t,
+}: {
+  beforeDangerItems?: ReactNode;
+  entries: readonly LayerContextMenuRenderEntry[];
+  runAction: (action: LayerContextAction) => void;
+  t: (key: string, options?: { defaultValue: string }) => string;
+}) =>
+  entries.map((entry) =>
+    entry.kind === 'slot' ? (
+      <Fragment key={entry.id}>
+        <Menu.Separator borderColor="border.subtle" />
+        {beforeDangerItems}
+      </Fragment>
+    ) : (
+      <LayerMenuSection key={entry.section.id} runAction={runAction} section={entry.section} t={t} />
+    )
+  );
+
+const LayerMenuSection = ({
+  runAction,
+  section,
+  t,
+}: {
+  runAction: (action: LayerContextAction) => void;
+  section: LayerContextMenuSection;
+  t: (key: string, options: { defaultValue: string }) => string;
+}) => {
+  const content = section.items.map((item) => (
+    <LayerMenuLayoutItem
+      key={item.kind === 'action' ? item.action.id : item.id}
+      compact={section.presentation === 'row'}
+      item={item}
+      runAction={runAction}
+      t={t}
+    />
+  ));
+
+  if (section.presentation === 'row') {
+    return <HStack gap="1">{content}</HStack>;
+  }
+
+  return (
+    <>
+      <Menu.Separator borderColor="border.subtle" />
+      {content}
+    </>
+  );
+};
+
+const LayerMenuLayoutItem = ({
+  compact,
+  item,
+  runAction,
+  t,
+}: {
+  compact: boolean;
+  item: LayerContextMenuItem;
+  runAction: (action: LayerContextAction) => void;
+  t: (key: string, options: { defaultValue: string }) => string;
+}) => {
+  if (item.kind === 'action') {
+    return compact ? (
+      <LayerMenuIconActionItem action={item.action} runAction={runAction} t={t} />
+    ) : (
+      <LayerMenuActionItem action={item.action} runAction={runAction} t={t} />
+    );
+  }
+
+  return <LayerMenuSubmenu compact={compact} item={item} runAction={runAction} t={t} />;
+};
+
+const LayerMenuSubmenu = ({
+  compact,
+  item,
+  runAction,
+  t,
+}: {
+  compact: boolean;
+  item: Extract<LayerContextMenuItem, { kind: 'submenu' }>;
+  runAction: (action: LayerContextAction) => void;
+  t: (key: string, options: { defaultValue: string }) => string;
+}) => {
+  const meta = SUBMENU_META[item.id];
+  const label = t(meta.labelKey, { defaultValue: meta.defaultLabel });
+
+  return (
+    <Menu.Root positioning={SUBMENU_POSITIONING}>
+      <Menu.TriggerItem
+        aria-label={label}
+        flex={compact ? '1' : undefined}
+        justifyContent={compact ? 'center' : undefined}
+      >
+        {compact ? (
+          <Tooltip
+            showArrow
+            content={label}
+            contentProps={QUICK_MENU_TOOLTIP_CONTENT_PROPS}
+            openDelay={300}
+            positioning={QUICK_MENU_TOOLTIP_POSITIONING_PROPS}
+          >
+            <Icon as={meta.icon} boxSize="4" color="fg" />
+          </Tooltip>
+        ) : (
+          <HStack gap="2" minW="0" w="full">
+            <Icon as={meta.icon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+            <Text flex="1" fontSize="xs">
+              {label}
+            </Text>
+            <Icon as={ChevronRightIcon} boxSize="3" color="fg.subtle" flexShrink={0} />
+          </HStack>
+        )}
+      </Menu.TriggerItem>
+      <Portal>
+        <Menu.Positioner>
+          <MenuContent minW="13rem" py="1">
+            {item.actions.map((action) => (
+              <LayerMenuActionItem key={action.id} action={action} runAction={runAction} t={t} />
+            ))}
+          </MenuContent>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
+
+const LayerMenuIconActionItem = ({
+  action,
+  runAction,
+  t,
+}: {
+  action: LayerContextAction;
+  runAction: (action: LayerContextAction) => void;
+  t: (key: string, options: { defaultValue: string }) => string;
+}) => {
+  const onSelect = useCallback(() => runAction(action), [action, runAction]);
+
+  return (
+    <LayerMenuIconItem
+      disabled={action.isDisabled}
+      icon={action.icon}
+      label={t(action.labelKey, { defaultValue: action.defaultLabel })}
+      value={action.id}
+      onSelect={onSelect}
+    />
+  );
+};
+
+const LayerMenuActionItem = ({
+  action,
+  runAction,
+  t,
+}: {
+  action: LayerContextAction;
+  runAction: (action: LayerContextAction) => void;
+  t: (key: string, options: { defaultValue: string }) => string;
+}) => {
+  const onSelect = useCallback(() => runAction(action), [action, runAction]);
+
+  return (
+    <LayerMenuItem
+      color={action.tone === 'danger' ? 'fg.error' : undefined}
+      disabled={action.isDisabled}
+      icon={action.icon}
+      label={t(action.labelKey, { defaultValue: action.defaultLabel })}
+      value={action.id}
+      onSelect={onSelect}
+    />
+  );
+};
+
+const LayerMenuItem = ({
+  color,
+  disabled,
+  icon,
+  label,
+  onSelect,
+  value,
+}: {
+  color?: string;
+  disabled?: boolean;
+  icon: LucideIcon;
+  label: string;
+  onSelect: () => void;
+  value: string;
+}) => (
+  <Menu.Item color={color} disabled={disabled} value={value} onSelect={onSelect}>
+    <HStack gap="2" minW="0" w="full">
+      <Icon as={icon} boxSize="3.5" color={color ?? 'fg.subtle'} flexShrink={0} />
+      <Text flex="1" fontSize="xs">
+        {label}
+      </Text>
+    </HStack>
+  </Menu.Item>
+);
+
+const LayerMenuIconItem = ({
+  color,
+  disabled,
+  icon,
+  label,
+  onSelect,
+  value,
+}: {
+  color?: string;
+  disabled?: boolean;
+  icon: LucideIcon;
+  label: string;
+  onSelect: () => void;
+  value: string;
+}) => (
+  <Tooltip
+    showArrow
+    content={label}
+    contentProps={QUICK_MENU_TOOLTIP_CONTENT_PROPS}
+    openDelay={300}
+    positioning={QUICK_MENU_TOOLTIP_POSITIONING_PROPS}
+  >
+    <Menu.Item
+      aria-label={label}
+      color={color}
+      disabled={disabled}
+      flex="1"
+      justifyContent="center"
+      value={value}
+      onSelect={onSelect}
+    >
+      <Icon as={icon} boxSize="4" color={color ?? 'fg'} />
+    </Menu.Item>
+  </Tooltip>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterControls.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterControls.test.ts
new file mode 100644
index 00000000000..506a95af375
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterControls.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import { getLayerFilterControlPolicy } from './LayerFilterControls';
+
+describe('getLayerFilterControlPolicy', () => {
+  it('keeps layer properties compact and gives the operation bar fixed-width upward-opening fields', () => {
+    expect(getLayerFilterControlPolicy('property')).toEqual({
+      controlMinH: undefined,
+      controlSize: 'xs',
+      fieldOrientation: 'vertical',
+      fieldW: undefined,
+      modelSize: 'xs',
+      positioning: { placement: 'bottom-end', sameWidth: false },
+      showFilterLabel: true,
+      showNumberStepper: true,
+    });
+    expect(getLayerFilterControlPolicy('operation')).toEqual({
+      controlMinH: undefined,
+      controlSize: 'xs',
+      fieldOrientation: 'horizontal',
+      fieldW: { enum: '13rem', filter: '11rem', model: '16rem', number: '17rem', string: '13rem' },
+      modelSize: 'xs',
+      positioning: { placement: 'top-end', sameWidth: false },
+      showFilterLabel: false,
+      showNumberStepper: false,
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterControls.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterControls.tsx
new file mode 100644
index 00000000000..7f5cb01fc2a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterControls.tsx
@@ -0,0 +1,334 @@
+import type {
+  NumberInput as ChakraNumberInput,
+  SelectValueChangeDetails,
+  SliderValueChangeDetails,
+} from '@chakra-ui/react';
+import type { FilterParamSpec } from '@workbench/generation/canvas/filterGraphs';
+import type { ModelConfig, ModelTaxonomyType } from '@workbench/models/types';
+import type { ChangeEvent } from 'react';
+
+import { Box, createListCollection, HStack, Input, NumberInput, Switch, Text } from '@chakra-ui/react';
+import { Field, Select, Slider } from '@workbench/components/ui';
+import {
+  CONTROL_FILTERS,
+  getFilterDefinition,
+  getFilterNumberBounds,
+  isSpandrelModelIdentifier,
+} from '@workbench/generation/canvas/filterGraphs';
+import { ModelSelect } from '@workbench/models/components/ModelSelect';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const SELECT_POSITIONING_DOWN = { placement: 'bottom-end', sameWidth: false } as const;
+const SELECT_POSITIONING_UP = { placement: 'top-end', sameWidth: false } as const;
+const SPANDREL_MODEL_TYPES: ModelTaxonomyType[] = ['spandrel_image_to_image'];
+
+interface LayerFilterControlsProps {
+  filterType: string;
+  settings: Record<string, unknown>;
+  disabled: boolean;
+  focusFilter: boolean;
+  variant?: LayerFilterControlsVariant;
+  onFilterTypeChange(value: string): void;
+  onSettingsChange(value: Record<string, unknown>): void;
+}
+
+type LayerFilterControlsVariant = 'operation' | 'property';
+
+export const getLayerFilterControlPolicy = (variant: LayerFilterControlsVariant) =>
+  variant === 'operation'
+    ? ({
+        controlMinH: undefined,
+        controlSize: 'xs',
+        fieldOrientation: 'horizontal',
+        fieldW: { enum: '13rem', filter: '11rem', model: '16rem', number: '17rem', string: '13rem' },
+        modelSize: 'xs',
+        positioning: SELECT_POSITIONING_UP,
+        showFilterLabel: false,
+        showNumberStepper: false,
+      } as const)
+    : ({
+        controlMinH: undefined,
+        controlSize: 'xs',
+        fieldOrientation: 'vertical',
+        fieldW: undefined,
+        modelSize: 'xs',
+        positioning: SELECT_POSITIONING_DOWN,
+        showFilterLabel: true,
+        showNumberStepper: true,
+      } as const);
+
+export const LayerFilterControls = ({
+  disabled,
+  filterType,
+  focusFilter,
+  onFilterTypeChange,
+  onSettingsChange,
+  settings,
+  variant = 'property',
+}: LayerFilterControlsProps) => {
+  const { t } = useTranslation();
+  const definition = getFilterDefinition(filterType);
+  const filterCollection = useMemo(
+    () =>
+      createListCollection({
+        items: CONTROL_FILTERS.map((filter) => ({
+          label: t(`widgets.layers.control.filters.${filter.type}`, filter.type),
+          value: filter.type,
+        })),
+      }),
+    [t]
+  );
+  const filterValue = useMemo(() => [filterType], [filterType]);
+  const policy = getLayerFilterControlPolicy(variant);
+  const filterFieldW = policy.fieldW?.filter;
+  const filterTriggerProps = useMemo(
+    () => ({ autoFocus: focusFilter, minH: policy.controlMinH }),
+    [focusFilter, policy.controlMinH]
+  );
+
+  const handleFilterTypeChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const next = value[0];
+      if (next) {
+        onFilterTypeChange(next);
+      }
+    },
+    [onFilterTypeChange]
+  );
+  const handleSettingChange = useCallback(
+    (key: string, value: unknown) => onSettingsChange({ ...settings, [key]: value }),
+    [onSettingsChange, settings]
+  );
+
+  const filterSelect = (
+    <Select
+      aria-label={t('widgets.layers.control.filter')}
+      collection={filterCollection}
+      disabled={disabled}
+      positioning={policy.positioning}
+      size={policy.controlSize}
+      triggerProps={filterTriggerProps}
+      value={filterValue}
+      valueText={t(`widgets.layers.control.filters.${filterType}`, filterType)}
+      onValueChange={handleFilterTypeChange}
+    />
+  );
+
+  return (
+    <>
+      {policy.showFilterLabel ? (
+        <Field label={t('widgets.layers.control.filter')} w={filterFieldW}>
+          {filterSelect}
+        </Field>
+      ) : (
+        <Box flexShrink="0" w={filterFieldW}>
+          {filterSelect}
+        </Box>
+      )}
+      {definition?.params.map((param) => (
+        <FilterParamField
+          key={param.key}
+          disabled={disabled}
+          param={param}
+          policy={policy}
+          settings={settings}
+          value={settings[param.key]}
+          onChange={handleSettingChange}
+        />
+      ))}
+    </>
+  );
+};
+
+interface FilterParamFieldProps {
+  disabled: boolean;
+  param: FilterParamSpec;
+  policy: ReturnType<typeof getLayerFilterControlPolicy>;
+  settings: Record<string, unknown>;
+  value: unknown;
+  onChange: (key: string, value: unknown) => void;
+}
+
+const FilterParamField = ({ disabled, param, policy, settings, value, onChange }: FilterParamFieldProps) => {
+  const { t } = useTranslation();
+  const label = t(`widgets.layers.control.filterParams.${param.key}`, param.key);
+  const labelAria = useMemo(() => [label], [label]);
+
+  const handleBoolean = useCallback(
+    ({ checked }: { checked: boolean }) => onChange(param.key, checked),
+    [onChange, param.key]
+  );
+  const handleEnum = useCallback(
+    ({ value: next }: SelectValueChangeDetails) => {
+      if (next[0]) {
+        onChange(param.key, next[0]);
+      }
+    },
+    [onChange, param.key]
+  );
+  const handleNumberEnd = useCallback(
+    ({ value: next }: SliderValueChangeDetails) => {
+      const n = next[0];
+      if (n !== undefined && Number.isFinite(n)) {
+        onChange(param.key, param.kind === 'number' && param.integer ? Math.round(n) : n);
+      }
+    },
+    [onChange, param]
+  );
+  const handleNumberInput = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        onChange(param.key, param.kind === 'number' && param.integer ? Math.round(valueAsNumber) : valueAsNumber);
+      }
+    },
+    [onChange, param]
+  );
+  const handleModel = useCallback(
+    (model: ModelConfig | null) => {
+      onChange(
+        param.key,
+        model ? { base: model.base, hash: model.hash, key: model.key, name: model.name, type: model.type } : null
+      );
+    },
+    [onChange, param.key]
+  );
+  const handleString = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => onChange(param.key, event.currentTarget.value),
+    [onChange, param.key]
+  );
+
+  const enumCollection = useMemo(
+    () =>
+      param.kind === 'enum'
+        ? createListCollection({
+            items: param.options.map((option) => ({ label: t(option.labelKey, option.value), value: option.value })),
+          })
+        : null,
+    [param, t]
+  );
+  const enumCurrent =
+    param.kind === 'enum' && typeof value === 'string' && param.options.some((option) => option.value === value)
+      ? value
+      : param.default;
+  const enumCurrentOption = param.kind === 'enum' ? param.options.find((option) => option.value === enumCurrent) : null;
+  const enumCurrentLabel = enumCurrentOption
+    ? t(enumCurrentOption.labelKey, enumCurrentOption.value)
+    : String(enumCurrent);
+  const enumValue = useMemo(() => [String(enumCurrent)], [enumCurrent]);
+  const enumTriggerProps = useMemo(() => ({ minH: policy.controlMinH }), [policy.controlMinH]);
+  const numberCurrent = typeof value === 'number' && Number.isFinite(value) ? value : param.default;
+  const numberBounds = param.kind === 'number' ? getFilterNumberBounds(param, settings) : null;
+  const sliderCurrent = numberBounds
+    ? Math.min(numberBounds.sliderMax, Math.max(numberBounds.sliderMin, Number(numberCurrent)))
+    : Number(numberCurrent);
+  const numberValue = useMemo(() => [sliderCurrent], [sliderCurrent]);
+
+  if (param.kind === 'boolean') {
+    return (
+      <Switch.Root
+        checked={typeof value === 'boolean' ? value : param.default}
+        colorPalette="accent"
+        disabled={disabled}
+        minH={policy.controlMinH}
+        size="xs"
+        onCheckedChange={handleBoolean}
+      >
+        <Switch.HiddenInput />
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        <Switch.Label>
+          <Text fontSize="xs">{label}</Text>
+        </Switch.Label>
+      </Switch.Root>
+    );
+  }
+
+  if (param.kind === 'enum' && enumCollection) {
+    return (
+      <Field label={label} orientation={policy.fieldOrientation} w={policy.fieldW?.enum}>
+        <Select
+          aria-label={label}
+          collection={enumCollection}
+          disabled={disabled}
+          positioning={policy.positioning}
+          size={policy.controlSize}
+          triggerProps={enumTriggerProps}
+          value={enumValue}
+          valueText={enumCurrentLabel}
+          onValueChange={handleEnum}
+        />
+      </Field>
+    );
+  }
+
+  if (param.kind === 'model') {
+    const model = isSpandrelModelIdentifier(value) ? (value as { key: string }) : null;
+    return (
+      <Field label={label} orientation={policy.fieldOrientation} required w={policy.fieldW?.model}>
+        <ModelSelect
+          disabled={disabled}
+          invalid={!model}
+          modelTypes={SPANDREL_MODEL_TYPES}
+          placeholder={label}
+          size={policy.modelSize}
+          value={model && typeof model.key === 'string' ? model.key : null}
+          onChange={handleModel}
+        />
+      </Field>
+    );
+  }
+
+  if (param.kind === 'string') {
+    return (
+      <Field label={label} orientation={policy.fieldOrientation} w={policy.fieldW?.string}>
+        <Input
+          disabled={disabled}
+          minH={policy.controlMinH}
+          size={policy.controlSize}
+          value={typeof value === 'string' ? value : param.default}
+          onChange={handleString}
+        />
+      </Field>
+    );
+  }
+
+  if (param.kind !== 'number' || !numberBounds) {
+    return null;
+  }
+
+  return (
+    <Field label={label} orientation={policy.fieldOrientation} w={policy.fieldW?.number}>
+      <HStack gap="2">
+        <Slider
+          aria-label={labelAria}
+          disabled={disabled}
+          flex="1"
+          max={numberBounds.sliderMax}
+          minH={policy.controlMinH}
+          min={numberBounds.sliderMin}
+          size="sm"
+          step={numberBounds.step}
+          value={numberValue}
+          withThumbTooltip
+          onValueChangeEnd={handleNumberEnd}
+        />
+        <NumberInput.Root
+          disabled={disabled}
+          max={numberBounds.inputMax}
+          min={numberBounds.inputMin}
+          minH={policy.controlMinH}
+          size={policy.controlSize}
+          step={numberBounds.step}
+          value={String(numberCurrent)}
+          w={policy.showNumberStepper ? '20' : '14'}
+          onValueChange={handleNumberInput}
+        >
+          {policy.showNumberStepper ? <NumberInput.Control /> : null}
+          <NumberInput.Input aria-label={label} />
+        </NumberInput.Root>
+      </HStack>
+    </Field>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationButton.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationButton.test.tsx
new file mode 100644
index 00000000000..aa06a8cb681
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationButton.test.tsx
@@ -0,0 +1,224 @@
+import type { StartFilterOperationResult } from '@workbench/canvas-operations/api';
+import type * as WorkbenchUI from '@workbench/components/ui';
+import type { ReactNode } from 'react';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createControlLayer, createEmptyPaintLayer } from '@workbench/widgets/layers/layerOps';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { LayerFilterOperationButton, type LayerFilterOperationEngine } from './LayerFilterOperationButton';
+
+interface CapturedButtonProps {
+  children?: ReactNode;
+  disabled?: boolean;
+  onClick?: () => void;
+}
+
+interface CapturedTooltipProps {
+  children?: ReactNode;
+  content?: ReactNode;
+  disabled?: boolean;
+}
+
+const { captured, notifyError, thumbnailSubscription } = vi.hoisted(() => ({
+  captured: {
+    button: null as CapturedButtonProps | null,
+    tooltip: null as CapturedTooltipProps | null,
+  },
+  notifyError: vi.fn(),
+  thumbnailSubscription: vi.fn(),
+}));
+
+vi.mock('@workbench/components/ui', async (importOriginal) => {
+  const actual = await importOriginal<typeof WorkbenchUI>();
+
+  return {
+    ...actual,
+    Button: (props: CapturedButtonProps) => {
+      captured.button = props;
+      return <button disabled={props.disabled}>{props.children}</button>;
+    },
+    Tooltip: (props: CapturedTooltipProps) => {
+      captured.tooltip = props;
+      return props.children;
+    },
+  };
+});
+vi.mock('@workbench/useNotify', () => ({
+  useNotify: () => ({ error: notifyError, info: vi.fn(), success: vi.fn() }),
+}));
+vi.mock('@workbench/widgets/canvas/engineStoreHooks', () => ({
+  useLayerThumbnailVersion: thumbnailSubscription,
+}));
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+type TestLayer = ReturnType<typeof createControlLayer> | ReturnType<typeof createEmptyPaintLayer>;
+
+const createEngine = (
+  hasExportableContent: boolean,
+  launch: () => StartFilterOperationResult | undefined = () => 'started'
+) => {
+  const hasExportableLayerContent = vi.fn(() => hasExportableContent);
+  const startFilterOperation = vi.fn(launch);
+  const engine = {
+    exports: { hasExportableLayerContent },
+    operations: { startFilterOperation },
+  } as unknown as LayerFilterOperationEngine;
+
+  return { engine, hasExportableLayerContent, startFilterOperation };
+};
+
+const renderButton = (engine: LayerFilterOperationEngine | null, layer: TestLayer, onOperationStarted = vi.fn()) => {
+  renderToStaticMarkup(
+    <ChakraProvider value={system}>
+      <LayerFilterOperationButton
+        engine={engine}
+        layer={layer}
+        onOperationStarted={onOperationStarted}
+        operations={
+          engine
+            ? (engine as unknown as { operations: { startFilterOperation(id: string): StartFilterOperationResult } })
+                .operations
+            : null
+        }
+      />
+    </ChakraProvider>
+  );
+
+  expect(captured.button).not.toBeNull();
+  expect(captured.tooltip).not.toBeNull();
+
+  return {
+    button: captured.button!,
+    onOperationStarted,
+    tooltip: captured.tooltip!,
+  };
+};
+
+beforeEach(() => {
+  captured.button = null;
+  captured.tooltip = null;
+  notifyError.mockClear();
+  thumbnailSubscription.mockClear();
+});
+
+describe('LayerFilterOperationButton eligibility', () => {
+  it.each([
+    {
+      expectedReasonKey: 'widgets.layers.actions.notReady',
+      getEngine: () => null,
+      getLayer: () => createEmptyPaintLayer('Raster', 'raster'),
+      scenario: 'missing engine',
+    },
+    {
+      expectedReasonKey: 'widgets.layers.actions.disabled',
+      getEngine: () => createEngine(true).engine,
+      getLayer: () => ({ ...createEmptyPaintLayer('Raster', 'raster'), isEnabled: false }),
+      scenario: 'disabled layer',
+    },
+    {
+      expectedReasonKey: 'widgets.layers.actions.locked',
+      getEngine: () => createEngine(true).engine,
+      getLayer: () => ({ ...createEmptyPaintLayer('Raster', 'raster'), isLocked: true }),
+      scenario: 'locked layer',
+    },
+    {
+      expectedReasonKey: 'widgets.layers.actions.empty',
+      getEngine: () => createEngine(false).engine,
+      getLayer: () => createEmptyPaintLayer('Raster', 'raster'),
+      scenario: 'empty layer',
+    },
+  ])('disables a $scenario with its stable tooltip reason', ({ expectedReasonKey, getEngine, getLayer }) => {
+    const { button, tooltip } = renderButton(getEngine(), getLayer());
+
+    expect(button.disabled).toBe(true);
+    expect(tooltip.disabled).toBe(false);
+    expect(tooltip.content).toBe(expectedReasonKey);
+  });
+
+  it.each([
+    ['raster', createEmptyPaintLayer('Raster', 'raster')],
+    ['control', createControlLayer('Control', 'control')],
+  ] as const)('enables a filterable %s layer and subscribes to its thumbnail', (_type, layer) => {
+    const { engine } = createEngine(true);
+    const { button, tooltip } = renderButton(engine, layer);
+
+    expect(button.children).toBe('widgets.layers.control.filter');
+    expect(button.disabled).toBe(false);
+    expect(tooltip.disabled).toBe(true);
+    expect(tooltip.content).toBe('');
+    expect(thumbnailSubscription).toHaveBeenCalledOnce();
+    expect(thumbnailSubscription).toHaveBeenCalledWith(engine, layer.id);
+  });
+});
+
+describe('LayerFilterOperationButton launch interaction', () => {
+  it('starts synchronously and reports success exactly once', () => {
+    const calls: string[] = [];
+    const layer = createEmptyPaintLayer('Raster', 'raster');
+    const { engine, startFilterOperation } = createEngine(true, () => {
+      calls.push('engine');
+      return 'started';
+    });
+    const onOperationStarted = vi.fn(() => calls.push('success'));
+    const { button } = renderButton(engine, layer, onOperationStarted);
+
+    button.onClick?.();
+
+    expect(calls).toEqual(['engine', 'success']);
+    expect(startFilterOperation).toHaveBeenCalledOnce();
+    expect(startFilterOperation).toHaveBeenCalledWith(layer.id);
+    expect(onOperationStarted).toHaveBeenCalledOnce();
+    expect(notifyError).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['missing', 'widgets.layers.actions.missing'],
+    ['disabled', 'widgets.layers.actions.disabled'],
+    ['locked', 'widgets.layers.actions.locked'],
+    ['unsupported', 'widgets.layers.actions.unsupported'],
+    ['not-ready', 'widgets.layers.actions.notReady'],
+  ] as const)('keeps properties open and reports an engine %s rejection', (result, reasonKey) => {
+    const layer = createControlLayer('Control', 'control');
+    const { engine, startFilterOperation } = createEngine(true, () => result);
+    const onOperationStarted = vi.fn();
+    const { button } = renderButton(engine, layer, onOperationStarted);
+
+    button.onClick?.();
+
+    expect(startFilterOperation).toHaveBeenCalledOnce();
+    expect(startFilterOperation).toHaveBeenCalledWith(layer.id);
+    expect(onOperationStarted).not.toHaveBeenCalled();
+    expect(notifyError).toHaveBeenCalledOnce();
+    expect(notifyError).toHaveBeenCalledWith('widgets.layers.actions.actionFailed', reasonKey);
+  });
+
+  it('keeps a missing-engine launch disabled and inert', () => {
+    const layer = createEmptyPaintLayer('Raster', 'raster');
+    const onOperationStarted = vi.fn();
+    const { button } = renderButton(null, layer, onOperationStarted);
+
+    button.onClick?.();
+
+    expect(button.disabled).toBe(true);
+    expect(onOperationStarted).not.toHaveBeenCalled();
+    expect(notifyError).not.toHaveBeenCalled();
+  });
+
+  it('does not report an undefined engine launch result', () => {
+    const layer = createEmptyPaintLayer('Raster', 'raster');
+    const { engine, startFilterOperation } = createEngine(true, () => undefined);
+    const onOperationStarted = vi.fn();
+    const { button } = renderButton(engine, layer, onOperationStarted);
+
+    button.onClick?.();
+
+    expect(startFilterOperation).toHaveBeenCalledOnce();
+    expect(onOperationStarted).not.toHaveBeenCalled();
+    expect(notifyError).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationButton.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationButton.tsx
new file mode 100644
index 00000000000..ec17094be84
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationButton.tsx
@@ -0,0 +1,71 @@
+import type { CanvasOperationCapability } from '@workbench/canvas-operations/api';
+import type { CanvasControlLayerContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+
+import { Box } from '@chakra-ui/react';
+import { Button, Tooltip } from '@workbench/components/ui';
+import { useNotify } from '@workbench/useNotify';
+import { useLayerThumbnailVersion } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import {
+  getLayerFilterLaunchDisabledReason,
+  getLayerFilterLaunchReasonKey,
+  type LayerFilterLaunchRejectedResult,
+  runLayerFilterOperation,
+} from './layerPropertiesOperation';
+
+export type LayerFilterOperationEngine = Pick<CanvasEngineHandle, 'exports' | 'projectId' | 'stores'>;
+
+interface LayerFilterOperationButtonProps {
+  engine: LayerFilterOperationEngine | null;
+  layer: CanvasRasterLayerContractV2 | CanvasControlLayerContract;
+  onOperationStarted(): void;
+  operations: Pick<CanvasOperationCapability, 'startFilterOperation'> | null;
+}
+
+export const LayerFilterOperationButton = ({
+  engine,
+  layer,
+  onOperationStarted,
+  operations,
+}: LayerFilterOperationButtonProps) => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  useLayerThumbnailVersion(engine, layer.id);
+
+  const disabledReason = getLayerFilterLaunchDisabledReason({
+    hasEngine: engine !== null,
+    hasExportableContent: engine?.exports.hasExportableLayerContent(layer.id) ?? false,
+    isEnabled: layer.isEnabled,
+    isLocked: layer.isLocked,
+  });
+
+  const onOperationRejected = useCallback(
+    (result: LayerFilterLaunchRejectedResult) => {
+      notify.error(t('widgets.layers.actions.actionFailed'), t(getLayerFilterLaunchReasonKey(result)));
+    },
+    [notify, t]
+  );
+
+  const start = useCallback(() => {
+    if (!engine || !operations || disabledReason) {
+      return;
+    }
+    runLayerFilterOperation(() => operations.startFilterOperation(layer.id), onOperationStarted, onOperationRejected);
+  }, [disabledReason, engine, layer.id, onOperationRejected, onOperationStarted, operations]);
+
+  return (
+    <Tooltip
+      content={disabledReason ? t(getLayerFilterLaunchReasonKey(disabledReason)) : ''}
+      disabled={disabledReason === null}
+    >
+      <Box w="full">
+        <Button disabled={disabledReason !== null} size="xs" variant="outline" w="full" onClick={start}>
+          {t('widgets.layers.control.filter')}
+        </Button>
+      </Box>
+    </Tooltip>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationDelegation.test.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationDelegation.test.tsx
new file mode 100644
index 00000000000..bf6c1568d18
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerFilterOperationDelegation.test.tsx
@@ -0,0 +1,86 @@
+import type { CanvasEngine } from '@workbench/canvas-operations/createCanvasEngine';
+import type { CanvasControlLayerContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { ChakraProvider } from '@chakra-ui/react';
+import { system } from '@theme/system';
+import { createControlLayer, createEmptyPaintLayer } from '@workbench/widgets/layers/layerOps';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ControlLayerSettings } from './ControlLayerSettings';
+import { RasterLayerFilterSection } from './RasterLayerFilterSection';
+
+interface SharedLaunchProps {
+  engine: CanvasEngine | null;
+  layer: CanvasControlLayerContract | CanvasRasterLayerContractV2;
+  onOperationStarted(): void;
+  operations: unknown;
+}
+
+const { dispatch, operations, renderSharedLaunch } = vi.hoisted(() => ({
+  dispatch: vi.fn(),
+  operations: { startFilterOperation: vi.fn() },
+  renderSharedLaunch: vi.fn(),
+}));
+const ENGINE = {
+  document: { getDocument: vi.fn(() => ({ layers: [] })) },
+  exports: { hasExportableLayerContent: vi.fn(() => false) },
+} as unknown as CanvasEngine;
+
+vi.mock('./LayerFilterOperationButton', () => ({
+  LayerFilterOperationButton: (props: SharedLaunchProps) => {
+    renderSharedLaunch(props);
+    return <span>shared filter launch</span>;
+  },
+}));
+vi.mock('@workbench/canvas-operations/createCanvasEngine', () => ({
+  getCanvasOperations: () => operations,
+}));
+vi.mock('@workbench/models/modelsStore', () => ({
+  useModelsSelector: (selector: (snapshot: { models: never[] }) => unknown) => selector({ models: [] }),
+}));
+vi.mock('@workbench/WorkbenchContext', () => ({
+  useActiveProjectId: () => 'project',
+  useActiveProjectSelector: () => null,
+  useWorkbenchDispatch: () => dispatch,
+  useWorkbenchStore: () => ({ dispatch, getState: vi.fn() }),
+}));
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+beforeEach(() => {
+  renderSharedLaunch.mockClear();
+});
+
+describe('layer filter launch delegation', () => {
+  it('delegates raster launch rendering to the shared control with the original props', () => {
+    const layer = createEmptyPaintLayer('Raster', 'raster');
+    const onOperationStarted = vi.fn();
+
+    renderToStaticMarkup(
+      <RasterLayerFilterSection engine={ENGINE} layer={layer} onOperationStarted={onOperationStarted} />
+    );
+
+    expect(renderSharedLaunch).toHaveBeenCalledOnce();
+    expect(renderSharedLaunch).toHaveBeenCalledWith(
+      expect.objectContaining({ engine: ENGINE, layer, onOperationStarted, operations: expect.any(Object) })
+    );
+  });
+
+  it('delegates control-layer launch rendering to the shared control with the original props', () => {
+    const layer = createControlLayer('Control', 'control');
+    const onOperationStarted = vi.fn();
+
+    renderToStaticMarkup(
+      <ChakraProvider value={system}>
+        <ControlLayerSettings engine={ENGINE} layer={layer} onOperationStarted={onOperationStarted} />
+      </ChakraProvider>
+    );
+
+    expect(renderSharedLaunch).toHaveBeenCalledOnce();
+    expect(renderSharedLaunch).toHaveBeenCalledWith(
+      expect.objectContaining({ engine: ENGINE, layer, onOperationStarted, operations: expect.any(Object) })
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerGroupSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerGroupSection.tsx
new file mode 100644
index 00000000000..23177a8abb4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerGroupSection.tsx
@@ -0,0 +1,324 @@
+import type { DragEndEvent } from '@dnd-kit/core';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasLayerContract } from '@workbench/types';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { LucideIcon } from 'lucide-react';
+import type { Dispatch } from 'react';
+
+import { Collapsible, HStack, Icon, Stack, Text } from '@chakra-ui/react';
+import { closestCenter, DndContext, KeyboardSensor, PointerSensor, useSensor, useSensors } from '@dnd-kit/core';
+import { restrictToParentElement, restrictToVerticalAxis } from '@dnd-kit/modifiers';
+import { SortableContext, verticalListSortingStrategy } from '@dnd-kit/sortable';
+import { canMergeVisibleRasters } from '@workbench/canvas-engine/document/mergeVisible';
+import { IconButton, toaster, Tooltip } from '@workbench/components/ui';
+import { useCanvasDocumentEditingLocked } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectName } from '@workbench/WorkbenchContext';
+import { ChevronDownIcon, EyeIcon, EyeOffIcon, FileDownIcon, LayersIcon, PlusIcon } from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { LayerGroupKey } from './layerGroups';
+
+import { groupAddItemId } from './addLayerMenu';
+import { LAYER_KEYBOARD_SENSOR_OPTIONS } from './layerDndConfig';
+import { canExportRasterPsd, getGroupActions, isGroupAllVisible, planGroupVisibilityToggle } from './layerGroupActions';
+import { reorderWithinGroup } from './layerGroups';
+import { LayerListItem, type LayerListItemEngine } from './LayerListItem';
+import { applyStructural } from './layerOps';
+import { getPsdExportNoticeKey } from './psdExportNotice';
+import { useAddLayer } from './useAddLayer';
+
+type LayerGroupEngine = LayerListItemEngine & Pick<CanvasEngineHandle, 'exports' | 'layers' | 'stores'>;
+
+const DND_MODIFIERS = [restrictToVerticalAxis, restrictToParentElement];
+const POINTER_SENSOR_OPTIONS = { activationConstraint: { distance: 6 } } as const;
+
+interface LayerGroupSectionProps {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  engine: LayerGroupEngine | null;
+  groupKey: LayerGroupKey;
+  groupLayers: readonly CanvasLayerContract[];
+  isCollapsed: boolean;
+  layers: readonly CanvasLayerContract[];
+  onToggleCollapse: (groupKey: LayerGroupKey) => void;
+  selectedLayerId: string | null;
+}
+
+/**
+ * One collapsible type-group section: a header (chevron + name + count + a
+ * right-aligned action cluster) and, when expanded, the group's rows in a
+ * self-contained `DndContext`. Scoping DnD to the group means a drag can never see
+ * (or drop onto) another group's rows — cross-group moves are structurally
+ * impossible. Collapsing a group unmounts only its own rows, so drag-and-drop in
+ * the other (still-expanded) groups is unaffected.
+ */
+export const LayerGroupSection = ({
+  dispatch,
+  engine,
+  groupKey,
+  groupLayers,
+  isCollapsed,
+  layers,
+  onToggleCollapse,
+  selectedLayerId,
+}: LayerGroupSectionProps) => {
+  const { t } = useTranslation();
+  const editingLocked = useCanvasDocumentEditingLocked(engine);
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, POINTER_SENSOR_OPTIONS),
+    useSensor(KeyboardSensor, LAYER_KEYBOARD_SENSOR_OPTIONS)
+  );
+
+  const globalIndexById = useMemo(() => {
+    const map = new Map<string, number>();
+    layers.forEach((layer, index) => map.set(layer.id, index));
+    return map;
+  }, [layers]);
+
+  const groupIds = useMemo(() => groupLayers.map((layer) => layer.id), [groupLayers]);
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      if (editingLocked) {
+        return;
+      }
+      const { active, over } = event;
+      if (!over) {
+        return;
+      }
+      const next = reorderWithinGroup(layers, String(active.id), String(over.id));
+      if (!next) {
+        return;
+      }
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.actions.reorder'),
+        { orderedIds: next, type: 'reorderCanvasLayers' },
+        { orderedIds: layers.map((layer) => layer.id), type: 'reorderCanvasLayers' }
+      );
+    },
+    [dispatch, editingLocked, engine, layers, t]
+  );
+
+  const handleToggleCollapse = useCallback(() => onToggleCollapse(groupKey), [groupKey, onToggleCollapse]);
+
+  return (
+    <Stack gap="1">
+      <HStack gap="1" px="1">
+        <IconButton
+          aria-label={t(isCollapsed ? 'widgets.layers.groupActions.expand' : 'widgets.layers.groupActions.collapse')}
+          color="fg.subtle"
+          size="2xs"
+          variant="ghost"
+          onClick={handleToggleCollapse}
+        >
+          <Icon
+            as={ChevronDownIcon}
+            boxSize="3.5"
+            transform={isCollapsed ? 'rotate(-90deg)' : undefined}
+            transitionDuration="fast"
+            transitionProperty="transform"
+          />
+        </IconButton>
+        <Text
+          color="fg.subtle"
+          cursor="pointer"
+          flex="1"
+          fontSize="2xs"
+          fontWeight="700"
+          textTransform="uppercase"
+          truncate
+          userSelect="none"
+          onClick={handleToggleCollapse}
+        >
+          {t(`widgets.layers.groups.${groupKey}`)} ({groupLayers.length})
+        </Text>
+        <GroupActions
+          dispatch={dispatch}
+          engine={engine}
+          editingLocked={editingLocked}
+          groupKey={groupKey}
+          groupLayers={groupLayers}
+          layers={layers}
+        />
+      </HStack>
+      {/* unmountOnExit: collapsing must UNMOUNT the rows (not just hide them) so an
+          open per-row properties popover — and any control-layer filter preview it
+          hosts — is torn down with them (Task 38/39 cleanup contract). */}
+      <Collapsible.Root lazyMount open={!isCollapsed} unmountOnExit>
+        <Collapsible.Content>
+          <DndContext
+            collisionDetection={closestCenter}
+            modifiers={DND_MODIFIERS}
+            sensors={sensors}
+            onDragEnd={handleDragEnd}
+          >
+            <SortableContext items={groupIds} strategy={verticalListSortingStrategy}>
+              <Stack gap="0.5">
+                {groupLayers.map((layer) => (
+                  <LayerListItem
+                    key={layer.id}
+                    dispatch={dispatch}
+                    editingLocked={editingLocked}
+                    engine={engine}
+                    index={globalIndexById.get(layer.id) ?? 0}
+                    isSelected={layer.id === selectedLayerId}
+                    layer={layer}
+                    layers={layers}
+                  />
+                ))}
+              </Stack>
+            </SortableContext>
+          </DndContext>
+        </Collapsible.Content>
+      </Collapsible.Root>
+    </Stack>
+  );
+};
+
+/**
+ * The right-aligned group-header action cluster. The set of actions is data
+ * (`getGroupActions`), so Task 44's PSD export button drops in by extending that
+ * array + this switch — no new prop wiring.
+ */
+const GroupActions = ({
+  dispatch,
+  editingLocked,
+  engine,
+  groupKey,
+  groupLayers,
+  layers,
+}: {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  editingLocked: boolean;
+  engine: LayerGroupEngine | null;
+  groupKey: LayerGroupKey;
+  groupLayers: readonly CanvasLayerContract[];
+  layers: readonly CanvasLayerContract[];
+}) => {
+  const { t } = useTranslation();
+  const addLayer = useAddLayer();
+  const projectName = useActiveProjectName();
+  const allVisible = isGroupAllVisible(groupLayers);
+  // Enablement and execution share the same contributor selector and the
+  // engine's live-content predicate, so empty paint layers do not enable an op.
+  const canMerge =
+    !editingLocked &&
+    !!engine &&
+    groupKey === 'raster' &&
+    canMergeVisibleRasters(layers, engine.exports.hasExportableLayerContent);
+  const canExport = !!engine && groupKey === 'raster' && canExportRasterPsd(layers);
+
+  const handleNew = useCallback(() => addLayer(groupAddItemId(groupKey)), [addLayer, groupKey]);
+
+  const handleToggleVisibility = useCallback(() => {
+    const { forward, inverse } = planGroupVisibilityToggle(groupLayers);
+    applyStructural(
+      engine,
+      dispatch,
+      t('widgets.layers.groupActions.toggleVisibility'),
+      { type: 'setCanvasLayersEnabled', updates: forward },
+      { type: 'setCanvasLayersEnabled', updates: inverse }
+    );
+  }, [dispatch, engine, groupLayers, t]);
+
+  const handleMergeVisible = useCallback(() => {
+    if (!engine) {
+      return;
+    }
+    void engine.layers.mergeVisibleRasterLayers().then((result) => {
+      if (result === 'not-ready') {
+        toaster.create({ title: t('widgets.layers.groupActions.mergeNotReady'), type: 'warning' });
+      }
+    });
+  }, [engine, t]);
+
+  const handleExportPsd = useCallback(async () => {
+    if (!engine) {
+      return;
+    }
+    // Read-only: no dispatch, no history. The engine lazily loads `ag-psd`,
+    // bakes the raster layers, and triggers the download. Surface the refusal
+    // cases (still-loading caches / oversized bounds / nothing to export).
+    try {
+      const result = await engine.exports.exportRasterLayersToPsd(projectName);
+      const noticeKey = getPsdExportNoticeKey(result);
+      if (noticeKey) {
+        toaster.create({ title: t(noticeKey), type: 'warning' });
+      }
+    } catch {
+      toaster.create({ title: t('widgets.layers.groupActions.exportFailed'), type: 'error' });
+    }
+  }, [engine, projectName, t]);
+
+  const actions = getGroupActions(groupKey);
+
+  return (
+    <HStack gap="0.5">
+      {actions.map((action) => {
+        switch (action) {
+          case 'mergeVisible':
+            return (
+              <GroupActionButton
+                key={action}
+                disabled={!canMerge}
+                icon={LayersIcon}
+                label={t('widgets.layers.groupActions.mergeVisible')}
+                onClick={handleMergeVisible}
+              />
+            );
+          case 'exportPsd':
+            return (
+              <GroupActionButton
+                key={action}
+                disabled={editingLocked || !canExport}
+                icon={FileDownIcon}
+                label={t('widgets.layers.groupActions.exportPsd')}
+                onClick={handleExportPsd}
+              />
+            );
+          case 'toggleVisibility':
+            return (
+              <GroupActionButton
+                key={action}
+                disabled={editingLocked}
+                icon={allVisible ? EyeIcon : EyeOffIcon}
+                label={t(allVisible ? 'widgets.layers.groupActions.hideAll' : 'widgets.layers.groupActions.showAll')}
+                onClick={handleToggleVisibility}
+              />
+            );
+          case 'new':
+            return (
+              <GroupActionButton
+                key={action}
+                disabled={editingLocked}
+                icon={PlusIcon}
+                label={t('widgets.layers.groupActions.new')}
+                onClick={handleNew}
+              />
+            );
+        }
+      })}
+    </HStack>
+  );
+};
+
+const GroupActionButton = ({
+  disabled,
+  icon,
+  label,
+  onClick,
+}: {
+  disabled?: boolean;
+  icon: LucideIcon;
+  label: string;
+  onClick: () => void;
+}) => (
+  <Tooltip content={label}>
+    <IconButton aria-label={label} color="fg.subtle" disabled={disabled} size="2xs" variant="ghost" onClick={onClick}>
+      <Icon as={icon} boxSize="3.5" />
+    </IconButton>
+  </Tooltip>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerListItem.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerListItem.test.ts
new file mode 100644
index 00000000000..d3a63a7f57c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerListItem.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { getLayerListItemInteractionState } from './LayerListItem';
+
+describe('getLayerListItemInteractionState', () => {
+  it('keeps selection available while disabling document edits and sorting during an operation', () => {
+    expect(getLayerListItemInteractionState(true)).toEqual({
+      canRename: false,
+      canSelect: true,
+      canToggleLock: false,
+      canToggleVisibility: false,
+      sortableDisabled: true,
+    });
+  });
+
+  it('enables ordinary row editing and sorting when document editing is unlocked', () => {
+    expect(getLayerListItemInteractionState(false)).toEqual({
+      canRename: true,
+      canSelect: true,
+      canToggleLock: true,
+      canToggleVisibility: true,
+      sortableDisabled: false,
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerListItem.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerListItem.tsx
new file mode 100644
index 00000000000..d8a2f849184
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerListItem.tsx
@@ -0,0 +1,247 @@
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasLayerContract } from '@workbench/types';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { Dispatch, KeyboardEvent, MouseEvent } from 'react';
+
+import { Badge, Box, HStack, Input, Stack, Text } from '@chakra-ui/react';
+import { useSortable } from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import { IconButton, Row, ToggleDot } from '@workbench/components/ui';
+import { LockIcon, LockOpenIcon } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import {
+  CanvasLayerContextMenu,
+  type CanvasLayerContextMenuTarget,
+  LayerContextMenu,
+  type LayerContextMenuEngine,
+} from './LayerContextMenu';
+import { createLayerMenuTargetFromContextEvent } from './layerMenuState';
+import { applyStructural } from './layerOps';
+import { LayerPropertiesPopover, type LayerPropertiesEngine } from './LayerPropertiesPopover';
+import { LayerThumbnail } from './LayerThumbnail';
+
+export type LayerListItemEngine = LayerContextMenuEngine & LayerPropertiesEngine & Pick<CanvasEngineHandle, 'previews'>;
+
+/** i18n key for a layer's short type/source badge. */
+const layerBadgeKey = (layer: CanvasLayerContract): string => {
+  if (layer.type === 'raster') {
+    return layer.source.type === 'image' ? 'widgets.layers.types.image' : 'widgets.layers.types.paint';
+  }
+  return `widgets.layers.types.${layer.type}`;
+};
+
+interface LayerListItemProps {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  editingLocked: boolean;
+  engine: LayerListItemEngine | null;
+  index: number;
+  isSelected: boolean;
+  layer: CanvasLayerContract;
+  layers: readonly CanvasLayerContract[];
+}
+
+export const getLayerListItemInteractionState = (editingLocked: boolean) => ({
+  canRename: !editingLocked,
+  canSelect: true,
+  canToggleLock: !editingLocked,
+  canToggleVisibility: !editingLocked,
+  sortableDisabled: editingLocked,
+});
+
+/**
+ * One layer row: thumbnail, name (double-click to rename), type badge,
+ * visibility + lock toggles, a properties popover (blend mode + the layer's
+ * type-specific settings), and an overflow/context menu. The whole row is the
+ * drag target — no visible handle — with a pointer distance activation
+ * constraint so clicks, double-click rename, and the row buttons still work;
+ * the selected layer's opacity (and mask fill swatch) lives in the panel header.
+ */
+export const LayerListItem = ({
+  dispatch,
+  editingLocked,
+  engine,
+  index,
+  isSelected,
+  layer,
+  layers,
+}: LayerListItemProps) => {
+  const { t } = useTranslation();
+  const interaction = getLayerListItemInteractionState(editingLocked);
+  const { attributes, isDragging, listeners, setNodeRef, transform, transition } = useSortable({
+    disabled: interaction.sortableDisabled,
+    id: layer.id,
+  });
+  const [isEditing, setIsEditing] = useState(false);
+  const [draftName, setDraftName] = useState(layer.name);
+  const [contextMenuTarget, setContextMenuTarget] = useState<CanvasLayerContextMenuTarget | null>(null);
+
+  const dndStyle = useMemo(
+    () => ({
+      opacity: isDragging ? 0.4 : undefined,
+      position: 'relative' as const,
+      transform: CSS.Translate.toString(transform),
+      transition,
+      zIndex: isDragging ? 1 : undefined,
+    }),
+    [isDragging, transform, transition]
+  );
+
+  const handleSelect = useCallback(() => {
+    if (interaction.canSelect && !isSelected) {
+      dispatch({ id: layer.id, type: 'setCanvasSelectedLayer' });
+    }
+  }, [dispatch, interaction.canSelect, isSelected, layer.id]);
+
+  const patchBase = useCallback(
+    (label: string, forward: Partial<CanvasLayerContract>, inverse: Partial<CanvasLayerContract>) => {
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { id: layer.id, patch: forward, type: 'updateCanvasLayer' },
+        { id: layer.id, patch: inverse, type: 'updateCanvasLayer' }
+      );
+    },
+    [dispatch, engine, layer.id]
+  );
+
+  const handleToggleVisible = useCallback(
+    (checked: boolean) => {
+      patchBase(t('widgets.layers.actions.toggleVisibility'), { isEnabled: checked }, { isEnabled: layer.isEnabled });
+    },
+    [layer.isEnabled, patchBase, t]
+  );
+
+  const handleToggleLock = useCallback(
+    (event: { stopPropagation: () => void }) => {
+      event.stopPropagation();
+      patchBase(t('widgets.layers.actions.toggleLock'), { isLocked: !layer.isLocked }, { isLocked: layer.isLocked });
+    },
+    [layer.isLocked, patchBase, t]
+  );
+
+  const startEditing = useCallback(() => {
+    setDraftName(layer.name);
+    setIsEditing(true);
+  }, [layer.name]);
+
+  const commitName = useCallback(() => {
+    setIsEditing(false);
+    const name = draftName.trim();
+    if (name && name !== layer.name) {
+      patchBase(t('widgets.layers.actions.rename'), { name }, { name: layer.name });
+    }
+  }, [draftName, layer.name, patchBase, t]);
+
+  const handleNameKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLInputElement>) => {
+      // Keep rename keystrokes from reaching canvas-level shortcuts.
+      event.stopPropagation();
+      if (event.key === 'Enter') {
+        commitName();
+      } else if (event.key === 'Escape') {
+        setIsEditing(false);
+      }
+    },
+    [commitName]
+  );
+
+  const handleNameChange = useCallback((event: { target: { value: string } }) => setDraftName(event.target.value), []);
+
+  const handleContextMenu = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      if (!isSelected) {
+        dispatch({ id: layer.id, type: 'setCanvasSelectedLayer' });
+      }
+      setContextMenuTarget(createLayerMenuTargetFromContextEvent(layer.id, event));
+    },
+    [dispatch, isSelected, layer.id]
+  );
+
+  const closeContextMenu = useCallback(() => setContextMenuTarget(null), []);
+
+  return (
+    <Box ref={setNodeRef} style={dndStyle}>
+      <Row
+        {...(interaction.sortableDisabled ? {} : attributes)}
+        {...(interaction.sortableDisabled ? {} : listeners)}
+        active={isSelected ? 'muted' : undefined}
+        cursor={isDragging ? 'grabbing' : 'default'}
+        display="flex"
+        gap="1.5"
+        p="1.5"
+        onClick={handleSelect}
+        onContextMenu={handleContextMenu}
+      >
+        <HStack gap="1.5" w="full">
+          <LayerThumbnail engine={engine} layer={layer} />
+          <Stack flex="1" gap="0.5" minW="0">
+            {isEditing ? (
+              <Input
+                autoFocus
+                aria-label={t('widgets.layers.actions.rename')}
+                disabled={!interaction.canRename}
+                size="2xs"
+                value={draftName}
+                onBlur={commitName}
+                onChange={handleNameChange}
+                onKeyDown={handleNameKeyDown}
+                onPointerDown={stopPropagation}
+              />
+            ) : (
+              <Text
+                aria-disabled={!interaction.canRename}
+                fontSize="2xs"
+                fontWeight="700"
+                truncate
+                onDoubleClick={interaction.canRename ? startEditing : undefined}
+              >
+                {layer.name}
+              </Text>
+            )}
+            <Badge alignSelf="flex-start" colorPalette="gray" size="xs" variant="subtle">
+              {t(layerBadgeKey(layer))}
+            </Badge>
+          </Stack>
+          <Box flexShrink="0" onClick={stopPropagation} onPointerDown={stopPropagation}>
+            <ToggleDot
+              checked={layer.isEnabled}
+              cursor={interaction.canToggleVisibility ? 'pointer' : 'not-allowed'}
+              disabled={!interaction.canToggleVisibility}
+              label={t('widgets.layers.actions.toggleVisibility')}
+              onCheckedChange={handleToggleVisible}
+            />
+          </Box>
+          <IconButton
+            aria-label={t('widgets.layers.actions.toggleLock')}
+            color={layer.isLocked ? 'fg' : 'fg.subtle'}
+            disabled={!interaction.canToggleLock}
+            size="2xs"
+            variant="ghost"
+            onClick={handleToggleLock}
+            onPointerDown={stopPropagation}
+          >
+            {layer.isLocked ? <LockIcon /> : <LockOpenIcon />}
+          </IconButton>
+          <Box flexShrink="0" onClick={stopPropagation} onPointerDown={stopPropagation}>
+            <LayerPropertiesPopover dispatch={dispatch} engine={engine} layer={layer} />
+          </Box>
+          <Box flexShrink="0" onPointerDown={stopPropagation}>
+            <LayerContextMenu dispatch={dispatch} engine={engine} index={index} layer={layer} layers={layers} />
+          </Box>
+        </HStack>
+      </Row>
+      <CanvasLayerContextMenu
+        dispatch={dispatch}
+        engine={engine}
+        layers={layers}
+        target={contextMenuTarget}
+        onClose={closeContextMenu}
+      />
+    </Box>
+  );
+};
+
+const stopPropagation = (event: { stopPropagation: () => void }): void => event.stopPropagation();
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerPropertiesPopover.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerPropertiesPopover.tsx
new file mode 100644
index 00000000000..7ae0ccd5f3d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerPropertiesPopover.tsx
@@ -0,0 +1,242 @@
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasLayerContract } from '@workbench/types';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { Dispatch } from 'react';
+
+import { Box, Popover, Portal, Stack, Switch, Text } from '@chakra-ui/react';
+import { IconButton } from '@workbench/components/ui';
+import { useCanvasDocumentEditingLocked } from '@workbench/widgets/canvas/engineStoreHooks';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { SlidersHorizontalIcon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { LayerPropertiesRequest } from './layerPropertiesRequestStore';
+
+import { AdjustmentsPopover } from './AdjustmentsPopover';
+import { ControlLayerSettings } from './ControlLayerSettings';
+import { InpaintMaskSettings } from './InpaintMaskSettings';
+import { applyStructural } from './layerOps';
+import {
+  closeLayerPropertiesForOperation,
+  getLayerPropertiesOwnershipKey,
+  isLayerPropertiesOpen,
+} from './layerPropertiesOperation';
+import { clearLayerPropertiesRequest, useLayerPropertiesRequest } from './layerPropertiesRequestStore';
+import { RasterLayerFilterSection } from './RasterLayerFilterSection';
+import { RegionalGuidanceSettings } from './RegionalGuidanceSettings';
+
+export type LayerPropertiesEngine = Pick<
+  CanvasEngineHandle,
+  'document' | 'exports' | 'layers' | 'projectId' | 'stores'
+>;
+
+const POPOVER_POSITIONING = { placement: 'left-start' } as const;
+
+const stopPropagation = (event: { stopPropagation: () => void }): void => event.stopPropagation();
+
+interface LayerPropertiesPopoverProps {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  engine: LayerPropertiesEngine | null;
+  layer: CanvasLayerContract;
+}
+
+/**
+ * The per-layer "properties/configure" affordance (round-3 restructure): a sliders
+ * IconButton on each row that opens a popover holding that layer's type-specific
+ * settings — control adapter/filter, regional prompts/ref-images, inpaint mask
+ * fill/noise, or raster adjustments. Previously these were
+ * stacked in the panel header for the *selected* layer; moving them into a per-row
+ * popover keeps the header slim and each layer's config next to the layer.
+ *
+ * Content is mounted only while open (`lazyMount` + `unmountOnExit`). Starting a
+ * canvas operation explicitly clears both trigger and request ownership before
+ * the operation panel takes over. Type-specific settings are keyed by layer so
+ * switching targets always mounts a fresh settings instance.
+ */
+export const LayerPropertiesPopover = (props: LayerPropertiesPopoverProps) => {
+  const editingLocked = useCanvasDocumentEditingLocked(props.engine);
+  const request = useLayerPropertiesRequest(props.layer.id);
+  return (
+    <LayerPropertiesPopoverOwnership
+      key={`${props.layer.id}:${getLayerPropertiesOwnershipKey(editingLocked)}`}
+      {...props}
+      editingLocked={editingLocked}
+      request={request}
+    />
+  );
+};
+
+const LayerPropertiesPopoverOwnership = ({
+  dispatch,
+  editingLocked,
+  engine,
+  layer,
+  request,
+}: LayerPropertiesPopoverProps & { editingLocked: boolean; request: LayerPropertiesRequest | null }) => {
+  const { t } = useTranslation();
+  const [triggerOpen, setTriggerOpen] = useState(false);
+  const documentRevision = useActiveProjectSelector((project) => project.canvas.documentRevision);
+  const isOpen = !editingLocked && isLayerPropertiesOpen({ requestToken: request?.token ?? null, triggerOpen });
+  const consumeLockedRequestRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      if (node && editingLocked && request) {
+        clearLayerPropertiesRequest(request.token);
+      }
+    },
+    [editingLocked, request]
+  );
+
+  const handleOpenChange = useCallback(
+    (details: { open: boolean }) => {
+      setTriggerOpen(details.open);
+      if (!details.open && request) {
+        clearLayerPropertiesRequest(request.token);
+      }
+    },
+    [request]
+  );
+  const handleOperationStarted = useCallback(() => {
+    const closed = closeLayerPropertiesForOperation({ requestToken: request?.token ?? null, triggerOpen });
+    setTriggerOpen(closed.triggerOpen);
+    if (closed.requestTokenToClear !== null) {
+      clearLayerPropertiesRequest(closed.requestTokenToClear);
+    }
+  }, [request?.token, triggerOpen]);
+
+  return (
+    <>
+      {editingLocked && request ? <Box ref={consumeLockedRequestRef} display="none" /> : null}
+      <Popover.Root
+        lazyMount
+        open={isOpen}
+        positioning={POPOVER_POSITIONING}
+        unmountOnExit
+        onOpenChange={handleOpenChange}
+      >
+        <Popover.Trigger asChild>
+          <IconButton
+            aria-label={t('widgets.layers.properties')}
+            color="fg.subtle"
+            disabled={editingLocked}
+            size="2xs"
+            variant="ghost"
+            onClick={stopPropagation}
+            onPointerDown={stopPropagation}
+          >
+            <SlidersHorizontalIcon />
+          </IconButton>
+        </Popover.Trigger>
+        <Portal>
+          <Popover.Positioner>
+            <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="20rem">
+              <Popover.Body p="2.5">
+                <Stack gap="2" inert={editingLocked}>
+                  <LayerTypeSettings
+                    dispatch={dispatch}
+                    documentRevision={documentRevision}
+                    engine={engine}
+                    layer={layer}
+                    onOperationStarted={handleOperationStarted}
+                  />
+                </Stack>
+              </Popover.Body>
+            </Popover.Content>
+          </Popover.Positioner>
+        </Portal>
+      </Popover.Root>
+    </>
+  );
+};
+
+/** Dispatches to the correct per-type settings block for the layer. */
+const LayerTypeSettings = ({
+  dispatch,
+  documentRevision,
+  engine,
+  layer,
+  onOperationStarted,
+}: {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  documentRevision: number;
+  engine: LayerPropertiesEngine | null;
+  layer: CanvasLayerContract;
+  onOperationStarted(): void;
+}) => {
+  switch (layer.type) {
+    case 'inpaint_mask':
+      return <InpaintMaskSettings key={layer.id} engine={engine} layer={layer} />;
+    case 'regional_guidance':
+      return <RegionalGuidanceSettings key={layer.id} engine={engine} layer={layer} />;
+    case 'control':
+      return (
+        <ControlLayerSettings key={layer.id} engine={engine} layer={layer} onOperationStarted={onOperationStarted} />
+      );
+    case 'raster':
+      return (
+        <RasterLayerSettings
+          key={`${engine?.projectId ?? 'none'}-${layer.id}-${documentRevision}`}
+          dispatch={dispatch}
+          engine={engine}
+          layer={layer}
+          onOperationStarted={onOperationStarted}
+        />
+      );
+  }
+};
+
+/** Raster-layer properties: transparency lock + non-destructive adjustments. */
+const RasterLayerSettings = ({
+  dispatch,
+  engine,
+  layer,
+  onOperationStarted,
+}: {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  engine: LayerPropertiesEngine | null;
+  layer: Extract<CanvasLayerContract, { type: 'raster' }>;
+  onOperationStarted(): void;
+}) => {
+  const { t } = useTranslation();
+  const isLocked = layer.isTransparencyLocked === true;
+
+  const handleTransparencyLock = useCallback(
+    (details: { checked: boolean }) => {
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.adjustments.transparencyLock'),
+        {
+          config: { isTransparencyLocked: details.checked, layerType: 'raster' },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        },
+        {
+          config: { isTransparencyLocked: isLocked, layerType: 'raster' },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        }
+      );
+    },
+    [dispatch, engine, isLocked, layer.id, t]
+  );
+
+  return (
+    <Stack gap="2">
+      <Switch.Root checked={isLocked} size="sm" onCheckedChange={handleTransparencyLock}>
+        <Switch.HiddenInput />
+        <Switch.Control>
+          <Switch.Thumb />
+        </Switch.Control>
+        <Switch.Label>
+          <Text fontSize="xs">{t('widgets.layers.adjustments.transparencyLock')}</Text>
+        </Switch.Label>
+      </Switch.Root>
+      <Text color="fg.subtle" fontSize="2xs" fontWeight="700" textTransform="uppercase">
+        {t('widgets.layers.adjustments.title')}
+      </Text>
+      <AdjustmentsPopover engine={engine} layer={layer} />
+      <RasterLayerFilterSection engine={engine} layer={layer} onOperationStarted={onOperationStarted} />
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerThumbnail.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerThumbnail.tsx
new file mode 100644
index 00000000000..1a149e144a9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayerThumbnail.tsx
@@ -0,0 +1,148 @@
+/* oxlint-disable react-perf/jsx-no-new-function-as-prop -- the canvas ref callback is memoized on [engine, layerId, version]; it is intentionally re-created when the layer's thumbnail version bumps so the cache is re-blitted. */
+import type { CanvasCoreStoreCapability, CanvasPreviewCapability } from '@workbench/canvas-engine/api';
+import type { LayerThumbnailFallbackStage } from '@workbench/canvas-engine/render/thumbnail';
+import type { CanvasLayerContract } from '@workbench/types';
+import type { CSSProperties } from 'react';
+
+import { Box, Icon, IconButton } from '@chakra-ui/react';
+import {
+  getLayerThumbnailFallbackRenderState,
+  nextLayerThumbnailFallbackStage,
+  resolveLayerThumbnailImageRef,
+} from '@workbench/canvas-engine/render/thumbnail';
+import { getImageFullUrl, getImageThumbnailUrl } from '@workbench/gallery/api';
+import { useLayerThumbnailStatus, useLayerThumbnailVersion } from '@workbench/widgets/canvas/engineStoreHooks';
+import { ImageOffIcon, RefreshCwIcon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+
+/** Backing-store cap for the thumbnail canvas (kept ≤128px per the engine contract). */
+const THUMBNAIL_MAX_PX = 96;
+
+const CANVAS_STYLE: CSSProperties = { height: '100%', objectFit: 'contain', width: '100%' };
+const IMG_STYLE: CSSProperties = { height: '100%', objectFit: 'cover', width: '100%' };
+
+type LayerThumbnailEngine = CanvasCoreStoreCapability & {
+  readonly previews: CanvasPreviewCapability;
+  readonly projectId: string;
+};
+
+/**
+ * A layer's thumbnail: the engine's live cache pixels drawn onto a `<canvas>`,
+ * redrawn whenever the layer's `thumbnailVersion` bumps. Falls back to the
+ * persisted image thumbnail (for image-source layers) or a placeholder icon
+ * when there is no engine / no cache yet.
+ */
+const LayerThumbnailContent = ({
+  engine,
+  layer,
+}: {
+  engine: LayerThumbnailEngine | null;
+  layer: CanvasLayerContract;
+}) => {
+  // Re-renders (and thus re-runs the ref callback below) when the cache repaints.
+  const version = useLayerThumbnailVersion(engine, layer.id);
+  const status = useLayerThumbnailStatus(engine, layer.id);
+  const [drawn, setDrawn] = useState(false);
+  const [fallbackStage, setFallbackStage] = useState<LayerThumbnailFallbackStage>('thumbnail');
+
+  const bindCanvas = useCallback(
+    (canvas: HTMLCanvasElement | null) => {
+      // `version` is read purely so a repaint (a new version) re-creates this
+      // callback, which React re-runs to re-blit the layer cache onto the canvas.
+      void version;
+      if (!canvas || !engine) {
+        setDrawn(false);
+        return;
+      }
+      if (status === 'idle') {
+        void engine.previews.requestLayerThumbnail(layer.id);
+      }
+      const didDraw = engine.previews.drawLayerThumbnail(layer.id, canvas, THUMBNAIL_MAX_PX);
+      setDrawn(didDraw);
+      if (didDraw) {
+        setFallbackStage('thumbnail');
+      }
+    },
+    // `version` is a deliberate identity trigger: a repaint bumps it, giving the
+    // callback a new identity so React re-runs it and re-blits the cache.
+    // react-compiler can't model that implicit use, so it is suppressed here.
+    // eslint-disable-next-line react/react-compiler
+    [engine, layer.id, status, version]
+  );
+
+  const retry = useCallback(() => {
+    setFallbackStage('thumbnail');
+    if (engine) {
+      void engine.previews.requestLayerThumbnail(layer.id);
+    }
+  }, [engine, layer.id]);
+
+  const fallbackImage = resolveLayerThumbnailImageRef(layer);
+  const onFallbackError = useCallback(() => setFallbackStage(nextLayerThumbnailFallbackStage), []);
+  const fallbackUrl =
+    fallbackImage && fallbackStage !== 'failed'
+      ? fallbackStage === 'thumbnail'
+        ? getImageThumbnailUrl(fallbackImage.imageName)
+        : getImageFullUrl(fallbackImage.imageName)
+      : null;
+  const { showFallback, showRetry } = getLayerThumbnailFallbackRenderState(drawn, fallbackStage, status === 'error');
+
+  return (
+    <Box
+      bg="bg.emphasized"
+      borderColor="border.subtle"
+      borderWidth="1px"
+      flexShrink={0}
+      h="9"
+      overflow="hidden"
+      position="relative"
+      rounded="sm"
+      w="9"
+    >
+      <canvas ref={bindCanvas} style={drawn ? CANVAS_STYLE : { display: 'none' }} />
+      {showFallback &&
+        (fallbackUrl ? (
+          <img alt={layer.name} onError={onFallbackError} src={fallbackUrl} style={IMG_STYLE} />
+        ) : (
+          <Box alignItems="center" color="fg.subtle" display="flex" h="full" justifyContent="center" w="full">
+            <Icon as={ImageOffIcon} boxSize="3.5" />
+          </Box>
+        ))}
+      {showRetry ? (
+        <IconButton
+          aria-label={`Retry thumbnail for ${layer.name}`}
+          inset="0"
+          minH="0"
+          minW="0"
+          onClick={retry}
+          position="absolute"
+          size="xs"
+          variant="surface"
+        >
+          <RefreshCwIcon />
+        </IconButton>
+      ) : null}
+    </Box>
+  );
+};
+
+/**
+ * The keyed boundary resets local draw/fallback state when a row is reused for a
+ * different project, layer, or persisted image. No effect-based reset is needed.
+ */
+export const LayerThumbnail = ({
+  engine,
+  layer,
+}: {
+  engine: LayerThumbnailEngine | null;
+  layer: CanvasLayerContract;
+}) => {
+  const imageName = resolveLayerThumbnailImageRef(layer)?.imageName ?? 'none';
+  return (
+    <LayerThumbnailContent
+      key={`${engine?.projectId ?? 'none'}:${layer.id}:${imageName}`}
+      engine={engine}
+      layer={layer}
+    />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersHeaderActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersHeaderActions.tsx
new file mode 100644
index 00000000000..f287d4d10eb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersHeaderActions.tsx
@@ -0,0 +1,82 @@
+import type { LucideIcon } from 'lucide-react';
+
+import { HStack, Icon, Menu, Portal, Text } from '@chakra-ui/react';
+import { IconButton, MenuContent } from '@workbench/components/ui';
+import {
+  BrushIcon,
+  ImagePlusIcon,
+  MapPinIcon,
+  PlusIcon,
+  SlidersHorizontalIcon,
+  SquareDashedBottomIcon,
+} from 'lucide-react';
+import { Fragment, useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { AddLayerItemId } from './addLayerMenu';
+
+import { ADD_LAYER_MENU } from './addLayerMenu';
+import { useAddLayer } from './useAddLayer';
+
+const MENU_POSITIONING = { placement: 'bottom-end' } as const;
+
+/** Icon per add-layer item (kept in the view; the menu structure itself is pure data). */
+const ADD_LAYER_ICONS: Record<AddLayerItemId, LucideIcon> = {
+  control: SlidersHorizontalIcon,
+  inpaint_mask: SquareDashedBottomIcon,
+  raster: BrushIcon,
+  regional_guidance: MapPinIcon,
+  regional_reference_image: ImagePlusIcon,
+};
+
+/**
+ * Layers-panel header: the add-layer menu, split into legacy's two labelled groups
+ * — "Regional" (inpaint mask / regional guidance / regional guidance + reference
+ * image) and "Layers" (control / raster). The per-item creation is delegated to the
+ * shared `useAddLayer` hook so this menu and each group header's "New" button agree.
+ */
+export const LayersHeaderActions = () => {
+  const { t } = useTranslation();
+  const addLayer = useAddLayer();
+
+  const handleSelect = useCallback((id: AddLayerItemId) => () => addLayer(id), [addLayer]);
+
+  return (
+    <Menu.Root positioning={MENU_POSITIONING}>
+      <Menu.Trigger asChild>
+        <IconButton aria-label={t('widgets.layers.addLayer')} color="fg.muted" size="2xs" variant="ghost">
+          <PlusIcon />
+        </IconButton>
+      </Menu.Trigger>
+      <Portal>
+        <Menu.Positioner>
+          <MenuContent minW="12rem">
+            {ADD_LAYER_MENU.map((group, groupIndex) => (
+              <Fragment key={group.titleKey}>
+                {groupIndex > 0 ? <Menu.Separator borderColor="border.subtle" /> : null}
+                <Menu.ItemGroup>
+                  <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                    {t(group.titleKey)}
+                  </Menu.ItemGroupLabel>
+                  {group.items.map((item) => {
+                    const ItemIcon = ADD_LAYER_ICONS[item.id];
+                    return (
+                      <Menu.Item key={item.id} value={item.id} onSelect={handleSelect(item.id)}>
+                        <HStack gap="2" minW="0" w="full">
+                          <Icon as={ItemIcon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+                          <Text flex="1" fontSize="xs">
+                            {t(item.labelKey)}
+                          </Text>
+                        </HStack>
+                      </Menu.Item>
+                    );
+                  })}
+                </Menu.ItemGroup>
+              </Fragment>
+            ))}
+          </MenuContent>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersPanelHeader.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersPanelHeader.test.ts
new file mode 100644
index 00000000000..1dcecdff19f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersPanelHeader.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { createEmptyPaintLayer } from './layerOps';
+import { isLayerEditingDisabled, isSameSelection } from './LayersPanelHeader';
+
+describe('LayersPanelHeader selection equality', () => {
+  it('invalidates the selected-layer view when blend mode changes', () => {
+    const normal = createEmptyPaintLayer('Layer', 'layer');
+    const multiply = { ...normal, blendMode: 'multiply' as const };
+
+    expect(isSameSelection(normal, multiply)).toBe(false);
+  });
+});
+
+describe('LayersPanelHeader editing state', () => {
+  it('disables layer controls without a selection or while engine editing is locked', () => {
+    const layer = createEmptyPaintLayer('Layer', 'layer');
+    expect(isLayerEditingDisabled(null, false)).toBe(true);
+    expect(isLayerEditingDisabled(layer, true)).toBe(true);
+    expect(isLayerEditingDisabled(layer, false)).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersPanelHeader.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersPanelHeader.tsx
new file mode 100644
index 00000000000..5b45cd48186
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersPanelHeader.tsx
@@ -0,0 +1,444 @@
+import type {
+  NumberInput as ChakraNumberInput,
+  SelectValueChangeDetails,
+  SliderValueChangeDetails,
+} from '@chakra-ui/react';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasBlendMode, CanvasLayerContract, CanvasMaskFillContract } from '@workbench/types';
+import type { CanvasEngineHandle } from '@workbench/widgets/canvas/useCanvasEngine';
+import type { Dispatch } from 'react';
+
+import { Box, createListCollection, Flex, HStack, NumberInput, Stack } from '@chakra-ui/react';
+import { ColorPicker, Field, Select, Slider } from '@workbench/components/ui';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { useCanvasDocumentEditingLocked } from '@workbench/widgets/canvas/engineStoreHooks';
+import {
+  CANVAS_DENOISING_STRENGTH_KEY,
+  clampCanvasDenoisingStrength,
+  MAX_CANVAS_DENOISING_STRENGTH,
+  MIN_CANVAS_DENOISING_STRENGTH,
+  readCanvasDenoisingStrength,
+} from '@workbench/widgets/canvas/invoke/canvasStrength';
+import { useCanvasEngine } from '@workbench/widgets/canvas/useCanvasEngine';
+import { useRegisterGenerateDraftFlusher } from '@workbench/widgets/generate/generateDraftRegistry';
+import { useDebouncedDraftValue } from '@workbench/widgets/generate/useDebouncedDraftValue';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useCallback, useMemo, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { DenoisingStrengthWave } from './DenoisingStrengthWave';
+import { applyStructural, applyStructuralPreview, CANVAS_BLEND_MODES } from './layerOps';
+
+type LayersPanelHeaderEngine = Pick<CanvasEngineHandle, 'layers' | 'stores'>;
+
+const STRENGTH_DEBOUNCE_MS = 250;
+const SELECT_POSITIONING = { placement: 'bottom-start', sameWidth: true } as const;
+
+const formatStrengthPercent = (value: number): string => `${Math.round(value * 100)}%`;
+const clamp01 = (value: number): number => Math.min(1, Math.max(0, value));
+
+/** A mask layer whose fill colour the header swatch edits (inpaint mask / region). */
+type MaskLayer = Extract<CanvasLayerContract, { type: 'inpaint_mask' | 'regional_guidance' }>;
+
+const isMaskLayer = (layer: CanvasLayerContract | null): layer is MaskLayer =>
+  layer !== null && (layer.type === 'inpaint_mask' || layer.type === 'regional_guidance');
+
+const selectSelectedLayer = (project: {
+  canvas: { document: { layers: readonly CanvasLayerContract[]; selectedLayerId: string | null } };
+}): CanvasLayerContract | null => {
+  const { layers, selectedLayerId } = project.canvas.document;
+  return layers.find((layer) => layer.id === selectedLayerId) ?? null;
+};
+
+export const isSameSelection = (left: CanvasLayerContract | null, right: CanvasLayerContract | null): boolean => {
+  if (left?.id !== right?.id || left?.opacity !== right?.opacity || left?.blendMode !== right?.blendMode) {
+    return false;
+  }
+  const leftFill = isMaskLayer(left) ? left.mask.fill.color : null;
+  const rightFill = isMaskLayer(right) ? right.mask.fill.color : null;
+  return leftFill === rightFill;
+};
+
+export const isLayerEditingDisabled = (layer: CanvasLayerContract | null, editingLocked: boolean): boolean =>
+  !layer || editingLocked;
+
+/**
+ * The slimmed Photoshop-style region above the layer groups (round 3): exactly two
+ * rows — the global canvas denoising-strength slider + a per-selection Opacity row
+ * (percent stepper + a mask-fill colour swatch for mask layers). Blend mode and the
+ * per-type settings that used to stack here now live in each row's properties
+ * popover, matching the legacy layout.
+ */
+export const LayersPanelHeader = () => {
+  const engine = useCanvasEngine();
+  const dispatch = useCanvasProjectMutationDispatch();
+  const layer = useActiveProjectSelector(selectSelectedLayer, isSameSelection);
+  const editingLocked = useCanvasDocumentEditingLocked(engine);
+
+  return (
+    <Stack gap="0">
+      <Box borderBottomWidth={1} px="1.5" py="1">
+        <DenoisingStrengthControl />
+      </Box>
+      <Box borderBottomWidth={1} px="1.5" py="1">
+        <Flex align="center" gap="2">
+          <BlendModeControl dispatch={dispatch} editingLocked={editingLocked} engine={engine} layer={layer} />
+          <OpacityRow dispatch={dispatch} editingLocked={editingLocked} engine={engine} layer={layer} />
+        </Flex>
+      </Box>
+    </Stack>
+  );
+};
+
+interface BlendModeOption {
+  label: string;
+  value: CanvasBlendMode;
+}
+
+const BlendModeControl = ({
+  dispatch,
+  editingLocked,
+  engine,
+  layer,
+}: {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  editingLocked: boolean;
+  engine: LayersPanelHeaderEngine | null;
+  layer: CanvasLayerContract | null;
+}) => {
+  const { t } = useTranslation();
+  const disabled = isLayerEditingDisabled(layer, editingLocked);
+  const blendMode = layer?.blendMode ?? 'normal';
+  const blendCollection = useMemo(
+    () =>
+      createListCollection<BlendModeOption>({
+        items: CANVAS_BLEND_MODES.map((mode) => ({ label: t(`widgets.layers.blendModes.${mode}`), value: mode })),
+      }),
+    [t]
+  );
+  const blendValue = useMemo(() => [blendMode], [blendMode]);
+
+  const handleBlendChange = useCallback(
+    ({ value }: SelectValueChangeDetails<BlendModeOption>) => {
+      const mode = value[0] as CanvasBlendMode | undefined;
+      if (!layer || !mode || mode === layer.blendMode) {
+        return;
+      }
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.actions.blendMode'),
+        { id: layer.id, patch: { blendMode: mode }, type: 'updateCanvasLayer' },
+        { id: layer.id, patch: { blendMode: layer.blendMode }, type: 'updateCanvasLayer' }
+      );
+    },
+    [dispatch, engine, layer, t]
+  );
+
+  return (
+    <Field disabled={disabled} flex="1.5" label={t('widgets.layers.actions.blendMode')} orientation="horizontal">
+      <Select
+        aria-label={t('widgets.layers.actions.blendMode')}
+        collection={blendCollection}
+        disabled={disabled}
+        minW="7rem"
+        positioning={SELECT_POSITIONING}
+        size="xs"
+        value={blendValue}
+        valueText={t(`widgets.layers.blendModes.${blendMode}`)}
+        w="full"
+        onValueChange={handleBlendChange}
+      />
+    </Field>
+  );
+};
+
+const OpacityRow = ({
+  dispatch,
+  editingLocked,
+  engine,
+  layer,
+}: {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  editingLocked: boolean;
+  engine: LayersPanelHeaderEngine | null;
+  layer: CanvasLayerContract | null;
+}) => {
+  const { t } = useTranslation();
+  // The uncommitted opacity edit: captured once per gesture. `before` is the
+  // pre-gesture value (the undo target); `latest` tracks the live value because
+  // React may not have re-rendered between the live dispatch and the commit
+  // trigger (both can fire inside one browser event), so `layer.opacity` from the
+  // render closure can be stale at commit time.
+  const pendingRef = useRef<{ id: string; before: number; latest: number } | null>(null);
+  const disabled = isLayerEditingDisabled(layer, editingLocked);
+  const opacityPercent = useMemo(() => String(Math.round((layer?.opacity ?? 1) * 100)), [layer?.opacity]);
+
+  // Records ONE history entry spanning the pending gesture (a spinner press,
+  // an arrow-key press, or a typed value committed via Enter/blur).
+  const commitPending = useCallback(() => {
+    const pending = pendingRef.current;
+    pendingRef.current = null;
+    if (!pending || pending.before === pending.latest) {
+      return;
+    }
+    applyStructural(
+      engine,
+      dispatch,
+      t('widgets.layers.actions.opacity'),
+      { id: pending.id, patch: { opacity: pending.latest }, type: 'updateCanvasLayer' },
+      { id: pending.id, patch: { opacity: pending.before }, type: 'updateCanvasLayer' }
+    );
+  }, [dispatch, engine, t]);
+
+  const handleOpacityChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (!layer || !Number.isFinite(valueAsNumber)) {
+        return;
+      }
+      // If a pending edit belongs to a previously selected layer, flush it first
+      // so its history entry is never attributed to the new layer.
+      if (pendingRef.current && pendingRef.current.id !== layer.id) {
+        commitPending();
+      }
+      const next = clamp01(valueAsNumber / 100);
+      if (
+        !applyStructuralPreview(engine, dispatch, {
+          id: layer.id,
+          patch: { opacity: next },
+          type: 'updateCanvasLayer',
+        })
+      ) {
+        return;
+      }
+      if (pendingRef.current === null) {
+        pendingRef.current = { before: layer.opacity, id: layer.id, latest: next };
+      } else {
+        pendingRef.current.latest = next;
+      }
+    },
+    [commitPending, dispatch, engine, layer]
+  );
+
+  // Commit per completed interaction: each spinner click (fires on release, so a
+  // press-and-hold repeat is one gesture), each arrow/paging key release, Enter,
+  // and blur (typed values).
+  const handleInputKeyUp = useCallback(
+    (event: { key: string }) => {
+      if (['ArrowDown', 'ArrowUp', 'End', 'Enter', 'Home', 'PageDown', 'PageUp'].includes(event.key)) {
+        commitPending();
+      }
+    },
+    [commitPending]
+  );
+
+  // Flush a still-pending edit if the row unmounts mid-gesture (e.g. the panel
+  // closes right after a spinner click) so the edit is never lost to history.
+  const flushOnUnmountRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      if (node) {
+        return () => commitPending();
+      }
+      return undefined;
+    },
+    [commitPending]
+  );
+
+  return (
+    <Field disabled={disabled} label={t('widgets.layers.actions.opacity')} orientation="horizontal">
+      <HStack ref={flushOnUnmountRef} gap="2">
+        <NumberInput.Root
+          disabled={disabled}
+          max={100}
+          min={0}
+          size="xs"
+          step={1}
+          value={opacityPercent}
+          w="20"
+          onValueChange={handleOpacityChange}
+        >
+          <NumberInput.Control onClick={commitPending} />
+          <NumberInput.Input
+            aria-label={t('widgets.layers.actions.opacity')}
+            onBlur={commitPending}
+            onKeyUp={handleInputKeyUp}
+          />
+        </NumberInput.Root>
+        {isMaskLayer(layer) ? (
+          <MaskFillSwatch disabled={editingLocked} dispatch={dispatch} engine={engine} layer={layer} />
+        ) : null}
+      </HStack>
+    </Field>
+  );
+};
+
+/**
+ * The selected mask layer's fill-colour swatch (legacy `ActionBarFill`): a colour
+ * swatch that opens the picker. Live edits during the drag are un-recorded; the
+ * final colour lands as one undoable history entry, mirroring the slider pattern.
+ */
+const MaskFillSwatch = ({
+  dispatch,
+  disabled,
+  engine,
+  layer,
+}: {
+  dispatch: Dispatch<CanvasProjectMutation>;
+  disabled: boolean;
+  engine: LayersPanelHeaderEngine | null;
+  layer: MaskLayer;
+}) => {
+  const { t } = useTranslation();
+  const fillBeforeRef = useRef<CanvasMaskFillContract | null>(null);
+  const fill = layer.mask.fill;
+
+  const patchFill = useCallback(
+    (next: CanvasMaskFillContract, before: CanvasMaskFillContract) => {
+      const config =
+        layer.type === 'inpaint_mask'
+          ? ({ layerType: 'inpaint_mask', mask: { fill: next } } as const)
+          : ({ layerType: 'regional_guidance', mask: { fill: next } } as const);
+      const inverseConfig =
+        layer.type === 'inpaint_mask'
+          ? ({ layerType: 'inpaint_mask', mask: { fill: before } } as const)
+          : ({ layerType: 'regional_guidance', mask: { fill: before } } as const);
+      applyStructural(
+        engine,
+        dispatch,
+        t('widgets.layers.maskFill.fill'),
+        { config, id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: inverseConfig, id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, engine, layer.id, layer.type, t]
+  );
+
+  const handleColorChange = useCallback(
+    (hex: string) => {
+      const next = { ...fill, color: hex };
+      const config =
+        layer.type === 'inpaint_mask'
+          ? ({ layerType: 'inpaint_mask', mask: { fill: next } } as const)
+          : ({ layerType: 'regional_guidance', mask: { fill: next } } as const);
+      if (!applyStructuralPreview(engine, dispatch, { config, id: layer.id, type: 'updateCanvasLayerConfig' })) {
+        return;
+      }
+      if (fillBeforeRef.current === null) {
+        fillBeforeRef.current = fill;
+      }
+    },
+    [dispatch, engine, fill, layer.id, layer.type]
+  );
+
+  const handleColorChangeEnd = useCallback(
+    (hex: string) => {
+      const before = fillBeforeRef.current ?? fill;
+      fillBeforeRef.current = null;
+      patchFill({ ...before, color: hex }, before);
+    },
+    [fill, patchFill]
+  );
+
+  return (
+    <Box aria-disabled={disabled} inert={disabled} opacity={disabled ? 0.5 : 1}>
+      <ColorPicker
+        aria-label={t('widgets.layers.maskFill.color')}
+        value={fill.color}
+        onValueChange={handleColorChange}
+        onValueChangeEnd={handleColorChangeEnd}
+      />
+    </Box>
+  );
+};
+
+const selectCanvasStrength = (project: Parameters<typeof getProjectWidgetValues>[0]): number =>
+  readCanvasDenoisingStrength(getProjectWidgetValues(project, 'canvas'));
+
+const DenoisingStrengthControl = () => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const projectId = useActiveProjectSelector((project) => project.id);
+  const strength = useActiveProjectSelector(selectCanvasStrength);
+
+  const commitStrength = useCallback(
+    (value: number) => {
+      dispatch({
+        type: 'patchWidgetValues',
+        values: { [CANVAS_DENOISING_STRENGTH_KEY]: clampCanvasDenoisingStrength(value) },
+        widgetId: 'canvas',
+      });
+    },
+    [dispatch]
+  );
+
+  const {
+    draftValue: draftStrength,
+    flushDraftValue,
+    setDraftValue: setStrength,
+  } = useDebouncedDraftValue({
+    delayMs: STRENGTH_DEBOUNCE_MS,
+    onCommit: commitStrength,
+    resetKey: projectId,
+    value: strength,
+  });
+
+  useRegisterGenerateDraftFlusher(flushDraftValue);
+
+  const strengthAriaLabel = useMemo(() => [t('widgets.layers.denoisingStrength')], [t]);
+  const strengthSliderValue = useMemo(() => [draftStrength], [draftStrength]);
+  const strengthNumberValue = useMemo(() => draftStrength.toFixed(2), [draftStrength]);
+  const strengthWave = useMemo(() => <DenoisingStrengthWave value={draftStrength} />, [draftStrength]);
+
+  const onSliderChange = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      if (next !== undefined && Number.isFinite(next)) {
+        setStrength(next);
+      }
+    },
+    [setStrength]
+  );
+
+  const onNumberChange = useCallback(
+    ({ valueAsNumber }: ChakraNumberInput.ValueChangeDetails) => {
+      if (Number.isFinite(valueAsNumber)) {
+        setStrength(valueAsNumber);
+      }
+    },
+    [setStrength]
+  );
+
+  return (
+    <Field label={t('widgets.layers.denoisingStrength')} labelEnd={strengthWave} orientation="horizontal">
+      <Flex direction="row" gap="2" align="center">
+        <Slider
+          aria-label={strengthAriaLabel}
+          flex="1"
+          formatValue={formatStrengthPercent}
+          max={MAX_CANVAS_DENOISING_STRENGTH}
+          min={MIN_CANVAS_DENOISING_STRENGTH}
+          minW="0"
+          size="sm"
+          step={0.01}
+          value={strengthSliderValue}
+          withThumbTooltip
+          onValueChange={onSliderChange}
+          ms="2"
+        />
+        <NumberInput.Root
+          max={MAX_CANVAS_DENOISING_STRENGTH}
+          min={MIN_CANVAS_DENOISING_STRENGTH}
+          size="xs"
+          step={0.05}
+          value={strengthNumberValue}
+          w="20"
+          onValueChange={onNumberChange}
+        >
+          <NumberInput.Control />
+          <NumberInput.Input aria-label={t('widgets.layers.denoisingStrength')} />
+        </NumberInput.Root>
+      </Flex>
+    </Field>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersWidgetView.tsx
new file mode 100644
index 00000000000..3b0d483b0cc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/LayersWidgetView.tsx
@@ -0,0 +1,88 @@
+import { Flex, Icon, Stack, Text } from '@chakra-ui/react';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { useCanvasEngine } from '@workbench/widgets/canvas/useCanvasEngine';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { LayersIcon } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { LayerGroupKey } from './layerGroups';
+
+import { groupLayers } from './layerGroups';
+import { LayerGroupSection } from './LayerGroupSection';
+import { isLayerPropertiesGroupRequested, useCurrentLayerPropertiesRequest } from './layerPropertiesRequestStore';
+import { LayersPanelHeader } from './LayersPanelHeader';
+
+/**
+ * The layers panel: a fixed Photoshop-style header region (selected layer's
+ * opacity + blend mode, global denoising strength) above the layer list, which
+ * is split into type groups (inpaint masks / regional guidance / control /
+ * raster — legacy display order). Each group is a within-group drag-to-reorder
+ * list mapped onto the single global z-ordered `layers` array.
+ */
+export const LayersWidgetView = () => {
+  const { t } = useTranslation();
+  const engine = useCanvasEngine();
+  const dispatch = useCanvasProjectMutationDispatch();
+  const propertiesRequest = useCurrentLayerPropertiesRequest();
+  const { layers, selectedLayerId } = useActiveProjectSelector(
+    (project) => ({
+      layers: project.canvas.document.layers,
+      selectedLayerId: project.canvas.document.selectedLayerId,
+    }),
+    (left, right) => left.layers === right.layers && left.selectedLayerId === right.selectedLayerId
+  );
+
+  const groups = useMemo(() => groupLayers(layers), [layers]);
+
+  // Collapse is transient panel UI state (not part of the canvas document / undo
+  // history): a set of collapsed group keys, defaulting to expanded.
+  const [collapsedGroups, setCollapsedGroups] = useState<Partial<Record<LayerGroupKey, boolean>>>({});
+  const handleToggleCollapse = useCallback((groupKey: LayerGroupKey) => {
+    setCollapsedGroups((prev) => ({ ...prev, [groupKey]: !prev[groupKey] }));
+  }, []);
+
+  return (
+    <Stack gap="3" h="full">
+      <LayersPanelHeader />
+      {groups.length === 0 ? (
+        <Flex
+          align="center"
+          borderColor="border.subtle"
+          borderStyle="dashed"
+          borderWidth="1px"
+          color="fg.subtle"
+          direction="column"
+          gap="2"
+          justify="center"
+          minH="8rem"
+          p="4"
+          rounded="md"
+        >
+          <Icon as={LayersIcon} boxSize="6" />
+          <Text fontSize="2xs" textAlign="center">
+            {t('widgets.layers.empty')}
+          </Text>
+        </Flex>
+      ) : (
+        <Stack gap="3">
+          {groups.map((group) => (
+            <LayerGroupSection
+              key={group.key}
+              dispatch={dispatch}
+              engine={engine}
+              groupKey={group.key}
+              groupLayers={group.layers}
+              isCollapsed={
+                collapsedGroups[group.key] === true && !isLayerPropertiesGroupRequested(propertiesRequest, group.layers)
+              }
+              layers={layers}
+              onToggleCollapse={handleToggleCollapse}
+              selectedLayerId={selectedLayerId}
+            />
+          ))}
+        </Stack>
+      )}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/RasterLayerFilterSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/RasterLayerFilterSection.tsx
new file mode 100644
index 00000000000..80d058a205b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/RasterLayerFilterSection.tsx
@@ -0,0 +1,21 @@
+import type { CanvasRasterLayerContractV2 } from '@workbench/types';
+import type { LayerFilterOperationEngine } from '@workbench/widgets/layers/LayerFilterOperationButton';
+
+import { getCanvasOperations } from '@workbench/canvas-operations/createCanvasEngine';
+
+import { LayerFilterOperationButton } from './LayerFilterOperationButton';
+
+interface RasterLayerFilterSectionProps {
+  engine: LayerFilterOperationEngine | null;
+  layer: CanvasRasterLayerContractV2;
+  onOperationStarted(): void;
+}
+
+export const RasterLayerFilterSection = ({ engine, layer, onOperationStarted }: RasterLayerFilterSectionProps) => (
+  <LayerFilterOperationButton
+    engine={engine}
+    layer={layer}
+    onOperationStarted={onOperationStarted}
+    operations={engine ? getCanvasOperations(engine) : null}
+  />
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/RegionalGuidanceSettings.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/RegionalGuidanceSettings.tsx
new file mode 100644
index 00000000000..07838a83d9d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/RegionalGuidanceSettings.tsx
@@ -0,0 +1,707 @@
+import type { SelectValueChangeDetails, SliderValueChangeDetails } from '@chakra-ui/react';
+import type { GenerateReferenceImage, GenerateReferenceImageAsset, IPAdapterMethod } from '@workbench/generation/types';
+import type { ModelConfig } from '@workbench/models/types';
+import type { CanvasMaskContract, CanvasMaskFillContract, CanvasRegionalGuidanceLayerContract } from '@workbench/types';
+import type { CanvasStructuralEngine } from '@workbench/widgets/layers/layerOps';
+import type { ChangeEvent, CSSProperties, FocusEvent, KeyboardEvent } from 'react';
+
+import { Box, createListCollection, HStack, IconButton, Input, Stack, Switch, Text } from '@chakra-ui/react';
+import { useDndMonitor, useDroppable } from '@dnd-kit/core';
+import { Button, ColorPicker, Field, Select, Slider } from '@workbench/components/ui';
+import { getGalleryImagesByNames, uploadGalleryImage } from '@workbench/gallery/api';
+import { useModelsSelector } from '@workbench/models/modelsStore';
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { isGalleryImageDragData } from '@workbench/widgets/gallery/galleryDnd';
+import { PROMPT_ATTENTION_TARGET_PROPS } from '@workbench/widgets/generate/promptFields/promptAttentionHotkeys';
+import { PromptTextarea } from '@workbench/widgets/generate/promptFields/PromptTextarea';
+import { FluxReduxControls } from '@workbench/widgets/generate/reference-images/ReferenceImageControls';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { ImageIcon, PlusIcon, XIcon } from 'lucide-react';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { applyStructural, applyStructuralPreview, createRegionalReferenceImage } from './layerOps';
+import { useSelectedModelBase } from './useSelectedModelBase';
+
+/** The regional-guidance fields patchable via `updateCanvasLayerConfig`. */
+interface RegionalConfigPatch {
+  mask?: Partial<CanvasMaskContract>;
+  positivePrompt?: string | null;
+  negativePrompt?: string | null;
+  autoNegative?: boolean;
+  referenceImages?: GenerateReferenceImage[];
+}
+
+/** The six mask fill styles, matching `CanvasMaskFillContract['style']` / legacy `zFillStyle`. */
+const MASK_FILL_STYLES: readonly CanvasMaskFillContract['style'][] = [
+  'solid',
+  'grid',
+  'crosshatch',
+  'diagonal',
+  'horizontal',
+  'vertical',
+];
+
+const IP_ADAPTER_METHODS: readonly IPAdapterMethod[] = [
+  'full',
+  'style',
+  'composition',
+  'style_strong',
+  'style_precise',
+];
+
+const SELECT_POSITIONING = { placement: 'bottom-end', sameWidth: false } as const;
+
+const COVER_IMG_STYLE: CSSProperties = { height: '100%', objectFit: 'cover', width: '100%' };
+
+const formatWeight = (value: number): string => value.toFixed(2);
+
+const REGIONAL_PROMPT_HEIGHT_PX = 72;
+
+/** DnD droppable id for a specific region's reference-image slot (gallery-image drop target). */
+const referenceImageDropId = (layerId: string, refId: string): string => `regional-ref-image:${layerId}:${refId}`;
+
+/**
+ * A fresh regional reference image for the currently selected model's base. Shared
+ * with the header add-layer menu via `layerOps.createRegionalReferenceImage`.
+ */
+const createReferenceImage = (base: string | null): GenerateReferenceImage => createRegionalReferenceImage(base);
+
+interface RegionalGuidanceSettingsProps {
+  engine: CanvasStructuralEngine | null;
+  layer: CanvasRegionalGuidanceLayerContract;
+}
+
+/**
+ * Per-layer settings for a selected regional-guidance region (plan §1.3): a
+ * positive + negative prompt, an Auto-Negative toggle, the mask fill colour/style
+ * + invert, and a per-region reference-images section (add/remove/enable + model
+ * + weight, mirroring the generate widget's IP-Adapter fields). Prompt/toggle/fill
+ * edits go through the canvas undo stack (`applyStructural` →
+ * `updateCanvasLayerConfig`); invert is an engine pixel op.
+ */
+export const RegionalGuidanceSettings = ({ engine, layer }: RegionalGuidanceSettingsProps) => {
+  const { t } = useTranslation();
+  const dispatch = useCanvasProjectMutationDispatch();
+  const workbenchDispatch = useWorkbenchDispatch();
+  const models = useModelsSelector((snapshot) => snapshot.models);
+  const base = useSelectedModelBase();
+  const showSyntaxHighlighting = useActiveProjectSelector((project) => project.settings.showPromptSyntaxHighlighting);
+  const fillBeforeRef = useRef<CanvasMaskFillContract | null>(null);
+  const [positivePrompt, setPositivePrompt] = useState(layer.positivePrompt ?? '');
+  const [negativePrompt, setNegativePrompt] = useState(layer.negativePrompt ?? '');
+
+  const fill = layer.mask.fill;
+  const isFlux = base === 'flux';
+
+  const commitConfig = useCallback(
+    (label: string, next: RegionalConfigPatch, before: RegionalConfigPatch) => {
+      applyStructural(
+        engine,
+        dispatch,
+        label,
+        { config: { layerType: 'regional_guidance', ...next }, id: layer.id, type: 'updateCanvasLayerConfig' },
+        { config: { layerType: 'regional_guidance', ...before }, id: layer.id, type: 'updateCanvasLayerConfig' }
+      );
+    },
+    [dispatch, engine, layer.id]
+  );
+
+  const handlePositiveBlur = useCallback(
+    (event: FocusEvent<HTMLTextAreaElement>) => {
+      const value = event.target.value;
+      const next = value.length > 0 ? value : null;
+      if (next !== layer.positivePrompt) {
+        commitConfig(
+          t('widgets.layers.regionalGuidance.positivePrompt'),
+          { positivePrompt: next },
+          {
+            positivePrompt: layer.positivePrompt,
+          }
+        );
+      }
+    },
+    [commitConfig, layer.positivePrompt, t]
+  );
+
+  const handlePositiveChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => setPositivePrompt(event.currentTarget.value),
+    []
+  );
+
+  const handleNegativeBlur = useCallback(
+    (event: FocusEvent<HTMLTextAreaElement>) => {
+      const value = event.target.value;
+      const next = value.length > 0 ? value : null;
+      if (next !== layer.negativePrompt) {
+        commitConfig(
+          t('widgets.layers.regionalGuidance.negativePrompt'),
+          { negativePrompt: next },
+          {
+            negativePrompt: layer.negativePrompt,
+          }
+        );
+      }
+    },
+    [commitConfig, layer.negativePrompt, t]
+  );
+
+  const handleNegativeChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => setNegativePrompt(event.currentTarget.value),
+    []
+  );
+
+  const stopKeyboardPropagation = useCallback((event: KeyboardEvent) => event.stopPropagation(), []);
+
+  const handleAutoNegative = useCallback(
+    (details: { checked: boolean }) => {
+      commitConfig(
+        t('widgets.layers.regionalGuidance.autoNegative'),
+        { autoNegative: details.checked },
+        { autoNegative: layer.autoNegative }
+      );
+    },
+    [commitConfig, layer.autoNegative, t]
+  );
+
+  const styleCollection = useMemo(
+    () =>
+      createListCollection({
+        items: MASK_FILL_STYLES.map((style) => ({
+          label: t(`widgets.layers.maskFill.styles.${style}`),
+          value: style,
+        })),
+      }),
+    [t]
+  );
+
+  const commitFill = useCallback(
+    (next: CanvasMaskFillContract, before: CanvasMaskFillContract) => {
+      commitConfig(t('widgets.layers.maskFill.fill'), { mask: { fill: next } }, { mask: { fill: before } });
+    },
+    [commitConfig, t]
+  );
+
+  const handleColorChange = useCallback(
+    (hex: string) => {
+      if (
+        !applyStructuralPreview(engine, dispatch, {
+          config: { layerType: 'regional_guidance', mask: { fill: { ...fill, color: hex } } },
+          id: layer.id,
+          type: 'updateCanvasLayerConfig',
+        })
+      ) {
+        return;
+      }
+      if (fillBeforeRef.current === null) {
+        fillBeforeRef.current = fill;
+      }
+    },
+    [dispatch, engine, fill, layer.id]
+  );
+
+  const handleColorChangeEnd = useCallback(
+    (hex: string) => {
+      const before = fillBeforeRef.current ?? fill;
+      fillBeforeRef.current = null;
+      commitFill({ ...before, color: hex }, before);
+    },
+    [commitFill, fill]
+  );
+
+  const handleStyleChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const style = value[0] as CanvasMaskFillContract['style'] | undefined;
+      if (style && style !== fill.style) {
+        commitFill({ ...fill, style }, fill);
+      }
+    },
+    [commitFill, fill]
+  );
+
+  const handleInvert = useCallback(() => {
+    engine?.layers.invertMask(layer.id);
+  }, [engine, layer.id]);
+
+  // Reference-image helpers ---------------------------------------------------
+  const referenceImages = layer.referenceImages;
+
+  const commitReferenceImages = useCallback(
+    (next: GenerateReferenceImage[]) => {
+      commitConfig(
+        t('widgets.layers.regionalGuidance.referenceImages'),
+        { referenceImages: next },
+        {
+          referenceImages: referenceImages,
+        }
+      );
+    },
+    [commitConfig, referenceImages, t]
+  );
+
+  const handleAddReferenceImage = useCallback(() => {
+    commitReferenceImages([...referenceImages, createReferenceImage(base)]);
+  }, [base, commitReferenceImages, referenceImages]);
+
+  // Assigning the image goes through the same undo path as the other ref edits
+  // (`commitReferenceImages` → `updateCanvasLayerConfig`), so a drop/upload/clear
+  // is a single, undoable document change.
+  const setReferenceImageAsset = useCallback(
+    (refId: string, image: GenerateReferenceImageAsset | null) => {
+      commitReferenceImages(
+        referenceImages.map((ref) => (ref.id === refId ? { ...ref, config: { ...ref.config, image } } : ref))
+      );
+    },
+    [commitReferenceImages, referenceImages]
+  );
+
+  const uploadReferenceImageAsset = useCallback(
+    async (refId: string, file: File) => {
+      try {
+        const uploaded = await uploadGalleryImage(file, 'none');
+        setReferenceImageAsset(refId, uploaded);
+        workbenchDispatch({ type: 'touchGalleryImagesRefresh' });
+      } catch (error) {
+        workbenchDispatch({
+          area: 'regional-guidance',
+          message: error instanceof Error ? error.message : String(error),
+          namespace: 'generation',
+          type: 'recordError',
+        });
+      }
+    },
+    [setReferenceImageAsset, workbenchDispatch]
+  );
+
+  // A single monitor routes gallery-image drops to the region's ref slot the drop
+  // landed on (each row registers a droppable keyed by layer + ref id).
+  useDndMonitor({
+    onDragEnd: (event) => {
+      const overId = event.over?.id;
+      const prefix = `regional-ref-image:${layer.id}:`;
+      if (typeof overId !== 'string' || !overId.startsWith(prefix)) {
+        return;
+      }
+      const data = event.active.data.current;
+      if (!isGalleryImageDragData(data) || data.images.length === 0) {
+        return;
+      }
+      const refId = overId.slice(prefix.length);
+      const [first] = data.images;
+      void getGalleryImagesByNames([first.imageName]).then((images) => {
+        if (images[0]) {
+          setReferenceImageAsset(refId, images[0]);
+        }
+      });
+    },
+  });
+
+  const ipAdapterModelCollection = useMemo(
+    () =>
+      createListCollection({
+        items: models
+          .filter((model) => model.type === 'ip_adapter' && (!base || model.base === base))
+          .map((model) => ({ label: model.name, value: model.key })),
+      }),
+    [base, models]
+  );
+
+  const fluxReduxModelCollection = useMemo(
+    () =>
+      createListCollection({
+        items: models
+          .filter((model) => model.type === 'flux_redux' && (!base || model.base === base))
+          .map((model) => ({ label: model.name, value: model.key })),
+      }),
+    [base, models]
+  );
+
+  const methodCollection = useMemo(
+    () =>
+      createListCollection({
+        items: IP_ADAPTER_METHODS.map((method) => ({
+          label: t(`widgets.layers.regionalGuidance.methods.${method}`),
+          value: method as string,
+        })),
+      }),
+    [t]
+  );
+
+  const styleValue = useMemo(() => [fill.style], [fill.style]);
+
+  return (
+    <Stack gap="2" onKeyDown={stopKeyboardPropagation}>
+      <Field label={t('widgets.layers.regionalGuidance.positivePrompt')}>
+        <PromptTextarea
+          {...PROMPT_ATTENTION_TARGET_PROPS}
+          aria-label={t('widgets.layers.regionalGuidance.positivePrompt')}
+          defaultHeightPx={REGIONAL_PROMPT_HEIGHT_PX}
+          maxHeightPx={180}
+          minHeightPx={REGIONAL_PROMPT_HEIGHT_PX}
+          placeholder={t('widgets.layers.regionalGuidance.positivePromptPlaceholder')}
+          resizeHandleAriaLabel={t('widgets.layers.regionalGuidance.positivePrompt')}
+          showSyntaxHighlighting={showSyntaxHighlighting}
+          size="sm"
+          value={positivePrompt}
+          onBlur={handlePositiveBlur}
+          onChange={handlePositiveChange}
+        />
+      </Field>
+      {!isFlux && (
+        <Field label={t('widgets.layers.regionalGuidance.negativePrompt')}>
+          <PromptTextarea
+            {...PROMPT_ATTENTION_TARGET_PROPS}
+            aria-label={t('widgets.layers.regionalGuidance.negativePrompt')}
+            defaultHeightPx={REGIONAL_PROMPT_HEIGHT_PX}
+            maxHeightPx={180}
+            minHeightPx={REGIONAL_PROMPT_HEIGHT_PX}
+            placeholder={t('widgets.layers.regionalGuidance.negativePromptPlaceholder')}
+            resizeHandleAriaLabel={t('widgets.layers.regionalGuidance.negativePrompt')}
+            showSyntaxHighlighting={showSyntaxHighlighting}
+            size="sm"
+            value={negativePrompt}
+            onBlur={handleNegativeBlur}
+            onChange={handleNegativeChange}
+          />
+        </Field>
+      )}
+      {!isFlux && (
+        <Switch.Root checked={layer.autoNegative} size="sm" onCheckedChange={handleAutoNegative}>
+          <Switch.HiddenInput />
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          <Switch.Label>
+            <Text fontSize="xs">{t('widgets.layers.regionalGuidance.autoNegative')}</Text>
+          </Switch.Label>
+        </Switch.Root>
+      )}
+
+      <HStack gap="2">
+        <Field flexShrink="0" label={t('widgets.layers.maskFill.color')}>
+          <ColorPicker
+            aria-label={t('widgets.layers.maskFill.color')}
+            value={fill.color}
+            onValueChange={handleColorChange}
+            onValueChangeEnd={handleColorChangeEnd}
+          />
+        </Field>
+        <Field flex="1" label={t('widgets.layers.maskFill.style')} minW="0">
+          <Select
+            aria-label={t('widgets.layers.maskFill.style')}
+            collection={styleCollection}
+            positioning={SELECT_POSITIONING}
+            size="xs"
+            value={styleValue}
+            valueText={t(`widgets.layers.maskFill.styles.${fill.style}`)}
+            onValueChange={handleStyleChange}
+          />
+        </Field>
+      </HStack>
+      <Button disabled={!engine} size="xs" variant="outline" onClick={handleInvert}>
+        {t('widgets.layers.maskFill.invert')}
+      </Button>
+
+      <Stack gap="2">
+        <HStack justify="space-between">
+          <Text fontSize="xs" fontWeight="medium">
+            {t('widgets.layers.regionalGuidance.referenceImages')}
+          </Text>
+          <IconButton
+            aria-label={t('widgets.layers.regionalGuidance.addReferenceImage')}
+            size="2xs"
+            variant="ghost"
+            onClick={handleAddReferenceImage}
+          >
+            <PlusIcon />
+          </IconButton>
+        </HStack>
+        {referenceImages.map((ref, index) => (
+          <ReferenceImageRow
+            dropId={referenceImageDropId(layer.id, ref.id)}
+            index={index}
+            ipAdapterModelCollection={ipAdapterModelCollection}
+            fluxReduxModelCollection={fluxReduxModelCollection}
+            key={ref.id}
+            methodCollection={methodCollection}
+            models={models}
+            referenceImage={ref}
+            referenceImages={referenceImages}
+            onCommit={commitReferenceImages}
+            onSetImage={setReferenceImageAsset}
+            onUpload={uploadReferenceImageAsset}
+          />
+        ))}
+      </Stack>
+    </Stack>
+  );
+};
+
+interface ReferenceImageRowProps {
+  dropId: string;
+  index: number;
+  referenceImage: GenerateReferenceImage;
+  referenceImages: readonly GenerateReferenceImage[];
+  ipAdapterModelCollection: ReturnType<typeof createListCollection<{ label: string; value: string }>>;
+  fluxReduxModelCollection: ReturnType<typeof createListCollection<{ label: string; value: string }>>;
+  methodCollection: ReturnType<typeof createListCollection<{ label: string; value: string }>>;
+  models: readonly ModelConfig[];
+  onCommit: (next: GenerateReferenceImage[]) => void;
+  onSetImage: (refId: string, image: GenerateReferenceImageAsset | null) => void;
+  onUpload: (refId: string, file: File) => void;
+}
+
+/**
+ * One regional reference image: enable/remove, an image slot (gallery drop or
+ * upload, mirroring the generate widget's mechanism), and the model + adapter
+ * fields for its config kind — IP-Adapter (model/method/weight) for non-FLUX
+ * regions, FLUX Redux (model/influence) for FLUX regions.
+ */
+const ReferenceImageRow = ({
+  dropId,
+  index,
+  ipAdapterModelCollection,
+  fluxReduxModelCollection,
+  methodCollection,
+  models,
+  referenceImage,
+  referenceImages,
+  onCommit,
+  onSetImage,
+  onUpload,
+}: ReferenceImageRowProps) => {
+  const { t } = useTranslation();
+  const { config } = referenceImage;
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const { isOver, setNodeRef } = useDroppable({ data: { kind: 'regional-reference-image' }, id: dropId });
+
+  const replaceRef = useCallback(
+    (next: GenerateReferenceImage) => {
+      onCommit(referenceImages.map((entry, i) => (i === index ? next : entry)));
+    },
+    [index, onCommit, referenceImages]
+  );
+
+  const handleRemove = useCallback(() => {
+    onCommit(referenceImages.filter((_, i) => i !== index));
+  }, [index, onCommit, referenceImages]);
+
+  const handleEnabled = useCallback(
+    (details: { checked: boolean }) => {
+      replaceRef({ ...referenceImage, isEnabled: details.checked });
+    },
+    [referenceImage, replaceRef]
+  );
+
+  const openUpload = useCallback(() => fileInputRef.current?.click(), []);
+
+  const handleFileChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      const file = event.currentTarget.files?.[0];
+      if (file) {
+        onUpload(referenceImage.id, file);
+      }
+      event.currentTarget.value = '';
+    },
+    [onUpload, referenceImage.id]
+  );
+
+  const handleClearImage = useCallback(() => onSetImage(referenceImage.id, null), [onSetImage, referenceImage.id]);
+
+  const handleModel = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      if (config.type !== 'ip_adapter' && config.type !== 'flux_redux') {
+        return;
+      }
+      const key = value[0];
+      const model = models.find((entry) => entry.key === key) ?? null;
+      const modelIdentity = model ? { base: model.base, key: model.key, name: model.name, type: model.type } : null;
+      replaceRef({ ...referenceImage, config: { ...config, model: modelIdentity } });
+    },
+    [config, models, referenceImage, replaceRef]
+  );
+
+  const handleMethod = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      if (config.type !== 'ip_adapter') {
+        return;
+      }
+      const method = value[0] as IPAdapterMethod | undefined;
+      if (method) {
+        replaceRef({ ...referenceImage, config: { ...config, method } });
+      }
+    },
+    [config, referenceImage, replaceRef]
+  );
+
+  // Local live value while dragging the weight slider — the thumb tracks the
+  // pointer without pushing a history entry / re-committing the ref per tick. The
+  // single commit lands on drag end. `null` ⇒ not dragging (show the stored value).
+  const [liveWeight, setLiveWeight] = useState<number | null>(null);
+
+  const handleWeight = useCallback(({ value }: SliderValueChangeDetails) => {
+    const next = value[0];
+    if (next === undefined || !Number.isFinite(next)) {
+      return;
+    }
+    setLiveWeight(next);
+  }, []);
+
+  const handleWeightEnd = useCallback(
+    ({ value }: SliderValueChangeDetails) => {
+      const next = value[0];
+      setLiveWeight(null);
+      if (config.type !== 'ip_adapter' || next === undefined || !Number.isFinite(next)) {
+        return;
+      }
+      replaceRef({ ...referenceImage, config: { ...config, weight: next } });
+    },
+    [config, referenceImage, replaceRef]
+  );
+
+  const handleFluxReduxConfig = useCallback(
+    (nextConfig: GenerateReferenceImage['config']) => {
+      replaceRef({ ...referenceImage, config: nextConfig });
+    },
+    [referenceImage, replaceRef]
+  );
+
+  const modelCollection = config.type === 'flux_redux' ? fluxReduxModelCollection : ipAdapterModelCollection;
+  const modelValue = useMemo(
+    () =>
+      config.type === 'ip_adapter' || config.type === 'flux_redux' ? (config.model ? [config.model.key] : []) : [],
+    [config]
+  );
+  const methodValue = useMemo(() => (config.type === 'ip_adapter' ? [config.method] : []), [config]);
+  const weightValue = useMemo(
+    () => (liveWeight !== null ? [liveWeight] : config.type === 'ip_adapter' ? [config.weight] : [1]),
+    [config, liveWeight]
+  );
+  const weightAria = useMemo(() => [t('widgets.layers.regionalGuidance.weight')], [t]);
+
+  const image = config.image;
+  const modelName =
+    'model' in config && config.model ? config.model.name : t('widgets.layers.regionalGuidance.selectModel');
+
+  return (
+    <Stack borderColor="border.subtle" borderWidth="1px" gap="2" p="2" rounded="md">
+      <HStack justify="space-between">
+        <Switch.Root checked={referenceImage.isEnabled} size="sm" onCheckedChange={handleEnabled}>
+          <Switch.HiddenInput />
+          <Switch.Control>
+            <Switch.Thumb />
+          </Switch.Control>
+          <Switch.Label>
+            <Text fontSize="xs">{`${t('widgets.layers.regionalGuidance.referenceImage')} ${index + 1}`}</Text>
+          </Switch.Label>
+        </Switch.Root>
+        <IconButton
+          aria-label={t('widgets.layers.regionalGuidance.removeReferenceImage')}
+          size="2xs"
+          variant="ghost"
+          onClick={handleRemove}
+        >
+          <XIcon />
+        </IconButton>
+      </HStack>
+
+      <HStack align="flex-start" gap="2">
+        <Box
+          bg={isOver ? 'accent.muted' : undefined}
+          borderColor={isOver ? 'accent.solid' : 'border.emphasized'}
+          borderStyle={image ? 'solid' : 'dashed'}
+          borderWidth="1px"
+          flexShrink="0"
+          h="16"
+          overflow="hidden"
+          position="relative"
+          ref={setNodeRef}
+          rounded="md"
+          w="16"
+        >
+          <Box
+            as="button"
+            alignItems="center"
+            aria-label={t('widgets.layers.regionalGuidance.setReferenceImage')}
+            bg="bg.muted"
+            color="fg.muted"
+            cursor="pointer"
+            display="flex"
+            h="full"
+            justifyContent="center"
+            w="full"
+            onClick={openUpload}
+          >
+            {image ? (
+              <img alt={image.imageName} draggable={false} src={image.thumbnailUrl} style={COVER_IMG_STYLE} />
+            ) : (
+              <ImageIcon size="20" />
+            )}
+          </Box>
+          {image ? (
+            <IconButton
+              aria-label={t('widgets.layers.regionalGuidance.clearReferenceImage')}
+              colorPalette="red"
+              position="absolute"
+              right="0.5"
+              size="2xs"
+              top="0.5"
+              variant="solid"
+              onClick={handleClearImage}
+            >
+              <XIcon />
+            </IconButton>
+          ) : null}
+        </Box>
+        <Text color="fg.muted" flex="1" fontSize="2xs" minW="0">
+          {t('widgets.layers.regionalGuidance.referenceImageHelp')}
+        </Text>
+        <Input ref={fileInputRef} accept="image/*" display="none" type="file" onChange={handleFileChange} />
+      </HStack>
+
+      <Field label={t('widgets.layers.regionalGuidance.model')}>
+        <Select
+          aria-label={t('widgets.layers.regionalGuidance.model')}
+          collection={modelCollection}
+          positioning={SELECT_POSITIONING}
+          size="xs"
+          value={modelValue}
+          valueText={modelName}
+          onValueChange={handleModel}
+        />
+      </Field>
+
+      {config.type === 'ip_adapter' ? (
+        <>
+          <Field label={t('widgets.layers.regionalGuidance.method')}>
+            <Select
+              aria-label={t('widgets.layers.regionalGuidance.method')}
+              collection={methodCollection}
+              positioning={SELECT_POSITIONING}
+              size="xs"
+              value={methodValue}
+              valueText={t(`widgets.layers.regionalGuidance.methods.${config.method}`)}
+              onValueChange={handleMethod}
+            />
+          </Field>
+          <Field label={t('widgets.layers.regionalGuidance.weight')}>
+            <Slider
+              aria-label={weightAria}
+              formatValue={formatWeight}
+              max={2}
+              min={-1}
+              size="sm"
+              step={0.01}
+              value={weightValue}
+              withThumbTooltip
+              onValueChange={handleWeight}
+              onValueChangeEnd={handleWeightEnd}
+            />
+          </Field>
+        </>
+      ) : config.type === 'flux_redux' ? (
+        <FluxReduxControls config={config} disabled={false} onChange={handleFluxReduxConfig} />
+      ) : null}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/RunLayerWorkflowDialog.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/RunLayerWorkflowDialog.test.ts
new file mode 100644
index 00000000000..8f9115ada3a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/RunLayerWorkflowDialog.test.ts
@@ -0,0 +1,72 @@
+import type { WorkflowImageBinding } from '@workbench/workflows/layerWorkflow';
+
+import { describe, expect, it } from 'vitest';
+
+import { getLayerWorkflowFailureKey, reconcileLayerWorkflowDialogSelection } from './RunLayerWorkflowDialog';
+
+const binding = (nodeId: string, fieldName = 'image', label = `${nodeId} → ${fieldName}`): WorkflowImageBinding => ({
+  fieldName,
+  label,
+  nodeId,
+});
+
+describe('reconcileLayerWorkflowDialogSelection', () => {
+  it('preserves a still-runnable input and output by field identity when availability refreshes', () => {
+    const refreshedInput = binding('input', 'image', 'Refreshed input');
+    const refreshedOutput = binding('output', 'image', 'Refreshed output');
+
+    expect(
+      reconcileLayerWorkflowDialogSelection(
+        {
+          destination: 'staging',
+          input: binding('input', 'image', 'Old input'),
+          output: binding('output', 'image', 'Old output'),
+        },
+        [refreshedOutput],
+        () => [refreshedInput]
+      )
+    ).toEqual({ destination: 'staging', input: refreshedInput, output: refreshedOutput });
+  });
+
+  it('keeps the selected output and clears its input when that output has no runnable inputs', () => {
+    const selectedOutput = binding('selected-output');
+    const fallbackOutput = binding('fallback-output');
+    const fallbackInput = binding('fallback-input');
+
+    expect(
+      reconcileLayerWorkflowDialogSelection(
+        { destination: 'copy-raster', input: binding('stale-input'), output: selectedOutput },
+        [selectedOutput, fallbackOutput],
+        (output) => (output.nodeId === fallbackOutput.nodeId ? [fallbackInput] : [])
+      )
+    ).toEqual({ destination: 'copy-raster', input: null, output: selectedOutput });
+  });
+
+  it('falls back to the first runnable pair when the selected output disappeared', () => {
+    const fallbackOutput = binding('fallback-output');
+    const fallbackInput = binding('fallback-input');
+
+    expect(
+      reconcileLayerWorkflowDialogSelection(
+        { destination: 'replace', input: binding('stale-input'), output: binding('removed-output') },
+        [fallbackOutput],
+        () => [fallbackInput]
+      )
+    ).toEqual({ destination: 'replace', input: fallbackInput, output: fallbackOutput });
+  });
+});
+
+describe('getLayerWorkflowFailureKey', () => {
+  it.each([
+    ['graph', 'widgets.layers.runWorkflow.graphFailure'],
+    ['hydrate', 'widgets.layers.runWorkflow.hydrationFailure'],
+    ['durability', 'widgets.layers.runWorkflow.durabilityFailure'],
+    ['export', 'widgets.layers.runWorkflow.failed'],
+    ['upload', 'widgets.layers.runWorkflow.failed'],
+    ['gallery', 'widgets.layers.runWorkflow.failed'],
+    ['staging', 'widgets.layers.runWorkflow.failed'],
+    ['commit', 'widgets.layers.runWorkflow.failed'],
+  ] as const)('maps %s failures to %s', (stage, key) => {
+    expect(getLayerWorkflowFailureKey(stage)).toBe(key);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/RunLayerWorkflowDialog.tsx b/invokeai/frontend/webv2/src/workbench/widgets/layers/RunLayerWorkflowDialog.tsx
new file mode 100644
index 00000000000..e5d1e75e9ea
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/RunLayerWorkflowDialog.tsx
@@ -0,0 +1,513 @@
+import type { SelectValueChangeDetails } from '@chakra-ui/react';
+import type { CanvasExportCapability, CanvasLayerCapability } from '@workbench/canvas-engine/api';
+import type { ProjectGraphState } from '@workbench/workflows/types';
+import type { FormEvent } from 'react';
+
+import { chakra, createListCollection, Dialog, Portal, Stack, Text } from '@chakra-ui/react';
+import { socketHub } from '@workbench/backend/socketHub';
+import { runUtilityGraph } from '@workbench/canvas-operations/backend/utilityQueue';
+import { Button, CloseButton, Field, Select } from '@workbench/components/ui';
+import { getGalleryImageByName, makeImageDurable, saveImageToGallery } from '@workbench/gallery/api';
+import { useNotify } from '@workbench/useNotify';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import {
+  buildLayerWorkflowGraph,
+  getDefaultLayerWorkflowSelection,
+  getLayerWorkflowInputs,
+  getLayerWorkflowOutputs,
+  getRunnableLayerWorkflowInputs,
+  reconcileLayerWorkflowSelection,
+  type GetRunnableLayerWorkflowInputs,
+  type LayerWorkflowSelection,
+  type WorkflowImageBinding,
+} from '@workbench/workflows/layerWorkflow';
+import { useInvocationTemplatesSnapshot, type InvocationTemplatesSnapshot } from '@workbench/workflows/templates';
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { createLayerActionSession } from './layerActionSession';
+import {
+  runLayerWorkflow,
+  type LayerWorkflowDestination,
+  type LayerWorkflowFailureStage,
+  type RunLayerWorkflowResult,
+} from './runLayerWorkflow';
+
+const SELECT_POSITIONING = { placement: 'bottom-start', sameWidth: true } as const;
+const EMPTY_BINDINGS: readonly WorkflowImageBinding[] = [];
+
+const bindingKey = (binding: WorkflowImageBinding): string => JSON.stringify([binding.nodeId, binding.fieldName]);
+const messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+export interface LayerWorkflowAvailability {
+  canRunWorkflow: boolean;
+  document: ProjectGraphState;
+  getRunnableInputs(output: WorkflowImageBinding): readonly WorkflowImageBinding[];
+  hasWorkflowBindings: boolean;
+  inputs: readonly WorkflowImageBinding[];
+  outputs: readonly WorkflowImageBinding[];
+  templatesSnapshot: InvocationTemplatesSnapshot;
+}
+
+/**
+ * Every layer row observes the same immutable graph/template objects. Cache the
+ * expensive injected-graph readiness probes by those identities so a long
+ * layer list does the work once, while each row still gets live eligibility.
+ */
+const availabilityCache = new WeakMap<
+  ProjectGraphState,
+  WeakMap<InvocationTemplatesSnapshot, LayerWorkflowAvailability>
+>();
+
+const getLayerWorkflowAvailability = (
+  document: ProjectGraphState,
+  templatesSnapshot: InvocationTemplatesSnapshot
+): LayerWorkflowAvailability => {
+  let byTemplates = availabilityCache.get(document);
+
+  if (!byTemplates) {
+    byTemplates = new WeakMap();
+    availabilityCache.set(document, byTemplates);
+  }
+
+  const cached = byTemplates.get(templatesSnapshot);
+
+  if (cached) {
+    return cached;
+  }
+
+  const inputs =
+    templatesSnapshot.status === 'loaded'
+      ? getLayerWorkflowInputs(document, templatesSnapshot.templates)
+      : EMPTY_BINDINGS;
+  const outputs =
+    templatesSnapshot.status === 'loaded'
+      ? getLayerWorkflowOutputs(document, templatesSnapshot.templates)
+      : EMPTY_BINDINGS;
+  const runnableByOutput = new Map<string, readonly WorkflowImageBinding[]>();
+
+  for (const output of outputs) {
+    runnableByOutput.set(bindingKey(output), getRunnableLayerWorkflowInputs(document, templatesSnapshot, output));
+  }
+
+  const availability: LayerWorkflowAvailability = {
+    canRunWorkflow: [...runnableByOutput.values()].some((runnableInputs) => runnableInputs.length > 0),
+    document,
+    getRunnableInputs: (output) => runnableByOutput.get(bindingKey(output)) ?? EMPTY_BINDINGS,
+    hasWorkflowBindings: inputs.length > 0 && outputs.length > 0,
+    inputs,
+    outputs,
+    templatesSnapshot,
+  };
+
+  byTemplates.set(templatesSnapshot, availability);
+  return availability;
+};
+
+export const useLayerWorkflowAvailability = (): LayerWorkflowAvailability => {
+  const document = useActiveProjectSelector((project) => project.projectGraph, Object.is);
+  const templatesSnapshot = useInvocationTemplatesSnapshot();
+
+  return getLayerWorkflowAvailability(document, templatesSnapshot);
+};
+
+interface RunLayerWorkflowDialogProps {
+  availability: LayerWorkflowAvailability;
+  engine: { readonly exports: CanvasExportCapability; readonly layers: CanvasLayerCapability } | null;
+  isOpen: boolean;
+  layerId: string;
+  onClose(): void;
+}
+
+interface SelectionState {
+  availability: LayerWorkflowAvailability;
+  selection: LayerWorkflowSelection;
+}
+
+const createDefaultSelection = (availability: LayerWorkflowAvailability): LayerWorkflowSelection =>
+  getDefaultLayerWorkflowSelection(availability.outputs, availability.getRunnableInputs);
+
+export const reconcileLayerWorkflowDialogSelection = (
+  current: LayerWorkflowSelection,
+  outputs: readonly WorkflowImageBinding[],
+  getRunnableInputs: GetRunnableLayerWorkflowInputs
+): LayerWorkflowSelection => {
+  const selectedOutput = current.output;
+  const currentOutput = selectedOutput
+    ? outputs.find((output) => bindingKey(output) === bindingKey(selectedOutput))
+    : undefined;
+
+  if (currentOutput) {
+    return reconcileLayerWorkflowSelection(current, currentOutput, getRunnableInputs(currentOutput));
+  }
+
+  return {
+    ...getDefaultLayerWorkflowSelection(outputs, getRunnableInputs),
+    destination: current.destination,
+  };
+};
+
+const SUCCESS_KEYS: Record<LayerWorkflowDestination, string> = {
+  'copy-raster': 'widgets.layers.runWorkflow.copySuccess',
+  gallery: 'widgets.layers.runWorkflow.gallerySuccess',
+  replace: 'widgets.layers.runWorkflow.replaceSuccess',
+  staging: 'widgets.layers.runWorkflow.stagingSuccess',
+};
+
+const FAILURE_KEYS: Record<Exclude<RunLayerWorkflowResult['status'], 'completed' | 'failed'>, string> = {
+  aborted: 'widgets.layers.runWorkflow.aborted',
+  busy: 'widgets.layers.runWorkflow.busy',
+  disabled: 'widgets.layers.runWorkflow.disabled',
+  empty: 'widgets.layers.runWorkflow.empty',
+  locked: 'widgets.layers.runWorkflow.locked',
+  missing: 'widgets.layers.runWorkflow.missing',
+  'not-ready': 'widgets.layers.runWorkflow.notReady',
+  'over-budget': 'widgets.layers.runWorkflow.notReady',
+  stale: 'widgets.layers.runWorkflow.stale',
+  unsupported: 'widgets.layers.runWorkflow.unsupported',
+};
+
+export const getLayerWorkflowFailureKey = (stage: LayerWorkflowFailureStage): string => {
+  switch (stage) {
+    case 'graph':
+      return 'widgets.layers.runWorkflow.graphFailure';
+    case 'hydrate':
+      return 'widgets.layers.runWorkflow.hydrationFailure';
+    case 'durability':
+      return 'widgets.layers.runWorkflow.durabilityFailure';
+    default:
+      return 'widgets.layers.runWorkflow.failed';
+  }
+};
+
+export const RunLayerWorkflowDialog = ({
+  availability,
+  engine,
+  isOpen,
+  layerId,
+  onClose,
+}: RunLayerWorkflowDialogProps) => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const dispatch = useWorkbenchDispatch();
+  const projectId = useActiveProjectSelector((project) => project.id);
+  const [session] = useState(createLayerActionSession);
+  const [selectionState, setSelectionState] = useState<SelectionState>(() => ({
+    availability,
+    selection: createDefaultSelection(availability),
+  }));
+  const [isRunning, setIsRunning] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  let selection = selectionState.selection;
+
+  if (selectionState.availability !== availability) {
+    selection = reconcileLayerWorkflowDialogSelection(selection, availability.outputs, availability.getRunnableInputs);
+    setSelectionState({ availability, selection });
+  }
+
+  const runnableInputs = selection.output ? availability.getRunnableInputs(selection.output) : EMPTY_BINDINGS;
+  const inputCollection = useMemo(
+    () =>
+      createListCollection({
+        items: runnableInputs.map((binding) => ({ label: binding.label, value: bindingKey(binding) })),
+      }),
+    [runnableInputs]
+  );
+  const outputCollection = useMemo(
+    () =>
+      createListCollection({
+        items: availability.outputs.map((binding) => ({ label: binding.label, value: bindingKey(binding) })),
+      }),
+    [availability.outputs]
+  );
+  const destinationCollection = useMemo(
+    () =>
+      createListCollection<{ label: string; value: LayerWorkflowDestination }>({
+        items: [
+          { label: t('widgets.layers.runWorkflow.gallery'), value: 'gallery' },
+          { label: t('widgets.layers.runWorkflow.staging'), value: 'staging' },
+          { label: t('widgets.layers.runWorkflow.replace'), value: 'replace' },
+          { label: t('widgets.layers.runWorkflow.copyRaster'), value: 'copy-raster' },
+        ],
+      }),
+    [t]
+  );
+  const inputValue = useMemo(() => (selection.input ? [bindingKey(selection.input)] : []), [selection.input]);
+  const outputValue = useMemo(() => (selection.output ? [bindingKey(selection.output)] : []), [selection.output]);
+  const destinationValue = useMemo(() => [selection.destination], [selection.destination]);
+
+  const close = useCallback(() => {
+    session.cancel();
+    onClose();
+  }, [onClose, session]);
+
+  const contentRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      if (!node) {
+        return;
+      }
+      return () => {
+        session.cancel();
+      };
+    },
+    [session]
+  );
+
+  const handleOpenChange = useCallback(
+    ({ open }: { open: boolean }) => {
+      if (!open) {
+        close();
+      }
+    },
+    [close]
+  );
+
+  const handleInputChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const input = runnableInputs.find((binding) => bindingKey(binding) === value[0]);
+
+      if (!input) {
+        return;
+      }
+
+      setSelectionState((current) => ({
+        availability,
+        selection: { ...current.selection, input },
+      }));
+      setError(null);
+    },
+    [availability, runnableInputs]
+  );
+
+  const handleOutputChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const output = availability.outputs.find((binding) => bindingKey(binding) === value[0]);
+
+      if (!output) {
+        return;
+      }
+
+      setSelectionState((current) => ({
+        availability,
+        selection: reconcileLayerWorkflowSelection(current.selection, output, availability.getRunnableInputs(output)),
+      }));
+      setError(null);
+    },
+    [availability]
+  );
+
+  const handleDestinationChange = useCallback(
+    ({ value }: SelectValueChangeDetails) => {
+      const destination = value[0] as LayerWorkflowDestination | undefined;
+
+      if (!destination || !destinationCollection.items.some((item) => item.value === destination)) {
+        return;
+      }
+
+      setSelectionState((current) => ({
+        availability,
+        selection: { ...current.selection, destination },
+      }));
+      setError(null);
+    },
+    [availability, destinationCollection.items]
+  );
+
+  const runContext = useMemo(
+    () => ({
+      availability,
+      close,
+      dispatch,
+      engine,
+      layerId,
+      notify,
+      projectId,
+      selection,
+      session,
+      t,
+    }),
+    [availability, close, dispatch, engine, layerId, notify, projectId, selection, session, t]
+  );
+
+  const run = useCallback(async (): Promise<void> => {
+    const { availability, close, dispatch, engine, layerId, notify, projectId, selection, session, t } = runContext;
+    const { input, output } = selection;
+
+    if (!engine || !input || !output) {
+      return;
+    }
+
+    const request = session.begin();
+
+    if (!request) {
+      return;
+    }
+
+    const destination = selection.destination;
+    setError(null);
+    setIsRunning(true);
+
+    try {
+      const executorDeps = engine.exports.getCompositeExecutorDeps();
+      const result = await runLayerWorkflow({
+        deps: {
+          appendStaging: (targetProjectId, candidate) =>
+            dispatch({ candidate, projectId: targetProjectId, type: 'appendCanvasStagingCandidate' }),
+          buildGraph: buildLayerWorkflowGraph,
+          commitGenerated: (options) => engine.layers.commitGeneratedImageResult(options),
+          createRequestId: () => crypto.randomUUID(),
+          exportLayer: (targetLayerId) => engine.exports.exportBakedLayerBlob(targetLayerId, { includeDisabled: true }),
+          getImage: getGalleryImageByName,
+          isGuardCurrent: (guard) => engine.exports.isLayerExportGuardCurrent(guard),
+          makeDurable: makeImageDurable,
+          runGraph: (options) => runUtilityGraph({ ...options, hub: socketHub }),
+          saveToGallery: saveImageToGallery,
+          touchGallery: (targetProjectId) =>
+            dispatch({ projectId: targetProjectId, type: 'touchGalleryImagesRefresh' }),
+          uploadIntermediate: async (blob, signal) => {
+            if (signal?.aborted) {
+              throw new DOMException('Layer workflow aborted', 'AbortError');
+            }
+            const uploaded = await executorDeps.uploadImage(blob);
+            if (signal?.aborted) {
+              throw new DOMException('Layer workflow aborted', 'AbortError');
+            }
+            return { imageName: uploaded.imageName };
+          },
+        },
+        destination,
+        document: availability.document,
+        input,
+        layerId,
+        output,
+        projectId,
+        signal: request.signal,
+        templatesSnapshot: availability.templatesSnapshot,
+      });
+
+      if (!session.isCurrent(request.token)) {
+        return;
+      }
+
+      if (result.status === 'completed') {
+        notify.success(t(SUCCESS_KEYS[destination]));
+        close();
+        return;
+      }
+
+      if (result.status === 'failed') {
+        setError(t(getLayerWorkflowFailureKey(result.stage), { message: result.message }));
+        return;
+      }
+
+      setError(t(FAILURE_KEYS[result.status]));
+    } catch (error) {
+      if (session.isCurrent(request.token)) {
+        setError(t('widgets.layers.runWorkflow.failed', { message: messageOf(error) }));
+      }
+    } finally {
+      if (session.isCurrent(request.token)) {
+        setIsRunning(false);
+      }
+      session.finish(request.token);
+    }
+  }, [runContext]);
+
+  const handleSubmit = useCallback(
+    (event: FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      void run();
+    },
+    [run]
+  );
+
+  const readinessMessage = !availability.hasWorkflowBindings
+    ? t('widgets.layers.runWorkflow.noBindings')
+    : !selection.input || !selection.output
+      ? t('widgets.layers.runWorkflow.notReady')
+      : null;
+  const canRun = engine !== null && !isRunning && readinessMessage === null;
+
+  return (
+    <Dialog.Root lazyMount open={isOpen} placement="center" size="sm" unmountOnExit onOpenChange={handleOpenChange}>
+      <Portal>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content ref={contentRef} bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" color="fg">
+            <chakra.form onSubmit={handleSubmit}>
+              <Dialog.Header>
+                <Dialog.Title fontSize="sm" fontWeight="700">
+                  {t('widgets.layers.runWorkflow.title')}
+                </Dialog.Title>
+              </Dialog.Header>
+              <Dialog.Body>
+                <Stack gap="4">
+                  <Field id="layer-workflow-output" label={t('widgets.layers.runWorkflow.output')}>
+                    <Select
+                      aria-label={t('widgets.layers.runWorkflow.output')}
+                      collection={outputCollection}
+                      disabled={isRunning || availability.outputs.length === 0}
+                      positioning={SELECT_POSITIONING}
+                      size="sm"
+                      value={outputValue}
+                      onValueChange={handleOutputChange}
+                    />
+                  </Field>
+                  <Field id="layer-workflow-input" label={t('widgets.layers.runWorkflow.input')}>
+                    <Select
+                      aria-label={t('widgets.layers.runWorkflow.input')}
+                      collection={inputCollection}
+                      disabled={isRunning || runnableInputs.length === 0}
+                      positioning={SELECT_POSITIONING}
+                      size="sm"
+                      value={inputValue}
+                      onValueChange={handleInputChange}
+                    />
+                  </Field>
+                  <Field id="layer-workflow-destination" label={t('widgets.layers.runWorkflow.destination')}>
+                    <Select
+                      aria-label={t('widgets.layers.runWorkflow.destination')}
+                      collection={destinationCollection}
+                      disabled={isRunning}
+                      positioning={SELECT_POSITIONING}
+                      size="sm"
+                      value={destinationValue}
+                      onValueChange={handleDestinationChange}
+                    />
+                  </Field>
+                  {readinessMessage ? (
+                    <Text color="fg.error" fontSize="xs" role="alert">
+                      {readinessMessage}
+                    </Text>
+                  ) : null}
+                  {error ? (
+                    <Text color="fg.error" fontSize="xs" role="alert">
+                      {error}
+                    </Text>
+                  ) : null}
+                  {isRunning ? (
+                    <Text color="fg.muted" fontSize="xs" role="status">
+                      {t('widgets.layers.runWorkflow.running')}
+                    </Text>
+                  ) : null}
+                </Stack>
+              </Dialog.Body>
+              <Dialog.Footer gap="2">
+                <Button size="xs" type="button" variant="ghost" onClick={close}>
+                  {t('widgets.layers.runWorkflow.cancel')}
+                </Button>
+                <Button disabled={!canRun} loading={isRunning} size="xs" type="submit" variant="solid">
+                  {t('widgets.layers.runWorkflow.run')}
+                </Button>
+              </Dialog.Footer>
+            </chakra.form>
+            <Dialog.CloseTrigger asChild>
+              <CloseButton aria-label={t('widgets.layers.runWorkflow.cancel')} color="fg.muted" size="sm" />
+            </Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/addLayerMenu.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/addLayerMenu.test.ts
new file mode 100644
index 00000000000..17475e87778
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/addLayerMenu.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { ADD_LAYER_MENU, groupAddItemId } from './addLayerMenu';
+
+describe('ADD_LAYER_MENU', () => {
+  it('splits into the legacy Regional / Layers groups in order', () => {
+    expect(ADD_LAYER_MENU.map((group) => group.titleKey)).toEqual([
+      'widgets.layers.menuGroups.regional',
+      'widgets.layers.menuGroups.layers',
+    ]);
+  });
+
+  it('lists inpaint mask, regional guidance, and regional reference image under Regional', () => {
+    expect(ADD_LAYER_MENU[0]?.items.map((item) => item.id)).toEqual([
+      'inpaint_mask',
+      'regional_guidance',
+      'regional_reference_image',
+    ]);
+  });
+
+  it('lists control + raster under Layers', () => {
+    expect(ADD_LAYER_MENU[1]?.items.map((item) => item.id)).toEqual(['control', 'raster']);
+  });
+
+  it('gives every item a widgets.layers i18n label key', () => {
+    for (const group of ADD_LAYER_MENU) {
+      for (const item of group.items) {
+        expect(item.labelKey.startsWith('widgets.layers.actions.')).toBe(true);
+      }
+    }
+  });
+});
+
+describe('groupAddItemId', () => {
+  it('maps a group key to its own add-layer item', () => {
+    expect(groupAddItemId('raster')).toBe('raster');
+    expect(groupAddItemId('control')).toBe('control');
+    expect(groupAddItemId('inpaint_mask')).toBe('inpaint_mask');
+    // A group header's "New" creates a plain region, not the ref-image variant.
+    expect(groupAddItemId('regional_guidance')).toBe('regional_guidance');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/addLayerMenu.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/addLayerMenu.ts
new file mode 100644
index 00000000000..aa3888bd485
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/addLayerMenu.ts
@@ -0,0 +1,48 @@
+/**
+ * Pure data for the layers-panel add-layer surfaces (kept free of React so the
+ * grouping is unit-testable). The header menu renders {@link ADD_LAYER_MENU}; each
+ * group header's "New" button uses {@link groupAddItemId} to add its own type.
+ */
+
+import type { LayerGroupKey } from './layerGroups';
+
+/** The distinct "add a layer" actions offered across the panel's add surfaces. */
+export type AddLayerItemId = 'inpaint_mask' | 'regional_guidance' | 'regional_reference_image' | 'control' | 'raster';
+
+/** A single add-layer menu entry (label is an i18n key; the icon lives in the view). */
+export interface AddLayerMenuItem {
+  id: AddLayerItemId;
+  labelKey: string;
+}
+
+/** A titled group of add-layer menu entries. */
+export interface AddLayerMenuGroup {
+  titleKey: string;
+  items: AddLayerMenuItem[];
+}
+
+/**
+ * The add-layer menu, split into legacy's two labelled groups: "Regional" (inpaint
+ * mask, regional guidance, regional guidance seeded with a reference image) and
+ * "Layers" (control, raster).
+ */
+export const ADD_LAYER_MENU: readonly AddLayerMenuGroup[] = [
+  {
+    items: [
+      { id: 'inpaint_mask', labelKey: 'widgets.layers.actions.addInpaintMask' },
+      { id: 'regional_guidance', labelKey: 'widgets.layers.actions.addRegionalGuidance' },
+      { id: 'regional_reference_image', labelKey: 'widgets.layers.actions.addRegionalReferenceImage' },
+    ],
+    titleKey: 'widgets.layers.menuGroups.regional',
+  },
+  {
+    items: [
+      { id: 'control', labelKey: 'widgets.layers.actions.addControlLayer' },
+      { id: 'raster', labelKey: 'widgets.layers.actions.addRasterLayer' },
+    ],
+    titleKey: 'widgets.layers.menuGroups.layers',
+  },
+];
+
+/** The add-layer action a group-header "New" button triggers for its type. */
+export const groupAddItemId = (groupKey: LayerGroupKey): AddLayerItemId => groupKey;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/controlModelOptions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/controlModelOptions.test.ts
new file mode 100644
index 00000000000..d33e766c0d1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/controlModelOptions.test.ts
@@ -0,0 +1,32 @@
+import type { ModelConfig } from '@workbench/models/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { getCompatibleControlModels } from './controlModelOptions';
+
+const model = (key: string, base: string, type: string): ModelConfig => ({ base, key, name: key, type }) as ModelConfig;
+
+describe('getCompatibleControlModels', () => {
+  it('returns only Z-Image ControlNet models for z_image_control', () => {
+    const models = [
+      model('z-control', 'z-image', 'controlnet'),
+      model('sd-control', 'sd-1', 'controlnet'),
+      model('z-t2i', 'z-image', 't2i_adapter'),
+    ];
+
+    expect(getCompatibleControlModels(models, 'z-image', 'z_image_control').map((candidate) => candidate.key)).toEqual([
+      'z-control',
+    ]);
+    expect(getCompatibleControlModels(models, 'sd-1', 'z_image_control')).toEqual([]);
+  });
+
+  it('keeps existing adapter filtering unchanged', () => {
+    const models = [model('sd-control', 'sd-1', 'controlnet'), model('flux-lora', 'flux', 'control_lora')];
+    expect(getCompatibleControlModels(models, 'sd-1', 'controlnet').map((candidate) => candidate.key)).toEqual([
+      'sd-control',
+    ]);
+    expect(getCompatibleControlModels(models, null, 'control_lora').map((candidate) => candidate.key)).toEqual([
+      'flux-lora',
+    ]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/controlModelOptions.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/controlModelOptions.ts
new file mode 100644
index 00000000000..e3b32508618
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/controlModelOptions.ts
@@ -0,0 +1,14 @@
+import type { ControlAdapterKind } from '@workbench/generation/canvas/controlValidation';
+import type { ModelConfig } from '@workbench/models/types';
+
+export const getCompatibleControlModels = (
+  models: readonly ModelConfig[],
+  base: string | null,
+  kind: ControlAdapterKind
+): ModelConfig[] => {
+  if (kind === 'z_image_control' && base !== 'z-image') {
+    return [];
+  }
+  const modelType = kind === 'z_image_control' ? 'controlnet' : kind;
+  return models.filter((model) => model.type === modelType && (!base || model.base === base));
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/curveEditorMath.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/curveEditorMath.test.ts
new file mode 100644
index 00000000000..075f4affc2e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/curveEditorMath.test.ts
@@ -0,0 +1,75 @@
+import type { CanvasAdjustmentsContract } from '@workbench/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { curvePointFromSvg, curvePointToSvg, finishCurveDragResult, getCurveGridCoordinates } from './curveEditorMath';
+
+const BEFORE: CanvasAdjustmentsContract = {
+  brightness: 0,
+  contrast: 0,
+  curves: {
+    b: [
+      [0, 0],
+      [255, 255],
+    ],
+    g: [
+      [0, 0],
+      [255, 255],
+    ],
+    r: [
+      [0, 0],
+      [255, 255],
+    ],
+  },
+  saturation: 0,
+};
+
+const CURRENT: CanvasAdjustmentsContract = {
+  ...BEFORE,
+  curves: {
+    ...BEFORE.curves!,
+    r: [
+      [0, 32],
+      [255, 255],
+    ],
+  },
+};
+
+describe('curve editor coordinates', () => {
+  it('insets endpoints so handles are fully visible', () => {
+    expect(curvePointToSvg(0, 0)).toEqual({ cx: 6, cy: 174 });
+    expect(curvePointToSvg(255, 255)).toEqual({ cx: 174, cy: 6 });
+  });
+
+  it('round-trips and clamps pointer coordinates through the inset plot', () => {
+    expect(curvePointFromSvg(90, 90)).toEqual([128, 128]);
+    expect(curvePointFromSvg(-20, 220)).toEqual([0, 0]);
+    expect(curvePointFromSvg(220, -20)).toEqual([255, 255]);
+  });
+
+  it('places the grid at quarter intervals within the inset plot', () => {
+    expect(getCurveGridCoordinates()).toEqual([6, 48, 90, 132, 174]);
+  });
+
+  it('restores the pre-drag snapshot without committing when cancelled after a live change', () => {
+    const onPreview = vi.fn();
+    const onCommit = vi.fn();
+
+    finishCurveDragResult({ before: BEFORE, cancelled: true, current: CURRENT, onCommit, onPreview });
+
+    expect(onPreview).toHaveBeenCalledTimes(1);
+    expect(onPreview).toHaveBeenCalledWith(BEFORE);
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('commits the current snapshot without restoring on pointer up', () => {
+    const onPreview = vi.fn();
+    const onCommit = vi.fn();
+
+    finishCurveDragResult({ before: BEFORE, cancelled: false, current: CURRENT, onCommit, onPreview });
+
+    expect(onCommit).toHaveBeenCalledTimes(1);
+    expect(onCommit).toHaveBeenCalledWith(CURRENT);
+    expect(onPreview).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/curveEditorMath.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/curveEditorMath.ts
new file mode 100644
index 00000000000..75058957c69
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/curveEditorMath.ts
@@ -0,0 +1,43 @@
+import type { CanvasAdjustmentsContract } from '@workbench/types';
+
+export const CURVE_SIZE = 180;
+export const CURVE_PADDING = 6;
+
+const CURVE_DRAW_SIZE = CURVE_SIZE - CURVE_PADDING * 2;
+const clamp255 = (value: number): number => Math.max(0, Math.min(255, value));
+
+export const getCurveGridCoordinates = (): number[] =>
+  Array.from({ length: 5 }, (_, index) => CURVE_PADDING + (index / 4) * CURVE_DRAW_SIZE);
+
+interface FinishCurveDragResultArgs {
+  cancelled: boolean;
+  before: CanvasAdjustmentsContract;
+  current: CanvasAdjustmentsContract;
+  onPreview: (adjustments: CanvasAdjustmentsContract) => void;
+  onCommit: (adjustments: CanvasAdjustmentsContract) => void;
+}
+
+export const finishCurveDragResult = ({
+  before,
+  cancelled,
+  current,
+  onCommit,
+  onPreview,
+}: FinishCurveDragResultArgs): void => {
+  if (cancelled) {
+    onPreview(before);
+    return;
+  }
+  onCommit(current);
+};
+
+export const curvePointToSvg = (x: number, y: number): { cx: number; cy: number } => ({
+  cx: CURVE_PADDING + (clamp255(x) / 255) * CURVE_DRAW_SIZE,
+  cy: CURVE_SIZE - CURVE_PADDING - (clamp255(y) / 255) * CURVE_DRAW_SIZE,
+});
+
+export const curvePointFromSvg = (px: number, py: number): [number, number] => {
+  const x = Math.round(((px - CURVE_PADDING) / CURVE_DRAW_SIZE) * 255);
+  const y = Math.round(((CURVE_SIZE - CURVE_PADDING - py) / CURVE_DRAW_SIZE) * 255);
+  return [clamp255(x), clamp255(y)];
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/index.ts
new file mode 100644
index 00000000000..680ae2cf89f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/index.ts
@@ -0,0 +1,18 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { LayersIcon } from 'lucide-react';
+
+import { LayersHeaderActions } from './LayersHeaderActions';
+import { LayersWidgetView } from './LayersWidgetView';
+
+export const layersWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['right'],
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  headerActions: LayersHeaderActions,
+  icon: LayersIcon,
+  id: 'layers',
+  label: (t) => t('widgets.labels.layers'),
+  version: 1,
+  view: LayersWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerActionSession.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerActionSession.test.ts
new file mode 100644
index 00000000000..40deb1c6b17
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerActionSession.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+
+import { createLayerActionSession } from './layerActionSession';
+
+describe('createLayerActionSession', () => {
+  it('allows only one request at a time and permits a new request after current finish', () => {
+    const session = createLayerActionSession();
+    const first = session.begin();
+
+    expect(first).not.toBeNull();
+    expect(session.begin()).toBeNull();
+    expect(session.isCurrent(first!.token)).toBe(true);
+    session.finish(first!.token);
+    expect(session.isCurrent(first!.token)).toBe(false);
+    expect(session.begin()).not.toBeNull();
+  });
+
+  it('cancel aborts and invalidates the active request while keeping the session reusable', () => {
+    const session = createLayerActionSession();
+    const first = session.begin()!;
+
+    session.cancel();
+
+    expect(first.signal.aborted).toBe(true);
+    expect(session.isCurrent(first.token)).toBe(false);
+    const second = session.begin();
+    expect(second).not.toBeNull();
+    expect(second!.token).not.toBe(first.token);
+  });
+
+  it('ignores stale finish so an old completion cannot clear the current request', () => {
+    const session = createLayerActionSession();
+    const first = session.begin()!;
+    session.cancel();
+    const second = session.begin()!;
+
+    session.finish(first.token);
+
+    expect(session.isCurrent(second.token)).toBe(true);
+    expect(session.begin()).toBeNull();
+  });
+
+  it('rejects a late completion after close/cancel invalidates its token', () => {
+    const session = createLayerActionSession();
+    const request = session.begin()!;
+    const wasCurrent = () => session.isCurrent(request.token);
+
+    session.cancel();
+
+    expect(wasCurrent()).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerActionSession.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerActionSession.ts
new file mode 100644
index 00000000000..6f24b0437ce
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerActionSession.ts
@@ -0,0 +1,39 @@
+export interface LayerActionRequest {
+  token: number;
+  signal: AbortSignal;
+}
+
+export interface LayerActionSession {
+  begin(): LayerActionRequest | null;
+  cancel(): void;
+  finish(token: number): void;
+  isCurrent(token: number): boolean;
+}
+
+export const createLayerActionSession = (): LayerActionSession => {
+  let nextToken = 0;
+  let active: { controller: AbortController; token: number } | null = null;
+
+  return {
+    begin: () => {
+      if (active) {
+        return null;
+      }
+      const controller = new AbortController();
+      const token = ++nextToken;
+      active = { controller, token };
+      return { signal: controller.signal, token };
+    },
+    cancel: () => {
+      nextToken += 1;
+      active?.controller.abort();
+      active = null;
+    },
+    finish: (token) => {
+      if (active?.token === token) {
+        active = null;
+      }
+    },
+    isCurrent: (token) => active?.token === token && !active.controller.signal.aborted,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextActions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextActions.test.ts
new file mode 100644
index 00000000000..b64a5f73b23
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextActions.test.ts
@@ -0,0 +1,764 @@
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  getLayerContextActionDefinition,
+  getLayerContextActions,
+  LAYER_CONTEXT_ACTION_DEFINITIONS,
+  type LayerContextAction,
+  type LayerContextActionEffects,
+  type LayerContextActionId,
+  type LayerContextActionRuntimeContext,
+  type LayerContextActionState,
+} from './layerContextActions';
+import {
+  createControlLayer,
+  createEmptyPaintLayer,
+  createInpaintMaskLayer,
+  createRegionalGuidanceLayer,
+} from './layerOps';
+
+const englishCatalogModules = import.meta.glob('../../../../public/locales/en.json', {
+  eager: true,
+  import: 'default',
+});
+const en = Object.values(englishCatalogModules)[0] as unknown;
+
+const paintLayer = (id: string, patch: Partial<CanvasRasterLayerContractV2> = {}): CanvasRasterLayerContractV2 => ({
+  ...createEmptyPaintLayer(id, id),
+  source: { bitmap: { height: 10, imageName: `${id}.png`, width: 10 }, type: 'paint' },
+  ...patch,
+});
+
+const rasterLayer = paintLayer('raster');
+const nonEmptyControlLayer = {
+  ...createControlLayer('Control', 'control'),
+  source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' as const },
+};
+
+const makeLayer = (type: CanvasLayerContract['type']): CanvasLayerContract => {
+  switch (type) {
+    case 'raster':
+      return paintLayer('raster');
+    case 'control':
+      return nonEmptyControlLayer;
+    case 'inpaint_mask':
+      return createInpaintMaskLayer('Mask', 'mask');
+    case 'regional_guidance':
+      return createRegionalGuidanceLayer('Region', 0, 'region');
+  }
+};
+
+const makeDocument = (layers: CanvasLayerContract[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 512, width: 512, x: 0, y: 0 },
+  height: 512,
+  layers,
+  selectedLayerId: layers[0]?.id ?? null,
+  version: 2,
+  width: 512,
+});
+
+const makeState = (
+  layer: CanvasLayerContract,
+  overrides: Partial<LayerContextActionState> = {}
+): LayerContextActionState => {
+  const document = overrides.document ?? makeDocument([layer]);
+  return {
+    canRunWorkflow: true,
+    document,
+    hasEngine: true,
+    hasSupportedContent: true,
+    hasWorkflowBindings: true,
+    index: document.layers.findIndex((entry) => entry.id === layer.id),
+    interactionLocked: false,
+    layer,
+    ...overrides,
+  };
+};
+
+const makeEffects = (): LayerContextActionEffects => ({
+  booleanMerge: vi.fn(() => Promise.resolve()),
+  copyTo: vi.fn(),
+  copyToClipboard: vi.fn(() => Promise.resolve()),
+  cropToBbox: vi.fn(() => Promise.resolve()),
+  delete: vi.fn(),
+  duplicate: vi.fn(),
+  extractMaskedArea: vi.fn(() => Promise.resolve()),
+  fitToBbox: vi.fn(),
+  mergeDown: vi.fn(),
+  openProperties: vi.fn(),
+  openRename: vi.fn(),
+  openRunWorkflow: vi.fn(),
+  startSelectObject: vi.fn(),
+  startFilter: vi.fn(),
+  patchConfig: vi.fn(),
+  rasterize: vi.fn(),
+  reorder: vi.fn(),
+  saveToAssets: vi.fn(() => Promise.resolve()),
+  toggleLock: vi.fn(),
+  toggleVisibility: vi.fn(),
+  transform: vi.fn(),
+  convertTo: vi.fn(),
+});
+
+const makeRuntimeContext = (
+  layer: CanvasLayerContract,
+  overrides: Partial<LayerContextActionRuntimeContext> = {}
+): LayerContextActionRuntimeContext => ({
+  ...makeState(layer, overrides),
+  effects: makeEffects(),
+  ...overrides,
+});
+
+const byId = (actions: readonly LayerContextAction[], id: LayerContextActionId): LayerContextAction => {
+  const action = actions.find((entry) => entry.id === id);
+  expect(action, `Expected action ${id}`).toBeDefined();
+  return action!;
+};
+
+const idsFor = (
+  layer: CanvasLayerContract,
+  layers: readonly CanvasLayerContract[] = [layer],
+  overrides: Partial<LayerContextActionState> = {}
+): LayerContextActionId[] =>
+  getLayerContextActions(makeState(layer, { document: makeDocument([...layers]), ...overrides })).map(
+    (action) => action.id
+  );
+
+const getEnglishTranslation = (key: string): unknown =>
+  key.split('.').reduce<unknown>((value, segment) => {
+    if (!value || typeof value !== 'object') {
+      return undefined;
+    }
+    return (value as Record<string, unknown>)[segment];
+  }, en);
+
+describe('layer context action registry', () => {
+  it('defines every action as complete executable data', () => {
+    for (const definition of LAYER_CONTEXT_ACTION_DEFINITIONS) {
+      expect(definition.icon).toBeDefined();
+      expect(definition.section).toMatch(/^(quick|primary|operations|output|state|danger)$/);
+      expect(definition.order).toEqual(expect.any(Number));
+      expect(definition.supportedLayerTypes.length).toBeGreaterThan(0);
+      expect(definition.isVisible).toEqual(expect.any(Function));
+      expect(definition.isEnabled).toEqual(expect.any(Function));
+      expect(definition.handler).toEqual(expect.any(Function));
+    }
+  });
+
+  it('has one definition per action id', () => {
+    const ids = LAYER_CONTEXT_ACTION_DEFINITIONS.map((definition) => definition.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('has English translations for registry labels and action errors', () => {
+    const keys = [
+      ...LAYER_CONTEXT_ACTION_DEFINITIONS.map((definition) => definition.labelKey),
+      'widgets.layers.actions.enableTransparencyEffect',
+      'widgets.layers.actions.disableTransparencyEffect',
+      'widgets.layers.actions.enableAutoNegative',
+      'widgets.layers.actions.disableAutoNegative',
+      'widgets.layers.actions.actionFailed',
+      'widgets.layers.actions.missing',
+      'widgets.layers.actions.unsupported',
+      'widgets.layers.actions.busy',
+      'widgets.layers.actions.locked',
+      'widgets.layers.actions.notReady',
+      'widgets.layers.actions.empty',
+      'widgets.layers.actions.disabled',
+      'widgets.layers.actions.copyFailed',
+      'widgets.layers.actions.cropBusy',
+      'widgets.layers.actions.cropFailed',
+      'widgets.layers.actions.cropUnsupported',
+      'widgets.layers.actions.cropped',
+      'widgets.layers.rasterFilter.busy',
+      'widgets.layers.rasterFilter.cancel',
+      'widgets.layers.rasterFilter.commitFailure',
+      'widgets.layers.rasterFilter.copy',
+      'widgets.layers.rasterFilter.durabilityFailure',
+      'widgets.layers.rasterFilter.graphFailure',
+      'widgets.layers.rasterFilter.locked',
+      'widgets.layers.rasterFilter.preview',
+      'widgets.layers.rasterFilter.replace',
+      'widgets.layers.rasterFilter.running',
+      'widgets.layers.rasterFilter.stale',
+      'widgets.layers.rasterFilter.title',
+      'widgets.layers.rasterFilter.unsupported',
+      'widgets.layers.selectObject.autoProcess',
+      'widgets.layers.selectObject.exclude',
+      'widgets.layers.selectObject.include',
+      'widgets.layers.selectObject.invert',
+      'widgets.layers.selectObject.isolatedPreview',
+      'widgets.layers.selectObject.model',
+      'widgets.layers.selectObject.modelHuge',
+      'widgets.layers.selectObject.modelSam2Large',
+      'widgets.layers.selectObject.prompt',
+      'widgets.layers.selectObject.process',
+      'widgets.layers.selectObject.refine',
+      'widgets.layers.selectObject.reset',
+      'widgets.layers.selectObject.saveAs',
+      'widgets.layers.selectObject.saveAs_control',
+      'widgets.layers.selectObject.saveAs_inpaint_mask',
+      'widgets.layers.selectObject.saveAs_raster',
+      'widgets.layers.selectObject.saveAs_regional_guidance',
+      'widgets.layers.selectObject.visual',
+      'widgets.layers.runWorkflow.aborted',
+      'widgets.layers.runWorkflow.busy',
+      'widgets.layers.runWorkflow.cancel',
+      'widgets.layers.runWorkflow.copyRaster',
+      'widgets.layers.runWorkflow.copySuccess',
+      'widgets.layers.runWorkflow.destination',
+      'widgets.layers.runWorkflow.durabilityFailure',
+      'widgets.layers.runWorkflow.disabled',
+      'widgets.layers.runWorkflow.empty',
+      'widgets.layers.runWorkflow.failed',
+      'widgets.layers.runWorkflow.gallery',
+      'widgets.layers.runWorkflow.gallerySuccess',
+      'widgets.layers.runWorkflow.graphFailure',
+      'widgets.layers.runWorkflow.hydrationFailure',
+      'widgets.layers.runWorkflow.input',
+      'widgets.layers.runWorkflow.locked',
+      'widgets.layers.runWorkflow.missing',
+      'widgets.layers.runWorkflow.noBindings',
+      'widgets.layers.runWorkflow.notReady',
+      'widgets.layers.runWorkflow.output',
+      'widgets.layers.runWorkflow.replace',
+      'widgets.layers.runWorkflow.replaceSuccess',
+      'widgets.layers.runWorkflow.run',
+      'widgets.layers.runWorkflow.running',
+      'widgets.layers.runWorkflow.staging',
+      'widgets.layers.runWorkflow.stagingSuccess',
+      'widgets.layers.runWorkflow.stale',
+      'widgets.layers.runWorkflow.title',
+      'widgets.layers.runWorkflow.unsupported',
+    ];
+
+    for (const key of keys) {
+      expect(getEnglishTranslation(key), key).toEqual(expect.any(String));
+    }
+  });
+
+  it('provides the disabled-layer reason used when Select Object start is refused', () => {
+    expect(getEnglishTranslation('widgets.layers.actions.disabled')).toBe('Enable the layer before using this action.');
+  });
+
+  it('throws for an unknown action definition', () => {
+    expect(() => getLayerContextActionDefinition('unknown' as LayerContextActionId)).toThrow(
+      'Unknown layer context action: unknown'
+    );
+  });
+
+  it('dispatches a registry handler through injected effects', () => {
+    const transform = vi.fn();
+    const context = makeRuntimeContext(rasterLayer, { effects: { ...makeEffects(), transform } });
+    getLayerContextActionDefinition('transform').handler(context);
+    expect(transform).toHaveBeenCalledOnce();
+  });
+
+  it('starts Select Object for the action layer through the registry', () => {
+    const effects = makeEffects();
+    const context = makeRuntimeContext(rasterLayer, { effects });
+
+    getLayerContextActionDefinition('select-object').handler(context);
+
+    expect(effects.startSelectObject).toHaveBeenCalledWith(rasterLayer.id);
+    expect(Object.values(effects).filter((effect) => effect.mock.calls.length > 0)).toEqual([
+      effects.startSelectObject,
+    ]);
+  });
+
+  it('opens Run Workflow through the registry without starting work itself', () => {
+    const effects = makeEffects();
+    const context = makeRuntimeContext(rasterLayer, { effects });
+
+    getLayerContextActionDefinition('run-workflow').handler(context);
+
+    expect(effects.openRunWorkflow).toHaveBeenCalledOnce();
+    expect(Object.values(effects).filter((effect) => effect.mock.calls.length > 0)).toEqual([effects.openRunWorkflow]);
+  });
+
+  it('dispatches parameterized registry handlers through injected effects', () => {
+    const effects = makeEffects();
+    const context = makeRuntimeContext(rasterLayer, { effects });
+
+    getLayerContextActionDefinition('move-to-front').handler(context);
+    getLayerContextActionDefinition('adjustments').handler(context);
+    getLayerContextActionDefinition('filter').handler(context);
+    getLayerContextActionDefinition('intersect').handler(context);
+    getLayerContextActionDefinition('copy-to-control').handler(context);
+    getLayerContextActionDefinition('convert-to-control').handler(context);
+    getLayerContextActionDefinition('regional-auto-negative').handler(context);
+
+    expect(effects.reorder).toHaveBeenCalledWith('front', 'move-to-front');
+    expect(effects.openProperties).toHaveBeenCalledWith('adjustments');
+    expect(effects.startFilter).toHaveBeenCalledWith(rasterLayer.id);
+    expect(effects.booleanMerge).toHaveBeenCalledWith('intersect');
+    expect(effects.copyTo).toHaveBeenCalledWith('control');
+    expect(effects.convertTo).toHaveBeenCalledWith('control');
+    expect(effects.patchConfig).toHaveBeenCalledWith('regional-auto-negative');
+  });
+});
+
+describe('getLayerContextActions', () => {
+  it.each([
+    ['raster', 'adjustments', true],
+    ['control', 'adjustments', false],
+    ['inpaint_mask', 'extract-masked-area', true],
+    ['control', 'extract-masked-area', false],
+  ] as const)('resolves %s visibility for %s', (type, actionId, expected) => {
+    const action = getLayerContextActions(makeState(makeLayer(type))).find((item) => item.id === actionId);
+    expect(Boolean(action)).toBe(expected);
+  });
+
+  it.each([
+    ['raster', true],
+    ['control', true],
+    ['inpaint_mask', false],
+    ['regional_guidance', false],
+  ] as const)('exposes transform only for engine-supported %s layers', (type, expected) => {
+    const action = getLayerContextActions(makeState(makeLayer(type))).find((item) => item.id === 'transform');
+    expect(Boolean(action)).toBe(expected);
+  });
+
+  it.each([
+    ['raster', true],
+    ['control', true],
+    ['inpaint_mask', false],
+    ['regional_guidance', false],
+  ] as const)('exposes layer-scoped Select Object only for pixel %s layers', (type, expected) => {
+    const action = getLayerContextActions(makeState(makeLayer(type))).find((item) => item.id === 'select-object');
+    expect(Boolean(action)).toBe(expected);
+  });
+
+  it('hides Select Object without source content', () => {
+    expect(
+      getLayerContextActions(makeState(rasterLayer, { hasSupportedContent: false })).some(
+        (action) => action.id === 'select-object'
+      )
+    ).toBe(false);
+  });
+
+  it.each([
+    ['raster', true],
+    ['control', true],
+    ['inpaint_mask', false],
+    ['regional_guidance', false],
+  ] as const)('exposes Run Workflow only for exportable %s content with compatible bindings', (type, expected) => {
+    const action = getLayerContextActions(makeState(makeLayer(type))).find((item) => item.id === 'run-workflow');
+    expect(Boolean(action)).toBe(expected);
+  });
+
+  it('hides Run Workflow when the active workflow has no compatible image bindings', () => {
+    expect(
+      getLayerContextActions(makeState(rasterLayer, { hasWorkflowBindings: false })).some(
+        (action) => action.id === 'run-workflow'
+      )
+    ).toBe(false);
+  });
+
+  it.each([
+    ['no runnable binding', { canRunWorkflow: false }],
+    ['missing engine', { hasEngine: false }],
+    ['locked layer', { layer: { ...rasterLayer, isLocked: true } }],
+    ['locked interaction', { interactionLocked: true }],
+  ] as const)('disables Run Workflow for %s', (_label, overrides) => {
+    const layer = 'layer' in overrides ? overrides.layer : rasterLayer;
+    expect(byId(getLayerContextActions(makeState(layer, overrides)), 'run-workflow').isDisabled).toBe(true);
+  });
+
+  it.each([
+    ['missing engine', { hasEngine: false }],
+    ['locked interaction', { interactionLocked: true }],
+  ] as const)('disables Select Object for %s', (_label, overrides) => {
+    expect(byId(getLayerContextActions(makeState(rasterLayer, overrides)), 'select-object').isDisabled).toBe(true);
+  });
+
+  it('disables Select Object for a locked layer', () => {
+    const locked = { ...rasterLayer, isLocked: true };
+    expect(byId(getLayerContextActions(makeState(locked)), 'select-object').isDisabled).toBe(true);
+  });
+
+  it('disables transform for a hidden layer', () => {
+    const hidden = { ...rasterLayer, isEnabled: false };
+    expect(byId(getLayerContextActions(makeState(hidden)), 'transform').isDisabled).toBe(true);
+  });
+
+  it('disables mutating pixel actions while interaction is locked', () => {
+    const rasterActions = getLayerContextActions(makeState(rasterLayer, { interactionLocked: true }));
+    const controlActions = getLayerContextActions(makeState(nonEmptyControlLayer, { interactionLocked: true }));
+    expect(byId(rasterActions, 'crop-to-bbox').isDisabled).toBe(true);
+    expect(byId(rasterActions, 'filter').isDisabled).toBe(true);
+    expect(byId(rasterActions, 'transform').isDisabled).toBe(true);
+    expect(byId(controlActions, 'filter').isDisabled).toBe(true);
+    expect(byId(rasterActions, 'copy-to-clipboard').isDisabled).toBe(true);
+  });
+
+  it('disables every layer action while canvas interaction is locked', () => {
+    const above = paintLayer('interaction-above');
+    const raster = paintLayer('interaction-raster');
+    const below = paintLayer('interaction-below');
+    const rasterDocument = makeDocument([above, raster, below]);
+    const text = paintLayer('interaction-text', {
+      source: {
+        align: 'left',
+        color: '#fff',
+        content: 'locked',
+        fontFamily: 'Inter',
+        fontSize: 32,
+        fontWeight: 400,
+        lineHeight: 1.2,
+        type: 'text',
+      },
+    });
+    const inpaint = createInpaintMaskLayer('Interaction mask', 'interaction-mask');
+    const regional = createRegionalGuidanceLayer('Interaction region', 0, 'interaction-region');
+    const contexts = [
+      makeState(raster, { document: rasterDocument, interactionLocked: true }),
+      makeState(nonEmptyControlLayer, { interactionLocked: true }),
+      makeState(inpaint, { interactionLocked: true }),
+      makeState(regional, { interactionLocked: true }),
+      makeState(text, { interactionLocked: true }),
+    ];
+    const actions = contexts.flatMap((context) => getLayerContextActions(context));
+    const actionsById = new Map(actions.map((action) => [action.id, action]));
+    const actionIds: readonly LayerContextActionId[] = [
+      'move-to-front',
+      'move-forward',
+      'move-backward',
+      'move-to-back',
+      'duplicate',
+      'rename',
+      'transform',
+      'fit-to-bbox',
+      'adjustments',
+      'save-to-assets',
+      'copy-to-clipboard',
+      'crop-to-bbox',
+      'extract-masked-area',
+      'filter',
+      'select-object',
+      'run-workflow',
+      'intersect',
+      'cutout',
+      'cutaway',
+      'exclude',
+      'copy-to-raster',
+      'copy-to-control',
+      'copy-to-inpaint-mask',
+      'copy-to-regional-guidance',
+      'rasterize',
+      'convert-to-control',
+      'convert-to-raster',
+      'convert-to-inpaint-mask',
+      'convert-to-regional-guidance',
+      'control-transparency-effect',
+      'regional-positive-prompt',
+      'regional-negative-prompt',
+      'regional-reference-image',
+      'regional-auto-negative',
+      'inpaint-noise',
+      'inpaint-denoise-limit',
+      'merge-down',
+      'toggle-visibility',
+      'toggle-lock',
+      'delete',
+    ];
+
+    expect(actionIds).toHaveLength(LAYER_CONTEXT_ACTION_DEFINITIONS.length);
+    expect(actionIds.filter((id) => !actionsById.has(id))).toEqual([]);
+    expect([...new Set(actions.filter((action) => !action.isDisabled).map((action) => action.id))]).toEqual([]);
+  });
+
+  it('still allows non-destructive copy and export from a locked layer when interaction is free', () => {
+    const actions = getLayerContextActions(makeState({ ...rasterLayer, isLocked: true }));
+    expect(byId(actions, 'copy-to-clipboard').isDisabled).toBe(false);
+    expect(byId(actions, 'save-to-assets').isDisabled).toBe(false);
+  });
+
+  it('disables locked-layer mutations but keeps toggle lock enabled', () => {
+    const lockedRaster = { ...rasterLayer, isLocked: true };
+    const below = paintLayer('below-locked-raster');
+    const actions = getLayerContextActions(makeState(lockedRaster, { document: makeDocument([lockedRaster, below]) }));
+
+    for (const id of [
+      'fit-to-bbox',
+      'adjustments',
+      'filter',
+      'select-object',
+      'run-workflow',
+      'crop-to-bbox',
+      'convert-to-control',
+      'intersect',
+      'merge-down',
+      'delete',
+    ] as const) {
+      expect(byId(actions, id).isDisabled, id).toBe(true);
+    }
+    expect(byId(actions, 'toggle-lock').isDisabled).toBe(false);
+
+    const lockedControl = { ...nonEmptyControlLayer, isLocked: true };
+    const controlActions = getLayerContextActions(makeState(lockedControl));
+    expect(byId(controlActions, 'filter').isDisabled).toBe(true);
+    expect(byId(controlActions, 'control-transparency-effect').isDisabled).toBe(true);
+    expect(byId(controlActions, 'convert-to-raster').isDisabled).toBe(true);
+
+    const lockedText = paintLayer('locked-text', {
+      isLocked: true,
+      source: {
+        align: 'left',
+        color: '#fff',
+        content: 'locked',
+        fontFamily: 'Inter',
+        fontSize: 32,
+        fontWeight: 400,
+        lineHeight: 1.2,
+        type: 'text',
+      },
+    });
+    expect(byId(getLayerContextActions(makeState(lockedText)), 'rasterize').isDisabled).toBe(true);
+  });
+
+  it('keeps boolean operations visible but disabled when an adjacent raster is locked', () => {
+    const upper = { ...paintLayer('locked-upper'), isLocked: true };
+    const below = paintLayer('below-locked-upper');
+    const actions = getLayerContextActions(makeState(upper, { document: makeDocument([upper, below]) }));
+
+    for (const id of ['intersect', 'cutout', 'cutaway', 'exclude'] as const) {
+      expect(byId(actions, id).isDisabled, id).toBe(true);
+    }
+  });
+
+  it('requires an engine and supported content for pixel actions', () => {
+    const noEngine = getLayerContextActions(makeState(rasterLayer, { hasEngine: false }));
+    const empty = getLayerContextActions(makeState(rasterLayer, { hasSupportedContent: false }));
+
+    for (const id of ['transform', 'filter', 'save-to-assets', 'copy-to-clipboard', 'crop-to-bbox'] as const) {
+      expect(byId(noEngine, id).isDisabled, id).toBe(true);
+    }
+    for (const id of ['save-to-assets', 'copy-to-clipboard', 'crop-to-bbox'] as const) {
+      expect(byId(empty, id).isDisabled, id).toBe(true);
+    }
+  });
+
+  it('does not offer fit for cache-only content whose bounds are not yet persisted', () => {
+    const cacheOnly = createEmptyPaintLayer('Cache only', 'cache-only');
+    const actions = getLayerContextActions(makeState(cacheOnly, { hasSupportedContent: true }));
+
+    expect(byId(actions, 'save-to-assets').isDisabled).toBe(false);
+    expect(byId(actions, 'fit-to-bbox').isDisabled).toBe(true);
+  });
+
+  it('keeps common actions available for a raster layer', () => {
+    expect(idsFor(rasterLayer)).toEqual(
+      expect.arrayContaining([
+        'move-to-front',
+        'duplicate',
+        'rename',
+        'transform',
+        'fit-to-bbox',
+        'adjustments',
+        'save-to-assets',
+        'copy-to-clipboard',
+        'crop-to-bbox',
+        'merge-down',
+        'delete',
+      ])
+    );
+  });
+
+  it('resolves movement boundaries within the layer type group', () => {
+    const first = paintLayer('first');
+    const middle = paintLayer('middle');
+    const last = paintLayer('last');
+    const document = makeDocument([first, middle, last]);
+
+    const firstActions = getLayerContextActions(makeState(first, { document }));
+    expect(byId(firstActions, 'move-to-front').isDisabled).toBe(true);
+    expect(byId(firstActions, 'move-forward').isDisabled).toBe(true);
+    expect(byId(firstActions, 'move-backward').isDisabled).toBe(false);
+    expect(byId(firstActions, 'move-to-back').isDisabled).toBe(false);
+
+    const middleActions = getLayerContextActions(makeState(middle, { document }));
+    expect(byId(middleActions, 'move-forward').isDisabled).toBe(false);
+    expect(byId(middleActions, 'move-backward').isDisabled).toBe(false);
+
+    const lastActions = getLayerContextActions(makeState(last, { document }));
+    expect(byId(lastActions, 'move-forward').isDisabled).toBe(false);
+    expect(byId(lastActions, 'move-backward').isDisabled).toBe(true);
+  });
+
+  it('exposes only pixel-backed raster to control conversion', () => {
+    const paint = paintLayer('paint');
+    const text = paintLayer('text', {
+      source: {
+        align: 'left',
+        color: '#fff',
+        content: 'hello',
+        fontFamily: 'Inter',
+        fontSize: 32,
+        fontWeight: 400,
+        lineHeight: 1.2,
+        type: 'text',
+      },
+    });
+
+    expect(idsFor(paint)).toEqual(
+      expect.arrayContaining([
+        'copy-to-control',
+        'copy-to-inpaint-mask',
+        'copy-to-regional-guidance',
+        'convert-to-control',
+        'convert-to-inpaint-mask',
+        'convert-to-regional-guidance',
+      ])
+    );
+    expect(idsFor(text)).not.toContain('convert-to-control');
+    expect(idsFor(text)).not.toContain('copy-to-inpaint-mask');
+  });
+
+  it('exposes control-only transparency and raster conversion actions while filtering supported control content', () => {
+    const empty = createControlLayer('Control', 'control-empty');
+
+    expect(idsFor(empty, [empty], { hasSupportedContent: false })).toEqual(
+      expect.arrayContaining([
+        'control-transparency-effect',
+        'convert-to-raster',
+        'copy-to-raster',
+        'copy-to-inpaint-mask',
+        'copy-to-regional-guidance',
+      ])
+    );
+    expect(idsFor(empty, [empty], { hasSupportedContent: false })).not.toContain('filter');
+    expect(idsFor(empty, [empty], { hasSupportedContent: true })).toContain('filter');
+    expect(idsFor(nonEmptyControlLayer)).toContain('filter');
+  });
+
+  it('exposes filter for every supported raster source', () => {
+    const layers: CanvasRasterLayerContractV2[] = [
+      paintLayer('filter-image', {
+        source: { image: { height: 10, imageName: 'filter-image', width: 10 }, type: 'image' },
+      }),
+      paintLayer('filter-paint'),
+      paintLayer('filter-text', {
+        source: {
+          align: 'left',
+          color: '#fff',
+          content: 'Filter me',
+          fontFamily: 'Inter',
+          fontSize: 32,
+          fontWeight: 400,
+          lineHeight: 1.2,
+          type: 'text',
+        },
+      }),
+      paintLayer('filter-gradient', {
+        source: {
+          angle: 45,
+          height: 20,
+          kind: 'linear',
+          stops: [
+            { color: '#000', offset: 0 },
+            { color: '#fff', offset: 1 },
+          ],
+          type: 'gradient',
+          width: 20,
+        },
+      }),
+      paintLayer('filter-rect', {
+        source: { fill: '#fff', height: 20, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 20 },
+      }),
+      paintLayer('filter-ellipse', {
+        source: {
+          fill: '#fff',
+          height: 20,
+          kind: 'ellipse',
+          stroke: null,
+          strokeWidth: 0,
+          type: 'shape',
+          width: 20,
+        },
+      }),
+    ];
+
+    for (const layer of layers) {
+      expect(idsFor(layer), layer.id).toContain('filter');
+    }
+  });
+
+  it('hides filter for empty paint and polygon raster sources', () => {
+    const empty = createEmptyPaintLayer('Empty', 'filter-empty');
+    const polygon = paintLayer('filter-polygon', {
+      source: {
+        fill: '#fff',
+        height: 20,
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 20, y: 0 },
+          { x: 10, y: 20 },
+        ],
+        stroke: null,
+        strokeWidth: 0,
+        type: 'shape',
+        width: 20,
+      },
+    });
+
+    expect(idsFor(empty, [empty], { hasSupportedContent: false })).not.toContain('filter');
+    expect(idsFor(polygon, [polygon], { hasSupportedContent: true })).not.toContain('filter');
+  });
+
+  it('enables raster filter only with an engine, unlocked layer, and unlocked interaction', () => {
+    const unlocked = paintLayer('filter-enabled');
+    expect(byId(getLayerContextActions(makeState(unlocked)), 'filter').isDisabled).toBe(false);
+    expect(byId(getLayerContextActions(makeState(unlocked, { hasEngine: false })), 'filter').isDisabled).toBe(true);
+    expect(byId(getLayerContextActions(makeState({ ...unlocked, isLocked: true })), 'filter').isDisabled).toBe(true);
+    expect(byId(getLayerContextActions(makeState(unlocked, { interactionLocked: true })), 'filter').isDisabled).toBe(
+      true
+    );
+  });
+
+  it('does not expose copy-to-raster for raster layers', () => {
+    expect(idsFor(rasterLayer)).not.toContain('copy-to-raster');
+  });
+
+  it('exposes regional guidance add actions only for missing prompts', () => {
+    const layer = { ...createRegionalGuidanceLayer('Region', 0, 'region-prompts'), positivePrompt: 'already' };
+
+    expect(idsFor(layer)).toContain('regional-negative-prompt');
+    expect(idsFor(layer)).toContain('regional-reference-image');
+    expect(idsFor(layer)).toContain('regional-auto-negative');
+    expect(idsFor(layer)).not.toContain('regional-positive-prompt');
+  });
+
+  it('exposes inpaint modifier add actions only for missing modifiers', () => {
+    const layer = { ...createInpaintMaskLayer('Mask', 'mask-modifiers'), noiseLevel: 0.25 };
+
+    expect(idsFor(layer)).toContain('inpaint-denoise-limit');
+    expect(idsFor(layer)).toContain('copy-to-regional-guidance');
+    expect(idsFor(layer)).toContain('extract-masked-area');
+    expect(idsFor(layer)).not.toContain('inpaint-noise');
+  });
+
+  it('copies regional guidance to an inpaint mask without unsupported conversions', () => {
+    const layer = createRegionalGuidanceLayer('Region', 0, 'region-copy');
+
+    expect(idsFor(layer)).toContain('copy-to-inpaint-mask');
+    expect(idsFor(layer)).not.toContain('convert-to-inpaint-mask');
+    expect(idsFor(layer)).not.toContain('copy-to-control');
+  });
+
+  it('exposes boolean raster actions only for an adjacent mergeable raster pair', () => {
+    const upper = paintLayer('upper');
+    const below = paintLayer('below');
+    const operations = ['intersect', 'cutout', 'cutaway', 'exclude'];
+
+    expect(idsFor(upper, [upper, below])).toEqual(expect.arrayContaining(operations));
+    expect(idsFor(below, [upper, below])).toEqual(expect.not.arrayContaining(operations));
+    expect(idsFor(upper, [upper, createInpaintMaskLayer('Mask', 'mask-below')])).toEqual(
+      expect.not.arrayContaining(operations)
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextActions.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextActions.ts
new file mode 100644
index 00000000000..9b42b7d5273
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextActions.ts
@@ -0,0 +1,788 @@
+import type { BooleanRasterOperation } from '@workbench/canvas-engine/engine';
+import type { CanvasDocumentContractV2, CanvasLayerContract } from '@workbench/types';
+import type { LucideIcon } from 'lucide-react';
+
+import { getSourceContentRect } from '@workbench/canvas-engine/document/sources';
+import {
+  ArrowDownIcon,
+  ArrowDownToLineIcon,
+  ArrowUpIcon,
+  ArrowUpToLineIcon,
+  CopyIcon,
+  CropIcon,
+  EyeIcon,
+  EyeOffIcon,
+  ImageIcon,
+  LockIcon,
+  LockOpenIcon,
+  MergeIcon,
+  PencilIcon,
+  SaveIcon,
+  ScanSearchIcon,
+  SlidersHorizontalIcon,
+  Trash2Icon,
+  WorkflowIcon,
+} from 'lucide-react';
+
+import type { LayerMoveKind } from './layerGroups';
+import type { LayerPropertiesSection } from './layerPropertiesRequestStore';
+
+import { getGroupPosition } from './layerGroups';
+import { canConvertRasterControl, canMergeLayerDown } from './layerOps';
+
+export type LayerContextActionId =
+  | 'move-to-front'
+  | 'move-forward'
+  | 'move-backward'
+  | 'move-to-back'
+  | 'duplicate'
+  | 'rename'
+  | 'transform'
+  | 'fit-to-bbox'
+  | 'adjustments'
+  | 'save-to-assets'
+  | 'copy-to-clipboard'
+  | 'crop-to-bbox'
+  | 'extract-masked-area'
+  | 'filter'
+  | 'select-object'
+  | 'run-workflow'
+  | 'intersect'
+  | 'cutout'
+  | 'cutaway'
+  | 'exclude'
+  | 'copy-to-raster'
+  | 'copy-to-control'
+  | 'copy-to-inpaint-mask'
+  | 'copy-to-regional-guidance'
+  | 'rasterize'
+  | 'convert-to-control'
+  | 'convert-to-raster'
+  | 'convert-to-inpaint-mask'
+  | 'convert-to-regional-guidance'
+  | 'control-transparency-effect'
+  | 'regional-positive-prompt'
+  | 'regional-negative-prompt'
+  | 'regional-reference-image'
+  | 'regional-auto-negative'
+  | 'inpaint-noise'
+  | 'inpaint-denoise-limit'
+  | 'merge-down'
+  | 'toggle-visibility'
+  | 'toggle-lock'
+  | 'delete';
+
+export type LayerType = CanvasLayerContract['type'];
+export type LayerContextMenuSectionId = 'quick' | 'primary' | 'operations' | 'output' | 'state' | 'danger';
+export type LayerContextSubmenuId = 'arrange' | 'add-modifiers' | 'add-regional' | 'boolean' | 'copy-to' | 'convert-to';
+
+export interface LayerContextActionState {
+  canRunWorkflow: boolean;
+  document: CanvasDocumentContractV2;
+  hasEngine: boolean;
+  hasSupportedContent: boolean;
+  hasWorkflowBindings: boolean;
+  index: number;
+  interactionLocked: boolean;
+  layer: CanvasLayerContract;
+}
+
+export interface LayerContextActionEffects {
+  reorder(kind: LayerMoveKind, actionId: LayerContextActionId): void;
+  duplicate(): void;
+  openRename(): void;
+  openRunWorkflow(): void;
+  startSelectObject(layerId: string): void;
+  startFilter(layerId: string): void;
+  transform(): void;
+  fitToBbox(): void;
+  openProperties(section: LayerPropertiesSection): void;
+  saveToAssets(): Promise<void>;
+  copyToClipboard(): Promise<void>;
+  cropToBbox(): Promise<void>;
+  extractMaskedArea(): Promise<void>;
+  booleanMerge(operation: BooleanRasterOperation): Promise<void>;
+  copyTo(target: LayerType): void | Promise<void>;
+  rasterize(): void;
+  convertTo(target: LayerType): void;
+  patchConfig(kind: LayerConfigPatchKind): void;
+  mergeDown(): void;
+  toggleVisibility(): void;
+  toggleLock(): void;
+  delete(): void;
+}
+
+export interface LayerContextActionRuntimeContext extends LayerContextActionState {
+  effects: LayerContextActionEffects;
+}
+
+export interface LayerContextActionDefinition {
+  id: LayerContextActionId;
+  labelKey: string;
+  defaultLabel: string;
+  icon: LucideIcon;
+  getIcon?(context: LayerContextActionState): LucideIcon;
+  section: LayerContextMenuSectionId;
+  submenu?: LayerContextSubmenuId;
+  order: number;
+  supportedLayerTypes: readonly LayerType[];
+  tone?: 'danger';
+  isVisible(context: LayerContextActionState): boolean;
+  isEnabled(context: LayerContextActionState): boolean;
+  handler(context: LayerContextActionRuntimeContext): void | Promise<void>;
+  getDefaultLabel?(context: LayerContextActionState): string;
+  getLabelKey?(context: LayerContextActionState): string;
+}
+
+export interface LayerContextAction {
+  id: LayerContextActionId;
+  labelKey: string;
+  defaultLabel: string;
+  icon: LucideIcon;
+  section: LayerContextMenuSectionId;
+  submenu?: LayerContextSubmenuId;
+  order: number;
+  tone?: 'danger';
+  isDisabled: boolean;
+  handler(context: LayerContextActionRuntimeContext): void | Promise<void>;
+}
+
+export type LayerConfigPatchKind =
+  | 'control-transparency-effect'
+  | 'regional-positive-prompt'
+  | 'regional-negative-prompt'
+  | 'regional-reference-image'
+  | 'regional-auto-negative'
+  | 'inpaint-noise'
+  | 'inpaint-denoise-limit';
+
+const ALL_LAYER_TYPES = ['raster', 'control', 'inpaint_mask', 'regional_guidance'] as const;
+const RASTER_ONLY = ['raster'] as const;
+const CONTROL_ONLY = ['control'] as const;
+const RASTER_AND_CONTROL = ['raster', 'control'] as const;
+const INPAINT_ONLY = ['inpaint_mask'] as const;
+const REGIONAL_ONLY = ['regional_guidance'] as const;
+
+const alwaysVisible = (): boolean => true;
+const isInteractionFree = (context: LayerContextActionState): boolean => !context.interactionLocked;
+const isLayerMutable = (context: LayerContextActionState): boolean =>
+  isInteractionFree(context) && !context.layer.isLocked;
+const hasReadablePixels = (context: LayerContextActionState): boolean =>
+  context.hasEngine && context.hasSupportedContent && !context.interactionLocked;
+const hasMutablePixels = (context: LayerContextActionState): boolean =>
+  isLayerMutable(context) && hasReadablePixels(context);
+const hasTransformablePixels = (context: LayerContextActionState): boolean =>
+  context.layer.isEnabled && hasMutablePixels(context);
+const hasDocumentContent = (context: LayerContextActionState): boolean => {
+  const contentRect = getSourceContentRect(context.layer, context.document);
+  return contentRect.width > 0 && contentRect.height > 0;
+};
+
+const isParametricRasterizable = (layer: CanvasLayerContract): boolean =>
+  layer.type === 'raster' &&
+  (layer.source.type === 'gradient' ||
+    layer.source.type === 'text' ||
+    (layer.source.type === 'shape' && layer.source.kind !== 'polygon'));
+
+const isPixelBacked = (layer: CanvasLayerContract): boolean =>
+  (layer.type === 'raster' || layer.type === 'control') &&
+  (layer.source.type === 'image' || layer.source.type === 'paint');
+
+const hasFilterableLayerContent = (context: LayerContextActionState): boolean => {
+  if (!context.hasSupportedContent || (context.layer.type !== 'raster' && context.layer.type !== 'control')) {
+    return false;
+  }
+  const { source } = context.layer;
+  if (source.type === 'image' || source.type === 'paint') {
+    // `hasSupportedContent` distinguishes empty paint from live unpersisted
+    // cache pixels, which are intentionally filterable despite `bitmap: null`.
+    return true;
+  }
+  if (context.layer.type !== 'raster') {
+    return false;
+  }
+  return (
+    source.type === 'text' ||
+    source.type === 'gradient' ||
+    (source.type === 'shape' && (source.kind === 'rect' || source.kind === 'ellipse'))
+  );
+};
+
+const groupPosition = (context: LayerContextActionState) => getGroupPosition(context.document.layers, context.layer.id);
+
+const canMoveForward = (context: LayerContextActionState): boolean => {
+  const position = groupPosition(context);
+  return isInteractionFree(context) && !!position && position.index > 0;
+};
+
+const canMoveBackward = (context: LayerContextActionState): boolean => {
+  const position = groupPosition(context);
+  return isInteractionFree(context) && !!position && position.index < position.count - 1;
+};
+
+const hasMergeableLayerBelow = (context: LayerContextActionState): boolean =>
+  canMergeLayerDown(context.document.layers, context.index, true);
+
+const isBooleanRasterLayer = (layer: CanvasLayerContract | undefined): boolean =>
+  !!layer &&
+  layer.isEnabled &&
+  layer.type === 'raster' &&
+  (layer.source.type === 'paint' || layer.source.type === 'image');
+
+const hasBooleanRasterPair = (context: LayerContextActionState): boolean =>
+  isBooleanRasterLayer(context.document.layers[context.index]) &&
+  isBooleanRasterLayer(context.document.layers[context.index + 1]);
+
+export const LAYER_CONTEXT_ACTION_DEFINITIONS: readonly LayerContextActionDefinition[] = [
+  {
+    defaultLabel: 'Move to front',
+    handler: ({ effects }) => effects.reorder('front', 'move-to-front'),
+    icon: ArrowUpToLineIcon,
+    id: 'move-to-front',
+    isEnabled: canMoveForward,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.moveToFront',
+    order: 0,
+    section: 'quick',
+    submenu: 'arrange',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Move forward',
+    handler: ({ effects }) => effects.reorder('forward', 'move-forward'),
+    icon: ArrowUpIcon,
+    id: 'move-forward',
+    isEnabled: canMoveForward,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.moveForward',
+    order: 1,
+    section: 'quick',
+    submenu: 'arrange',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Move backward',
+    handler: ({ effects }) => effects.reorder('backward', 'move-backward'),
+    icon: ArrowDownIcon,
+    id: 'move-backward',
+    isEnabled: canMoveBackward,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.moveBackward',
+    order: 2,
+    section: 'quick',
+    submenu: 'arrange',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Move to back',
+    handler: ({ effects }) => effects.reorder('back', 'move-to-back'),
+    icon: ArrowDownToLineIcon,
+    id: 'move-to-back',
+    isEnabled: canMoveBackward,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.moveToBack',
+    order: 3,
+    section: 'quick',
+    submenu: 'arrange',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Duplicate',
+    handler: ({ effects }) => effects.duplicate(),
+    icon: CopyIcon,
+    id: 'duplicate',
+    isEnabled: isInteractionFree,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.duplicate',
+    order: 10,
+    section: 'quick',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Add image noise',
+    handler: ({ effects }) => effects.patchConfig('inpaint-noise'),
+    icon: SlidersHorizontalIcon,
+    id: 'inpaint-noise',
+    isEnabled: isLayerMutable,
+    isVisible: (context) => context.layer.type === 'inpaint_mask' && context.layer.noiseLevel === undefined,
+    labelKey: 'widgets.layers.actions.addImageNoise',
+    order: 0,
+    section: 'primary',
+    submenu: 'add-modifiers',
+    supportedLayerTypes: INPAINT_ONLY,
+  },
+  {
+    defaultLabel: 'Add denoise limit',
+    handler: ({ effects }) => effects.patchConfig('inpaint-denoise-limit'),
+    icon: SlidersHorizontalIcon,
+    id: 'inpaint-denoise-limit',
+    isEnabled: isLayerMutable,
+    isVisible: (context) => context.layer.type === 'inpaint_mask' && context.layer.denoiseLimit === undefined,
+    labelKey: 'widgets.layers.actions.addDenoiseLimit',
+    order: 1,
+    section: 'primary',
+    submenu: 'add-modifiers',
+    supportedLayerTypes: INPAINT_ONLY,
+  },
+  {
+    defaultLabel: 'Add positive prompt',
+    handler: ({ effects }) => effects.patchConfig('regional-positive-prompt'),
+    icon: PencilIcon,
+    id: 'regional-positive-prompt',
+    isEnabled: isLayerMutable,
+    isVisible: (context) => context.layer.type === 'regional_guidance' && context.layer.positivePrompt === null,
+    labelKey: 'widgets.layers.actions.addPositivePrompt',
+    order: 0,
+    section: 'primary',
+    submenu: 'add-regional',
+    supportedLayerTypes: REGIONAL_ONLY,
+  },
+  {
+    defaultLabel: 'Add negative prompt',
+    handler: ({ effects }) => effects.patchConfig('regional-negative-prompt'),
+    icon: PencilIcon,
+    id: 'regional-negative-prompt',
+    isEnabled: isLayerMutable,
+    isVisible: (context) => context.layer.type === 'regional_guidance' && context.layer.negativePrompt === null,
+    labelKey: 'widgets.layers.actions.addNegativePrompt',
+    order: 1,
+    section: 'primary',
+    submenu: 'add-regional',
+    supportedLayerTypes: REGIONAL_ONLY,
+  },
+  {
+    defaultLabel: 'Add reference image',
+    handler: ({ effects }) => effects.patchConfig('regional-reference-image'),
+    icon: ImageIcon,
+    id: 'regional-reference-image',
+    isEnabled: isLayerMutable,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.addReferenceImage',
+    order: 2,
+    section: 'primary',
+    submenu: 'add-regional',
+    supportedLayerTypes: REGIONAL_ONLY,
+  },
+  {
+    defaultLabel: 'Transform',
+    handler: ({ effects }) => effects.transform(),
+    icon: SlidersHorizontalIcon,
+    id: 'transform',
+    isEnabled: hasTransformablePixels,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.transform',
+    order: 10,
+    section: 'primary',
+    supportedLayerTypes: ['raster', 'control'],
+  },
+  {
+    defaultLabel: 'Rename',
+    handler: ({ effects }) => effects.openRename(),
+    icon: PencilIcon,
+    id: 'rename',
+    isEnabled: isInteractionFree,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.rename',
+    order: 20,
+    section: 'primary',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Fit to bbox',
+    handler: ({ effects }) => effects.fitToBbox(),
+    icon: ImageIcon,
+    id: 'fit-to-bbox',
+    isEnabled: (context) => hasDocumentContent(context) && isLayerMutable(context),
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.fitToBbox',
+    order: 30,
+    section: 'primary',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Adjustments',
+    handler: ({ effects }) => effects.openProperties('adjustments'),
+    icon: SlidersHorizontalIcon,
+    id: 'adjustments',
+    isEnabled: hasMutablePixels,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.adjustments',
+    order: 31,
+    section: 'primary',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Filter',
+    handler: ({ effects, layer }) => effects.startFilter(layer.id),
+    icon: SlidersHorizontalIcon,
+    id: 'filter',
+    isEnabled: hasMutablePixels,
+    isVisible: hasFilterableLayerContent,
+    labelKey: 'widgets.layers.control.filter',
+    order: 40,
+    section: 'primary',
+    supportedLayerTypes: RASTER_AND_CONTROL,
+  },
+  {
+    defaultLabel: 'Select object',
+    handler: ({ effects, layer }) => effects.startSelectObject(layer.id),
+    icon: ScanSearchIcon,
+    id: 'select-object',
+    isEnabled: hasMutablePixels,
+    isVisible: hasFilterableLayerContent,
+    labelKey: 'widgets.layers.actions.selectObject',
+    order: 41,
+    section: 'primary',
+    supportedLayerTypes: RASTER_AND_CONTROL,
+  },
+  {
+    defaultLabel: 'Run workflow',
+    handler: ({ effects }) => effects.openRunWorkflow(),
+    icon: WorkflowIcon,
+    id: 'run-workflow',
+    isEnabled: (context) => context.canRunWorkflow && hasMutablePixels(context),
+    isVisible: (context) => context.hasWorkflowBindings && context.hasSupportedContent,
+    labelKey: 'widgets.layers.actions.runWorkflow',
+    order: 42,
+    section: 'primary',
+    supportedLayerTypes: RASTER_AND_CONTROL,
+  },
+  {
+    defaultLabel: 'Toggle transparency effect',
+    getDefaultLabel: (context) =>
+      context.layer.type === 'control' && context.layer.withTransparencyEffect
+        ? 'Disable transparency effect'
+        : 'Enable transparency effect',
+    getLabelKey: (context) =>
+      context.layer.type === 'control' && context.layer.withTransparencyEffect
+        ? 'widgets.layers.actions.disableTransparencyEffect'
+        : 'widgets.layers.actions.enableTransparencyEffect',
+    handler: ({ effects }) => effects.patchConfig('control-transparency-effect'),
+    icon: SlidersHorizontalIcon,
+    id: 'control-transparency-effect',
+    isEnabled: isLayerMutable,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.toggleTransparencyEffect',
+    order: 50,
+    section: 'primary',
+    supportedLayerTypes: CONTROL_ONLY,
+  },
+  {
+    defaultLabel: 'Toggle auto-negative',
+    getDefaultLabel: (context) =>
+      context.layer.type === 'regional_guidance' && context.layer.autoNegative
+        ? 'Disable auto-negative'
+        : 'Enable auto-negative',
+    getLabelKey: (context) =>
+      context.layer.type === 'regional_guidance' && context.layer.autoNegative
+        ? 'widgets.layers.actions.disableAutoNegative'
+        : 'widgets.layers.actions.enableAutoNegative',
+    handler: ({ effects }) => effects.patchConfig('regional-auto-negative'),
+    icon: SlidersHorizontalIcon,
+    id: 'regional-auto-negative',
+    isEnabled: isLayerMutable,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.toggleAutoNegative',
+    order: 50,
+    section: 'primary',
+    supportedLayerTypes: REGIONAL_ONLY,
+  },
+  {
+    defaultLabel: 'Extract masked area',
+    handler: ({ effects }) => effects.extractMaskedArea(),
+    icon: CropIcon,
+    id: 'extract-masked-area',
+    isEnabled: hasMutablePixels,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.extractMaskedArea',
+    order: 60,
+    section: 'primary',
+    supportedLayerTypes: INPAINT_ONLY,
+  },
+  {
+    defaultLabel: 'Merge down',
+    handler: ({ effects }) => effects.mergeDown(),
+    icon: MergeIcon,
+    id: 'merge-down',
+    isEnabled: (context) => hasMutablePixels(context) && hasMergeableLayerBelow(context),
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.mergeDown',
+    order: 0,
+    section: 'operations',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Intersect with layer below',
+    handler: ({ effects }) => effects.booleanMerge('intersect'),
+    icon: MergeIcon,
+    id: 'intersect',
+    isEnabled: (context) => hasMutablePixels(context) && hasMergeableLayerBelow(context),
+    isVisible: hasBooleanRasterPair,
+    labelKey: 'widgets.layers.actions.intersect',
+    order: 10,
+    section: 'operations',
+    submenu: 'boolean',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Cutout with layer below',
+    handler: ({ effects }) => effects.booleanMerge('cutout'),
+    icon: MergeIcon,
+    id: 'cutout',
+    isEnabled: (context) => hasMutablePixels(context) && hasMergeableLayerBelow(context),
+    isVisible: hasBooleanRasterPair,
+    labelKey: 'widgets.layers.actions.cutout',
+    order: 11,
+    section: 'operations',
+    submenu: 'boolean',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Cutaway with layer below',
+    handler: ({ effects }) => effects.booleanMerge('cutaway'),
+    icon: MergeIcon,
+    id: 'cutaway',
+    isEnabled: (context) => hasMutablePixels(context) && hasMergeableLayerBelow(context),
+    isVisible: hasBooleanRasterPair,
+    labelKey: 'widgets.layers.actions.cutaway',
+    order: 12,
+    section: 'operations',
+    submenu: 'boolean',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Exclude layer below',
+    handler: ({ effects }) => effects.booleanMerge('exclude'),
+    icon: MergeIcon,
+    id: 'exclude',
+    isEnabled: (context) => hasMutablePixels(context) && hasMergeableLayerBelow(context),
+    isVisible: hasBooleanRasterPair,
+    labelKey: 'widgets.layers.actions.exclude',
+    order: 13,
+    section: 'operations',
+    submenu: 'boolean',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Copy layer to clipboard',
+    handler: ({ effects }) => effects.copyToClipboard(),
+    icon: CopyIcon,
+    id: 'copy-to-clipboard',
+    isEnabled: hasReadablePixels,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.copyLayerToClipboard',
+    order: 20,
+    section: 'operations',
+    submenu: 'copy-to',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Copy to raster layer',
+    handler: ({ effects }) => effects.copyTo('raster'),
+    icon: CopyIcon,
+    id: 'copy-to-raster',
+    isEnabled: hasReadablePixels,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.copyToRasterLayer',
+    order: 21,
+    section: 'operations',
+    submenu: 'copy-to',
+    supportedLayerTypes: ['control', 'inpaint_mask', 'regional_guidance'],
+  },
+  {
+    defaultLabel: 'Copy to control layer',
+    handler: ({ effects }) => effects.copyTo('control'),
+    icon: CopyIcon,
+    id: 'copy-to-control',
+    isEnabled: hasReadablePixels,
+    isVisible: (context) => isPixelBacked(context.layer),
+    labelKey: 'widgets.layers.actions.copyToControl',
+    order: 22,
+    section: 'operations',
+    submenu: 'copy-to',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Copy to inpaint mask',
+    handler: ({ effects }) => effects.copyTo('inpaint_mask'),
+    icon: CopyIcon,
+    id: 'copy-to-inpaint-mask',
+    isEnabled: hasReadablePixels,
+    isVisible: (context) => isPixelBacked(context.layer) || context.layer.type === 'regional_guidance',
+    labelKey: 'widgets.layers.actions.copyToInpaintMask',
+    order: 23,
+    section: 'operations',
+    submenu: 'copy-to',
+    supportedLayerTypes: ['raster', 'control', 'regional_guidance'],
+  },
+  {
+    defaultLabel: 'Copy to regional guidance',
+    handler: ({ effects }) => effects.copyTo('regional_guidance'),
+    icon: CopyIcon,
+    id: 'copy-to-regional-guidance',
+    isEnabled: hasReadablePixels,
+    isVisible: (context) => isPixelBacked(context.layer) || context.layer.type === 'inpaint_mask',
+    labelKey: 'widgets.layers.actions.copyToRegionalGuidance',
+    order: 24,
+    section: 'operations',
+    submenu: 'copy-to',
+    supportedLayerTypes: ['raster', 'control', 'inpaint_mask'],
+  },
+  {
+    defaultLabel: 'Rasterize',
+    handler: ({ effects }) => effects.rasterize(),
+    icon: ImageIcon,
+    id: 'rasterize',
+    isEnabled: hasMutablePixels,
+    isVisible: (context) => isParametricRasterizable(context.layer),
+    labelKey: 'widgets.layers.actions.rasterize',
+    order: 30,
+    section: 'operations',
+    submenu: 'convert-to',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Convert to Control Layer',
+    handler: ({ effects }) => effects.convertTo('control'),
+    icon: SlidersHorizontalIcon,
+    id: 'convert-to-control',
+    isEnabled: isLayerMutable,
+    isVisible: (context) => canConvertRasterControl(context.layer),
+    labelKey: 'widgets.layers.actions.convertToControl',
+    order: 31,
+    section: 'operations',
+    submenu: 'convert-to',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Convert to Raster Layer',
+    handler: ({ effects }) => effects.convertTo('raster'),
+    icon: ImageIcon,
+    id: 'convert-to-raster',
+    isEnabled: isLayerMutable,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.convertToRaster',
+    order: 32,
+    section: 'operations',
+    submenu: 'convert-to',
+    supportedLayerTypes: CONTROL_ONLY,
+  },
+  {
+    defaultLabel: 'Convert to inpaint mask',
+    handler: ({ effects }) => effects.convertTo('inpaint_mask'),
+    icon: ImageIcon,
+    id: 'convert-to-inpaint-mask',
+    isEnabled: isLayerMutable,
+    isVisible: (context) => isPixelBacked(context.layer),
+    labelKey: 'widgets.layers.actions.convertToInpaintMask',
+    order: 33,
+    section: 'operations',
+    submenu: 'convert-to',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Convert to regional guidance',
+    handler: ({ effects }) => effects.convertTo('regional_guidance'),
+    icon: ImageIcon,
+    id: 'convert-to-regional-guidance',
+    isEnabled: isLayerMutable,
+    isVisible: (context) => isPixelBacked(context.layer),
+    labelKey: 'widgets.layers.actions.convertToRegionalGuidance',
+    order: 34,
+    section: 'operations',
+    submenu: 'convert-to',
+    supportedLayerTypes: RASTER_ONLY,
+  },
+  {
+    defaultLabel: 'Crop layer to bbox',
+    handler: ({ effects }) => effects.cropToBbox(),
+    icon: CropIcon,
+    id: 'crop-to-bbox',
+    isEnabled: hasMutablePixels,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.cropLayerToBbox',
+    order: 0,
+    section: 'output',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Save layer to assets',
+    handler: ({ effects }) => effects.saveToAssets(),
+    icon: SaveIcon,
+    id: 'save-to-assets',
+    isEnabled: hasReadablePixels,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.saveLayerToAssets',
+    order: 10,
+    section: 'output',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Toggle visibility',
+    getDefaultLabel: (context) => (context.layer.isEnabled ? 'Hide' : 'Show'),
+    getIcon: (context) => (context.layer.isEnabled ? EyeOffIcon : EyeIcon),
+    getLabelKey: (context) => (context.layer.isEnabled ? 'widgets.layers.actions.hide' : 'widgets.layers.actions.show'),
+    handler: ({ effects }) => effects.toggleVisibility(),
+    icon: EyeIcon,
+    id: 'toggle-visibility',
+    isEnabled: isInteractionFree,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.toggleVisibility',
+    order: 0,
+    section: 'state',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Toggle lock',
+    getDefaultLabel: (context) => (context.layer.isLocked ? 'Unlock' : 'Lock'),
+    getIcon: (context) => (context.layer.isLocked ? LockOpenIcon : LockIcon),
+    getLabelKey: (context) =>
+      context.layer.isLocked ? 'widgets.layers.actions.unlock' : 'widgets.layers.actions.lock',
+    handler: ({ effects }) => effects.toggleLock(),
+    icon: LockIcon,
+    id: 'toggle-lock',
+    isEnabled: isInteractionFree,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.toggleLock',
+    order: 10,
+    section: 'state',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+  },
+  {
+    defaultLabel: 'Delete',
+    handler: ({ effects }) => effects.delete(),
+    icon: Trash2Icon,
+    id: 'delete',
+    isEnabled: isLayerMutable,
+    isVisible: alwaysVisible,
+    labelKey: 'widgets.layers.actions.delete',
+    order: 0,
+    section: 'danger',
+    supportedLayerTypes: ALL_LAYER_TYPES,
+    tone: 'danger',
+  },
+];
+
+export const getLayerContextActionDefinition = (id: LayerContextActionId): LayerContextActionDefinition => {
+  const definition = LAYER_CONTEXT_ACTION_DEFINITIONS.find((candidate) => candidate.id === id);
+  if (!definition) {
+    throw new Error(`Unknown layer context action: ${id}`);
+  }
+  return definition;
+};
+
+export const getLayerContextActions = (context: LayerContextActionState): LayerContextAction[] =>
+  LAYER_CONTEXT_ACTION_DEFINITIONS.filter(
+    (definition) => definition.supportedLayerTypes.includes(context.layer.type) && definition.isVisible(context)
+  ).map((definition) => ({
+    defaultLabel: definition.getDefaultLabel?.(context) ?? definition.defaultLabel,
+    handler: definition.handler,
+    icon: definition.getIcon?.(context) ?? definition.icon,
+    id: definition.id,
+    isDisabled: !definition.isEnabled(context),
+    labelKey: definition.getLabelKey?.(context) ?? definition.labelKey,
+    order: definition.order,
+    section: definition.section,
+    submenu: definition.submenu,
+    tone: definition.tone,
+  }));
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextMenuLayout.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextMenuLayout.test.ts
new file mode 100644
index 00000000000..b9ea945dfc7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextMenuLayout.test.ts
@@ -0,0 +1,186 @@
+import type { CanvasDocumentContractV2, CanvasLayerContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { getLayerContextActions } from './layerContextActions';
+import {
+  getLayerContextMenuLayerLabelKey,
+  getLayerContextMenuLayout,
+  getLayerContextMenuRenderEntries,
+  type LayerContextMenuSection,
+} from './layerContextMenuLayout';
+import {
+  createControlLayer,
+  createEmptyPaintLayer,
+  createInpaintMaskLayer,
+  createRegionalGuidanceLayer,
+} from './layerOps';
+
+const paintLayer = (id: string, patch: Partial<CanvasRasterLayerContractV2> = {}): CanvasLayerContract => ({
+  ...createEmptyPaintLayer(id, id),
+  source: { bitmap: { height: 10, imageName: `${id}.png`, width: 10 }, type: 'paint' },
+  ...patch,
+});
+
+const makeDocument = (layers: CanvasLayerContract[]): CanvasDocumentContractV2 => ({
+  background: 'transparent',
+  bbox: { height: 512, width: 512, x: 0, y: 0 },
+  height: 512,
+  layers,
+  selectedLayerId: layers[0]?.id ?? null,
+  version: 2,
+  width: 512,
+});
+
+const actionsFor = (layer: CanvasLayerContract, layers: readonly CanvasLayerContract[] = [layer]) =>
+  getLayerContextActions({
+    canRunWorkflow: true,
+    document: makeDocument([...layers]),
+    hasEngine: true,
+    hasSupportedContent: true,
+    hasWorkflowBindings: true,
+    index: layers.indexOf(layer),
+    interactionLocked: false,
+    layer,
+  });
+
+const layoutFor = (layer: CanvasLayerContract, layers: readonly CanvasLayerContract[] = [layer]) =>
+  getLayerContextMenuLayout(actionsFor(layer, layers));
+
+const summarizeLayout = (layout: readonly LayerContextMenuSection[]) =>
+  layout.map((section) => ({
+    id: section.id,
+    items: section.items.map((item) =>
+      item.kind === 'action' ? item.action.id : `${item.id}(${item.actions.map((action) => action.id).join(',')})`
+    ),
+    presentation: section.presentation,
+  }));
+
+const summarize = (layer: CanvasLayerContract, layers: readonly CanvasLayerContract[] = [layer]) =>
+  summarizeLayout(layoutFor(layer, layers));
+
+describe('getLayerContextMenuLayout', () => {
+  it('organizes raster actions like the legacy menu and keeps delete last', () => {
+    const upper = paintLayer('upper');
+    const below = paintLayer('below');
+
+    expect(summarize(upper, [upper, below])).toEqual([
+      {
+        id: 'quick',
+        items: ['arrange(move-to-front,move-forward,move-backward,move-to-back)', 'duplicate'],
+        presentation: 'row',
+      },
+      {
+        id: 'primary',
+        items: ['transform', 'rename', 'fit-to-bbox', 'adjustments', 'filter', 'select-object', 'run-workflow'],
+        presentation: 'list',
+      },
+      {
+        id: 'operations',
+        items: [
+          'merge-down',
+          'boolean(intersect,cutout,cutaway,exclude)',
+          'copy-to(copy-to-clipboard,copy-to-control,copy-to-inpaint-mask,copy-to-regional-guidance)',
+          'convert-to(convert-to-control,convert-to-inpaint-mask,convert-to-regional-guidance)',
+        ],
+        presentation: 'list',
+      },
+      { id: 'output', items: ['crop-to-bbox', 'save-to-assets'], presentation: 'list' },
+      { id: 'state', items: ['toggle-visibility', 'toggle-lock'], presentation: 'list' },
+      { id: 'danger', items: ['delete'], presentation: 'list' },
+    ]);
+  });
+
+  it('groups inpaint modifiers and regional additions into type-specific submenus', () => {
+    const inpaint = createInpaintMaskLayer('Mask', 'mask');
+    const regional = createRegionalGuidanceLayer('Region', 0, 'region');
+
+    expect(summarize(inpaint)[1]).toEqual({
+      id: 'primary',
+      items: ['add-modifiers(inpaint-noise,inpaint-denoise-limit)', 'rename', 'fit-to-bbox', 'extract-masked-area'],
+      presentation: 'list',
+    });
+    expect(summarize(regional)[1]).toEqual({
+      id: 'primary',
+      items: [
+        'add-regional(regional-positive-prompt,regional-negative-prompt,regional-reference-image)',
+        'rename',
+        'fit-to-bbox',
+        'regional-auto-negative',
+      ],
+      presentation: 'list',
+    });
+  });
+
+  it('places control filter and transparency actions before conversion operations', () => {
+    const control = {
+      ...createControlLayer('Control', 'control'),
+      source: { image: { height: 10, imageName: 'control-image', width: 10 }, type: 'image' as const },
+    };
+
+    expect(summarize(control)[1]).toEqual({
+      id: 'primary',
+      items: [
+        'transform',
+        'rename',
+        'fit-to-bbox',
+        'filter',
+        'select-object',
+        'run-workflow',
+        'control-transparency-effect',
+      ],
+      presentation: 'list',
+    });
+    expect(summarize(control)[2]).toEqual({
+      id: 'operations',
+      items: [
+        'merge-down',
+        'copy-to(copy-to-clipboard,copy-to-raster,copy-to-inpaint-mask,copy-to-regional-guidance)',
+        'convert-to(convert-to-raster)',
+      ],
+      presentation: 'list',
+    });
+  });
+
+  it('derives the same hierarchy when the input registry order is shuffled', () => {
+    const upper = paintLayer('upper-shuffled');
+    const below = paintLayer('below-shuffled');
+    const actions = actionsFor(upper, [upper, below]);
+    const reversed = [...actions].reverse();
+
+    expect(summarizeLayout(getLayerContextMenuLayout(reversed))).toEqual(
+      summarizeLayout(getLayerContextMenuLayout(actions))
+    );
+  });
+
+  it('inserts optional canvas items immediately before the terminal danger section', () => {
+    const upper = paintLayer('upper-with-canvas-items');
+    const below = paintLayer('below-with-canvas-items');
+    const layout = layoutFor(upper, [upper, below]);
+
+    const summarizeEntries = (includeBeforeDangerSlot: boolean) =>
+      getLayerContextMenuRenderEntries(layout, includeBeforeDangerSlot).map((entry) =>
+        entry.kind === 'slot' ? entry.id : entry.section.id
+      );
+
+    expect(summarizeEntries(true)).toEqual([
+      'quick',
+      'primary',
+      'operations',
+      'output',
+      'state',
+      'before-danger',
+      'danger',
+    ]);
+    expect(summarizeEntries(false)).toEqual(['quick', 'primary', 'operations', 'output', 'state', 'danger']);
+  });
+
+  it.each([
+    ['raster', 'widgets.canvas.import.raster'],
+    ['control', 'widgets.canvas.import.control'],
+    ['inpaint_mask', 'widgets.canvas.import.inpaintMask'],
+    ['regional_guidance', 'widgets.canvas.import.regionalGuidance'],
+  ] as const)('uses the legacy singular label for %s layer menus', (type, expected) => {
+    expect(getLayerContextMenuLayerLabelKey(type)).toBe(expected);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextMenuLayout.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextMenuLayout.ts
new file mode 100644
index 00000000000..da77195d7d8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerContextMenuLayout.ts
@@ -0,0 +1,113 @@
+import type {
+  LayerContextAction,
+  LayerContextMenuSectionId,
+  LayerContextSubmenuId,
+  LayerType,
+} from './layerContextActions';
+
+export type { LayerContextSubmenuId } from './layerContextActions';
+
+export type LayerContextMenuItem =
+  | { action: LayerContextAction; kind: 'action' }
+  | { actions: readonly LayerContextAction[]; id: LayerContextSubmenuId; kind: 'submenu' };
+
+export interface LayerContextMenuSection {
+  id: LayerContextMenuSectionId;
+  items: readonly LayerContextMenuItem[];
+  presentation: 'row' | 'list';
+}
+
+export type LayerContextMenuRenderEntry =
+  | { id: 'before-danger'; kind: 'slot' }
+  | { kind: 'section'; section: LayerContextMenuSection };
+
+type LayerContextMenuLayerLabelKey =
+  | 'widgets.canvas.import.control'
+  | 'widgets.canvas.import.inpaintMask'
+  | 'widgets.canvas.import.raster'
+  | 'widgets.canvas.import.regionalGuidance';
+
+const SECTION_LAYOUT: readonly {
+  id: LayerContextMenuSectionId;
+  order: number;
+  presentation: 'row' | 'list';
+}[] = [
+  { id: 'quick', order: 0, presentation: 'row' },
+  { id: 'primary', order: 1, presentation: 'list' },
+  { id: 'operations', order: 2, presentation: 'list' },
+  { id: 'output', order: 3, presentation: 'list' },
+  { id: 'state', order: 4, presentation: 'list' },
+  { id: 'danger', order: 5, presentation: 'list' },
+];
+
+const sortActions = (actions: readonly LayerContextAction[]): LayerContextAction[] =>
+  [...actions].sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+
+interface OrderedMenuItem {
+  id: string;
+  item: LayerContextMenuItem;
+  order: number;
+}
+
+const buildSectionItems = (actions: readonly LayerContextAction[]): LayerContextMenuItem[] => {
+  const ordered: OrderedMenuItem[] = [];
+  const submenus = new Map<LayerContextSubmenuId, LayerContextAction[]>();
+
+  for (const action of actions) {
+    if (!action.submenu) {
+      ordered.push({ id: action.id, item: { action, kind: 'action' }, order: action.order });
+      continue;
+    }
+    const submenuActions = submenus.get(action.submenu) ?? [];
+    submenuActions.push(action);
+    submenus.set(action.submenu, submenuActions);
+  }
+
+  for (const [id, submenuActions] of submenus) {
+    const sorted = sortActions(submenuActions);
+    ordered.push({
+      id,
+      item: { actions: sorted, id, kind: 'submenu' },
+      order: sorted[0]?.order ?? Number.POSITIVE_INFINITY,
+    });
+  }
+
+  return ordered.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)).map(({ item }) => item);
+};
+
+/** Builds the layer-menu hierarchy exclusively from executable registry metadata. */
+export const getLayerContextMenuLayout = (actions: readonly LayerContextAction[]): LayerContextMenuSection[] =>
+  [...SECTION_LAYOUT]
+    .sort((a, b) => a.order - b.order)
+    .flatMap((section): LayerContextMenuSection[] => {
+      const items = buildSectionItems(actions.filter((action) => action.section === section.id));
+      return items.length > 0 ? [{ id: section.id, items, presentation: section.presentation }] : [];
+    });
+
+/** Inserts canvas-only items before destructive layer actions without coupling them to the layer-action registry. */
+export const getLayerContextMenuRenderEntries = (
+  sections: readonly LayerContextMenuSection[],
+  includeBeforeDangerSlot: boolean
+): LayerContextMenuRenderEntry[] =>
+  sections.flatMap((section): LayerContextMenuRenderEntry[] =>
+    includeBeforeDangerSlot && section.id === 'danger'
+      ? [
+          { id: 'before-danger', kind: 'slot' },
+          { kind: 'section', section },
+        ]
+      : [{ kind: 'section', section }]
+  );
+
+/** Resolves the singular layer labels used by the legacy canvas context menu. */
+export const getLayerContextMenuLayerLabelKey = (type: LayerType): LayerContextMenuLayerLabelKey => {
+  switch (type) {
+    case 'control':
+      return 'widgets.canvas.import.control';
+    case 'inpaint_mask':
+      return 'widgets.canvas.import.inpaintMask';
+    case 'raster':
+      return 'widgets.canvas.import.raster';
+    case 'regional_guidance':
+      return 'widgets.canvas.import.regionalGuidance';
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerDndConfig.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerDndConfig.ts
new file mode 100644
index 00000000000..f6cec3219ee
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerDndConfig.ts
@@ -0,0 +1,12 @@
+import type { KeyboardSensorOptions } from '@dnd-kit/core';
+
+import { sortableKeyboardCoordinates } from '@dnd-kit/sortable';
+
+export const LAYER_KEYBOARD_SENSOR_OPTIONS = {
+  coordinateGetter: sortableKeyboardCoordinates,
+  keyboardCodes: {
+    cancel: ['Escape'],
+    end: ['Enter'],
+    start: ['Enter'],
+  },
+} satisfies KeyboardSensorOptions;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerExportActions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerExportActions.test.ts
new file mode 100644
index 00000000000..485e8ea25b0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerExportActions.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { copyBlobToClipboard } from './layerExportActions';
+
+describe('copyBlobToClipboard', () => {
+  it('writes a ClipboardItem using the blob MIME type', async () => {
+    const write = vi.fn(() => Promise.resolve());
+    const created: Record<string, Blob>[] = [];
+    class TestClipboardItem {
+      presentationStyle: PresentationStyle = 'unspecified';
+      types: string[] = [];
+      constructor(items: Record<string, Blob>) {
+        created.push(items);
+        this.types = Object.keys(items);
+      }
+      getType(type: string): Promise<Blob> {
+        return Promise.resolve(created.at(-1)?.[type] ?? new Blob());
+      }
+    }
+    const blob = new Blob(['pixels'], { type: 'image/png' });
+
+    await copyBlobToClipboard(blob, { ClipboardItemCtor: TestClipboardItem, clipboard: { write } });
+
+    expect(created).toHaveLength(1);
+    expect(created[0]?.['image/png']).toBe(blob);
+    expect(write).toHaveBeenCalledWith([expect.any(TestClipboardItem)]);
+  });
+
+  it('fails when the clipboard API is unavailable', async () => {
+    await expect(copyBlobToClipboard(new Blob(['pixels']))).rejects.toThrow('Clipboard image copy is unavailable');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerExportActions.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerExportActions.ts
new file mode 100644
index 00000000000..259d904af00
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerExportActions.ts
@@ -0,0 +1,17 @@
+type ClipboardLike = { write(items: ClipboardItem[]): Promise<void> };
+type ClipboardItemCtor = new (items: Record<string, Blob>) => ClipboardItem;
+
+export interface CopyBlobToClipboardDeps {
+  clipboard?: ClipboardLike;
+  ClipboardItemCtor?: ClipboardItemCtor;
+}
+
+export const copyBlobToClipboard = async (blob: Blob, deps: CopyBlobToClipboardDeps = {}): Promise<void> => {
+  const clipboard = deps.clipboard ?? globalThis.navigator?.clipboard;
+  const ClipboardItemImpl = deps.ClipboardItemCtor ?? globalThis.ClipboardItem;
+  if (!clipboard || !ClipboardItemImpl) {
+    throw new Error('Clipboard image copy is unavailable');
+  }
+  const type = blob.type || 'image/png';
+  await clipboard.write([new ClipboardItemImpl({ [type]: blob })]);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroupActions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroupActions.test.ts
new file mode 100644
index 00000000000..db1ea118b02
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroupActions.test.ts
@@ -0,0 +1,121 @@
+import type {
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerSourceContract,
+  CanvasRasterLayerContractV2,
+} from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { canExportRasterPsd, getGroupActions, isGroupAllVisible, planGroupVisibilityToggle } from './layerGroupActions';
+
+const raster = (source: CanvasLayerSourceContract, id = 'r'): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const imageRef = { height: 10, imageName: 'img', width: 10 };
+
+const inpaint = (id: string, isEnabled = true): CanvasInpaintMaskLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#f00', style: 'solid' } },
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+describe('getGroupActions', () => {
+  it('offers merge-visible + export-psd only for the raster group, with new + toggle everywhere', () => {
+    expect(getGroupActions('raster')).toEqual(['mergeVisible', 'exportPsd', 'toggleVisibility', 'new']);
+    expect(getGroupActions('control')).toEqual(['toggleVisibility', 'new']);
+    expect(getGroupActions('inpaint_mask')).toEqual(['toggleVisibility', 'new']);
+    expect(getGroupActions('regional_guidance')).toEqual(['toggleVisibility', 'new']);
+  });
+
+  it('renders "new" rightmost', () => {
+    for (const key of ['raster', 'control', 'inpaint_mask', 'regional_guidance'] as const) {
+      const actions = getGroupActions(key);
+      expect(actions[actions.length - 1]).toBe('new');
+    }
+  });
+});
+
+describe('canExportRasterPsd', () => {
+  it('is false with no exportable raster content', () => {
+    expect(canExportRasterPsd([])).toBe(false);
+    expect(canExportRasterPsd([inpaint('m')])).toBe(false);
+    // A brand-new paint layer (no bitmap) still counts — its live cache may hold
+    // unflushed strokes the export bakes.
+    expect(canExportRasterPsd([raster({ bitmap: null, type: 'paint' })])).toBe(true);
+  });
+
+  it('counts image/paint/gradient/text and non-polygon shapes as content', () => {
+    expect(canExportRasterPsd([raster({ image: imageRef, type: 'image' })])).toBe(true);
+    expect(canExportRasterPsd([raster({ bitmap: imageRef, type: 'paint' })])).toBe(true);
+    expect(
+      canExportRasterPsd([
+        raster({ fill: null, height: 10, kind: 'rect', stroke: null, strokeWidth: 0, type: 'shape', width: 10 }),
+      ])
+    ).toBe(true);
+  });
+
+  it('excludes polygon shapes (no rasterizer)', () => {
+    expect(
+      canExportRasterPsd([
+        raster({ fill: null, height: 10, kind: 'polygon', stroke: null, strokeWidth: 0, type: 'shape', width: 10 }),
+      ])
+    ).toBe(false);
+  });
+});
+
+describe('isGroupAllVisible', () => {
+  it('is true only when every layer is enabled (empty ⇒ true)', () => {
+    expect(isGroupAllVisible([])).toBe(true);
+    expect(isGroupAllVisible([inpaint('a', true), inpaint('b', true)])).toBe(true);
+    expect(isGroupAllVisible([inpaint('a', true), inpaint('b', false)])).toBe(false);
+  });
+});
+
+describe('planGroupVisibilityToggle', () => {
+  it('hides all when every layer is visible', () => {
+    const layers = [inpaint('a', true), inpaint('b', true)];
+    const { forward, inverse, nextVisible } = planGroupVisibilityToggle(layers);
+    expect(nextVisible).toBe(false);
+    expect(forward).toEqual([
+      { id: 'a', isEnabled: false },
+      { id: 'b', isEnabled: false },
+    ]);
+    // Inverse restores each layer's prior visibility verbatim (single undo entry).
+    expect(inverse).toEqual([
+      { id: 'a', isEnabled: true },
+      { id: 'b', isEnabled: true },
+    ]);
+  });
+
+  it('shows all when any layer is hidden, preserving the mixed prior state in the inverse', () => {
+    const layers = [inpaint('a', true), inpaint('b', false)];
+    const { forward, inverse, nextVisible } = planGroupVisibilityToggle(layers);
+    expect(nextVisible).toBe(true);
+    expect(forward).toEqual([
+      { id: 'a', isEnabled: true },
+      { id: 'b', isEnabled: true },
+    ]);
+    expect(inverse).toEqual([
+      { id: 'a', isEnabled: true },
+      { id: 'b', isEnabled: false },
+    ]);
+  });
+});
+
+// Merge-visible contributor selection is tested where it lives:
+// `canvas-engine/document/mergeVisible.test.ts` (the selector the engine op runs).
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroupActions.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroupActions.ts
new file mode 100644
index 00000000000..b6ff82edd0f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroupActions.ts
@@ -0,0 +1,92 @@
+/**
+ * Pure logic for the layers-panel type-group header actions (round-3 restructure).
+ *
+ * Each type group renders a right-aligned action cluster. The set of actions per
+ * group is data (`getGroupActions`), so a new action — e.g. Task 44's PSD export —
+ * is added by extending one array, not by threading a new prop through the header.
+ * The visibility-toggle planning lives here as pure functions so it is
+ * unit-testable in node (no React, no engine); merge-visible planning lives in
+ * the engine's `document/mergeVisible` (shared with the engine op).
+ */
+
+import type { CanvasLayerContract } from '@workbench/types';
+
+import type { LayerGroupKey } from './layerGroups';
+
+/** A group-header action id. Extend this + `getGroupActions` to add a new action. */
+export type GroupActionId = 'mergeVisible' | 'exportPsd' | 'toggleVisibility' | 'new';
+
+/**
+ * The right-aligned actions for a group, in left-to-right render order (the "New"
+ * action sits rightmost, nearest the panel's own add-layer menu). Only the raster
+ * group offers "merge visible" + "export to PSD"; every group offers
+ * hide/show-all + new.
+ */
+export const getGroupActions = (groupKey: LayerGroupKey): GroupActionId[] => {
+  const actions: GroupActionId[] = [];
+  if (groupKey === 'raster') {
+    actions.push('mergeVisible', 'exportPsd');
+  }
+  actions.push('toggleVisibility', 'new');
+  return actions;
+};
+
+/**
+ * True when a raster layer carries content that a PSD export could contain: an
+ * image/paint/gradient/text source, or a non-`polygon` shape (`polygon` has no
+ * rasterizer). A brand-new paint layer with unflushed live strokes is still
+ * counted (its `source.bitmap` is null but its live cache holds pixels the
+ * export bakes) — enablement never under-counts; a genuinely empty layer is
+ * handled gracefully at export time (the planner returns `empty`).
+ */
+const hasExportableRasterContent = (layer: CanvasLayerContract): boolean => {
+  if (layer.type !== 'raster') {
+    return false;
+  }
+  switch (layer.source.type) {
+    case 'image':
+    case 'paint':
+    case 'gradient':
+    case 'text':
+      return true;
+    case 'shape':
+      return layer.source.kind !== 'polygon';
+    default:
+      return false;
+  }
+};
+
+/** Whether the raster group's "export to PSD" action has anything to export. */
+export const canExportRasterPsd = (layers: readonly CanvasLayerContract[]): boolean =>
+  layers.some(hasExportableRasterContent);
+
+/** A single layer's target visibility, for the bulk `setCanvasLayersEnabled` action. */
+export interface LayerVisibilityUpdate {
+  id: string;
+  isEnabled: boolean;
+}
+
+/** True when every layer in the group is currently visible (enabled). Empty ⇒ true. */
+export const isGroupAllVisible = (groupLayers: readonly CanvasLayerContract[]): boolean =>
+  groupLayers.every((layer) => layer.isEnabled);
+
+/**
+ * Plans a group hide/show-all toggle as ONE reversible bulk action: if every layer
+ * is visible, hide them all; otherwise show them all (legacy `CanvasEntityType`
+ * toggle semantics). `forward` sets the shared target; `inverse` restores each
+ * layer's prior visibility verbatim, so undo is a single history entry.
+ */
+export const planGroupVisibilityToggle = (
+  groupLayers: readonly CanvasLayerContract[]
+): { forward: LayerVisibilityUpdate[]; inverse: LayerVisibilityUpdate[]; nextVisible: boolean } => {
+  const nextVisible = !isGroupAllVisible(groupLayers);
+  return {
+    forward: groupLayers.map((layer) => ({ id: layer.id, isEnabled: nextVisible })),
+    inverse: groupLayers.map((layer) => ({ id: layer.id, isEnabled: layer.isEnabled })),
+    nextVisible,
+  };
+};
+
+// Merge-visible contributor selection lives in the engine's document layer
+// (`@workbench/canvas-engine/document/mergeVisible`) so button enablement and
+// execution use the same legacy-parity eligibility rules.
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroups.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroups.test.ts
new file mode 100644
index 00000000000..86fa892d3ff
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroups.test.ts
@@ -0,0 +1,170 @@
+import type {
+  CanvasControlLayerContract,
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerContract,
+  CanvasRegionalGuidanceLayerContract,
+} from '@workbench/types';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getGroupPosition,
+  groupLayers,
+  LAYER_GROUP_ORDER,
+  reorderWithinGroup,
+  reorderWithinGroupByKind,
+} from './layerGroups';
+import { createEmptyPaintLayer } from './layerOps';
+
+const raster = (id: string): CanvasLayerContract => createEmptyPaintLayer(id, id);
+
+const base = (id: string) => ({
+  blendMode: 'normal' as const,
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+});
+
+const mask = (): { bitmap: null; fill: { color: string; style: 'solid' } } => ({
+  bitmap: null,
+  fill: { color: '#f00', style: 'solid' },
+});
+
+const control = (id: string): CanvasControlLayerContract => ({
+  ...base(id),
+  adapter: { beginEndStepPct: [0, 1], controlMode: null, kind: 'controlnet', model: null, weight: 1 },
+  source: { bitmap: null, type: 'paint' },
+  type: 'control',
+  withTransparencyEffect: true,
+});
+
+const regional = (id: string): CanvasRegionalGuidanceLayerContract => ({
+  ...base(id),
+  autoNegative: false,
+  mask: mask(),
+  negativePrompt: null,
+  positivePrompt: null,
+  referenceImages: [],
+  type: 'regional_guidance',
+});
+
+const inpaint = (id: string): CanvasInpaintMaskLayerContract => ({
+  ...base(id),
+  mask: mask(),
+  type: 'inpaint_mask',
+});
+
+const ids = (layers: CanvasLayerContract[]): string[] => layers.map((layer) => layer.id);
+
+describe('LAYER_GROUP_ORDER', () => {
+  it('matches legacy top-to-bottom display order', () => {
+    expect(LAYER_GROUP_ORDER).toEqual(['inpaint_mask', 'regional_guidance', 'control', 'raster']);
+  });
+});
+
+describe('groupLayers', () => {
+  it('partitions into non-empty groups in display order, preserving global order within a group', () => {
+    // Global z-order (index 0 = top) with interleaved types.
+    const layers = [inpaint('i1'), raster('r1'), regional('g1'), raster('r2'), control('c1'), inpaint('i2')];
+    const groups = groupLayers(layers);
+    expect(groups.map((group) => group.key)).toEqual(['inpaint_mask', 'regional_guidance', 'control', 'raster']);
+    expect(ids(groups[0]!.layers)).toEqual(['i1', 'i2']);
+    expect(ids(groups[1]!.layers)).toEqual(['g1']);
+    expect(ids(groups[2]!.layers)).toEqual(['c1']);
+    expect(ids(groups[3]!.layers)).toEqual(['r1', 'r2']);
+  });
+
+  it('drops empty groups', () => {
+    const groups = groupLayers([raster('r1'), raster('r2')]);
+    expect(groups).toHaveLength(1);
+    expect(groups[0]!.key).toBe('raster');
+  });
+
+  it('returns nothing for an empty document', () => {
+    expect(groupLayers([])).toEqual([]);
+  });
+});
+
+describe('getGroupPosition', () => {
+  const layers = [inpaint('i1'), raster('r1'), raster('r2'), raster('r3')];
+
+  it('reports index within the group and the group count', () => {
+    expect(getGroupPosition(layers, 'r1')).toEqual({ count: 3, index: 0 });
+    expect(getGroupPosition(layers, 'r3')).toEqual({ count: 3, index: 2 });
+    expect(getGroupPosition(layers, 'i1')).toEqual({ count: 1, index: 0 });
+  });
+
+  it('returns null for an absent id', () => {
+    expect(getGroupPosition(layers, 'ghost')).toBeNull();
+  });
+});
+
+describe('reorderWithinGroup', () => {
+  // Interleaved: raster r1/r2/r3 sit at global slots 1, 3, 4.
+  const layers = [inpaint('i1'), raster('r1'), regional('g1'), raster('r2'), raster('r3')];
+
+  it('moves a raster below another raster, keeping other-group layers in place', () => {
+    // r1 (slot 1) dropped onto r3 (slot 4): raster subsequence r1,r2,r3 -> r2,r3,r1
+    // written back into slots [1,3,4]; i1 and g1 keep slots 0 and 2.
+    expect(reorderWithinGroup(layers, 'r1', 'r3')).toEqual(['i1', 'r2', 'g1', 'r3', 'r1']);
+  });
+
+  it('moves a raster up', () => {
+    expect(reorderWithinGroup(layers, 'r3', 'r1')).toEqual(['i1', 'r3', 'g1', 'r1', 'r2']);
+  });
+
+  it('rejects a cross-group drop (raster onto regional)', () => {
+    expect(reorderWithinGroup(layers, 'r1', 'g1')).toBeNull();
+  });
+
+  it('rejects a no-op (active equals over)', () => {
+    expect(reorderWithinGroup(layers, 'r1', 'r1')).toBeNull();
+  });
+
+  it('rejects when an id is absent', () => {
+    expect(reorderWithinGroup(layers, 'ghost', 'r1')).toBeNull();
+    expect(reorderWithinGroup(layers, 'r1', 'ghost')).toBeNull();
+  });
+});
+
+describe('reorderWithinGroupByKind', () => {
+  const layers = [inpaint('i1'), raster('r1'), regional('g1'), raster('r2'), raster('r3')];
+
+  it('moves to front (top of the group)', () => {
+    expect(reorderWithinGroupByKind(layers, 'r3', 'front')).toEqual(['i1', 'r3', 'g1', 'r1', 'r2']);
+  });
+
+  it('moves to back (bottom of the group)', () => {
+    expect(reorderWithinGroupByKind(layers, 'r1', 'back')).toEqual(['i1', 'r2', 'g1', 'r3', 'r1']);
+  });
+
+  it('moves forward one within the group', () => {
+    expect(reorderWithinGroupByKind(layers, 'r2', 'forward')).toEqual(['i1', 'r2', 'g1', 'r1', 'r3']);
+  });
+
+  it('moves backward one within the group', () => {
+    expect(reorderWithinGroupByKind(layers, 'r1', 'backward')).toEqual(['i1', 'r2', 'g1', 'r1', 'r3']);
+  });
+
+  it('is a no-op at the group front boundary (forward)', () => {
+    expect(reorderWithinGroupByKind(layers, 'r1', 'forward')).toBeNull();
+    expect(reorderWithinGroupByKind(layers, 'r1', 'front')).toBeNull();
+  });
+
+  it('is a no-op at the group back boundary (backward)', () => {
+    expect(reorderWithinGroupByKind(layers, 'r3', 'backward')).toBeNull();
+    expect(reorderWithinGroupByKind(layers, 'r3', 'back')).toBeNull();
+  });
+
+  it('is a no-op for a lone group member', () => {
+    expect(reorderWithinGroupByKind(layers, 'i1', 'front')).toBeNull();
+    expect(reorderWithinGroupByKind(layers, 'i1', 'back')).toBeNull();
+  });
+
+  it('returns null for an absent id', () => {
+    expect(reorderWithinGroupByKind(layers, 'ghost', 'front')).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroups.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroups.ts
new file mode 100644
index 00000000000..48fe10e9c75
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerGroups.ts
@@ -0,0 +1,165 @@
+/**
+ * Pure grouping + within-group reorder mapping for the layers panel.
+ *
+ * The reducer keeps ONE z-ordered `layers` array (index 0 = top). The panel
+ * renders it as type groups (inpaint masks, regional guidance, control, raster
+ * — legacy display order), which are filtered *views* preserving each layer's
+ * global relative order. Reordering happens WITHIN a group only: moving layer A
+ * relative to same-group layer B rewrites A's slot in the GLOBAL array while
+ * every other layer stays put. Cross-group moves are rejected (null → no-op).
+ *
+ * Kept free of React / dnd-kit so the mapping is unit-testable in node.
+ */
+
+import type { CanvasLayerContract } from '@workbench/types';
+
+import { moveItem } from './layersDnd';
+
+/** The four layer-type groups. Keys equal the contract's `layer.type`. */
+export type LayerGroupKey = 'inpaint_mask' | 'regional_guidance' | 'control' | 'raster';
+
+/**
+ * Top-to-bottom display order of the type groups, matching legacy's
+ * `CanvasEntityList` (InpaintMask → RegionalGuidance → ControlLayer →
+ * RasterLayer). This is a *display* order only; it does not touch global z.
+ */
+export const LAYER_GROUP_ORDER: readonly LayerGroupKey[] = ['inpaint_mask', 'regional_guidance', 'control', 'raster'];
+
+/** The group a layer belongs to — its contract type maps 1:1 to a group key. */
+export const getLayerGroupKey = (layer: CanvasLayerContract): LayerGroupKey => layer.type;
+
+/** A non-empty type group: its key plus its members in global relative order. */
+export interface LayerGroup {
+  key: LayerGroupKey;
+  layers: CanvasLayerContract[];
+}
+
+/**
+ * Partitions layers into the non-empty type groups, in display order. Each
+ * group's members keep their global relative order; empty groups are dropped.
+ */
+export const groupLayers = (layers: readonly CanvasLayerContract[]): LayerGroup[] =>
+  LAYER_GROUP_ORDER.map((key) => ({
+    key,
+    layers: layers.filter((layer) => getLayerGroupKey(layer) === key),
+  })).filter((group) => group.layers.length > 0);
+
+/** A layer's position within its own group (index 0 = top of the group). */
+export interface GroupPosition {
+  index: number;
+  count: number;
+}
+
+/** Where `layerId` sits inside its type group, or null when it is absent. */
+export const getGroupPosition = (layers: readonly CanvasLayerContract[], layerId: string): GroupPosition | null => {
+  const layer = layers.find((entry) => entry.id === layerId);
+  if (!layer) {
+    return null;
+  }
+  const key = getLayerGroupKey(layer);
+  const index = layers.filter((entry) => getLayerGroupKey(entry) === key).findIndex((entry) => entry.id === layerId);
+  const count = layers.filter((entry) => getLayerGroupKey(entry) === key).length;
+  return { count, index };
+};
+
+const sameOrder = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((id, index) => id === b[index]);
+
+/**
+ * Reorders one type group in place inside the global id order: `reorderGroup`
+ * receives the group's ids (top-to-bottom) and returns their new order (or null
+ * for a no-op). The returned order is written back into exactly the slots the
+ * group occupied, so every other layer keeps its global position. Returns the
+ * full new global id list, or null when nothing moved.
+ */
+const remapGroupOrder = (
+  layers: readonly CanvasLayerContract[],
+  key: LayerGroupKey,
+  reorderGroup: (groupIds: string[]) => string[] | null
+): string[] | null => {
+  const slots: number[] = [];
+  const groupIds: string[] = [];
+  layers.forEach((layer, index) => {
+    if (getLayerGroupKey(layer) === key) {
+      slots.push(index);
+      groupIds.push(layer.id);
+    }
+  });
+  const reordered = reorderGroup(groupIds);
+  if (!reordered || sameOrder(reordered, groupIds)) {
+    return null;
+  }
+  const next = layers.map((layer) => layer.id);
+  reordered.forEach((id, i) => {
+    const slot = slots[i];
+    if (slot !== undefined) {
+      next[slot] = id;
+    }
+  });
+  return next;
+};
+
+/**
+ * Maps a drag-to-reorder (drop `activeId` onto same-group `overId`) to the new
+ * global id order. Returns null — a no-op — when the ids are equal, either is
+ * absent, they live in different groups (cross-group drop), or nothing moved.
+ */
+export const reorderWithinGroup = (
+  layers: readonly CanvasLayerContract[],
+  activeId: string,
+  overId: string
+): string[] | null => {
+  if (activeId === overId) {
+    return null;
+  }
+  const active = layers.find((layer) => layer.id === activeId);
+  const over = layers.find((layer) => layer.id === overId);
+  if (!active || !over || getLayerGroupKey(active) !== getLayerGroupKey(over)) {
+    return null;
+  }
+  return remapGroupOrder(layers, getLayerGroupKey(active), (groupIds) => {
+    const from = groupIds.indexOf(activeId);
+    const to = groupIds.indexOf(overId);
+    return moveItem(groupIds, from, to);
+  });
+};
+
+/** A z-reorder direction for the context menu. Index 0 = front/top. */
+export type LayerMoveKind = 'front' | 'forward' | 'backward' | 'back';
+
+const moveTargetIndex = (index: number, count: number, kind: LayerMoveKind): number => {
+  switch (kind) {
+    case 'front':
+      return 0;
+    case 'forward':
+      return Math.max(0, index - 1);
+    case 'backward':
+      return Math.min(count - 1, index + 1);
+    case 'back':
+      return count - 1;
+  }
+};
+
+/**
+ * Maps a "move to front / forward / backward / to back" command to the new
+ * global id order, moving `layerId` within its own group only. Returns null
+ * when the layer is absent or already at the group boundary for that direction.
+ */
+export const reorderWithinGroupByKind = (
+  layers: readonly CanvasLayerContract[],
+  layerId: string,
+  kind: LayerMoveKind
+): string[] | null => {
+  const layer = layers.find((entry) => entry.id === layerId);
+  if (!layer) {
+    return null;
+  }
+  return remapGroupOrder(layers, getLayerGroupKey(layer), (groupIds) => {
+    const index = groupIds.indexOf(layerId);
+    const target = moveTargetIndex(index, groupIds.length, kind);
+    if (target === index) {
+      return null;
+    }
+    return moveItem(groupIds, index, target);
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerMenuState.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerMenuState.test.ts
new file mode 100644
index 00000000000..db5eafb88d5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerMenuState.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+
+import type { CanvasLayerContextMenuTarget } from './LayerContextMenu';
+
+import {
+  createLayerMenuTargetFromContextEvent,
+  type LayerMenuDialogKind,
+  resolveMenuTargetForRender,
+} from './layerMenuState';
+
+const target = (layerId: string): CanvasLayerContextMenuTarget => ({ layerId, x: 10, y: 20 });
+
+describe('resolveMenuTargetForRender', () => {
+  it('renders the live target while the menu is open', () => {
+    const live = target('a');
+    expect(resolveMenuTargetForRender(live, null)).toBe(live);
+  });
+
+  it('renders nothing with no live target and no pending dialog', () => {
+    expect(resolveMenuTargetForRender(null, null)).toBeNull();
+  });
+
+  it.each(['rename', 'run-workflow'] as const)(
+    'falls back to the captured %s target after the menu closes',
+    (kind: LayerMenuDialogKind) => {
+      const dialogTarget = target('a');
+      expect(resolveMenuTargetForRender(null, { kind, target: dialogTarget })).toBe(dialogTarget);
+    }
+  );
+
+  it('prefers the live target over a pending dialog target when both exist', () => {
+    const live = target('b');
+    expect(resolveMenuTargetForRender(live, { kind: 'rename', target: target('a') })).toBe(live);
+  });
+
+  it('clears the sticky target after dialog close', () => {
+    const dialogState = { kind: 'rename', target: target('a') } as const;
+    expect(resolveMenuTargetForRender(null, dialogState)).toBe(dialogState.target);
+    expect(resolveMenuTargetForRender(null, null)).toBeNull();
+  });
+});
+
+describe('createLayerMenuTargetFromContextEvent', () => {
+  it('uses the pointer position and suppresses the browser context menu', () => {
+    let didPreventDefault = false;
+    let didStopPropagation = false;
+
+    expect(
+      createLayerMenuTargetFromContextEvent('layer-1', {
+        clientX: 30,
+        clientY: 40,
+        preventDefault: () => {
+          didPreventDefault = true;
+        },
+        stopPropagation: () => {
+          didStopPropagation = true;
+        },
+      })
+    ).toEqual({ layerId: 'layer-1', x: 30, y: 40 });
+    expect(didPreventDefault).toBe(true);
+    expect(didStopPropagation).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerMenuState.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerMenuState.ts
new file mode 100644
index 00000000000..ce89e751b20
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerMenuState.ts
@@ -0,0 +1,37 @@
+import type { CanvasLayerContextMenuTarget } from './LayerContextMenu';
+
+/**
+ * Which layer the canvas right-click menu should render for.
+ *
+ * Opening a sibling dialog closes the menu, which nulls the live `target`. The
+ * wrapper keeps a captured dialog target until that dialog closes so the shared
+ * subtree remains mounted for rename and workflow actions.
+ */
+export type LayerMenuDialogKind = 'rename' | 'run-workflow';
+
+export interface LayerMenuDialogState {
+  kind: LayerMenuDialogKind;
+  target: CanvasLayerContextMenuTarget;
+}
+
+export const resolveMenuTargetForRender = (
+  liveTarget: CanvasLayerContextMenuTarget | null,
+  dialogState: LayerMenuDialogState | null
+): CanvasLayerContextMenuTarget | null => liveTarget ?? dialogState?.target ?? null;
+
+export interface LayerContextMenuEvent {
+  clientX: number;
+  clientY: number;
+  preventDefault: () => void;
+  stopPropagation: () => void;
+}
+
+export const createLayerMenuTargetFromContextEvent = (
+  layerId: string,
+  event: LayerContextMenuEvent
+): CanvasLayerContextMenuTarget => {
+  event.preventDefault();
+  event.stopPropagation();
+
+  return { layerId, x: event.clientX, y: event.clientY };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerOps.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerOps.test.ts
new file mode 100644
index 00000000000..9d1f7fbf693
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerOps.test.ts
@@ -0,0 +1,712 @@
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { CanvasLayerContract, CanvasRasterLayerContractV2 } from '@workbench/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  applyStructuralPreview,
+  applyStructural,
+  type CanvasStructuralEngine,
+  canConvertRasterControl,
+  canMergeLayerDown,
+  convertRasterToControl,
+  convertRasterToInpaintMask,
+  convertRasterToRegionalGuidance,
+  convertRasterControlLayer,
+  copyControlToInpaintMask,
+  copyControlToRaster,
+  copyControlToRegionalGuidance,
+  copyMaskToRegionalGuidance,
+  copyRasterToControl,
+  copyRasterToInpaintMask,
+  copyRasterToRegionalGuidance,
+  copyRegionalGuidanceToInpaintMask,
+  createControlLayer,
+  createEmptyPaintLayer,
+  createInpaintMaskFromImage,
+  createInpaintMaskLayer,
+  createRegionalGuidanceFromImage,
+  createRegionalGuidanceLayer,
+  createRegionalGuidanceLayerWithRefImage,
+  createRegionalReferenceImage,
+  DEFAULT_CONTROL_ADAPTER,
+  CONTROL_ADAPTER_DEFAULTS,
+  CONTROL_WEIGHT_BOUNDS,
+  DEFAULT_INPAINT_MASK_FILL,
+  fitLayerTransformToBbox,
+  getControlTransparencyEffectPatch,
+  getInpaintDenoiseLimitPatch,
+  getInpaintNoisePatch,
+  getRegionalGuidanceAutoNegativePatch,
+  getRegionalGuidanceNegativePromptPatch,
+  getRegionalGuidancePositivePromptPatch,
+  getRegionalGuidanceReferenceImagePatch,
+  isMergeableRasterLayer,
+  nextControlLayerName,
+  nextInpaintMaskName,
+  nextRegionalGuidanceFillColor,
+  REGIONAL_GUIDANCE_FILL_COLORS,
+} from './layerOps';
+
+const paintLayer = (id: string, patch: Partial<CanvasRasterLayerContractV2> = {}): CanvasLayerContract => ({
+  ...createEmptyPaintLayer(id, id),
+  ...patch,
+});
+
+const imageLayer = (id: string): CanvasLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: 10, imageName: id, width: 10 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const maskLayer = (id: string): CanvasLayerContract => ({
+  autoNegative: false,
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { color: '#f00', style: 'solid' } },
+  name: id,
+  negativePrompt: null,
+  opacity: 1,
+  positivePrompt: null,
+  referenceImages: [],
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'regional_guidance',
+});
+
+describe('createEmptyPaintLayer', () => {
+  it('builds an enabled, document-sized paint raster layer', () => {
+    const layer = createEmptyPaintLayer('Layer 1', 'l1');
+    expect(layer).toMatchObject({
+      id: 'l1',
+      isEnabled: true,
+      isLocked: false,
+      name: 'Layer 1',
+      opacity: 1,
+      source: { bitmap: null, type: 'paint' },
+      type: 'raster',
+    });
+  });
+
+  it('mints a unique id when none is supplied', () => {
+    expect(createEmptyPaintLayer('a').id).not.toBe(createEmptyPaintLayer('a').id);
+  });
+});
+
+describe('nextRegionalGuidanceFillColor', () => {
+  it('derives the colour purely from the existing regional-guidance count (no session state)', () => {
+    // Legacy pre-increment cycler: the first region (0 existing) gets index 1.
+    expect(nextRegionalGuidanceFillColor(0)).toBe(REGIONAL_GUIDANCE_FILL_COLORS[1]);
+    expect(nextRegionalGuidanceFillColor(1)).toBe(REGIONAL_GUIDANCE_FILL_COLORS[2]);
+    // Wraps modulo the palette length.
+    expect(nextRegionalGuidanceFillColor(REGIONAL_GUIDANCE_FILL_COLORS.length - 1)).toBe(
+      REGIONAL_GUIDANCE_FILL_COLORS[0]
+    );
+    // Pure: the same count always yields the same colour, regardless of call order.
+    expect(nextRegionalGuidanceFillColor(0)).toBe(nextRegionalGuidanceFillColor(0));
+  });
+
+  it('createRegionalGuidanceLayer uses the count-derived fill colour', () => {
+    expect(createRegionalGuidanceLayer('Regional Guidance 1', 0).mask.fill.color).toBe(
+      REGIONAL_GUIDANCE_FILL_COLORS[1]
+    );
+    expect(createRegionalGuidanceLayer('Regional Guidance 2', 1).mask.fill.color).toBe(
+      REGIONAL_GUIDANCE_FILL_COLORS[2]
+    );
+  });
+});
+
+describe('isMergeableRasterLayer', () => {
+  it('accepts enabled paint and image raster layers', () => {
+    expect(isMergeableRasterLayer(paintLayer('p'))).toBe(true);
+    expect(isMergeableRasterLayer(imageLayer('i'))).toBe(true);
+  });
+
+  it('rejects disabled layers and non-raster layers', () => {
+    expect(isMergeableRasterLayer(paintLayer('p', { isEnabled: false }))).toBe(false);
+    expect(isMergeableRasterLayer(maskLayer('m'))).toBe(false);
+  });
+
+  it('rejects locked layers (matches the paint tool: a locked target refuses edits)', () => {
+    expect(isMergeableRasterLayer(paintLayer('p', { isLocked: true }))).toBe(false);
+    expect(isMergeableRasterLayer({ ...imageLayer('i'), isLocked: true })).toBe(false);
+  });
+});
+
+describe('canMergeLayerDown', () => {
+  const layers = [paintLayer('top'), imageLayer('mid'), maskLayer('bottom')];
+
+  it('requires an engine (merge is pixel work)', () => {
+    expect(canMergeLayerDown(layers, 0, false)).toBe(false);
+  });
+
+  it('allows merging when the layer and the one below are both mergeable', () => {
+    expect(canMergeLayerDown(layers, 0, true)).toBe(true);
+  });
+
+  it('disallows merging into a non-mergeable below layer', () => {
+    // index 1 (mid, image) sits above the mask layer, which cannot be merged into.
+    expect(canMergeLayerDown(layers, 1, true)).toBe(false);
+  });
+
+  it('disallows merging the bottom-most layer (nothing below)', () => {
+    expect(canMergeLayerDown(layers, 2, true)).toBe(false);
+  });
+
+  it('disallows merging when the upper layer is locked', () => {
+    const lockedTop = [paintLayer('top', { isLocked: true }), imageLayer('mid'), maskLayer('bottom')];
+    expect(canMergeLayerDown(lockedTop, 0, true)).toBe(false);
+  });
+
+  it('disallows merging when the below layer is locked', () => {
+    const lockedMid = [paintLayer('top'), { ...imageLayer('mid'), isLocked: true }, maskLayer('bottom')];
+    expect(canMergeLayerDown(lockedMid, 0, true)).toBe(false);
+  });
+});
+
+describe('applyStructural', () => {
+  const forward: CanvasProjectMutation = { ids: ['a'], type: 'removeCanvasLayers' };
+  const inverse: CanvasProjectMutation = { index: 0, layer: paintLayer('a'), type: 'addCanvasLayer' };
+
+  it('routes through the engine history when an engine is attached', () => {
+    const commitStructural = vi.fn();
+    const engine = { layers: { commitStructural } } as unknown as CanvasStructuralEngine;
+    const dispatch = vi.fn();
+
+    applyStructural(engine, dispatch, 'Delete layer', forward, inverse);
+
+    expect(commitStructural).toHaveBeenCalledWith('Delete layer', forward, inverse);
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+
+  it('falls back to a plain forward dispatch without an engine', () => {
+    const dispatch = vi.fn();
+
+    applyStructural(null, dispatch, 'Delete layer', forward, inverse);
+
+    expect(dispatch).toHaveBeenCalledWith(forward);
+    expect(dispatch).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('applyStructuralPreview', () => {
+  it('routes a live document edit through the engine guard', () => {
+    const action = { id: 'layer', patch: { opacity: 0.5 }, type: 'updateCanvasLayer' } as const;
+    const applyPreview = vi.fn(() => false);
+    const engine = { layers: { applyStructuralPreview: applyPreview } } as unknown as CanvasStructuralEngine;
+    const dispatch = vi.fn();
+
+    expect(applyStructuralPreview(engine, dispatch, action)).toBe(false);
+
+    expect(applyPreview).toHaveBeenCalledWith(action);
+    expect(dispatch).not.toHaveBeenCalled();
+  });
+});
+
+describe('createInpaintMaskLayer', () => {
+  it('builds an empty inpaint mask with the legacy-default diagonal fill', () => {
+    const layer = createInpaintMaskLayer('Inpaint Mask 1', 'm1');
+    expect(layer.type).toBe('inpaint_mask');
+    expect(layer.id).toBe('m1');
+    expect(layer.name).toBe('Inpaint Mask 1');
+    expect(layer.isEnabled).toBe(true);
+    expect(layer.mask.bitmap).toBeNull();
+    expect(layer.mask.fill).toEqual(DEFAULT_INPAINT_MASK_FILL);
+    expect(layer.mask.fill.style).toBe('diagonal');
+  });
+
+  it('mints a fresh id when none is given', () => {
+    const a = createInpaintMaskLayer('m');
+    const b = createInpaintMaskLayer('m');
+    expect(a.id).not.toBe(b.id);
+  });
+});
+
+describe('image-backed mask layer factories', () => {
+  const image = { height: 13, imageName: 'selected-object.png', width: 17 };
+  const rect = { height: 13, width: 17, x: -4, y: 9 };
+
+  it('builds a complete inpaint mask contract with the image at the world rect', () => {
+    expect(
+      createInpaintMaskFromImage({
+        fill: { color: '#123456', style: 'crosshatch' },
+        id: 'mask-result',
+        image,
+        name: 'Inpaint Mask 2',
+        rect,
+      })
+    ).toEqual({
+      blendMode: 'normal',
+      id: 'mask-result',
+      isEnabled: true,
+      isLocked: false,
+      mask: {
+        bitmap: image,
+        fill: { color: '#123456', style: 'crosshatch' },
+        offset: { x: -4, y: 9 },
+      },
+      name: 'Inpaint Mask 2',
+      opacity: 1,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'inpaint_mask',
+    });
+  });
+
+  it('builds a complete regional-guidance contract with preserved defaults', () => {
+    expect(
+      createRegionalGuidanceFromImage({
+        fill: { color: '#83d683', style: 'solid' },
+        id: 'regional-result',
+        image,
+        name: 'Regional Guidance 3',
+        rect,
+      })
+    ).toEqual({
+      autoNegative: false,
+      blendMode: 'normal',
+      id: 'regional-result',
+      isEnabled: true,
+      isLocked: false,
+      mask: {
+        bitmap: image,
+        fill: { color: '#83d683', style: 'solid' },
+        offset: { x: -4, y: 9 },
+      },
+      name: 'Regional Guidance 3',
+      negativePrompt: null,
+      opacity: 0.5,
+      positivePrompt: null,
+      referenceImages: [],
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'regional_guidance',
+    });
+  });
+});
+
+describe('nextInpaintMaskName', () => {
+  it('returns the first free "Inpaint Mask N"', () => {
+    expect(nextInpaintMaskName([])).toBe('Inpaint Mask 1');
+    expect(nextInpaintMaskName(['Inpaint Mask 1'])).toBe('Inpaint Mask 2');
+    // Fills the first gap, ignoring unrelated names.
+    expect(nextInpaintMaskName(['Inpaint Mask 1', 'Inpaint Mask 3', 'Layer 2'])).toBe('Inpaint Mask 2');
+  });
+});
+
+describe('createControlLayer', () => {
+  it('centralizes legacy defaults for every adapter kind', () => {
+    expect(CONTROL_ADAPTER_DEFAULTS).toEqual({
+      control_lora: { beginEndStepPct: [0, 1], controlMode: null, kind: 'control_lora', model: null, weight: 0.75 },
+      controlnet: {
+        beginEndStepPct: [0, 0.75],
+        controlMode: 'balanced',
+        kind: 'controlnet',
+        model: null,
+        weight: 0.75,
+      },
+      t2i_adapter: { beginEndStepPct: [0, 1], controlMode: null, kind: 't2i_adapter', model: null, weight: 1 },
+      z_image_control: {
+        beginEndStepPct: [0, 1],
+        controlMode: null,
+        kind: 'z_image_control',
+        model: null,
+        weight: 0.75,
+      },
+    });
+  });
+
+  it('keeps the 0.75 creation default separate from legacy weight input ranges', () => {
+    expect(DEFAULT_CONTROL_ADAPTER.weight).toBe(0.75);
+    expect(CONTROL_WEIGHT_BOUNDS).toEqual({ inputMax: 2, inputMin: -1, sliderMax: 2, sliderMin: 0, step: 0.05 });
+  });
+
+  it('builds an empty control layer with the legacy-default ControlNet adapter and transparency on', () => {
+    const layer = createControlLayer('Control Layer 1', 'c1');
+    expect(layer).toMatchObject({
+      id: 'c1',
+      isEnabled: true,
+      name: 'Control Layer 1',
+      type: 'control',
+      withTransparencyEffect: true,
+    });
+    expect(layer.source).toEqual({ bitmap: null, type: 'paint' });
+    expect(layer.adapter).toEqual(DEFAULT_CONTROL_ADAPTER);
+    expect(layer.adapter.weight).toBe(0.75);
+    // The default adapter's mutable array must be copied, not shared.
+    expect(layer.adapter.beginEndStepPct).not.toBe(DEFAULT_CONTROL_ADAPTER.beginEndStepPct);
+    expect(layer.adapter.beginEndStepPct).toEqual([0, 0.75]);
+  });
+
+  it('uses Z-Image control defaults when created for a Z-Image main model', () => {
+    expect(createControlLayer('Z Control', 'z1', 'z-image').adapter).toEqual(CONTROL_ADAPTER_DEFAULTS.z_image_control);
+  });
+});
+
+describe('nextControlLayerName', () => {
+  it('returns the first free "Control Layer N" gap', () => {
+    expect(nextControlLayerName([])).toBe('Control Layer 1');
+    expect(nextControlLayerName(['Control Layer 1', 'Control Layer 3'])).toBe('Control Layer 2');
+    expect(nextControlLayerName(['Control Layer 1', 'Control Layer 2'])).toBe('Control Layer 3');
+  });
+});
+
+describe('canConvertRasterControl', () => {
+  it('is true for image/paint raster layers and control layers, false otherwise', () => {
+    expect(canConvertRasterControl(createEmptyPaintLayer('p', 'p'))).toBe(true);
+    expect(canConvertRasterControl(createControlLayer('c', 'c'))).toBe(true);
+    expect(
+      canConvertRasterControl(
+        paintLayer('img', { source: { image: { height: 1, imageName: 'i', width: 1 }, type: 'image' } })
+      )
+    ).toBe(true);
+    // Parametric raster sources cannot convert.
+    expect(
+      canConvertRasterControl(
+        paintLayer('txt', {
+          source: {
+            align: 'left',
+            color: '#fff',
+            content: 'hi',
+            fontFamily: 'x',
+            fontSize: 12,
+            fontWeight: 400,
+            lineHeight: 1,
+            type: 'text',
+          },
+        })
+      )
+    ).toBe(false);
+    expect(canConvertRasterControl(createInpaintMaskLayer('m', 'm'))).toBe(false);
+  });
+});
+
+describe('fitLayerTransformToBbox', () => {
+  it('scales and positions a layer content rect into the bbox', () => {
+    const layer = paintLayer('paint', {
+      source: { bitmap: { height: 50, imageName: 'paint', width: 100 }, offset: { x: 20, y: 10 }, type: 'paint' },
+    });
+
+    expect(
+      fitLayerTransformToBbox(layer, { height: 100, width: 200, x: 0, y: 0 }, { height: 512, width: 512, x: 0, y: 0 })
+    ).toEqual({ rotation: 0, scaleX: 2, scaleY: 2, x: -40, y: -20 });
+  });
+
+  it('returns null for empty content', () => {
+    expect(fitLayerTransformToBbox(createEmptyPaintLayer('empty'), { height: 512, width: 512, x: 0, y: 0 })).toBeNull();
+  });
+
+  it('contains and centers landscape content without stretching', () => {
+    const layer = paintLayer('landscape', {
+      source: {
+        bitmap: { height: 100, imageName: 'landscape', width: 200 },
+        offset: { x: 10, y: 20 },
+        type: 'paint',
+      },
+    });
+
+    expect(fitLayerTransformToBbox(layer, { height: 100, width: 100, x: 0, y: 0 })).toEqual({
+      rotation: 0,
+      scaleX: 0.5,
+      scaleY: 0.5,
+      x: -5,
+      y: 15,
+    });
+  });
+
+  it('contains and centers portrait content without stretching', () => {
+    const layer = paintLayer('portrait', {
+      source: {
+        bitmap: { height: 200, imageName: 'portrait', width: 100 },
+        offset: { x: 10, y: 20 },
+        type: 'paint',
+      },
+    });
+
+    expect(fitLayerTransformToBbox(layer, { height: 100, width: 100, x: 0, y: 0 })).toEqual({
+      rotation: 0,
+      scaleX: 0.5,
+      scaleY: 0.5,
+      x: 20,
+      y: -10,
+    });
+  });
+
+  it('accounts for non-zero local content origins and bbox placement', () => {
+    const layer = paintLayer('offset', {
+      source: {
+        bitmap: { height: 50, imageName: 'offset', width: 50 },
+        offset: { x: -20, y: 30 },
+        type: 'paint',
+      },
+    });
+
+    expect(fitLayerTransformToBbox(layer, { height: 100, width: 200, x: 50, y: 100 })).toEqual({
+      rotation: 0,
+      scaleX: 2,
+      scaleY: 2,
+      x: 140,
+      y: 40,
+    });
+  });
+});
+
+describe('menu patch helpers', () => {
+  it('builds control transparency effect patches', () => {
+    const layer = createControlLayer('control', 'c1');
+
+    expect(getControlTransparencyEffectPatch(layer)).toEqual({
+      forward: { layerType: 'control', withTransparencyEffect: false },
+      inverse: { layerType: 'control', withTransparencyEffect: true },
+    });
+  });
+
+  it('builds regional prompt and reference image patches', () => {
+    const layer = createRegionalGuidanceLayer('region', 0, 'r1');
+
+    expect(getRegionalGuidancePositivePromptPatch(layer)).toEqual({
+      forward: { layerType: 'regional_guidance', positivePrompt: '' },
+      inverse: { layerType: 'regional_guidance', positivePrompt: null },
+    });
+    expect(getRegionalGuidanceNegativePromptPatch(layer)).toEqual({
+      forward: { layerType: 'regional_guidance', negativePrompt: '' },
+      inverse: { layerType: 'regional_guidance', negativePrompt: null },
+    });
+    expect(getRegionalGuidanceAutoNegativePatch(layer)).toEqual({
+      forward: { autoNegative: true, layerType: 'regional_guidance' },
+      inverse: { autoNegative: false, layerType: 'regional_guidance' },
+    });
+    expect(getRegionalGuidanceReferenceImagePatch(layer, 'sdxl').forward.referenceImages).toHaveLength(1);
+  });
+
+  it('builds inpaint modifier patches', () => {
+    const layer = createInpaintMaskLayer('mask', 'm1');
+
+    expect(getInpaintNoisePatch(layer)).toEqual({
+      forward: { layerType: 'inpaint_mask', noiseLevel: 0.25 },
+      inverse: { layerType: 'inpaint_mask', noiseLevel: undefined },
+    });
+    expect(getInpaintDenoiseLimitPatch(layer)).toEqual({
+      forward: { denoiseLimit: 0.8, layerType: 'inpaint_mask' },
+      inverse: { denoiseLimit: undefined, layerType: 'inpaint_mask' },
+    });
+  });
+});
+
+describe('convertRasterControlLayer', () => {
+  it('converts raster→control preserving source/id/name/transform and applying the default adapter', () => {
+    const source = { image: { height: 48, imageName: 'pic', width: 64 }, type: 'image' } as const;
+    const transform = { rotation: 10, scaleX: 2, scaleY: 2, x: 5, y: 6 };
+    const raster = paintLayer('r', { name: 'My Layer', opacity: 0.5, source, transform });
+    const converted = convertRasterControlLayer(raster, 'control');
+    expect(converted).toMatchObject({
+      id: 'r',
+      name: 'My Layer',
+      opacity: 0.5,
+      type: 'control',
+      withTransparencyEffect: true,
+    });
+    if (converted?.type === 'control') {
+      expect(converted.source).toEqual(source);
+      expect(converted.transform).toEqual(transform);
+      expect(converted.adapter).toEqual(DEFAULT_CONTROL_ADAPTER);
+    }
+  });
+
+  it('converts raster→control with Z-Image defaults for a Z-Image main model', () => {
+    const converted = convertRasterControlLayer(paintLayer('r'), 'control', 'z-image');
+    expect(converted?.type === 'control' ? converted.adapter : null).toEqual(CONTROL_ADAPTER_DEFAULTS.z_image_control);
+  });
+
+  it('converts control→raster preserving the pixel source and round-trips', () => {
+    const control = createControlLayer('C', 'c1');
+    const withSource = {
+      ...control,
+      source: { image: { height: 48, imageName: 'pic', width: 64 }, type: 'image' },
+    } as CanvasLayerContract;
+    const raster = convertRasterControlLayer(withSource, 'raster');
+    expect(raster?.type).toBe('raster');
+    if (raster?.type === 'raster') {
+      expect(raster.source).toEqual({ image: { height: 48, imageName: 'pic', width: 64 }, type: 'image' });
+      expect(raster.id).toBe('c1');
+    }
+    // Round-trip back to control keeps the source.
+    const backToControl = raster ? convertRasterControlLayer(raster, 'control') : null;
+    expect(backToControl?.type).toBe('control');
+    if (backToControl?.type === 'control') {
+      expect(backToControl.source).toEqual({ image: { height: 48, imageName: 'pic', width: 64 }, type: 'image' });
+    }
+  });
+
+  it('returns null when the layer already has the target type or cannot convert', () => {
+    expect(convertRasterControlLayer(createControlLayer('c', 'c'), 'control')).toBeNull();
+    expect(convertRasterControlLayer(createEmptyPaintLayer('p', 'p'), 'raster')).toBeNull();
+    expect(convertRasterControlLayer(createInpaintMaskLayer('m', 'm'), 'control')).toBeNull();
+  });
+});
+
+describe('layer copy and conversion parity', () => {
+  const transform = { rotation: 10, scaleX: 2, scaleY: 3, x: 4, y: 5 };
+  const raster = {
+    ...createEmptyPaintLayer('Raster', 'r1'),
+    blendMode: 'multiply' as const,
+    isEnabled: false,
+    isLocked: true,
+    opacity: 0.4,
+    source: {
+      bitmap: { height: 20, imageName: 'paint-bitmap', width: 30 },
+      offset: { x: -3, y: 7 },
+      type: 'paint' as const,
+    },
+    transform,
+  };
+
+  it('copies and converts pixel-backed raster layers without baking their source', () => {
+    const controlCopy = copyRasterToControl(raster, 'c-copy');
+    expect(controlCopy).toMatchObject({
+      id: 'c-copy',
+      isEnabled: false,
+      isLocked: true,
+      name: 'Raster copy',
+      opacity: 0.4,
+      source: raster.source,
+      transform,
+      type: 'control',
+      withTransparencyEffect: true,
+    });
+    expect(copyRasterToInpaintMask(raster, 'm-copy')).toMatchObject({
+      id: 'm-copy',
+      mask: { bitmap: raster.source.bitmap, offset: raster.source.offset },
+      name: 'Raster copy',
+      type: 'inpaint_mask',
+    });
+    expect(copyRasterToRegionalGuidance(raster, 'rg-copy')).toMatchObject({
+      autoNegative: false,
+      id: 'rg-copy',
+      mask: { bitmap: raster.source.bitmap, offset: raster.source.offset },
+      name: 'Raster copy',
+      negativePrompt: null,
+      positivePrompt: null,
+      referenceImages: [],
+      type: 'regional_guidance',
+    });
+
+    expect(convertRasterToControl(raster)).toMatchObject({ id: 'r1', source: raster.source, type: 'control' });
+    expect(convertRasterToInpaintMask(raster)).toMatchObject({
+      id: 'r1',
+      mask: { bitmap: raster.source.bitmap, offset: raster.source.offset },
+      type: 'inpaint_mask',
+    });
+    expect(convertRasterToRegionalGuidance(raster)).toMatchObject({
+      id: 'r1',
+      mask: { bitmap: raster.source.bitmap, offset: raster.source.offset },
+      type: 'regional_guidance',
+    });
+  });
+
+  it('copies control layers to pixel and mask-backed destinations', () => {
+    const control = { ...createControlLayer('Control', 'c1'), source: raster.source, transform };
+
+    expect(copyControlToRaster(control, 'r-copy')).toMatchObject({
+      id: 'r-copy',
+      name: 'Control copy',
+      source: raster.source,
+      transform,
+      type: 'raster',
+    });
+    expect(copyControlToInpaintMask(control, 'm-copy')).toMatchObject({
+      id: 'm-copy',
+      mask: { bitmap: raster.source.bitmap, offset: raster.source.offset },
+      type: 'inpaint_mask',
+    });
+    expect(copyControlToRegionalGuidance(control, 'rg-copy')).toMatchObject({
+      id: 'rg-copy',
+      mask: { bitmap: raster.source.bitmap, offset: raster.source.offset },
+      type: 'regional_guidance',
+    });
+  });
+
+  it('copies between mask layer types while preserving bitmap, offset, and fill', () => {
+    const mask = {
+      ...createInpaintMaskLayer('Mask', 'm1'),
+      mask: {
+        bitmap: { height: 12, imageName: 'mask-bitmap', width: 13 },
+        fill: { color: '#123456', style: 'crosshatch' as const },
+        offset: { x: 8, y: -2 },
+      },
+      transform,
+    };
+    const regional = copyMaskToRegionalGuidance(mask, 'rg-copy');
+
+    expect(regional).toMatchObject({ id: 'rg-copy', mask: mask.mask, name: 'Mask copy', type: 'regional_guidance' });
+    expect(regional?.mask).not.toBe(mask.mask);
+    expect(copyRegionalGuidanceToInpaintMask(regional!, 'm-copy')).toMatchObject({
+      id: 'm-copy',
+      mask: mask.mask,
+      name: 'Mask copy copy',
+      type: 'inpaint_mask',
+    });
+  });
+
+  it('rejects parametric raster sources that cannot be represented as masks or controls', () => {
+    const text = {
+      ...raster,
+      source: {
+        align: 'left' as const,
+        color: '#fff',
+        content: 'hello',
+        fontFamily: 'Inter',
+        fontSize: 32,
+        fontWeight: 400,
+        lineHeight: 1.2,
+        type: 'text' as const,
+      },
+    };
+
+    expect(copyRasterToControl(text, 'copy')).toBeNull();
+    expect(copyRasterToInpaintMask(text, 'copy')).toBeNull();
+    expect(copyRasterToRegionalGuidance(text, 'copy')).toBeNull();
+    expect(convertRasterToControl(text)).toBeNull();
+    expect(convertRasterToInpaintMask(text)).toBeNull();
+    expect(convertRasterToRegionalGuidance(text)).toBeNull();
+  });
+});
+
+describe('createRegionalReferenceImage', () => {
+  it('mints a FLUX Redux ref image for a flux base', () => {
+    const ref = createRegionalReferenceImage('flux', 'ref-1');
+    expect(ref).toEqual({
+      config: { image: null, imageInfluence: 'highest', model: null, type: 'flux_redux' },
+      id: 'ref-1',
+      isEnabled: true,
+    });
+  });
+
+  it('mints an IP-Adapter ref image for a non-flux base', () => {
+    const ref = createRegionalReferenceImage('sdxl', 'ref-2');
+    expect(ref.id).toBe('ref-2');
+    expect(ref.isEnabled).toBe(true);
+    expect(ref.config.type).toBe('ip_adapter');
+  });
+});
+
+describe('createRegionalGuidanceLayerWithRefImage', () => {
+  it('is a regional guidance layer pre-seeded with exactly one empty reference image', () => {
+    const layer = createRegionalGuidanceLayerWithRefImage('Region 1', 0, 'sdxl', 'rg-1');
+    expect(layer.type).toBe('regional_guidance');
+    expect(layer.id).toBe('rg-1');
+    expect(layer.referenceImages).toHaveLength(1);
+    expect(layer.referenceImages[0]?.config.type).toBe('ip_adapter');
+    expect(layer.referenceImages[0]?.config.image).toBeNull();
+  });
+
+  it('seeds a FLUX Redux reference image when the base is flux', () => {
+    const layer = createRegionalGuidanceLayerWithRefImage('Region 1', 0, 'flux', 'rg-2');
+    expect(layer.referenceImages[0]?.config.type).toBe('flux_redux');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerOps.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerOps.ts
new file mode 100644
index 00000000000..98ab7635fdd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerOps.ts
@@ -0,0 +1,682 @@
+/**
+ * Shared helpers for the layers panel: id minting, the paint-layer factory, the
+ * blend-mode list, merge-down eligibility, and the single seam that routes a
+ * structural edit either through the engine's canvas history (when an engine is
+ * attached) or as a plain reducer dispatch (when it is not).
+ */
+
+import type { CanvasLayerCapability } from '@workbench/canvas-engine/api';
+import type { Rect } from '@workbench/canvas-engine/types';
+import type { CanvasProjectMutation } from '@workbench/canvasProjectMutations';
+import type { GenerateReferenceImage } from '@workbench/generation/types';
+import type {
+  CanvasBlendMode,
+  CanvasControlLayerContract,
+  CanvasDocumentContractV2,
+  CanvasImageRef,
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerBaseContract,
+  CanvasLayerContract,
+  CanvasLayerSourceContract,
+  CanvasMaskContract,
+  CanvasMaskFillContract,
+  CanvasRasterLayerContractV2,
+  CanvasRegionalGuidanceLayerContract,
+} from '@workbench/types';
+import type { Dispatch } from 'react';
+
+export type CanvasStructuralEngine = { readonly layers: CanvasLayerCapability };
+
+import { getSourceContentRect, isMergeableRasterLayer } from '@workbench/canvas-engine/document/sources';
+import { CONTROL_ADAPTER_DEFAULTS } from '@workbench/controlAdapters';
+
+type LayerTransform = CanvasLayerBaseContract['transform'];
+
+type ControlConfigPatch = { layerType: 'control'; withTransparencyEffect?: boolean };
+type RegionalGuidanceConfigPatch = {
+  layerType: 'regional_guidance';
+  positivePrompt?: string | null;
+  negativePrompt?: string | null;
+  autoNegative?: boolean;
+  referenceImages?: CanvasRegionalGuidanceLayerContract['referenceImages'];
+};
+type InpaintMaskConfigPatch = { layerType: 'inpaint_mask'; noiseLevel?: number; denoiseLimit?: number };
+type PatchPair<T> = { forward: T; inverse: T };
+
+/**
+ * Re-exported so existing imports of `isMergeableRasterLayer` from this module
+ * keep working; the canonical definition lives in the engine's `document/sources`
+ * (the single source of truth the engine's own `mergeLayerDown` guard uses too —
+ * see the finding this fixed: the engine used to gate on the broader
+ * `isRenderableLayer`, which let a mask merge-down corrupt data).
+ */
+export { isMergeableRasterLayer };
+
+/** All 16 document blend modes, in the contract's declared order. */
+export const CANVAS_BLEND_MODES: readonly CanvasBlendMode[] = [
+  'normal',
+  'multiply',
+  'screen',
+  'overlay',
+  'darken',
+  'lighten',
+  'color-dodge',
+  'color-burn',
+  'hard-light',
+  'soft-light',
+  'difference',
+  'exclusion',
+  'hue',
+  'saturation',
+  'color',
+  'luminosity',
+];
+
+/** Mints a fresh layer id (matches the engine's `createLayerId` shape). */
+export const createLayerId = (): string => `layer-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+/** Builds an empty, document-sized paint layer with sensible defaults. */
+export const createEmptyPaintLayer = (name: string, id: string = createLayerId()): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+/**
+ * Legacy-default inpaint mask fill: a diagonal hatch (legacy's
+ * `getInpaintMaskState` default `style: 'diagonal'`) in the first cycled mask
+ * fill colour (legacy `rgb(224,117,117)`). Multiple inpaint masks are allowed.
+ */
+export const DEFAULT_INPAINT_MASK_FILL = { color: '#e07575', style: 'diagonal' } as const;
+
+/** The next free "Inpaint Mask N" name given the existing layer names (N ≥ 1, first gap). */
+export const nextInpaintMaskName = (existingNames: readonly string[]): string => {
+  const used = new Set<number>();
+  for (const name of existingNames) {
+    const match = /^Inpaint Mask (\d+)$/.exec(name.trim());
+    if (match) {
+      const n = Number(match[1]);
+      if (Number.isInteger(n) && n > 0) {
+        used.add(n);
+      }
+    }
+  }
+  let n = 1;
+  while (used.has(n)) {
+    n += 1;
+  }
+  return `Inpaint Mask ${n}`;
+};
+
+/** Builds an empty inpaint mask layer with the legacy-default fill (no bitmap yet). */
+export const createInpaintMaskLayer = (name: string, id: string = createLayerId()): CanvasInpaintMaskLayerContract => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: { bitmap: null, fill: { ...DEFAULT_INPAINT_MASK_FILL } },
+  name,
+  opacity: 1,
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'inpaint_mask',
+});
+
+/**
+ * Legacy's regional-guidance mask fill palette (`DEFAULT_RG_MASK_FILL_COLORS`),
+ * as hex. New regions cycle through these so overlapping regions stay visually
+ * distinct.
+ */
+export const REGIONAL_GUIDANCE_FILL_COLORS: readonly string[] = [
+  '#799ddb',
+  '#83d683',
+  '#fae150',
+  '#dc9065',
+  '#e07575',
+  '#d58bca',
+  '#a178d6',
+];
+
+/**
+ * The next cycled regional-guidance fill colour, derived purely from the document
+ * (the count of existing regional-guidance layers) rather than session-global
+ * state. Legacy's cycler was seeded at index 0 and pre-incremented, so the first
+ * new region (0 existing) gets index 1 (`#83d683`, green); each subsequent region
+ * advances by one, wrapping modulo the palette length. Being a pure function of
+ * the document, colours no longer depend on session history or leak across
+ * projects.
+ */
+export const nextRegionalGuidanceFillColor = (existingRegionalGuidanceCount: number): string =>
+  REGIONAL_GUIDANCE_FILL_COLORS[(existingRegionalGuidanceCount + 1) % REGIONAL_GUIDANCE_FILL_COLORS.length];
+
+/** The next free "Regional Guidance N" name given the existing layer names (N ≥ 1, first gap). */
+export const nextRegionalGuidanceName = (existingNames: readonly string[]): string => {
+  const used = new Set<number>();
+  for (const name of existingNames) {
+    const match = /^Regional Guidance (\d+)$/.exec(name.trim());
+    if (match) {
+      const n = Number(match[1]);
+      if (Number.isInteger(n) && n > 0) {
+        used.add(n);
+      }
+    }
+  }
+  let n = 1;
+  while (used.has(n)) {
+    n += 1;
+  }
+  return `Regional Guidance ${n}`;
+};
+
+/**
+ * Builds an empty regional-guidance layer with legacy defaults: a solid fill in
+ * the next cycled palette colour (derived from `existingRegionalGuidanceCount`,
+ * the number of regional-guidance layers already in the document), opacity 0.5,
+ * no prompts, autoNegative off, and no reference images (no mask bitmap yet — the
+ * user paints the region).
+ */
+export const createRegionalGuidanceLayer = (
+  name: string,
+  existingRegionalGuidanceCount: number,
+  id: string = createLayerId()
+): CanvasRegionalGuidanceLayerContract => ({
+  autoNegative: false,
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  mask: {
+    bitmap: null,
+    fill: { color: nextRegionalGuidanceFillColor(existingRegionalGuidanceCount), style: 'solid' },
+  },
+  name,
+  negativePrompt: null,
+  opacity: 0.5,
+  positivePrompt: null,
+  referenceImages: [],
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'regional_guidance',
+});
+
+export interface CreateMaskLayerFromImageInput {
+  image: CanvasImageRef;
+  rect: Rect;
+  id: string;
+  name: string;
+  fill: CanvasMaskFillContract;
+}
+
+export const createInpaintMaskFromImage = (input: CreateMaskLayerFromImageInput): CanvasInpaintMaskLayerContract => ({
+  ...createInpaintMaskLayer(input.name, input.id),
+  mask: {
+    bitmap: { ...input.image },
+    fill: { ...input.fill },
+    offset: { x: input.rect.x, y: input.rect.y },
+  },
+});
+
+export const createRegionalGuidanceFromImage = (
+  input: CreateMaskLayerFromImageInput
+): CanvasRegionalGuidanceLayerContract => ({
+  ...createRegionalGuidanceLayer(input.name, 0, input.id),
+  mask: {
+    bitmap: { ...input.image },
+    fill: { ...input.fill },
+    offset: { x: input.rect.x, y: input.rect.y },
+  },
+});
+
+/** Mints a fresh regional-guidance reference-image id. */
+export const createReferenceImageId = (): string =>
+  `rgref-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+/**
+ * A fresh regional reference image, minting the config kind the region's base can
+ * actually consume: FLUX regions use FLUX Redux (the only kind resolved for FLUX
+ * in `resolveRegionalReferenceImages`), everything else uses an IP-Adapter (legacy
+ * `initialRegionalGuidanceIPAdapter`). The model is chosen by the user; the image
+ * is assigned via drop/upload. Shared by `RegionalGuidanceSettings` (the in-popover
+ * "add reference image" button) and the header add-layer menu's "Regional Reference
+ * Image" item, so both mint the same shape.
+ */
+export const createRegionalReferenceImage = (
+  base: string | null,
+  id: string = createReferenceImageId()
+): GenerateReferenceImage => {
+  if (base === 'flux') {
+    return {
+      config: { image: null, imageInfluence: 'highest', model: null, type: 'flux_redux' },
+      id,
+      isEnabled: true,
+    };
+  }
+  return {
+    config: {
+      beginEndStepPct: [0, 1],
+      clipVisionModel: 'ViT-H',
+      image: null,
+      method: 'full',
+      model: null,
+      type: 'ip_adapter',
+      weight: 1,
+    },
+    id,
+    isEnabled: true,
+  };
+};
+
+/**
+ * Builds a regional-guidance layer pre-seeded with ONE empty reference image
+ * (legacy's "regional guidance with a reference image" add-layer path). Identical
+ * to `createRegionalGuidanceLayer` except the region starts with a single ref-image
+ * slot the user then assigns a model + image to via the region's settings popover.
+ */
+export const createRegionalGuidanceLayerWithRefImage = (
+  name: string,
+  existingRegionalGuidanceCount: number,
+  base: string | null,
+  id: string = createLayerId()
+): CanvasRegionalGuidanceLayerContract => ({
+  ...createRegionalGuidanceLayer(name, existingRegionalGuidanceCount, id),
+  referenceImages: [createRegionalReferenceImage(base)],
+});
+
+/**
+ * The legacy-default control adapter for a freshly created control layer
+ * (`features/controlLayers/store/util.ts` `initialControlNet`): a ControlNet with
+ * weight 0.75, an active range of the first 75% of steps, `balanced` control mode,
+ * and no model selected yet.
+ */
+export { CONTROL_ADAPTER_DEFAULTS };
+
+export const CONTROL_WEIGHT_BOUNDS = {
+  inputMax: 2,
+  inputMin: -1,
+  sliderMax: 2,
+  sliderMin: 0,
+  step: 0.05,
+} as const;
+
+export const DEFAULT_CONTROL_ADAPTER = CONTROL_ADAPTER_DEFAULTS.controlnet;
+
+/** The next free "Control Layer N" name given the existing layer names (N ≥ 1, first gap). */
+export const nextControlLayerName = (existingNames: readonly string[]): string => {
+  const used = new Set<number>();
+  for (const name of existingNames) {
+    const match = /^Control Layer (\d+)$/.exec(name.trim());
+    if (match) {
+      const n = Number(match[1]);
+      if (Number.isInteger(n) && n > 0) {
+        used.add(n);
+      }
+    }
+  }
+  let n = 1;
+  while (used.has(n)) {
+    n += 1;
+  }
+  return `Control Layer ${n}`;
+};
+
+/**
+ * Builds an empty control layer with the legacy-default ControlNet adapter and
+ * transparency effect ON (legacy `withTransparencyEffect: true`). No source /
+ * filter yet — the user paints or drops an image, then optionally previews a
+ * filter.
+ */
+export const createControlLayer = (
+  name: string,
+  id: string = createLayerId(),
+  base?: string | null
+): CanvasControlLayerContract => {
+  const adapter = base === 'z-image' ? CONTROL_ADAPTER_DEFAULTS.z_image_control : DEFAULT_CONTROL_ADAPTER;
+  return {
+    adapter: { ...adapter, beginEndStepPct: [...adapter.beginEndStepPct] },
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    name,
+    opacity: 1,
+    source: { bitmap: null, type: 'paint' },
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'control',
+    withTransparencyEffect: true,
+  };
+};
+
+/** Returns the transform that fits the layer's unrotated local content into the bbox. */
+export const fitLayerTransformToBbox = (
+  layer: CanvasLayerContract,
+  bbox: Rect,
+  documentRect: Rect = bbox
+): LayerTransform | null => {
+  const doc = { height: documentRect.height, width: documentRect.width } as CanvasDocumentContractV2;
+  const contentRect = getSourceContentRect(layer, doc);
+  if (contentRect.width <= 0 || contentRect.height <= 0) {
+    return null;
+  }
+  const scale = Math.min(bbox.width / contentRect.width, bbox.height / contentRect.height);
+  return {
+    rotation: 0,
+    scaleX: scale,
+    scaleY: scale,
+    x: bbox.x + (bbox.width - contentRect.width * scale) / 2 - contentRect.x * scale,
+    y: bbox.y + (bbox.height - contentRect.height * scale) / 2 - contentRect.y * scale,
+  };
+};
+
+export const getControlTransparencyEffectPatch = (
+  layer: CanvasControlLayerContract
+): PatchPair<ControlConfigPatch> => ({
+  forward: { layerType: 'control', withTransparencyEffect: !layer.withTransparencyEffect },
+  inverse: { layerType: 'control', withTransparencyEffect: layer.withTransparencyEffect },
+});
+
+export const getRegionalGuidancePositivePromptPatch = (
+  layer: CanvasRegionalGuidanceLayerContract
+): PatchPair<RegionalGuidanceConfigPatch> => ({
+  forward: { layerType: 'regional_guidance', positivePrompt: layer.positivePrompt ?? '' },
+  inverse: { layerType: 'regional_guidance', positivePrompt: layer.positivePrompt },
+});
+
+export const getRegionalGuidanceNegativePromptPatch = (
+  layer: CanvasRegionalGuidanceLayerContract
+): PatchPair<RegionalGuidanceConfigPatch> => ({
+  forward: { layerType: 'regional_guidance', negativePrompt: layer.negativePrompt ?? '' },
+  inverse: { layerType: 'regional_guidance', negativePrompt: layer.negativePrompt },
+});
+
+export const getRegionalGuidanceAutoNegativePatch = (
+  layer: CanvasRegionalGuidanceLayerContract
+): PatchPair<RegionalGuidanceConfigPatch> => ({
+  forward: { autoNegative: !layer.autoNegative, layerType: 'regional_guidance' },
+  inverse: { autoNegative: layer.autoNegative, layerType: 'regional_guidance' },
+});
+
+export const getRegionalGuidanceReferenceImagePatch = (
+  layer: CanvasRegionalGuidanceLayerContract,
+  base: string | null
+): PatchPair<RegionalGuidanceConfigPatch> => ({
+  forward: {
+    layerType: 'regional_guidance',
+    referenceImages: [...layer.referenceImages, createRegionalReferenceImage(base)],
+  },
+  inverse: { layerType: 'regional_guidance', referenceImages: layer.referenceImages },
+});
+
+export const getInpaintNoisePatch = (layer: CanvasInpaintMaskLayerContract): PatchPair<InpaintMaskConfigPatch> => ({
+  forward: { layerType: 'inpaint_mask', noiseLevel: layer.noiseLevel === undefined ? 0.25 : undefined },
+  inverse: { layerType: 'inpaint_mask', noiseLevel: layer.noiseLevel },
+});
+
+export const getInpaintDenoiseLimitPatch = (
+  layer: CanvasInpaintMaskLayerContract
+): PatchPair<InpaintMaskConfigPatch> => ({
+  forward: { denoiseLimit: layer.denoiseLimit === undefined ? 0.8 : undefined, layerType: 'inpaint_mask' },
+  inverse: { denoiseLimit: layer.denoiseLimit, layerType: 'inpaint_mask' },
+});
+
+/**
+ * True when `layer` can be converted to a control layer (and vice-versa): only a
+ * raster layer with a rasterizable image/paint source, or a control layer,
+ * qualifies — parametric raster sources (shape/text/gradient) and mask layers do
+ * not (legacy only offers raster↔control conversion for pixel-backed layers).
+ */
+export const canConvertRasterControl = (layer: CanvasLayerContract): boolean => {
+  if (layer.type === 'control') {
+    return true;
+  }
+  return layer.type === 'raster' && (layer.source.type === 'image' || layer.source.type === 'paint');
+};
+
+type PixelLayer = CanvasRasterLayerContractV2 | CanvasControlLayerContract;
+type PixelSource = Extract<CanvasLayerSourceContract, { type: 'image' | 'paint' }>;
+
+const cloneTransform = (layer: CanvasLayerContract): LayerTransform => ({ ...layer.transform });
+
+const clonePixelSource = (layer: PixelLayer): PixelSource | null => {
+  if (layer.source.type === 'image') {
+    return { image: { ...layer.source.image }, type: 'image' };
+  }
+  if (layer.source.type === 'paint') {
+    return {
+      bitmap: layer.source.bitmap ? { ...layer.source.bitmap } : null,
+      offset: layer.source.offset ? { ...layer.source.offset } : undefined,
+      type: 'paint',
+    };
+  }
+  return null;
+};
+
+const pixelLayerToMask = (layer: PixelLayer): CanvasMaskContract | null => {
+  const source = clonePixelSource(layer);
+  if (!source) {
+    return null;
+  }
+  if (source.type === 'image') {
+    return { bitmap: source.image, fill: { ...DEFAULT_INPAINT_MASK_FILL } };
+  }
+  return {
+    bitmap: source.bitmap,
+    fill: { ...DEFAULT_INPAINT_MASK_FILL },
+    offset: source.offset,
+  };
+};
+
+const cloneMask = (mask: CanvasMaskContract): CanvasMaskContract => ({
+  bitmap: mask.bitmap ? { ...mask.bitmap } : null,
+  fill: { ...mask.fill },
+  offset: mask.offset ? { ...mask.offset } : undefined,
+});
+
+const destinationBase = (layer: CanvasLayerContract, id: string, isCopy: boolean): CanvasLayerBaseContract => ({
+  blendMode: layer.blendMode,
+  id,
+  isEnabled: layer.isEnabled,
+  isLocked: layer.isLocked,
+  name: isCopy ? `${layer.name} copy` : layer.name,
+  opacity: layer.opacity,
+  transform: cloneTransform(layer),
+});
+
+const pixelLayerToControl = (
+  layer: PixelLayer,
+  id: string,
+  isCopy: boolean,
+  base?: string | null
+): CanvasControlLayerContract | null => {
+  const source = clonePixelSource(layer);
+  if (!source) {
+    return null;
+  }
+  return {
+    ...destinationBase(layer, id, isCopy),
+    adapter: {
+      ...(base === 'z-image' ? CONTROL_ADAPTER_DEFAULTS.z_image_control : DEFAULT_CONTROL_ADAPTER),
+      beginEndStepPct: [
+        ...(base === 'z-image'
+          ? CONTROL_ADAPTER_DEFAULTS.z_image_control.beginEndStepPct
+          : DEFAULT_CONTROL_ADAPTER.beginEndStepPct),
+      ],
+    },
+    source,
+    type: 'control',
+    withTransparencyEffect: true,
+  };
+};
+
+const pixelLayerToInpaintMask = (
+  layer: PixelLayer,
+  id: string,
+  isCopy: boolean
+): CanvasInpaintMaskLayerContract | null => {
+  const mask = pixelLayerToMask(layer);
+  return mask ? { ...destinationBase(layer, id, isCopy), mask, type: 'inpaint_mask' } : null;
+};
+
+const pixelLayerToRegionalGuidance = (
+  layer: PixelLayer,
+  id: string,
+  isCopy: boolean
+): CanvasRegionalGuidanceLayerContract | null => {
+  const mask = pixelLayerToMask(layer);
+  return mask
+    ? {
+        ...destinationBase(layer, id, isCopy),
+        autoNegative: false,
+        mask,
+        negativePrompt: null,
+        positivePrompt: null,
+        referenceImages: [],
+        type: 'regional_guidance',
+      }
+    : null;
+};
+
+export const copyRasterToControl = (
+  layer: CanvasRasterLayerContractV2,
+  id: string,
+  base?: string | null
+): CanvasControlLayerContract | null => pixelLayerToControl(layer, id, true, base);
+
+export const copyRasterToInpaintMask = (
+  layer: CanvasRasterLayerContractV2,
+  id: string
+): CanvasInpaintMaskLayerContract | null => pixelLayerToInpaintMask(layer, id, true);
+
+export const copyRasterToRegionalGuidance = (
+  layer: CanvasRasterLayerContractV2,
+  id: string
+): CanvasRegionalGuidanceLayerContract | null => pixelLayerToRegionalGuidance(layer, id, true);
+
+export const convertRasterToControl = (
+  layer: CanvasRasterLayerContractV2,
+  base?: string | null
+): CanvasControlLayerContract | null => pixelLayerToControl(layer, layer.id, false, base);
+
+export const convertRasterToInpaintMask = (layer: CanvasRasterLayerContractV2): CanvasInpaintMaskLayerContract | null =>
+  pixelLayerToInpaintMask(layer, layer.id, false);
+
+export const convertRasterToRegionalGuidance = (
+  layer: CanvasRasterLayerContractV2
+): CanvasRegionalGuidanceLayerContract | null => pixelLayerToRegionalGuidance(layer, layer.id, false);
+
+export const copyControlToRaster = (
+  layer: CanvasControlLayerContract,
+  id: string
+): CanvasRasterLayerContractV2 | null => {
+  const source = clonePixelSource(layer);
+  return source ? { ...destinationBase(layer, id, true), source, type: 'raster' } : null;
+};
+
+export const copyControlToInpaintMask = (
+  layer: CanvasControlLayerContract,
+  id: string
+): CanvasInpaintMaskLayerContract | null => pixelLayerToInpaintMask(layer, id, true);
+
+export const copyControlToRegionalGuidance = (
+  layer: CanvasControlLayerContract,
+  id: string
+): CanvasRegionalGuidanceLayerContract | null => pixelLayerToRegionalGuidance(layer, id, true);
+
+export const copyMaskToRegionalGuidance = (
+  layer: CanvasInpaintMaskLayerContract,
+  id: string
+): CanvasRegionalGuidanceLayerContract => ({
+  ...destinationBase(layer, id, true),
+  autoNegative: false,
+  mask: cloneMask(layer.mask),
+  negativePrompt: null,
+  positivePrompt: null,
+  referenceImages: [],
+  type: 'regional_guidance',
+});
+
+export const copyRegionalGuidanceToInpaintMask = (
+  layer: CanvasRegionalGuidanceLayerContract,
+  id: string
+): CanvasInpaintMaskLayerContract => ({
+  ...destinationBase(layer, id, true),
+  mask: cloneMask(layer.mask),
+  type: 'inpaint_mask',
+});
+
+/**
+ * Converts a raster layer to a control layer (default adapter, transparency on)
+ * or a control layer back to a raster layer, preserving the pixel source, id,
+ * name, transform, and base props. Returns `null` when the layer cannot convert
+ * (parametric/mask sources) or already has the target type.
+ */
+export const convertRasterControlLayer = (
+  layer: CanvasLayerContract,
+  targetType: 'raster' | 'control',
+  base?: string | null
+): CanvasLayerContract | null => {
+  if (layer.type === targetType || !canConvertRasterControl(layer)) {
+    return null;
+  }
+  if (layer.type === 'raster' && targetType === 'control') {
+    return convertRasterToControl(layer, base);
+  }
+  if (layer.type === 'control' && targetType === 'raster') {
+    const source = clonePixelSource(layer);
+    return source ? { ...destinationBase(layer, layer.id, false), source, type: 'raster' } : null;
+  }
+  return null;
+};
+
+/**
+ * Whether the layer at `index` can be merged down: an engine must be attached
+ * (merge is pixel work), a layer must exist directly below it, and both that
+ * layer and the one below must be mergeable raster layers.
+ */
+export const canMergeLayerDown = (
+  layers: readonly CanvasLayerContract[],
+  index: number,
+  hasEngine: boolean
+): boolean => {
+  if (!hasEngine) {
+    return false;
+  }
+  const layer = layers[index];
+  const below = layers[index + 1];
+  return !!layer && !!below && isMergeableRasterLayer(layer) && isMergeableRasterLayer(below);
+};
+
+/**
+ * Applies a structural document edit. With an engine attached it goes through
+ * `commitStructural`, joining the canvas undo stack; without one it is a plain
+ * dispatch (no undo entry — acceptable when the canvas is not mounted).
+ */
+export const applyStructural = (
+  engine: CanvasStructuralEngine | null,
+  dispatch: Dispatch<CanvasProjectMutation>,
+  label: string,
+  forward: CanvasProjectMutation,
+  inverse: CanvasProjectMutation
+): void => {
+  if (engine) {
+    engine.layers.commitStructural(label, forward, inverse);
+  } else {
+    dispatch(forward);
+  }
+};
+
+/** Applies a guarded live edit without recording history until the interaction ends. */
+export const applyStructuralPreview = (
+  engine: CanvasStructuralEngine | null,
+  dispatch: Dispatch<CanvasProjectMutation>,
+  action: CanvasProjectMutation
+): boolean => {
+  if (engine) {
+    return engine.layers.applyStructuralPreview(action);
+  }
+  dispatch(action);
+  return true;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesOperation.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesOperation.test.ts
new file mode 100644
index 00000000000..52ba17f07a0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesOperation.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  closeLayerPropertiesForOperation,
+  getLayerFilterLaunchDisabledReason,
+  getLayerFilterLaunchReasonKey,
+  getLayerPropertiesOwnershipKey,
+  isLayerPropertiesOpen,
+  runLayerFilterOperation,
+} from './layerPropertiesOperation';
+
+describe('getLayerFilterLaunchDisabledReason', () => {
+  it.each([
+    {
+      expected: 'not-ready',
+      input: { hasEngine: false, hasExportableContent: false, isEnabled: true, isLocked: false },
+      scenario: 'missing engine',
+    },
+    {
+      expected: 'disabled',
+      input: { hasEngine: true, hasExportableContent: true, isEnabled: false, isLocked: false },
+      scenario: 'disabled layer',
+    },
+    {
+      expected: 'locked',
+      input: { hasEngine: true, hasExportableContent: true, isEnabled: true, isLocked: true },
+      scenario: 'locked layer',
+    },
+    {
+      expected: 'empty',
+      input: { hasEngine: true, hasExportableContent: false, isEnabled: true, isLocked: false },
+      scenario: 'empty layer',
+    },
+    {
+      expected: null,
+      input: { hasEngine: true, hasExportableContent: true, isEnabled: true, isLocked: false },
+      scenario: 'eligible layer',
+    },
+  ] as const)('returns $expected for $scenario', ({ expected, input }) => {
+    expect(getLayerFilterLaunchDisabledReason(input)).toBe(expected);
+  });
+
+  it.each([
+    ['empty', 'widgets.layers.actions.empty'],
+    ['missing', 'widgets.layers.actions.missing'],
+    ['disabled', 'widgets.layers.actions.disabled'],
+    ['locked', 'widgets.layers.actions.locked'],
+    ['unsupported', 'widgets.layers.actions.unsupported'],
+    ['not-ready', 'widgets.layers.actions.notReady'],
+  ] as const)('maps %s to %s', (reason, key) => {
+    expect(getLayerFilterLaunchReasonKey(reason)).toBe(key);
+  });
+});
+
+describe('runLayerFilterOperation callbacks', () => {
+  it('notifies only the success callback for a started launch', () => {
+    const onOperationStarted = vi.fn();
+    const onOperationRejected = vi.fn();
+
+    expect(runLayerFilterOperation(() => 'started', onOperationStarted, onOperationRejected)).toBe('started');
+    expect(onOperationStarted).toHaveBeenCalledOnce();
+    expect(onOperationRejected).not.toHaveBeenCalled();
+  });
+
+  it.each(['missing', 'disabled', 'locked', 'unsupported', 'not-ready'] as const)(
+    'notifies rejection for %s without closing properties',
+    (result) => {
+      const onOperationStarted = vi.fn();
+      const onOperationRejected = vi.fn();
+
+      expect(runLayerFilterOperation(() => result, onOperationStarted, onOperationRejected)).toBe(result);
+      expect(onOperationStarted).not.toHaveBeenCalled();
+      expect(onOperationRejected).toHaveBeenCalledOnce();
+      expect(onOperationRejected).toHaveBeenCalledWith(result);
+    }
+  );
+
+  it('does not report rejection when no engine supplied a launch result', () => {
+    const onOperationStarted = vi.fn();
+    const onOperationRejected = vi.fn();
+
+    expect(runLayerFilterOperation(() => undefined, onOperationStarted, onOperationRejected)).toBeUndefined();
+    expect(onOperationStarted).not.toHaveBeenCalled();
+    expect(onOperationRejected).not.toHaveBeenCalled();
+  });
+});
+
+describe('closeLayerPropertiesForOperation', () => {
+  it('uses separate ownership across editing-lock transitions so trigger state cannot reopen after cancel', () => {
+    expect(getLayerPropertiesOwnershipKey(false)).not.toBe(getLayerPropertiesOwnershipKey(true));
+  });
+
+  it.each([
+    { requestToken: null, triggerOpen: true },
+    { requestToken: 42, triggerOpen: false },
+    { requestToken: 42, triggerOpen: true },
+  ])('clears trigger and request ownership for $triggerOpen/$requestToken', (state) => {
+    const closed = closeLayerPropertiesForOperation(state);
+
+    expect(closed).toEqual({ requestToken: null, requestTokenToClear: state.requestToken, triggerOpen: false });
+    expect(isLayerPropertiesOpen(closed)).toBe(false);
+  });
+
+  it('stays closed after the operation is later canceled', () => {
+    const closed = closeLayerPropertiesForOperation({ requestToken: 7, triggerOpen: true });
+
+    expect(isLayerPropertiesOpen(closed)).toBe(false);
+  });
+});
+
+describe('runLayerFilterOperation', () => {
+  it('notifies the popover after a successful manual launch', () => {
+    const onOperationStarted = vi.fn();
+
+    expect(runLayerFilterOperation(() => 'started', onOperationStarted)).toBe('started');
+    expect(onOperationStarted).toHaveBeenCalledOnce();
+  });
+
+  it('notifies the popover after a successful model-recommendation launch', () => {
+    const onOperationStarted = vi.fn();
+    const start = vi.fn((_recommendation: string) => 'started' as const);
+
+    expect(runLayerFilterOperation(() => start('normal_map'), onOperationStarted)).toBe('started');
+    expect(start).toHaveBeenCalledWith('normal_map');
+    expect(onOperationStarted).toHaveBeenCalledOnce();
+  });
+
+  it.each(['locked', 'not-ready', 'missing', undefined] as const)('does not close after a %s launch', (result) => {
+    const onOperationStarted = vi.fn();
+
+    expect(runLayerFilterOperation(() => result, onOperationStarted)).toBe(result);
+    expect(onOperationStarted).not.toHaveBeenCalled();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesOperation.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesOperation.ts
new file mode 100644
index 00000000000..38f755a35a5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesOperation.ts
@@ -0,0 +1,75 @@
+import type { StartFilterOperationResult } from '@workbench/canvas-operations/api';
+
+interface LayerPropertiesOpenOwnership {
+  requestToken: number | null;
+  triggerOpen: boolean;
+}
+
+export type LayerFilterLaunchRejectedResult = Exclude<StartFilterOperationResult, 'started'>;
+export type LayerFilterLaunchDisabledReason = LayerFilterLaunchRejectedResult | 'empty';
+
+export interface LayerFilterLaunchEligibilityInput {
+  hasEngine: boolean;
+  hasExportableContent: boolean;
+  isEnabled: boolean;
+  isLocked: boolean;
+}
+
+const LAYER_FILTER_LAUNCH_REASON_KEYS: Record<LayerFilterLaunchDisabledReason, string> = {
+  disabled: 'widgets.layers.actions.disabled',
+  empty: 'widgets.layers.actions.empty',
+  locked: 'widgets.layers.actions.locked',
+  missing: 'widgets.layers.actions.missing',
+  'not-ready': 'widgets.layers.actions.notReady',
+  unsupported: 'widgets.layers.actions.unsupported',
+};
+
+export const getLayerFilterLaunchDisabledReason = ({
+  hasEngine,
+  hasExportableContent,
+  isEnabled,
+  isLocked,
+}: LayerFilterLaunchEligibilityInput): LayerFilterLaunchDisabledReason | null => {
+  if (!hasEngine) {
+    return 'not-ready';
+  }
+  if (!isEnabled) {
+    return 'disabled';
+  }
+  if (isLocked) {
+    return 'locked';
+  }
+  if (!hasExportableContent) {
+    return 'empty';
+  }
+  return null;
+};
+
+export const getLayerFilterLaunchReasonKey = (reason: LayerFilterLaunchDisabledReason): string =>
+  LAYER_FILTER_LAUNCH_REASON_KEYS[reason];
+
+export const getLayerPropertiesOwnershipKey = (editingLocked: boolean): 'editable' | 'locked' =>
+  editingLocked ? 'locked' : 'editable';
+
+export const isLayerPropertiesOpen = ({ requestToken, triggerOpen }: LayerPropertiesOpenOwnership): boolean =>
+  triggerOpen || requestToken !== null;
+
+export const closeLayerPropertiesForOperation = ({ requestToken }: LayerPropertiesOpenOwnership) => ({
+  requestToken: null,
+  requestTokenToClear: requestToken,
+  triggerOpen: false,
+});
+
+export const runLayerFilterOperation = (
+  launch: () => StartFilterOperationResult | undefined,
+  onOperationStarted: () => void,
+  onOperationRejected?: (result: LayerFilterLaunchRejectedResult) => void
+): StartFilterOperationResult | undefined => {
+  const result = launch();
+  if (result === 'started') {
+    onOperationStarted();
+  } else if (result !== undefined) {
+    onOperationRejected?.(result);
+  }
+  return result;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesRequestStore.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesRequestStore.test.ts
new file mode 100644
index 00000000000..824069031ed
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesRequestStore.test.ts
@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createControlLayer, createEmptyPaintLayer } from './layerOps';
+import {
+  clearLayerPropertiesRequest,
+  getLayerPropertiesRequest,
+  isLayerPropertiesGroupRequested,
+  layerPropertiesRequestStore,
+  requestLayerProperties,
+} from './layerPropertiesRequestStore';
+
+describe('layerPropertiesRequestStore', () => {
+  beforeEach(() => {
+    clearLayerPropertiesRequest();
+  });
+
+  it.each(['filter', 'adjustments'] as const)('publishes and token-safely clears a %s request', (section) => {
+    requestLayerProperties('layer-1', section);
+    const first = getLayerPropertiesRequest();
+    requestLayerProperties('layer-2', section);
+    const second = getLayerPropertiesRequest();
+
+    expect(first).toMatchObject({ layerId: 'layer-1', section });
+    expect(second).toMatchObject({ layerId: 'layer-2', section });
+    clearLayerPropertiesRequest(first?.token);
+    expect(getLayerPropertiesRequest()).toEqual(second);
+    clearLayerPropertiesRequest(second?.token);
+    expect(getLayerPropertiesRequest()).toBeNull();
+  });
+
+  it('publishes a fresh token for repeated requests and notifies subscribers', () => {
+    const listener = vi.fn();
+    const unsubscribe = layerPropertiesRequestStore.subscribe(listener);
+
+    requestLayerProperties('control-1', 'filter');
+    const first = getLayerPropertiesRequest();
+    requestLayerProperties('control-1', 'filter');
+    const second = getLayerPropertiesRequest();
+
+    expect(second?.token).toBeGreaterThan(first?.token ?? 0);
+    expect(listener).toHaveBeenCalledTimes(2);
+    unsubscribe();
+  });
+
+  it('only clears the request matching the supplied token', () => {
+    requestLayerProperties('control-1', 'filter');
+    const first = getLayerPropertiesRequest();
+    requestLayerProperties('control-2', 'filter');
+    const second = getLayerPropertiesRequest();
+
+    clearLayerPropertiesRequest(first?.token);
+    expect(getLayerPropertiesRequest()).toEqual(second);
+    clearLayerPropertiesRequest(second?.token);
+    expect(getLayerPropertiesRequest()).toBeNull();
+  });
+
+  it('identifies the collapsed layer group that must mount to consume the request', () => {
+    const control = createControlLayer('Control', 'control-1');
+    requestLayerProperties(control.id, 'filter');
+    const request = getLayerPropertiesRequest();
+
+    expect(isLayerPropertiesGroupRequested(request, [control])).toBe(true);
+    expect(isLayerPropertiesGroupRequested(request, [createEmptyPaintLayer('Raster', 'raster-1')])).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesRequestStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesRequestStore.ts
new file mode 100644
index 00000000000..83d8e318711
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layerPropertiesRequestStore.ts
@@ -0,0 +1,46 @@
+import type { CanvasLayerContract } from '@workbench/types';
+
+import { createExternalStore } from '@workbench/externalStore';
+
+export type LayerPropertiesSection = 'filter' | 'adjustments';
+
+export interface LayerPropertiesRequest {
+  layerId: string;
+  section: LayerPropertiesSection;
+  token: number;
+}
+
+export const layerPropertiesRequestStore = createExternalStore<{ request: LayerPropertiesRequest | null }>({
+  request: null,
+});
+
+let nextToken = 1;
+
+export const requestLayerProperties = (layerId: string, section: LayerPropertiesSection): void => {
+  layerPropertiesRequestStore.setSnapshot({ request: { layerId, section, token: nextToken++ } });
+};
+
+export const clearLayerPropertiesRequest = (token?: number): void => {
+  const current = layerPropertiesRequestStore.getSnapshot().request;
+  if (token !== undefined && current?.token !== token) {
+    return;
+  }
+  layerPropertiesRequestStore.setSnapshot({ request: null });
+};
+
+export const getLayerPropertiesRequest = (): LayerPropertiesRequest | null =>
+  layerPropertiesRequestStore.getSnapshot().request;
+
+export const useLayerPropertiesRequest = (layerId: string): LayerPropertiesRequest | null =>
+  layerPropertiesRequestStore.useSelector(
+    (snapshot) => (snapshot.request?.layerId === layerId ? snapshot.request : null),
+    Object.is
+  );
+
+export const useCurrentLayerPropertiesRequest = (): LayerPropertiesRequest | null =>
+  layerPropertiesRequestStore.useSelector((snapshot) => snapshot.request, Object.is);
+
+export const isLayerPropertiesGroupRequested = (
+  request: LayerPropertiesRequest | null,
+  layers: readonly CanvasLayerContract[]
+): boolean => !!request && layers.some((layer) => layer.id === request.layerId);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layersDnd.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layersDnd.test.ts
new file mode 100644
index 00000000000..6899e750851
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layersDnd.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+
+import { LAYER_KEYBOARD_SENSOR_OPTIONS } from './layerDndConfig';
+import { moveItem } from './layersDnd';
+
+describe('layer keyboard drag configuration', () => {
+  it('uses Enter alone to start and end, Escape to cancel, and never claims Space', () => {
+    expect(LAYER_KEYBOARD_SENSOR_OPTIONS.keyboardCodes).toEqual({
+      cancel: ['Escape'],
+      end: ['Enter'],
+      start: ['Enter'],
+    });
+    expect(Object.values(LAYER_KEYBOARD_SENSOR_OPTIONS.keyboardCodes).flat()).not.toContain('Space');
+  });
+});
+
+describe('moveItem', () => {
+  it('moves an item forward, shifting the rest', () => {
+    expect(moveItem(['a', 'b', 'c', 'd'], 0, 2)).toEqual(['b', 'c', 'a', 'd']);
+  });
+
+  it('moves an item backward, shifting the rest', () => {
+    expect(moveItem(['a', 'b', 'c', 'd'], 3, 1)).toEqual(['a', 'd', 'b', 'c']);
+  });
+
+  it('is a no-op (order preserved) when from equals to', () => {
+    expect(moveItem(['a', 'b', 'c'], 1, 1)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('does not mutate the input', () => {
+    const input = ['a', 'b', 'c'];
+    moveItem(input, 0, 2);
+    expect(input).toEqual(['a', 'b', 'c']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/layersDnd.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/layersDnd.ts
new file mode 100644
index 00000000000..1328ea5c455
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/layersDnd.ts
@@ -0,0 +1,18 @@
+/**
+ * Pure array move used by the layers panel's grouped drag-to-reorder and its
+ * context-menu z-arrange commands (see `layerGroups.ts`, which maps a
+ * within-group move back onto the single global z-ordered `layers` array).
+ *
+ * Kept free of dnd-kit and React so the mapping is unit-testable in node.
+ */
+
+/** Moves the item at `fromIndex` to `toIndex`, shifting the others. Returns a new array. */
+export const moveItem = <T>(items: readonly T[], fromIndex: number, toIndex: number): T[] => {
+  const next = [...items];
+  const [moved] = next.splice(fromIndex, 1);
+  if (moved === undefined) {
+    return next;
+  }
+  next.splice(toIndex, 0, moved);
+  return next;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/psdExportNotice.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/psdExportNotice.test.ts
new file mode 100644
index 00000000000..1745639e9eb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/psdExportNotice.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPsdExportNoticeKey } from './psdExportNotice';
+
+describe('getPsdExportNoticeKey', () => {
+  it.each([
+    ['not-ready', 'widgets.layers.groupActions.exportNotReady'],
+    ['too-large', 'widgets.layers.groupActions.exportTooLarge'],
+    ['nothing', 'widgets.layers.groupActions.exportNothing'],
+    ['over-budget', 'widgets.layers.groupActions.exportOverBudget'],
+    ['stale', 'widgets.layers.groupActions.exportStale'],
+    ['aborted', 'widgets.layers.groupActions.exportAborted'],
+    ['exported', null],
+  ] as const)('maps %s to a user-visible typed notice', (result, expected) => {
+    expect(getPsdExportNoticeKey(result)).toBe(expected);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/psdExportNotice.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/psdExportNotice.ts
new file mode 100644
index 00000000000..3a9de715b3c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/psdExportNotice.ts
@@ -0,0 +1,28 @@
+import type { PsdExportResult } from '@workbench/canvas-engine/api';
+
+export type PsdExportNoticeKey =
+  | 'widgets.layers.groupActions.exportNotReady'
+  | 'widgets.layers.groupActions.exportTooLarge'
+  | 'widgets.layers.groupActions.exportNothing'
+  | 'widgets.layers.groupActions.exportOverBudget'
+  | 'widgets.layers.groupActions.exportStale'
+  | 'widgets.layers.groupActions.exportAborted';
+
+export const getPsdExportNoticeKey = (result: PsdExportResult): PsdExportNoticeKey | null => {
+  switch (result) {
+    case 'exported':
+      return null;
+    case 'not-ready':
+      return 'widgets.layers.groupActions.exportNotReady';
+    case 'too-large':
+      return 'widgets.layers.groupActions.exportTooLarge';
+    case 'nothing':
+      return 'widgets.layers.groupActions.exportNothing';
+    case 'over-budget':
+      return 'widgets.layers.groupActions.exportOverBudget';
+    case 'stale':
+      return 'widgets.layers.groupActions.exportStale';
+    case 'aborted':
+      return 'widgets.layers.groupActions.exportAborted';
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/runLayerWorkflow.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/runLayerWorkflow.test.ts
new file mode 100644
index 00000000000..97342e4b109
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/runLayerWorkflow.test.ts
@@ -0,0 +1,365 @@
+import type { CommitGeneratedImageResult, LayerExportGuard } from '@workbench/canvas-engine/engine';
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { WorkflowImageBinding } from '@workbench/workflows/layerWorkflow';
+import type { InvocationTemplatesSnapshot } from '@workbench/workflows/templates';
+import type { ProjectGraphState } from '@workbench/workflows/types';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  runLayerWorkflow,
+  type LayerWorkflowDestination,
+  type RunLayerWorkflowDeps,
+  type RunLayerWorkflowOptions,
+} from './runLayerWorkflow';
+
+const guard = {
+  cacheVersion: 1,
+  documentGeneration: 2,
+  layer: { id: 'layer-1' },
+  layerId: 'layer-1',
+  projectId: 'project-1',
+} as LayerExportGuard;
+const document = { id: 'workflow-1' } as ProjectGraphState;
+const templatesSnapshot = { error: null, status: 'loaded', templates: {} } as InvocationTemplatesSnapshot;
+const input: WorkflowImageBinding = { fieldName: 'image', label: 'Input · Image', nodeId: 'input-node' };
+const output: WorkflowImageBinding = { fieldName: 'image', label: 'Output · Image', nodeId: 'output-node' };
+const sourceBlob = new Blob(['source'], { type: 'image/png' });
+const image: GalleryImage = {
+  boardId: 'none',
+  height: 160,
+  imageCategory: 'other',
+  imageName: 'workflow-output.png',
+  imageUrl: '/full/workflow-output.png',
+  queuedAt: '2026-07-09T12:00:00.000Z',
+  sourceQueueItemId: 'backend-gallery',
+  starred: false,
+  thumbnailUrl: '/thumb/workflow-output.png',
+  width: 240,
+};
+
+const createDeps = () => {
+  const order: string[] = [];
+  const deps: RunLayerWorkflowDeps = {
+    appendStaging: vi.fn(() => order.push('append-staging')),
+    buildGraph: vi.fn(() => {
+      order.push('build-graph');
+      return { graph: { edges: [], id: 'layer-workflow', nodes: {} }, outputNodeId: 'capture' };
+    }),
+    commitGenerated: vi.fn(() => {
+      order.push('commit-generated');
+      return Promise.resolve<CommitGeneratedImageResult>({ layerId: 'result-layer', status: 'committed' });
+    }),
+    createRequestId: vi.fn(() => 'request-7'),
+    exportLayer: vi.fn<RunLayerWorkflowDeps['exportLayer']>(() => {
+      order.push('export');
+      return Promise.resolve({ blob: sourceBlob, guard, rect: { height: 60, width: 80, x: 11, y: 22 }, status: 'ok' });
+    }),
+    getImage: vi.fn(() => {
+      order.push('get-image');
+      return Promise.resolve(image);
+    }),
+    isGuardCurrent: vi.fn(() => true),
+    makeDurable: vi.fn(() => {
+      order.push('make-durable');
+      return Promise.resolve();
+    }),
+    runGraph: vi.fn<RunLayerWorkflowDeps['runGraph']>(() => {
+      order.push('run-graph');
+      return Promise.resolve({ imageName: image.imageName, origin: 'webv2:util:test' });
+    }),
+    saveToGallery: vi.fn<RunLayerWorkflowDeps['saveToGallery']>(() => {
+      order.push('save-gallery');
+      return Promise.resolve({ ...image, imageCategory: 'general' as const });
+    }),
+    touchGallery: vi.fn(() => order.push('touch-gallery')),
+    uploadIntermediate: vi.fn(() => {
+      order.push('upload');
+      return Promise.resolve({ imageName: 'layer-input.png' });
+    }),
+  };
+  return { deps, order };
+};
+
+const createOptions = (
+  destination: LayerWorkflowDestination,
+  deps: RunLayerWorkflowDeps,
+  signal?: AbortSignal
+): RunLayerWorkflowOptions => ({
+  deps,
+  destination,
+  document,
+  input,
+  layerId: 'layer-1',
+  output,
+  projectId: 'project-1',
+  signal,
+  templatesSnapshot,
+});
+
+describe('runLayerWorkflow', () => {
+  it('runs the captured output to Gallery and refreshes the captured project', async () => {
+    const { deps, order } = createDeps();
+
+    await expect(runLayerWorkflow(createOptions('gallery', deps))).resolves.toEqual({
+      imageName: image.imageName,
+      status: 'completed',
+    });
+
+    expect(order).toEqual([
+      'export',
+      'upload',
+      'build-graph',
+      'run-graph',
+      'get-image',
+      'save-gallery',
+      'touch-gallery',
+    ]);
+    expect(deps.buildGraph).toHaveBeenCalledWith({
+      document,
+      imageName: 'layer-input.png',
+      input,
+      output,
+      templatesSnapshot,
+    });
+    expect(deps.touchGallery).toHaveBeenCalledWith('project-1');
+    expect(deps.makeDurable).not.toHaveBeenCalled();
+  });
+
+  it('appends a durable orphan staging candidate at the source origin and native result dimensions', async () => {
+    const { deps, order } = createDeps();
+
+    await expect(runLayerWorkflow(createOptions('staging', deps))).resolves.toEqual({
+      imageName: image.imageName,
+      status: 'completed',
+    });
+
+    expect(order).toEqual([
+      'export',
+      'upload',
+      'build-graph',
+      'run-graph',
+      'get-image',
+      'make-durable',
+      'append-staging',
+    ]);
+    expect(deps.appendStaging).toHaveBeenCalledWith('project-1', {
+      ...image,
+      placement: { height: 160, opacity: 1, width: 240, x: 11, y: 22 },
+      sourceQueueItemId: 'layer-workflow:request-7',
+    });
+  });
+
+  it.each([
+    ['replace', 'replace'],
+    ['copy-raster', 'copy-raster'],
+  ] as const)('promotes then commits the %s destination', async (destination, target) => {
+    const { deps, order } = createDeps();
+
+    await expect(runLayerWorkflow(createOptions(destination, deps))).resolves.toEqual({
+      imageName: image.imageName,
+      status: 'completed',
+    });
+
+    expect(order).toEqual([
+      'export',
+      'upload',
+      'build-graph',
+      'run-graph',
+      'get-image',
+      'make-durable',
+      'commit-generated',
+    ]);
+    expect(deps.commitGenerated).toHaveBeenCalledWith({
+      guard,
+      image: { height: image.height, imageName: image.imageName, width: image.width },
+      origin: { x: 11, y: 22 },
+      signal: undefined,
+      target,
+    });
+  });
+
+  it.each(['missing', 'disabled', 'unsupported', 'empty', 'not-ready'] as const)(
+    'maps an export %s result without starting the workflow',
+    async (status) => {
+      const { deps } = createDeps();
+      vi.mocked(deps.exportLayer).mockResolvedValue({ status });
+
+      await expect(runLayerWorkflow(createOptions('gallery', deps))).resolves.toEqual({ status });
+
+      expect(deps.uploadIntermediate).not.toHaveBeenCalled();
+    }
+  );
+
+  it('stops with stale after hydration when the source guard changed', async () => {
+    const { deps } = createDeps();
+    vi.mocked(deps.isGuardCurrent).mockReturnValueOnce(true).mockReturnValueOnce(true).mockReturnValueOnce(false);
+
+    await expect(runLayerWorkflow(createOptions('staging', deps))).resolves.toEqual({ status: 'stale' });
+
+    expect(deps.makeDurable).not.toHaveBeenCalled();
+    expect(deps.appendStaging).not.toHaveBeenCalled();
+  });
+
+  it('does not append staging when the guard changes during durability', async () => {
+    const { deps } = createDeps();
+    vi.mocked(deps.isGuardCurrent).mockImplementation(() => vi.mocked(deps.makeDurable).mock.calls.length === 0);
+
+    await expect(runLayerWorkflow(createOptions('staging', deps))).resolves.toEqual({ status: 'stale' });
+
+    expect(deps.makeDurable).toHaveBeenCalledOnce();
+    expect(deps.appendStaging).not.toHaveBeenCalled();
+  });
+
+  it('checks cancellation at every async boundary and forwards the signal', async () => {
+    const controller = new AbortController();
+    const { deps } = createDeps();
+    vi.mocked(deps.getImage).mockImplementation((_imageName, signal) => {
+      expect(signal).toBe(controller.signal);
+      controller.abort();
+      return Promise.resolve(image);
+    });
+
+    await expect(runLayerWorkflow(createOptions('staging', deps, controller.signal))).resolves.toEqual({
+      status: 'aborted',
+    });
+
+    expect(deps.uploadIntermediate).toHaveBeenCalledWith(sourceBlob, controller.signal);
+    expect(deps.runGraph).toHaveBeenCalledWith(
+      expect.objectContaining({ outputNodeId: 'capture', signal: controller.signal })
+    );
+    expect(deps.makeDurable).not.toHaveBeenCalled();
+  });
+
+  it.each(['export', 'upload', 'run', 'hydrate', 'durability'] as const)(
+    'stops routing when canceled during %s',
+    async (boundary) => {
+      const controller = new AbortController();
+      const { deps } = createDeps();
+
+      if (boundary === 'export') {
+        vi.mocked(deps.exportLayer).mockImplementation(() => {
+          controller.abort();
+          return Promise.resolve({
+            blob: sourceBlob,
+            guard,
+            rect: { height: 60, width: 80, x: 11, y: 22 },
+            status: 'ok',
+          });
+        });
+      } else if (boundary === 'upload') {
+        vi.mocked(deps.uploadIntermediate).mockImplementation(() => {
+          controller.abort();
+          return Promise.resolve({ imageName: 'layer-input.png' });
+        });
+      } else if (boundary === 'run') {
+        vi.mocked(deps.runGraph).mockImplementation(() => {
+          controller.abort();
+          return Promise.resolve({ imageName: image.imageName, origin: 'webv2:util:test' });
+        });
+      } else if (boundary === 'hydrate') {
+        vi.mocked(deps.getImage).mockImplementation(() => {
+          controller.abort();
+          return Promise.resolve(image);
+        });
+      } else {
+        vi.mocked(deps.makeDurable).mockImplementation(() => {
+          controller.abort();
+          return Promise.resolve();
+        });
+      }
+
+      await expect(runLayerWorkflow(createOptions('staging', deps, controller.signal))).resolves.toEqual({
+        status: 'aborted',
+      });
+      expect(deps.appendStaging).not.toHaveBeenCalled();
+      expect(deps.commitGenerated).not.toHaveBeenCalled();
+    }
+  );
+
+  it('does not route when durability promotion fails', async () => {
+    const { deps } = createDeps();
+    vi.mocked(deps.makeDurable).mockRejectedValue(new Error('promotion failed'));
+
+    await expect(runLayerWorkflow(createOptions('staging', deps))).resolves.toEqual({
+      message: 'promotion failed',
+      stage: 'durability',
+      status: 'failed',
+    });
+    expect(deps.appendStaging).not.toHaveBeenCalled();
+  });
+
+  it('does not refresh Gallery when saving the output fails', async () => {
+    const { deps } = createDeps();
+    vi.mocked(deps.saveToGallery).mockRejectedValue(new Error('save failed'));
+
+    await expect(runLayerWorkflow(createOptions('gallery', deps))).resolves.toEqual({
+      message: 'save failed',
+      stage: 'gallery',
+      status: 'failed',
+    });
+    expect(deps.touchGallery).not.toHaveBeenCalled();
+  });
+
+  it('preserves an authoritative successful engine commit after a late abort', async () => {
+    const controller = new AbortController();
+    const { deps } = createDeps();
+    vi.mocked(deps.commitGenerated).mockImplementation(() => {
+      controller.abort();
+      return Promise.resolve({ layerId: 'result-layer', status: 'committed' });
+    });
+
+    await expect(runLayerWorkflow(createOptions('replace', deps, controller.signal))).resolves.toEqual({
+      imageName: image.imageName,
+      status: 'completed',
+    });
+  });
+
+  it.each(['missing', 'locked', 'stale', 'unsupported', 'busy', 'aborted'] as const)(
+    'maps a generated-image commit %s result',
+    async (status) => {
+      const { deps } = createDeps();
+      vi.mocked(deps.commitGenerated).mockResolvedValue({ status });
+
+      await expect(runLayerWorkflow(createOptions('replace', deps))).resolves.toEqual({ status });
+    }
+  );
+
+  it('maps generated-image commit failures and unexpected API failures', async () => {
+    const commit = createDeps();
+    vi.mocked(commit.deps.commitGenerated).mockResolvedValue({ message: 'draw failed', status: 'failed' });
+    await expect(runLayerWorkflow(createOptions('replace', commit.deps))).resolves.toEqual({
+      message: 'draw failed',
+      stage: 'commit',
+      status: 'failed',
+    });
+
+    const hydrate = createDeps();
+    vi.mocked(hydrate.deps.getImage).mockRejectedValue(new Error('metadata failed'));
+    await expect(runLayerWorkflow(createOptions('gallery', hydrate.deps))).resolves.toEqual({
+      message: 'metadata failed',
+      stage: 'hydrate',
+      status: 'failed',
+    });
+  });
+
+  it('identifies graph-build failures for specific UI feedback', async () => {
+    const { deps } = createDeps();
+    vi.mocked(deps.buildGraph).mockImplementation(() => {
+      throw new Error('workflow is not ready');
+    });
+
+    await expect(runLayerWorkflow(createOptions('gallery', deps))).resolves.toEqual({
+      message: 'workflow is not ready',
+      stage: 'graph',
+      status: 'failed',
+    });
+  });
+
+  it('maps AbortError failures to aborted', async () => {
+    const { deps } = createDeps();
+    vi.mocked(deps.runGraph).mockRejectedValue(new DOMException('canceled', 'AbortError'));
+
+    await expect(runLayerWorkflow(createOptions('gallery', deps))).resolves.toEqual({ status: 'aborted' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/runLayerWorkflow.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/runLayerWorkflow.ts
new file mode 100644
index 00000000000..cd3e04c5301
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/runLayerWorkflow.ts
@@ -0,0 +1,216 @@
+import type {
+  CommitGeneratedImageOptions,
+  CommitGeneratedImageResult,
+  ExportBakedLayerBlobResult,
+  LayerExportGuard,
+} from '@workbench/canvas-engine/engine';
+import type { RunUtilityGraphOptions, UtilityGraphResult } from '@workbench/canvas-operations/backend/utilityQueue';
+import type { GalleryImage } from '@workbench/gallery/api';
+import type { CanvasStagingCandidateContract } from '@workbench/types';
+import type {
+  BuildLayerWorkflowGraphOptions,
+  BuiltLayerWorkflowGraph,
+  LayerWorkflowDestination,
+  WorkflowImageBinding,
+} from '@workbench/workflows/layerWorkflow';
+import type { InvocationTemplatesSnapshot } from '@workbench/workflows/templates';
+import type { ProjectGraphState } from '@workbench/workflows/types';
+
+export type { LayerWorkflowDestination } from '@workbench/workflows/layerWorkflow';
+
+export type LayerWorkflowFailureStage =
+  | 'export'
+  | 'upload'
+  | 'graph'
+  | 'hydrate'
+  | 'durability'
+  | 'gallery'
+  | 'staging'
+  | 'commit';
+
+export type RunLayerWorkflowResult =
+  | { status: 'completed'; imageName: string }
+  | {
+      status:
+        | 'aborted'
+        | 'missing'
+        | 'disabled'
+        | 'unsupported'
+        | 'empty'
+        | 'not-ready'
+        | 'over-budget'
+        | 'locked'
+        | 'stale'
+        | 'busy';
+    }
+  | { status: 'failed'; message: string; stage: LayerWorkflowFailureStage };
+
+export interface RunLayerWorkflowDeps {
+  exportLayer(layerId: string): Promise<ExportBakedLayerBlobResult>;
+  uploadIntermediate(blob: Blob, signal?: AbortSignal): Promise<{ imageName: string }>;
+  buildGraph(options: BuildLayerWorkflowGraphOptions): BuiltLayerWorkflowGraph;
+  runGraph(
+    options: Pick<RunUtilityGraphOptions, 'graph' | 'outputNodeId' | 'signal'>
+  ): Promise<Pick<UtilityGraphResult, 'imageName' | 'origin'>>;
+  getImage(imageName: string, signal?: AbortSignal): Promise<GalleryImage>;
+  makeDurable(imageName: string): Promise<void>;
+  saveToGallery(imageName: string): Promise<GalleryImage>;
+  touchGallery(projectId: string): void;
+  appendStaging(projectId: string, candidate: CanvasStagingCandidateContract): void;
+  commitGenerated(options: CommitGeneratedImageOptions): Promise<CommitGeneratedImageResult>;
+  isGuardCurrent(guard: LayerExportGuard): boolean;
+  createRequestId(): string;
+}
+
+export interface RunLayerWorkflowOptions {
+  layerId: string;
+  projectId: string;
+  document: ProjectGraphState;
+  templatesSnapshot: InvocationTemplatesSnapshot;
+  input: WorkflowImageBinding;
+  output: WorkflowImageBinding;
+  destination: LayerWorkflowDestination;
+  signal?: AbortSignal;
+  deps: RunLayerWorkflowDeps;
+}
+
+const isAbortError = (error: unknown): boolean =>
+  typeof error === 'object' && error !== null && 'name' in error && error.name === 'AbortError';
+
+const messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+const stopped = (
+  signal: AbortSignal | undefined,
+  guard: LayerExportGuard,
+  isGuardCurrent: (guard: LayerExportGuard) => boolean
+): { status: 'aborted' | 'stale' } | null => {
+  if (signal?.aborted) {
+    return { status: 'aborted' };
+  }
+  if (!isGuardCurrent(guard)) {
+    return { status: 'stale' };
+  }
+  return null;
+};
+
+export const runLayerWorkflow = async (options: RunLayerWorkflowOptions): Promise<RunLayerWorkflowResult> => {
+  const { deps, signal } = options;
+  let failureStage: LayerWorkflowFailureStage = 'export';
+  if (signal?.aborted) {
+    return { status: 'aborted' };
+  }
+
+  try {
+    const exported = await deps.exportLayer(options.layerId);
+    if (signal?.aborted) {
+      return { status: 'aborted' };
+    }
+    if (exported.status !== 'ok') {
+      return exported;
+    }
+
+    let canceled = stopped(signal, exported.guard, deps.isGuardCurrent);
+    if (canceled) {
+      return canceled;
+    }
+
+    failureStage = 'upload';
+    const uploaded = await deps.uploadIntermediate(exported.blob, signal);
+    canceled = stopped(signal, exported.guard, deps.isGuardCurrent);
+    if (canceled) {
+      return canceled;
+    }
+
+    failureStage = 'graph';
+    const built = deps.buildGraph({
+      document: options.document,
+      imageName: uploaded.imageName,
+      input: options.input,
+      output: options.output,
+      templatesSnapshot: options.templatesSnapshot,
+    });
+    canceled = stopped(signal, exported.guard, deps.isGuardCurrent);
+    if (canceled) {
+      return canceled;
+    }
+
+    const output = await deps.runGraph({ graph: built.graph, outputNodeId: built.outputNodeId, signal });
+    canceled = stopped(signal, exported.guard, deps.isGuardCurrent);
+    if (canceled) {
+      return canceled;
+    }
+
+    failureStage = 'hydrate';
+    const image = await deps.getImage(output.imageName, signal);
+    canceled = stopped(signal, exported.guard, deps.isGuardCurrent);
+    if (canceled) {
+      return canceled;
+    }
+
+    if (options.destination === 'gallery') {
+      // Saving is itself the authoritative external mutation. Once it succeeds,
+      // refresh the captured project and report success even if the dialog closes
+      // in the same tick.
+      failureStage = 'gallery';
+      await deps.saveToGallery(image.imageName);
+      try {
+        deps.touchGallery(options.projectId);
+      } catch {
+        // Refresh is ancillary once the backend has authoritatively saved the image.
+      }
+      return { imageName: image.imageName, status: 'completed' };
+    }
+
+    failureStage = 'durability';
+    // Promotion must precede any canvas reference. If cancellation/staleness
+    // wins after this non-abortable PATCH, leave the output durable but
+    // unreferenced: arbitrary workflow outputs may echo/cache an existing image,
+    // and the image API has no ownership token or compare-and-swap with which to
+    // safely delete or mark it intermediate again.
+    await deps.makeDurable(image.imageName);
+    canceled = stopped(signal, exported.guard, deps.isGuardCurrent);
+    if (canceled) {
+      return canceled;
+    }
+
+    if (options.destination === 'staging') {
+      failureStage = 'staging';
+      deps.appendStaging(options.projectId, {
+        ...image,
+        placement: {
+          height: image.height,
+          opacity: 1,
+          width: image.width,
+          x: exported.rect.x,
+          y: exported.rect.y,
+        },
+        sourceQueueItemId: `layer-workflow:${deps.createRequestId()}`,
+      });
+      return { imageName: image.imageName, status: 'completed' };
+    }
+
+    failureStage = 'commit';
+    const committed = await deps.commitGenerated({
+      guard: exported.guard,
+      image: { height: image.height, imageName: image.imageName, width: image.width },
+      origin: { x: exported.rect.x, y: exported.rect.y },
+      signal,
+      target: options.destination,
+    });
+    // The engine performs the last abort/guard check immediately before its
+    // structural mutation. Preserve that authoritative result instead of
+    // relabeling a successful commit after a late dialog close.
+    if (committed.status === 'committed') {
+      return { imageName: image.imageName, status: 'completed' };
+    }
+    if (committed.status === 'failed') {
+      return { ...committed, stage: 'commit' };
+    }
+    return committed;
+  } catch (error) {
+    if (signal?.aborted || isAbortError(error)) {
+      return { status: 'aborted' };
+    }
+    return { message: messageOf(error), stage: failureStage, status: 'failed' };
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/selectedModel.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/selectedModel.ts
new file mode 100644
index 00000000000..bcd3489d094
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/selectedModel.ts
@@ -0,0 +1,8 @@
+import type { Project } from '@workbench/types';
+
+import { getProjectWidgetValues } from '@workbench/widgetState';
+
+export const getSelectedModelBase = (project: Project): string | null => {
+  const model = getProjectWidgetValues(project, 'generate').model;
+  return model && typeof model === 'object' && 'base' in model && typeof model.base === 'string' ? model.base : null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/useAddLayer.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/useAddLayer.ts
new file mode 100644
index 00000000000..161122178b0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/useAddLayer.ts
@@ -0,0 +1,108 @@
+import { useCanvasProjectMutationDispatch } from '@workbench/useCanvasProjectMutationDispatch';
+import { useCanvasEngine } from '@workbench/widgets/canvas/useCanvasEngine';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { nextLayerName } from '@workbench/workbenchState';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { AddLayerItemId } from './addLayerMenu';
+
+import {
+  applyStructural,
+  createControlLayer,
+  createEmptyPaintLayer,
+  createInpaintMaskLayer,
+  createRegionalGuidanceLayer,
+  createRegionalGuidanceLayerWithRefImage,
+  nextControlLayerName,
+  nextInpaintMaskName,
+  nextRegionalGuidanceName,
+} from './layerOps';
+import { useSelectedModelBase } from './useSelectedModelBase';
+
+/**
+ * Returns a single `addLayer(id)` callback that creates a new layer of the given
+ * kind at the top of the stack via the shared `applyStructural` seam (one undoable
+ * history entry per add). Reused by the panel's add-layer menu AND each group
+ * header's "New" button so both surfaces stay in lockstep.
+ */
+export const useAddLayer = (): ((id: AddLayerItemId) => void) => {
+  const { t } = useTranslation();
+  const engine = useCanvasEngine();
+  const dispatch = useCanvasProjectMutationDispatch();
+  const base = useSelectedModelBase();
+  const layerNames = useActiveProjectSelector(
+    (project) => project.canvas.document.layers.map((layer) => layer.name),
+    (left, right) => left.length === right.length && left.every((name, index) => name === right[index])
+  );
+  const regionalGuidanceCount = useActiveProjectSelector(
+    (project) => project.canvas.document.layers.filter((layer) => layer.type === 'regional_guidance').length
+  );
+
+  return useCallback(
+    (id: AddLayerItemId) => {
+      switch (id) {
+        case 'raster': {
+          const layer = createEmptyPaintLayer(nextLayerName(layerNames));
+          applyStructural(
+            engine,
+            dispatch,
+            t('widgets.layers.actions.addRasterLayer'),
+            { index: 0, layer, type: 'addCanvasLayer' },
+            { ids: [layer.id], type: 'removeCanvasLayers' }
+          );
+          return;
+        }
+        case 'control': {
+          const layer = createControlLayer(nextControlLayerName(layerNames), undefined, base);
+          applyStructural(
+            engine,
+            dispatch,
+            t('widgets.layers.actions.addControlLayer'),
+            { index: 0, layer, type: 'addCanvasLayer' },
+            { ids: [layer.id], type: 'removeCanvasLayers' }
+          );
+          return;
+        }
+        case 'inpaint_mask': {
+          const layer = createInpaintMaskLayer(nextInpaintMaskName(layerNames));
+          applyStructural(
+            engine,
+            dispatch,
+            t('widgets.layers.actions.addInpaintMask'),
+            { index: 0, layer, type: 'addCanvasLayer' },
+            { ids: [layer.id], type: 'removeCanvasLayers' }
+          );
+          return;
+        }
+        case 'regional_guidance': {
+          const layer = createRegionalGuidanceLayer(nextRegionalGuidanceName(layerNames), regionalGuidanceCount);
+          applyStructural(
+            engine,
+            dispatch,
+            t('widgets.layers.actions.addRegionalGuidance'),
+            { index: 0, layer, type: 'addCanvasLayer' },
+            { ids: [layer.id], type: 'removeCanvasLayers' }
+          );
+          return;
+        }
+        case 'regional_reference_image': {
+          const layer = createRegionalGuidanceLayerWithRefImage(
+            nextRegionalGuidanceName(layerNames),
+            regionalGuidanceCount,
+            base
+          );
+          applyStructural(
+            engine,
+            dispatch,
+            t('widgets.layers.actions.addRegionalReferenceImage'),
+            { index: 0, layer, type: 'addCanvasLayer' },
+            { ids: [layer.id], type: 'removeCanvasLayers' }
+          );
+          return;
+        }
+      }
+    },
+    [base, dispatch, engine, layerNames, regionalGuidanceCount, t]
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/layers/useSelectedModelBase.ts b/invokeai/frontend/webv2/src/workbench/widgets/layers/useSelectedModelBase.ts
new file mode 100644
index 00000000000..b1cbf3b0c8d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/layers/useSelectedModelBase.ts
@@ -0,0 +1,13 @@
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+
+import { getSelectedModelBase } from './selectedModel';
+
+/**
+ * The main model's base (`sd-1` / `sdxl` / `flux` / …), read from the generate
+ * widget values. Drives which control-adapter kinds and reference-image kinds a
+ * region can consume. Shared by the control/regional settings and the add-layer
+ * flow so a freshly created "regional reference image" mints the base-correct kind.
+ */
+export const useSelectedModelBase = (): string | null => {
+  return useActiveProjectSelector(getSelectedModelBase);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/notifications/NotificationsHeaderActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/notifications/NotificationsHeaderActions.tsx
new file mode 100644
index 00000000000..c4110ef46d9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/notifications/NotificationsHeaderActions.tsx
@@ -0,0 +1,23 @@
+import { HStack } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export const NotificationsHeaderActions = () => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const markAllRead = useCallback(() => dispatch({ type: 'markAllNotificationsRead' }), [dispatch]);
+  const clearNotifications = useCallback(() => dispatch({ type: 'clearNotifications' }), [dispatch]);
+
+  return (
+    <HStack gap="2">
+      <Button size="2xs" variant="outline" onClick={markAllRead}>
+        {t('notifications.markRead')}
+      </Button>
+      <Button size="2xs" variant="outline" onClick={clearNotifications}>
+        {t('common.clear')}
+      </Button>
+    </HStack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/notifications/NotificationsWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/notifications/NotificationsWidgetView.tsx
new file mode 100644
index 00000000000..38ab8a934a3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/notifications/NotificationsWidgetView.tsx
@@ -0,0 +1,92 @@
+import type { WidgetViewProps, WorkbenchNotificationKind } from '@workbench/types';
+
+import { Badge, HStack, Icon, Stack, Text } from '@chakra-ui/react';
+import { StatusWidgetChip } from '@workbench/widget-frame';
+import { useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { BellIcon, CircleCheckIcon, CircleXIcon, InfoIcon, TriangleAlertIcon, type LucideIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+const kindColorPalette: Record<WorkbenchNotificationKind, string> = {
+  error: 'red',
+  info: 'blue',
+  success: 'green',
+};
+
+const kindIcon = {
+  error: CircleXIcon,
+  info: InfoIcon,
+  success: CircleCheckIcon,
+} satisfies Record<WorkbenchNotificationKind, LucideIcon>;
+
+export const NotificationsWidgetView = ({ presentation, region }: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const { errorCount, totalCount, unreadCount } = useWorkbenchSelector((snapshot) => ({
+    errorCount: snapshot.state.notifications.filter((notification) => notification.kind === 'error').length,
+    totalCount: snapshot.state.notifications.length,
+    unreadCount: snapshot.state.notifications.filter((notification) => !notification.isRead).length,
+  }));
+  const label =
+    unreadCount > 0
+      ? t('notifications.newCount', { count: unreadCount })
+      : t('notifications.totalCount', { count: totalCount });
+  const icon = errorCount > 0 ? TriangleAlertIcon : BellIcon;
+
+  if (region === 'bottom' && presentation !== 'expanded') {
+    return <StatusWidgetChip icon={icon}>{t('notifications.labelWithCount', { label })}</StatusWidgetChip>;
+  }
+
+  return <NotificationsPanel />;
+};
+
+const NotificationsPanel = () => {
+  const { t } = useTranslation();
+  const notifications = useWorkbenchSelector((snapshot) => snapshot.state.notifications);
+
+  return (
+    <Stack flex="1" gap="3" minH="0" p="2">
+      {notifications.length === 0 ? (
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('notifications.empty')}
+        </Text>
+      ) : (
+        <Stack gap="2">
+          {notifications.map((notification) => {
+            const IconComponent = kindIcon[notification.kind];
+
+            return (
+              <Stack
+                key={notification.id}
+                bg={notification.isRead ? 'bg.subtle' : 'bg.muted'}
+                borderWidth="1px"
+                borderColor={notification.isRead ? 'border.subtle' : 'border.emphasized'}
+                gap="1"
+                p="2"
+                rounded="md"
+              >
+                <HStack align="start" justify="space-between">
+                  <HStack gap="2" minW="0">
+                    <Icon as={IconComponent} color={`${kindColorPalette[notification.kind]}.300`} boxSize="3.5" />
+                    <Text fontSize="2xs" fontWeight="700">
+                      {notification.title}
+                    </Text>
+                  </HStack>
+                  <Badge colorPalette={kindColorPalette[notification.kind]} size="xs">
+                    {t(`notifications.kind.${notification.kind}`)}
+                  </Badge>
+                </HStack>
+                {notification.message ? (
+                  <Text color="fg.subtle" fontSize="2xs">
+                    {notification.message}
+                  </Text>
+                ) : null}
+                <Text color="fg.subtle" fontSize="2xs">
+                  {notification.createdAt}
+                </Text>
+              </Stack>
+            );
+          })}
+        </Stack>
+      )}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/notifications/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/notifications/index.ts
new file mode 100644
index 00000000000..a979808c1e0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/notifications/index.ts
@@ -0,0 +1,19 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { BellIcon } from 'lucide-react';
+
+import { NotificationsHeaderActions } from './NotificationsHeaderActions';
+import { NotificationsWidgetView } from './NotificationsWidgetView';
+
+export const notificationsWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['bottom'],
+  bottomPanel: 'expandable',
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  headerActions: NotificationsHeaderActions,
+  icon: BellIcon,
+  id: 'notifications',
+  label: (t) => t('widgets.labels.notifications'),
+  version: 1,
+  view: NotificationsWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewCompare.tsx b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewCompare.tsx
new file mode 100644
index 00000000000..821ea7587df
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewCompare.tsx
@@ -0,0 +1,216 @@
+import type { GeneratedImageContract, WidgetRuntimeApi } from '@workbench/types';
+
+import { Badge, Box, Flex, HStack, Stack } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { ArrowLeftRightIcon, Columns2Icon, XIcon } from 'lucide-react';
+import {
+  useCallback,
+  useEffect,
+  useEffectEvent,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type PointerEvent,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+
+type CompareMode = 'slider' | 'side-by-side';
+
+const COMPARE_IMAGE_STYLE: CSSProperties = {
+  display: 'block',
+  height: '100%',
+  inset: 0,
+  objectFit: 'contain',
+  pointerEvents: 'none',
+  position: 'absolute',
+  userSelect: 'none',
+  width: '100%',
+};
+
+const previewGridCss = {
+  backgroundImage: 'radial-gradient(circle, currentColor 1px, transparent 1.5px)',
+  backgroundPosition: 'center',
+  backgroundRepeat: 'repeat',
+  backgroundSize: '24px 24px',
+} as const;
+
+const sliderTouchStyle = { touchAction: 'none' } as const;
+
+/**
+ * Two-image comparison: a draggable slider that reveals the compare image over
+ * the selected one, or a side-by-side split.
+ */
+export const PreviewCompare = ({
+  baseImage,
+  compareImage,
+  onExit,
+  onSwap,
+  runtime,
+}: {
+  baseImage: GeneratedImageContract;
+  compareImage: GeneratedImageContract;
+  onExit: () => void;
+  onSwap: () => void;
+  runtime: WidgetRuntimeApi;
+}) => {
+  const { t } = useTranslation();
+  const [mode, setMode] = useState<CompareMode>('slider');
+  const [dividerPercent, setDividerPercent] = useState(50);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const isDraggingRef = useRef(false);
+  const nextMode = useEffectEvent(() => setMode((current) => (current === 'slider' ? 'side-by-side' : 'slider')));
+  const nextComparisonModeLabel = t('widgets.preview.commands.nextComparisonMode');
+
+  useEffect(() => {
+    const command = runtime.commands.register({
+      handler: nextMode,
+      id: 'viewer.nextComparisonMode',
+      title: nextComparisonModeLabel,
+    });
+    const hotkey = runtime.hotkeys.register({
+      commandId: 'viewer.nextComparisonMode',
+      defaultKeys: ['m'],
+      id: 'viewer.nextComparisonMode',
+      title: nextComparisonModeLabel,
+    });
+
+    return () => {
+      command();
+      hotkey();
+    };
+  }, [nextComparisonModeLabel, runtime.commands, runtime.hotkeys]);
+
+  const updateDivider = useCallback((clientX: number) => {
+    const rect = containerRef.current?.getBoundingClientRect();
+
+    if (!rect || rect.width === 0) {
+      return;
+    }
+
+    setDividerPercent(Math.min(100, Math.max(0, ((clientX - rect.left) / rect.width) * 100)));
+  }, []);
+  const handlePointerDown = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (event.pointerType === 'mouse' && event.button !== 0) {
+        return;
+      }
+
+      event.preventDefault();
+      isDraggingRef.current = true;
+      event.currentTarget.setPointerCapture(event.pointerId);
+      updateDivider(event.clientX);
+    },
+    [updateDivider]
+  );
+  const handlePointerMove = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (isDraggingRef.current) {
+        event.preventDefault();
+        updateDivider(event.clientX);
+      }
+    },
+    [updateDivider]
+  );
+  const endDrag = useCallback((event?: PointerEvent<HTMLDivElement>) => {
+    if (event?.currentTarget.hasPointerCapture(event.pointerId)) {
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    }
+
+    isDraggingRef.current = false;
+  }, []);
+  const toggleMode = useCallback(() => setMode((current) => (current === 'slider' ? 'side-by-side' : 'slider')), []);
+  const clipStyle = useMemo(() => ({ clipPath: `inset(0 ${100 - dividerPercent}% 0 0)` }), [dividerPercent]);
+
+  return (
+    <Stack gap="3" h="full" minH="0" w="full">
+      <Flex
+        align="center"
+        backgroundColor="bg.inset"
+        borderWidth="1px"
+        borderColor="border.subtle"
+        color="fg.grid"
+        css={previewGridCss}
+        flex="1"
+        justify="center"
+        minH="0"
+        overflow="hidden"
+        p="6"
+        rounded="lg"
+        w="full"
+      >
+        {mode === 'slider' ? (
+          <Box
+            ref={containerRef}
+            bg="transparent"
+            cursor="ew-resize"
+            h="full"
+            overflow="hidden"
+            position="relative"
+            style={sliderTouchStyle}
+            w="full"
+            onPointerDown={handlePointerDown}
+            onPointerMove={handlePointerMove}
+            onPointerUp={endDrag}
+            onPointerCancel={endDrag}
+            onLostPointerCapture={endDrag}
+          >
+            <img alt={baseImage.imageName} draggable={false} src={baseImage.imageUrl} style={COMPARE_IMAGE_STYLE} />
+            <Box bg="transparent" inset="0" pointerEvents="none" position="absolute" style={clipStyle}>
+              <img
+                alt={compareImage.imageName}
+                draggable={false}
+                src={compareImage.imageUrl}
+                style={COMPARE_IMAGE_STYLE}
+              />
+            </Box>
+            <Box
+              bg="accent.solid"
+              bottom="0"
+              left={`${dividerPercent}%`}
+              pointerEvents="none"
+              position="absolute"
+              top="0"
+              transform="translateX(-50%)"
+              w="2px"
+            />
+            <Badge left="2" pointerEvents="none" position="absolute" size="xs" top="2" variant="solid">
+              {t('widgets.preview.compare')}
+            </Badge>
+            <Badge pointerEvents="none" position="absolute" right="2" size="xs" top="2" variant="solid">
+              {t('widgets.preview.viewing')}
+            </Badge>
+          </Box>
+        ) : (
+          <HStack gap="2" h="full" minH="0" w="full">
+            <CompareSidePane image={compareImage} label={t('widgets.preview.compare')} />
+            <CompareSidePane image={baseImage} label={t('widgets.preview.viewing')} />
+          </HStack>
+        )}
+      </Flex>
+      <HStack flexShrink={0} gap="1" justify="center">
+        <Button size="2xs" variant="outline" onClick={toggleMode}>
+          <Columns2Icon />
+          {mode === 'slider' ? t('widgets.preview.sideBySide') : t('widgets.preview.slider')}
+        </Button>
+        <Button size="2xs" variant="outline" onClick={onSwap}>
+          <ArrowLeftRightIcon />
+          {t('common.swap')}
+        </Button>
+        <Button size="2xs" variant="outline" onClick={onExit}>
+          <XIcon />
+          {t('widgets.preview.exitCompare')}
+        </Button>
+      </HStack>
+    </Stack>
+  );
+};
+
+const CompareSidePane = ({ image, label }: { image: GeneratedImageContract; label: string }) => (
+  <Box bg="transparent" flex="1" h="full" minW="0" overflow="hidden" position="relative">
+    <img alt={image.imageName} draggable={false} src={image.imageUrl} style={COMPARE_IMAGE_STYLE} />
+    <Badge left="2" pointerEvents="none" position="absolute" size="xs" top="2" variant="solid">
+      {label}
+    </Badge>
+  </Box>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewHeaderActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewHeaderActions.tsx
new file mode 100644
index 00000000000..0ad0d44f134
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewHeaderActions.tsx
@@ -0,0 +1,39 @@
+import { Icon } from '@chakra-ui/react';
+import { useProgressImage } from '@workbench/backend/progressImageStore';
+import { IconButton } from '@workbench/components/ui';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { HourglassIcon } from 'lucide-react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export const PreviewHeaderActions = () => {
+  const { t } = useTranslation();
+  const showProgressImagesInViewer = useActiveProjectSelector((project) => project.settings.showProgressImagesInViewer);
+  const hasProgressImage = useProgressImage() !== null;
+  const dispatch = useWorkbenchDispatch();
+  const label = showProgressImagesInViewer
+    ? t('widgets.preview.hideInProgressDiffusion')
+    : t('widgets.preview.showInProgressDiffusion');
+  const toggleProgressImages = useCallback(
+    () =>
+      dispatch({
+        settings: { showProgressImagesInViewer: !showProgressImagesInViewer },
+        type: 'setActiveProjectSettings',
+      }),
+    [dispatch, showProgressImagesInViewer]
+  );
+
+  return (
+    <IconButton
+      aria-label={label}
+      colorPalette={showProgressImagesInViewer ? 'accent' : 'gray'}
+      opacity={hasProgressImage || showProgressImagesInViewer ? 1 : 0.7}
+      size="2xs"
+      title={label}
+      variant={showProgressImagesInViewer ? 'solid' : 'ghost'}
+      onClick={toggleProgressImages}
+    >
+      <Icon as={HourglassIcon} boxSize="3.5" />
+    </IconButton>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewWidgetView.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewWidgetView.test.ts
new file mode 100644
index 00000000000..456a9b3ad97
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewWidgetView.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPreviewBoardsRequestKey } from './PreviewWidgetView';
+
+describe('getPreviewBoardsRequestKey', () => {
+  it('requests boards for local generated images, not only backend gallery images', () => {
+    expect(
+      getPreviewBoardsRequestKey({ hasSelectedImage: true, isBackendImage: false, refreshToken: 'refresh-1' })
+    ).toBe('refresh-1');
+  });
+
+  it('does not request boards without a selected image', () => {
+    expect(
+      getPreviewBoardsRequestKey({ hasSelectedImage: false, isBackendImage: false, refreshToken: 'refresh-1' })
+    ).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewWidgetView.tsx
new file mode 100644
index 00000000000..40f911fd454
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/preview/PreviewWidgetView.tsx
@@ -0,0 +1,668 @@
+/* eslint-disable react/react-compiler */
+import type { GeneratedImageContract, WidgetViewProps } from '@workbench/types';
+
+import { Badge, Box, Flex, HStack, Stack, Text } from '@chakra-ui/react';
+import { useProgressImage, type ProgressImageSnapshot } from '@workbench/backend/progressImageStore';
+import { Button } from '@workbench/components/ui';
+import {
+  listGalleryBoards,
+  listGalleryImages,
+  type GalleryBoard,
+  type GalleryImage,
+  type GalleryView,
+} from '@workbench/gallery/api';
+import { getGallerySettings } from '@workbench/gallery/settings';
+import { ImageContextMenu, useImageActions, type ImageContextMenuTarget } from '@workbench/image-actions';
+import { imageUrlToStreamingSource, progressImageToStreamingSource } from '@workbench/images/streamingImageSource';
+import { useStreamingImageSource } from '@workbench/images/useStreamingImageSource';
+import {
+  getGalleryCompareImage,
+  getGalleryImagesRefreshToken,
+  getGalleryRecentImagesKey,
+  getGalleryRefreshToken,
+} from '@workbench/widgets/gallery/galleryStateView';
+import { createGenerateFormValuesSelector } from '@workbench/widgets/generate/generateFormViewModel';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import {
+  useActiveProjectId,
+  useActiveProjectSelector,
+  useWidgetValuesSelector,
+  useWorkbenchDispatch,
+} from '@workbench/WorkbenchContext';
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import {
+  useCallback,
+  useEffect,
+  useEffectEvent,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type MouseEvent,
+  type CSSProperties,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { PreviewCompare } from './PreviewCompare';
+
+type PreviewImage = GeneratedImageContract & Partial<Pick<GalleryImage, 'boardId' | 'imageCategory' | 'starred'>>;
+
+const fallbackBoards: GalleryBoard[] = [
+  { archived: false, assetCount: 0, id: 'none', imageCount: 0, kind: 'uncategorized', name: 'Uncategorized' },
+];
+
+const getGalleryImages = (values: Record<string, unknown>): PreviewImage[] =>
+  Array.isArray(values.recentImages)
+    ? (values.recentImages as GeneratedImageContract[]).map((image) => ({
+        ...image,
+        boardId: 'none',
+        imageCategory: 'general' as const,
+      }))
+    : [];
+
+const getSelectedImage = (values: Record<string, unknown>): PreviewImage | null => {
+  const images = getGalleryImages(values);
+  const selectedImage = values.selectedImage;
+  const selectedImageName = typeof values.selectedImageName === 'string' ? values.selectedImageName : null;
+
+  if (
+    selectedImage &&
+    typeof selectedImage === 'object' &&
+    typeof (selectedImage as GeneratedImageContract).imageName === 'string'
+  ) {
+    return selectedImage as PreviewImage;
+  }
+
+  return images.find((image) => image.imageName === selectedImageName) ?? images[0] ?? null;
+};
+
+/**
+ * The board used for the "N of M" index comes from the image itself, never
+ * from the gallery's currently selected board — switching boards or changing
+ * the board list sort must not reshuffle the preview. Freshly generated local
+ * images (no boardId yet) fall back to the gallery selection for display only.
+ */
+const getImageBoardId = (image: PreviewImage): string => (typeof image.boardId === 'string' ? image.boardId : 'none');
+
+const getDisplayBoardId = (image: PreviewImage, values: Record<string, unknown>): string => {
+  if (typeof image.boardId === 'string') {
+    return image.boardId;
+  }
+
+  return typeof values.selectedBoardId === 'string' ? values.selectedBoardId : 'none';
+};
+
+const getImageGalleryView = (image: PreviewImage): GalleryView => {
+  if (
+    image.imageCategory === 'control' ||
+    image.imageCategory === 'mask' ||
+    image.imageCategory === 'user' ||
+    image.imageCategory === 'other'
+  ) {
+    return 'assets';
+  }
+
+  return 'images';
+};
+
+const getBoardName = (
+  boards: GalleryBoard[],
+  boardId: string,
+  uncategorizedLabel: string,
+  unknownBoardLabel: string
+): string =>
+  boardId === 'none' ? uncategorizedLabel : (boards.find((board) => board.id === boardId)?.name ?? unknownBoardLabel);
+
+const shouldLoadBackendBoard = (image: PreviewImage): boolean => image.sourceQueueItemId === 'backend-gallery';
+
+export const getPreviewBoardsRequestKey = ({
+  hasSelectedImage,
+  refreshToken,
+}: {
+  hasSelectedImage: boolean;
+  isBackendImage: boolean;
+  refreshToken: string;
+}): string | null => (hasSelectedImage ? refreshToken : null);
+
+const previewGridCss = {
+  backgroundImage: 'radial-gradient(circle, currentColor 1px, transparent 1.5px)',
+  backgroundPosition: 'center',
+  backgroundRepeat: 'repeat',
+  backgroundSize: '24px 24px',
+} as const;
+
+const selectGenerateRecallValues = createGenerateFormValuesSelector();
+
+export const PreviewWidgetView = ({ region, runtime }: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const galleryValues = useActiveProjectSelector((project) => getProjectWidgetValues(project, 'gallery'));
+  const generateValues = useWidgetValuesSelector('generate', selectGenerateRecallValues);
+  const { antialiasProgressImages, showProgressImagesInViewer } = useActiveProjectSelector(
+    (project) => project.settings
+  );
+  const progressImage = useProgressImage();
+  const dispatch = useWorkbenchDispatch();
+  const selectedImage = useMemo(() => getSelectedImage(galleryValues), [galleryValues]);
+  const compareImage = getGalleryCompareImage(galleryValues);
+  const recentImages = Array.isArray(galleryValues.recentImages) ? galleryValues.recentImages : null;
+  const localImages = useMemo(() => getGalleryImages({ recentImages }), [recentImages]);
+  const imageBoardId = selectedImage ? getImageBoardId(selectedImage) : 'none';
+  const displayBoardId = selectedImage ? getDisplayBoardId(selectedImage, galleryValues) : 'none';
+  const selectedGalleryView = selectedImage ? getImageGalleryView(selectedImage) : 'images';
+  const hasSelectedImage = selectedImage !== null;
+  const isBackendImage = selectedImage ? shouldLoadBackendBoard(selectedImage) : false;
+  const { imageOrderDir, starredFirst } = getGallerySettings(galleryValues);
+  const boardRefreshToken = getGalleryRefreshToken(galleryValues);
+  const imageRefreshToken = getGalleryImagesRefreshToken(galleryValues);
+  const recentImagesKey = getGalleryRecentImagesKey(galleryValues);
+  const [boards, setBoards] = useState<GalleryBoard[]>(fallbackBoards);
+  const [boardImages, setBoardImages] = useState<PreviewImage[]>(localImages);
+  const [isLoadingBoard, setIsLoadingBoard] = useState(false);
+  const isSidePanel = region === 'left' || region === 'right';
+  const selectedIndex = selectedImage
+    ? boardImages.findIndex((image) => image.imageName === selectedImage.imageName)
+    : -1;
+  const boardName = getBoardName(
+    boards,
+    displayBoardId,
+    t('widgets.gallery.uncategorized'),
+    t('widgets.gallery.unknownBoard')
+  );
+  const selectedImageRef = useRef(selectedImage);
+  const boardImagesRef = useRef(boardImages);
+
+  selectedImageRef.current = selectedImage;
+  boardImagesRef.current = boardImages;
+
+  const boardsRequestKey = getPreviewBoardsRequestKey({
+    hasSelectedImage,
+    isBackendImage,
+    refreshToken: boardRefreshToken,
+  });
+
+  useEffect(() => {
+    if (boardsRequestKey === null) {
+      setBoards(fallbackBoards);
+      return;
+    }
+
+    let isStale = false;
+
+    listGalleryBoards()
+      .then((nextBoards) => {
+        if (!isStale) {
+          setBoards(nextBoards);
+        }
+      })
+      .catch(() => {
+        if (!isStale) {
+          setBoards(fallbackBoards);
+        }
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [boardsRequestKey]);
+
+  // Deliberately NOT keyed on the selected image object or the gallery's
+  // board selection/sort: the board context only refetches when the image's
+  // own board, the view, the image ordering, or backend contents change.
+  useEffect(() => {
+    if (!hasSelectedImage) {
+      setBoardImages([]);
+      setIsLoadingBoard(false);
+      return;
+    }
+
+    if (!isBackendImage) {
+      setBoardImages(localImages);
+      setIsLoadingBoard(false);
+      return;
+    }
+
+    let isStale = false;
+
+    setIsLoadingBoard(true);
+    listGalleryImages({
+      boardId: imageBoardId,
+      galleryView: selectedGalleryView,
+      orderDir: imageOrderDir,
+      searchTerm: '',
+      starredFirst,
+    })
+      .then((nextImagesPage) => {
+        if (isStale) {
+          return;
+        }
+
+        const fallbackImage = selectedImageRef.current;
+
+        setBoardImages(nextImagesPage.images.length ? nextImagesPage.images : fallbackImage ? [fallbackImage] : []);
+      })
+      .catch((error: unknown) => {
+        if (!isStale) {
+          dispatch({
+            area: 'preview-board-images',
+            message: error instanceof Error ? error.message : String(error),
+            namespace: 'gallery',
+            type: 'recordError',
+          });
+
+          const fallbackImage = selectedImageRef.current;
+
+          setBoardImages(fallbackImage ? [fallbackImage] : []);
+        }
+      })
+      .finally(() => {
+        if (!isStale) {
+          setIsLoadingBoard(false);
+        }
+      });
+
+    return () => {
+      isStale = true;
+    };
+  }, [
+    dispatch,
+    hasSelectedImage,
+    imageBoardId,
+    imageOrderDir,
+    imageRefreshToken,
+    isBackendImage,
+    localImages,
+    recentImagesKey,
+    selectedGalleryView,
+    starredFirst,
+  ]);
+
+  const selectByOffset = useCallback(
+    (offset: -1 | 1) => {
+      if (selectedIndex === -1) {
+        return;
+      }
+
+      const nextImage = boardImages[selectedIndex + offset];
+
+      if (nextImage) {
+        dispatch({ image: nextImage, type: 'selectGalleryImage' });
+      }
+    },
+    [boardImages, dispatch, selectedIndex]
+  );
+
+  const [contextMenuTarget, setContextMenuTarget] = useState<ImageContextMenuTarget | null>(null);
+  const onImagesDeleted = useCallback(
+    (imageNames: string[]) => {
+      const deletedNames = new Set(imageNames);
+      const images = boardImagesRef.current;
+      const anchorName = selectedImageRef.current?.imageName ?? null;
+
+      if (!anchorName || !deletedNames.has(anchorName)) {
+        return;
+      }
+
+      const anchorIndex = images.findIndex((image) => image.imageName === anchorName);
+
+      if (anchorIndex === -1) {
+        return;
+      }
+
+      const remaining = images.filter((image) => !deletedNames.has(image.imageName));
+      const remainingBeforeAnchor = images
+        .slice(0, anchorIndex)
+        .filter((image) => !deletedNames.has(image.imageName)).length;
+      const nextImage = remaining[remainingBeforeAnchor] ?? remaining[remainingBeforeAnchor - 1] ?? null;
+
+      if (nextImage) {
+        dispatch({ image: nextImage, type: 'selectGalleryImage' });
+      }
+    },
+    [dispatch]
+  );
+  const projectId = useActiveProjectId();
+  const imageActions = useImageActions({
+    boards,
+    dispatch,
+    generateValues,
+    onImagesDeleted,
+    projectId,
+  });
+  const contextMenuImage = useMemo<GalleryImage | null>(() => {
+    if (!selectedImage) {
+      return null;
+    }
+
+    const boardImage = boardImages.find((image) => image.imageName === selectedImage.imageName);
+
+    return {
+      ...selectedImage,
+      boardId: boardImage?.boardId ?? displayBoardId,
+      imageCategory: boardImage?.imageCategory ?? selectedImage.imageCategory ?? 'general',
+      starred: boardImage?.starred ?? selectedImage.starred ?? false,
+    };
+  }, [boardImages, displayBoardId, selectedImage]);
+  const isComparing =
+    selectedImage !== null && compareImage !== null && compareImage.imageName !== selectedImage.imageName;
+  const shouldShowProgressImage = showProgressImagesInViewer && progressImage !== null && !isComparing;
+  const exitCompare = useCallback(() => dispatch({ image: null, type: 'setGalleryCompareImage' }), [dispatch]);
+  const swapCompareImages = useCallback(() => {
+    if (selectedImage && compareImage) {
+      dispatch({ image: compareImage, type: 'selectGalleryImage' });
+      dispatch({ image: selectedImage, type: 'setGalleryCompareImage' });
+    }
+  }, [compareImage, dispatch, selectedImage]);
+  const openImageContextMenu = useCallback(
+    (x: number, y: number) => {
+      if (contextMenuImage) {
+        setContextMenuTarget({ images: [contextMenuImage], x, y });
+      }
+    },
+    [contextMenuImage]
+  );
+  const selectNextImage = useCallback(() => selectByOffset(1), [selectByOffset]);
+  const selectPreviousImage = useCallback(() => selectByOffset(-1), [selectByOffset]);
+  const closeContextMenu = useCallback(() => setContextMenuTarget(null), []);
+  const executeViewerHotkey = useEffectEvent((commandId: string) => {
+    if (commandId === 'viewer.toggleViewer') {
+      runtime.workbench.closeWidgetInstance(runtime.instanceId);
+      return;
+    }
+
+    if (commandId === 'viewer.swapImages' && selectedImage && compareImage) {
+      dispatch({ image: compareImage, type: 'selectGalleryImage' });
+      dispatch({ image: selectedImage, type: 'setGalleryCompareImage' });
+      return;
+    }
+
+    if (commandId === 'viewer.deleteImage' && selectedImage) {
+      void imageActions.deleteImages([selectedImage.imageName]);
+    }
+  });
+
+  useEffect(() => {
+    const hotkeys = [
+      ['viewer.toggleViewer', t('widgets.preview.commands.togglePreview'), ['z']],
+      ['viewer.swapImages', t('widgets.preview.commands.swapComparisonImages'), ['c']],
+      ['viewer.deleteImage', t('widgets.preview.commands.deletePreviewImage'), ['delete', 'backspace']],
+    ] as const;
+    const disposers = hotkeys.flatMap(([id, title, defaultKeys]) => [
+      runtime.commands.register({ handler: () => executeViewerHotkey(id), id, title }),
+      runtime.hotkeys.register({ commandId: id, defaultKeys: [...defaultKeys], id, title }),
+    ]);
+
+    return () => {
+      disposers.forEach((dispose) => dispose());
+    };
+  }, [runtime.commands, runtime.hotkeys, t]);
+
+  return (
+    <Box p="2" h="full">
+      {selectedImage ? (
+        <>
+          {isComparing && compareImage ? (
+            <PreviewCompare
+              baseImage={selectedImage}
+              compareImage={compareImage}
+              runtime={runtime}
+              onExit={exitCompare}
+              onSwap={swapCompareImages}
+            />
+          ) : (
+            <SelectedImagePreview
+              boardImageCount={boardImages.length}
+              boardName={boardName}
+              image={selectedImage}
+              isCompact={isSidePanel}
+              isLoadingBoard={isLoadingBoard}
+              progressImage={shouldShowProgressImage ? progressImage : null}
+              selectedIndex={selectedIndex}
+              shouldAntialiasProgressImage={antialiasProgressImages}
+              onContextMenu={openImageContextMenu}
+              onNext={selectNextImage}
+              onPrevious={selectPreviousImage}
+            />
+          )}
+          <ImageContextMenu
+            actions={imageActions}
+            boards={boards}
+            target={contextMenuTarget}
+            onClose={closeContextMenu}
+          />
+        </>
+      ) : (
+        <EmptyPreview
+          progressImage={shouldShowProgressImage ? progressImage : null}
+          shouldAntialiasProgressImage={antialiasProgressImages}
+        />
+      )}
+    </Box>
+  );
+};
+
+const SelectedImagePreview = ({
+  boardImageCount,
+  boardName,
+  image,
+  isCompact,
+  isLoadingBoard,
+  progressImage,
+  selectedIndex,
+  shouldAntialiasProgressImage,
+  onContextMenu,
+  onNext,
+  onPrevious,
+}: {
+  boardImageCount: number;
+  boardName: string;
+  image: GeneratedImageContract;
+  isCompact: boolean;
+  isLoadingBoard: boolean;
+  progressImage: ProgressImageSnapshot | null;
+  selectedIndex: number;
+  shouldAntialiasProgressImage: boolean;
+  onContextMenu: (x: number, y: number) => void;
+  onNext: () => void;
+  onPrevious: () => void;
+}) => {
+  const { t } = useTranslation();
+  const previewImage = useStreamingImageSource({
+    fallbackImage: imageUrlToStreamingSource({
+      alt: image.imageName,
+      height: image.height,
+      kind: 'fallback',
+      src: image.imageUrl,
+      width: image.width,
+    }),
+    liveImage: progressImageToStreamingSource(progressImage),
+  });
+  const isProgressImage = previewImage?.kind === 'live';
+  const previewWidth = previewImage?.width ?? image.width;
+  const previewHeight = previewImage?.height ?? image.height;
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === 'ArrowLeft') {
+        event.preventDefault();
+        onPrevious();
+      }
+
+      if (event.key === 'ArrowRight') {
+        event.preventDefault();
+        onNext();
+      }
+    },
+    [onNext, onPrevious]
+  );
+  const handleContextMenu = useCallback(
+    (event: MouseEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      onContextMenu(event.clientX, event.clientY);
+    },
+    [onContextMenu]
+  );
+  const imageStyle = useMemo<CSSProperties>(
+    () => ({
+      display: 'block',
+      height: '100%',
+      imageRendering: isProgressImage && !shouldAntialiasProgressImage ? 'pixelated' : 'auto',
+      inset: 0,
+      objectFit: 'contain',
+      position: 'absolute',
+      width: '100%',
+    }),
+    [isProgressImage, shouldAntialiasProgressImage]
+  );
+
+  return (
+    <Stack gap="3" h="full" minH="0" tabIndex={0} w="full" onKeyDown={handleKeyDown}>
+      <Flex
+        align="center"
+        borderWidth="1px"
+        borderColor="border.subtle"
+        color="fg.grid"
+        css={previewGridCss}
+        flex="1"
+        justify="center"
+        minH="0"
+        overflow="hidden"
+        p={isCompact ? '3' : '6'}
+        rounded="lg"
+        w="full"
+      >
+        <Box
+          aspectRatio={previewWidth / previewHeight}
+          bg="transparent"
+          borderWidth="1px"
+          borderColor={isProgressImage ? 'accent.solid' : 'border.emphasized'}
+          boxShadow="0 24px 80px rgba(0,0,0,0.42)"
+          h={isCompact ? 'auto' : 'full'}
+          maxH={isCompact ? undefined : 'full'}
+          maxW="full"
+          overflow="hidden"
+          position="relative"
+          rounded="lg"
+          w={isCompact ? 'full' : 'auto'}
+          onContextMenu={handleContextMenu}
+        >
+          {previewImage ? <img alt={previewImage.alt} src={previewImage.src} style={imageStyle} /> : null}
+          {isProgressImage ? (
+            <Badge left="2" pointerEvents="none" position="absolute" size="xs" top="2" variant="solid">
+              {t('common.generating')}
+            </Badge>
+          ) : null}
+        </Box>
+      </Flex>
+      <Stack borderWidth="1px" borderColor="border.subtle" gap="2" p="3" rounded="lg">
+        <HStack align="center" justify="space-between">
+          <HStack gap="2" minW="0">
+            <Badge flexShrink={0} size="xs" variant="subtle">
+              {boardName}
+            </Badge>
+            <Text color="fg.subtle" fontSize="2xs" truncate>
+              {isLoadingBoard
+                ? t('widgets.preview.loadingBoard')
+                : selectedIndex === -1
+                  ? t('widgets.preview.imageCount', { count: boardImageCount })
+                  : t('common.countOfTotal', { count: selectedIndex + 1, total: boardImageCount })}
+            </Text>
+          </HStack>
+          <HStack flexShrink={0} gap="1">
+            <Button
+              aria-label={t('widgets.preview.previousImageInBoard')}
+              disabled={selectedIndex <= 0}
+              size="2xs"
+              variant="outline"
+              onClick={onPrevious}
+            >
+              <ChevronLeftIcon />
+            </Button>
+            <Button
+              aria-label={t('widgets.preview.nextImageInBoard')}
+              disabled={selectedIndex === -1 || selectedIndex >= boardImageCount - 1}
+              size="2xs"
+              variant="outline"
+              onClick={onNext}
+            >
+              <ChevronRightIcon />
+            </Button>
+          </HStack>
+        </HStack>
+        <Stack>
+          <Text fontSize="xs" fontWeight="800" truncate>
+            {image.imageName}
+          </Text>
+          <Text color="fg.subtle" fontSize="2xs">
+            {t('widgets.preview.sourceRun', { id: image.sourceQueueItemId })}
+          </Text>
+          <Text color="fg.subtle" flexShrink={0} fontSize="2xs">
+            {isProgressImage ? t('common.generating') : `${image.width} x ${image.height}`}
+          </Text>
+        </Stack>
+      </Stack>
+    </Stack>
+  );
+};
+
+const EmptyPreview = ({
+  progressImage,
+  shouldAntialiasProgressImage,
+}: {
+  progressImage: ProgressImageSnapshot | null;
+  shouldAntialiasProgressImage: boolean;
+}) => {
+  const { t } = useTranslation();
+  const previewImage = useStreamingImageSource({
+    liveImage: progressImageToStreamingSource(progressImage),
+  });
+
+  return (
+    <Flex
+      align="center"
+      backgroundColor="bg.inset"
+      color="fg.grid"
+      css={previewGridCss}
+      h="full"
+      justify="center"
+      w="full"
+    >
+      {previewImage ? (
+        <Box
+          aspectRatio={(previewImage.width ?? 1) / (previewImage.height ?? 1)}
+          borderColor="accent.solid"
+          borderWidth="1px"
+          boxShadow="0 24px 80px rgba(0,0,0,0.42)"
+          maxH="full"
+          maxW="full"
+          overflow="hidden"
+          position="relative"
+          rounded="lg"
+        >
+          <img
+            alt={previewImage.alt}
+            draggable={false}
+            src={previewImage.src}
+            style={{
+              display: 'block',
+              height: '100%',
+              imageRendering: shouldAntialiasProgressImage ? 'auto' : 'pixelated',
+              objectFit: 'contain',
+              width: '100%',
+            }}
+          />
+          <Badge left="2" pointerEvents="none" position="absolute" size="xs" top="2" variant="solid">
+            {t('common.generating')}
+          </Badge>
+        </Box>
+      ) : (
+        <Stack align="center" color="fg" gap="2" maxW="18rem" textAlign="center">
+          <Text fontSize="sm" fontWeight="800">
+            {t('widgets.preview.noGallerySelection')}
+          </Text>
+          <Text color="fg.subtle" fontSize="2xs">
+            {t('widgets.preview.emptyDescription')}
+          </Text>
+        </Stack>
+      )}
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/preview/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/preview/index.ts
new file mode 100644
index 00000000000..6a5ce786025
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/preview/index.ts
@@ -0,0 +1,18 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { EyeIcon } from 'lucide-react';
+
+import { PreviewHeaderActions } from './PreviewHeaderActions';
+import { PreviewWidgetView } from './PreviewWidgetView';
+
+export const previewWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['center', 'right'],
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  headerActions: PreviewHeaderActions,
+  icon: EyeIcon,
+  id: 'preview',
+  label: (t) => t('widgets.labels.preview'),
+  version: 1,
+  view: PreviewWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/project/ProjectWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/project/ProjectWidgetView.tsx
new file mode 100644
index 00000000000..d1670015597
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/project/ProjectWidgetView.tsx
@@ -0,0 +1,292 @@
+import type { Project } from '@workbench/types';
+
+import { HStack, Icon, Input, Stack, Text } from '@chakra-ui/react';
+import { Button, IconButton, ConfirmDialog, Field, FieldLabel, Panel } from '@workbench/components/ui';
+import { useProjectSyncSelector } from '@workbench/projects/syncStore';
+import { useProjectActions } from '@workbench/projects/useProjectActions';
+import { useNotify } from '@workbench/useNotify';
+import { flushGenerateDrafts } from '@workbench/widgets/generate/generateDraftRegistry';
+import {
+  shallowEqual,
+  useActiveProjectSelector,
+  useWorkbenchDispatch,
+  useWorkbenchSelector,
+} from '@workbench/WorkbenchContext';
+import { ArrowRightIcon, CopyIcon, History as HistoryIcon, Trash2Icon } from 'lucide-react';
+import { useCallback, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+
+const RECOVERY_DELETE_HOVER = { color: 'fg.error' } as const;
+
+/**
+ * The Project panel: rename the active project, see its sync/debug details,
+ * and manage recovery copies (open or delete them). Recoveries are keyed to
+ * their root original via `recoveryOf`, so the whole family is visible from
+ * any of its members.
+ */
+export const ProjectWidgetView = () => {
+  const activeProject = useActiveProjectSelector(
+    (project) => ({
+      events: project.events,
+      graphHistory: project.graphHistory,
+      id: project.id,
+      name: project.name,
+      projectGraph: project.projectGraph,
+      queue: project.queue,
+      recoveredAt: project.recoveredAt,
+      recoveryOf: project.recoveryOf,
+    }),
+    shallowEqual
+  );
+
+  return (
+    <Stack gap="5" p="3">
+      <NameSection project={activeProject} />
+      <RecoverySection project={activeProject} />
+      <DetailsSection project={activeProject} />
+    </Stack>
+  );
+};
+
+type ProjectPanelViewModel = Pick<
+  Project,
+  'events' | 'graphHistory' | 'id' | 'name' | 'projectGraph' | 'queue' | 'recoveredAt' | 'recoveryOf'
+>;
+
+const NameSection = ({ project }: { project: ProjectPanelViewModel }) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+
+  const commitName = useCallback(
+    (value: string) => {
+      const name = value.trim();
+
+      if (name && name !== project.name) {
+        dispatch({ name, projectId: project.id, type: 'renameProject' });
+      }
+    },
+    [dispatch, project.id, project.name]
+  );
+  const handleBlur = useCallback(
+    (event: React.FocusEvent<HTMLInputElement>) => commitName(event.currentTarget.value),
+    [commitName]
+  );
+  const handleKeyDown = useCallback((event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Enter') {
+      event.currentTarget.blur();
+    }
+  }, []);
+
+  return (
+    <Field helpText={t('widgets.project.nameHelp')} label={t('widgets.project.nameLabel')}>
+      <Input
+        defaultValue={project.name}
+        key={`${project.id}:${project.name}`}
+        size="sm"
+        onBlur={handleBlur}
+        onKeyDown={handleKeyDown}
+      />
+    </Field>
+  );
+};
+
+/** The id whose recovery family this project belongs to. */
+const getRecoveryRootId = (project: Pick<Project, 'id' | 'recoveryOf'>): string => project.recoveryOf ?? project.id;
+
+const formatTimestamp = (timestamp: string | undefined, unknownTime: string): string => {
+  if (!timestamp) {
+    return unknownTime;
+  }
+
+  const date = new Date(timestamp);
+
+  return Number.isNaN(date.getTime()) ? unknownTime : date.toLocaleString();
+};
+
+const RecoverySection = ({ project }: { project: ProjectPanelViewModel }) => {
+  const { t } = useTranslation();
+  const projects = useWorkbenchSelector((snapshot) => snapshot.state.projects);
+  const dispatch = useWorkbenchDispatch();
+  const { deleteProject } = useProjectActions();
+  const [deleteTarget, setDeleteTarget] = useState<Project | null>(null);
+  const rootId = getRecoveryRootId(project);
+  const original = project.recoveryOf ? projects.find((candidate) => candidate.id === project.recoveryOf) : null;
+  const recoveries = projects.filter(
+    (candidate) => candidate.id !== project.id && getRecoveryRootId(candidate) === rootId && candidate.recoveryOf
+  );
+  const handleOpenOriginal = useCallback(() => {
+    if (original) {
+      flushGenerateDrafts();
+      dispatch({ projectId: original.id, type: 'switchProject' });
+    }
+  }, [dispatch, original]);
+  const handleCloseDeleteDialog = useCallback(() => setDeleteTarget(null), []);
+  const handleConfirmDelete = useCallback(async () => {
+    if (deleteTarget) {
+      await deleteProject(deleteTarget);
+    }
+  }, [deleteProject, deleteTarget]);
+
+  if (!project.recoveryOf && recoveries.length === 0) {
+    return null;
+  }
+
+  return (
+    <Stack gap="2">
+      <FieldLabel>{t('widgets.project.recoveries')}</FieldLabel>
+      {project.recoveryOf ? (
+        <Panel p="2.5">
+          <HStack gap="2">
+            <Icon as={HistoryIcon} boxSize="3.5" color="fg.muted" flexShrink={0} />
+            <Stack flex="1" gap="0" minW="0">
+              <Text fontSize="xs" fontWeight="600">
+                {t('widgets.project.recoveryCopy')}
+              </Text>
+              <Text color="fg.muted" fontSize="2xs">
+                {t('widgets.project.recoveryForkedDescription', {
+                  time: formatTimestamp(project.recoveredAt, t('common.unknownTime')),
+                })}
+              </Text>
+            </Stack>
+          </HStack>
+          {original ? (
+            <Button mt="2" size="2xs" variant="outline" w="full" onClick={handleOpenOriginal}>
+              <ArrowRightIcon />
+              {t('widgets.project.openOriginal', { name: original.name })}
+            </Button>
+          ) : null}
+        </Panel>
+      ) : null}
+      {recoveries.map((recovery) => (
+        <RecoveryRow key={recovery.id} recovery={recovery} onDelete={setDeleteTarget} />
+      ))}
+      <ConfirmDialog
+        body={t('widgets.project.deleteRecoveryBody', { name: deleteTarget?.name ?? '' })}
+        confirmLabel={t('widgets.project.deleteRecovery')}
+        isOpen={deleteTarget !== null}
+        title={t('widgets.project.deleteRecoveryTitle')}
+        onClose={handleCloseDeleteDialog}
+        onConfirm={handleConfirmDelete}
+      />
+    </Stack>
+  );
+};
+
+const RecoveryRow = ({
+  recovery,
+  onDelete,
+}: {
+  recovery: Project;
+  onDelete: React.Dispatch<React.SetStateAction<Project | null>>;
+}) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const handleOpen = useCallback(() => {
+    flushGenerateDrafts();
+    dispatch({ projectId: recovery.id, type: 'switchProject' });
+  }, [dispatch, recovery.id]);
+  const handleDelete = useCallback(() => onDelete(recovery), [onDelete, recovery]);
+
+  return (
+    <Panel alignItems="center" flexDirection="row" gap="2" p="2">
+      <Stack flex="1" gap="0" minW="0">
+        <Text fontSize="xs" fontWeight="600" truncate>
+          {recovery.name}
+        </Text>
+        <Text color="fg.muted" fontSize="2xs">
+          {formatTimestamp(recovery.recoveredAt, t('common.unknownTime'))}
+        </Text>
+      </Stack>
+      <IconButton
+        aria-label={t('widgets.project.openRecovery', { name: recovery.name })}
+        color="fg.muted"
+        size="2xs"
+        variant="ghost"
+        onClick={handleOpen}
+      >
+        <ArrowRightIcon />
+      </IconButton>
+      <IconButton
+        aria-label={t('widgets.project.deleteRecoveryAria', { name: recovery.name })}
+        color="fg.muted"
+        size="2xs"
+        variant="ghost"
+        _hover={RECOVERY_DELETE_HOVER}
+        onClick={handleDelete}
+      >
+        <Trash2Icon />
+      </IconButton>
+    </Panel>
+  );
+};
+
+const DetailsSection = ({ project }: { project: ProjectPanelViewModel }) => {
+  const { t } = useTranslation();
+  const backendConnectionStatus = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status);
+  const lastSavedAt = useWorkbenchSelector((snapshot) => snapshot.state.autosave.lastSavedAt);
+  const projectSync = useProjectSyncSelector((snapshot) => snapshot.projects[project.id]);
+  const notify = useNotify();
+
+  const syncLabel =
+    backendConnectionStatus !== 'connected'
+      ? t('widgets.project.syncOffline')
+      : projectSync === undefined || projectSync.isPendingPush
+        ? t('widgets.project.syncWaiting')
+        : t('widgets.project.syncSynced', { revision: projectSync.revision ?? '—' });
+
+  const copyId = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(project.id);
+      notify.success(t('widgets.project.idCopied'));
+    } catch {
+      notify.error(t('common.couldNotCopy'), t('common.clipboardBlocked'));
+    }
+  }, [notify, project.id, t]);
+  const handleCopyId = useCallback(() => void copyId(), [copyId]);
+
+  return (
+    <Stack gap="2">
+      <FieldLabel>{t('common.details')}</FieldLabel>
+      <Panel gap="1.5" p="2.5">
+        <DetailRow label={t('common.id')}>
+          <HStack gap="1" minW="0">
+            <Text fontFamily="mono" fontSize="2xs" truncate>
+              {project.id}
+            </Text>
+            <IconButton
+              aria-label={t('widgets.project.copyId')}
+              color="fg.muted"
+              size="2xs"
+              variant="ghost"
+              onClick={handleCopyId}
+            >
+              <CopyIcon />
+            </IconButton>
+          </HStack>
+        </DetailRow>
+        <DetailRow label={t('widgets.project.sync')}>{syncLabel}</DetailRow>
+        <DetailRow label={t('common.lastSaved')}>
+          {lastSavedAt ? formatTimestamp(lastSavedAt, t('common.unknownTime')) : t('common.notYet')}
+        </DetailRow>
+        <DetailRow label={t('widgets.project.graphNodes')}>{project.projectGraph.nodes.length}</DetailRow>
+        <DetailRow label={t('widgets.project.queueItems')}>{project.queue.items.length}</DetailRow>
+        <DetailRow label={t('widgets.project.events')}>{project.events.length}</DetailRow>
+      </Panel>
+    </Stack>
+  );
+};
+
+const DetailRow = ({ children, label }: { children: ReactNode; label: string }) => (
+  <HStack gap="3" justify="space-between" minH="5">
+    <Text color="fg.subtle" flexShrink={0} fontSize="2xs">
+      {label}
+    </Text>
+    {typeof children === 'string' || typeof children === 'number' ? (
+      <Text fontSize="2xs" textAlign="end">
+        {children}
+      </Text>
+    ) : (
+      children
+    )}
+  </HStack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/project/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/project/index.ts
new file mode 100644
index 00000000000..70eeaae357a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/project/index.ts
@@ -0,0 +1,16 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { FolderCogIcon } from 'lucide-react';
+
+import { ProjectWidgetView } from './ProjectWidgetView';
+
+export const projectWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['left', 'right'],
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  icon: FolderCogIcon,
+  id: 'project',
+  label: (t) => t('widgets.labels.project'),
+  version: 1,
+  view: ProjectWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/CancelQueueItemButton.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/CancelQueueItemButton.tsx
new file mode 100644
index 00000000000..168cb15ee41
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/CancelQueueItemButton.tsx
@@ -0,0 +1,56 @@
+import type { MouseEvent as ReactMouseEvent } from 'react';
+
+import { Icon } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { useNotify } from '@workbench/useNotify';
+import { XIcon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { refreshQueue } from './queueDataStore';
+import { cancelQueueItem } from './queueServerApi';
+
+/**
+ * Cancel a single queue item by its backend id. Works for any in-flight item
+ * regardless of which client submitted it; the coordinator settles local items
+ * off the resulting `queue_item_status_changed` event. `stopPropagation` keeps a
+ * click from also toggling the row it sits in.
+ */
+export const CancelQueueItemButton = ({ itemId }: { itemId: number }) => {
+  const { t } = useTranslation();
+  const notify = useNotify();
+  const [busy, setBusy] = useState(false);
+
+  const onCancel = useCallback(
+    async (event: ReactMouseEvent) => {
+      event.stopPropagation();
+      setBusy(true);
+
+      try {
+        await cancelQueueItem(itemId);
+        await refreshQueue();
+      } catch (error) {
+        notify.error(t('common.cancelFailed'), getApiErrorMessage(error, t('widgets.queue.couldNotCancelItem')));
+      } finally {
+        setBusy(false);
+      }
+    },
+    [itemId, notify, t]
+  );
+
+  return (
+    <Tooltip content={t('widgets.queue.cancelItem', { id: itemId })}>
+      <IconButton
+        aria-label={t('widgets.queue.cancelItem', { id: itemId })}
+        color="fg.muted"
+        loading={busy}
+        size="2xs"
+        variant="ghost"
+        onClick={onCancel}
+      >
+        <Icon as={XIcon} boxSize="3.5" />
+      </IconButton>
+    </Tooltip>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/ModelCacheFooter.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/ModelCacheFooter.tsx
new file mode 100644
index 00000000000..63754d8c454
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/ModelCacheFooter.tsx
@@ -0,0 +1,141 @@
+import { Collapsible, HStack, Icon, Progress, Stack, Text } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button } from '@workbench/components/ui';
+import { formatBytes } from '@workbench/models/taxonomy';
+import { useNotify } from '@workbench/useNotify';
+import { ChevronUpIcon, DatabaseIcon, Trash2Icon } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import {
+  clearModelCache,
+  getModelCacheClearToast,
+  getModelCacheUsage,
+  refreshModelCacheStats,
+  useModelCacheStats,
+} from './modelCacheStore';
+
+const INDICATOR_OPEN = { transform: 'rotate(180deg)' } as const;
+const TRIGGER_HOVER = { color: 'fg' } as const;
+
+const CacheStat = ({ label, value }: { label: string; value: number }) => (
+  <Text color="fg.subtle" fontSize="2xs">
+    {label}{' '}
+    <Text as="span" color="fg" fontVariantNumeric="tabular-nums" fontWeight="600">
+      {value}
+    </Text>
+  </Text>
+);
+
+/**
+ * Collapsible MODEL CACHE footer (manifest `footer` slot). Collapsed: a label, a
+ * RAM-used / budget readout, and a fill bar. Expanded: hit/miss/loaded counts and
+ * a Clear action. The cache has no enable/disable endpoint, so there is no
+ * "Disable" toggle. Mirrors the model manager's `InstallQueueBar` collapse shape.
+ */
+export const ModelCacheFooter = () => {
+  const { t } = useTranslation();
+  const { stats } = useModelCacheStats();
+  const notify = useNotify();
+  const [expanded, setExpanded] = useState(false);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    void refreshModelCacheStats();
+  }, []);
+
+  const { total, used } = getModelCacheUsage(stats);
+  const ratio = total > 0 ? Math.min(1, used / total) : 0;
+
+  const handleOpenChange = useCallback((event: { open: boolean }) => setExpanded(event.open), []);
+  const handleClear = useCallback(async () => {
+    setBusy(true);
+
+    try {
+      const clearResult = await clearModelCache();
+      const toast = getModelCacheClearToast(clearResult, t);
+      notify[toast.status](toast.title, toast.description);
+    } catch (error) {
+      notify.error(
+        t('widgets.queue.modelCache.clearFailed'),
+        getApiErrorMessage(error, t('widgets.queue.modelCache.couldNotClear'))
+      );
+    } finally {
+      setBusy(false);
+    }
+  }, [notify, t]);
+
+  return (
+    <Collapsible.Root
+      bg="bg.subtle"
+      borderTopWidth={1}
+      open={expanded}
+      overflow="hidden"
+      onOpenChange={handleOpenChange}
+    >
+      <Collapsible.Content>
+        <Stack borderBottomWidth={1} gap="2" px="3" py="2.5">
+          <HStack gap="3">
+            <CacheStat label={t('widgets.queue.modelCache.hits')} value={stats?.hits ?? 0} />
+            <CacheStat label={t('widgets.queue.modelCache.misses')} value={stats?.misses ?? 0} />
+            <CacheStat label={t('widgets.queue.modelCache.loaded')} value={stats?.in_cache ?? 0} />
+          </HStack>
+          <HStack>
+            <Button loading={busy} size="2xs" variant="surface" onClick={handleClear}>
+              <Icon as={Trash2Icon} boxSize="3" />
+              {t('widgets.queue.modelCache.clear')}
+            </Button>
+          </HStack>
+        </Stack>
+      </Collapsible.Content>
+
+      <Stack gap="0">
+        <Progress.Root
+          aria-label={t('widgets.queue.modelCache.usage')}
+          aria-valuetext={t('widgets.queue.modelCache.usedOfTotal', {
+            total: formatBytes(total),
+            used: formatBytes(used),
+          })}
+          colorPalette="accent"
+          max={1}
+          size="xs"
+          value={ratio}
+        >
+          <Progress.Track bg="transparent">
+            <Progress.Range />
+          </Progress.Track>
+        </Progress.Root>
+        <Collapsible.Trigger
+          alignItems="center"
+          bg="transparent"
+          color="inherit"
+          display="flex"
+          gap="2"
+          px="3"
+          py="2"
+          textAlign="start"
+          w="full"
+          _hover={TRIGGER_HOVER}
+        >
+          <Icon as={DatabaseIcon} boxSize="3.5" color="fg.subtle" flexShrink={0} />
+          <Text
+            color="fg.muted"
+            flex="1"
+            fontSize="2xs"
+            fontWeight="700"
+            letterSpacing="0.06em"
+            textTransform="uppercase"
+          >
+            {t('widgets.queue.modelCache.label')}
+          </Text>
+          <Text color="fg.subtle" fontSize="2xs" fontVariantNumeric="tabular-nums">
+            {formatBytes(used)} / {formatBytes(total)}
+          </Text>
+          <Collapsible.Indicator _open={INDICATOR_OPEN} transition="transform var(--wb-motion-duration-slow)">
+            <Icon as={ChevronUpIcon} boxSize="4" color="fg.subtle" flexShrink={0} />
+          </Collapsible.Indicator>
+        </Collapsible.Trigger>
+      </Stack>
+    </Collapsible.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/NowNextSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/NowNextSection.tsx
new file mode 100644
index 00000000000..11f85dd2f45
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/NowNextSection.tsx
@@ -0,0 +1,28 @@
+import { Stack } from '@chakra-ui/react';
+import { useTranslation } from 'react-i18next';
+
+import { QueueItemRow } from './QueueItemRow';
+import { useScopedCurrentBatchItems } from './queueScope';
+import { SectionHeader } from './SectionHeader';
+
+/** CURRENT BATCH — the running item plus every pending item in the same backend batch. */
+export const CurrentBatchSection = () => {
+  const { t } = useTranslation();
+  const items = useScopedCurrentBatchItems();
+  const count = items.length;
+
+  if (count === 0) {
+    return null;
+  }
+
+  return (
+    <Stack gap="2">
+      <SectionHeader count={count} title={t('widgets.queue.currentBatch')} />
+      <Stack gap="1">
+        {items.map((item) => (
+          <QueueItemRow key={item.item_id} item={item} />
+        ))}
+      </Stack>
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueDataRuntime.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueDataRuntime.test.ts
new file mode 100644
index 00000000000..8111be0aa7d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueDataRuntime.test.ts
@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  clearAllProgress: vi.fn(),
+  clearProgress: vi.fn(),
+  setProgress: vi.fn(),
+  onConnectionChange: vi.fn(),
+  refreshModelCacheStats: vi.fn(),
+  refreshQueue: vi.fn(),
+  socketOn: vi.fn(),
+}));
+
+vi.mock('@workbench/backend/events', () => ({
+  isTerminalBackendStatus: (status: string) => status === 'completed' || status === 'failed' || status === 'canceled',
+}));
+
+vi.mock('@workbench/backend/itemProgressStore', () => ({
+  itemProgressStore: {
+    clear: mocks.clearProgress,
+    clearAll: mocks.clearAllProgress,
+    set: mocks.setProgress,
+  },
+}));
+
+vi.mock('@workbench/backend/socketHub', () => ({
+  socketHub: {
+    on: mocks.socketOn,
+    onConnectionChange: mocks.onConnectionChange,
+  },
+}));
+
+vi.mock('./modelCacheStore', () => ({
+  refreshModelCacheStats: mocks.refreshModelCacheStats,
+}));
+
+vi.mock('./queueDataStore', () => ({
+  ensureQueueLoaded: vi.fn(),
+  refreshQueue: mocks.refreshQueue,
+  setQueueScope: vi.fn(),
+  useCurrentBatchItems: vi.fn(() => []),
+  useQueueCounts: vi.fn(() => ({
+    canceled: 0,
+    completed: 0,
+    failed: 0,
+    in_progress: 0,
+    pending: 0,
+    queue_id: 'default',
+    total: 0,
+  })),
+  useRecentItems: vi.fn(() => []),
+}));
+
+vi.mock('@workbench/settings/store', () => ({
+  useWorkbenchPreferences: vi.fn(() => ({ queueJobsScope: 'all' })),
+}));
+
+vi.mock('@workbench/WorkbenchContext', () => ({
+  useOptionalWorkbenchSelector: vi.fn((_selector: unknown, fallback: unknown) => fallback),
+}));
+
+describe('QueueDataRuntime queue refresh events', () => {
+  beforeEach(() => {
+    mocks.clearAllProgress.mockReset();
+    mocks.clearProgress.mockReset();
+    mocks.onConnectionChange.mockReset();
+    mocks.refreshModelCacheStats.mockReset();
+    mocks.refreshQueue.mockReset();
+    mocks.setProgress.mockReset();
+    mocks.socketOn.mockReset();
+    mocks.socketOn.mockReturnValue(vi.fn());
+    mocks.onConnectionChange.mockReturnValue(vi.fn());
+  });
+
+  it('refreshes queue data for all queue mutation socket events', async () => {
+    const { attachQueueDataRuntime } = await import('./QueueDataRuntime');
+
+    attachQueueDataRuntime();
+
+    const handlersByEvent = new Map<string, (payload: never) => void>(
+      mocks.socketOn.mock.calls.map((call) => [call[0] as string, call[1] as (payload: never) => void])
+    );
+
+    handlersByEvent.get('batch_enqueued')?.({} as never);
+    handlersByEvent.get('queue_cleared')?.({} as never);
+    handlersByEvent.get('queue_items_retried')?.({} as never);
+
+    expect(mocks.refreshQueue).toHaveBeenCalledTimes(3);
+  });
+
+  it('stores live denoise preview images by backend queue item id', async () => {
+    const { attachQueueDataRuntime } = await import('./QueueDataRuntime');
+
+    attachQueueDataRuntime();
+
+    const handlersByEvent = new Map<string, (payload: never) => void>(
+      mocks.socketOn.mock.calls.map((call) => [call[0] as string, call[1] as (payload: never) => void])
+    );
+
+    handlersByEvent.get('invocation_progress')?.({
+      image: { dataURL: 'data:image/png;base64,preview', height: 32, width: 64 },
+      item_id: 42,
+      message: 'Denoising',
+      percentage: 0.5,
+    } as never);
+
+    expect(mocks.setProgress).toHaveBeenCalledWith(42, {
+      image: { dataUrl: 'data:image/png;base64,preview', height: 32, width: 64 },
+      message: 'Denoising',
+      percentage: 0.5,
+    });
+  });
+
+  it('does not clear the last live preview when later invocations start for the same queue item', async () => {
+    const { attachQueueDataRuntime } = await import('./QueueDataRuntime');
+
+    attachQueueDataRuntime();
+
+    const handlersByEvent = new Map<string, (payload: never) => void>(
+      mocks.socketOn.mock.calls.map((call) => [call[0] as string, call[1] as (payload: never) => void])
+    );
+
+    handlersByEvent.get('invocation_progress')?.({
+      image: { dataURL: 'data:image/png;base64,last-denoise', height: 32, width: 64 },
+      item_id: 42,
+      message: 'Denoising',
+      percentage: 1,
+    } as never);
+    handlersByEvent.get('invocation_started')?.({ item_id: 42 } as never);
+
+    expect(mocks.setProgress).toHaveBeenLastCalledWith(42, {
+      message: '',
+      percentage: null,
+    });
+  });
+
+  it('keeps completed item progress images until the refreshed queue item has a final result', async () => {
+    const { attachQueueDataRuntime } = await import('./QueueDataRuntime');
+
+    attachQueueDataRuntime();
+
+    const handlersByEvent = new Map<string, (payload: never) => void>(
+      mocks.socketOn.mock.calls.map((call) => [call[0] as string, call[1] as (payload: never) => void])
+    );
+
+    handlersByEvent.get('queue_item_status_changed')?.({ item_id: 42, status: 'completed' } as never);
+    handlersByEvent.get('queue_item_status_changed')?.({ item_id: 43, status: 'failed' } as never);
+
+    expect(mocks.clearProgress).not.toHaveBeenCalledWith(42);
+    expect(mocks.clearProgress).toHaveBeenCalledWith(43);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueDataRuntime.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueDataRuntime.tsx
new file mode 100644
index 00000000000..22e7593affa
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueDataRuntime.tsx
@@ -0,0 +1,102 @@
+import type {
+  InvocationProgressEvent,
+  InvocationStartedEvent,
+  QueueItemStatusChangedEvent,
+} from '@workbench/backend/events';
+
+import { isTerminalBackendStatus } from '@workbench/backend/events';
+import { itemProgressStore } from '@workbench/backend/itemProgressStore';
+import { socketHub } from '@workbench/backend/socketHub';
+import { ConfirmDialog } from '@workbench/components/ui';
+import { useEffect } from 'react';
+
+import { refreshModelCacheStats } from './modelCacheStore';
+import { clearQueueConfirmation, useQueueConfirmation } from './queueConfirmationStore';
+import { ensureQueueLoaded, refreshQueue, setQueueScope } from './queueDataStore';
+import { useQueueQueryScope } from './queueScope';
+
+/**
+ * Singleton runtime for the Queue widget (mounted via `manifest.host`). It owns
+ * the live wiring: socket lifecycle events refresh the server-queue store and
+ * feed per-item progress, replacing the RTK Query tag-invalidation the legacy v6
+ * app used. Pure side effects — renders nothing.
+ */
+export const attachQueueDataRuntime = (): (() => void) => {
+  ensureQueueLoaded();
+  void refreshModelCacheStats();
+
+  const refresh = () => {
+    void refreshQueue();
+  };
+  const detachers = [
+    socketHub.on('queue_item_status_changed', (payload: never) => {
+      const event = payload as unknown as QueueItemStatusChangedEvent;
+
+      if (isTerminalBackendStatus(event.status) && event.status !== 'completed') {
+        itemProgressStore.clear(event.item_id);
+      }
+
+      refresh();
+    }),
+    socketHub.on('batch_enqueued', refresh),
+    socketHub.on('queue_cleared', refresh),
+    socketHub.on('queue_items_retried', refresh),
+    socketHub.on('invocation_started', (payload: never) => {
+      const event = payload as unknown as InvocationStartedEvent;
+      itemProgressStore.set(event.item_id, { message: '', percentage: null });
+    }),
+    socketHub.on('invocation_progress', (payload: never) => {
+      const event = payload as unknown as InvocationProgressEvent;
+      itemProgressStore.set(event.item_id, {
+        image: event.image?.dataURL
+          ? { dataUrl: event.image.dataURL, height: event.image.height, width: event.image.width }
+          : undefined,
+        message: event.message,
+        percentage: event.percentage,
+      });
+    }),
+    socketHub.on('model_load_complete', () => {
+      void refreshModelCacheStats();
+    }),
+  ];
+
+  const detachConnection = socketHub.onConnectionChange((status) => {
+    if (status === 'connected') {
+      itemProgressStore.clearAll();
+      void refreshQueue();
+      void refreshModelCacheStats();
+    }
+  });
+
+  return () => {
+    for (const detach of detachers) {
+      detach();
+    }
+
+    detachConnection();
+  };
+};
+
+export const QueueDataRuntime = () => {
+  const scope = useQueueQueryScope();
+  const confirmation = useQueueConfirmation();
+
+  useEffect(() => {
+    setQueueScope(scope);
+  }, [scope, scope.originPrefix]);
+
+  useEffect(() => {
+    return attachQueueDataRuntime();
+  }, []);
+
+  return confirmation ? (
+    <ConfirmDialog
+      body={confirmation.body}
+      confirmLabel={confirmation.confirmLabel}
+      isOpen={true}
+      title={confirmation.title}
+      onClose={clearQueueConfirmation}
+      onConfirm={confirmation.onConfirm}
+    />
+  ) : null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueFilterTabs.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueFilterTabs.tsx
new file mode 100644
index 00000000000..deb6c9fc12e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueFilterTabs.tsx
@@ -0,0 +1,44 @@
+import { SegmentGroup } from '@chakra-ui/react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { QueueFilterId } from './queueFilters';
+
+import { QUEUE_FILTERS } from './queueFilters';
+
+/** Status filter pills for the RECENT list (All · Active · Done · Failed · Canceled). */
+export const QueueFilterTabs = ({
+  value,
+  onChange,
+}: {
+  value: QueueFilterId;
+  onChange: (filter: QueueFilterId) => void;
+}) => {
+  const { t } = useTranslation();
+  const onValueChange = useCallback(
+    (details: { value: string | null }) => {
+      if (details.value) {
+        onChange(details.value as QueueFilterId);
+      }
+    },
+    [onChange]
+  );
+
+  return (
+    <SegmentGroup.Root
+      aria-label={t('widgets.queue.filterRecentByStatus')}
+      colorPalette="accent"
+      size="xs"
+      value={value}
+      onValueChange={onValueChange}
+    >
+      <SegmentGroup.Indicator />
+      {QUEUE_FILTERS.map((filter) => (
+        <SegmentGroup.Item key={filter.id} value={filter.id}>
+          <SegmentGroup.ItemHiddenInput />
+          <SegmentGroup.ItemText>{t(filter.labelKey)}</SegmentGroup.ItemText>
+        </SegmentGroup.Item>
+      ))}
+    </SegmentGroup.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderActions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderActions.test.ts
new file mode 100644
index 00000000000..9b08e2b5058
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderActions.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { getQueueHeaderCancelState } from './QueueHeaderActions';
+
+describe('getQueueHeaderCancelState', () => {
+  it('enables cancelling when connected with an in-progress current item', () => {
+    expect(getQueueHeaderCancelState({ currentStatus: 'in_progress', isConnected: true })).toEqual({
+      disabled: false,
+      itemLabel: 'widgets.queue.cancelCurrent',
+    });
+  });
+
+  it('disables cancelling when disconnected or there is no current in-progress item', () => {
+    expect(getQueueHeaderCancelState({ currentStatus: 'in_progress', isConnected: false }).disabled).toBe(true);
+    expect(getQueueHeaderCancelState({ currentStatus: 'pending', isConnected: true }).disabled).toBe(true);
+    expect(getQueueHeaderCancelState({ currentStatus: null, isConnected: true }).disabled).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderActions.tsx
new file mode 100644
index 00000000000..0332c4fbe6c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderActions.tsx
@@ -0,0 +1,66 @@
+/* oxlint-disable react-perf/jsx-no-new-function-as-prop */
+import { Icon } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button } from '@workbench/components/ui';
+import { useNotify } from '@workbench/useNotify';
+import { useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { XIcon } from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { QueueServerItem } from './queueServerApi';
+
+import { refreshQueue, useNowNextItems } from './queueDataStore';
+import { cancelQueueItem } from './queueServerApi';
+
+export const getQueueHeaderCancelState = ({
+  currentStatus,
+  isConnected,
+}: {
+  currentStatus: QueueServerItem['status'] | null;
+  isConnected: boolean;
+}): { disabled: boolean; itemLabel: string } => ({
+  disabled: !isConnected || currentStatus !== 'in_progress',
+  itemLabel: 'widgets.queue.cancelCurrent',
+});
+
+/**
+ * Cancel the current queue item from the manifest `headerActions` slot, so the
+ * most common interruption action sits inline beside the actions menu.
+ */
+export const QueueHeaderActions = () => {
+  const { t } = useTranslation();
+  const isConnected = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status === 'connected');
+  const { current } = useNowNextItems();
+  const notify = useNotify();
+  const [busy, setBusy] = useState(false);
+  const currentItemId = current?.item_id ?? null;
+  const { disabled, itemLabel } = getQueueHeaderCancelState({
+    currentStatus: current?.status ?? null,
+    isConnected,
+  });
+
+  const onCancel = async () => {
+    if (disabled || currentItemId === null) {
+      return;
+    }
+
+    setBusy(true);
+
+    try {
+      await cancelQueueItem(currentItemId);
+      await refreshQueue();
+    } catch (error) {
+      notify.error(t('common.cancelFailed'), getApiErrorMessage(error, t('widgets.queue.couldNotCancelCurrentItem')));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Button disabled={disabled} loading={busy} size="2xs" variant="outline" onClick={onCancel}>
+      <Icon as={XIcon} boxSize="3.5" />
+      {t(itemLabel)}
+    </Button>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderLabel.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderLabel.tsx
new file mode 100644
index 00000000000..837a7837a5b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderLabel.tsx
@@ -0,0 +1,30 @@
+import { Stack, Text } from '@chakra-ui/react';
+import { useTranslation } from 'react-i18next';
+
+import { useScopedQueueCounts } from './queueScope';
+
+/**
+ * The Queue widget's header title: "Queue" over a live "N generating · M waiting"
+ * summary. Rendered as the manifest `label`, so it sits in the standard frame
+ * header. Counts come straight from the server-wide status, with tabular
+ * numerals so the summary doesn't jitter as items move through the queue.
+ */
+export const QueueHeaderLabel = () => {
+  const { t } = useTranslation();
+  const counts = useScopedQueueCounts();
+  const isGenerating = counts.in_progress > 0;
+
+  return (
+    <Stack gap="0.5" minW="0">
+      <Text fontSize="xs" fontWeight="700" lineHeight="1.15">
+        {t('widgets.labels.queue')}
+      </Text>
+      <Text color="fg.subtle" fontSize="2xs" fontVariantNumeric="tabular-nums" lineHeight="1.15" truncate mb="-1.5">
+        <Text as="span" color={isGenerating ? 'accent.solid' : 'fg.subtle'} fontWeight={isGenerating ? '600' : '400'}>
+          {t('widgets.queue.generating', { count: counts.in_progress })}
+        </Text>{' '}
+        · {t('widgets.queue.waiting', { count: counts.pending })}
+      </Text>
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderMenu.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderMenu.tsx
new file mode 100644
index 00000000000..8f249719705
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueHeaderMenu.tsx
@@ -0,0 +1,101 @@
+import { Icon, Menu } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { useNotify } from '@workbench/useNotify';
+import { Trash2Icon, TrashIcon } from 'lucide-react';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { requestQueueConfirmation } from './queueConfirmationStore';
+import { refreshQueue, useQueueCounts } from './queueDataStore';
+import { QueueMenuItems, useQueueMenuActions } from './queueMenuActions';
+import { useQueueQueryScope } from './queueScope';
+import { clearFailedQueueItems, clearScopedQueue } from './queueServerApi';
+
+const ERROR_ITEM_HOVER_PROPS = { bg: 'bg.error', color: 'fg.error' };
+
+/**
+ * Queue actions contributed to the frame's shared actions menu via the manifest
+ * `headerMenu` slot. This intentionally uses the same action model as the
+ * topbar queue menu so backend mutations keep local run coordination in sync.
+ */
+export const QueueHeaderMenu = () => {
+  const { t } = useTranslation();
+  const actions = useQueueMenuActions();
+  const counts = useQueueCounts();
+  const scope = useQueueQueryScope();
+  const notify = useNotify();
+
+  const clearFailed = useCallback(async () => {
+    try {
+      await clearFailedQueueItems(scope);
+      await refreshQueue();
+      notify.success(t('widgets.queue.failedItemsCleared'));
+    } catch (error) {
+      notify.error(
+        t('widgets.queue.failedToClearItems'),
+        getApiErrorMessage(error, t('widgets.queue.couldNotClearFailedItems'))
+      );
+    }
+  }, [notify, scope, t]);
+
+  const clearAll = useCallback(async () => {
+    try {
+      await clearScopedQueue(scope);
+      await refreshQueue();
+      notify.success(t('widgets.queue.queueCleared'));
+    } catch (error) {
+      notify.error(
+        t('widgets.queue.failedToClearQueue'),
+        getApiErrorMessage(error, t('widgets.queue.couldNotClearQueue'))
+      );
+    }
+  }, [notify, scope, t]);
+  const onClearFailed = useCallback(() => {
+    requestQueueConfirmation({
+      body: t('widgets.queue.clearFailedConfirmationBody'),
+      confirmLabel: t('widgets.queue.clearFailedItems'),
+      onConfirm: clearFailed,
+      title: t('widgets.queue.clearFailedTitle'),
+    });
+  }, [clearFailed, t]);
+  const onClearAll = useCallback(() => {
+    requestQueueConfirmation({
+      body: t('widgets.queue.clearQueueConfirmationBody'),
+      confirmLabel: t('widgets.queue.clearQueue'),
+      onConfirm: clearAll,
+      title: t('widgets.queue.clearQueueTitle'),
+    });
+  }, [clearAll, t]);
+
+  return (
+    <>
+      <QueueMenuItems actions={actions} label={t('widgets.labels.queue')} />
+      <Menu.Separator />
+      <Menu.ItemGroup>
+        <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+          {t('common.clear')}
+        </Menu.ItemGroupLabel>
+        <Menu.Item
+          color="fg.error"
+          disabled={counts.failed === 0}
+          value="clear-failed-items"
+          _hover={ERROR_ITEM_HOVER_PROPS}
+          onClick={onClearFailed}
+        >
+          <Icon as={Trash2Icon} boxSize="3" />
+          <Menu.ItemText>{t('widgets.queue.clearFailedItems')}</Menu.ItemText>
+        </Menu.Item>
+        <Menu.Item
+          color="fg.error"
+          disabled={counts.total === 0}
+          value="clear-all-items"
+          _hover={ERROR_ITEM_HOVER_PROPS}
+          onClick={onClearAll}
+        >
+          <Icon as={TrashIcon} boxSize="3" />
+          <Menu.ItemText>{t('widgets.queue.clearAllItems')}</Menu.ItemText>
+        </Menu.Item>
+      </Menu.ItemGroup>
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemActions.tsx
new file mode 100644
index 00000000000..a7d3be619c1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemActions.tsx
@@ -0,0 +1,113 @@
+import type { GenerateWidgetValues } from '@workbench/generation/types';
+
+import { ButtonGroup, Dialog, Icon, Portal } from '@chakra-ui/react';
+import { Button, CloseButton, JsonPreview, Tooltip } from '@workbench/components/ui';
+import { useNotify } from '@workbench/useNotify';
+import { useOpenWorkbenchWidget } from '@workbench/useOpenWorkbenchWidget';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { FileTextIcon, UndoIcon, WandSparklesIcon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { QueueServerItem } from './queueServerApi';
+
+/**
+ * Per-item actions for the RECENT details panel.
+ *
+ * - **Use again** recalls the exact submission snapshot into Generate (only the
+ *   submitting client has it; otherwise disabled — recall from the gallery).
+ * - **Send to canvas** is deferred (no canvas-import path exists in webv2 yet),
+ *   so it reports "coming soon" rather than silently no-op'ing.
+ * - **View JSON** opens the raw queue item (incl. its session) in a dialog.
+ */
+export const QueueItemActions = ({
+  item,
+  localGenerateValues,
+}: {
+  item: QueueServerItem;
+  localGenerateValues: GenerateWidgetValues | null;
+}) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const openWidget = useOpenWorkbenchWidget();
+  const notify = useNotify();
+  const [jsonOpen, setJsonOpen] = useState(false);
+
+  const canRecall = localGenerateValues !== null;
+
+  const onUseAgain = useCallback(() => {
+    if (!localGenerateValues) {
+      return;
+    }
+
+    dispatch({ type: 'setGenerateSettings', values: localGenerateValues });
+    openWidget('generate', { preferredRegions: ['left'] });
+    notify.success(t('widgets.queue.settingsRecalled'), t('widgets.queue.settingsRecalledDescription'));
+  }, [dispatch, localGenerateValues, notify, openWidget, t]);
+
+  const onSendToCanvas = useCallback(
+    () => notify.info(t('widgets.queue.sendToCanvas'), t('widgets.queue.sendToCanvasComingSoon')),
+    [notify, t]
+  );
+
+  const openJson = useCallback(() => setJsonOpen(true), []);
+  const closeJson = useCallback(() => setJsonOpen(false), []);
+
+  return (
+    <>
+      {/*<HStack flexWrap="wrap" gap="1.5">
+        <Tooltip content={canRecall ? 'Load these settings into Generate' : 'Recall this generation from the gallery'}>
+          <Button disabled={!canRecall} size="2xs" variant="surface" onClick={onUseAgain}>
+            Recall All
+          </Button>
+        </Tooltip>
+        <Button color="fg.subtle" size="2xs" variant="ghost" onClick={onSendToCanvas}>
+          Send to canvas
+        </Button>
+        <Button size="2xs" variant="surface" onClick={openJson}>
+          View JSON
+        </Button>
+      </HStack>*/}
+
+      <ButtonGroup size="2xs" variant="subtle">
+        <Tooltip
+          content={canRecall ? t('widgets.queue.loadSettingsIntoGenerate') : t('widgets.queue.recallFromGallery')}
+        >
+          <Button onClick={onUseAgain} disabled={!canRecall}>
+            <Icon as={UndoIcon} boxSize="3" />
+            {t('widgets.queue.recallAll')}
+          </Button>
+        </Tooltip>
+        <Button disabled variant="ghost" onClick={onSendToCanvas}>
+          <Icon as={WandSparklesIcon} boxSize="3" />
+          {t('widgets.queue.sendToCanvas')}
+        </Button>
+        <Button size="2xs" onClick={openJson}>
+          <Icon as={FileTextIcon} boxSize="3" />
+          {t('common.viewJson')}
+        </Button>
+      </ButtonGroup>
+
+      <Dialog.Root open={jsonOpen} placement="center" scrollBehavior="inside" size="lg" onOpenChange={closeJson}>
+        <Portal>
+          <Dialog.Backdrop />
+          <Dialog.Positioner>
+            <Dialog.Content bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" color="fg">
+              <Dialog.Header>
+                <Dialog.Title fontSize="sm" fontWeight="700">
+                  {t('widgets.queue.itemTitle', { id: item.item_id })}
+                </Dialog.Title>
+              </Dialog.Header>
+              <Dialog.Body>
+                <JsonPreview label={t('widgets.queue.itemJsonLabel', { id: item.item_id })} maxH="60vh" value={item} />
+              </Dialog.Body>
+              <Dialog.CloseTrigger asChild>
+                <CloseButton color="fg.muted" size="sm" />
+              </Dialog.CloseTrigger>
+            </Dialog.Content>
+          </Dialog.Positioner>
+        </Portal>
+      </Dialog.Root>
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemDetails.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemDetails.tsx
new file mode 100644
index 00000000000..a63fec4ab4f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemDetails.tsx
@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react';
+
+import { DataList, Separator, Text } from '@chakra-ui/react';
+import { useTranslation } from 'react-i18next';
+
+import type { QueueServerItem } from './queueServerApi';
+
+import { extractGenerationMeta } from './fieldValues';
+import { formatDuration } from './formatDuration';
+import { QueueItemActions } from './QueueItemActions';
+import { useLocalGenerateValues } from './useLocalGenerateValues';
+
+const DetailRow = ({ label, children }: { label: string; children: ReactNode }) => (
+  <DataList.Item key={label} alignItems="start">
+    <DataList.ItemLabel>{label}</DataList.ItemLabel>
+    <DataList.ItemValue fontFamily="mono" fontSize="2xs">
+      {children}
+    </DataList.ItemValue>
+  </DataList.Item>
+);
+
+/** Expanded detail grid + actions for a RECENT queue item row. */
+export const QueueItemDetails = ({ item }: { item: QueueServerItem }) => {
+  const { t } = useTranslation();
+  const meta = extractGenerationMeta(item);
+  const localGenerateValues = useLocalGenerateValues(item.origin);
+  const duration = formatDuration(item.started_at, item.completed_at);
+
+  return (
+    <DataList.Root gap="1.5" orientation="horizontal" size="sm">
+      <DetailRow label={t('common.prompt')}>{meta.positivePrompt ?? '—'}</DetailRow>
+      <DetailRow label={t('common.negative')}>{meta.negativePrompt ?? '—'}</DetailRow>
+      <DetailRow label={t('common.seed')}>
+        <Text as="span" fontVariantNumeric="tabular-nums">
+          {meta.seed ?? '—'}
+        </Text>
+      </DetailRow>
+      <DetailRow label={t('common.created')}>{new Date(item.created_at).toLocaleString()}</DetailRow>
+      <DetailRow label={t('widgets.queue.took')}>{duration ?? '—'}</DetailRow>
+      <DetailRow label={t('widgets.queue.batch')}>
+        <Text as="span" truncate>
+          {item.batch_id}
+        </Text>
+      </DetailRow>
+      <DetailRow label={t('common.item')}>
+        <Text as="span" fontVariantNumeric="tabular-nums">
+          #{item.item_id}
+        </Text>
+      </DetailRow>
+      {item.error_message ? (
+        <DetailRow label={t('common.error')}>
+          <Text as="span" color="fg.error">
+            {item.error_message}
+          </Text>
+        </DetailRow>
+      ) : null}
+
+      <Separator borderColor="border.subtle" my="0.5" />
+      <QueueItemActions item={item} localGenerateValues={localGenerateValues} />
+    </DataList.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemRow.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemRow.tsx
new file mode 100644
index 00000000000..9d5969f9162
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemRow.tsx
@@ -0,0 +1,100 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+import { Box, HStack, Icon, Stack, Text } from '@chakra-ui/react';
+import { useItemProgress } from '@workbench/backend/itemProgressStore';
+import { Row } from '@workbench/components/ui';
+import { ChevronRightIcon } from 'lucide-react';
+import { memo, useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { QueueServerItem } from './queueServerApi';
+
+import { CancelQueueItemButton } from './CancelQueueItemButton';
+import { extractGenerationMeta, getResultImageName } from './fieldValues';
+import { formatCompactAge, formatDuration } from './formatDuration';
+import { QueueItemDetails } from './QueueItemDetails';
+import { QueueItemThumbnail } from './QueueItemThumbnail';
+import { QueueStatusDot } from './QueueStatusDot';
+import { QueueStepProgress } from './QueueStepProgress';
+import { getStatusMeta } from './statusMeta';
+
+const CHEVRON_OPEN = { transform: 'rotate(90deg)' } as const;
+
+const QUEUE_ITEM_BUTTON_SX: SystemStyleObject = {
+  display: 'flex',
+  alignItems: 'center',
+  flex: 1,
+  gap: 2.5,
+  minH: 11,
+  minW: 0,
+  px: 2,
+  py: 1.5,
+  textAlign: 'start',
+  rounded: 'none',
+  transitionDuration: 'fastest',
+} as const;
+
+export const QueueItemRow = memo(({ item }: { item: QueueServerItem }) => {
+  const { t } = useTranslation();
+  const [expanded, setExpanded] = useState(false);
+  const toggle = useCallback(() => setExpanded((open) => !open), []);
+  const meta = extractGenerationMeta(item);
+  const duration = formatDuration(item.started_at, item.completed_at);
+  const age = formatCompactAge(item.completed_at ?? item.created_at);
+  const ageLabel = [duration, age].filter(Boolean).join(' · ');
+  const isFailed = item.status === 'failed';
+  const isCancellable = item.status === 'pending' || item.status === 'in_progress';
+  const progress = useItemProgress(item.item_id);
+  const liveImage = progress?.image ?? null;
+  const resultImageName = getResultImageName(item);
+  const statusLabel = t(getStatusMeta(item.status).labelKey);
+
+  const showBorder = expanded || isFailed;
+  const borderColor = showBorder ? (isFailed ? 'fg.error' : 'border') : 'transparent';
+
+  return (
+    <Box overflow="hidden" rounded="md" borderWidth={1} borderColor={borderColor}>
+      <HStack gap="0">
+        <Row aria-expanded={expanded} as="button" css={QUEUE_ITEM_BUTTON_SX} onClick={toggle}>
+          <QueueItemThumbnail boxSize="8" imageName={resultImageName} liveImage={liveImage} />
+          <Stack flex="1" gap="0.5" minW="0">
+            <Text fontSize="xs" truncate>
+              {meta.positivePrompt?.trim() || t('widgets.queue.noPrompt')}
+            </Text>
+            <HStack gap="1.5" minW="0">
+              <QueueStatusDot status={item.status} />
+              <Text color="fg.subtle" fontSize="2xs" fontVariantNumeric="tabular-nums" truncate>
+                {[statusLabel, ageLabel].filter(Boolean).join(' · ')}
+              </Text>
+            </HStack>
+          </Stack>
+          <Icon
+            as={ChevronRightIcon}
+            boxSize="4"
+            color="fg.muted"
+            flexShrink={0}
+            transition="transform var(--wb-motion-duration-fast) ease"
+            css={expanded ? CHEVRON_OPEN : undefined}
+          />
+        </Row>
+        {isCancellable ? (
+          <Box flexShrink={0} pe="1">
+            <CancelQueueItemButton itemId={item.item_id} />
+          </Box>
+        ) : null}
+      </HStack>
+
+      {item.status === 'in_progress' ? (
+        <Box px="2.5" pb="2">
+          <QueueStepProgress message={progress?.message ?? ''} percentage={progress?.percentage ?? null} />
+        </Box>
+      ) : null}
+
+      {expanded ? (
+        <Box pb="2.5" pt="1" px="2.5">
+          <QueueItemDetails item={item} />
+        </Box>
+      ) : null}
+    </Box>
+  );
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemThumbnail.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemThumbnail.tsx
new file mode 100644
index 00000000000..de350aad0d1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueItemThumbnail.tsx
@@ -0,0 +1,53 @@
+import { Icon, type SystemStyleObject } from '@chakra-ui/react';
+import { absolutizeApiUrl } from '@workbench/backend/http';
+import { StreamingImageFrame } from '@workbench/images/StreamingImageFrame';
+import { imageUrlToStreamingSource, progressImageToStreamingSource } from '@workbench/images/streamingImageSource';
+import { ImageOffIcon } from 'lucide-react';
+
+/**
+ * Square result preview for a queue item. Falls back to a deterministic gradient
+ * derived from the item id, so items without a (yet) resolvable image still read
+ * as distinct tiles — and the real thumbnail cross-fades in once loaded. A
+ * hairline inset outline (theme border token) gives the tile consistent edge
+ * depth without picking up the surface color underneath.
+ */
+const QUEUE_ITEM_THUMBNAIL_SX: SystemStyleObject = {
+  boxShadow: 'inset 0 0 0 1px {colors.border.subtle}',
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+} as const;
+const IMAGE_OFF_PLACEHOLDER = <Icon as={ImageOffIcon} w="4" h="4" />;
+
+export const QueueItemThumbnail = ({
+  imageName,
+  liveImage,
+  // seed,
+  boxSize = '8',
+  rounded = 'md',
+}: {
+  imageName: string | null;
+  liveImage?: { dataUrl: string; width: number; height: number } | null;
+  // seed: number;
+  boxSize?: string;
+  rounded?: string;
+}) => {
+  const finalImage = imageUrlToStreamingSource({
+    alt: imageName ?? '',
+    src: imageName ? absolutizeApiUrl(`/api/v1/images/i/${encodeURIComponent(imageName)}/thumbnail`) : null,
+  });
+
+  return (
+    <StreamingImageFrame
+      bg="bg.subtle"
+      boxSize={boxSize}
+      flexShrink={0}
+      finalImage={finalImage}
+      liveImage={progressImageToStreamingSource(liveImage)}
+      rounded={rounded}
+      css={QUEUE_ITEM_THUMBNAIL_SX}
+    >
+      {IMAGE_OFF_PLACEHOLDER}
+    </StreamingImageFrame>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStats.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStats.tsx
new file mode 100644
index 00000000000..e0575e419a1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStats.tsx
@@ -0,0 +1,30 @@
+import { SimpleGrid, Stat } from '@chakra-ui/react';
+import { useTranslation } from 'react-i18next';
+
+import { useScopedQueueCounts } from './queueScope';
+
+/**
+ * The four headline counts (done / failed / canceled / total) as a row of cards.
+ * Numbers are tabular so they stay aligned as the queue churns; the failed count
+ * turns danger-colored only when there's something to call out.
+ */
+const QueueStatCard = ({ value, label, danger }: { value: number; label: string; danger?: boolean }) => (
+  <Stat.Root size="sm" colorScheme={danger ? 'red' : undefined} gap="0">
+    <Stat.ValueText>{value}</Stat.ValueText>
+    <Stat.Label fontSize="xs">{label}</Stat.Label>
+  </Stat.Root>
+);
+
+export const QueueStats = () => {
+  const { t } = useTranslation();
+  const counts = useScopedQueueCounts();
+
+  return (
+    <SimpleGrid columns={4}>
+      <QueueStatCard label={t('common.done')} value={counts.completed} />
+      <QueueStatCard danger={counts.failed > 0} label={t('common.failed')} value={counts.failed} />
+      <QueueStatCard label={t('common.canceled')} value={counts.canceled} />
+      <QueueStatCard label={t('common.total')} value={counts.total} />
+    </SimpleGrid>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStatusDot.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStatusDot.tsx
new file mode 100644
index 00000000000..0d6a62d37d5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStatusDot.tsx
@@ -0,0 +1,26 @@
+import type { BackendQueueItemStatus } from '@workbench/backend/events';
+
+import { Box } from '@chakra-ui/react';
+import { useTranslation } from 'react-i18next';
+
+import { getStatusMeta } from './statusMeta';
+
+const ACTIVE_HALO = { boxShadow: '0 0 0 3px {colors.accent.subtle}' } as const;
+
+/** Small status indicator dot; the running state gets a soft accent halo. */
+export const QueueStatusDot = ({ status, boxSize = '2' }: { status: BackendQueueItemStatus; boxSize?: string }) => {
+  const { t } = useTranslation();
+  const { dotColor, labelKey } = getStatusMeta(status);
+
+  return (
+    <Box
+      aria-label={t(labelKey)}
+      bg={dotColor}
+      boxSize={boxSize}
+      flexShrink={0}
+      rounded="full"
+      role="img"
+      css={status === 'in_progress' ? ACTIVE_HALO : undefined}
+    />
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStepProgress.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStepProgress.tsx
new file mode 100644
index 00000000000..41bace05e70
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueStepProgress.tsx
@@ -0,0 +1,35 @@
+import { Progress, Stack, Text } from '@chakra-ui/react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Thin denoising progress bar with a "step 12/30 · 39%" caption. `percentage` is
+ * 0..1 (null → indeterminate). The caption uses tabular numerals so the live
+ * step count and percent don't shift the layout as they tick.
+ */
+export const QueueStepProgress = ({ message, percentage }: { message: string; percentage: number | null }) => {
+  const { t } = useTranslation();
+  const percentLabel = percentage !== null ? `${Math.round(percentage * 100)}%` : '';
+  const caption = [message.trim(), percentLabel].filter(Boolean).join(' · ');
+
+  return (
+    <Stack gap="1.5" w="full">
+      <Progress.Root
+        aria-label={t('widgets.queue.itemProgress')}
+        colorPalette="accent"
+        max={1}
+        size="xs"
+        value={percentage}
+        w="full"
+      >
+        <Progress.Track rounded="full">
+          <Progress.Range rounded="full" transition="width var(--wb-motion-duration-fast) ease" />
+        </Progress.Track>
+      </Progress.Root>
+      {caption ? (
+        <Text color="fg.subtle" fontSize="2xs" fontVariantNumeric="tabular-nums">
+          {caption}
+        </Text>
+      ) : null}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueWidgetView.tsx
new file mode 100644
index 00000000000..e85a7a95525
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/QueueWidgetView.tsx
@@ -0,0 +1,53 @@
+import type { WidgetViewProps } from '@workbench/types';
+
+import { Stack } from '@chakra-ui/react';
+import { StatusWidgetChip } from '@workbench/widget-frame';
+import { ListOrderedIcon } from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { QueueFilterId } from './queueFilters';
+
+import { CurrentBatchSection } from './NowNextSection';
+import { QueueFilterTabs } from './QueueFilterTabs';
+import { useScopedQueueCounts } from './queueScope';
+import { QueueStats } from './QueueStats';
+import { RecentSection } from './RecentSection';
+
+/**
+ * Queue console: server-wide stats, status filters, a live NOW & NEXT card, and
+ * the RECENT history. Header (title/Pause/menu) and the MODEL CACHE footer are
+ * provided through the manifest's chrome slots; this view is just the scrolling
+ * body. In a collapsed bottom dock it degrades to a single status chip.
+ */
+export const QueueWidgetView = ({ presentation, region }: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const counts = useScopedQueueCounts();
+
+  if (region === 'bottom' && presentation !== 'expanded') {
+    const isGenerating = counts.in_progress > 0;
+
+    return (
+      <StatusWidgetChip icon={ListOrderedIcon} tone={isGenerating ? 'accent' : undefined}>
+        {isGenerating
+          ? t('widgets.queue.generating', { count: counts.in_progress })
+          : t('widgets.queue.queued', { count: counts.pending })}
+      </StatusWidgetChip>
+    );
+  }
+
+  return <QueueContent />;
+};
+
+const QueueContent = () => {
+  const [filter, setFilter] = useState<QueueFilterId>('all');
+
+  return (
+    <Stack gap="3" p="3">
+      <QueueStats />
+      <QueueFilterTabs value={filter} onChange={setFilter} />
+      <CurrentBatchSection />
+      <RecentSection filter={filter} />
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/RecentSection.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/RecentSection.tsx
new file mode 100644
index 00000000000..677f1ec9b28
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/RecentSection.tsx
@@ -0,0 +1,49 @@
+import { Stack, Text } from '@chakra-ui/react';
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { QueueFilterId } from './queueFilters';
+
+import { useQueueLoadState } from './queueDataStore';
+import { matchesFilter } from './queueFilters';
+import { QueueItemRow } from './QueueItemRow';
+import { useScopedCurrentBatchItems, useScopedRecentItems } from './queueScope';
+import { SectionHeader } from './SectionHeader';
+
+/**
+ * RECENT — the windowed queue history, filtered by the active tab. The running
+ * and next items are excluded here since NOW & NEXT already shows them.
+ */
+export const RecentSection = ({ filter }: { filter: QueueFilterId }) => {
+  const { t } = useTranslation();
+  const currentBatchItems = useScopedCurrentBatchItems();
+  const items = useScopedRecentItems();
+  const { error, loadState } = useQueueLoadState();
+
+  const excluded = useMemo(() => new Set(currentBatchItems.map((item) => item.item_id)), [currentBatchItems]);
+  const filtered = useMemo(
+    () => items.filter((item) => !excluded.has(item.item_id) && matchesFilter(item.status, filter)),
+    [excluded, filter, items]
+  );
+
+  return (
+    <Stack gap="2">
+      <SectionHeader count={filtered.length} title={t('common.recent')} />
+      {filtered.length === 0 ? (
+        <Text color={loadState === 'error' ? 'fg.error' : 'fg.subtle'} fontSize="2xs" px="1">
+          {loadState === 'loading'
+            ? t('widgets.queue.loading')
+            : loadState === 'error'
+              ? error
+              : t('common.nothingHereYet')}
+        </Text>
+      ) : (
+        <Stack gap="1">
+          {filtered.map((item) => (
+            <QueueItemRow key={item.item_id} item={item} />
+          ))}
+        </Stack>
+      )}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/SectionHeader.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/SectionHeader.tsx
new file mode 100644
index 00000000000..c47af01bfcf
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/SectionHeader.tsx
@@ -0,0 +1,15 @@
+import { HStack, Text } from '@chakra-ui/react';
+
+/** Small uppercase section label with an optional count, e.g. "RECENT 13". */
+export const SectionHeader = ({ title, count }: { title: string; count?: number }) => (
+  <HStack gap="2" px="1">
+    <Text color="fg.muted" fontSize="2xs" fontWeight="700" letterSpacing="0.06em" textTransform="uppercase">
+      {title}
+    </Text>
+    {count !== undefined ? (
+      <Text color="fg.subtle" fontSize="2xs" fontVariantNumeric="tabular-nums">
+        {count}
+      </Text>
+    ) : null}
+  </HStack>
+);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/currentBatchItems.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/currentBatchItems.test.ts
new file mode 100644
index 00000000000..efb918a64df
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/currentBatchItems.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import type { QueueServerItem } from './queueServerApi';
+
+import { getCurrentBatchItems } from './currentBatchItems';
+
+const createItem = (item_id: number, batch_id: string, status: QueueServerItem['status']): QueueServerItem => ({
+  batch_id,
+  created_at: '2026-06-26T00:00:00Z',
+  item_id,
+  session_id: `session-${item_id}`,
+  status,
+  updated_at: '2026-06-26T00:00:00Z',
+});
+
+describe('getCurrentBatchItems', () => {
+  it('shows the current item and every pending item from the current batch', () => {
+    const current = createItem(2, 'batch-a', 'in_progress');
+    const items = [
+      createItem(4, 'batch-b', 'pending'),
+      createItem(3, 'batch-a', 'pending'),
+      current,
+      createItem(1, 'batch-a', 'completed'),
+    ];
+
+    expect(
+      getCurrentBatchItems({ current, items, next: createItem(3, 'batch-a', 'pending') }).map((item) => item.item_id)
+    ).toEqual([2, 3]);
+  });
+
+  it('uses the next item batch when there is no current item', () => {
+    const next = createItem(5, 'batch-c', 'pending');
+    const items = [createItem(6, 'batch-c', 'pending'), next, createItem(4, 'batch-b', 'pending')];
+
+    expect(getCurrentBatchItems({ current: null, items, next }).map((item) => item.item_id)).toEqual([5, 6]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/currentBatchItems.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/currentBatchItems.ts
new file mode 100644
index 00000000000..f494480517b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/currentBatchItems.ts
@@ -0,0 +1,40 @@
+import type { QueueServerItem } from './queueServerApi';
+
+const isCurrentBatchStatus = (status: QueueServerItem['status']): boolean =>
+  status === 'pending' || status === 'in_progress';
+
+export const getCurrentBatchItems = ({
+  current,
+  items,
+  next,
+}: {
+  current: QueueServerItem | null;
+  items: QueueServerItem[];
+  next: QueueServerItem | null;
+}): QueueServerItem[] => {
+  const batchId = current?.batch_id ?? next?.batch_id ?? null;
+
+  if (!batchId) {
+    return [];
+  }
+
+  const itemsById = new Map<number, QueueServerItem>();
+
+  for (const item of [current, next, ...items]) {
+    if (item && item.batch_id === batchId && isCurrentBatchStatus(item.status)) {
+      itemsById.set(item.item_id, item);
+    }
+  }
+
+  return [...itemsById.values()].sort((left, right) => {
+    if (left.status === 'in_progress' && right.status !== 'in_progress') {
+      return -1;
+    }
+
+    if (left.status !== 'in_progress' && right.status === 'in_progress') {
+      return 1;
+    }
+
+    return left.item_id - right.item_id;
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/fieldValues.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/fieldValues.ts
new file mode 100644
index 00000000000..4e27f471f85
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/fieldValues.ts
@@ -0,0 +1,68 @@
+import type { QueueServerItem } from './queueServerApi';
+
+/**
+ * Best-effort recovery of the human-facing generation parameters for a queue
+ * item. The reliable source is the local submission snapshot (matched in the
+ * view by origin), but server items from other clients/sources only carry
+ * `field_values` — generic `{node_path, field_name, value}` substitutions. For
+ * webv2 generate batches these are exactly the seed (number) + positive/negative
+ * prompts (strings), so we recover them by value type and order, degrading
+ * gracefully for unknown graphs.
+ */
+
+export interface QueueGenerationMeta {
+  positivePrompt?: string;
+  negativePrompt?: string;
+  seed?: number;
+}
+
+export const extractGenerationMeta = (item: QueueServerItem): QueueGenerationMeta => {
+  const meta: QueueGenerationMeta = {};
+  const prompts: string[] = [];
+
+  for (const fieldValue of item.field_values ?? []) {
+    const { value } = fieldValue;
+
+    if (typeof value === 'number' && meta.seed === undefined) {
+      meta.seed = value;
+    } else if (typeof value === 'string' && value.trim().length > 0) {
+      prompts.push(value);
+    }
+  }
+
+  if (prompts[0] !== undefined) {
+    meta.positivePrompt = prompts[0];
+  }
+
+  if (prompts[1] !== undefined) {
+    meta.negativePrompt = prompts[1];
+  }
+
+  return meta;
+};
+
+/** First result image name from a completed item's session, or null. */
+export const getResultImageName = (item: QueueServerItem): string | null => {
+  for (const result of Object.values(item.session?.results ?? {})) {
+    if (!result || typeof result !== 'object') {
+      continue;
+    }
+
+    const image = (result as { image?: { image_name?: unknown } }).image;
+    if (typeof image?.image_name === 'string') {
+      return image.image_name;
+    }
+
+    const collection = (result as { collection?: unknown }).collection;
+    if (Array.isArray(collection)) {
+      for (const entry of collection) {
+        const imageName = entry && typeof entry === 'object' ? (entry as { image_name?: unknown }).image_name : null;
+        if (typeof imageName === 'string') {
+          return imageName;
+        }
+      }
+    }
+  }
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/formatDuration.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/formatDuration.ts
new file mode 100644
index 00000000000..afb885348c0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/formatDuration.ts
@@ -0,0 +1,61 @@
+/**
+ * Compact execution-time labels for queue items ("4.37s", "1m 23s"). Computed
+ * from the backend's `started_at`/`completed_at` ISO timestamps; returns null
+ * when either is missing so callers can omit the field.
+ */
+export const formatDuration = (startedAt?: string | null, completedAt?: string | null): string | null => {
+  if (!startedAt || !completedAt) {
+    return null;
+  }
+
+  const seconds = (new Date(completedAt).getTime() - new Date(startedAt).getTime()) / 1000;
+
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    return null;
+  }
+
+  if (seconds < 60) {
+    return `${seconds.toFixed(2)}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+
+  if (minutes < 60) {
+    return `${minutes}m ${Math.round(seconds % 60)}s`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+
+  return `${hours}h ${minutes % 60}m`;
+};
+
+/** Ultra-compact "age" label for a timestamp ("now", "12s", "19m", "1h", "3d"). */
+export const formatCompactAge = (timestamp?: string | null): string => {
+  if (!timestamp) {
+    return '';
+  }
+
+  const seconds = (Date.now() - new Date(timestamp).getTime()) / 1000;
+
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    return '';
+  }
+
+  if (seconds < 5) {
+    return 'now';
+  }
+
+  if (seconds < 60) {
+    return `${Math.floor(seconds)}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+
+  return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/index.ts
new file mode 100644
index 00000000000..34251c79eb1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/index.ts
@@ -0,0 +1,30 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { ListOrderedIcon } from 'lucide-react';
+
+import { ModelCacheFooter } from './ModelCacheFooter';
+import { QueueDataRuntime } from './QueueDataRuntime';
+import { QueueHeaderActions } from './QueueHeaderActions';
+import { QueueHeaderLabel } from './QueueHeaderLabel';
+import { QueueHeaderMenu } from './QueueHeaderMenu';
+import { QueueWidgetView } from './QueueWidgetView';
+
+export const queueWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['right'],
+  failurePolicy: {
+    isolateRenderFailure: true,
+    onRegistrationFailure: 'disable',
+  },
+  footer: ModelCacheFooter,
+  headerActions: QueueHeaderActions,
+  headerMenu: QueueHeaderMenu,
+  host: QueueDataRuntime,
+  icon: ListOrderedIcon,
+  id: 'queue',
+  headerLabel: QueueHeaderLabel,
+  label: (t) => t('widgets.labels.queue'),
+  settingsSection: 'queue',
+  version: 1,
+  view: QueueWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/modelCacheStore.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/modelCacheStore.test.ts
new file mode 100644
index 00000000000..71ca812016c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/modelCacheStore.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { getModelCacheClearToast, getModelCacheUsage, normalizeModelCacheClearResult } from './modelCacheStore';
+
+const t = ((key: string, values?: Record<string, unknown>) => {
+  const translations: Record<string, string> = {
+    'widgets.queue.modelCache.cleared': 'Model cache cleared',
+    'widgets.queue.modelCache.clearedDescription': `Cleared ${values?.count} cached models and freed ${values?.bytes}.`,
+    'widgets.queue.modelCache.noModelsCleared': 'No cached models cleared',
+    'widgets.queue.modelCache.noModelsClearedDescription':
+      'No unlocked cached models were available to clear. Active models stay loaded until they are no longer in use.',
+  };
+
+  return translations[key] ?? key;
+}) as never;
+
+describe('model cache stats helpers', () => {
+  it('uses current cache usage instead of the historical high watermark', () => {
+    expect(
+      getModelCacheUsage({
+        cache_size: 100,
+        cache_used: 12,
+        cleared: 0,
+        high_watermark: 90,
+        hits: 0,
+        in_cache: 1,
+        misses: 0,
+      })
+    ).toEqual({ total: 100, used: 12 });
+  });
+
+  it('reports whether clear cache actually cleared models', () => {
+    expect(getModelCacheClearToast({ bytes_freed: 1024, models_cleared: 2 }, t)).toEqual({
+      description: 'Cleared 2 cached models and freed 1.0 KB.',
+      status: 'success',
+      title: 'Model cache cleared',
+    });
+
+    expect(getModelCacheClearToast({ bytes_freed: 0, models_cleared: 0 }, t)).toEqual({
+      description:
+        'No unlocked cached models were available to clear. Active models stay loaded until they are no longer in use.',
+      status: 'info',
+      title: 'No cached models cleared',
+    });
+  });
+
+  it('normalizes legacy null clear-cache responses', () => {
+    expect(normalizeModelCacheClearResult(null)).toEqual({ bytes_freed: 0, models_cleared: 0 });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/modelCacheStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/modelCacheStore.ts
new file mode 100644
index 00000000000..c18d368a093
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/modelCacheStore.ts
@@ -0,0 +1,106 @@
+import type { TFunction } from 'i18next';
+
+import { apiFetchJson, getApiErrorMessage } from '@workbench/backend/http';
+import { createExternalStore } from '@workbench/externalStore';
+import { formatBytes } from '@workbench/models/taxonomy';
+
+/**
+ * RAM/VRAM model-cache statistics for the Queue widget's footer. Pull-based:
+ * the backend exposes `GET /api/v2/models/stats` (no socket events for cache
+ * stats), so we refresh on mount, after a model loads, and after a clear.
+ */
+
+export interface ModelCacheStats {
+  hits: number;
+  misses: number;
+  /** Peak bytes resident in the cache. */
+  high_watermark: number;
+  /** Current bytes resident in the cache. */
+  cache_used?: number;
+  /** Number of models currently held in the cache. */
+  in_cache: number;
+  cleared: number;
+  /** Configured cache budget, in bytes. */
+  cache_size: number;
+  loaded_model_sizes?: Record<string, number>;
+}
+
+export interface ModelCacheClearResult {
+  models_cleared: number;
+  bytes_freed: number;
+}
+
+const EMPTY_MODEL_CACHE_CLEAR_RESULT: ModelCacheClearResult = { bytes_freed: 0, models_cleared: 0 };
+
+export const normalizeModelCacheClearResult = (result: ModelCacheClearResult | null): ModelCacheClearResult =>
+  result ?? EMPTY_MODEL_CACHE_CLEAR_RESULT;
+
+export const getModelCacheUsage = (stats: ModelCacheStats | null): { used: number; total: number } => ({
+  total: stats?.cache_size ?? 0,
+  used: stats?.cache_used ?? stats?.high_watermark ?? 0,
+});
+
+export const getModelCacheClearToast = (
+  { bytes_freed, models_cleared }: ModelCacheClearResult,
+  t: TFunction
+): { title: string; description: string; status: 'info' | 'success' } => {
+  if (models_cleared === 0) {
+    return {
+      description: t('widgets.queue.modelCache.noModelsClearedDescription'),
+      status: 'info',
+      title: t('widgets.queue.modelCache.noModelsCleared'),
+    };
+  }
+
+  return {
+    description: t('widgets.queue.modelCache.clearedDescription', {
+      bytes: formatBytes(bytes_freed),
+      count: models_cleared,
+    }),
+    status: 'success',
+    title: t('widgets.queue.modelCache.cleared'),
+  };
+};
+
+interface ModelCacheSnapshot {
+  stats: ModelCacheStats | null;
+  loadState: 'idle' | 'loading' | 'loaded' | 'error';
+  error: string | null;
+}
+
+const store = createExternalStore<ModelCacheSnapshot>({ error: null, loadState: 'idle', stats: null });
+
+let inflight: Promise<void> | null = null;
+
+export const refreshModelCacheStats = (): Promise<void> => {
+  if (inflight) {
+    return inflight;
+  }
+
+  if (store.getSnapshot().loadState === 'idle') {
+    store.patchSnapshot({ loadState: 'loading' });
+  }
+
+  inflight = apiFetchJson<ModelCacheStats | null>('/api/v2/models/stats')
+    .then((stats) => {
+      store.patchSnapshot({ error: null, loadState: 'loaded', stats });
+    })
+    .catch((error: unknown) => {
+      store.patchSnapshot({ error: getApiErrorMessage(error, 'Failed to load model cache stats'), loadState: 'error' });
+    })
+    .finally(() => {
+      inflight = null;
+    });
+
+  return inflight;
+};
+
+export const clearModelCache = async (): Promise<ModelCacheClearResult> => {
+  const result = await apiFetchJson<ModelCacheClearResult | null>('/api/v2/models/empty_model_cache', {
+    method: 'POST',
+  });
+  await refreshModelCacheStats();
+  return normalizeModelCacheClearResult(result);
+};
+
+export const useModelCacheStats = (): ModelCacheSnapshot => store.useSnapshot();
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueConfirmationStore.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueConfirmationStore.test.ts
new file mode 100644
index 00000000000..a997a5fda30
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueConfirmationStore.test.ts
@@ -0,0 +1,27 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearQueueConfirmation, getQueueConfirmation, requestQueueConfirmation } from './queueConfirmationStore';
+
+describe('queueConfirmationStore', () => {
+  beforeEach(() => {
+    clearQueueConfirmation();
+  });
+
+  it('keeps confirmation state outside the menu item lifecycle until explicitly cleared', () => {
+    const onConfirm = vi.fn();
+
+    requestQueueConfirmation({
+      body: 'Clear queued work?',
+      confirmLabel: 'Clear Queue',
+      onConfirm,
+      title: 'Clear queue?',
+    });
+
+    expect(getQueueConfirmation()).toMatchObject({
+      body: 'Clear queued work?',
+      confirmLabel: 'Clear Queue',
+      onConfirm,
+      title: 'Clear queue?',
+    });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueConfirmationStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueConfirmationStore.ts
new file mode 100644
index 00000000000..e83a53bdd77
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueConfirmationStore.ts
@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+
+import { createExternalStore } from '@workbench/externalStore';
+
+export interface QueueConfirmation {
+  body: ReactNode;
+  confirmLabel: string;
+  onConfirm: () => Promise<void> | void;
+  title: string;
+}
+
+const queueConfirmationStore = createExternalStore<{ confirmation: QueueConfirmation | null }>({ confirmation: null });
+
+export const requestQueueConfirmation = (confirmation: QueueConfirmation): void => {
+  queueConfirmationStore.setSnapshot({ confirmation });
+};
+
+export const clearQueueConfirmation = (): void => {
+  queueConfirmationStore.setSnapshot({ confirmation: null });
+};
+
+export const getQueueConfirmation = (): QueueConfirmation | null => queueConfirmationStore.getSnapshot().confirmation;
+
+export const useQueueConfirmation = (): QueueConfirmation | null =>
+  queueConfirmationStore.useSelector((snapshot) => snapshot.confirmation, Object.is);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueDataStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueDataStore.ts
new file mode 100644
index 00000000000..d0058d60ee5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueDataStore.ts
@@ -0,0 +1,165 @@
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { createExternalStore } from '@workbench/externalStore';
+import { shallowEqual } from '@workbench/workbenchSelectors';
+
+import type { QueueAndProcessorStatus, QueueQueryScope, QueueServerItem, QueueStatusCounts } from './queueServerApi';
+
+import { getCurrentBatchItems } from './currentBatchItems';
+import { clearProgressForQueueItemsWithResults } from './queueProgressCleanup';
+import {
+  getCurrentQueueItem,
+  getNextQueueItem,
+  getQueueItemIds,
+  getQueueItemsByIds,
+  getQueueStatus,
+} from './queueServerApi';
+
+/**
+ * Read model for the whole backend session queue, shared by the Queue widget's
+ * header, stats, CURRENT BATCH, and RECENT sections. A single external store fed by
+ * one debounced `refreshQueue()` keeps every section consistent and lets each
+ * subscribe to just the slice it renders (composition: one lifted store, many
+ * thin readers). Socket events drive refresh via `QueueDataRuntime`.
+ */
+
+/** How many of the most-recent items we hydrate for the RECENT list. */
+export const RECENT_WINDOW = 50;
+const REFRESH_DEBOUNCE_MS = 300;
+
+const EMPTY_COUNTS: QueueStatusCounts = {
+  canceled: 0,
+  completed: 0,
+  failed: 0,
+  in_progress: 0,
+  pending: 0,
+  queue_id: 'default',
+  total: 0,
+};
+
+interface QueueDataSnapshot {
+  status: QueueAndProcessorStatus | null;
+  current: QueueServerItem | null;
+  next: QueueServerItem | null;
+  items: QueueServerItem[];
+  scope: QueueQueryScope;
+  loadState: 'idle' | 'loading' | 'loaded' | 'error';
+  error: string | null;
+}
+
+const store = createExternalStore<QueueDataSnapshot>({
+  current: null,
+  error: null,
+  items: [],
+  loadState: 'idle',
+  next: null,
+  scope: {},
+  status: null,
+});
+
+let inflight: Promise<void> | null = null;
+let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+let needsRefresh = false;
+let refreshSequence = 0;
+
+const runRefresh = async (): Promise<void> => {
+  const scope = store.getSnapshot().scope;
+  const sequence = ++refreshSequence;
+
+  if (store.getSnapshot().loadState === 'idle') {
+    store.patchSnapshot({ loadState: 'loading' });
+  }
+
+  try {
+    // Independent reads run together to avoid a request waterfall; the window
+    // fetch is the only one that must wait (it needs the ordered ids first).
+    const [status, current, next, idsResult] = await Promise.all([
+      getQueueStatus(scope),
+      getCurrentQueueItem(scope),
+      getNextQueueItem(scope),
+      getQueueItemIds('desc', scope),
+    ]);
+    const items = await getQueueItemsByIds(idsResult.item_ids.slice(0, RECENT_WINDOW));
+
+    if (sequence === refreshSequence) {
+      clearProgressForQueueItemsWithResults([current, next, ...items].filter((item) => item !== null));
+      store.patchSnapshot({ current, error: null, items, loadState: 'loaded', next, status });
+    }
+  } catch (error) {
+    if (sequence === refreshSequence) {
+      store.patchSnapshot({ error: getApiErrorMessage(error, 'Failed to load queue'), loadState: 'error' });
+    }
+  }
+};
+
+const runRefreshLoop = async (): Promise<void> => {
+  do {
+    needsRefresh = false;
+    await runRefresh();
+  } while (needsRefresh);
+};
+
+/** Coalesced refresh — many socket events in a burst collapse into one fetch. */
+export const refreshQueue = (): Promise<void> => {
+  if (inflight !== null && refreshTimer === null) {
+    needsRefresh = true;
+    return inflight;
+  }
+
+  if (refreshTimer !== null) {
+    return inflight ?? Promise.resolve();
+  }
+
+  inflight = new Promise<void>((resolve) => {
+    refreshTimer = setTimeout(() => {
+      refreshTimer = null;
+      void runRefreshLoop().finally(() => {
+        inflight = null;
+        resolve();
+      });
+    }, REFRESH_DEBOUNCE_MS);
+  });
+
+  return inflight;
+};
+
+export const setQueueScope = (scope: QueueQueryScope): void => {
+  const previous = store.getSnapshot().scope;
+  const isSameScope = previous.originPrefix === scope.originPrefix;
+
+  if (isSameScope) {
+    return;
+  }
+
+  store.patchSnapshot({ current: null, error: null, items: [], loadState: 'loading', next: null, scope, status: null });
+  void refreshQueue();
+};
+
+/** First load — idempotent; safe to call from every mounting surface. */
+export const ensureQueueLoaded = (): void => {
+  if (store.getSnapshot().loadState === 'idle') {
+    void refreshQueue();
+  }
+};
+
+// --- Selectors / hooks -----------------------------------------------------
+
+export const useQueueCounts = (): QueueStatusCounts =>
+  store.useSelector((snapshot) => snapshot.status?.queue ?? EMPTY_COUNTS, shallowEqual);
+
+/** The processor is "paused" when it has been stopped (`is_started` false). */
+export const useIsProcessorPaused = (): boolean =>
+  store.useSelector((snapshot) => snapshot.status?.processor.is_started === false);
+
+export const useNowNextItems = (): { current: QueueServerItem | null; next: QueueServerItem | null } =>
+  store.useSelector((snapshot) => ({ current: snapshot.current, next: snapshot.next }), shallowEqual);
+
+export const useCurrentBatchItems = (): QueueServerItem[] =>
+  store.useSelector(
+    (snapshot) => getCurrentBatchItems({ current: snapshot.current, items: snapshot.items, next: snapshot.next }),
+    shallowEqual
+  );
+
+export const useRecentItems = (): QueueServerItem[] => store.useSelector((snapshot) => snapshot.items);
+
+export const useQueueLoadState = (): { loadState: QueueDataSnapshot['loadState']; error: string | null } =>
+  store.useSelector((snapshot) => ({ error: snapshot.error, loadState: snapshot.loadState }), shallowEqual);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueFilters.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueFilters.ts
new file mode 100644
index 00000000000..f57e3ef22b6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueFilters.ts
@@ -0,0 +1,44 @@
+import type { BackendQueueItemStatus } from '@workbench/backend/events';
+
+import type { QueueStatusCounts } from './queueServerApi';
+
+/** Status filters for the RECENT list, matching the screenshot's tab row. */
+export type QueueFilterId = 'all' | 'active' | 'completed' | 'failed' | 'canceled';
+
+export const QUEUE_FILTERS: { id: QueueFilterId; labelKey: string }[] = [
+  { id: 'all', labelKey: 'common.all' },
+  { id: 'active', labelKey: 'common.active' },
+  { id: 'completed', labelKey: 'common.done' },
+  { id: 'failed', labelKey: 'common.failed' },
+  { id: 'canceled', labelKey: 'common.canceled' },
+];
+
+export const matchesFilter = (status: BackendQueueItemStatus, filter: QueueFilterId): boolean => {
+  if (filter === 'all') {
+    return true;
+  }
+
+  if (filter === 'active') {
+    return status === 'pending' || status === 'in_progress';
+  }
+
+  return status === filter;
+};
+
+/** Count for a filter, derived from the server-wide status counts (not the windowed list). */
+export const getFilterCount = (counts: QueueStatusCounts, filter: QueueFilterId): number => {
+  switch (filter) {
+    case 'all':
+      return counts.total;
+    case 'active':
+      return counts.pending + counts.in_progress;
+    case 'completed':
+      return counts.completed;
+    case 'failed':
+      return counts.failed;
+    case 'canceled':
+      return counts.canceled;
+    default:
+      return 0;
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueMenuActions.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueMenuActions.test.ts
new file mode 100644
index 00000000000..3f7864b9afb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueMenuActions.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { getQueueMenuActions } from './queueMenuActions';
+
+describe('getQueueMenuActions', () => {
+  it('uses the same cancellation and processor actions for topbar and widget menus', () => {
+    const actions = getQueueMenuActions({
+      labels: {
+        cancelAll: 'Cancel All Items',
+        cancelAllExceptCurrent: 'Cancel all except current item',
+        cancelCurrent: 'Cancel Current Item',
+        openQueue: 'Open Queue',
+        pauseProcessor: 'Pause Processor',
+        resumeProcessor: 'Resume Processor',
+      },
+      cancellableCount: 2,
+      canManageProcessor: true,
+      hasPendingQueueWork: true,
+      hasRunningItem: true,
+      isConnected: true,
+      onCancelAll: vi.fn(),
+      onCancelAllExceptCurrent: vi.fn(),
+      onCancelCurrent: vi.fn(),
+      onOpenQueue: vi.fn(),
+      onPauseProcessor: vi.fn(),
+      onResumeProcessor: vi.fn(),
+    });
+
+    expect(actions.map((action) => action.label)).toEqual([
+      'Cancel Current Item',
+      'Cancel All Items',
+      'Cancel all except current item',
+      'Resume Processor',
+      'Pause Processor',
+      'Open Queue',
+    ]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueMenuActions.tsx b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueMenuActions.tsx
new file mode 100644
index 00000000000..3e887004777
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueMenuActions.tsx
@@ -0,0 +1,285 @@
+import { Icon, Menu } from '@chakra-ui/react';
+import { useCapabilities } from '@workbench/auth/capabilities';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { useNotify } from '@workbench/useNotify';
+import { useOpenWorkbenchWidget } from '@workbench/useOpenWorkbenchWidget';
+import { useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { ListOrderedIcon, PauseIcon, PlayIcon, XIcon, type LucideIcon } from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { requestQueueConfirmation } from './queueConfirmationStore';
+import { refreshQueue, useNowNextItems, useQueueCounts } from './queueDataStore';
+import { useQueueQueryScope } from './queueScope';
+import { cancelQueueItem, cancelScopedQueueItems, pauseQueueProcessor, resumeQueueProcessor } from './queueServerApi';
+
+const ERROR_ITEM_HOVER_PROPS = { bg: 'bg.error', color: 'fg.error' };
+
+interface QueueMenuActionInputs {
+  labels: {
+    cancelAll: string;
+    cancelAllExceptCurrent: string;
+    cancelCurrent: string;
+    openQueue: string;
+    pauseProcessor: string;
+    resumeProcessor: string;
+  };
+  cancellableCount: number;
+  hasPendingQueueWork: boolean;
+  hasRunningItem: boolean;
+  isConnected: boolean;
+  canManageProcessor: boolean;
+  onCancelAll: () => void;
+  onCancelAllExceptCurrent: () => void;
+  onCancelCurrent: () => void;
+  onOpenQueue: () => void;
+  onPauseProcessor: () => void;
+  onResumeProcessor: () => void;
+}
+
+export interface QueueMenuAction {
+  label: string;
+  icon: LucideIcon;
+  disabled: boolean;
+  destructive?: boolean;
+  onClick: () => void;
+}
+
+export const getQueueMenuActions = ({
+  labels,
+  cancellableCount,
+  hasPendingQueueWork,
+  hasRunningItem,
+  isConnected,
+  canManageProcessor,
+  onCancelAll,
+  onCancelAllExceptCurrent,
+  onCancelCurrent,
+  onOpenQueue,
+  onPauseProcessor,
+  onResumeProcessor,
+}: QueueMenuActionInputs): QueueMenuAction[] => [
+  {
+    destructive: true,
+    disabled: !isConnected || !hasRunningItem,
+    icon: XIcon,
+    label: labels.cancelCurrent,
+    onClick: onCancelCurrent,
+  },
+  {
+    destructive: true,
+    disabled: cancellableCount === 0,
+    icon: XIcon,
+    label: labels.cancelAll,
+    onClick: onCancelAll,
+  },
+  {
+    destructive: true,
+    disabled: !isConnected || !hasPendingQueueWork,
+    icon: XIcon,
+    label: labels.cancelAllExceptCurrent,
+    onClick: onCancelAllExceptCurrent,
+  },
+  {
+    disabled: !isConnected || !canManageProcessor,
+    icon: PlayIcon,
+    label: labels.resumeProcessor,
+    onClick: onResumeProcessor,
+  },
+  {
+    disabled: !isConnected || !canManageProcessor,
+    icon: PauseIcon,
+    label: labels.pauseProcessor,
+    onClick: onPauseProcessor,
+  },
+  {
+    disabled: false,
+    icon: ListOrderedIcon,
+    label: labels.openQueue,
+    onClick: onOpenQueue,
+  },
+];
+
+export const useQueueMenuActions = (): QueueMenuAction[] => {
+  const { t } = useTranslation();
+  const backendConnectionStatus = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection.status);
+  const counts = useQueueCounts();
+  const { current } = useNowNextItems();
+  const scope = useQueueQueryScope();
+  const { canManageModels } = useCapabilities();
+  const notify = useNotify();
+  const openWorkbenchWidget = useOpenWorkbenchWidget();
+  const isConnected = backendConnectionStatus === 'connected';
+  const cancellableCount = counts.pending + counts.in_progress;
+  const hasRunningItem = current?.status === 'in_progress';
+  const hasPendingQueueWork = counts.pending > 0;
+
+  const cancelCurrent = useCallback(() => {
+    if (!current) {
+      notify.info(t('widgets.queue.noCurrentItem'), t('widgets.queue.noCurrentItemDescription'));
+      return;
+    }
+
+    cancelQueueItem(current.item_id)
+      .then(() => refreshQueue())
+      .then(() =>
+        notify.success(
+          t('widgets.queue.cancellationRequested'),
+          t('widgets.queue.backendItem', { id: current.item_id })
+        )
+      )
+      .catch((error: unknown) =>
+        notify.error(
+          t('widgets.queue.failedToCancelCurrentItem'),
+          getApiErrorMessage(error, t('widgets.queue.couldNotCancelCurrentItem'))
+        )
+      );
+  }, [current, notify, t]);
+
+  const cancelAllExceptCurrent = useCallback(() => {
+    cancelScopedQueueItems(scope, current?.item_id ?? null)
+      .then(() => refreshQueue())
+      .then(() =>
+        notify.success(
+          t('widgets.queue.queueCancellationRequested'),
+          t('widgets.queue.cancelAllExceptCurrentRequested')
+        )
+      )
+      .catch((error: unknown) =>
+        notify.error(
+          t('widgets.queue.failedToCancelItems'),
+          getApiErrorMessage(error, t('widgets.queue.couldNotCancelItems'))
+        )
+      );
+  }, [current?.item_id, notify, scope, t]);
+
+  const runProcessorAction = useCallback(
+    (label: 'pause' | 'resume') => {
+      const action = label === 'pause' ? pauseQueueProcessor : resumeQueueProcessor;
+
+      action()
+        .then(() =>
+          notify.success(label === 'pause' ? t('widgets.queue.processorPaused') : t('widgets.queue.processorResumed'))
+        )
+        .then(() => refreshQueue())
+        .catch((error: unknown) =>
+          notify.error(
+            label === 'pause' ? t('widgets.queue.failedToPauseProcessor') : t('widgets.queue.failedToResumeProcessor'),
+            getApiErrorMessage(error, t('widgets.queue.couldNotChangeProcessor'))
+          )
+        );
+    },
+    [notify, t]
+  );
+  const cancelAll = useCallback(() => {
+    cancelScopedQueueItems(scope)
+      .then(() => refreshQueue())
+      .then(() =>
+        notify.success(t('widgets.queue.queueCancellationRequested'), t('widgets.queue.allScopedItemsRequested'))
+      )
+      .catch((error: unknown) =>
+        notify.error(
+          t('widgets.queue.failedToCancelItems'),
+          getApiErrorMessage(error, t('widgets.queue.couldNotCancelItems'))
+        )
+      );
+  }, [notify, scope, t]);
+  const resumeProcessor = useCallback(() => runProcessorAction('resume'), [runProcessorAction]);
+  const pauseProcessor = useCallback(() => runProcessorAction('pause'), [runProcessorAction]);
+  const openQueue = useCallback(() => openWorkbenchWidget('queue'), [openWorkbenchWidget]);
+
+  return useMemo(
+    () =>
+      getQueueMenuActions({
+        labels: {
+          cancelAll: t('widgets.queue.cancelAllItems'),
+          cancelAllExceptCurrent: t('widgets.queue.cancelAllExceptCurrent'),
+          cancelCurrent: t('widgets.queue.cancelCurrentItem'),
+          openQueue: t('widgets.queue.openQueue'),
+          pauseProcessor: t('widgets.queue.pauseProcessor'),
+          resumeProcessor: t('widgets.queue.resumeProcessor'),
+        },
+        cancellableCount,
+        canManageProcessor: canManageModels,
+        hasPendingQueueWork,
+        hasRunningItem,
+        isConnected,
+        onCancelAll: cancelAll,
+        onCancelAllExceptCurrent: cancelAllExceptCurrent,
+        onCancelCurrent: cancelCurrent,
+        onOpenQueue: openQueue,
+        onPauseProcessor: pauseProcessor,
+        onResumeProcessor: resumeProcessor,
+      }),
+    [
+      cancelAll,
+      cancelAllExceptCurrent,
+      cancelCurrent,
+      cancellableCount,
+      canManageModels,
+      hasPendingQueueWork,
+      hasRunningItem,
+      isConnected,
+      openQueue,
+      pauseProcessor,
+      resumeProcessor,
+      t,
+    ]
+  );
+};
+
+export const QueueMenuItems = ({ actions, label }: { actions: QueueMenuAction[]; label?: string }) => {
+  const destructiveActions = actions.filter((action) => action.destructive);
+  const processorActions = actions.filter((action) => !action.destructive);
+
+  return (
+    <>
+      <Menu.ItemGroup>
+        {label ? (
+          <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+            {label}
+          </Menu.ItemGroupLabel>
+        ) : null}
+        {destructiveActions.map((action) => (
+          <DestructiveQueueMenuItem key={action.label} action={action} />
+        ))}
+      </Menu.ItemGroup>
+      <Menu.Separator />
+      <Menu.ItemGroup>
+        {processorActions.map((action) => (
+          <Menu.Item key={action.label} disabled={action.disabled} value={action.label} onClick={action.onClick}>
+            <Icon as={action.icon} boxSize="3" />
+            <Menu.ItemText>{action.label}</Menu.ItemText>
+          </Menu.Item>
+        ))}
+      </Menu.ItemGroup>
+    </>
+  );
+};
+
+const DestructiveQueueMenuItem = ({ action }: { action: QueueMenuAction }) => {
+  const { t } = useTranslation();
+  const onClick = useCallback(
+    () =>
+      requestQueueConfirmation({
+        body: t('widgets.queue.cancelConfirmationBody'),
+        confirmLabel: action.label,
+        onConfirm: action.onClick,
+        title: t('widgets.queue.actionConfirmationTitle', { action: action.label }),
+      }),
+    [action, t]
+  );
+
+  return (
+    <Menu.Item
+      color="fg.error"
+      disabled={action.disabled}
+      value={action.label}
+      _hover={ERROR_ITEM_HOVER_PROPS}
+      onClick={onClick}
+    >
+      <Icon as={action.icon} boxSize="3" />
+      <Menu.ItemText>{action.label}</Menu.ItemText>
+    </Menu.Item>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueProgressCleanup.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueProgressCleanup.test.ts
new file mode 100644
index 00000000000..03d7eec07a6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueProgressCleanup.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+
+import type { QueueServerItem } from './queueServerApi';
+
+import { getQueueItemIdsWithResultImages } from './queueProgressCleanup';
+
+const createItem = (itemId: number, results: Record<string, unknown> = {}): QueueServerItem => ({
+  batch_id: 'batch-1',
+  created_at: '2026-06-27T00:00:00Z',
+  item_id: itemId,
+  session: { results },
+  session_id: 'session-1',
+  status: 'completed',
+  updated_at: '2026-06-27T00:00:00Z',
+});
+
+describe('getQueueItemIdsWithResultImages', () => {
+  it('returns queue item ids that have final image results', () => {
+    expect(
+      getQueueItemIdsWithResultImages([
+        createItem(1),
+        createItem(2, { node: { image: { image_name: 'result.png' } } }),
+        createItem(3, { node: { collection: [{ image_name: 'batch-result.png' }] } }),
+      ])
+    ).toEqual([2, 3]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueProgressCleanup.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueProgressCleanup.ts
new file mode 100644
index 00000000000..00dfc40566f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueProgressCleanup.ts
@@ -0,0 +1,23 @@
+import { itemProgressStore } from '@workbench/backend/itemProgressStore';
+
+import type { QueueServerItem } from './queueServerApi';
+
+import { getResultImageName } from './fieldValues';
+
+export const getQueueItemIdsWithResultImages = (items: QueueServerItem[]): number[] => {
+  const itemIds: number[] = [];
+
+  for (const item of items) {
+    if (getResultImageName(item)) {
+      itemIds.push(item.item_id);
+    }
+  }
+
+  return itemIds;
+};
+
+export const clearProgressForQueueItemsWithResults = (items: QueueServerItem[]): void => {
+  for (const itemId of getQueueItemIdsWithResultImages(items)) {
+    itemProgressStore.clear(itemId);
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueScope.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueScope.test.ts
new file mode 100644
index 00000000000..2d6bacc8c09
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueScope.test.ts
@@ -0,0 +1,69 @@
+import type { Project, QueueItem } from '@workbench/types';
+
+import { buildQueueItemOrigin, buildProjectQueueItemOriginPrefix } from '@workbench/backend/events';
+import { describe, expect, it } from 'vitest';
+
+import type { QueueServerItem } from './queueServerApi';
+
+import { getQueueQueryScope, isQueueServerItemInProject } from './queueScope';
+
+const createProject = (items: QueueItem[]): Project =>
+  ({
+    id: 'project-1',
+    name: 'Project 1',
+    queue: { items },
+  }) as Project;
+
+const createLocalQueueItem = ({
+  backendItemIds,
+  id,
+  status,
+}: {
+  backendItemIds?: number[];
+  id: string;
+  status: QueueItem['status'];
+}): QueueItem =>
+  ({
+    backendItemIds,
+    id,
+    status,
+  }) as QueueItem;
+
+const createServerQueueItem = ({ itemId, origin }: { itemId: number; origin?: string | null }): QueueServerItem =>
+  ({
+    item_id: itemId,
+    origin,
+  }) as QueueServerItem;
+
+describe('isQueueServerItemInProject', () => {
+  it('matches server queue items by webv2 origin', () => {
+    const project = createProject([createLocalQueueItem({ id: 'local-1', status: 'pending' })]);
+
+    expect(
+      isQueueServerItemInProject(
+        createServerQueueItem({ itemId: 7, origin: buildQueueItemOrigin('local-1', 'project-1') }),
+        project
+      )
+    ).toBe(true);
+    expect(isQueueServerItemInProject(createServerQueueItem({ itemId: 7, origin: 'webv2:local-1' }), project)).toBe(
+      true
+    );
+    expect(isQueueServerItemInProject(createServerQueueItem({ itemId: 8, origin: 'webv2:local-2' }), project)).toBe(
+      false
+    );
+  });
+
+  it('falls back to backend item ids when origin is unavailable', () => {
+    const project = createProject([createLocalQueueItem({ backendItemIds: [7, 8], id: 'local-1', status: 'running' })]);
+
+    expect(isQueueServerItemInProject(createServerQueueItem({ itemId: 8, origin: null }), project)).toBe(true);
+    expect(isQueueServerItemInProject(createServerQueueItem({ itemId: 9, origin: null }), project)).toBe(false);
+  });
+  it('builds backend origin-prefix scopes from the active project', () => {
+    expect(getQueueQueryScope({ projectId: 'project-1', queueJobsScope: 'active-project' })).toEqual({
+      originPrefix: buildProjectQueueItemOriginPrefix('project-1'),
+    });
+
+    expect(getQueueQueryScope({ projectId: 'project-1', queueJobsScope: 'all' })).toEqual({});
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueScope.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueScope.ts
new file mode 100644
index 00000000000..f2358803f0e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueScope.ts
@@ -0,0 +1,48 @@
+import type { Project, WorkbenchPreferences } from '@workbench/types';
+
+import { buildProjectQueueItemOriginPrefix, parseQueueItemOrigin } from '@workbench/backend/events';
+import { useWorkbenchPreferences } from '@workbench/settings/store';
+import { useOptionalWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { useMemo } from 'react';
+
+import type { QueueQueryScope, QueueServerItem } from './queueServerApi';
+
+import { useCurrentBatchItems, useQueueCounts, useRecentItems } from './queueDataStore';
+
+export type QueueJobsScope = WorkbenchPreferences['queueJobsScope'];
+
+export const isQueueServerItemInProject = (serverItem: QueueServerItem, project: Pick<Project, 'queue'>): boolean => {
+  const localQueueItemId = parseQueueItemOrigin(serverItem.origin);
+
+  if (localQueueItemId && project.queue.items.some((item) => item.id === localQueueItemId)) {
+    return true;
+  }
+
+  return project.queue.items.some((item) => item.backendItemIds?.includes(serverItem.item_id) ?? false);
+};
+
+export const useQueueJobsScope = (): QueueJobsScope => useWorkbenchPreferences().queueJobsScope;
+
+export const getQueueQueryScope = ({
+  projectId,
+  queueJobsScope,
+}: {
+  projectId: string | null;
+  queueJobsScope: QueueJobsScope;
+}): QueueQueryScope =>
+  queueJobsScope === 'active-project' && projectId
+    ? { originPrefix: buildProjectQueueItemOriginPrefix(projectId) }
+    : {};
+
+export const useQueueQueryScope = (): QueueQueryScope => {
+  const queueJobsScope = useQueueJobsScope();
+  const projectId = useOptionalWorkbenchSelector((snapshot) => snapshot.activeProject.id, null);
+
+  return useMemo(() => getQueueQueryScope({ projectId, queueJobsScope }), [projectId, queueJobsScope]);
+};
+
+export const useScopedQueueCounts = useQueueCounts;
+
+export const useScopedCurrentBatchItems = useCurrentBatchItems;
+
+export const useScopedRecentItems = useRecentItems;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueServerApi.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueServerApi.test.ts
new file mode 100644
index 00000000000..65105d004d1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueServerApi.test.ts
@@ -0,0 +1,50 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  apiFetchJson: vi.fn(),
+}));
+
+vi.mock('@workbench/backend/http', () => ({
+  apiFetchJson: mocks.apiFetchJson,
+}));
+
+describe('queueServerApi', () => {
+  beforeEach(() => {
+    mocks.apiFetchJson.mockReset();
+    mocks.apiFetchJson.mockResolvedValue({ item_ids: [], total_count: 0 });
+  });
+
+  it('uses backend SQLiteDirection values for queue item ordering', async () => {
+    const { getQueueItemIds } = await import('./queueServerApi');
+
+    await getQueueItemIds('desc');
+
+    expect(mocks.apiFetchJson).toHaveBeenCalledWith('/api/v1/queue/default/item_ids?order_dir=DESC');
+  });
+
+  it('deletes only failed queue items when clearing failed items', async () => {
+    mocks.apiFetchJson.mockImplementation((url: string) => {
+      if (url === '/api/v1/queue/default/item_ids?order_dir=DESC') {
+        return Promise.resolve({ item_ids: [3, 2, 1], total_count: 3 });
+      }
+
+      if (url === '/api/v1/queue/default/items_by_ids') {
+        return Promise.resolve([
+          { item_id: 3, status: 'completed' },
+          { item_id: 2, status: 'failed' },
+          { item_id: 1, status: 'pending' },
+        ]);
+      }
+
+      return Promise.resolve({});
+    });
+
+    const { clearFailedQueueItems } = await import('./queueServerApi');
+
+    await clearFailedQueueItems();
+
+    expect(mocks.apiFetchJson).toHaveBeenCalledWith('/api/v1/queue/default/i/2', { method: 'DELETE' });
+    expect(mocks.apiFetchJson).not.toHaveBeenCalledWith('/api/v1/queue/default/i/1', { method: 'DELETE' });
+    expect(mocks.apiFetchJson).not.toHaveBeenCalledWith('/api/v1/queue/default/i/3', { method: 'DELETE' });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueServerApi.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueServerApi.ts
new file mode 100644
index 00000000000..40ae4007682
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueServerApi.ts
@@ -0,0 +1,208 @@
+import type { BackendQueueItemStatus } from '@workbench/backend/events';
+
+import { apiFetchJson } from '@workbench/backend/http';
+
+/**
+ * Server-wide session-queue REST layer for the Queue widget. This mirrors the
+ * legacy v6 queue API surface (`frontend/web/src/services/api/endpoints/queue.ts`)
+ * — the same status/list/current/next reads, the `item_ids → items_by_ids`
+ * windowed pagination, and the clear/prune/cancel/pause mutations — ported to
+ * webv2's `apiFetchJson` idiom. Socket events drive refresh (see
+ * `queueDataStore` + `QueueDataRuntime`) in place of RTK Query tag invalidation.
+ *
+ * Unlike the local in-session queue (`project.queue.items`, which only tracks
+ * this client's submissions), this reads the whole backend queue: counts and
+ * items from every source and every client.
+ */
+
+const QUEUE_ID = 'default';
+const buildQueueUrl = (path = ''): string => `/api/v1/queue/${QUEUE_ID}/${path}`;
+
+export interface QueueQueryScope {
+  originPrefix?: string;
+}
+
+const buildQueryString = (params: Record<string, string | undefined>): string => {
+  const searchParams = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) {
+      searchParams.set(key, value);
+    }
+  }
+
+  const queryString = searchParams.toString();
+
+  return queryString ? `?${queryString}` : '';
+};
+
+/** A single batch substitution recorded for a queue item (prompt / seed / image field). */
+export interface QueueNodeFieldValue {
+  node_path: string;
+  field_name: string;
+  value: string | number | { image_name?: string } | null;
+}
+
+/**
+ * The backend `SessionQueueItem` shape, narrowed to the fields the widget reads.
+ * `session` is the heavy execution graph; we only ever touch `session.results`
+ * to resolve a result image, so it is loosely typed here.
+ */
+export interface QueueServerItem {
+  item_id: number;
+  status: BackendQueueItemStatus;
+  batch_id: string;
+  origin?: string | null;
+  destination?: string | null;
+  session_id: string;
+  error_type?: string | null;
+  error_message?: string | null;
+  error_traceback?: string | null;
+  created_at: string;
+  updated_at: string;
+  started_at?: string | null;
+  completed_at?: string | null;
+  field_values?: QueueNodeFieldValue[] | null;
+  retried_from_item_id?: number | null;
+  session?: { results?: Record<string, unknown> };
+}
+
+export interface QueueStatusCounts {
+  queue_id: string;
+  item_id?: number | null;
+  batch_id?: string | null;
+  session_id?: string | null;
+  pending: number;
+  in_progress: number;
+  completed: number;
+  failed: number;
+  canceled: number;
+  total: number;
+}
+
+export interface QueueProcessorStatus {
+  is_started: boolean;
+  is_processing: boolean;
+}
+
+export interface QueueAndProcessorStatus {
+  queue: QueueStatusCounts;
+  processor: QueueProcessorStatus;
+}
+
+export interface QueueItemIdsResult {
+  item_ids: number[];
+  total_count: number;
+}
+
+// --- Reads -----------------------------------------------------------------
+
+export const getQueueStatus = (scope: QueueQueryScope = {}): Promise<QueueAndProcessorStatus> =>
+  apiFetchJson<QueueAndProcessorStatus>(
+    buildQueueUrl(`status${buildQueryString({ origin_prefix: scope.originPrefix })}`)
+  );
+
+export const getCurrentQueueItem = (scope: QueueQueryScope = {}): Promise<QueueServerItem | null> =>
+  apiFetchJson<QueueServerItem | null>(
+    buildQueueUrl(`current${buildQueryString({ origin_prefix: scope.originPrefix })}`)
+  );
+
+export const getNextQueueItem = (scope: QueueQueryScope = {}): Promise<QueueServerItem | null> =>
+  apiFetchJson<QueueServerItem | null>(buildQueueUrl(`next${buildQueryString({ origin_prefix: scope.originPrefix })}`));
+
+export const getQueueItem = (itemId: number): Promise<QueueServerItem> =>
+  apiFetchJson<QueueServerItem>(buildQueueUrl(`i/${itemId}`));
+
+export const getQueueItemIds = (
+  orderDir: 'asc' | 'desc' = 'desc',
+  scope: QueueQueryScope = {}
+): Promise<QueueItemIdsResult> =>
+  apiFetchJson<QueueItemIdsResult>(
+    buildQueueUrl(
+      `item_ids${buildQueryString({ order_dir: orderDir.toUpperCase(), origin_prefix: scope.originPrefix })}`
+    )
+  );
+
+/** Fetch full items for the given ids, preserving order. Mirrors legacy `items_by_ids`. */
+export const getQueueItemsByIds = (itemIds: number[]): Promise<QueueServerItem[]> => {
+  if (itemIds.length === 0) {
+    return Promise.resolve([]);
+  }
+
+  return apiFetchJson<QueueServerItem[]>(buildQueueUrl('items_by_ids'), {
+    body: JSON.stringify({ item_ids: itemIds }),
+    method: 'POST',
+  });
+};
+
+// --- Mutations -------------------------------------------------------------
+
+export const clearQueue = (): Promise<unknown> => apiFetchJson(buildQueueUrl('clear'), { method: 'PUT' });
+
+export const pruneQueue = (): Promise<unknown> => apiFetchJson(buildQueueUrl('prune'), { method: 'PUT' });
+
+export const deleteQueueItem = (itemId: number): Promise<unknown> =>
+  apiFetchJson(buildQueueUrl(`i/${itemId}`), { method: 'DELETE' });
+
+export const deleteQueueItems = async (itemIds: number[]): Promise<void> => {
+  await Promise.all(itemIds.map(deleteQueueItem));
+};
+
+export const cancelQueueItems = async (itemIds: number[]): Promise<void> => {
+  await Promise.all(itemIds.map(cancelQueueItem));
+};
+
+export const clearFailedQueueItems = async (scope: QueueQueryScope = {}): Promise<void> => {
+  const idsResult = await getQueueItemIds('desc', scope);
+  const items = await getQueueItemsByIds(idsResult.item_ids);
+  const failedItemIds = items.filter((item) => item.status === 'failed').map((item) => item.item_id);
+
+  await deleteQueueItems(failedItemIds);
+};
+
+export const clearScopedQueue = async (scope: QueueQueryScope = {}): Promise<void> => {
+  if (!scope.originPrefix) {
+    await clearQueue();
+    return;
+  }
+
+  const idsResult = await getQueueItemIds('desc', scope);
+  await deleteQueueItems(idsResult.item_ids);
+};
+
+export const cancelAllExceptCurrent = (): Promise<unknown> =>
+  apiFetchJson(buildQueueUrl('cancel_all_except_current'), { method: 'PUT' });
+
+export const cancelQueueItem = (itemId: number): Promise<unknown> =>
+  apiFetchJson(buildQueueUrl(`i/${itemId}/cancel`), { method: 'PUT' });
+
+export const cancelScopedQueueItems = async (
+  scope: QueueQueryScope = {},
+  currentItemId?: number | null
+): Promise<void> => {
+  const idsResult = await getQueueItemIds('desc', scope);
+  const items = await getQueueItemsByIds(idsResult.item_ids);
+  const cancellableItemIds = items
+    .filter((item) => item.item_id !== currentItemId && (item.status === 'pending' || item.status === 'in_progress'))
+    .map((item) => item.item_id);
+
+  await cancelQueueItems(cancellableItemIds);
+};
+
+export const cancelByBatchIds = (batchIds: string[]): Promise<unknown> =>
+  apiFetchJson(buildQueueUrl('cancel_by_batch_ids'), {
+    body: JSON.stringify({ batch_ids: batchIds }),
+    method: 'PUT',
+  });
+
+export const retryItemsById = (itemIds: number[]): Promise<unknown> =>
+  apiFetchJson(buildQueueUrl('retry_items_by_id'), {
+    body: JSON.stringify(itemIds),
+    method: 'PUT',
+  });
+
+export const pauseQueueProcessor = (): Promise<unknown> =>
+  apiFetchJson(buildQueueUrl('processor/pause'), { method: 'PUT' });
+
+export const resumeQueueProcessor = (): Promise<unknown> =>
+  apiFetchJson(buildQueueUrl('processor/resume'), { method: 'PUT' });
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/queueViewModel.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueViewModel.ts
new file mode 100644
index 00000000000..73589fec608
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/queueViewModel.ts
@@ -0,0 +1,94 @@
+import type { Project, QueueItem } from '@workbench/types';
+
+import { createStableSelector } from '@workbench/workbenchSelectors';
+
+export interface QueueRow {
+  item: QueueItem;
+  projectId: string;
+  projectName: string;
+}
+
+export interface QueueActionState {
+  cancellableCount: number;
+  currentItemId: string | null;
+  hasPendingQueueWork: boolean;
+  hasRunningItem: boolean;
+}
+
+export const areQueueRowsEqual = (left: readonly QueueRow[], right: readonly QueueRow[]): boolean =>
+  left.length === right.length &&
+  left.every((row, index) => {
+    const other = right[index];
+
+    return (
+      other !== undefined &&
+      row.item === other.item &&
+      row.projectId === other.projectId &&
+      row.projectName === other.projectName
+    );
+  });
+
+export const createQueueRowsSelector = () =>
+  createStableSelector(
+    (projects: readonly Project[]): QueueRow[] =>
+      projects.flatMap((project) =>
+        project.queue.items.map((item) => ({ item, projectId: project.id, projectName: project.name }))
+      ),
+    areQueueRowsEqual
+  );
+
+export const getPendingQueueCount = (items: readonly QueueItem[]): number =>
+  items.reduce((count, item) => (item.status === 'pending' || item.status === 'running' ? count + 1 : count), 0);
+
+export const hasPendingWorkflowQueueItem = (items: readonly QueueItem[]): boolean =>
+  items.some(
+    (item) => item.snapshot.sourceId === 'workflow' && (item.status === 'running' || item.status === 'pending')
+  );
+
+const isCancellableQueueItem = (item: QueueItem): boolean =>
+  item.cancellable && (item.status === 'pending' || item.status === 'running');
+
+const compareQueueSubmittedAt = (left: QueueItem, right: QueueItem): number => {
+  const leftTime = Date.parse(left.snapshot.submittedAt);
+  const rightTime = Date.parse(right.snapshot.submittedAt);
+
+  return (Number.isFinite(leftTime) ? leftTime : 0) - (Number.isFinite(rightTime) ? rightTime : 0);
+};
+
+const getCurrentQueueActionItem = (queueItems: readonly QueueItem[]): QueueItem | null => {
+  const runningItem = queueItems.filter(isCancellableQueueItem).find((item) => item.status === 'running');
+
+  if (runningItem) {
+    return runningItem;
+  }
+
+  return queueItems.filter(isCancellableQueueItem).sort(compareQueueSubmittedAt)[0] ?? null;
+};
+
+const getOpenBackendSlotCount = (item: QueueItem): number => {
+  if (!item.backendItemIds?.length) {
+    return item.status === 'pending' || item.status === 'running' ? 1 : 0;
+  }
+
+  const terminalBackendItemIds = new Set([
+    ...(item.completedBackendItemIds ?? []),
+    ...(item.cancelledBackendItemIds ?? []),
+  ]);
+
+  return item.backendItemIds.filter((backendItemId) => !terminalBackendItemIds.has(backendItemId)).length;
+};
+
+export const getQueueActionState = (queueItems: readonly QueueItem[]): QueueActionState => {
+  const currentItem = getCurrentQueueActionItem(queueItems);
+
+  return {
+    cancellableCount: queueItems.filter(isCancellableQueueItem).length,
+    currentItemId: currentItem?.id ?? null,
+    hasPendingQueueWork: queueItems.some((item) =>
+      item.id === currentItem?.id
+        ? item.status === 'running' && getOpenBackendSlotCount(item) > 1
+        : item.status === 'pending'
+    ),
+    hasRunningItem: queueItems.some((item) => isCancellableQueueItem(item) && item.status === 'running'),
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/statusMeta.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/statusMeta.ts
new file mode 100644
index 00000000000..811fe994dc8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/statusMeta.ts
@@ -0,0 +1,22 @@
+import type { BackendQueueItemStatus } from '@workbench/backend/events';
+
+/**
+ * Presentation metadata for each backend queue status: the human label, the
+ * Chakra `colorPalette` for badges, and the dot color used in list rows and the
+ * NOW & NEXT card. One table so status styling stays consistent everywhere.
+ */
+export interface QueueStatusMeta {
+  labelKey: string;
+  colorPalette: string;
+  dotColor: string;
+}
+
+const STATUS_META: Record<BackendQueueItemStatus, QueueStatusMeta> = {
+  canceled: { colorPalette: 'orange', dotColor: 'orange.solid', labelKey: 'common.status.canceled' },
+  completed: { colorPalette: 'green', dotColor: 'green.solid', labelKey: 'common.status.completed' },
+  failed: { colorPalette: 'red', dotColor: 'red.solid', labelKey: 'common.status.failed' },
+  in_progress: { colorPalette: 'accent', dotColor: 'accent.solid', labelKey: 'common.generating' },
+  pending: { colorPalette: 'gray', dotColor: 'fg.muted', labelKey: 'common.status.pending' },
+};
+
+export const getStatusMeta = (status: BackendQueueItemStatus): QueueStatusMeta => STATUS_META[status];
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/queue/useLocalGenerateValues.ts b/invokeai/frontend/webv2/src/workbench/widgets/queue/useLocalGenerateValues.ts
new file mode 100644
index 00000000000..0965a48ef93
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/queue/useLocalGenerateValues.ts
@@ -0,0 +1,32 @@
+import type { GenerateWidgetValues } from '@workbench/generation/types';
+
+import { parseQueueItemOrigin } from '@workbench/backend/events';
+import { useWorkbenchSelector } from '@workbench/WorkbenchContext';
+
+/**
+ * The full Generate settings snapshot for a server queue item, if this client
+ * submitted it. webv2 stamps the local submission id into each item's `origin`,
+ * so we decode it and look the snapshot up in local state. Present → "Use again"
+ * can recall the exact settings (model, steps, LoRAs, …); absent (item from
+ * another client, or a cleared snapshot) → only field_values are recoverable.
+ */
+export const useLocalGenerateValues = (origin?: string | null): GenerateWidgetValues | null =>
+  useWorkbenchSelector((snapshot) => {
+    const localId = parseQueueItemOrigin(origin);
+
+    if (!localId) {
+      return null;
+    }
+
+    for (const project of snapshot.state.projects) {
+      const localItem = project.queue.items.find((queueItem) => queueItem.id === localId);
+
+      if (localItem) {
+        const generate = (localItem.snapshot.widgetStates as Record<string, { values?: unknown }>).generate;
+
+        return (generate?.values as GenerateWidgetValues | undefined) ?? null;
+      }
+    }
+
+    return null;
+  });
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/server-status/ServerStatusWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/server-status/ServerStatusWidgetView.tsx
new file mode 100644
index 00000000000..ce87140596e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/server-status/ServerStatusWidgetView.tsx
@@ -0,0 +1,44 @@
+import type { WidgetViewProps } from '@workbench/types';
+
+import { Stack, Text } from '@chakra-ui/react';
+import { StatusWidgetChip } from '@workbench/widget-frame';
+import { useWorkbenchSelector } from '@workbench/WorkbenchContext';
+import { CircleXIcon, PlugZapIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+export const ServerStatusWidgetView = ({ presentation }: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const backendConnection = useWorkbenchSelector((snapshot) => snapshot.state.backendConnection);
+  const isConnected = backendConnection.status === 'connected';
+  const isDisconnected = backendConnection.status === 'disconnected';
+  const label = isConnected
+    ? t('widgets.serverStatus.connected')
+    : isDisconnected
+      ? t('widgets.serverStatus.disconnected')
+      : t('widgets.serverStatus.connecting');
+
+  if (presentation === 'tooltip') {
+    return (
+      <Stack gap="2">
+        <Text fontSize="xs" fontWeight="700">
+          {t('widgets.serverStatus.label')}
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          {backendConnection.error
+            ? t('widgets.serverStatus.labelWithError', { error: backendConnection.error, label })
+            : label}
+        </Text>
+      </Stack>
+    );
+  }
+
+  if (isDisconnected) {
+    return (
+      <StatusWidgetChip icon={CircleXIcon} tone="error">
+        {label}
+      </StatusWidgetChip>
+    );
+  }
+
+  return <StatusWidgetChip icon={PlugZapIcon}>{label}</StatusWidgetChip>;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/server-status/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/server-status/index.ts
new file mode 100644
index 00000000000..eefa02b2ddb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/server-status/index.ts
@@ -0,0 +1,17 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { PlugZapIcon } from 'lucide-react';
+
+import { ServerStatusWidgetView } from './ServerStatusWidgetView';
+
+export const serverStatusWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['bottom'],
+  bottomPanel: 'tooltip',
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  icon: PlugZapIcon,
+  id: 'server-status',
+  label: (t) => t('widgets.labels.serverStatus'),
+  version: 1,
+  view: ServerStatusWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/version-status/VersionStatusWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/version-status/VersionStatusWidgetView.tsx
new file mode 100644
index 00000000000..5717a7af10b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/version-status/VersionStatusWidgetView.tsx
@@ -0,0 +1,25 @@
+import type { WidgetViewProps } from '@workbench/types';
+
+import { Stack, Text } from '@chakra-ui/react';
+import { StatusWidgetChip } from '@workbench/widget-frame';
+import { InfoIcon } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+export const VersionStatusWidgetView = ({ presentation }: WidgetViewProps) => {
+  const { t } = useTranslation();
+
+  if (presentation === 'tooltip') {
+    return (
+      <Stack gap="2">
+        <Text fontSize="xs" fontWeight="700">
+          {t('widgets.versionStatus.label')}
+        </Text>
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('widgets.versionStatus.description')}
+        </Text>
+      </Stack>
+    );
+  }
+
+  return <StatusWidgetChip icon={InfoIcon}>{t('widgets.versionStatus.chipLabel')}</StatusWidgetChip>;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/version-status/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/version-status/index.ts
new file mode 100644
index 00000000000..3e4e95fb717
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/version-status/index.ts
@@ -0,0 +1,17 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { InfoIcon } from 'lucide-react';
+
+import { VersionStatusWidgetView } from './VersionStatusWidgetView';
+
+export const versionStatusWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['bottom'],
+  bottomPanel: 'tooltip',
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  icon: InfoIcon,
+  id: 'version-status',
+  label: (t) => t('widgets.labels.versionStatus'),
+  version: 1,
+  view: VersionStatusWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/WorkflowWidgetChrome.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/WorkflowWidgetChrome.tsx
new file mode 100644
index 00000000000..8522f0ec867
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/WorkflowWidgetChrome.tsx
@@ -0,0 +1,427 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type { WidgetLabelProps, WidgetViewProps } from '@workbench/types';
+import type { InvocationTemplate, XYPosition } from '@workbench/workflows/types';
+
+import { HStack, Icon, Input, Menu, Portal, Stack, Text } from '@chakra-ui/react';
+import { IconButton, ConfirmDialog, Tooltip } from '@workbench/components/ui';
+import { useNotify } from '@workbench/useNotify';
+import { useActiveProjectSelector, useWorkbenchDispatch, useWorkbenchStore } from '@workbench/WorkbenchContext';
+import { CONNECTOR_INPUT_HANDLE, CONNECTOR_OUTPUT_HANDLE } from '@workbench/workflows/connectors';
+import {
+  buildConnectorNode,
+  buildCurrentImageNode,
+  buildInvocationNode,
+  buildNotesNode,
+  createProjectGraph,
+  createWorkflowId,
+} from '@workbench/workflows/document';
+import { getCompatibleInputTemplate, getCompatibleOutputTemplate } from '@workbench/workflows/validation';
+import { parseWorkflowJson } from '@workbench/workflows/workflowJson';
+import { HistoryIcon, LibraryIcon, PlusIcon } from 'lucide-react';
+import { useEffect, useId, useRef, type ChangeEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { AddNodeDialog } from './editor/AddNodeDialog';
+import { getWorkflowFlowInstance } from './editor/flowInstanceStore';
+import { WorkflowLibraryDialog } from './library/WorkflowLibraryDialog';
+import { copyWorkflowJson, downloadWorkflowJson } from './workflowTransfer';
+import {
+  requestWorkflowImport,
+  setAddNodeOpen,
+  setNewWorkflowConfirmOpen,
+  setWorkflowLibraryOpen,
+  workflowUiStore,
+} from './workflowUiStore';
+
+/**
+ * The workflow widget's frame chrome. The label renders the editable
+ * `Workflow / [name]` title; quick actions (add node, library, history) are
+ * header icon buttons; everything else contributes to the shared widget
+ * actions menu via the manifest's `headerMenu`. Dialogs live here (always
+ * mounted) and are driven through `workflowUiStore`.
+ */
+
+export const WorkflowWidgetLabel = ({ region }: WidgetLabelProps) => {
+  const { t } = useTranslation();
+  const workflowName = useActiveProjectSelector((project) => project.projectGraph.name);
+  const dispatch = useWorkbenchDispatch();
+
+  if (region !== 'center') {
+    return (
+      <Text fontSize="xs" fontWeight="700">
+        {t('widgets.labels.workflow')}
+      </Text>
+    );
+  }
+
+  return (
+    <HStack flex="1" gap="1" minW="0">
+      <Text flexShrink={0} fontSize="xs" fontWeight="700">
+        {t('widgets.labels.workflow')}
+      </Text>
+      <Text color="fg.subtle" flexShrink={0} fontSize="xs">
+        /
+      </Text>
+      <Input
+        aria-label={t('widgets.workflow.name')}
+        fontSize="xs"
+        fontWeight="600"
+        h="6"
+        maxW="16rem"
+        placeholder={t('widgets.workflow.untitled')}
+        size="2xs"
+        value={workflowName}
+        variant="flushed"
+        onChange={(event: ChangeEvent<HTMLInputElement>) =>
+          dispatch({
+            action: { patch: { name: event.currentTarget.value }, type: 'setMetadata' },
+            type: 'applyProjectGraphAction',
+          })
+        }
+      />
+    </HStack>
+  );
+};
+
+/** Entries contributed to the shared widget actions menu. */
+export const WorkflowMenuItems = (_props: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const store = useWorkbenchStore();
+  const dispatch = useWorkbenchDispatch();
+  const notify = useNotify();
+
+  const openDetailsPanel = () => {
+    dispatch({ region: 'left', type: 'openRegionWidget', widgetId: 'workflow' });
+    dispatch({ type: 'patchWidgetValues', values: { editTab: 'details', panelMode: 'edit' }, widgetId: 'workflow' });
+  };
+
+  return (
+    <Menu.ItemGroup>
+      <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+        {t('widgets.labels.workflow')}
+      </Menu.ItemGroupLabel>
+      <Menu.Item value="snapshot" onClick={() => dispatch({ type: 'saveProjectGraphSnapshot' })}>
+        {t('widgets.workflow.saveGraphSnapshot')}
+      </Menu.Item>
+      <Menu.Item value="details" onClick={openDetailsPanel}>
+        {t('widgets.workflow.detailsWithEllipsis')}
+      </Menu.Item>
+      <Menu.Item value="import" onClick={requestWorkflowImport}>
+        {t('widgets.workflow.importJsonWithEllipsis')}
+      </Menu.Item>
+      <Menu.Item value="export" onClick={() => downloadWorkflowJson(store.getSnapshot().activeProject.projectGraph)}>
+        {t('widgets.workflow.exportJson')}
+      </Menu.Item>
+      <Menu.Item
+        value="copy"
+        onClick={() => {
+          copyWorkflowJson(store.getSnapshot().activeProject.projectGraph)
+            .then(() => notify.success(t('widgets.workflow.copyJsonSuccess')))
+            .catch(() => notify.error(t('widgets.workflow.copyJsonFailed')));
+        }}
+      >
+        {t('widgets.workflow.copyJson')}
+      </Menu.Item>
+      <Menu.Item color="fg.error" value="new" onClick={() => setNewWorkflowConfirmOpen(true)}>
+        {t('widgets.workflow.newWorkflowWithEllipsis')}
+      </Menu.Item>
+    </Menu.ItemGroup>
+  );
+};
+
+export const WorkflowHeaderActions = ({ region }: WidgetViewProps) => {
+  const { t } = useTranslation();
+  const graphHistory = useActiveProjectSelector((project) => project.graphHistory);
+  const dispatch = useWorkbenchDispatch();
+  const restorableHistory = graphHistory.filter((entry) => entry.document);
+  const historyTriggerId = useId();
+
+  return (
+    <HStack gap="0.5">
+      {region === 'center' ? (
+        <Tooltip content={t('widgets.workflow.addNode')}>
+          <IconButton
+            aria-label={t('widgets.workflow.addNode')}
+            color="fg.muted"
+            size="2xs"
+            variant="ghost"
+            onClick={() => setAddNodeOpen(true)}
+          >
+            <Icon as={PlusIcon} boxSize="3.5" />
+          </IconButton>
+        </Tooltip>
+      ) : null}
+      <Tooltip content={t('widgets.workflow.library')}>
+        <IconButton
+          aria-label={t('widgets.workflow.library')}
+          color="fg.muted"
+          size="2xs"
+          variant="ghost"
+          onClick={() => setWorkflowLibraryOpen(true)}
+        >
+          <Icon as={LibraryIcon} boxSize="3.5" />
+        </IconButton>
+      </Tooltip>
+      <Menu.Root ids={{ trigger: historyTriggerId }} positioning={{ placement: 'bottom-end' }}>
+        <Tooltip content={t('widgets.workflow.graphHistorySnapshots')} ids={{ trigger: historyTriggerId }}>
+          <Menu.Trigger asChild>
+            <IconButton
+              aria-label={t('widgets.workflow.graphHistorySnapshots')}
+              color="fg.muted"
+              disabled={restorableHistory.length === 0}
+              size="2xs"
+              variant="ghost"
+            >
+              <Icon as={HistoryIcon} boxSize="3.5" />
+            </IconButton>
+          </Menu.Trigger>
+        </Tooltip>
+        <Portal>
+          <Menu.Positioner>
+            <Menu.Content maxH="18rem" minW="16rem" overflowY="auto">
+              <Menu.ItemGroup>
+                <Menu.ItemGroupLabel color="fg.subtle" fontSize="2xs" textTransform="uppercase">
+                  {t('widgets.workflow.graphHistorySnapshots')}
+                </Menu.ItemGroupLabel>
+                {restorableHistory.map((entry) => (
+                  <Menu.Item
+                    key={entry.id}
+                    value={entry.id}
+                    onClick={() => dispatch({ snapshotId: entry.id, type: 'restoreProjectGraphSnapshot' })}
+                  >
+                    <Stack gap="0" minW="0">
+                      <Menu.ItemText fontSize="xs" truncate>
+                        {entry.label}
+                      </Menu.ItemText>
+                      <Text color="fg.subtle" fontSize="2xs">
+                        {new Date(entry.createdAt).toLocaleString()}
+                      </Text>
+                    </Stack>
+                  </Menu.Item>
+                ))}
+              </Menu.ItemGroup>
+            </Menu.Content>
+          </Menu.Positioner>
+        </Portal>
+      </Menu.Root>
+    </HStack>
+  );
+};
+
+export const WorkflowDialogHost = () => {
+  const dispatch = useWorkbenchDispatch();
+  const notify = useNotify();
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const addNodeConnection = workflowUiStore.useSelector((snapshot) => snapshot.addNodeConnection);
+  const addNodePosition = workflowUiStore.useSelector((snapshot) => snapshot.addNodePosition);
+  const importRequestCount = workflowUiStore.useSelector((snapshot) => snapshot.importRequestCount);
+  const isAddNodeOpen = workflowUiStore.useSelector((snapshot) => snapshot.isAddNodeOpen);
+  const isLibraryOpen = workflowUiStore.useSelector((snapshot) => snapshot.isLibraryOpen);
+  const isNewWorkflowConfirmOpen = workflowUiStore.useSelector((snapshot) => snapshot.isNewWorkflowConfirmOpen);
+  const lastImportRequestRef = useRef(importRequestCount);
+
+  useEffect(() => {
+    if (importRequestCount > lastImportRequestRef.current) {
+      fileInputRef.current?.click();
+    }
+
+    lastImportRequestRef.current = importRequestCount;
+  }, [importRequestCount]);
+
+  const getInsertPosition = (): XYPosition => {
+    if (addNodePosition) {
+      return addNodePosition;
+    }
+
+    const instance = getWorkflowFlowInstance();
+    const center = instance
+      ? instance.screenToFlowPosition({ x: window.innerWidth / 2, y: window.innerHeight / 2 })
+      : { x: 0, y: 0 };
+
+    // Slight scatter so repeated inserts do not stack perfectly.
+    return { x: center.x + (Math.random() - 0.5) * 80, y: center.y + (Math.random() - 0.5) * 80 };
+  };
+
+  const addNode = (template: InvocationTemplate) => {
+    const node = buildInvocationNode(template, getInsertPosition());
+
+    if (!addNodeConnection) {
+      dispatch({
+        action: { node, type: 'addNode' },
+        type: 'applyProjectGraphAction',
+      });
+      return;
+    }
+
+    if (addNodeConnection.kind === 'source') {
+      const targetInput = getCompatibleInputTemplate(template, addNodeConnection.sourceType);
+
+      if (!targetInput) {
+        dispatch({
+          action: { node, type: 'addNode' },
+          type: 'applyProjectGraphAction',
+        });
+        return;
+      }
+
+      dispatch({
+        action: {
+          edge: {
+            id: createWorkflowId('edge'),
+            source: addNodeConnection.sourceNodeId,
+            sourceHandle: addNodeConnection.sourceHandle,
+            target: node.id,
+            targetHandle: targetInput.name,
+            type: 'default',
+          },
+          node,
+          type: 'addNodeAndEdge',
+        },
+        type: 'applyProjectGraphAction',
+      });
+      return;
+    }
+
+    const sourceOutput = getCompatibleOutputTemplate(template, addNodeConnection.targetType);
+
+    if (!sourceOutput) {
+      dispatch({
+        action: { node, type: 'addNode' },
+        type: 'applyProjectGraphAction',
+      });
+      return;
+    }
+
+    dispatch({
+      action: {
+        edge: {
+          id: createWorkflowId('edge'),
+          source: node.id,
+          sourceHandle: sourceOutput.name,
+          target: addNodeConnection.targetNodeId,
+          targetHandle: addNodeConnection.targetHandle,
+          type: 'default',
+        },
+        node,
+        type: 'addNodeAndEdge',
+      },
+      type: 'applyProjectGraphAction',
+    });
+  };
+
+  const addNote = () => {
+    dispatch({
+      action: { node: buildNotesNode(getInsertPosition()), type: 'addNode' },
+      type: 'applyProjectGraphAction',
+    });
+  };
+
+  const addConnector = () => {
+    const node = buildConnectorNode(getInsertPosition());
+
+    if (!addNodeConnection) {
+      dispatch({
+        action: { node, type: 'addNode' },
+        type: 'applyProjectGraphAction',
+      });
+      return;
+    }
+
+    dispatch({
+      action: {
+        edge:
+          addNodeConnection.kind === 'source'
+            ? {
+                id: createWorkflowId('edge'),
+                source: addNodeConnection.sourceNodeId,
+                sourceHandle: addNodeConnection.sourceHandle,
+                target: node.id,
+                targetHandle: CONNECTOR_INPUT_HANDLE,
+                type: 'default',
+              }
+            : {
+                id: createWorkflowId('edge'),
+                source: node.id,
+                sourceHandle: CONNECTOR_OUTPUT_HANDLE,
+                target: addNodeConnection.targetNodeId,
+                targetHandle: addNodeConnection.targetHandle,
+                type: 'default',
+              },
+        node,
+        type: 'addNodeAndEdge',
+      },
+      type: 'applyProjectGraphAction',
+    });
+  };
+
+  const addCurrentImage = () => {
+    dispatch({
+      action: { node: buildCurrentImageNode(getInsertPosition()), type: 'addNode' },
+      type: 'applyProjectGraphAction',
+    });
+  };
+
+  const importFile = (file: File) => {
+    file
+      .text()
+      .then((text) => {
+        const { document, warnings } = parseWorkflowJson(JSON.parse(text));
+
+        dispatch({ document, label: `Imported "${file.name}"`, type: 'replaceProjectGraph' });
+
+        for (const warning of warnings) {
+          notify.info('Workflow import warning', warning);
+        }
+      })
+      .catch((error: unknown) => {
+        notify.error(
+          'Failed to import workflow',
+          error instanceof Error ? error.message : 'The file is not a valid workflow JSON.'
+        );
+      });
+  };
+
+  return (
+    <>
+      <input
+        ref={fileInputRef}
+        accept=".json,application/json"
+        hidden
+        type="file"
+        onChange={(event: ChangeEvent<HTMLInputElement>) => {
+          const file = event.currentTarget.files?.[0];
+
+          event.currentTarget.value = '';
+
+          if (file) {
+            importFile(file);
+          }
+        }}
+      />
+      <AddNodeDialog
+        connectionFilter={addNodeConnection}
+        isOpen={isAddNodeOpen}
+        onAddCurrentImage={addCurrentImage}
+        onAddConnector={addConnector}
+        onAddNode={addNode}
+        onAddNote={addNote}
+        onOpenChange={setAddNodeOpen}
+      />
+      <WorkflowLibraryDialog isOpen={isLibraryOpen} onOpenChange={setWorkflowLibraryOpen} />
+      <ConfirmDialog
+        body="Replace the project graph with an empty workflow? The current graph is saved to graph history first."
+        confirmLabel="New workflow"
+        isOpen={isNewWorkflowConfirmOpen}
+        title="New workflow"
+        onClose={() => setNewWorkflowConfirmOpen(false)}
+        onConfirm={() => {
+          dispatch({
+            document: createProjectGraph(createWorkflowId('workflow')),
+            label: 'New workflow',
+            type: 'replaceProjectGraph',
+          });
+        }}
+      />
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/WorkflowWidgetView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/WorkflowWidgetView.tsx
new file mode 100644
index 00000000000..fb79567d835
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/WorkflowWidgetView.tsx
@@ -0,0 +1,44 @@
+import type { WidgetViewProps } from '@workbench/types';
+
+import { Box, HStack, Icon, Text } from '@chakra-ui/react';
+import { hasPendingWorkflowQueueItem } from '@workbench/widgets/queue/queueViewModel';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { WorkflowIcon } from 'lucide-react';
+
+import { WorkflowEditorView } from './editor/WorkflowEditorView';
+import { WorkflowLinearPanel } from './linear/WorkflowLinearPanel';
+
+/**
+ * The workflow widget's surfaces, per its manifest: the center region is the
+ * node editor over the project graph; the left region is the Linear UI panel
+ * bound to the same document; the bottom region is a status-bar entry whose
+ * expanded panel is the same node editor — handy while another widget (e.g.
+ * the canvas and its staging area) holds the center.
+ */
+
+const WorkflowStatusBarItem = () => {
+  const workflowName = useActiveProjectSelector((project) => project.projectGraph.name);
+  const isRunning = useActiveProjectSelector((project) => hasPendingWorkflowQueueItem(project.queue.items));
+
+  return (
+    <HStack gap="1" maxW="14rem" minW="0" px="2">
+      <Icon as={WorkflowIcon} boxSize="3" color={isRunning ? 'brand.solid' : undefined} flexShrink={0} />
+      <Text fontSize="2xs" minW="0" truncate>
+        {workflowName || 'Untitled Workflow'}
+      </Text>
+      {isRunning ? <Box bg="brand.solid" boxSize="1.5" flexShrink={0} rounded="full" /> : null}
+    </HStack>
+  );
+};
+
+export const WorkflowWidgetView = ({ presentation, region, runtime }: WidgetViewProps) => {
+  if (region === 'bottom') {
+    return presentation === 'expanded' ? <WorkflowEditorView runtime={runtime} /> : <WorkflowStatusBarItem />;
+  }
+
+  if (region === 'left') {
+    return <WorkflowLinearPanel />;
+  }
+
+  return <WorkflowEditorView runtime={runtime} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/AddNodeDialog.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/AddNodeDialog.tsx
new file mode 100644
index 00000000000..64c10999f0c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/AddNodeDialog.tsx
@@ -0,0 +1,656 @@
+import type { AddNodeConnectionFilter } from '@workbench/widgets/workflow/workflowUiStore';
+import type { InvocationTemplate } from '@workbench/workflows/types';
+
+import { Badge, Box, Dialog, HStack, Icon, Input, Portal, ScrollArea, Stack, Text } from '@chakra-ui/react';
+import { IconButton, Tooltip } from '@workbench/components/ui';
+import { registerHotkeyModalLayer } from '@workbench/hotkeys';
+import { useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import { getCompatibleInputTemplate, getCompatibleOutputTemplate } from '@workbench/workflows/validation';
+import { ChevronDownIcon, ChevronsDownUpIcon, ChevronsUpDownIcon, HammerIcon } from 'lucide-react';
+import {
+  startTransition,
+  useCallback,
+  useEffect,
+  useEffectEvent,
+  useMemo,
+  useState,
+  type ChangeEvent,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+import { useVirtualizer } from 'react-hook-tanstack-virtual';
+
+/**
+ * Command-palette-style node picker: a centered search dialog whose results
+ * are grouped into collapsible categories (with counts), mirroring the legacy
+ * editor's add-node menu. Beta nodes carry the hammer icon. The two UI-only
+ * nodes (Notes, Current Image) lead as a "Utility" group. No result cap —
+ * searching auto-expands every group; idle shows all categories collapsed.
+ */
+
+const UTILITY_CATEGORY = 'Utility';
+const CATEGORY_ROW_HEIGHT_PX = 28;
+const NODE_ROW_HEIGHT_PX = 44;
+const RESULT_LIST_ID = 'add-node-dialog-results';
+const ROW_HOVER_PROPS = { bg: 'bg.emphasized' };
+const VIRTUALIZER_INITIAL_RECT = { height: 384, width: 0 };
+
+const toCategoryLabel = (value: string): string =>
+  value
+    .replace(/[_-]+/g, ' ')
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+    .trim();
+
+const matchesSearch = (template: InvocationTemplate, terms: string[]): boolean => {
+  const haystack = `${template.title} ${template.type} ${template.tags.join(' ')} ${template.category}`.toLowerCase();
+
+  return terms.every((term) => haystack.includes(term));
+};
+
+const isCompatibleConnectionTemplate = (
+  template: InvocationTemplate,
+  connectionFilter: AddNodeConnectionFilter | null
+): boolean => {
+  if (!connectionFilter) {
+    return true;
+  }
+
+  if (connectionFilter.kind === 'source') {
+    return getCompatibleInputTemplate(template, connectionFilter.sourceType) !== null;
+  }
+
+  return getCompatibleOutputTemplate(template, connectionFilter.targetType) !== null;
+};
+
+const getConnectionFilterName = (connectionFilter: AddNodeConnectionFilter): string => {
+  if (connectionFilter.kind === 'source') {
+    return connectionFilter.sourceType?.name ?? 'connector';
+  }
+
+  return connectionFilter.targetType?.name ?? 'connector';
+};
+
+interface NodeRow {
+  description: string;
+  isBeta: boolean;
+  key: string;
+  nodePack: string;
+  onAdd: () => void;
+  title: string;
+}
+
+interface CategoryGroup {
+  label: string;
+  rows: NodeRow[];
+}
+
+type ResultRow =
+  | { group: CategoryGroup; id: string; isExpanded: boolean; kind: 'category' }
+  | { groupLabel: string; id: string; kind: 'node'; row: NodeRow };
+
+const getResultRowId = (index: number): string => `${RESULT_LIST_ID}-${index}`;
+
+const NodeResultRow = ({
+  id,
+  isActive,
+  onActive,
+  row,
+}: {
+  id: string;
+  isActive: boolean;
+  onActive: () => void;
+  row: NodeRow;
+}) => (
+  <Box
+    id={id}
+    as="button"
+    aria-level={2}
+    aria-selected={isActive}
+    bg={isActive ? 'bg.emphasized' : undefined}
+    role="treeitem"
+    tabIndex={-1}
+    _hover={ROW_HOVER_PROPS}
+    ps="5"
+    pe="1.5"
+    py="1.5"
+    rounded="md"
+    textAlign="start"
+    w="full"
+    onClick={row.onAdd}
+    onMouseEnter={onActive}
+    cursor="pointer"
+  >
+    <HStack gap="2" justify="space-between" alignItems="start">
+      <Stack gap="0" minW="0">
+        <HStack gap="1.5" minW="0">
+          {row.isBeta ? (
+            <Tooltip content="Beta node — may change in the future">
+              <Icon as={HammerIcon} boxSize="3" color="fg.subtle" flexShrink={0} />
+            </Tooltip>
+          ) : null}
+          <Text fontSize="xs" fontWeight="600" truncate>
+            {row.title}
+          </Text>
+        </HStack>
+        {row.description ? (
+          <Text color="fg.subtle" fontSize="2xs" lineClamp={2} lineHeight="1.4">
+            {row.description}
+          </Text>
+        ) : null}
+      </Stack>
+      <Badge size="xs" variant="outline" fontFamily="mono">
+        {row.nodePack}
+      </Badge>
+    </HStack>
+  </Box>
+);
+
+const CategoryHeaderRow = ({
+  group,
+  id,
+  isActive,
+  isExpanded,
+  onActive,
+  onToggle,
+}: {
+  group: CategoryGroup;
+  id: string;
+  isActive: boolean;
+  isExpanded: boolean;
+  onActive: () => void;
+  onToggle: (label: string) => void;
+}) => {
+  const toggle = useCallback(() => onToggle(group.label), [group.label, onToggle]);
+
+  return (
+    <Box
+      id={id}
+      as="button"
+      aria-expanded={isExpanded}
+      aria-level={1}
+      aria-selected={isActive}
+      bg={isActive ? 'bg.emphasized' : undefined}
+      role="treeitem"
+      tabIndex={-1}
+      _hover={ROW_HOVER_PROPS}
+      cursor="pointer"
+      ps="1"
+      pe="2"
+      py="1"
+      textAlign="start"
+      w="full"
+      onClick={toggle}
+      onMouseEnter={onActive}
+      rounded="md"
+    >
+      <HStack gap="1.5">
+        <Icon
+          as={ChevronDownIcon}
+          boxSize="3"
+          color="fg.subtle"
+          flexShrink={0}
+          transform={isExpanded ? 'rotate(0deg)' : 'rotate(-90deg)'}
+          transition="transform var(--wb-motion-duration-fast) ease-out"
+        />
+        <Text flex="1" fontSize="xs" fontWeight="700">
+          {group.label}
+        </Text>
+        <Badge size="sm" variant="surface" fontFamily="mono">
+          {group.rows.length}
+        </Badge>
+      </HStack>
+    </Box>
+  );
+};
+
+export const AddNodeDialog = ({
+  connectionFilter,
+  isOpen,
+  onAddCurrentImage,
+  onAddConnector,
+  onAddNode,
+  onAddNote,
+  onOpenChange,
+}: {
+  connectionFilter: AddNodeConnectionFilter | null;
+  isOpen: boolean;
+  onAddCurrentImage: () => void;
+  onAddConnector: () => void;
+  onAddNode: (template: InvocationTemplate) => void;
+  onAddNote: () => void;
+  onOpenChange: (isOpen: boolean) => void;
+}) => {
+  const onDialogOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onOpenChange(false);
+      }
+    },
+    [onOpenChange]
+  );
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    return registerHotkeyModalLayer('workflow-add-node');
+  }, [isOpen]);
+
+  return (
+    <Dialog.Root
+      lazyMount
+      open={isOpen}
+      placement="center"
+      scrollBehavior="inside"
+      size="md"
+      unmountOnExit
+      onOpenChange={onDialogOpenChange}
+    >
+      <AddNodeDialogContent
+        connectionFilter={connectionFilter}
+        onAddCurrentImage={onAddCurrentImage}
+        onAddConnector={onAddConnector}
+        onAddNode={onAddNode}
+        onAddNote={onAddNote}
+        onOpenChange={onOpenChange}
+      />
+    </Dialog.Root>
+  );
+};
+
+const AddNodeDialogContent = ({
+  connectionFilter,
+  onAddCurrentImage,
+  onAddConnector,
+  onAddNode,
+  onAddNote,
+  onOpenChange,
+}: {
+  connectionFilter: AddNodeConnectionFilter | null;
+  onAddCurrentImage: () => void;
+  onAddConnector: () => void;
+  onAddNode: (template: InvocationTemplate) => void;
+  onAddNote: () => void;
+  onOpenChange: (isOpen: boolean) => void;
+}) => {
+  const error = useInvocationTemplatesSelector((snapshot) => snapshot.error);
+  const status = useInvocationTemplatesSelector((snapshot) => snapshot.status);
+  const templates = useInvocationTemplatesSelector((snapshot) => snapshot.templates);
+  const [searchTerm, setSearchTerm] = useState('');
+  const [expandedCategories, setExpandedCategories] = useState<Set<string>>(() => new Set());
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const [scrollElement, setScrollElement] = useState<HTMLDivElement | null>(null);
+  // While searching, every matching group is force-expanded regardless of the
+  // manual expand/collapse state, so results are never hidden behind a header.
+  const isSearching = searchTerm.trim().length > 0;
+
+  const close = useCallback(
+    (added: boolean) => {
+      onOpenChange(false);
+
+      if (added) {
+        setSearchTerm('');
+      }
+    },
+    [onOpenChange]
+  );
+
+  const groups = useMemo<CategoryGroup[]>(() => {
+    const terms = searchTerm.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const utilityRows: NodeRow[] = [
+      {
+        description: 'Route a connection through a compact pass-through handle.',
+        isBeta: false,
+        key: 'utility:connector',
+        nodePack: 'invokeai',
+        onAdd: () => {
+          onAddConnector();
+          close(true);
+        },
+        title: 'Connector',
+      },
+      ...(connectionFilter
+        ? []
+        : [
+            {
+              description: 'Annotate the workflow with a free-text note.',
+              isBeta: false,
+              key: 'utility:notes',
+              nodePack: 'invokeai',
+              onAdd: () => {
+                onAddNote();
+                close(true);
+              },
+              title: 'Notes',
+            },
+            {
+              description: 'Show the latest generated image (and live progress) inside the graph.',
+              isBeta: false,
+              key: 'utility:current_image',
+              nodePack: 'invokeai',
+              onAdd: () => {
+                onAddCurrentImage();
+                close(true);
+              },
+              title: 'Current Image',
+            },
+          ]),
+    ].filter((row) => terms.every((term) => row.title.toLowerCase().includes(term)));
+
+    const byCategory = new Map<string, NodeRow[]>();
+
+    for (const template of Object.values(templates)) {
+      if (
+        template.classification === 'internal' ||
+        (terms.length > 0 && !matchesSearch(template, terms)) ||
+        !isCompatibleConnectionTemplate(template, connectionFilter)
+      ) {
+        continue;
+      }
+
+      const label = toCategoryLabel(template.category || 'other');
+      const row: NodeRow = {
+        description: template.description,
+        isBeta: template.classification === 'beta',
+        key: `template:${template.type}`,
+        nodePack: template.nodePack,
+        onAdd: () => {
+          onAddNode(template);
+          close(true);
+        },
+        title: template.title,
+      };
+
+      byCategory.set(label, [...(byCategory.get(label) ?? []), row]);
+    }
+
+    const categoryGroups = [...byCategory.entries()]
+      .map(([label, rows]) => ({
+        label,
+        rows: rows.sort((a, b) => a.title.localeCompare(b.title, undefined, { sensitivity: 'base' })),
+      }))
+      .sort((a, b) => a.label.localeCompare(b.label));
+
+    return utilityRows.length > 0
+      ? [{ label: UTILITY_CATEGORY, rows: utilityRows }, ...categoryGroups]
+      : categoryGroups;
+  }, [close, connectionFilter, onAddConnector, onAddCurrentImage, onAddNode, onAddNote, searchTerm, templates]);
+
+  const totalCount = groups.reduce((sum, group) => sum + group.rows.length, 0);
+  const isAllExpanded = groups.length > 0 && groups.every((group) => expandedCategories.has(group.label));
+
+  const resultRows = useMemo<ResultRow[]>(() => {
+    const rows: ResultRow[] = [];
+
+    for (const group of groups) {
+      const isExpanded = isSearching || expandedCategories.has(group.label);
+      rows.push({ group, id: `category:${group.label}`, isExpanded, kind: 'category' });
+
+      if (isExpanded) {
+        for (const row of group.rows) {
+          rows.push({ groupLabel: group.label, id: row.key, kind: 'node', row });
+        }
+      }
+    }
+
+    return rows;
+  }, [expandedCategories, groups, isSearching]);
+  const effectiveActiveIndex =
+    resultRows.length === 0 ? null : activeIndex === null ? 0 : Math.min(activeIndex, resultRows.length - 1);
+  const estimateVirtualRowSize = useCallback(
+    (index: number) => (resultRows[index]?.kind === 'category' ? CATEGORY_ROW_HEIGHT_PX : NODE_ROW_HEIGHT_PX),
+    [resultRows]
+  );
+  const getVirtualItemKey = useCallback((index: number) => resultRows[index]?.id ?? index, [resultRows]);
+  const getVirtualScrollElement = useCallback(() => scrollElement, [scrollElement]);
+
+  const virtualizer = useVirtualizer({
+    count: resultRows.length,
+    estimateSize: estimateVirtualRowSize,
+    getItemKey: getVirtualItemKey,
+    getScrollElement: getVirtualScrollElement,
+    initialRect: VIRTUALIZER_INITIAL_RECT,
+    overscan: 8,
+  });
+  const measureVirtualizer = useEffectEvent(() => {
+    virtualizer.measure();
+  });
+
+  const toggleCategory = useCallback((label: string) => {
+    setExpandedCategories((prev) => {
+      const next = new Set(prev);
+
+      if (next.has(label)) {
+        next.delete(label);
+      } else {
+        next.add(label);
+      }
+
+      return next;
+    });
+  }, []);
+
+  const toggleAllCategories = useCallback(() => {
+    startTransition(() => {
+      setExpandedCategories((prev) => {
+        const shouldCollapse = groups.length > 0 && groups.every((group) => prev.has(group.label));
+
+        return shouldCollapse ? new Set() : new Set(groups.map((group) => group.label));
+      });
+    });
+  }, [groups]);
+
+  useEffect(() => {
+    measureVirtualizer();
+  }, [resultRows.length]);
+
+  useEffect(() => {
+    if (effectiveActiveIndex !== null) {
+      virtualizer.scrollToIndex(effectiveActiveIndex, { align: 'auto' });
+    }
+  }, [effectiveActiveIndex, virtualizer]);
+
+  const moveActiveIndex = useCallback(
+    (direction: 1 | -1) => {
+      setActiveIndex((prev) => {
+        if (resultRows.length === 0) {
+          return null;
+        }
+
+        if (prev === null) {
+          return direction > 0 ? 0 : resultRows.length - 1;
+        }
+
+        return (prev + direction + resultRows.length) % resultRows.length;
+      });
+    },
+    [resultRows.length]
+  );
+
+  const activateResultRow = useCallback(
+    (row: ResultRow | undefined) => {
+      if (!row) {
+        return;
+      }
+
+      if (row.kind === 'category') {
+        toggleCategory(row.group.label);
+        return;
+      }
+
+      row.row.onAdd();
+    },
+    [toggleCategory]
+  );
+
+  const onSearchKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        moveActiveIndex(1);
+        return;
+      }
+
+      if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        moveActiveIndex(-1);
+        return;
+      }
+
+      if (event.key === 'Enter') {
+        event.preventDefault();
+        activateResultRow(effectiveActiveIndex === null ? undefined : resultRows[effectiveActiveIndex]);
+      }
+    },
+    [activateResultRow, effectiveActiveIndex, moveActiveIndex, resultRows]
+  );
+  const onSearchChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => setSearchTerm(event.currentTarget.value),
+    []
+  );
+
+  let body: ReactNode;
+
+  if (status !== 'loaded') {
+    body = (
+      <Text color={status === 'error' ? 'fg.error' : 'fg.subtle'} fontSize="xs" px="1" py="4">
+        {status === 'error' ? (error ?? 'Failed to load node definitions.') : 'Loading node definitions…'}
+      </Text>
+    );
+  } else if (totalCount === 0) {
+    body = (
+      <Text color="fg.subtle" fontSize="xs" px="1" py="4" textAlign="center">
+        {connectionFilter
+          ? `No compatible ${getConnectionFilterName(connectionFilter)} nodes.`
+          : 'No nodes match your search.'}
+      </Text>
+    );
+  } else {
+    body = (
+      <Box h={`${virtualizer.totalSize}px`} position="relative" w="full">
+        {virtualizer.virtualItems.map((virtualRow) => (
+          <VirtualResultRow
+            key={virtualRow.key}
+            activeIndex={effectiveActiveIndex}
+            measureElement={virtualizer.measureElement}
+            resultRows={resultRows}
+            virtualIndex={virtualRow.index}
+            virtualStart={virtualRow.start}
+            onActiveIndexChange={setActiveIndex}
+            onToggleCategory={toggleCategory}
+          />
+        ))}
+      </Box>
+    );
+  }
+
+  return (
+    <Portal>
+      <Dialog.Backdrop />
+      <Dialog.Positioner>
+        <Dialog.Content h="min(512px, calc(100dvh - 4rem))">
+          <Dialog.Body display="flex" minH="0" p="3">
+            <Stack gap="2" flex="1" minH="0">
+              <HStack gap="2" flexShrink={0}>
+                <Input
+                  autoFocus
+                  aria-activedescendant={
+                    effectiveActiveIndex === null ? undefined : getResultRowId(effectiveActiveIndex)
+                  }
+                  aria-controls={RESULT_LIST_ID}
+                  aria-expanded="true"
+                  aria-label="Search for nodes"
+                  flex="1"
+                  placeholder={
+                    connectionFilter
+                      ? `Search compatible ${getConnectionFilterName(connectionFilter)} nodes…`
+                      : 'Search for nodes…'
+                  }
+                  role="combobox"
+                  size="sm"
+                  value={searchTerm}
+                  onChange={onSearchChange}
+                  onKeyDown={onSearchKeyDown}
+                />
+                <Tooltip content={isAllExpanded ? 'Collapse All' : 'Expand All'}>
+                  <IconButton
+                    aria-label={isAllExpanded ? 'Collapse all categories' : 'Expand all categories'}
+                    size="sm"
+                    variant="ghost"
+                    onClick={toggleAllCategories}
+                  >
+                    <Icon as={isAllExpanded ? ChevronsUpDownIcon : ChevronsDownUpIcon} />
+                  </IconButton>
+                </Tooltip>
+              </HStack>
+              <ScrollArea.Root flex="1" minH="0" size="xs" variant="hover" w="full">
+                <ScrollArea.Viewport ref={setScrollElement} aria-label="Node search results" h="full" w="full">
+                  <ScrollArea.Content id={RESULT_LIST_ID} role="tree" w="full">
+                    {body}
+                  </ScrollArea.Content>
+                </ScrollArea.Viewport>
+                <ScrollArea.Scrollbar>
+                  <ScrollArea.Thumb />
+                </ScrollArea.Scrollbar>
+              </ScrollArea.Root>
+            </Stack>
+          </Dialog.Body>
+        </Dialog.Content>
+      </Dialog.Positioner>
+    </Portal>
+  );
+};
+
+const VirtualResultRow = ({
+  activeIndex,
+  measureElement,
+  resultRows,
+  virtualIndex,
+  virtualStart,
+  onActiveIndexChange,
+  onToggleCategory,
+}: {
+  activeIndex: number | null;
+  measureElement: (node: Element | null) => void;
+  resultRows: ResultRow[];
+  virtualIndex: number;
+  virtualStart: number;
+  onActiveIndexChange: (index: number) => void;
+  onToggleCategory: (label: string) => void;
+}) => {
+  const row = resultRows[virtualIndex];
+  const onActive = useCallback(() => onActiveIndexChange(virtualIndex), [onActiveIndexChange, virtualIndex]);
+
+  if (!row) {
+    return null;
+  }
+
+  const isActive = virtualIndex === activeIndex;
+  const id = getResultRowId(virtualIndex);
+
+  return (
+    <Box
+      ref={measureElement}
+      data-index={virtualIndex}
+      left="0"
+      position="absolute"
+      top="0"
+      transform={`translateY(${virtualStart}px)`}
+      w="full"
+    >
+      {row.kind === 'category' ? (
+        <CategoryHeaderRow
+          id={id}
+          group={row.group}
+          isActive={isActive}
+          isExpanded={row.isExpanded}
+          onActive={onActive}
+          onToggle={onToggleCategory}
+        />
+      ) : (
+        <NodeResultRow id={id} isActive={isActive} onActive={onActive} row={row.row} />
+      )}
+    </Box>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/ConnectorFlowNode.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/ConnectorFlowNode.tsx
new file mode 100644
index 00000000000..4b2285de662
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/ConnectorFlowNode.tsx
@@ -0,0 +1,78 @@
+import type { FieldType } from '@workbench/workflows/types';
+
+import { Box, Flex } from '@chakra-ui/react';
+import { Tooltip } from '@workbench/components/ui';
+import { CONNECTOR_INPUT_HANDLE, CONNECTOR_OUTPUT_HANDLE } from '@workbench/workflows/connectors';
+import { getFieldTypeColor, getFieldTypeLabel, isModelFieldType } from '@workbench/workflows/fields';
+import { Handle, Position, type NodeProps } from '@xyflow/react';
+import { memo, useMemo } from 'react';
+
+import type { ConnectorFlowNode as ConnectorFlowNodeType } from './flowAdapters';
+
+import { getHandleTypeTooltip } from './handleTooltip';
+import { getWorkflowNodeChromeProps } from './nodeChrome';
+
+const HANDLE_SIZE = 12;
+type HandleSide = 'left' | 'right';
+
+const genericHandleStyle: React.CSSProperties = {
+  background: 'var(--wb-flow-grid)',
+  border: '1px solid var(--chakra-colors-bg)',
+  height: HANDLE_SIZE,
+  width: HANDLE_SIZE,
+};
+
+const typedHandleStyle = (type: FieldType, side: HandleSide): React.CSSProperties => {
+  const color = getFieldTypeColor(type);
+  const isFilled = type.cardinality === 'SINGLE';
+  const isAngular = isModelFieldType(type) || type.batch;
+  const centeredDiamondTransform = `translate(${side === 'left' ? '-' : ''}50%, -50%) rotate(45deg)`;
+
+  return {
+    background: isFilled ? color : 'var(--xy-background-color)',
+    border: isFilled ? 'none' : `3px solid ${color}`,
+    borderRadius: isAngular ? 3 : '50%',
+    boxShadow: '0 0 0 1px var(--xy-background-color)',
+    height: HANDLE_SIZE,
+    transform: type.batch ? centeredDiamondTransform : undefined,
+    width: HANDLE_SIZE,
+  };
+};
+
+const getConnectorHandleStyle = (type: FieldType | null, side: HandleSide): React.CSSProperties =>
+  type ? typedHandleStyle(type, side) : genericHandleStyle;
+
+const getConnectorTitle = (inputType: FieldType | null, outputType: FieldType | null): string => {
+  const inputLabel = inputType ? getFieldTypeLabel(inputType) : 'Any input';
+  const outputLabel = outputType ? getFieldTypeLabel(outputType) : 'Any output';
+
+  return `Connector: ${inputLabel} -> ${outputLabel}`;
+};
+
+const ConnectorFlowNodeComponent = ({ data, selected }: NodeProps<ConnectorFlowNodeType>) => {
+  const node = data.documentNode;
+  const inputHandleStyle = useMemo(
+    () => ({ ...getConnectorHandleStyle(data.inputFieldType, 'left'), left: -HANDLE_SIZE / 2 }),
+    [data.inputFieldType]
+  );
+  const outputHandleStyle = useMemo(
+    () => ({ ...getConnectorHandleStyle(data.outputFieldType, 'right'), right: -HANDLE_SIZE / 2 }),
+    [data.outputFieldType]
+  );
+
+  return (
+    <Flex align="center" data-connector-node-id={node.id} justify="center" position="relative">
+      <Tooltip content={getHandleTypeTooltip(data.inputFieldType, 'Any input')} showArrow>
+        <Handle id={CONNECTOR_INPUT_HANDLE} position={Position.Left} style={inputHandleStyle} type="target" />
+      </Tooltip>
+      <Tooltip content={getConnectorTitle(data.inputFieldType, data.outputFieldType)} showArrow>
+        <Box bg="bg" h="1rem" rounded="full" w="2.5rem" {...getWorkflowNodeChromeProps({ selected })} />
+      </Tooltip>
+      <Tooltip content={getHandleTypeTooltip(data.outputFieldType, 'Any output')} showArrow>
+        <Handle id={CONNECTOR_OUTPUT_HANDLE} position={Position.Right} style={outputHandleStyle} type="source" />
+      </Tooltip>
+    </Flex>
+  );
+};
+
+export const ConnectorFlowNode = memo(ConnectorFlowNodeComponent);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/CurrentImageFlowNode.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/CurrentImageFlowNode.tsx
new file mode 100644
index 00000000000..f3bf4299012
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/CurrentImageFlowNode.tsx
@@ -0,0 +1,65 @@
+import type { GeneratedImageContract } from '@workbench/types';
+import type { NodeProps } from '@xyflow/react';
+
+import { Box, Flex, Text } from '@chakra-ui/react';
+import { useProgressImage } from '@workbench/backend/progressImageStore';
+import { StreamingImageFrame } from '@workbench/images/StreamingImageFrame';
+import { imageUrlToStreamingSource, progressImageToStreamingSource } from '@workbench/images/streamingImageSource';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { memo } from 'react';
+
+import type { CurrentImageFlowNode as CurrentImageFlowNodeType } from './flowAdapters';
+
+import { getWorkflowNodeChromeProps } from './nodeChrome';
+
+/**
+ * The legacy `current_image` UI node: a live monitor inside the graph. Shows
+ * the in-flight denoising preview while a run executes, and the most recently
+ * generated image otherwise.
+ */
+
+const getLatestImage = (values: Record<string, unknown>): GeneratedImageContract | null => {
+  const recentImages = Array.isArray(values.recentImages) ? (values.recentImages as GeneratedImageContract[]) : [];
+
+  return recentImages[0] ?? null;
+};
+
+const CurrentImageFlowNodeComponent = ({ data, selected }: NodeProps<CurrentImageFlowNodeType>) => {
+  const galleryValues = useActiveProjectSelector((project) => getProjectWidgetValues(project, 'gallery'));
+  const progressImage = useProgressImage();
+  const node = data.documentNode;
+  const latestImage = getLatestImage(galleryValues);
+
+  return (
+    <Box bg="bg" fontSize="xs" overflow="hidden" rounded="lg" w="20rem" {...getWorkflowNodeChromeProps({ selected })}>
+      <Flex align="center" bg="bg.subtle" borderBottomWidth="1px" borderColor="border.subtle" px="3" py="1.5">
+        <Text fontWeight="700">{node.data.label || 'Current Image'}</Text>
+        {progressImage ? (
+          <Text color="brand.solid" fontSize="2xs" ms="auto">
+            generating…
+          </Text>
+        ) : null}
+      </Flex>
+      <StreamingImageFrame
+        fallbackImage={imageUrlToStreamingSource({
+          alt: latestImage?.imageName ?? 'Current image',
+          height: latestImage?.height,
+          kind: 'fallback',
+          src: latestImage?.imageUrl,
+          width: latestImage?.width,
+        })}
+        fit="contain"
+        h="18rem"
+        liveImage={progressImageToStreamingSource(progressImage)}
+        w="full"
+      >
+        <Flex align="center" color="fg.subtle" fontSize="2xs" h="full" justify="center" px="4" textAlign="center">
+          No image yet — the latest generation will appear here.
+        </Flex>
+      </StreamingImageFrame>
+    </Box>
+  );
+};
+
+export const CurrentImageFlowNode = memo(CurrentImageFlowNodeComponent);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/EditorToolbar.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/EditorToolbar.tsx
new file mode 100644
index 00000000000..cc65395d4e3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/EditorToolbar.tsx
@@ -0,0 +1,144 @@
+import { Box, Icon, Popover, Portal, Slider, Stack, Text } from '@chakra-ui/react';
+import { IconButton, Toolbar, ToolbarButton, ToolbarSeparator, Tooltip } from '@workbench/components/ui';
+import { useWorkbenchReduceMotion } from '@workbench/settings/store';
+import { useReactFlow } from '@xyflow/react';
+import {
+  BlendIcon,
+  BoxSelectIcon,
+  EraserIcon,
+  HandIcon,
+  LassoIcon,
+  MaximizeIcon,
+  ZoomInIcon,
+  ZoomOutIcon,
+} from 'lucide-react';
+import { useCallback, useId, useMemo } from 'react';
+
+/**
+ * The editor's single tool strip, docked to the left edge: interaction tools
+ * on top (legacy-toolbar style), viewport actions and the node-opacity slider
+ * below.
+ * - pan: dragging the pane moves the viewport (Shift-drag still box-selects)
+ * - box-select: dragging the pane draws a selection rectangle (middle-mouse pans)
+ * - lasso: dragging the pane draws a freeform selection
+ * - eraser: clicking nodes or edges deletes them
+ */
+export type EditorTool = 'pan' | 'box-select' | 'lasso' | 'eraser';
+
+const TOOLS: { icon: typeof HandIcon; id: EditorTool; label: string }[] = [
+  { icon: HandIcon, id: 'pan', label: 'Pan (drag to move the viewport)' },
+  { icon: BoxSelectIcon, id: 'box-select', label: 'Box select (drag to select nodes)' },
+  { icon: LassoIcon, id: 'lasso', label: 'Lasso select (draw around nodes)' },
+  { icon: EraserIcon, id: 'eraser', label: 'Eraser (click nodes or edges to delete)' },
+];
+
+const POPOVER_POSITIONING = { placement: 'right' } as const;
+const TOOLTIP_POSITIONING = { placement: 'right-start' } as const;
+
+export const EditorToolbar = ({
+  nodeOpacity,
+  tool,
+  onNodeOpacityChange,
+  onToolChange,
+}: {
+  nodeOpacity: number;
+  tool: EditorTool;
+  onNodeOpacityChange: (opacity: number) => void;
+  onToolChange: (tool: EditorTool) => void;
+}) => {
+  const { fitView, zoomIn, zoomOut } = useReactFlow();
+  const reduceMotion = useWorkbenchReduceMotion();
+  const opacityTriggerId = useId();
+  const fitViewDuration = reduceMotion ? 0 : 300;
+  const opacityIds = useMemo(() => ({ trigger: opacityTriggerId }), [opacityTriggerId]);
+  const opacityValue = useMemo(() => [Math.round(nodeOpacity * 100)], [nodeOpacity]);
+  const onZoomInClick = useCallback(() => void zoomIn(), [zoomIn]);
+  const onZoomOutClick = useCallback(() => void zoomOut(), [zoomOut]);
+  const onFitViewClick = useCallback(() => void fitView({ duration: fitViewDuration }), [fitView, fitViewDuration]);
+  const onSliderValueChange = useCallback(
+    (event: { value: number[] }) => onNodeOpacityChange((event.value[0] ?? 100) / 100),
+    [onNodeOpacityChange]
+  );
+
+  return (
+    <Box left="3" position="absolute" top="50%" transform="translateY(-50%)" zIndex="5">
+      <Toolbar>
+        {TOOLS.map(({ icon, id, label }) => (
+          <EditorToolButton
+            key={id}
+            icon={icon}
+            id={id}
+            isActive={tool === id}
+            label={label}
+            onToolChange={onToolChange}
+          />
+        ))}
+        <ToolbarSeparator />
+        <ToolbarButton icon={ZoomInIcon} label="Zoom in" onClick={onZoomInClick} />
+        <ToolbarButton icon={ZoomOutIcon} label="Zoom out" onClick={onZoomOutClick} />
+        <ToolbarButton icon={MaximizeIcon} label="Fit view" onClick={onFitViewClick} />
+        <ToolbarSeparator />
+        <Popover.Root ids={opacityIds} positioning={POPOVER_POSITIONING}>
+          <Tooltip content="Node opacity" ids={opacityIds} positioning={TOOLTIP_POSITIONING}>
+            <Popover.Trigger asChild>
+              <IconButton
+                aria-label="Node opacity"
+                color={nodeOpacity < 1 ? 'accent.solid' : undefined}
+                size="sm"
+                variant="ghost"
+              >
+                <Icon as={BlendIcon} boxSize="3.5" />
+              </IconButton>
+            </Popover.Trigger>
+          </Tooltip>
+          <Portal>
+            <Popover.Positioner>
+              <Popover.Content w="12rem">
+                <Popover.Body p="3">
+                  <Stack gap="1.5">
+                    <Text color="fg.muted" fontSize="2xs" fontWeight="600">
+                      Node opacity · {Math.round(nodeOpacity * 100)}%
+                    </Text>
+                    <Slider.Root
+                      max={100}
+                      min={20}
+                      size="sm"
+                      step={5}
+                      value={opacityValue}
+                      onValueChange={onSliderValueChange}
+                    >
+                      <Slider.Control>
+                        <Slider.Track>
+                          <Slider.Range />
+                        </Slider.Track>
+                        <Slider.Thumbs />
+                      </Slider.Control>
+                    </Slider.Root>
+                  </Stack>
+                </Popover.Body>
+              </Popover.Content>
+            </Popover.Positioner>
+          </Portal>
+        </Popover.Root>
+      </Toolbar>
+    </Box>
+  );
+};
+
+const EditorToolButton = ({
+  icon,
+  id,
+  isActive,
+  label,
+  onToolChange,
+}: {
+  icon: typeof HandIcon;
+  id: EditorTool;
+  isActive: boolean;
+  label: string;
+  onToolChange: (tool: EditorTool) => void;
+}) => {
+  const onClick = useCallback(() => onToolChange(id), [id, onToolChange]);
+
+  return <ToolbarButton icon={icon} isActive={isActive} label={label} onClick={onClick} />;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/InvocationFlowNode.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/InvocationFlowNode.tsx
new file mode 100644
index 00000000000..f3eb18f77ee
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/InvocationFlowNode.tsx
@@ -0,0 +1,787 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type {
+  FieldInputTemplate,
+  FieldOutputTemplate,
+  FieldType,
+  WorkflowInvocationNode,
+} from '@workbench/workflows/types';
+
+import { Box, Checkbox, Field, Flex, HStack, Icon, IconButton, Image, Input, Stack, Text } from '@chakra-ui/react';
+import { useNodeExecutionState, type NodeExecutionState } from '@workbench/backend/nodeExecutionStore';
+import { Tooltip } from '@workbench/components/ui';
+import { FieldDescriptionPopover } from '@workbench/widgets/workflow/fields/FieldDescriptionPopover';
+import { WorkflowFieldInput } from '@workbench/widgets/workflow/fields/WorkflowFieldInput';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import {
+  cloneWorkflowFieldDefault,
+  getFieldTypeColor,
+  getFieldTypeLabel,
+  getWorkflowFieldInvalidReason,
+  isDirectInputField,
+  isExposableField,
+  isWorkflowFieldValueDefault,
+  isModelFieldType,
+} from '@workbench/workflows/fields';
+import { Handle, Position, useStore, type NodeProps } from '@xyflow/react';
+import {
+  ChevronDownIcon,
+  ChevronRightIcon,
+  InfoIcon,
+  PinIcon,
+  PinOffIcon,
+  RotateCcwIcon,
+  TriangleAlertIcon,
+} from 'lucide-react';
+import { memo, useState, type ChangeEvent, type KeyboardEvent } from 'react';
+
+import type { InvocationFlowNode as InvocationFlowNodeType, InvocationNodeTemplateView } from './flowAdapters';
+
+import { getHandleTypeTooltip } from './handleTooltip';
+import { getWorkflowNodeChromeProps } from './nodeChrome';
+
+const NODE_WIDTH = '18rem';
+const HANDLE_SIZE = 12;
+type HandleSide = 'left' | 'right';
+/** Row padding-x in px; inline handles sit in the label rows, so they pull back out past it. */
+const ROW_PADDING_X = 12;
+/** Below this viewport zoom, field content renders as skeleton bars (ComfyUI-style) for performance/readability. */
+const CONTENT_VISIBILITY_ZOOM = 0.4;
+
+const handleStyle = (type: FieldType, side: HandleSide): React.CSSProperties => {
+  const color = getFieldTypeColor(type);
+  const isFilled = type.cardinality === 'SINGLE';
+  const isAngular = isModelFieldType(type) || type.batch;
+  const centeredDiamondTransform = `translate(${side === 'left' ? '-' : ''}50%, -50%) rotate(45deg)`;
+
+  return {
+    background: isFilled ? color : 'var(--xy-background-color)',
+    border: isFilled ? 'none' : `3px solid ${color}`,
+    borderRadius: isAngular ? 3 : '50%',
+    boxShadow: '0 0 0 1.5px var(--xy-background-color)',
+    height: HANDLE_SIZE,
+    transform: type.batch ? centeredDiamondTransform : undefined,
+    width: HANDLE_SIZE,
+  };
+};
+
+/** True while the viewport is zoomed out far enough that field content is unreadable noise. */
+const useIsZoomedOut = (): boolean => useStore((state) => state.transform[2] < CONTENT_VISIBILITY_ZOOM);
+
+/** Static placeholder bar standing in for text/controls at far zoom. No animation — there may be hundreds. */
+const SkeletonBar = ({ h = '2', w }: { h?: string; w?: string }) => <Box bg="bg.emphasized" h={h} rounded="sm" w={w} />;
+
+const hasMissingRequiredInputs = (
+  node: WorkflowInvocationNode,
+  templateInputs: FieldInputTemplate[],
+  connectedFieldNames: Set<string>
+): boolean =>
+  templateInputs.some(
+    (inputTemplate) =>
+      getWorkflowFieldInvalidReason({
+        isConnected: connectedFieldNames.has(inputTemplate.name),
+        template: inputTemplate,
+        value: node.data.inputs[inputTemplate.name]?.value,
+      }) !== null
+  );
+
+const NodeShell = ({
+  hasMissingRequiredInput,
+  children,
+  isMissing,
+  isRunning,
+  selected,
+}: {
+  hasMissingRequiredInput?: boolean;
+  children: React.ReactNode;
+  isMissing?: boolean;
+  isRunning?: boolean;
+  selected: boolean;
+}) => {
+  const isInvalid = isMissing || hasMissingRequiredInput;
+
+  return (
+    <Box
+      bg="bg"
+      fontSize="xs"
+      rounded="lg"
+      w={NODE_WIDTH}
+      {...getWorkflowNodeChromeProps({ invalid: isInvalid, running: isRunning, selected })}
+    >
+      {children}
+    </Box>
+  );
+};
+
+/** Thin progress strip under the header while the node's invocation executes. */
+const NodeProgressStrip = ({ execution }: { execution: NodeExecutionState | null }) => {
+  if (execution?.status !== 'running') {
+    return null;
+  }
+
+  return (
+    <Box bg="bg.muted" h="2px" overflow="hidden" position="relative" w="full">
+      <Box
+        bg="brand.solid"
+        h="full"
+        transition="width var(--wb-motion-duration-slow) ease"
+        w={execution.progress === null ? 'full' : `${Math.round(execution.progress * 100)}%`}
+        {...(execution.progress === null
+          ? {
+              animationDuration: 'var(--wb-motion-duration-slow)',
+              animationIterationCount: 'var(--wb-motion-animation-iteration-count)',
+              animationName: 'pulse',
+            }
+          : {})}
+      />
+    </Box>
+  );
+};
+
+const NodeTitle = ({ node, title }: { node: WorkflowInvocationNode; title: string }) => {
+  const dispatch = useWorkbenchDispatch();
+  const [draftLabel, setDraftLabel] = useState<string | null>(null);
+
+  if (draftLabel !== null) {
+    return (
+      <Input
+        autoFocus
+        aria-label="Node label"
+        className="nodrag"
+        size="2xs"
+        value={draftLabel}
+        onBlur={() => {
+          dispatch({
+            action: { label: draftLabel.trim(), nodeId: node.id, type: 'setNodeLabel' },
+            type: 'applyProjectGraphAction',
+          });
+          setDraftLabel(null);
+        }}
+        onChange={(event: ChangeEvent<HTMLInputElement>) => setDraftLabel(event.currentTarget.value)}
+        onKeyDown={(event: KeyboardEvent<HTMLInputElement>) => {
+          if (event.key === 'Enter' || event.key === 'Escape') {
+            event.currentTarget.blur();
+          }
+        }}
+      />
+    );
+  }
+
+  return (
+    <Text
+      fontWeight="700"
+      minW="0"
+      title="Double-click to rename"
+      truncate
+      // Editing always starts from the displayed title: an unset label
+      // prefills with the template title rather than an empty input.
+      onDoubleClick={() => setDraftLabel(title)}
+    >
+      {title}
+    </Text>
+  );
+};
+
+const getInputModeLabel = (input: FieldInputTemplate['input']): string => {
+  if (input === 'connection') {
+    return 'Connection only';
+  }
+
+  if (input === 'direct') {
+    return 'Direct value only';
+  }
+
+  return 'Direct value or connection';
+};
+
+const InputFieldTooltip = ({
+  description,
+  isConnected,
+  isExposed,
+  label,
+  template,
+}: {
+  description: string;
+  isConnected: boolean;
+  isExposed: boolean;
+  label: string;
+  template: FieldInputTemplate;
+}) => (
+  <Stack gap="0.5" maxW="18rem">
+    <Text fontWeight="700">{label}</Text>
+    <Text color="fg.subtle">Field: {template.name}</Text>
+    <Text color="fg.subtle">Type: {getFieldTypeLabel(template.type)}</Text>
+    <Text color="fg.subtle">
+      {template.required ? 'Required' : 'Optional'} · {getInputModeLabel(template.input)}
+    </Text>
+    {isConnected ? <Text color="fg.subtle">Connected by graph edge.</Text> : null}
+    {isExposed ? <Text color="fg.subtle">Pinned to Linear UI.</Text> : null}
+    {description ? <Text>{description}</Text> : null}
+  </Stack>
+);
+
+const OutputFieldTooltip = ({ template }: { template: FieldOutputTemplate }) => (
+  <Stack gap="0.5" maxW="18rem">
+    <Text fontWeight="700">{template.title}</Text>
+    <Text color="fg.subtle">Field: {template.name}</Text>
+    <Text color="fg.subtle">Type: {getFieldTypeLabel(template.type)}</Text>
+    <Text color="fg.subtle">Output</Text>
+    {template.description ? <Text>{template.description}</Text> : null}
+  </Stack>
+);
+
+const NodeInfoTooltipContent = ({
+  node,
+  template,
+}: {
+  node: WorkflowInvocationNode;
+  template: InvocationNodeTemplateView['template'];
+}) => {
+  const title = node.data.label ? `${node.data.label} (${template.title})` : template.title;
+  const nodePack = node.data.nodePack || template.nodePack;
+
+  return (
+    <Stack gap="1" maxW="20rem">
+      <Text fontWeight="700">{title}</Text>
+      <Text color="fg.subtle">Type: {template.type}</Text>
+      <Text color="fg.subtle">Node pack: {nodePack}</Text>
+      <Text color="fg.subtle">Version: {node.data.version}</Text>
+      <Text color="fg.subtle">Classification: {template.classification}</Text>
+      <Text color="fg.subtle">Category: {template.category}</Text>
+      {template.description ? <Text fontStyle="italic">{template.description}</Text> : null}
+      {node.data.notes ? <Text>{node.data.notes}</Text> : null}
+    </Stack>
+  );
+};
+
+const NodeInfoButton = ({
+  node,
+  template,
+}: {
+  node: WorkflowInvocationNode;
+  template: InvocationNodeTemplateView['template'];
+}) => (
+  <Tooltip
+    content={<NodeInfoTooltipContent node={node} template={template} />}
+    positioning={{ placement: 'top-end' }}
+    showArrow
+  >
+    <IconButton
+      aria-label={`Show details for ${node.data.label || template.title}`}
+      className="nodrag"
+      size="2xs"
+      variant="ghost"
+    >
+      <Icon as={InfoIcon} boxSize="3.5" />
+    </IconButton>
+  </Tooltip>
+);
+
+const NodeFooter = ({ canUseCache, node }: { canUseCache: boolean; node: WorkflowInvocationNode }) => {
+  const dispatch = useWorkbenchDispatch();
+
+  return (
+    <Flex
+      align="center"
+      bg="bg.subtle"
+      borderBottomRadius="lg"
+      borderColor="border.subtle"
+      borderTopWidth="1px"
+      className="nodrag"
+      gap="3"
+      justify="space-between"
+      minH="8"
+      px="2.5"
+      py="1"
+    >
+      <HStack gap="4">
+        {canUseCache ? (
+          <Checkbox.Root
+            checked={node.data.useCache}
+            colorPalette="accent"
+            size="xs"
+            onCheckedChange={(event) =>
+              dispatch({
+                action: { nodeId: node.id, type: 'setNodeUseCache', useCache: event.checked === true },
+                type: 'applyProjectGraphAction',
+              })
+            }
+          >
+            <Checkbox.HiddenInput />
+            <Checkbox.Control />
+            <Checkbox.Label fontSize="2xs">Use Cache</Checkbox.Label>
+          </Checkbox.Root>
+        ) : null}
+        <Checkbox.Root
+          checked={!node.data.isIntermediate}
+          colorPalette="accent"
+          size="xs"
+          onCheckedChange={(event) =>
+            dispatch({
+              action: { isIntermediate: event.checked !== true, nodeId: node.id, type: 'setNodeIsIntermediate' },
+              type: 'applyProjectGraphAction',
+            })
+          }
+        >
+          <Checkbox.HiddenInput />
+          <Checkbox.Control />
+          <Checkbox.Label fontSize="2xs">Save to Gallery</Checkbox.Label>
+        </Checkbox.Root>
+      </HStack>
+    </Flex>
+  );
+};
+
+const InputFieldRow = ({
+  isConnected,
+  isExposed,
+  isSkeleton,
+  node,
+  template,
+}: {
+  isConnected: boolean;
+  isExposed: boolean;
+  isSkeleton: boolean;
+  node: WorkflowInvocationNode;
+  template: FieldInputTemplate;
+}) => {
+  const dispatch = useWorkbenchDispatch();
+  const instance = node.data.inputs[template.name];
+  const fieldIdentifier = { fieldName: template.name, nodeId: node.id };
+  const showsControl = !isConnected && isDirectInputField(template);
+  const label = instance?.label || template.title;
+  const invalidReason = getWorkflowFieldInvalidReason({
+    isConnected,
+    template,
+    value: instance?.value,
+  });
+  const isInvalid = invalidReason !== null;
+  const handleTooltip = getHandleTypeTooltip(template.type);
+  const canReset = showsControl && !isWorkflowFieldValueDefault(template, instance?.value);
+
+  if (isSkeleton) {
+    return (
+      <Box px="3" py="1.5">
+        <HStack gap="1.5" h="5" position="relative">
+          {template.input !== 'direct' ? (
+            <Tooltip content={handleTooltip} showArrow>
+              <Handle
+                id={template.name}
+                position={Position.Left}
+                style={{ ...handleStyle(template.type, 'left'), left: -ROW_PADDING_X, top: '50%' }}
+                type="target"
+              />
+            </Tooltip>
+          ) : null}
+          <SkeletonBar w="55%" />
+        </HStack>
+        {showsControl ? <SkeletonBar h="6" w="full" /> : null}
+      </Box>
+    );
+  }
+
+  return (
+    <Box px="3" py="1.5" w="full">
+      <Field.Root gap="0" invalid={isInvalid} minW="0" w="full">
+        {/* The handle lives inside the label row so it stays centered on the
+            label even when the value control below grows the row. */}
+        <HStack gap="1.5" h="5" justify="space-between" minW="0" position="relative" w="full">
+          {template.input !== 'direct' ? (
+            <Tooltip content={handleTooltip} positioning={{ placement: 'right-end' }} showArrow>
+              <Handle
+                id={template.name}
+                position={Position.Left}
+                style={{ ...handleStyle(template.type, 'left'), left: -ROW_PADDING_X, top: '50%' }}
+                type="target"
+              />
+            </Tooltip>
+          ) : null}
+          <Tooltip
+            positioning={{ placement: 'top-start' }}
+            content={
+              <InputFieldTooltip
+                description={instance?.description || template.description}
+                isConnected={isConnected}
+                isExposed={isExposed}
+                label={label}
+                template={template}
+              />
+            }
+          >
+            <Text
+              color={isInvalid ? 'fg.error' : isConnected ? 'fg.muted' : 'fg'}
+              fontSize="2xs"
+              lineHeight="1"
+              minW="0"
+              truncate
+            >
+              {label}
+              {template.required ? (
+                <Text as="span" color="fg.error">
+                  {' *'}
+                </Text>
+              ) : null}
+            </Text>
+          </Tooltip>
+          <HStack flexShrink={0} gap="0" ml="auto">
+            {canReset ? (
+              <Tooltip content="Reset to default value">
+                <IconButton
+                  aria-label={`Reset ${label} to default value`}
+                  className="nodrag"
+                  color="fg.subtle"
+                  size="2xs"
+                  title="Reset to default value"
+                  variant="ghost"
+                  onClick={() =>
+                    dispatch({
+                      action: {
+                        fieldName: template.name,
+                        nodeId: node.id,
+                        type: 'setFieldValue',
+                        value: cloneWorkflowFieldDefault(template),
+                      },
+                      type: 'applyProjectGraphAction',
+                    })
+                  }
+                >
+                  <Icon as={RotateCcwIcon} boxSize="3" />
+                </IconButton>
+              </Tooltip>
+            ) : null}
+            <FieldDescriptionPopover
+              description={instance?.description}
+              fieldName={template.name}
+              nodeId={node.id}
+              templateDescription={template.description}
+            />
+            {isExposableField(template) ? (
+              <IconButton
+                aria-label={isExposed ? `Remove ${label} from Linear UI` : `Expose ${label} in Linear UI`}
+                className="nodrag"
+                color={isExposed ? 'accent.solid' : 'fg.subtle'}
+                size="2xs"
+                title={isExposed ? 'Remove from Linear UI form' : 'Expose in Linear UI form'}
+                variant="ghost"
+                onClick={() =>
+                  dispatch({
+                    action: { fieldIdentifier, type: isExposed ? 'unexposeField' : 'exposeField' },
+                    type: 'applyProjectGraphAction',
+                  })
+                }
+              >
+                <Icon as={isExposed ? PinOffIcon : PinIcon} boxSize="3" />
+              </IconButton>
+            ) : null}
+          </HStack>
+        </HStack>
+        {showsControl ? (
+          <Box mt="0.5" w="full">
+            <WorkflowFieldInput
+              id={`${node.id}-${template.name}-value`}
+              invalid={isInvalid}
+              template={template}
+              value={instance?.value}
+              onChange={(value) =>
+                dispatch({
+                  action: { fieldName: template.name, nodeId: node.id, type: 'setFieldValue', value },
+                  type: 'applyProjectGraphAction',
+                })
+              }
+            />
+          </Box>
+        ) : null}
+        {invalidReason ? <Field.ErrorText fontSize="2xs">{invalidReason}</Field.ErrorText> : null}
+      </Field.Root>
+    </Box>
+  );
+};
+
+const OutputFieldRow = ({ isSkeleton, template }: { isSkeleton: boolean; template: FieldOutputTemplate }) => {
+  const handleTooltip = getHandleTypeTooltip(template.type);
+
+  return (
+    <Box px="3" py="1">
+      <Flex align="center" h="5" justify="flex-end" position="relative">
+        <Tooltip content={handleTooltip} positioning={{ placement: 'left-start' }} showArrow>
+          <Handle
+            id={template.name}
+            position={Position.Right}
+            style={{ ...handleStyle(template.type, 'right'), right: -ROW_PADDING_X, top: '50%' }}
+            type="source"
+          />
+        </Tooltip>
+        {isSkeleton ? (
+          <Flex justify="flex-end" w="full">
+            <SkeletonBar w="40%" />
+          </Flex>
+        ) : (
+          <Box textAlign="end">
+            <Tooltip content={<OutputFieldTooltip template={template} />} positioning={{ placement: 'top-end' }}>
+              <Text
+                as="span"
+                color="fg.muted"
+                display="inline-block"
+                fontSize="2xs"
+                lineHeight="1"
+                maxW="full"
+                textAlign="end"
+                truncate
+              >
+                {template.title}
+              </Text>
+            </Tooltip>
+          </Box>
+        )}
+      </Flex>
+    </Box>
+  );
+};
+
+/** Keeps every handle mounted (invisible) so edges stay attached when rows are not rendered. */
+const HiddenHandles = ({
+  inputTemplates,
+  outputTemplates,
+}: {
+  inputTemplates: FieldInputTemplate[];
+  outputTemplates: FieldOutputTemplate[];
+}) => (
+  <Box position="relative" h="0">
+    {outputTemplates.map((outputTemplate) => (
+      <Handle
+        key={outputTemplate.name}
+        id={outputTemplate.name}
+        position={Position.Right}
+        style={{ ...handleStyle(outputTemplate.type, 'right'), opacity: 0, right: 0, top: -14 }}
+        type="source"
+      />
+    ))}
+    {inputTemplates.map((inputTemplate) =>
+      inputTemplate.input !== 'direct' ? (
+        <Handle
+          key={inputTemplate.name}
+          id={inputTemplate.name}
+          position={Position.Left}
+          style={{ ...handleStyle(inputTemplate.type, 'left'), left: 0, opacity: 0, top: -14 }}
+          type="target"
+        />
+      ) : null
+    )}
+  </Box>
+);
+
+const CompactHiddenHandles = ({
+  connectedSourceHandles,
+  connectedTargetHandles,
+  inputTemplates,
+  outputTemplates,
+}: {
+  connectedSourceHandles: string[];
+  connectedTargetHandles: string[];
+  inputTemplates: FieldInputTemplate[];
+  outputTemplates: FieldOutputTemplate[];
+}) => {
+  const connectedSources = new Set(connectedSourceHandles);
+  const connectedTargets = new Set(connectedTargetHandles);
+
+  return (
+    <HiddenHandles
+      inputTemplates={inputTemplates.filter((inputTemplate) => connectedTargets.has(inputTemplate.name))}
+      outputTemplates={outputTemplates.filter((outputTemplate) => connectedSources.has(outputTemplate.name))}
+    />
+  );
+};
+
+const CompactNodeBody = ({ inputCount, outputCount }: { inputCount: number; outputCount: number }) => (
+  <Flex
+    align="center"
+    bg="bg.muted"
+    borderBottomRadius="lg"
+    borderTopWidth="1px"
+    borderColor="border.subtle"
+    color="fg.subtle"
+    fontSize="2xs"
+    gap="2"
+    px="3"
+    py="2"
+  >
+    <Text>
+      {inputCount} input{inputCount === 1 ? '' : 's'}
+    </Text>
+    <Text>·</Text>
+    <Text>
+      {outputCount} output{outputCount === 1 ? '' : 's'}
+    </Text>
+    <Text ms="auto">Select for fields</Text>
+  </Flex>
+);
+
+const CompactInvocationNode = ({ data, selected }: NodeProps<InvocationFlowNodeType>) => {
+  const node = data.documentNode;
+  const templateView = data.template;
+  const inputTemplates = templateView?.inputTemplates ?? [];
+  const outputTemplates = templateView?.outputTemplates ?? [];
+  const title = node.data.label || templateView?.template.title || node.data.type;
+
+  return (
+    <NodeShell isMissing={!templateView} selected={selected ?? false}>
+      <Flex
+        align="center"
+        bg="bg.subtle"
+        borderBottomWidth="1px"
+        borderColor="border.subtle"
+        borderTopRadius="lg"
+        gap="1"
+        px="3"
+        py="2"
+      >
+        <Text fontSize="sm" fontWeight="700" minW="0" title={title} truncate>
+          {title}
+        </Text>
+      </Flex>
+      {templateView ? (
+        <CompactNodeBody inputCount={inputTemplates.length} outputCount={outputTemplates.length} />
+      ) : (
+        <Text bg="bg.muted" borderBottomRadius="lg" color="fg.subtle" fontSize="2xs" px="3" py="2">
+          Unknown node type. Select for details.
+        </Text>
+      )}
+      <CompactHiddenHandles
+        connectedSourceHandles={data.connectedSourceHandles}
+        connectedTargetHandles={data.connectedTargetHandles}
+        inputTemplates={inputTemplates}
+        outputTemplates={outputTemplates}
+      />
+    </NodeShell>
+  );
+};
+
+const ExpandedInvocationNode = ({ data, selected }: NodeProps<InvocationFlowNodeType>) => {
+  const dispatch = useWorkbenchDispatch();
+  const isZoomedOut = useIsZoomedOut();
+  const node = data.documentNode;
+  const templateView = data.template;
+  const execution = useNodeExecutionState(node.id);
+
+  if (!templateView) {
+    return (
+      <NodeShell isMissing selected={selected ?? false}>
+        <HStack gap="1.5" p="3">
+          <Icon as={TriangleAlertIcon} boxSize="3.5" color="red.solid" />
+          <Stack gap="0">
+            <Text fontWeight="700">{node.data.label || node.data.type}</Text>
+            <Text color="fg.subtle" fontSize="2xs">
+              Unknown node type "{node.data.type}". It cannot run on this backend.
+            </Text>
+          </Stack>
+        </HStack>
+      </NodeShell>
+    );
+  }
+
+  const template = templateView.template;
+  const connectedFieldNames = new Set(data.connectedTargetHandles);
+  const exposedFieldNames = new Set(data.exposedFieldNames);
+  const inputTemplates = templateView.inputTemplates;
+  const outputTemplates = templateView.outputTemplates;
+  const isOpen = node.data.isOpen;
+  const isRunning = execution?.status === 'running';
+  const isMissingRequiredInput = hasMissingRequiredInputs(node, Object.values(template.inputs), connectedFieldNames);
+  const isCompact = data.isCompact && !selected;
+  const withFooter = !isZoomedOut && templateView.isExecutable && templateView.hasImageOutput;
+  const withOutputPreview = Boolean(execution?.outputImageUrl);
+
+  return (
+    <NodeShell hasMissingRequiredInput={isMissingRequiredInput} isRunning={isRunning} selected={selected ?? false}>
+      <Flex
+        align="center"
+        bg="bg.subtle"
+        borderBottomWidth={isOpen ? '1px' : '0'}
+        borderColor="border.subtle"
+        borderTopRadius="lg"
+        borderBottomRadius={isOpen ? 'none' : 'lg'}
+        gap="1"
+        ps="1.5"
+        pe="2"
+        py="1.5"
+      >
+        <IconButton
+          aria-label={isOpen ? 'Collapse node' : 'Expand node'}
+          className="nodrag"
+          size="2xs"
+          variant="ghost"
+          onClick={() =>
+            dispatch({
+              action: { isOpen: !isOpen, nodeId: node.id, type: 'setNodeIsOpen' },
+              type: 'applyProjectGraphAction',
+            })
+          }
+        >
+          <Icon as={isOpen ? ChevronDownIcon : ChevronRightIcon} boxSize="3.5" />
+        </IconButton>
+        {isZoomedOut ? (
+          <Text fontSize="sm" fontWeight="700" minW="0" truncate>
+            {node.data.label || template.title}
+          </Text>
+        ) : (
+          <>
+            <NodeTitle node={node} title={node.data.label || template.title} />
+            <Box flex="1" />
+            <NodeInfoButton node={node} template={template} />
+          </>
+        )}
+      </Flex>
+      <NodeProgressStrip execution={execution} />
+      {isOpen && isCompact ? (
+        <>
+          <CompactNodeBody inputCount={inputTemplates.length} outputCount={outputTemplates.length} />
+          <HiddenHandles inputTemplates={inputTemplates} outputTemplates={outputTemplates} />
+        </>
+      ) : isOpen ? (
+        <Box bg="bg.muted" borderBottomRadius={withFooter || withOutputPreview ? 'none' : 'lg'} py="1">
+          {outputTemplates.map((outputTemplate) => (
+            <OutputFieldRow key={outputTemplate.name} isSkeleton={isZoomedOut} template={outputTemplate} />
+          ))}
+          {inputTemplates.map((inputTemplate) => (
+            <InputFieldRow
+              key={inputTemplate.name}
+              isConnected={connectedFieldNames.has(inputTemplate.name)}
+              isExposed={exposedFieldNames.has(inputTemplate.name)}
+              isSkeleton={isZoomedOut}
+              node={node}
+              template={inputTemplate}
+            />
+          ))}
+        </Box>
+      ) : (
+        <HiddenHandles inputTemplates={inputTemplates} outputTemplates={outputTemplates} />
+      )}
+      {isOpen && execution?.outputImageUrl ? (
+        <Box borderBottomRadius={withFooter ? 'none' : 'lg'} borderColor="border.subtle" borderTopWidth="1px" p="1.5">
+          {isZoomedOut ? (
+            <SkeletonBar h="6rem" w="full" />
+          ) : (
+            <Image
+              alt="Latest output of this node"
+              draggable={false}
+              maxH="10rem"
+              mx="auto"
+              objectFit="contain"
+              rounded="sm"
+              src={execution.outputImageUrl}
+            />
+          )}
+        </Box>
+      ) : null}
+      {isOpen && withFooter ? <NodeFooter canUseCache={data.canUseCache} node={node} /> : null}
+    </NodeShell>
+  );
+};
+
+const InvocationFlowNodeComponent = (props: NodeProps<InvocationFlowNodeType>) =>
+  props.data.isCompact && !props.selected ? (
+    <CompactInvocationNode {...props} />
+  ) : (
+    <ExpandedInvocationNode {...props} />
+  );
+
+export const InvocationFlowNode = memo(InvocationFlowNodeComponent);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/NodeContextMenu.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/NodeContextMenu.tsx
new file mode 100644
index 00000000000..d25bf155b6b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/NodeContextMenu.tsx
@@ -0,0 +1,136 @@
+import type { XYPosition } from '@workbench/workflows/types';
+
+import { Icon, Menu, Portal } from '@chakra-ui/react';
+import {
+  ChevronsDownUpIcon,
+  ChevronsUpDownIcon,
+  ClipboardPasteIcon,
+  CopyIcon,
+  CopyPlusIcon,
+  PlusIcon,
+  Trash2Icon,
+} from 'lucide-react';
+import { useCallback, useMemo } from 'react';
+
+/**
+ * Right-click utilities for the flow pane and nodes, anchored at the pointer.
+ * The menu is fully controlled because each action needs editor-local context.
+ */
+
+export interface NodeContextMenuState {
+  kind: 'node';
+  nodeId?: string;
+  /** The node's `isOpen`; null for node types without a collapse toggle (notes). */
+  isNodeOpen: boolean | null;
+  x: number;
+  y: number;
+}
+
+export interface PaneContextMenuState {
+  kind: 'pane';
+  position: XYPosition;
+  x: number;
+  y: number;
+}
+
+export type WorkflowContextMenuState = NodeContextMenuState | PaneContextMenuState;
+
+export const NodeContextMenu = ({
+  canPaste,
+  menuState,
+  onClose,
+  onAddConnector,
+  onCopy,
+  onDelete,
+  onDuplicate,
+  onPaste,
+  onToggleOpen,
+}: {
+  canPaste: boolean;
+  menuState: WorkflowContextMenuState | null;
+  onClose: () => void;
+  onAddConnector: (position: XYPosition) => void;
+  onCopy: () => void;
+  onDelete: () => void;
+  onDuplicate: () => void;
+  onPaste: () => void;
+  onToggleOpen: () => void;
+}) => {
+  const positioning = useMemo(
+    () => ({
+      getAnchorRect: () => (menuState ? { height: 1, width: 1, x: menuState.x, y: menuState.y } : null),
+      placement: 'bottom-start' as const,
+    }),
+    [menuState]
+  );
+  const onOpenChange = useCallback(
+    (event: { open: boolean }) => {
+      if (!event.open) {
+        onClose();
+      }
+    },
+    [onClose]
+  );
+
+  return (
+    <Menu.Root open={menuState !== null} positioning={positioning} onOpenChange={onOpenChange}>
+      <Portal>
+        <Menu.Positioner>
+          <Menu.Content minW="11rem">
+            {!menuState ? null : menuState.kind === 'pane' ? (
+              <PaneAddConnectorMenuItem position={menuState.position} onAddConnector={onAddConnector} />
+            ) : (
+              <>
+                <Menu.Item value="copy" onClick={onCopy}>
+                  <Icon as={CopyIcon} boxSize="3.5" />
+                  <Menu.ItemText>Copy</Menu.ItemText>
+                  <Menu.ItemCommand>Ctrl C</Menu.ItemCommand>
+                </Menu.Item>
+                <Menu.Item disabled={!canPaste} value="paste" _disabled={DISABLED_PROPS} onClick={onPaste}>
+                  <Icon as={ClipboardPasteIcon} boxSize="3.5" />
+                  <Menu.ItemText>Paste</Menu.ItemText>
+                  <Menu.ItemCommand>Ctrl V</Menu.ItemCommand>
+                </Menu.Item>
+                <Menu.Item value="duplicate" onClick={onDuplicate}>
+                  <Icon as={CopyPlusIcon} boxSize="3.5" />
+                  <Menu.ItemText>Duplicate</Menu.ItemText>
+                </Menu.Item>
+                {menuState.isNodeOpen !== null ? (
+                  <Menu.Item value="toggle-open" onClick={onToggleOpen}>
+                    <Icon as={menuState.isNodeOpen ? ChevronsDownUpIcon : ChevronsUpDownIcon} boxSize="3.5" />
+                    <Menu.ItemText>{menuState.isNodeOpen ? 'Collapse' : 'Expand'}</Menu.ItemText>
+                  </Menu.Item>
+                ) : null}
+                <Menu.Separator borderColor="border.subtle" />
+                <Menu.Item color="fg.error" value="delete" onClick={onDelete}>
+                  <Icon as={Trash2Icon} boxSize="3.5" />
+                  <Menu.ItemText>Delete</Menu.ItemText>
+                  <Menu.ItemCommand>Del</Menu.ItemCommand>
+                </Menu.Item>
+              </>
+            )}
+          </Menu.Content>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
+
+const DISABLED_PROPS = { opacity: 0.4 };
+
+const PaneAddConnectorMenuItem = ({
+  onAddConnector,
+  position,
+}: {
+  onAddConnector: (position: XYPosition) => void;
+  position: XYPosition;
+}) => {
+  const onClick = useCallback(() => onAddConnector(position), [onAddConnector, position]);
+
+  return (
+    <Menu.Item value="add-connector" onClick={onClick}>
+      <Icon as={PlusIcon} boxSize="3.5" />
+      <Menu.ItemText>Add connector</Menu.ItemText>
+    </Menu.Item>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/NotesFlowNode.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/NotesFlowNode.tsx
new file mode 100644
index 00000000000..8b3681efc21
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/NotesFlowNode.tsx
@@ -0,0 +1,58 @@
+import type { NodeProps } from '@xyflow/react';
+
+import { Box, Input, Textarea } from '@chakra-ui/react';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { memo, useCallback, type ChangeEvent } from 'react';
+
+import type { NotesFlowNode as NotesFlowNodeType } from './flowAdapters';
+
+import { getWorkflowNodeChromeProps } from './nodeChrome';
+
+const NotesFlowNodeComponent = ({ data, selected }: NodeProps<NotesFlowNodeType>) => {
+  const dispatch = useWorkbenchDispatch();
+  const node = data.documentNode;
+  const onLabelChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) =>
+      dispatch({
+        action: { label: event.currentTarget.value, nodeId: node.id, type: 'setNodeLabel' },
+        type: 'applyProjectGraphAction',
+      }),
+    [dispatch, node.id]
+  );
+  const onNotesChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) =>
+      dispatch({
+        action: { nodeId: node.id, notes: event.currentTarget.value, type: 'setNodeNotes' },
+        type: 'applyProjectGraphAction',
+      }),
+    [dispatch, node.id]
+  );
+
+  return (
+    <Box bg="bg.subtle" p="2" rounded="lg" w="16rem" {...getWorkflowNodeChromeProps({ selected })}>
+      <Input
+        aria-label="Note title"
+        className="nodrag"
+        fontWeight="700"
+        mb="1.5"
+        size="2xs"
+        value={node.data.label}
+        variant="flushed"
+        onChange={onLabelChange}
+      />
+      <Textarea
+        aria-label="Note text"
+        className="nodrag nowheel"
+        fontSize="2xs"
+        minH="5rem"
+        placeholder="Write a note…"
+        resize="vertical"
+        size="xs"
+        value={node.data.notes}
+        onChange={onNotesChange}
+      />
+    </Box>
+  );
+};
+
+export const NotesFlowNode = memo(NotesFlowNodeComponent);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEdge.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEdge.test.ts
new file mode 100644
index 00000000000..79374458cb3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEdge.test.ts
@@ -0,0 +1,41 @@
+import { Position } from '@xyflow/react';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import type { WorkflowEdgeData } from './flowAdapters';
+
+import { WorkflowEdge } from './WorkflowEdge';
+
+const data: WorkflowEdgeData = {
+  fieldTypeLabel: 'Image',
+  pathType: 'default',
+  stroke: '#c4b5fd',
+  strokeWidth: 2,
+  tooltip: 'Image',
+};
+
+const props = {
+  data,
+  id: 'edge-1',
+  markerEnd: undefined,
+  selected: false,
+  source: 'a',
+  sourcePosition: Position.Right,
+  sourceX: 0,
+  sourceY: 0,
+  target: 'b',
+  targetPosition: Position.Left,
+  targetX: 100,
+  targetY: 0,
+};
+
+describe('WorkflowEdge', () => {
+  it('attaches the field type tooltip to visible and interactive edge paths', () => {
+    const markup = renderToStaticMarkup(createElement(WorkflowEdge, props));
+
+    expect(markup).toContain('react-flow__edge-path');
+    expect(markup).toContain('react-flow__edge-interaction');
+    expect(markup.match(/<title>Image<\/title>/g)).toHaveLength(2);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEdge.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEdge.tsx
new file mode 100644
index 00000000000..6e8889bb3c8
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEdge.tsx
@@ -0,0 +1,91 @@
+import type { EdgeProps } from '@xyflow/react';
+
+import { getBezierPath, getSmoothStepPath } from '@xyflow/react';
+import { memo, type CSSProperties } from 'react';
+
+import type { WorkflowEdgeData } from './flowAdapters';
+
+const FALLBACK_EDGE_DATA: WorkflowEdgeData = {
+  fieldTypeLabel: 'Unknown',
+  pathType: 'default',
+  stroke: 'var(--xy-edge-stroke)',
+  strokeWidth: 2,
+  tooltip: 'Unknown field type',
+};
+
+const WorkflowEdgeComponent = ({
+  data,
+  interactionWidth = 20,
+  markerEnd,
+  markerStart,
+  selected,
+  sourcePosition,
+  sourceX,
+  sourceY,
+  style,
+  targetPosition,
+  targetX,
+  targetY,
+}: EdgeProps) => {
+  const edgeData = (data as WorkflowEdgeData | undefined) ?? FALLBACK_EDGE_DATA;
+  const [edgePath] =
+    edgeData.pathType === 'step'
+      ? getSmoothStepPath({
+          borderRadius: 0,
+          sourcePosition,
+          sourceX,
+          sourceY,
+          targetPosition,
+          targetX,
+          targetY,
+        })
+      : getBezierPath({
+          sourcePosition,
+          sourceX,
+          sourceY,
+          targetPosition,
+          targetX,
+          targetY,
+        });
+  const edgeStyle: CSSProperties = {
+    ...style,
+    animation: selected
+      ? 'dashdraw var(--wb-motion-duration-slow) linear var(--wb-motion-animation-iteration-count)'
+      : undefined,
+    stroke: edgeData.stroke,
+    strokeDasharray: selected ? '5' : edgeData.strokeDasharray,
+    strokeLinecap: 'round',
+    strokeLinejoin: 'round',
+    strokeWidth: edgeData.strokeWidth,
+  };
+
+  return (
+    <g aria-label={edgeData.tooltip} role="img">
+      <path
+        aria-label={edgeData.tooltip}
+        className="react-flow__edge-path"
+        d={edgePath}
+        fill="none"
+        markerEnd={markerEnd}
+        markerStart={markerStart}
+        style={edgeStyle}
+      >
+        <title>{edgeData.tooltip}</title>
+      </path>
+      {interactionWidth ? (
+        <path
+          aria-label={edgeData.tooltip}
+          className="react-flow__edge-interaction"
+          d={edgePath}
+          fill="none"
+          strokeOpacity={0}
+          strokeWidth={interactionWidth}
+        >
+          <title>{edgeData.tooltip}</title>
+        </path>
+      ) : null}
+    </g>
+  );
+};
+
+export const WorkflowEdge = memo(WorkflowEdgeComponent);
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEditorView.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEditorView.test.ts
new file mode 100644
index 00000000000..855664d4216
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEditorView.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import type { WorkflowFlowEdge, WorkflowFlowNode } from './flowAdapters';
+
+import { WORKFLOW_INITIAL_RENDER_NODE_COUNT } from './performanceConstants';
+import { getInitialRenderFlowModel } from './WorkflowEditorView';
+
+const createNode = (id: string, x: number): WorkflowFlowNode => ({
+  data: { documentNode: { data: { label: '', notes: '' }, id, position: { x, y: 0 }, type: 'notes' } },
+  id,
+  position: { x, y: 0 },
+  type: 'notes',
+});
+
+const createEdge = (id: string, source: string, target: string): WorkflowFlowEdge => ({
+  data: {
+    fieldTypeLabel: 'Unknown',
+    pathType: 'default',
+    stroke: 'var(--xy-edge-stroke)',
+    strokeWidth: 2,
+    tooltip: 'Unknown field type',
+  },
+  id,
+  source,
+  sourceHandle: 'value',
+  target,
+  targetHandle: 'value',
+  type: 'default',
+});
+
+describe('getInitialRenderFlowModel', () => {
+  it('keeps the nearest initial nodes and filters edges to that window', () => {
+    const nodes = Array.from({ length: WORKFLOW_INITIAL_RENDER_NODE_COUNT + 2 }, (_, index) =>
+      createNode(`node-${index}`, index)
+    );
+    const model = {
+      nodes,
+      edges: [
+        createEdge('inside', 'node-0', 'node-1'),
+        createEdge('outside', 'node-0', `node-${WORKFLOW_INITIAL_RENDER_NODE_COUNT + 1}`),
+      ],
+    };
+
+    const windowed = getInitialRenderFlowModel(model, { x: 0, y: 0, zoom: 1 });
+
+    expect(windowed.nodes).toHaveLength(WORKFLOW_INITIAL_RENDER_NODE_COUNT);
+    expect(windowed.nodes.map((node) => node.id)).toContain('node-0');
+    expect(windowed.nodes.map((node) => node.id)).not.toContain(`node-${WORKFLOW_INITIAL_RENDER_NODE_COUNT + 1}`);
+    expect(windowed.edges.map((edge) => edge.id)).toEqual(['inside']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEditorView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEditorView.tsx
new file mode 100644
index 00000000000..d7cc32494c4
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/WorkflowEditorView.tsx
@@ -0,0 +1,1201 @@
+import type { DiagnosticSource } from '@workbench/diagnostics/logger';
+/* eslint-disable react/react-compiler */
+import type { WidgetRuntimeApi } from '@workbench/types';
+import type { ProjectGraphState, XYPosition } from '@workbench/workflows/types';
+
+import { Box, Flex, HStack, Spinner, Stack, Text } from '@chakra-ui/react';
+import { useAuthSession } from '@workbench/auth/session';
+import { FlowMiniMap, flowThemeCss, getFlowColorMode } from '@workbench/graph-preview';
+import '@xyflow/react/dist/style.css';
+import { markWorkbenchPerf, measureWorkbenchPerf, timeWorkbenchPerf } from '@workbench/performanceMarks';
+import { useWorkbenchPreferenceSelector } from '@workbench/settings/store';
+import { useModifierHeld } from '@workbench/useModifierHeld';
+import { useNotify } from '@workbench/useNotify';
+import { setAddNodeOpen } from '@workbench/widgets/workflow/workflowUiStore';
+import { shallowEqual, useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { getProjectGraphReadiness } from '@workbench/workflows/buildGraph';
+import { buildConnectorNode, createWorkflowId } from '@workbench/workflows/document';
+import { createWorkflowGraphIndex } from '@workbench/workflows/graphIndex';
+import { ensureInvocationTemplatesLoaded, useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import {
+  getWorkflowSourceFieldType,
+  getWorkflowTargetFieldType,
+  validateConnection,
+} from '@workbench/workflows/validation';
+import {
+  Background,
+  BackgroundVariant,
+  ConnectionLineType,
+  ReactFlow,
+  ReactFlowProvider,
+  SelectionMode,
+  applyEdgeChanges,
+  applyNodeChanges,
+  type Connection,
+  type EdgeChange,
+  type EdgeTypes,
+  type IsValidConnection,
+  type NodeChange,
+  type NodeTypes,
+  type OnConnectEnd,
+  type Viewport,
+} from '@xyflow/react';
+import {
+  useCallback,
+  useEffect,
+  useEffectEvent,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  startTransition,
+  type MouseEvent as ReactMouseEvent,
+} from 'react';
+
+import { buildDuplicateElements, buildPasteElements, copyNodesToClipboard, useHasClipboardNodes } from './clipboard';
+import { ConnectorFlowNode } from './ConnectorFlowNode';
+import { CurrentImageFlowNode } from './CurrentImageFlowNode';
+import { EditorToolbar, type EditorTool } from './EditorToolbar';
+import {
+  toFlowEdges,
+  toFlowNodes,
+  withNodeSelection,
+  type FlowEdgeType,
+  type WorkflowFlowEdge,
+  type WorkflowFlowNode,
+} from './flowAdapters';
+import {
+  registerWorkflowFlowInstance,
+  releaseWorkflowFlowInstance,
+  type WorkflowFlowInstance,
+} from './flowInstanceStore';
+import { InvocationFlowNode } from './InvocationFlowNode';
+import { NodeContextMenu, type WorkflowContextMenuState } from './NodeContextMenu';
+import { NotesFlowNode } from './NotesFlowNode';
+import {
+  isLargeWorkflowGraph,
+  WORKFLOW_INITIAL_RENDER_NODE_COUNT,
+  WORKFLOW_MINIMAP_DELAY_MS,
+} from './performanceConstants';
+import {
+  clearNodeSelectionRequest,
+  reportNodeHover,
+  reportNodeSelection,
+  workflowSelectionStore,
+} from './selectionStore';
+import { useEraser } from './useEraser';
+import { useLasso } from './useLasso';
+import { WorkflowEdge } from './WorkflowEdge';
+import { getWorkflowViewport, getWorkflowViewportKey, setWorkflowViewport } from './workflowViewportStore';
+
+const nodeTypes: NodeTypes = {
+  connector: ConnectorFlowNode,
+  current_image: CurrentImageFlowNode,
+  invocation: InvocationFlowNode,
+  notes: NotesFlowNode,
+};
+
+const edgeTypes: EdgeTypes = {
+  default: WorkflowEdge,
+  step: WorkflowEdge,
+};
+
+/**
+ * The workflow center view: an xyflow editor over the project graph document.
+ * The document is the source of truth — flow state is rebuilt from it on every
+ * document change (undo, import, field edits), while transient view state
+ * (selection, in-flight drags, the active tool) lives in local component state.
+ */
+/** Snap spacing matches the background dot grid. */
+const SNAP_GRID: [number, number] = [24, 24];
+
+const DELETE_KEY_CODES = ['Backspace', 'Delete'];
+
+const DEFAULT_EDGE_OPTIONS = { style: { strokeWidth: 2 } };
+const DEFAULT_VIEWPORT = { x: 0, y: 0, zoom: 1 } as const;
+
+interface WorkflowFlowModel {
+  edges: WorkflowFlowEdge[];
+  nodes: WorkflowFlowNode[];
+}
+
+const EMPTY_FLOW_EDGES: WorkflowFlowEdge[] = [];
+const EMPTY_FLOW_NODES: WorkflowFlowNode[] = [];
+
+const buildWorkflowFlowModel = ({
+  document,
+  edgeType,
+  invocationTemplates,
+  previousEdges = [],
+  previousNodes = [],
+  reduceMotion,
+  selectedNodeIds = new Set<string>(),
+  isCompact = false,
+  canUseCache = false,
+  perfSource,
+}: {
+  canUseCache?: boolean;
+  document: ProjectGraphState;
+  edgeType: FlowEdgeType;
+  isCompact?: boolean;
+  invocationTemplates?: Parameters<typeof toFlowNodes>[2];
+  perfSource?: DiagnosticSource;
+  previousEdges?: WorkflowFlowEdge[];
+  previousNodes?: WorkflowFlowNode[];
+  reduceMotion: boolean;
+  selectedNodeIds?: Set<string>;
+}): WorkflowFlowModel => {
+  const index = timeWorkbenchPerf('workflow:create-graph-index', perfSource, () =>
+    createWorkflowGraphIndex(document.nodes, document.edges)
+  );
+
+  return timeWorkbenchPerf('workflow:build-flow-model', perfSource, () => ({
+    edges: timeWorkbenchPerf('workflow:to-flow-edges', perfSource, () =>
+      toFlowEdges(document, previousEdges, edgeType, selectedNodeIds, invocationTemplates, reduceMotion, index)
+    ),
+    nodes: timeWorkbenchPerf('workflow:to-flow-nodes', perfSource, () =>
+      toFlowNodes(document, previousNodes, invocationTemplates, index, isCompact, canUseCache)
+    ),
+  }));
+};
+
+const getEventClientPosition = (event: MouseEvent | TouchEvent): { x: number; y: number } | null => {
+  if (event instanceof MouseEvent) {
+    return { x: event.clientX, y: event.clientY };
+  }
+
+  const touch = event.changedTouches[0];
+
+  return touch ? { x: touch.clientX, y: touch.clientY } : null;
+};
+
+const WorkflowEditorPreparingState = ({ edgeCount, nodeCount }: { edgeCount: number; nodeCount: number }) => (
+  <Flex align="center" bg="bg.inset" h="full" justify="center" p="6" w="full">
+    <Stack align="center" gap="3" textAlign="center">
+      <HStack color="fg.muted" gap="2">
+        <Spinner size="sm" />
+        <Text fontSize="sm" fontWeight="700">
+          Preparing workflow graph
+        </Text>
+      </HStack>
+      <Text color="fg.subtle" fontSize="xs">
+        Loading {nodeCount.toLocaleString()} node{nodeCount === 1 ? '' : 's'} and {edgeCount.toLocaleString()} edge
+        {edgeCount === 1 ? '' : 's'}.
+      </Text>
+    </Stack>
+  </Flex>
+);
+
+const getSelectedNodeIdSet = (nodes: WorkflowFlowNode[]): Set<string> =>
+  new Set(nodes.filter((node) => node.selected).map((node) => node.id));
+
+const getNodeDistanceFromViewportOrigin = (node: WorkflowFlowNode, viewport: Viewport): number => {
+  const zoom = viewport.zoom || 1;
+  const originX = -viewport.x / zoom;
+  const originY = -viewport.y / zoom;
+  const dx = node.position.x - originX;
+  const dy = node.position.y - originY;
+
+  return dx * dx + dy * dy;
+};
+
+export const getInitialRenderFlowModel = (model: WorkflowFlowModel, viewport: Viewport): WorkflowFlowModel => {
+  if (model.nodes.length <= WORKFLOW_INITIAL_RENDER_NODE_COUNT) {
+    return model;
+  }
+
+  const nodes = [...model.nodes]
+    .sort(
+      (left, right) =>
+        getNodeDistanceFromViewportOrigin(left, viewport) - getNodeDistanceFromViewportOrigin(right, viewport)
+    )
+    .slice(0, WORKFLOW_INITIAL_RENDER_NODE_COUNT);
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const edges = model.edges.filter((edge) => nodeIds.has(edge.source) && nodeIds.has(edge.target));
+
+  return { edges, nodes };
+};
+
+const WorkflowFlow = ({ runtime }: { runtime: WidgetRuntimeApi }) => {
+  const projectGraph = useActiveProjectSelector((project) => project.projectGraph);
+  const projectId = useActiveProjectSelector((project) => project.id);
+  const session = useAuthSession();
+  const dispatch = useWorkbenchDispatch();
+  const notify = useNotify();
+  const {
+    reduceMotion,
+    themeId,
+    workflowEdgeStyle,
+    workflowShowMinimap,
+    workflowSnapToGrid,
+    workflowValidateConnections,
+  } = useWorkbenchPreferenceSelector(
+    (preferences) => ({
+      reduceMotion: preferences.reduceMotion,
+      themeId: preferences.themeId,
+      workflowEdgeStyle: preferences.workflowEdgeStyle,
+      workflowShowMinimap: preferences.workflowShowMinimap,
+      workflowSnapToGrid: preferences.workflowSnapToGrid,
+      workflowValidateConnections: preferences.workflowValidateConnections,
+    }),
+    shallowEqual
+  );
+  const templatesStatus = useInvocationTemplatesSelector((snapshot) => snapshot.status);
+  const templates = useInvocationTemplatesSelector((snapshot) => snapshot.templates);
+  const invocationTemplates = templatesStatus === 'loaded' ? templates : undefined;
+  const canUseCache = !session.multiuserEnabled || session.user?.is_admin === true;
+  const edgeType: FlowEdgeType = workflowEdgeStyle === 'square' ? 'step' : 'default';
+  const isLargeGraph = isLargeWorkflowGraph({
+    edgeCount: projectGraph.edges.length,
+    nodeCount: projectGraph.nodes.length,
+  });
+  const viewportKey = useMemo(
+    () => getWorkflowViewportKey(projectId, runtime.instanceId),
+    [projectId, runtime.instanceId]
+  );
+  const perfSource = useMemo<DiagnosticSource>(
+    () => ({
+      instanceId: runtime.instanceId,
+      kind: 'widget',
+      projectId,
+      region: runtime.region,
+      typeId: runtime.typeId,
+    }),
+    [projectId, runtime.instanceId, runtime.region, runtime.typeId]
+  );
+  const defaultViewport = useMemo(() => getWorkflowViewport(viewportKey) ?? DEFAULT_VIEWPORT, [viewportKey]);
+  const [flowModel, setFlowModel] = useState<WorkflowFlowModel | null>(() =>
+    isLargeGraph
+      ? null
+      : buildWorkflowFlowModel({
+          canUseCache,
+          document: projectGraph,
+          edgeType,
+          invocationTemplates,
+          isCompact: isLargeGraph,
+          perfSource,
+          reduceMotion,
+        })
+  );
+  const flowNodes = flowModel?.nodes ?? EMPTY_FLOW_NODES;
+  const flowEdges = flowModel?.edges ?? EMPTY_FLOW_EDGES;
+  const isPreparing = flowModel === null;
+  const shouldDeferInitialBuild = isLargeGraph && flowModel === null;
+  const [flowInstance, setFlowInstance] = useState<WorkflowFlowInstance | null>(null);
+  const [isFullGraphMounted, setIsFullGraphMounted] = useState(!isLargeGraph);
+  const [tool, setTool] = useState<EditorTool>('pan');
+  const [nodeOpacity, setNodeOpacity] = useState(1);
+  const [isMinimapReady, setIsMinimapReady] = useState(!isLargeGraph);
+  const [contextMenu, setContextMenu] = useState<WorkflowContextMenuState | null>(null);
+  const selectedNodeIds = workflowSelectionStore.useSelector((snapshot) => snapshot.selectedNodeIds);
+  const selectionRequest = workflowSelectionStore.useSelector((snapshot) => snapshot.selectionRequest);
+  const isSnapHeld = useModifierHeld('Control');
+  const hasClipboardNodes = useHasClipboardNodes();
+  const backgroundId = useId().replace(/:/g, '');
+  const perfMountMarkRef = useRef(`workflow:${runtime.instanceId}:editor-mounted`);
+  const perfReadyMarkRef = useRef(`workflow:${runtime.instanceId}:editor-ready`);
+  const hasScheduledFullGraphMountRef = useRef(false);
+  /** Node ids to select once the next document-driven rebuild lands (fresh paste/duplicate results). */
+  const pendingSelectionRef = useRef<string[] | null>(null);
+  const lastBuiltModelRef = useRef<{
+    edgeType: FlowEdgeType;
+    invocationTemplates: typeof invocationTemplates;
+    projectGraph: ProjectGraphState;
+    reduceMotion: boolean;
+    selectedNodeIds: string[];
+  } | null>(null);
+
+  const selectNodes = useCallback(
+    (nodeIds: string[]) => {
+      const selectedNodeIdSet = new Set(nodeIds);
+
+      setFlowModel((current) => {
+        if (!current) {
+          return current;
+        }
+
+        const index = createWorkflowGraphIndex(projectGraph.nodes, projectGraph.edges);
+
+        return {
+          edges: toFlowEdges(
+            projectGraph,
+            current.edges,
+            edgeType,
+            selectedNodeIdSet,
+            invocationTemplates,
+            reduceMotion,
+            index
+          ),
+          nodes: withNodeSelection(current.nodes, selectedNodeIdSet),
+        };
+      });
+      reportNodeSelection(nodeIds);
+    },
+    [edgeType, invocationTemplates, projectGraph, reduceMotion]
+  );
+
+  const { lassoHandlers, lassoOverlay } = useLasso({
+    enabled: tool === 'lasso',
+    flowInstance,
+    onSelect: selectNodes,
+  });
+  const eraseElements = useCallback(
+    ({ edgeIds, nodeIds }: { edgeIds: string[]; nodeIds: string[] }) => {
+      const requestedNodeIds = new Set(nodeIds);
+      const existingNodeIds = projectGraph.nodes.filter((node) => requestedNodeIds.has(node.id)).map((node) => node.id);
+
+      if (existingNodeIds.length > 0) {
+        dispatch({ action: { nodeIds: existingNodeIds, type: 'removeNodes' }, type: 'applyProjectGraphAction' });
+      }
+
+      const removedNodeIds = new Set(existingNodeIds);
+      const requestedEdgeIds = new Set(edgeIds);
+      const existingEdgeIds = projectGraph.edges
+        .filter(
+          (edge) =>
+            requestedEdgeIds.has(edge.id) && !removedNodeIds.has(edge.source) && !removedNodeIds.has(edge.target)
+        )
+        .map((edge) => edge.id);
+
+      if (existingEdgeIds.length > 0) {
+        dispatch({ action: { edgeIds: existingEdgeIds, type: 'removeEdges' }, type: 'applyProjectGraphAction' });
+      }
+    },
+    [dispatch, projectGraph.edges, projectGraph.nodes]
+  );
+  const { eraserHandlers, eraserOverlay } = useEraser({
+    enabled: tool === 'eraser',
+    flowInstance,
+    onErase: eraseElements,
+  });
+  const pointerToolHandlers = tool === 'lasso' ? lassoHandlers : tool === 'eraser' ? eraserHandlers : {};
+  const renderedFlowModel = useMemo(
+    () =>
+      flowModel && isLargeGraph && !isFullGraphMounted
+        ? getInitialRenderFlowModel(flowModel, defaultViewport)
+        : flowModel,
+    [defaultViewport, flowModel, isFullGraphMounted, isLargeGraph]
+  );
+  const renderedFlowNodes = renderedFlowModel?.nodes ?? EMPTY_FLOW_NODES;
+  const renderedFlowEdges = renderedFlowModel?.edges ?? EMPTY_FLOW_EDGES;
+
+  useEffect(() => {
+    hasScheduledFullGraphMountRef.current = false;
+    setIsFullGraphMounted(!isLargeGraph);
+  }, [isLargeGraph, projectId]);
+
+  useEffect(() => {
+    markWorkbenchPerf(perfMountMarkRef.current, perfSource);
+  }, [perfSource]);
+
+  useEffect(() => {
+    if (isPreparing) {
+      return;
+    }
+
+    markWorkbenchPerf(perfReadyMarkRef.current, perfSource);
+    measureWorkbenchPerf(
+      'workflow:editor-mounted-to-ready',
+      perfMountMarkRef.current,
+      perfSource,
+      perfReadyMarkRef.current
+    );
+  }, [isPreparing, perfSource]);
+
+  useEffect(() => {
+    if (!isFullGraphMounted || !isLargeGraph) {
+      return;
+    }
+
+    markWorkbenchPerf('workflow:full-graph-mounted', perfSource);
+    measureWorkbenchPerf(
+      'workflow:full-graph-expand',
+      'workflow:full-graph-expand-start',
+      perfSource,
+      'workflow:full-graph-mounted'
+    );
+  }, [isFullGraphMounted, isLargeGraph, perfSource]);
+
+  useEffect(() => {
+    if (!workflowShowMinimap) {
+      setIsMinimapReady(false);
+      return undefined;
+    }
+
+    if (!isLargeGraph) {
+      setIsMinimapReady(true);
+      return undefined;
+    }
+
+    setIsMinimapReady(false);
+
+    if (isPreparing) {
+      return undefined;
+    }
+
+    const timeoutId = window.setTimeout(() => {
+      markWorkbenchPerf('workflow:minimap-ready', perfSource);
+      setIsMinimapReady(true);
+    }, WORKFLOW_MINIMAP_DELAY_MS);
+
+    return () => window.clearTimeout(timeoutId);
+  }, [isLargeGraph, isPreparing, perfSource, workflowShowMinimap]);
+
+  useEffect(() => {
+    const pendingSelection = pendingSelectionRef.current;
+
+    pendingSelectionRef.current = null;
+    const nextSelectedNodeIds = pendingSelection ?? selectedNodeIds;
+    const nextSelectedNodeIdSet = new Set(nextSelectedNodeIds);
+    let frameId: number | null = null;
+
+    const lastBuiltModel = lastBuiltModelRef.current;
+
+    if (
+      pendingSelection === null &&
+      !shouldDeferInitialBuild &&
+      lastBuiltModel?.projectGraph === projectGraph &&
+      lastBuiltModel.edgeType === edgeType &&
+      lastBuiltModel.invocationTemplates === invocationTemplates &&
+      lastBuiltModel.reduceMotion === reduceMotion &&
+      lastBuiltModel.selectedNodeIds === nextSelectedNodeIds
+    ) {
+      return undefined;
+    }
+
+    const updateModel = () => {
+      lastBuiltModelRef.current = {
+        edgeType,
+        invocationTemplates,
+        projectGraph,
+        reduceMotion,
+        selectedNodeIds: nextSelectedNodeIds,
+      };
+
+      startTransition(() => {
+        setFlowModel((current) => {
+          const next = buildWorkflowFlowModel({
+            document: projectGraph,
+            edgeType,
+            canUseCache,
+            isCompact: isLargeGraph,
+            invocationTemplates,
+            perfSource,
+            previousEdges: current?.edges,
+            previousNodes: current?.nodes,
+            reduceMotion,
+            selectedNodeIds: nextSelectedNodeIdSet,
+          });
+
+          return { ...next, nodes: withNodeSelection(next.nodes, nextSelectedNodeIdSet) };
+        });
+      });
+    };
+
+    if (shouldDeferInitialBuild) {
+      frameId = window.requestAnimationFrame(updateModel);
+    } else {
+      updateModel();
+    }
+
+    if (pendingSelection) {
+      reportNodeSelection(pendingSelection);
+    }
+
+    return () => {
+      if (frameId !== null) {
+        window.cancelAnimationFrame(frameId);
+      }
+    };
+  }, [
+    canUseCache,
+    edgeType,
+    invocationTemplates,
+    isLargeGraph,
+    perfSource,
+    projectGraph,
+    reduceMotion,
+    selectedNodeIds,
+    shouldDeferInitialBuild,
+  ]);
+
+  // Expose the instance to the widget header's actions (outside this provider).
+  useEffect(() => {
+    if (!flowInstance) {
+      return undefined;
+    }
+
+    registerWorkflowFlowInstance(flowInstance);
+
+    return () => {
+      releaseWorkflowFlowInstance(flowInstance);
+    };
+  }, [flowInstance]);
+
+  // Outside surfaces (the form builder's zoom-to-node) request a selection;
+  // the editor applies it and brings the nodes into view.
+  useEffect(() => {
+    if (!selectionRequest || !flowInstance) {
+      return;
+    }
+
+    selectNodes(selectionRequest.nodeIds);
+    void flowInstance.fitView({
+      duration: reduceMotion ? 0 : 300,
+      maxZoom: 1.25,
+      nodes: selectionRequest.nodeIds.map((id) => ({ id })),
+    });
+    clearNodeSelectionRequest();
+  }, [flowInstance, reduceMotion, selectNodes, selectionRequest]);
+
+  /** The context-menu node acts alone unless it is part of the current selection. */
+  const getActionNodeIds = useCallback(
+    (nodeId?: string): string[] => {
+      const selectedIds = flowNodes.filter((node) => node.selected).map((node) => node.id);
+
+      if (nodeId && !selectedIds.includes(nodeId)) {
+        return [nodeId];
+      }
+
+      return selectedIds;
+    },
+    [flowNodes]
+  );
+
+  const copyNodes = useCallback(
+    (nodeId?: string) => {
+      const copiedCount = copyNodesToClipboard(projectGraph, getActionNodeIds(nodeId));
+
+      if (copiedCount > 0) {
+        notify.success(`Copied ${copiedCount} node${copiedCount === 1 ? '' : 's'}`);
+      }
+    },
+    [getActionNodeIds, notify, projectGraph]
+  );
+
+  const pasteNodes = useCallback(() => {
+    const { edges, nodes } = buildPasteElements();
+
+    if (nodes.length === 0) {
+      return;
+    }
+
+    pendingSelectionRef.current = nodes.map((node) => node.id);
+    dispatch({ action: { edges, nodes, type: 'addGraphElements' }, type: 'applyProjectGraphAction' });
+  }, [dispatch]);
+
+  const duplicateNodes = useCallback(
+    (nodeId?: string) => {
+      const { edges, nodes } = buildDuplicateElements(projectGraph, getActionNodeIds(nodeId));
+
+      if (nodes.length === 0) {
+        return;
+      }
+
+      pendingSelectionRef.current = nodes.map((node) => node.id);
+      dispatch({ action: { edges, nodes, type: 'addGraphElements' }, type: 'applyProjectGraphAction' });
+    },
+    [dispatch, getActionNodeIds, projectGraph]
+  );
+
+  const deleteNodes = useCallback(
+    (nodeId?: string) => {
+      const nodeIds = getActionNodeIds(nodeId);
+
+      if (nodeIds.length > 0) {
+        dispatch({ action: { nodeIds, type: 'removeNodes' }, type: 'applyProjectGraphAction' });
+      }
+    },
+    [dispatch, getActionNodeIds]
+  );
+
+  const addConnector = useCallback(
+    (position: XYPosition) => {
+      dispatch({ action: { node: buildConnectorNode(position), type: 'addNode' }, type: 'applyProjectGraphAction' });
+    },
+    [dispatch]
+  );
+
+  const selectAll = () => {
+    selectNodes(projectGraph.nodes.map((node) => node.id));
+  };
+
+  const deleteSelection = () => {
+    const nodeIds = flowNodes.filter((node) => node.selected).map((node) => node.id);
+    const edgeIds = flowEdges.filter((edge) => edge.selected).map((edge) => edge.id);
+
+    if (nodeIds.length > 0) {
+      dispatch({ action: { nodeIds, type: 'removeNodes' }, type: 'applyProjectGraphAction' });
+    }
+
+    if (edgeIds.length > 0) {
+      dispatch({ action: { edgeIds, type: 'removeEdges' }, type: 'applyProjectGraphAction' });
+    }
+  };
+
+  const executeWorkflowHotkey = useEffectEvent((commandId: string) => {
+    switch (commandId) {
+      case 'workflows.addNode': {
+        setAddNodeOpen(true);
+        return;
+      }
+      case 'workflows.copySelection': {
+        copyNodes();
+        return;
+      }
+      case 'workflows.pasteSelection':
+      case 'workflows.pasteSelectionWithEdges': {
+        pasteNodes();
+        return;
+      }
+      case 'workflows.duplicateSelection': {
+        duplicateNodes();
+        return;
+      }
+      case 'workflows.selectAll': {
+        selectAll();
+        return;
+      }
+      case 'workflows.deleteSelection': {
+        deleteSelection();
+        return;
+      }
+      case 'workflows.undo': {
+        dispatch({ type: 'undoProjectChange' });
+        return;
+      }
+      case 'workflows.redo': {
+        dispatch({ type: 'redoProjectChange' });
+        return;
+      }
+    }
+  });
+
+  useEffect(() => {
+    const hotkeys = [
+      ['workflows.addNode', 'Add workflow node', ['shift+a', 'space']],
+      ['workflows.copySelection', 'Copy workflow selection', ['mod+c']],
+      ['workflows.pasteSelection', 'Paste workflow selection', ['mod+v']],
+      ['workflows.pasteSelectionWithEdges', 'Paste workflow selection with edges', ['mod+shift+v']],
+      ['workflows.duplicateSelection', 'Duplicate workflow selection', ['mod+d']],
+      ['workflows.selectAll', 'Select all workflow nodes', ['mod+a']],
+      ['workflows.deleteSelection', 'Delete workflow selection', ['delete', 'backspace']],
+      ['workflows.undo', 'Undo workflow edit', ['mod+z']],
+      ['workflows.redo', 'Redo workflow edit', ['mod+shift+z', 'mod+y']],
+    ] as const;
+    const disposers = hotkeys.flatMap(([id, title, defaultKeys]) => [
+      runtime.commands.register({ handler: () => executeWorkflowHotkey(id), id, title }),
+      runtime.hotkeys.register({ commandId: id, defaultKeys: [...defaultKeys], id, title }),
+    ]);
+
+    return () => {
+      disposers.forEach((dispose) => dispose());
+    };
+  }, [runtime.commands, runtime.hotkeys]);
+
+  const onNodesChange = useCallback(
+    (changes: NodeChange<WorkflowFlowNode>[]) => {
+      const removedNodeIds = changes.flatMap((change) => (change.type === 'remove' ? [change.id] : []));
+
+      if (removedNodeIds.length > 0) {
+        dispatch({ action: { nodeIds: removedNodeIds, type: 'removeNodes' }, type: 'applyProjectGraphAction' });
+      }
+
+      for (const change of changes) {
+        if (change.type === 'position' && change.dragging === false && change.position) {
+          dispatch({
+            action: { nodeId: change.id, position: change.position, type: 'setNodePosition' },
+            type: 'applyProjectGraphAction',
+          });
+        }
+      }
+
+      setFlowModel((current) => (current ? { ...current, nodes: applyNodeChanges(changes, current.nodes) } : current));
+    },
+    [dispatch]
+  );
+
+  const onEdgesChange = useCallback(
+    (changes: EdgeChange<WorkflowFlowEdge>[]) => {
+      const removedEdgeIds = changes.flatMap((change) => (change.type === 'remove' ? [change.id] : []));
+
+      if (removedEdgeIds.length > 0) {
+        dispatch({ action: { edgeIds: removedEdgeIds, type: 'removeEdges' }, type: 'applyProjectGraphAction' });
+      }
+
+      setFlowModel((current) => (current ? { ...current, edges: applyEdgeChanges(changes, current.edges) } : current));
+    },
+    [dispatch]
+  );
+
+  const isValidConnection: IsValidConnection<WorkflowFlowEdge> = useCallback(
+    (connection) => {
+      if (!connection.sourceHandle || !connection.targetHandle) {
+        return false;
+      }
+
+      // Lenient wiring: the user opted out of type validation in settings.
+      if (!workflowValidateConnections) {
+        return true;
+      }
+
+      return (
+        validateConnection(
+          {
+            sourceHandle: connection.sourceHandle,
+            sourceNodeId: connection.source,
+            targetHandle: connection.targetHandle,
+            targetNodeId: connection.target,
+          },
+          projectGraph,
+          templates
+        ) === null
+      );
+    },
+    [projectGraph, templates, workflowValidateConnections]
+  );
+
+  const onConnect = useCallback(
+    (connection: Connection) => {
+      if (!connection.sourceHandle || !connection.targetHandle) {
+        return;
+      }
+
+      dispatch({
+        action: {
+          edge: {
+            id: createWorkflowId('edge'),
+            source: connection.source,
+            sourceHandle: connection.sourceHandle,
+            target: connection.target,
+            targetHandle: connection.targetHandle,
+            type: 'default',
+          },
+          type: 'addEdge',
+        },
+        type: 'applyProjectGraphAction',
+      });
+    },
+    [dispatch]
+  );
+
+  const onConnectEnd = useCallback<OnConnectEnd>(
+    (event, connectionState) => {
+      if (!flowInstance || !(event.target instanceof Element) || !event.target.closest('.react-flow__pane')) {
+        return;
+      }
+
+      if (connectionState.isValid || connectionState.toHandle || connectionState.toNode) {
+        return;
+      }
+
+      const handle = connectionState.fromHandle;
+      const handleId = handle?.id;
+      const nodeId = handle?.nodeId ?? connectionState.fromNode?.id;
+
+      if (!handleId || !nodeId) {
+        return;
+      }
+
+      const position = getEventClientPosition(event);
+
+      if (!position) {
+        return;
+      }
+
+      if (handle.type === 'source') {
+        const sourceType = getWorkflowSourceFieldType(projectGraph, templates, nodeId, handleId);
+
+        if (sourceType === undefined) {
+          return;
+        }
+
+        setAddNodeOpen(true, flowInstance.screenToFlowPosition(position), {
+          kind: 'source',
+          sourceHandle: handleId,
+          sourceNodeId: nodeId,
+          sourceType,
+        });
+        return;
+      }
+
+      if (handle.type === 'target') {
+        const targetType = getWorkflowTargetFieldType(projectGraph, templates, nodeId, handleId);
+
+        if (targetType === undefined) {
+          return;
+        }
+
+        setAddNodeOpen(true, flowInstance.screenToFlowPosition(position), {
+          kind: 'target',
+          targetHandle: handleId,
+          targetNodeId: nodeId,
+          targetType,
+        });
+      }
+    },
+    [flowInstance, projectGraph, templates]
+  );
+
+  const onNodeContextMenu = useCallback((event: ReactMouseEvent, node: WorkflowFlowNode) => {
+    event.preventDefault();
+    setContextMenu({
+      kind: 'node',
+      isNodeOpen: node.type === 'invocation' ? node.data.documentNode.data.isOpen : null,
+      nodeId: node.id,
+      x: event.clientX,
+      y: event.clientY,
+    });
+  }, []);
+
+  const onPaneContextMenu = useCallback(
+    (event: ReactMouseEvent | globalThis.MouseEvent) => {
+      if (!flowInstance) {
+        return;
+      }
+
+      event.preventDefault();
+      if (
+        event.target instanceof Element &&
+        event.target.closest('.react-flow__nodesselection') &&
+        getActionNodeIds().length > 0
+      ) {
+        setContextMenu({
+          kind: 'node',
+          isNodeOpen: null,
+          x: event.clientX,
+          y: event.clientY,
+        });
+        return;
+      }
+
+      setContextMenu({
+        kind: 'pane',
+        position: flowInstance.screenToFlowPosition({ x: event.clientX, y: event.clientY }),
+        x: event.clientX,
+        y: event.clientY,
+      });
+    },
+    [flowInstance, getActionNodeIds]
+  );
+
+  const onEditorContextMenuCapture = useCallback(
+    (event: ReactMouseEvent<HTMLDivElement>) => {
+      if (
+        event.target instanceof Element &&
+        event.target.closest('.react-flow__nodesselection') &&
+        getActionNodeIds().length > 0
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        setContextMenu({
+          kind: 'node',
+          isNodeOpen: null,
+          x: event.clientX,
+          y: event.clientY,
+        });
+      }
+    },
+    [getActionNodeIds]
+  );
+
+  const onNodeClick = useCallback(
+    (_: ReactMouseEvent, node: WorkflowFlowNode) => {
+      if (tool === 'eraser') {
+        eraseElements({ edgeIds: [], nodeIds: [node.id] });
+      }
+    },
+    [eraseElements, tool]
+  );
+
+  const onEdgeClick = useCallback(
+    (_: ReactMouseEvent, edge: WorkflowFlowEdge) => {
+      if (tool === 'eraser') {
+        eraseElements({ edgeIds: [edge.id], nodeIds: [] });
+      }
+    },
+    [eraseElements, tool]
+  );
+
+  const onSelectionChange = useCallback(
+    ({ nodes }: { nodes: WorkflowFlowNode[] }) => {
+      const nodeIds = nodes.map((node) => node.id);
+
+      setFlowModel((current) => {
+        if (!current) {
+          return current;
+        }
+
+        const index = createWorkflowGraphIndex(projectGraph.nodes, projectGraph.edges);
+
+        return {
+          ...current,
+          edges: toFlowEdges(
+            projectGraph,
+            current.edges,
+            edgeType,
+            getSelectedNodeIdSet(nodes),
+            invocationTemplates,
+            reduceMotion,
+            index
+          ),
+        };
+      });
+      reportNodeSelection(nodeIds);
+    },
+    [edgeType, invocationTemplates, projectGraph, reduceMotion]
+  );
+
+  const onNodeMouseEnter = useCallback((_: ReactMouseEvent, node: WorkflowFlowNode) => {
+    reportNodeHover(node.id);
+  }, []);
+
+  const onNodeMouseLeave = useCallback((_: ReactMouseEvent, node: WorkflowFlowNode) => {
+    if (workflowSelectionStore.getSnapshot().hoveredNodeId === node.id) {
+      reportNodeHover(null);
+    }
+  }, []);
+  const onMoveEnd = useCallback(
+    (_: MouseEvent | TouchEvent | null, viewport: Viewport) => {
+      setWorkflowViewport(viewportKey, viewport);
+    },
+    [viewportKey]
+  );
+  const onFlowInit = useCallback(
+    (instance: WorkflowFlowInstance) => {
+      const flowInitMark = 'workflow:react-flow-init';
+
+      markWorkbenchPerf(flowInitMark, perfSource);
+      measureWorkbenchPerf(
+        'workflow:editor-ready-to-react-flow-init',
+        perfReadyMarkRef.current,
+        perfSource,
+        flowInitMark
+      );
+      measureWorkbenchPerf(
+        'workflow:editor-mounted-to-react-flow-init',
+        perfMountMarkRef.current,
+        perfSource,
+        flowInitMark
+      );
+      setFlowInstance(instance);
+
+      if (isLargeGraph && !isFullGraphMounted && !hasScheduledFullGraphMountRef.current) {
+        hasScheduledFullGraphMountRef.current = true;
+
+        window.setTimeout(() => {
+          markWorkbenchPerf('workflow:full-graph-expand-start', perfSource);
+          setIsFullGraphMounted(true);
+        }, 0);
+      }
+    },
+    [isFullGraphMounted, isLargeGraph, perfSource]
+  );
+
+  const editorCss = useMemo(
+    () => ({
+      ...flowThemeCss,
+      '& .react-flow__node': { opacity: nodeOpacity },
+      '& .react-flow__edge .react-flow__edge-path': {
+        opacity: 0.38,
+        transition: 'opacity var(--wb-motion-duration-fast) ease',
+      },
+      '& .react-flow__edge.selected .react-flow__edge-path, & .react-flow__edge.workflow-selected-node-edge .react-flow__edge-path, & .react-flow__edge:hover .react-flow__edge-path':
+        {
+          opacity: 1,
+        },
+      '& .react-flow__edge.workflow-selected-node-edge .react-flow__edge-path': {
+        animation: 'dashdraw var(--wb-motion-duration-slow) linear var(--wb-motion-animation-iteration-count)',
+        strokeDasharray: '5',
+      },
+      ...(tool === 'eraser'
+        ? { '& .react-flow__edge, & .react-flow__node, & .react-flow__pane': { cursor: 'crosshair' } }
+        : {}),
+      ...(tool === 'lasso' ? { '& .react-flow__pane': { cursor: 'crosshair' } } : {}),
+    }),
+    [nodeOpacity, tool]
+  );
+  const panOnDrag = useMemo(() => (tool === 'pan' ? true : [1, 2]), [tool]);
+  const proOptions = useMemo(() => ({ hideAttribution: true }), []);
+  const flowStyle = useMemo(() => ({ background: 'transparent' }), []);
+  const onContextMenuAddConnector = useCallback(
+    (position: XYPosition) => {
+      addConnector(position);
+      setContextMenu(null);
+    },
+    [addConnector]
+  );
+  const onContextMenuClose = useCallback(() => setContextMenu(null), []);
+  const onContextMenuCopy = useCallback(() => {
+    copyNodes(contextMenu?.kind === 'node' ? contextMenu.nodeId : undefined);
+    setContextMenu(null);
+  }, [contextMenu, copyNodes]);
+  const onContextMenuDelete = useCallback(() => {
+    deleteNodes(contextMenu?.kind === 'node' ? contextMenu.nodeId : undefined);
+    setContextMenu(null);
+  }, [contextMenu, deleteNodes]);
+  const onContextMenuDuplicate = useCallback(() => {
+    duplicateNodes(contextMenu?.kind === 'node' ? contextMenu.nodeId : undefined);
+    setContextMenu(null);
+  }, [contextMenu, duplicateNodes]);
+  const onContextMenuPaste = useCallback(() => {
+    pasteNodes();
+    setContextMenu(null);
+  }, [pasteNodes]);
+  const onContextMenuToggleOpen = useCallback(() => {
+    if (contextMenu?.kind === 'node' && contextMenu.nodeId && contextMenu.isNodeOpen !== null) {
+      dispatch({
+        action: { isOpen: !contextMenu.isNodeOpen, nodeId: contextMenu.nodeId, type: 'setNodeIsOpen' },
+        type: 'applyProjectGraphAction',
+      });
+    }
+
+    setContextMenu(null);
+  }, [contextMenu, dispatch]);
+
+  if (isPreparing) {
+    return <WorkflowEditorPreparingState edgeCount={projectGraph.edges.length} nodeCount={projectGraph.nodes.length} />;
+  }
+
+  return (
+    <Box
+      bg="bg.inset"
+      css={editorCss}
+      h="full"
+      position="relative"
+      w="full"
+      onContextMenuCapture={onEditorContextMenuCapture}
+      {...pointerToolHandlers}
+    >
+      <ReactFlow<WorkflowFlowNode, WorkflowFlowEdge>
+        key={viewportKey}
+        colorMode={getFlowColorMode(themeId)}
+        connectionLineType={edgeType === 'step' ? ConnectionLineType.Step : ConnectionLineType.Bezier}
+        defaultEdgeOptions={DEFAULT_EDGE_OPTIONS}
+        defaultViewport={defaultViewport}
+        deleteKeyCode={DELETE_KEY_CODES}
+        elevateEdgesOnSelect
+        edges={renderedFlowEdges}
+        edgeTypes={edgeTypes}
+        isValidConnection={isValidConnection}
+        maxZoom={2}
+        minZoom={0.1}
+        nodes={renderedFlowNodes}
+        nodeTypes={nodeTypes}
+        onlyRenderVisibleElements={isLargeGraph}
+        panOnDrag={panOnDrag}
+        proOptions={proOptions}
+        selectionMode={SelectionMode.Partial}
+        selectionOnDrag={tool === 'box-select'}
+        snapGrid={SNAP_GRID}
+        snapToGrid={workflowSnapToGrid || isSnapHeld}
+        style={flowStyle}
+        onConnect={onConnect}
+        onConnectEnd={onConnectEnd}
+        onEdgeClick={onEdgeClick}
+        onEdgesChange={onEdgesChange}
+        onInit={onFlowInit}
+        onNodeClick={onNodeClick}
+        onNodeContextMenu={onNodeContextMenu}
+        onNodeMouseEnter={onNodeMouseEnter}
+        onNodeMouseLeave={onNodeMouseLeave}
+        onNodesChange={onNodesChange}
+        onMoveEnd={onMoveEnd}
+        onPaneContextMenu={onPaneContextMenu}
+        onSelectionChange={onSelectionChange}
+      >
+        <Background
+          bgColor="var(--xy-background-color)"
+          color="var(--wb-flow-grid)"
+          gap={24}
+          id={`workflow-grid-${backgroundId}`}
+          size={1.5}
+          variant={BackgroundVariant.Dots}
+        />
+        <EditorToolbar
+          nodeOpacity={nodeOpacity}
+          tool={tool}
+          onNodeOpacityChange={setNodeOpacity}
+          onToolChange={setTool}
+        />
+        {workflowShowMinimap && isMinimapReady ? <FlowMiniMap /> : null}
+      </ReactFlow>
+      {lassoOverlay}
+      {eraserOverlay}
+      <NodeContextMenu
+        canPaste={hasClipboardNodes}
+        menuState={contextMenu}
+        onAddConnector={onContextMenuAddConnector}
+        onClose={onContextMenuClose}
+        onCopy={onContextMenuCopy}
+        onDelete={onContextMenuDelete}
+        onDuplicate={onContextMenuDuplicate}
+        onPaste={onContextMenuPaste}
+        onToggleOpen={onContextMenuToggleOpen}
+      />
+    </Box>
+  );
+};
+
+const ReadinessBanner = () => {
+  const projectGraph = useActiveProjectSelector((project) => project.projectGraph);
+  const templatesStatus = useInvocationTemplatesSelector((snapshot) => snapshot.status);
+  const templates = useInvocationTemplatesSelector((snapshot) => snapshot.templates);
+  const templatesSnapshot = useMemo(
+    () => ({ error: null, status: templatesStatus, templates }),
+    [templatesStatus, templates]
+  );
+  const readiness = useMemo(
+    () => getProjectGraphReadiness(projectGraph, templatesSnapshot),
+    [projectGraph, templatesSnapshot]
+  );
+
+  if (readiness.canInvoke || projectGraph.nodes.length === 0) {
+    return null;
+  }
+
+  return (
+    <Box
+      bg="bg.muted"
+      borderColor="border.subtle"
+      borderRadius="md"
+      borderWidth="1px"
+      left="3"
+      maxW="24rem"
+      p="2"
+      position="absolute"
+      top="3"
+      zIndex="1"
+    >
+      <Stack gap="0.5">
+        {readiness.reasons.slice(0, 4).map((reason, index) => (
+          <Text key={`${index}:${reason}`} color="fg.muted" fontSize="2xs">
+            {reason}
+          </Text>
+        ))}
+        {readiness.reasons.length > 4 ? (
+          <Text color="fg.subtle" fontSize="2xs">
+            +{readiness.reasons.length - 4} more
+          </Text>
+        ) : null}
+      </Stack>
+    </Box>
+  );
+};
+
+export const WorkflowEditorView = ({ runtime }: { runtime: WidgetRuntimeApi }) => {
+  useEffect(() => {
+    ensureInvocationTemplatesLoaded();
+  }, []);
+
+  return (
+    <ReactFlowProvider>
+      <Flex direction="column" h="full" minH="0" w="full">
+        <Box flex="1" minH="0" position="relative">
+          <WorkflowFlow runtime={runtime} />
+          <ReadinessBanner />
+        </Box>
+      </Flex>
+    </ReactFlowProvider>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/clipboard.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/clipboard.test.ts
new file mode 100644
index 00000000000..68074158317
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/clipboard.test.ts
@@ -0,0 +1,101 @@
+import type { ProjectGraphState, WorkflowEdge, WorkflowInvocationNode } from '@workbench/workflows/types';
+
+import { createProjectGraph } from '@workbench/workflows/document';
+import { describe, expect, it } from 'vitest';
+
+import { buildDuplicateElements, buildPasteElements, copyNodesToClipboard, hasClipboardNodes } from './clipboard';
+
+const createNode = (id: string, x: number, y: number): WorkflowInvocationNode => ({
+  data: {
+    inputs: { a: { label: '', name: 'a', value: 1 } },
+    isIntermediate: true,
+    isOpen: true,
+    label: '',
+    nodePack: 'invokeai',
+    notes: '',
+    type: 'add',
+    useCache: true,
+    version: '1.0.0',
+  },
+  id,
+  position: { x, y },
+  type: 'invocation',
+});
+
+const createEdge = (id: string, source: string, target: string): WorkflowEdge => ({
+  id,
+  source,
+  sourceHandle: 'value',
+  target,
+  targetHandle: 'a',
+  type: 'default',
+});
+
+const createDoc = (): ProjectGraphState => ({
+  ...createProjectGraph('clipboard-test'),
+  edges: [createEdge('edge-1', 'node-a', 'node-b'), createEdge('edge-2', 'node-outside', 'node-a')],
+  nodes: [createNode('node-a', 0, 0), createNode('node-b', 100, 50), createNode('node-outside', -200, 0)],
+});
+
+describe('workflow clipboard', () => {
+  it('copies selected nodes with only their internal edges', () => {
+    const copiedCount = copyNodesToClipboard(createDoc(), ['node-a', 'node-b']);
+
+    expect(copiedCount).toBe(2);
+    expect(hasClipboardNodes()).toBe(true);
+
+    const { edges, nodes } = buildPasteElements();
+
+    expect(nodes).toHaveLength(2);
+    // The edge from node-outside is not part of the copied set.
+    expect(edges).toHaveLength(1);
+  });
+
+  it('pastes with fresh ids, remapped edges, and offset positions', () => {
+    copyNodesToClipboard(createDoc(), ['node-a', 'node-b']);
+
+    const { edges, nodes } = buildPasteElements();
+    const pastedIds = new Set(nodes.map((node) => node.id));
+
+    expect(pastedIds.has('node-a')).toBe(false);
+    expect(pastedIds.has('node-b')).toBe(false);
+    expect(edges[0]?.id).not.toBe('edge-1');
+    expect(pastedIds.has(edges[0]?.source ?? '')).toBe(true);
+    expect(pastedIds.has(edges[0]?.target ?? '')).toBe(true);
+    expect(nodes[0]?.position).toEqual({ x: 32, y: 32 });
+
+    // Pasting twice yields fresh ids each time.
+    const second = buildPasteElements();
+
+    expect(second.nodes.every((node) => !pastedIds.has(node.id))).toBe(true);
+  });
+
+  it('anchors the pasted group on an explicit position, preserving relative layout', () => {
+    copyNodesToClipboard(createDoc(), ['node-a', 'node-b']);
+
+    const { nodes } = buildPasteElements({ x: 500, y: 500 });
+
+    expect(nodes.map((node) => node.position)).toEqual([
+      { x: 500, y: 500 },
+      { x: 600, y: 550 },
+    ]);
+  });
+
+  it('duplicates in place without touching the clipboard', () => {
+    copyNodesToClipboard(createDoc(), ['node-a']);
+
+    const { edges, nodes } = buildDuplicateElements(createDoc(), ['node-a', 'node-b']);
+
+    expect(nodes).toHaveLength(2);
+    expect(edges).toHaveLength(1);
+    // The clipboard still holds the single copied node.
+    expect(buildPasteElements().nodes).toHaveLength(1);
+  });
+
+  it('copying nothing leaves the clipboard untouched', () => {
+    copyNodesToClipboard(createDoc(), ['node-a']);
+
+    expect(copyNodesToClipboard(createDoc(), ['missing-node'])).toBe(0);
+    expect(buildPasteElements().nodes).toHaveLength(1);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/clipboard.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/clipboard.ts
new file mode 100644
index 00000000000..fb85dc4f72d
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/clipboard.ts
@@ -0,0 +1,102 @@
+import type { ProjectGraphState, WorkflowEdge, WorkflowNode, XYPosition } from '@workbench/workflows/types';
+
+import { createExternalStore } from '@workbench/externalStore';
+import { createWorkflowId } from '@workbench/workflows/document';
+
+/**
+ * Session-lived clipboard for workflow nodes. Copies hold deep clones of the
+ * selected nodes plus the edges that connect them to each other; pasting
+ * materializes fresh ids (remapping those internal edges) so a payload can be
+ * pasted repeatedly. Deliberately not the system clipboard: node fragments are
+ * not a valid workflow JSON, so a partial graph on the OS clipboard would only
+ * masquerade as an importable document.
+ */
+
+interface WorkflowClipboardSnapshot {
+  nodes: WorkflowNode[];
+  edges: WorkflowEdge[];
+}
+
+const clipboardStore = createExternalStore<WorkflowClipboardSnapshot>({ edges: [], nodes: [] });
+
+const PASTE_OFFSET = 32;
+
+export const copyNodesToClipboard = (document: ProjectGraphState, nodeIds: string[]): number => {
+  const copiedIds = new Set(nodeIds);
+  const nodes = document.nodes.filter((node) => copiedIds.has(node.id));
+
+  if (nodes.length === 0) {
+    return 0;
+  }
+
+  const edges = document.edges.filter((edge) => copiedIds.has(edge.source) && copiedIds.has(edge.target));
+
+  clipboardStore.setSnapshot(structuredClone({ edges, nodes }));
+
+  return nodes.length;
+};
+
+export const hasClipboardNodes = (): boolean => clipboardStore.getSnapshot().nodes.length > 0;
+
+export const useHasClipboardNodes = (): boolean => clipboardStore.useSelector((snapshot) => snapshot.nodes.length > 0);
+
+const materializeElements = (
+  payload: WorkflowClipboardSnapshot,
+  at?: XYPosition
+): { nodes: WorkflowNode[]; edges: WorkflowEdge[] } => {
+  const { edges, nodes } = structuredClone(payload);
+
+  if (nodes.length === 0) {
+    return { edges: [], nodes: [] };
+  }
+
+  const idMap = new Map<string, string>();
+
+  for (const node of nodes) {
+    idMap.set(node.id, createWorkflowId(node.type === 'invocation' ? node.data.type : node.type));
+  }
+
+  let offset: XYPosition = { x: PASTE_OFFSET, y: PASTE_OFFSET };
+
+  if (at) {
+    const minX = Math.min(...nodes.map((node) => node.position.x));
+    const minY = Math.min(...nodes.map((node) => node.position.y));
+
+    offset = { x: at.x - minX, y: at.y - minY };
+  }
+
+  return {
+    edges: edges.map((edge) => ({
+      ...edge,
+      id: createWorkflowId('edge'),
+      source: idMap.get(edge.source) ?? edge.source,
+      target: idMap.get(edge.target) ?? edge.target,
+    })),
+    nodes: nodes.map((node) => ({
+      ...node,
+      id: idMap.get(node.id) ?? node.id,
+      position: { x: node.position.x + offset.x, y: node.position.y + offset.y },
+    })),
+  };
+};
+
+/**
+ * Materializes the clipboard into paste-ready elements with fresh ids.
+ * Positions shift by a fixed offset from the copied originals (or anchor the
+ * group's top-left on `at` when given) so pastes do not stack on their source.
+ */
+export const buildPasteElements = (at?: XYPosition): { nodes: WorkflowNode[]; edges: WorkflowEdge[] } =>
+  materializeElements(clipboardStore.getSnapshot(), at);
+
+/** Clone-in-place for the given nodes (and their internal edges) without touching the clipboard. */
+export const buildDuplicateElements = (
+  document: ProjectGraphState,
+  nodeIds: string[]
+): { nodes: WorkflowNode[]; edges: WorkflowEdge[] } => {
+  const copiedIds = new Set(nodeIds);
+
+  return materializeElements({
+    edges: document.edges.filter((edge) => copiedIds.has(edge.source) && copiedIds.has(edge.target)),
+    nodes: document.nodes.filter((node) => copiedIds.has(node.id)),
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowAdapters.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowAdapters.test.ts
new file mode 100644
index 00000000000..3616f91ae34
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowAdapters.test.ts
@@ -0,0 +1,335 @@
+import type {
+  FieldType,
+  InvocationTemplate,
+  InvocationTemplates,
+  ProjectGraphState,
+  WorkflowConnectorNode,
+  WorkflowEdge,
+  WorkflowInvocationNode,
+} from '@workbench/workflows/types';
+
+import { CONNECTOR_INPUT_HANDLE, CONNECTOR_OUTPUT_HANDLE } from '@workbench/workflows/connectors';
+import { buildCurrentImageNode, createProjectGraph } from '@workbench/workflows/document';
+import { describe, expect, it } from 'vitest';
+
+import { getWorkflowEdgeData, toFlowEdges, toFlowNodes, withNodeSelection } from './flowAdapters';
+
+const single = (name: string): FieldType => ({ batch: false, cardinality: 'SINGLE', name });
+const collection = (name: string): FieldType => ({ batch: false, cardinality: 'COLLECTION', name });
+
+const createTemplate = (outputType: FieldType = single('IntegerField')): InvocationTemplate => ({
+  category: 'test',
+  classification: 'stable',
+  description: '',
+  inputs: {
+    a: {
+      default: undefined,
+      description: '',
+      exclusiveMaximum: null,
+      exclusiveMinimum: null,
+      input: 'any',
+      maximum: null,
+      minimum: null,
+      multipleOf: null,
+      name: 'a',
+      options: null,
+      required: true,
+      title: 'A',
+      type: outputType,
+      uiChoiceLabels: null,
+      uiComponent: null,
+      uiHidden: false,
+      uiModelBase: null,
+      uiModelType: null,
+      uiOrder: null,
+    },
+  },
+  nodePack: 'invokeai',
+  outputType: 'test',
+  outputs: {
+    value: { description: '', name: 'value', title: 'Value', type: outputType },
+  },
+  tags: [],
+  title: 'Add',
+  type: 'add',
+  useCache: true,
+  version: '1.0.0',
+});
+
+const createTemplates = (outputType?: FieldType): InvocationTemplates => ({ add: createTemplate(outputType) });
+
+const createNode = (id: string): WorkflowInvocationNode => ({
+  data: {
+    inputs: {},
+    isIntermediate: true,
+    isOpen: true,
+    label: '',
+    nodePack: 'invokeai',
+    notes: '',
+    type: 'add',
+    useCache: true,
+    version: '1.0.0',
+  },
+  id,
+  position: { x: 0, y: 0 },
+  type: 'invocation',
+});
+
+const createEdge = (
+  id: string,
+  source: string,
+  target: string,
+  sourceHandle = 'value',
+  targetHandle = 'a'
+): WorkflowEdge => ({
+  id,
+  source,
+  sourceHandle,
+  target,
+  targetHandle,
+  type: 'default',
+});
+
+const createConnector = (id: string): WorkflowConnectorNode => ({
+  data: { label: '' },
+  id,
+  position: { x: 0, y: 0 },
+  type: 'connector',
+});
+
+const createDoc = (overrides?: Partial<ProjectGraphState>): ProjectGraphState => ({
+  ...createProjectGraph('adapters-test'),
+  edges: [createEdge('e1', 'a', 'b')],
+  nodes: [createNode('a'), createNode('b')],
+  ...overrides,
+});
+
+describe('flowAdapters identity preservation', () => {
+  it('reuses unchanged node objects across rebuilds (memo-friendly)', () => {
+    const doc = createDoc();
+    const first = toFlowNodes(doc);
+    const second = toFlowNodes(doc, first);
+
+    expect(second[0]).toBe(first[0]);
+    expect(second[1]).toBe(first[1]);
+  });
+
+  it('replaces only the node whose document node changed', () => {
+    const doc = createDoc();
+    const first = toFlowNodes(doc);
+    const movedNodeB = { ...doc.nodes[1]!, position: { x: 50, y: 50 } };
+    const second = toFlowNodes({ ...doc, nodes: [doc.nodes[0]!, movedNodeB] }, first);
+
+    expect(second[0]).toBe(first[0]);
+    expect(second[1]).not.toBe(first[1]);
+  });
+
+  it('recomputes a node when its incoming connections change', () => {
+    const doc = createDoc();
+    const first = toFlowNodes(doc);
+    // Drop the edge into node b; its connectedTargetHandles must update.
+    const second = toFlowNodes({ ...doc, edges: [] }, first);
+    const nodeB = second[1];
+
+    expect(nodeB?.type === 'invocation' && nodeB.data.connectedTargetHandles).toEqual([]);
+    expect(second[1]).not.toBe(first[1]);
+    // Node a lost its outgoing handle metadata, so it must also update.
+    expect(second[0]).not.toBe(first[0]);
+    expect(second[0]?.type === 'invocation' && second[0].data.connectedSourceHandles).toEqual([]);
+  });
+
+  it('precomputes connected source handles onto invocation node data', () => {
+    const doc = createDoc();
+    const nodes = toFlowNodes(doc);
+    const source = nodes[0];
+    const target = nodes[1];
+
+    expect(source?.type === 'invocation' ? source.data.connectedSourceHandles : []).toEqual(['value']);
+    expect(target?.type === 'invocation' ? target.data.connectedSourceHandles : []).toEqual([]);
+  });
+
+  it('precomputes exposed field names onto invocation node data', () => {
+    const doc = createDoc();
+    const exposed = {
+      ...doc,
+      form: {
+        ...doc.form,
+        elements: {
+          ...doc.form.elements,
+          'field-1': {
+            data: { fieldIdentifier: { fieldName: 'a', nodeId: 'b' }, showDescription: false },
+            id: 'field-1',
+            parentId: doc.form.rootElementId,
+            type: 'node-field' as const,
+          },
+        },
+      },
+    };
+    const nodes = toFlowNodes(exposed);
+    const nodeB = nodes[1];
+
+    expect(nodeB?.type === 'invocation' && nodeB.data.exposedFieldNames).toEqual(['a']);
+  });
+
+  it('marks invocation nodes compact for large workflow rendering', () => {
+    const doc = createDoc();
+    const normal = toFlowNodes(doc);
+    const compact = toFlowNodes(doc, normal, undefined, undefined, true);
+    const compactAgain = toFlowNodes(doc, compact, undefined, undefined, true);
+
+    expect(normal[0]?.type === 'invocation' && normal[0].data.isCompact).toBe(false);
+    expect(compact[0]?.type === 'invocation' && compact[0].data.isCompact).toBe(true);
+    expect(compact[0]).not.toBe(normal[0]);
+    expect(compactAgain[0]).toBe(compact[0]);
+  });
+
+  it('precomputes resolved connector field types onto connector node data', () => {
+    const fieldType = single('ImageField');
+    const templates = createTemplates(fieldType);
+    const doc = createDoc({
+      edges: [
+        createEdge('e1', 'a', 'c', 'value', CONNECTOR_INPUT_HANDLE),
+        createEdge('e2', 'c', 'b', CONNECTOR_OUTPUT_HANDLE, 'a'),
+      ],
+      nodes: [createNode('a'), createConnector('c'), createNode('b')],
+    });
+    const untyped = toFlowNodes(doc);
+    const typed = toFlowNodes(doc, untyped, templates);
+    const connector = typed[1];
+
+    expect(connector?.type).toBe('connector');
+    expect(connector?.type === 'connector' && connector.data.inputFieldType).toBe(fieldType);
+    expect(connector?.type === 'connector' && connector.data.outputFieldType).toBe(fieldType);
+    expect(connector).not.toBe(untyped[1]);
+    expect(toFlowNodes(doc, typed, templates)[1]).toBe(connector);
+  });
+
+  it('precomputes stable invocation template views onto invocation node data', () => {
+    const doc = createDoc();
+    const templates = createTemplates();
+    const first = toFlowNodes(doc, [], templates);
+    const second = toFlowNodes(doc, first, templates);
+    const node = first[0];
+
+    expect(node?.type === 'invocation' ? node.data.template?.template.title : null).toBe('Add');
+    expect(node?.type === 'invocation' ? node.data.template?.inputTemplates.map((input) => input.name) : []).toEqual([
+      'a',
+    ]);
+    expect(second[0]).toBe(first[0]);
+  });
+
+  it('does not mark a target as connected through an unresolved connector output', () => {
+    const doc = createDoc({
+      edges: [createEdge('e1', 'c', 'b', CONNECTOR_OUTPUT_HANDLE, 'a')],
+      nodes: [createConnector('c'), createNode('b')],
+    });
+    const nodes = toFlowNodes(doc);
+    const target = nodes.find((node) => node.id === 'b');
+
+    expect(target?.type).toBe('invocation');
+    expect(target?.type === 'invocation' ? target.data.connectedTargetHandles : []).toEqual([]);
+  });
+
+  it('carries selection across rebuilds and toggles it without copying unchanged nodes', () => {
+    const doc = createDoc();
+    const selected = withNodeSelection(toFlowNodes(doc), new Set(['a']));
+
+    expect(selected[0]?.selected).toBe(true);
+
+    const rebuilt = toFlowNodes(doc, selected);
+
+    expect(rebuilt[0]?.selected).toBe(true);
+
+    // Re-applying the same selection set returns identical node objects.
+    const reselected = withNodeSelection(selected, new Set(['a']));
+
+    expect(reselected[0]).toBe(selected[0]);
+  });
+
+  it('builds current_image nodes and reuses them when unchanged', () => {
+    const currentImage = buildCurrentImageNode({ x: 0, y: 0 });
+    const doc = createDoc({ nodes: [createNode('a'), currentImage] });
+    const first = toFlowNodes(doc);
+
+    expect(first[1]?.type).toBe('current_image');
+    expect(toFlowNodes(doc, first)[1]).toBe(first[1]);
+  });
+
+  it('reuses unchanged edge objects but replaces edges on type change', () => {
+    const doc = createDoc();
+    const first = toFlowEdges(doc, [], 'default');
+    const same = toFlowEdges(doc, first, 'default');
+
+    expect(same[0]).toBe(first[0]);
+
+    const restyled = toFlowEdges(doc, first, 'step');
+
+    expect(restyled[0]).not.toBe(first[0]);
+    expect(restyled[0]?.type).toBe('step');
+  });
+
+  it('adds field type metadata for custom edge rendering', () => {
+    const doc = createDoc();
+    const edge = toFlowEdges(doc, [], 'default', new Set(), createTemplates())[0];
+
+    expect(edge?.data).toMatchObject({
+      fieldTypeLabel: 'Integer',
+      pathType: 'default',
+      stroke: '#f87171',
+      strokeWidth: 2,
+      tooltip: 'Integer',
+    });
+  });
+
+  it('uses line pattern metadata for collection field types', () => {
+    const doc = createDoc();
+    const data = getWorkflowEdgeData(doc, doc.edges[0]!, 'step', createTemplates(collection('ImageField')));
+
+    expect(data).toMatchObject({
+      fieldTypeLabel: 'Image Collection',
+      pathType: 'step',
+      stroke: '#c4b5fd',
+      strokeDasharray: '8 4',
+      strokeWidth: 2.5,
+      tooltip: 'Image Collection',
+    });
+  });
+
+  it('replaces edges when templates resolve their field type styling', () => {
+    const doc = createDoc();
+    const untyped = toFlowEdges(doc, [], 'default');
+    const typed = toFlowEdges(doc, untyped, 'default', new Set(), createTemplates());
+
+    expect(typed[0]).not.toBe(untyped[0]);
+    expect(typed[0]?.data?.tooltip).toBe('Integer');
+  });
+
+  it('styles edges connected to selected nodes without persisting the highlight after deselection', () => {
+    const doc = createDoc();
+    const highlighted = toFlowEdges(doc, [], 'default', new Set(['a']));
+
+    expect(highlighted[0]?.animated).toBe(true);
+    expect(highlighted[0]?.className).toBe('workflow-selected-node-edge');
+    expect(highlighted[0]?.zIndex).toBe(1000);
+    expect(highlighted[0]?.style).toEqual({ strokeWidth: 2 });
+    expect(toFlowEdges(doc, highlighted, 'default', new Set(['a']))[0]).toBe(highlighted[0]);
+
+    const cleared = toFlowEdges(doc, highlighted, 'default');
+
+    expect(cleared[0]).not.toBe(highlighted[0]);
+    expect(cleared[0]?.animated).toBeUndefined();
+    expect(cleared[0]?.className).toBeUndefined();
+    expect(cleared[0]?.zIndex).toBeUndefined();
+    expect(cleared[0]?.style).toBeUndefined();
+  });
+
+  it('keeps selected-node edge styling but disables edge animation when motion is reduced', () => {
+    const doc = createDoc();
+    const highlighted = toFlowEdges(doc, [], 'default', new Set(['a']), undefined, true);
+
+    expect(highlighted[0]?.animated).toBeUndefined();
+    expect(highlighted[0]?.className).toBe('workflow-selected-node-edge');
+    expect(highlighted[0]?.zIndex).toBe(1000);
+    expect(highlighted[0]?.style).toEqual({ strokeWidth: 2 });
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowAdapters.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowAdapters.ts
new file mode 100644
index 00000000000..d6eb1f955fd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowAdapters.ts
@@ -0,0 +1,428 @@
+import type {
+  FieldType,
+  FieldInputTemplate,
+  FieldOutputTemplate,
+  InvocationTemplate,
+  InvocationTemplates,
+  ProjectGraphState,
+  WorkflowConnectorNode,
+  WorkflowCurrentImageNode,
+  WorkflowEdge,
+  WorkflowInvocationNode,
+  WorkflowNotesNode,
+} from '@workbench/workflows/types';
+import type { Edge as FlowEdge, Node as FlowNode } from '@xyflow/react';
+import type { CSSProperties } from 'react';
+
+import { isExecutableInvocationType } from '@workbench/workflows/buildGraph';
+import {
+  CONNECTOR_INPUT_HANDLE,
+  CONNECTOR_OUTPUT_HANDLE,
+  getResolvedWorkflowEdgesIndexed,
+} from '@workbench/workflows/connectors';
+import { getFieldTypeColor, getFieldTypeLabel } from '@workbench/workflows/fields';
+import { createWorkflowGraphIndex, type WorkflowGraphIndex } from '@workbench/workflows/graphIndex';
+import { getWorkflowSourceFieldType, getWorkflowTargetFieldType } from '@workbench/workflows/validation';
+
+/**
+ * Adapters between the project graph document and xyflow's node/edge state.
+ * The document is the source of truth; xyflow state is rebuilt from it on
+ * every document change, carrying over transient view state (selection).
+ *
+ * Rebuilds preserve object identity for unchanged nodes/edges so memoized
+ * node components skip re-rendering (see React Flow's performance guidance) —
+ * the document reducer already keeps untouched node identities stable.
+ * Derived per-node facts the node components need (incoming connections,
+ * Linear-UI exposure) are precomputed into `data` here, so node components
+ * never subscribe to workbench state.
+ */
+
+export type InvocationFlowNode = FlowNode<
+  {
+    canUseCache: boolean;
+    documentNode: WorkflowInvocationNode;
+    /** Source handle names with an outgoing edge. */
+    connectedSourceHandles: string[];
+    /** Target handle names with an incoming edge. */
+    connectedTargetHandles: string[];
+    /** Field names of this node exposed in the Linear UI form. */
+    exposedFieldNames: string[];
+    /** Large workflows render unselected nodes without field controls until selected. */
+    isCompact: boolean;
+    template: InvocationNodeTemplateView | null;
+  },
+  'invocation'
+>;
+export type NotesFlowNode = FlowNode<{ documentNode: WorkflowNotesNode }, 'notes'>;
+export type CurrentImageFlowNode = FlowNode<{ documentNode: WorkflowCurrentImageNode }, 'current_image'>;
+export type ConnectorFlowNode = FlowNode<
+  { documentNode: WorkflowConnectorNode; inputFieldType: FieldType | null; outputFieldType: FieldType | null },
+  'connector'
+>;
+export type WorkflowFlowNode = InvocationFlowNode | NotesFlowNode | CurrentImageFlowNode | ConnectorFlowNode;
+
+const EMPTY_NAMES: string[] = [];
+const EMPTY_NODE_IDS = new Set<string>();
+const SELECTED_NODE_EDGE_CLASS = 'workflow-selected-node-edge';
+const SELECTED_NODE_EDGE_STYLE: CSSProperties = { strokeWidth: 2 };
+
+const sameNames = (a: string[], b: string[]): boolean => a.length === b.length && a.every((name, i) => name === b[i]);
+
+export interface InvocationNodeTemplateView {
+  hasImageOutput: boolean;
+  inputTemplates: FieldInputTemplate[];
+  isExecutable: boolean;
+  outputTemplates: FieldOutputTemplate[];
+  template: InvocationTemplate;
+}
+
+const sortByUiOrder = <T extends { uiOrder?: number | null }>(templates: T[]): T[] =>
+  [...templates].sort((a, b) => (a.uiOrder ?? Number.MAX_SAFE_INTEGER) - (b.uiOrder ?? Number.MAX_SAFE_INTEGER));
+
+const hasImageOutput = (template: InvocationTemplate): boolean =>
+  template.type !== 'image' && Object.values(template.outputs).some((output) => output.type.name === 'ImageField');
+
+const createInvocationNodeTemplateView = (template: InvocationTemplate): InvocationNodeTemplateView => ({
+  hasImageOutput: hasImageOutput(template),
+  inputTemplates: sortByUiOrder(Object.values(template.inputs).filter((input) => !input.uiHidden)),
+  isExecutable: isExecutableInvocationType(template.type),
+  outputTemplates: Object.values(template.outputs),
+  template,
+});
+
+const templateViewCache = new WeakMap<InvocationTemplates, Map<string, InvocationNodeTemplateView>>();
+
+const getInvocationNodeTemplateViews = (
+  templates: InvocationTemplates | undefined
+): Map<string, InvocationNodeTemplateView> => {
+  if (!templates) {
+    return new Map();
+  }
+
+  const cached = templateViewCache.get(templates);
+
+  if (cached) {
+    return cached;
+  }
+
+  const views = new Map<string, InvocationNodeTemplateView>();
+
+  for (const template of Object.values(templates)) {
+    views.set(template.type, createInvocationNodeTemplateView(template));
+  }
+
+  templateViewCache.set(templates, views);
+
+  return views;
+};
+
+const getConnectedHandlesByNode = (document: ProjectGraphState, index: WorkflowGraphIndex): Map<string, string[]> => {
+  const byNode = new Map<string, string[]>();
+
+  for (const edge of getResolvedWorkflowEdgesIndexed(document.edges, index)) {
+    byNode.set(edge.target, [...(byNode.get(edge.target) ?? []), edge.targetHandle]);
+  }
+
+  for (const handles of byNode.values()) {
+    handles.sort();
+  }
+
+  return byNode;
+};
+
+const getConnectedSourceHandlesByNode = (document: ProjectGraphState): Map<string, string[]> => {
+  const byNode = new Map<string, string[]>();
+
+  for (const edge of document.edges) {
+    byNode.set(edge.source, [...(byNode.get(edge.source) ?? []), edge.sourceHandle]);
+  }
+
+  for (const handles of byNode.values()) {
+    handles.sort();
+  }
+
+  return byNode;
+};
+
+const getExposedFieldsByNode = (document: ProjectGraphState): Map<string, string[]> => {
+  const byNode = new Map<string, string[]>();
+
+  for (const element of Object.values(document.form.elements)) {
+    if (element.type === 'node-field') {
+      const { fieldName, nodeId } = element.data.fieldIdentifier;
+
+      byNode.set(nodeId, [...(byNode.get(nodeId) ?? []), fieldName]);
+    }
+  }
+
+  for (const fields of byNode.values()) {
+    fields.sort();
+  }
+
+  return byNode;
+};
+
+export const toFlowNodes = (
+  document: ProjectGraphState,
+  previousNodes: WorkflowFlowNode[] = [],
+  templates?: InvocationTemplates,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges),
+  isCompact = false,
+  canUseCache = false
+): WorkflowFlowNode[] => {
+  const previousById = new Map(previousNodes.map((node) => [node.id, node]));
+  const connectedByNode = getConnectedHandlesByNode(document, index);
+  const connectedSourcesByNode = getConnectedSourceHandlesByNode(document);
+  const exposedByNode = getExposedFieldsByNode(document);
+  const templateViews = getInvocationNodeTemplateViews(templates);
+
+  return document.nodes.map((documentNode): WorkflowFlowNode => {
+    const previous = previousById.get(documentNode.id);
+    const selected = previous?.selected ?? false;
+
+    if (documentNode.type === 'invocation') {
+      const connectedSourceHandles = connectedSourcesByNode.get(documentNode.id) ?? EMPTY_NAMES;
+      const connectedTargetHandles = connectedByNode.get(documentNode.id) ?? EMPTY_NAMES;
+      const exposedFieldNames = exposedByNode.get(documentNode.id) ?? EMPTY_NAMES;
+      const template = templateViews.get(documentNode.data.type) ?? null;
+
+      if (
+        previous?.type === 'invocation' &&
+        previous.data.canUseCache === canUseCache &&
+        previous.data.documentNode === documentNode &&
+        previous.data.isCompact === isCompact &&
+        previous.data.template === template &&
+        sameNames(previous.data.connectedSourceHandles, connectedSourceHandles) &&
+        sameNames(previous.data.connectedTargetHandles, connectedTargetHandles) &&
+        sameNames(previous.data.exposedFieldNames, exposedFieldNames)
+      ) {
+        return previous;
+      }
+
+      return {
+        data: {
+          canUseCache,
+          connectedSourceHandles,
+          connectedTargetHandles,
+          documentNode,
+          exposedFieldNames,
+          isCompact,
+          template,
+        },
+        id: documentNode.id,
+        position: documentNode.position,
+        selected,
+        type: 'invocation' as const,
+      };
+    }
+
+    if (documentNode.type === 'notes') {
+      if (previous?.type === 'notes' && previous.data.documentNode === documentNode) {
+        return previous;
+      }
+
+      return {
+        data: { documentNode },
+        id: documentNode.id,
+        position: documentNode.position,
+        selected,
+        type: 'notes' as const,
+      };
+    }
+
+    if (documentNode.type === 'connector') {
+      const inputFieldType = templates
+        ? (getWorkflowTargetFieldType(document, templates, documentNode.id, CONNECTOR_INPUT_HANDLE, index) ?? null)
+        : null;
+      const outputFieldType = templates
+        ? (getWorkflowSourceFieldType(document, templates, documentNode.id, CONNECTOR_OUTPUT_HANDLE, index) ?? null)
+        : null;
+
+      if (
+        previous?.type === 'connector' &&
+        previous.data.documentNode === documentNode &&
+        previous.data.inputFieldType === inputFieldType &&
+        previous.data.outputFieldType === outputFieldType
+      ) {
+        return previous;
+      }
+
+      return {
+        data: { documentNode, inputFieldType, outputFieldType },
+        id: documentNode.id,
+        position: documentNode.position,
+        selected,
+        type: 'connector' as const,
+      };
+    }
+
+    if (previous?.type === 'current_image' && previous.data.documentNode === documentNode) {
+      return previous;
+    }
+
+    return {
+      data: { documentNode },
+      id: documentNode.id,
+      position: documentNode.position,
+      selected,
+      type: 'current_image' as const,
+    };
+  });
+};
+
+/** Returns nodes with exactly `selectedIds` selected, preserving identity where unchanged. */
+export const withNodeSelection = (nodes: WorkflowFlowNode[], selectedIds: Set<string>): WorkflowFlowNode[] =>
+  nodes.map((node) => {
+    const selected = selectedIds.has(node.id);
+
+    if ((node.selected ?? false) === selected) {
+      return node;
+    }
+
+    // Narrowed per branch so TS keeps the node type / data correlation through the spread.
+    if (node.type === 'invocation') {
+      return { ...node, selected };
+    }
+
+    if (node.type === 'notes') {
+      return { ...node, selected };
+    }
+
+    if (node.type === 'connector') {
+      return { ...node, selected };
+    }
+
+    return { ...node, selected };
+  });
+
+/** xyflow edge component per the user's connection-style preference. */
+export type FlowEdgeType = 'default' | 'step';
+
+export interface WorkflowEdgeData extends Record<string, unknown> {
+  fieldTypeLabel: string;
+  pathType: FlowEdgeType;
+  stroke: string;
+  strokeDasharray?: string;
+  strokeWidth: number;
+  tooltip: string;
+}
+
+export type WorkflowFlowEdge = FlowEdge<WorkflowEdgeData, FlowEdgeType>;
+
+const UNKNOWN_EDGE_DATA = (pathType: FlowEdgeType): WorkflowEdgeData => ({
+  fieldTypeLabel: 'Unknown',
+  pathType,
+  stroke: 'var(--xy-edge-stroke)',
+  strokeWidth: 2,
+  tooltip: 'Unknown field type',
+});
+
+const getWorkflowEdgeFieldType = (
+  document: ProjectGraphState,
+  templates: InvocationTemplates | undefined,
+  edge: WorkflowEdge,
+  index: WorkflowGraphIndex
+): FieldType | null => {
+  if (!templates) {
+    return null;
+  }
+
+  return (
+    getWorkflowSourceFieldType(document, templates, edge.source, edge.sourceHandle, index) ??
+    getWorkflowTargetFieldType(document, templates, edge.target, edge.targetHandle, index) ??
+    null
+  );
+};
+
+export const getWorkflowEdgeData = (
+  document: ProjectGraphState,
+  edge: WorkflowEdge,
+  pathType: FlowEdgeType,
+  templates?: InvocationTemplates,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges)
+): WorkflowEdgeData => {
+  const fieldType = getWorkflowEdgeFieldType(document, templates, edge, index);
+
+  if (!fieldType) {
+    return UNKNOWN_EDGE_DATA(pathType);
+  }
+
+  const fieldTypeLabel = getFieldTypeLabel(fieldType);
+  const strokeDasharray = fieldType.batch
+    ? '2 5'
+    : fieldType.cardinality === 'COLLECTION'
+      ? '8 4'
+      : fieldType.cardinality === 'SINGLE_OR_COLLECTION'
+        ? '8 3 2 3'
+        : undefined;
+
+  return {
+    fieldTypeLabel,
+    pathType,
+    stroke: getFieldTypeColor(fieldType),
+    strokeDasharray,
+    strokeWidth: fieldType.cardinality === 'SINGLE' && !fieldType.batch ? 2 : 2.5,
+    tooltip: fieldType.batch ? `${fieldTypeLabel} batch` : fieldTypeLabel,
+  };
+};
+
+const isSameEdgeData = (a: WorkflowEdgeData | undefined, b: WorkflowEdgeData): boolean =>
+  a?.fieldTypeLabel === b.fieldTypeLabel &&
+  a.pathType === b.pathType &&
+  a.stroke === b.stroke &&
+  a.strokeDasharray === b.strokeDasharray &&
+  a.strokeWidth === b.strokeWidth &&
+  a.tooltip === b.tooltip;
+
+export const toFlowEdges = (
+  document: ProjectGraphState,
+  previousEdges: WorkflowFlowEdge[] = [],
+  edgeType: FlowEdgeType = 'default',
+  selectedNodeIds: Set<string> = EMPTY_NODE_IDS,
+  templates?: InvocationTemplates,
+  reduceMotion = false,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges)
+): WorkflowFlowEdge[] => {
+  const previousById = new Map(previousEdges.map((edge) => [edge.id, edge]));
+
+  return document.edges.map((edge) => {
+    const previous = previousById.get(edge.id);
+    const data = getWorkflowEdgeData(document, edge, edgeType, templates, index);
+    const isConnectedToSelectedNode = selectedNodeIds.has(edge.source) || selectedNodeIds.has(edge.target);
+    const animated = isConnectedToSelectedNode && !reduceMotion ? true : undefined;
+    const className = isConnectedToSelectedNode ? SELECTED_NODE_EDGE_CLASS : undefined;
+    const style = isConnectedToSelectedNode ? SELECTED_NODE_EDGE_STYLE : undefined;
+    const zIndex = isConnectedToSelectedNode ? 1000 : undefined;
+
+    if (
+      previous &&
+      previous.type === edgeType &&
+      previous.source === edge.source &&
+      previous.sourceHandle === edge.sourceHandle &&
+      previous.target === edge.target &&
+      previous.targetHandle === edge.targetHandle &&
+      previous.animated === animated &&
+      previous.className === className &&
+      isSameEdgeData(previous.data, data) &&
+      previous.style === style &&
+      previous.zIndex === zIndex
+    ) {
+      return previous;
+    }
+
+    return {
+      id: edge.id,
+      animated,
+      className,
+      data,
+      selected: previous?.selected ?? false,
+      source: edge.source,
+      sourceHandle: edge.sourceHandle,
+      style,
+      target: edge.target,
+      targetHandle: edge.targetHandle,
+      type: edgeType,
+      zIndex,
+    };
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowInstanceStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowInstanceStore.ts
new file mode 100644
index 00000000000..2f1d651d428
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/flowInstanceStore.ts
@@ -0,0 +1,26 @@
+import type { ReactFlowInstance } from '@xyflow/react';
+
+import type { WorkflowFlowEdge, WorkflowFlowNode } from './flowAdapters';
+
+/**
+ * Module-level handle to the mounted workflow editor's ReactFlow instance, so
+ * surfaces outside the ReactFlowProvider (the widget frame's header actions)
+ * can place inserted nodes at the current viewport center. Mirrors the legacy
+ * editor's nanostore-held instance.
+ */
+
+export type WorkflowFlowInstance = ReactFlowInstance<WorkflowFlowNode, WorkflowFlowEdge>;
+
+let flowInstance: WorkflowFlowInstance | null = null;
+
+export const registerWorkflowFlowInstance = (instance: WorkflowFlowInstance): void => {
+  flowInstance = instance;
+};
+
+export const releaseWorkflowFlowInstance = (instance: WorkflowFlowInstance): void => {
+  if (flowInstance === instance) {
+    flowInstance = null;
+  }
+};
+
+export const getWorkflowFlowInstance = (): WorkflowFlowInstance | null => flowInstance;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/handleTooltip.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/handleTooltip.test.ts
new file mode 100644
index 00000000000..0ad8d6c1e10
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/handleTooltip.test.ts
@@ -0,0 +1,24 @@
+import type { FieldType } from '@workbench/workflows/types';
+
+import { describe, expect, it } from 'vitest';
+
+import { getHandleTypeTooltip } from './handleTooltip';
+
+const fieldType = (overrides: Partial<FieldType> = {}): FieldType => ({
+  batch: false,
+  cardinality: 'SINGLE',
+  name: 'ImageField',
+  ...overrides,
+});
+
+describe('handleTooltip', () => {
+  it('uses the resolved field type label for handle titles', () => {
+    expect(getHandleTypeTooltip(fieldType())).toBe('Image');
+    expect(getHandleTypeTooltip(fieldType({ cardinality: 'COLLECTION' }))).toBe('Image Collection');
+    expect(getHandleTypeTooltip(fieldType({ batch: true }))).toBe('Image batch');
+  });
+
+  it('uses fallbacks for unresolved connector handles', () => {
+    expect(getHandleTypeTooltip(null, 'Any input')).toBe('Any input');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/handleTooltip.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/handleTooltip.ts
new file mode 100644
index 00000000000..2ca61145392
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/handleTooltip.ts
@@ -0,0 +1,13 @@
+import type { FieldType } from '@workbench/workflows/types';
+
+import { getFieldTypeLabel } from '@workbench/workflows/fields';
+
+export const getHandleTypeTooltip = (type: FieldType | null, fallback = 'Any'): string => {
+  if (!type) {
+    return fallback;
+  }
+
+  const label = getFieldTypeLabel(type);
+
+  return type.batch ? `${label} batch` : label;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/nodeChrome.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/nodeChrome.ts
new file mode 100644
index 00000000000..8bf9b270cbc
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/nodeChrome.ts
@@ -0,0 +1,21 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+const NODE_HOVER_RING = '0 0 0 2px {colors.accent.solid/50}, {shadows.md}';
+const NODE_RUNNING_RING = '0 0 0 2px {colors.brand.solid/70}, 0 0 10px {colors.brand.solid/50}';
+const NODE_SELECTED_RING = '0 0 0 2px {colors.accent.solid}, {shadows.md}';
+
+export const getWorkflowNodeChromeProps = ({
+  invalid = false,
+  running = false,
+  selected,
+}: {
+  invalid?: boolean;
+  running?: boolean;
+  selected: boolean;
+}): BoxProps => ({
+  borderColor: invalid ? 'red.solid' : running ? 'brand.solid' : 'border.emphasized',
+  borderWidth: '1px',
+  shadow: selected ? NODE_SELECTED_RING : running ? NODE_RUNNING_RING : 'sm',
+  transition: 'border-color var(--wb-motion-duration-fast) ease, box-shadow var(--wb-motion-duration-fast) ease',
+  _hover: selected ? undefined : { shadow: NODE_HOVER_RING },
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/performanceConstants.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/performanceConstants.ts
new file mode 100644
index 00000000000..55b4c87e901
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/performanceConstants.ts
@@ -0,0 +1,8 @@
+export const WORKFLOW_LARGE_GRAPH_NODE_COUNT = 300;
+export const WORKFLOW_LARGE_GRAPH_EDGE_COUNT = 500;
+
+export const WORKFLOW_MINIMAP_DELAY_MS = 450;
+export const WORKFLOW_INITIAL_RENDER_NODE_COUNT = 120;
+
+export const isLargeWorkflowGraph = ({ edgeCount, nodeCount }: { edgeCount: number; nodeCount: number }): boolean =>
+  nodeCount >= WORKFLOW_LARGE_GRAPH_NODE_COUNT || edgeCount >= WORKFLOW_LARGE_GRAPH_EDGE_COUNT;
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/selectionStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/selectionStore.ts
new file mode 100644
index 00000000000..f570993dadb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/selectionStore.ts
@@ -0,0 +1,45 @@
+import { createExternalStore } from '@workbench/externalStore';
+
+/**
+ * Session-lived editor selection, shared with surfaces outside the flow (the
+ * node inspector, the form builder's zoom-to-node). The editor writes
+ * `selectedNodeIds` from its selection events; other surfaces ask for a
+ * selection via `requestNodeSelection`, which the editor applies and focuses.
+ */
+
+export interface WorkflowSelectionSnapshot {
+  hoveredNodeId: string | null;
+  selectedNodeIds: string[];
+  /** A pending outside request: the editor selects + zooms to these, then clears. */
+  selectionRequest: { nodeIds: string[]; token: number } | null;
+}
+
+export const workflowSelectionStore = createExternalStore<WorkflowSelectionSnapshot>({
+  hoveredNodeId: null,
+  selectedNodeIds: [],
+  selectionRequest: null,
+});
+
+const areSameIds = (a: string[], b: string[]): boolean => a.length === b.length && a.every((id, i) => id === b[i]);
+
+export const reportNodeSelection = (selectedNodeIds: string[]): void => {
+  if (!areSameIds(workflowSelectionStore.getSnapshot().selectedNodeIds, selectedNodeIds)) {
+    workflowSelectionStore.patchSnapshot({ selectedNodeIds });
+  }
+};
+
+export const reportNodeHover = (hoveredNodeId: string | null): void => {
+  if (workflowSelectionStore.getSnapshot().hoveredNodeId !== hoveredNodeId) {
+    workflowSelectionStore.patchSnapshot({ hoveredNodeId });
+  }
+};
+
+export const requestNodeSelection = (nodeIds: string[]): void => {
+  const previousToken = workflowSelectionStore.getSnapshot().selectionRequest?.token ?? 0;
+
+  workflowSelectionStore.patchSnapshot({ selectionRequest: { nodeIds, token: previousToken + 1 } });
+};
+
+export const clearNodeSelectionRequest = (): void => {
+  workflowSelectionStore.patchSnapshot({ selectionRequest: null });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/useEraser.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/useEraser.tsx
new file mode 100644
index 00000000000..daaa79ad119
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/useEraser.tsx
@@ -0,0 +1,262 @@
+import type { XYPosition } from '@workbench/workflows/types';
+
+import { Box } from '@chakra-ui/react';
+import {
+  useEffect,
+  useRef,
+  useState,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from 'react';
+
+import type { WorkflowFlowInstance } from './flowInstanceStore';
+
+const ERASER_RADIUS_PX = 14;
+const EDGE_SAMPLE_DISTANCE = 12;
+
+type ErasedElements = { edgeIds: string[]; nodeIds: string[] };
+
+const getDistanceToSegmentSquared = (point: XYPosition, start: XYPosition, end: XYPosition): number => {
+  const dx = end.x - start.x;
+  const dy = end.y - start.y;
+  const lengthSquared = dx * dx + dy * dy;
+
+  if (lengthSquared === 0) {
+    return (point.x - start.x) ** 2 + (point.y - start.y) ** 2;
+  }
+
+  const t = Math.max(0, Math.min(1, ((point.x - start.x) * dx + (point.y - start.y) * dy) / lengthSquared));
+  const closest = { x: start.x + t * dx, y: start.y + t * dy };
+
+  return (point.x - closest.x) ** 2 + (point.y - closest.y) ** 2;
+};
+
+const getEraserRect = (start: XYPosition, end: XYPosition, radius: number) => ({
+  height: Math.abs(end.y - start.y) + radius * 2,
+  width: Math.abs(end.x - start.x) + radius * 2,
+  x: Math.min(start.x, end.x) - radius,
+  y: Math.min(start.y, end.y) - radius,
+});
+
+const getLocalPoint = (bounds: DOMRect, clientX: number, clientY: number): XYPosition => ({
+  x: clientX - bounds.left,
+  y: clientY - bounds.top,
+});
+
+const isEraserTarget = (target: EventTarget | null): target is Element =>
+  target instanceof Element && target.closest('.react-flow__pane, .react-flow__node, .react-flow__edge') !== null;
+
+const getIntersectingEdgeIds = ({
+  container,
+  erasedEdgeIds,
+  end,
+  radius,
+  start,
+}: {
+  container: HTMLElement;
+  erasedEdgeIds: Set<string>;
+  end: XYPosition;
+  radius: number;
+  start: XYPosition;
+}): string[] => {
+  const edgeIds: string[] = [];
+  const radiusSquared = radius * radius;
+  const sampleDistance = Math.max(radius, EDGE_SAMPLE_DISTANCE);
+
+  for (const path of container.querySelectorAll<SVGPathElement>('.react-flow__edge-path')) {
+    const edgeId = path.closest<SVGGElement>('.react-flow__edge')?.dataset.id;
+
+    if (!edgeId || erasedEdgeIds.has(edgeId)) {
+      continue;
+    }
+
+    let length: number;
+
+    try {
+      length = path.getTotalLength();
+    } catch {
+      continue;
+    }
+
+    for (let distance = 0; distance <= length; distance += sampleDistance) {
+      const point = path.getPointAtLength(distance);
+
+      if (getDistanceToSegmentSquared(point, start, end) <= radiusSquared) {
+        edgeIds.push(edgeId);
+        break;
+      }
+    }
+
+    if (!edgeIds.includes(edgeId)) {
+      const point = path.getPointAtLength(length);
+
+      if (getDistanceToSegmentSquared(point, start, end) <= radiusSquared) {
+        edgeIds.push(edgeId);
+      }
+    }
+  }
+
+  return edgeIds;
+};
+
+export const useEraser = ({
+  enabled,
+  flowInstance,
+  onErase,
+}: {
+  enabled: boolean;
+  flowInstance: WorkflowFlowInstance | null;
+  onErase: (elements: ErasedElements) => void;
+}): {
+  eraserHandlers: {
+    onClickCapture: (event: ReactMouseEvent<HTMLDivElement>) => void;
+    onPointerDownCapture: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  };
+  eraserOverlay: ReactNode;
+} => {
+  const [screenPoints, setScreenPoints] = useState<XYPosition[]>([]);
+  const boundsRef = useRef<DOMRect | null>(null);
+  const cleanupRef = useRef<(() => void) | null>(null);
+  const erasedEdgeIdsRef = useRef(new Set<string>());
+  const erasedNodeIdsRef = useRef(new Set<string>());
+  const flowPointsRef = useRef<XYPosition[]>([]);
+  const suppressClickRef = useRef(false);
+
+  useEffect(
+    () => () => {
+      cleanupRef.current?.();
+    },
+    []
+  );
+
+  const eraseSegment = (container: HTMLElement, start: XYPosition, end: XYPosition) => {
+    if (!flowInstance) {
+      return;
+    }
+
+    const radius = ERASER_RADIUS_PX / flowInstance.getZoom();
+    const nodeIds = flowInstance
+      .getIntersectingNodes(getEraserRect(start, end, radius), true)
+      .map((node) => node.id)
+      .filter((nodeId) => !erasedNodeIdsRef.current.has(nodeId));
+    const nodeIdSet = new Set(nodeIds);
+
+    for (const edge of flowInstance.getEdges()) {
+      if (nodeIdSet.has(edge.source) || nodeIdSet.has(edge.target)) {
+        erasedEdgeIdsRef.current.add(edge.id);
+      }
+    }
+
+    const edgeIds = getIntersectingEdgeIds({
+      container,
+      erasedEdgeIds: erasedEdgeIdsRef.current,
+      end,
+      radius,
+      start,
+    });
+
+    if (nodeIds.length === 0 && edgeIds.length === 0) {
+      return;
+    }
+
+    for (const nodeId of nodeIds) {
+      erasedNodeIdsRef.current.add(nodeId);
+    }
+
+    for (const edgeId of edgeIds) {
+      erasedEdgeIdsRef.current.add(edgeId);
+    }
+
+    onErase({ edgeIds, nodeIds });
+  };
+
+  const addPoint = (container: HTMLElement, event: Pick<PointerEvent, 'clientX' | 'clientY'>) => {
+    const bounds = boundsRef.current;
+
+    if (!flowInstance || !bounds) {
+      return;
+    }
+
+    const flowPoint = flowInstance.screenToFlowPosition({ x: event.clientX, y: event.clientY });
+    const previousPoint = flowPointsRef.current.at(-1) ?? flowPoint;
+
+    flowPointsRef.current = [...flowPointsRef.current, flowPoint];
+    setScreenPoints((current) => [...current, getLocalPoint(bounds, event.clientX, event.clientY)]);
+    eraseSegment(container, previousPoint, flowPoint);
+  };
+
+  const onPointerDownCapture = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (!enabled || !flowInstance || event.button !== 0 || !isEraserTarget(event.target)) {
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    suppressClickRef.current = true;
+    erasedEdgeIdsRef.current = new Set();
+    erasedNodeIdsRef.current = new Set();
+    flowPointsRef.current = [];
+
+    const container = event.currentTarget;
+    boundsRef.current = container.getBoundingClientRect();
+    setScreenPoints([]);
+    addPoint(container, event.nativeEvent);
+
+    const onPointerMove = (moveEvent: globalThis.PointerEvent) => {
+      moveEvent.preventDefault();
+      addPoint(container, moveEvent);
+    };
+
+    const onPointerUp = () => {
+      cleanupRef.current?.();
+      flowPointsRef.current = [];
+      boundsRef.current = null;
+      setScreenPoints([]);
+    };
+
+    window.addEventListener('pointermove', onPointerMove);
+    window.addEventListener('pointerup', onPointerUp);
+    cleanupRef.current = () => {
+      window.removeEventListener('pointermove', onPointerMove);
+      window.removeEventListener('pointerup', onPointerUp);
+      cleanupRef.current = null;
+    };
+  };
+
+  const onClickCapture = (event: ReactMouseEvent<HTMLDivElement>) => {
+    if (!suppressClickRef.current) {
+      return;
+    }
+
+    suppressClickRef.current = false;
+    event.preventDefault();
+    event.stopPropagation();
+  };
+
+  const points = screenPoints.map((point) => `${point.x},${point.y}`).join(' ');
+  const eraserOverlay =
+    screenPoints.length > 0 ? (
+      <Box as="svg" h="full" inset="0" overflow="visible" pointerEvents="none" position="absolute" w="full" zIndex="4">
+        <polyline
+          fill="none"
+          points={points}
+          stroke="var(--xy-selection-background-color)"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth={ERASER_RADIUS_PX * 2}
+        />
+        <polyline
+          fill="none"
+          points={points}
+          stroke="var(--xy-edge-stroke-selected)"
+          strokeDasharray="4 3"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="1.5"
+        />
+      </Box>
+    ) : null;
+
+  return { eraserHandlers: { onClickCapture, onPointerDownCapture }, eraserOverlay };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/useLasso.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/useLasso.tsx
new file mode 100644
index 00000000000..9694c2d70ef
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/useLasso.tsx
@@ -0,0 +1,185 @@
+import type { XYPosition } from '@workbench/workflows/types';
+
+import { Box } from '@chakra-ui/react';
+import {
+  useEffect,
+  useRef,
+  useState,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from 'react';
+
+import type { WorkflowFlowInstance } from './flowInstanceStore';
+
+/**
+ * Freeform lasso selection for the flow editor. xyflow has no core lasso (its
+ * official one is a copy-in component), so this follows the same approach:
+ * capture-phase pointer handlers on the flow wrapper stop the pane's own drag,
+ * the path is hit-tested against node bounds in flow coordinates, and a
+ * pointer-events-free SVG overlay draws the path. Partial mode: a node is
+ * selected when any corner or its center falls inside the polygon.
+ */
+
+const MIN_POLYGON_POINTS = 3;
+
+/** Ray-casting point-in-polygon. */
+const isInsidePolygon = (point: XYPosition, polygon: XYPosition[]): boolean => {
+  let isInside = false;
+
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+    const a = polygon[i] as XYPosition;
+    const b = polygon[j] as XYPosition;
+
+    if (a.y > point.y !== b.y > point.y && point.x < ((b.x - a.x) * (point.y - a.y)) / (b.y - a.y) + a.x) {
+      isInside = !isInside;
+    }
+  }
+
+  return isInside;
+};
+
+export const useLasso = ({
+  enabled,
+  flowInstance,
+  onSelect,
+}: {
+  enabled: boolean;
+  flowInstance: WorkflowFlowInstance | null;
+  onSelect: (nodeIds: string[]) => void;
+}): {
+  /** Spread onto the flow wrapper (capture phase, so the pane never sees the drag). */
+  lassoHandlers: {
+    onClickCapture: (event: ReactMouseEvent<HTMLDivElement>) => void;
+    onPointerDownCapture: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  };
+  /** Render inside the (position: relative) flow wrapper. */
+  lassoOverlay: ReactNode;
+} => {
+  const [screenPoints, setScreenPoints] = useState<XYPosition[]>([]);
+  const flowPointsRef = useRef<XYPosition[]>([]);
+  const frameRef = useRef<number | null>(null);
+  const cleanupRef = useRef<(() => void) | null>(null);
+  const suppressClickRef = useRef(false);
+
+  useEffect(
+    () => () => {
+      cleanupRef.current?.();
+
+      if (frameRef.current !== null) {
+        cancelAnimationFrame(frameRef.current);
+      }
+    },
+    []
+  );
+
+  const applySelection = () => {
+    const polygon = flowPointsRef.current;
+
+    if (!flowInstance || polygon.length < MIN_POLYGON_POINTS) {
+      return;
+    }
+
+    const selectedIds: string[] = [];
+
+    for (const node of flowInstance.getNodes()) {
+      const width = node.measured?.width ?? 0;
+      const height = node.measured?.height ?? 0;
+      const { x, y } = node.position;
+      const probes: XYPosition[] = [
+        { x, y },
+        { x: x + width, y },
+        { x, y: y + height },
+        { x: x + width, y: y + height },
+        { x: x + width / 2, y: y + height / 2 },
+      ];
+
+      if (probes.some((probe) => isInsidePolygon(probe, polygon))) {
+        selectedIds.push(node.id);
+      }
+    }
+
+    onSelect(selectedIds);
+  };
+
+  const onPointerDownCapture = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (!enabled || !flowInstance || event.button !== 0) {
+      return;
+    }
+
+    // Let clicks inside nodes/controls behave normally; the lasso only owns
+    // drags that start on the pane itself.
+    if (!(event.target instanceof Element) || !event.target.classList.contains('react-flow__pane')) {
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+
+    const container = event.currentTarget;
+    const bounds = container.getBoundingClientRect();
+    const toLocal = (clientX: number, clientY: number): XYPosition => ({
+      x: clientX - bounds.left,
+      y: clientY - bounds.top,
+    });
+
+    flowPointsRef.current = [flowInstance.screenToFlowPosition({ x: event.clientX, y: event.clientY })];
+    setScreenPoints([toLocal(event.clientX, event.clientY)]);
+
+    const onPointerMove = (moveEvent: globalThis.PointerEvent) => {
+      flowPointsRef.current = [
+        ...flowPointsRef.current,
+        flowInstance.screenToFlowPosition({ x: moveEvent.clientX, y: moveEvent.clientY }),
+      ];
+      setScreenPoints((current) => [...current, toLocal(moveEvent.clientX, moveEvent.clientY)]);
+
+      if (frameRef.current === null) {
+        frameRef.current = requestAnimationFrame(() => {
+          frameRef.current = null;
+          applySelection();
+        });
+      }
+    };
+
+    const onPointerUp = () => {
+      suppressClickRef.current = flowPointsRef.current.length >= MIN_POLYGON_POINTS;
+      cleanupRef.current?.();
+      applySelection();
+      flowPointsRef.current = [];
+      setScreenPoints([]);
+    };
+
+    window.addEventListener('pointermove', onPointerMove);
+    window.addEventListener('pointerup', onPointerUp);
+    cleanupRef.current = () => {
+      window.removeEventListener('pointermove', onPointerMove);
+      window.removeEventListener('pointerup', onPointerUp);
+      cleanupRef.current = null;
+    };
+  };
+
+  const onClickCapture = (event: ReactMouseEvent<HTMLDivElement>) => {
+    if (!suppressClickRef.current) {
+      return;
+    }
+
+    suppressClickRef.current = false;
+    event.preventDefault();
+    event.stopPropagation();
+  };
+
+  const lassoOverlay =
+    screenPoints.length >= 2 ? (
+      <Box as="svg" h="full" inset="0" overflow="visible" pointerEvents="none" position="absolute" w="full" zIndex="4">
+        <polygon
+          fill="var(--xy-selection-background-color)"
+          points={screenPoints.map((point) => `${point.x},${point.y}`).join(' ')}
+          stroke="var(--xy-edge-stroke-selected)"
+          strokeDasharray="4 2"
+          strokeWidth="1"
+        />
+      </Box>
+    ) : null;
+
+  return { lassoHandlers: { onClickCapture, onPointerDownCapture }, lassoOverlay };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/workflowViewportStore.test.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/workflowViewportStore.test.ts
new file mode 100644
index 00000000000..a290ed36290
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/workflowViewportStore.test.ts
@@ -0,0 +1,18 @@
+import type { Viewport } from '@xyflow/react';
+
+import { describe, expect, it } from 'vitest';
+
+import { getWorkflowViewport, setWorkflowViewport } from './workflowViewportStore';
+
+describe('workflowViewportStore', () => {
+  it('stores workflow editor viewports per widget instance for the current session', () => {
+    const viewport: Viewport = { x: 12, y: 24, zoom: 0.75 };
+
+    expect(getWorkflowViewport('workflow:center')).toBeNull();
+
+    setWorkflowViewport('workflow:center', viewport);
+
+    expect(getWorkflowViewport('workflow:center')).toEqual(viewport);
+    expect(getWorkflowViewport('workflow:bottom')).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/workflowViewportStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/workflowViewportStore.ts
new file mode 100644
index 00000000000..b1820283318
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/editor/workflowViewportStore.ts
@@ -0,0 +1,17 @@
+import type { WidgetInstanceId } from '@workbench/types';
+import type { Viewport } from '@xyflow/react';
+
+const viewports = new Map<string, Viewport>();
+
+export const getWorkflowViewportKey = (projectId: string, instanceId: WidgetInstanceId): string =>
+  `${projectId}:${instanceId}`;
+
+export const getWorkflowViewport = (key: string): Viewport | null => {
+  const viewport = viewports.get(key);
+
+  return viewport ? { ...viewport } : null;
+};
+
+export const setWorkflowViewport = (key: string, viewport: Viewport): void => {
+  viewports.set(key, { x: viewport.x, y: viewport.y, zoom: viewport.zoom });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/fields/FieldDescriptionPopover.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/fields/FieldDescriptionPopover.tsx
new file mode 100644
index 00000000000..cafe861b79c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/fields/FieldDescriptionPopover.tsx
@@ -0,0 +1,81 @@
+import type { ChangeEvent } from 'react';
+
+import { Icon, Popover, Portal, Stack, Text, Textarea, IconButton } from '@chakra-ui/react';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { FileTextIcon } from 'lucide-react';
+import { useCallback } from 'react';
+
+const POPOVER_POSITIONING = { placement: 'bottom-end' } as const;
+
+/**
+ * Small textarea popover overriding a field's template description ("field
+ * notes"), shared by the editor's node field rows and the form builder.
+ */
+export const FieldDescriptionPopover = ({
+  description,
+  fieldName,
+  nodeId,
+  templateDescription,
+}: {
+  /** The current override, if any. */
+  description: string | undefined;
+  fieldName: string;
+  nodeId: string;
+  templateDescription: string;
+}) => {
+  const dispatch = useWorkbenchDispatch();
+  const onDescriptionChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) =>
+      dispatch({
+        action: {
+          description: event.currentTarget.value,
+          fieldName,
+          nodeId,
+          type: 'setFieldDescription',
+        },
+        type: 'applyProjectGraphAction',
+      }),
+    [dispatch, fieldName, nodeId]
+  );
+
+  return (
+    <Popover.Root lazyMount positioning={POPOVER_POSITIONING}>
+      <Popover.Trigger asChild>
+        <IconButton
+          aria-label="Edit field description"
+          className="nodrag"
+          color={description ? 'accent.solid' : 'fg.subtle'}
+          size="2xs"
+          title="Edit field description"
+          variant="ghost"
+        >
+          <Icon as={FileTextIcon} boxSize="3" />
+        </IconButton>
+      </Popover.Trigger>
+      <Portal>
+        <Popover.Positioner>
+          <Popover.Content bg="bg.muted" borderColor="border.emphasized" borderWidth="1px" w="18rem">
+            <Popover.Body p="2">
+              <Stack gap="1">
+                <Text color="fg.subtle" fontSize="2xs" lineHeight={1.3}>
+                  Field description — overrides the node's default. Clear to restore it.
+                </Text>
+                <Textarea
+                  aria-label="Field description"
+                  className="nodrag nowheel"
+                  fontSize="2xs"
+                  minH="4rem"
+                  placeholder={templateDescription || 'Describe this field…'}
+                  resize="vertical"
+                  size="xs"
+                  value={description ?? ''}
+                  onChange={onDescriptionChange}
+                />
+              </Stack>
+            </Popover.Body>
+          </Popover.Content>
+        </Popover.Positioner>
+      </Portal>
+    </Popover.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/fields/WorkflowFieldInput.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/fields/WorkflowFieldInput.tsx
new file mode 100644
index 00000000000..30f1fc32613
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/fields/WorkflowFieldInput.tsx
@@ -0,0 +1,468 @@
+import type { ModelConfig, ModelTaxonomyType } from '@workbench/models/types';
+import type { GeneratedImageContract } from '@workbench/types';
+import type { FieldInputTemplate } from '@workbench/workflows/types';
+
+import { HStack, Input, NativeSelect, Switch, Text, Textarea } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { listGalleryBoards, type GalleryBoard } from '@workbench/gallery/api';
+import { SCHEDULER_OPTIONS } from '@workbench/generation/baseGenerationPolicies';
+import { ModelSelect } from '@workbench/models/components';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector } from '@workbench/WorkbenchContext';
+import { useCallback, useEffect, useMemo, useState, type ChangeEvent } from 'react';
+
+/**
+ * Direct-input controls for workflow fields, shared between the node editor
+ * and the Linear UI panel. Renders by template field type; connection-only
+ * and unsupported types fall through to a muted note.
+ */
+
+export interface WorkflowFieldInputProps {
+  id?: string;
+  invalid?: boolean;
+  template: FieldInputTemplate;
+  value: unknown;
+  onChange: (value: unknown) => void;
+}
+
+const invalidProps = (invalid: boolean | undefined) => (invalid ? { 'aria-invalid': true } : {});
+
+const toFiniteNumber = (raw: string): number | null => {
+  if (raw.trim() === '') {
+    return null;
+  }
+
+  const parsed = Number(raw);
+
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+const StringInput = ({ id, invalid, onChange, template, value }: WorkflowFieldInputProps) => {
+  const text = typeof value === 'string' ? value : '';
+  const onTextareaChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => onChange(event.currentTarget.value),
+    [onChange]
+  );
+  const onInputChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => onChange(event.currentTarget.value),
+    [onChange]
+  );
+
+  if (template.uiComponent === 'textarea') {
+    return (
+      <Textarea
+        aria-label={template.title}
+        className="nodrag nowheel"
+        fontFamily="mono"
+        id={id ? `${id}-textarea` : undefined}
+        minH="4.5rem"
+        resize="vertical"
+        size="xs"
+        value={text}
+        w="full"
+        {...invalidProps(invalid)}
+        onChange={onTextareaChange}
+      />
+    );
+  }
+
+  return (
+    <Input
+      aria-label={template.title}
+      className="nodrag"
+      id={id ? `${id}-input` : undefined}
+      size="xs"
+      value={text}
+      w="full"
+      {...invalidProps(invalid)}
+      onChange={onInputChange}
+    />
+  );
+};
+
+const NumericInput = ({ id, invalid, onChange, template, value }: WorkflowFieldInputProps) => {
+  const isInteger = template.type.name === 'IntegerField';
+  const numericValue = typeof value === 'number' && Number.isFinite(value) ? value : '';
+  const min = template.minimum ?? template.exclusiveMinimum ?? undefined;
+  const max = template.maximum ?? template.exclusiveMaximum ?? undefined;
+  const onInputChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      const parsed = toFiniteNumber(event.currentTarget.value);
+
+      if (parsed !== null) {
+        onChange(isInteger ? Math.round(parsed) : parsed);
+      }
+    },
+    [isInteger, onChange]
+  );
+
+  return (
+    <Input
+      aria-label={template.title}
+      className="nodrag"
+      id={id ? `${id}-number-input` : undefined}
+      max={max !== undefined ? String(max) : undefined}
+      min={min !== undefined ? String(min) : undefined}
+      size="xs"
+      step={template.multipleOf !== null ? String(template.multipleOf) : isInteger ? '1' : 'any'}
+      type="number"
+      value={numericValue}
+      w="full"
+      {...invalidProps(invalid)}
+      onChange={onInputChange}
+    />
+  );
+};
+
+const SWITCH_CHECKED_PROPS = { bg: 'accent.solid' };
+
+const BooleanInput = ({ id, invalid, onChange, template, value }: WorkflowFieldInputProps) => {
+  const onCheckedChange = useCallback((event: { checked: boolean }) => onChange(event.checked), [onChange]);
+
+  return (
+    <Switch.Root
+      checked={value === true}
+      className="nodrag"
+      invalid={invalid}
+      size="sm"
+      onCheckedChange={onCheckedChange}
+    >
+      <Switch.HiddenInput
+        aria-label={template.title}
+        id={id ? `${id}-switch-input` : undefined}
+        {...invalidProps(invalid)}
+      />
+      <Switch.Control _checked={SWITCH_CHECKED_PROPS}>
+        <Switch.Thumb />
+      </Switch.Control>
+    </Switch.Root>
+  );
+};
+
+const SelectInput = ({
+  id,
+  invalid,
+  onChange,
+  options,
+  title,
+  value,
+}: {
+  id?: string;
+  onChange: (value: string) => void;
+  invalid?: boolean;
+  options: { label: string; value: string }[];
+  title: string;
+  value: unknown;
+}) => {
+  const selectedValue = typeof value === 'string' ? value : '';
+  const onSelectChange = useCallback(
+    (event: ChangeEvent<HTMLSelectElement>) => onChange(event.currentTarget.value),
+    [onChange]
+  );
+
+  return (
+    <NativeSelect.Root className="nodrag" invalid={invalid} size="xs" w="full">
+      <NativeSelect.Field
+        aria-label={title}
+        id={id ? `${id}-select` : undefined}
+        value={selectedValue}
+        onChange={onSelectChange}
+      >
+        {typeof value !== 'string' || !options.some((option) => option.value === value) ? (
+          <option value="">Select…</option>
+        ) : null}
+        {options.map((option) => (
+          <option key={option.value} value={option.value}>
+            {option.label}
+          </option>
+        ))}
+      </NativeSelect.Field>
+      <NativeSelect.Indicator />
+    </NativeSelect.Root>
+  );
+};
+
+const EnumInput = ({ id, invalid, onChange, template, value }: WorkflowFieldInputProps) => {
+  const options = useMemo(
+    () =>
+      (template.options ?? []).map((option) => ({
+        label: template.uiChoiceLabels?.[option] ?? option,
+        value: option,
+      })),
+    [template.options, template.uiChoiceLabels]
+  );
+
+  return (
+    <SelectInput id={id} invalid={invalid} options={options} title={template.title} value={value} onChange={onChange} />
+  );
+};
+
+const DEFAULT_MODEL_TYPES: ModelTaxonomyType[] = ['main', 'vae', 'lora', 'controlnet', 't2i_adapter', 'ip_adapter'];
+
+const ModelIdentifierInput = ({ id, invalid, onChange, template, value }: WorkflowFieldInputProps) => {
+  const selectedKey =
+    typeof (value as { key?: unknown } | null)?.key === 'string' ? (value as { key: string }).key : null;
+  const modelTypes = (template.uiModelType as ModelTaxonomyType[] | null) ?? DEFAULT_MODEL_TYPES;
+  const allowedBases = template.uiModelBase;
+  const filter = useCallback(
+    (model: ModelConfig) => (allowedBases ? allowedBases.includes(model.base) : true),
+    [allowedBases]
+  );
+  const onModelChange = useCallback(
+    (model: ModelConfig | null) =>
+      onChange(
+        model ? { base: model.base, hash: model.hash, key: model.key, name: model.name, type: model.type } : undefined
+      ),
+    [onChange]
+  );
+
+  return (
+    <ModelSelect
+      className="nodrag nowheel"
+      filter={allowedBases ? filter : undefined}
+      id={id ? `${id}-model-combobox` : undefined}
+      invalid={invalid}
+      isClearable={false}
+      modelTypes={modelTypes}
+      size="xs"
+      value={selectedKey}
+      onChange={onModelChange}
+    />
+  );
+};
+
+const SchedulerInput = ({ id, invalid, onChange, template, value }: WorkflowFieldInputProps) => (
+  <SelectInput
+    id={id}
+    invalid={invalid}
+    options={SCHEDULER_OPTIONS}
+    title={template.title}
+    value={value}
+    onChange={onChange}
+  />
+);
+
+let boardOptionsRequest: Promise<GalleryBoard[]> | null = null;
+
+const getBoardOptions = (): Promise<GalleryBoard[]> => {
+  if (!boardOptionsRequest) {
+    boardOptionsRequest = listGalleryBoards()
+      .then((loadedBoards) => loadedBoards.filter((board) => board.kind === 'board'))
+      .catch((error: unknown) => {
+        boardOptionsRequest = null;
+        throw error;
+      });
+  }
+
+  return boardOptionsRequest;
+};
+
+const BoardInput = ({ id, invalid, onChange, template, value }: WorkflowFieldInputProps) => {
+  const [boards, setBoards] = useState<GalleryBoard[]>([]);
+
+  useEffect(() => {
+    let isCancelled = false;
+
+    getBoardOptions()
+      .then((loadedBoards) => {
+        if (!isCancelled) {
+          setBoards(loadedBoards);
+        }
+      })
+      .catch(() => {
+        // Board listing is a convenience; the auto/none sentinels still work.
+      });
+
+    return () => {
+      isCancelled = true;
+    };
+  }, []);
+
+  const selected =
+    value === 'auto' || value === 'none'
+      ? value
+      : typeof (value as { board_id?: unknown } | null)?.board_id === 'string'
+        ? (value as { board_id: string }).board_id
+        : 'auto';
+  const options = useMemo(
+    () => [
+      { label: 'Auto', value: 'auto' },
+      { label: 'None', value: 'none' },
+      ...boards.map((board) => ({ label: board.name, value: board.id })),
+    ],
+    [boards]
+  );
+  const onBoardChange = useCallback(
+    (next: string) => onChange(next === 'auto' || next === 'none' ? next : { board_id: next }),
+    [onChange]
+  );
+
+  return (
+    <SelectInput
+      id={id}
+      invalid={invalid}
+      options={options}
+      title={template.title}
+      value={selected}
+      onChange={onBoardChange}
+    />
+  );
+};
+
+const ImageInput = ({ invalid, onChange, value }: WorkflowFieldInputProps) => {
+  const gallerySelection = useActiveProjectSelector(
+    (project) => getProjectWidgetValues(project, 'gallery').selectedImage as GeneratedImageContract | null | undefined
+  );
+  const imageName =
+    typeof (value as { image_name?: unknown } | null)?.image_name === 'string'
+      ? (value as { image_name: string }).image_name
+      : null;
+  const invalidAriaProps = useMemo(() => (invalid ? { 'aria-invalid': true } : {}), [invalid]);
+  const onUseGallerySelectionClick = useCallback(() => {
+    if (gallerySelection) {
+      onChange({ image_name: gallerySelection.imageName });
+    }
+  }, [gallerySelection, onChange]);
+  const onClearClick = useCallback(() => onChange(undefined), [onChange]);
+
+  return (
+    <HStack
+      boxShadow={invalid ? '0 0 0 1px {colors.red.solid}' : undefined}
+      gap="1.5"
+      minW="0"
+      rounded="sm"
+      w="full"
+      {...invalidAriaProps}
+    >
+      {imageName ? (
+        <Text color="fg.muted" flex="1" fontSize="2xs" minW="0" title={imageName} truncate>
+          {imageName}
+        </Text>
+      ) : (
+        <Text color="fg.subtle" flex="1" fontSize="2xs">
+          No image set
+        </Text>
+      )}
+      <Button
+        className="nodrag"
+        disabled={!gallerySelection}
+        size="2xs"
+        title={gallerySelection ? `Use ${gallerySelection.imageName}` : 'Select an image in the Gallery first.'}
+        variant="outline"
+        onClick={onUseGallerySelectionClick}
+      >
+        Use gallery selection
+      </Button>
+      {imageName ? (
+        <Button className="nodrag" size="2xs" variant="ghost" onClick={onClearClick}>
+          Clear
+        </Button>
+      ) : null}
+    </HStack>
+  );
+};
+
+const COLOR_CHANNELS = ['r', 'g', 'b', 'a'] as const;
+
+const ColorInput = ({ id, invalid, onChange, value }: WorkflowFieldInputProps) => {
+  const color = useMemo(
+    () => (typeof value === 'object' && value !== null ? value : {}) as Partial<Record<string, number>>,
+    [value]
+  );
+
+  return (
+    <HStack gap="1" w="full">
+      {COLOR_CHANNELS.map((channel) => (
+        <ColorChannelInput
+          key={channel}
+          channel={channel}
+          color={color}
+          id={id}
+          invalid={invalid}
+          onChange={onChange}
+        />
+      ))}
+    </HStack>
+  );
+};
+
+const ColorChannelInput = ({
+  channel,
+  color,
+  id,
+  invalid,
+  onChange,
+}: {
+  channel: (typeof COLOR_CHANNELS)[number];
+  color: Partial<Record<string, number>>;
+  id?: string;
+  invalid?: boolean;
+  onChange: (value: unknown) => void;
+}) => {
+  const ariaLabel = useMemo(() => `Color ${channel.toUpperCase()}`, [channel]);
+  const placeholder = channel.toUpperCase();
+  const onInputChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      const parsed = toFiniteNumber(event.currentTarget.value);
+
+      if (parsed !== null) {
+        onChange({
+          a: 255,
+          b: 0,
+          g: 0,
+          r: 0,
+          ...color,
+          [channel]: Math.min(255, Math.max(0, Math.round(parsed))),
+        });
+      }
+    },
+    [channel, color, onChange]
+  );
+
+  return (
+    <Input
+      aria-label={ariaLabel}
+      className="nodrag"
+      id={id ? `${id}-color-${channel}-input` : undefined}
+      max="255"
+      min="0"
+      placeholder={placeholder}
+      size="xs"
+      type="number"
+      value={typeof color[channel] === 'number' ? color[channel] : ''}
+      w="full"
+      {...invalidProps(invalid)}
+      onChange={onInputChange}
+    />
+  );
+};
+
+export const WorkflowFieldInput = (props: WorkflowFieldInputProps) => {
+  switch (props.template.type.name) {
+    case 'StringField':
+      return <StringInput {...props} />;
+    case 'IntegerField':
+    case 'FloatField':
+      return <NumericInput {...props} />;
+    case 'BooleanField':
+      return <BooleanInput {...props} />;
+    case 'EnumField':
+      return <EnumInput {...props} />;
+    case 'ModelIdentifierField':
+      return <ModelIdentifierInput {...props} />;
+    case 'SchedulerField':
+      return <SchedulerInput {...props} />;
+    case 'BoardField':
+      return <BoardInput {...props} />;
+    case 'ImageField':
+      return <ImageInput {...props} />;
+    case 'ColorField':
+      return <ColorInput {...props} />;
+    default:
+      return (
+        <Text color="fg.subtle" fontSize="2xs">
+          Connection only
+        </Text>
+      );
+  }
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/index.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/index.ts
new file mode 100644
index 00000000000..d9c9afa37d3
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/index.ts
@@ -0,0 +1,33 @@
+import type { WidgetManifest } from '@workbench/types';
+
+import { WorkflowIcon } from 'lucide-react';
+
+import {
+  WorkflowDialogHost,
+  WorkflowHeaderActions,
+  WorkflowMenuItems,
+  WorkflowWidgetLabel,
+} from './WorkflowWidgetChrome';
+import { WorkflowWidgetView } from './WorkflowWidgetView';
+
+export const workflowWidgetManifest: WidgetManifest = {
+  allowMultiple: false,
+  allowedRegions: ['center', 'left', 'bottom'],
+  bottomPanel: 'expandable',
+  failurePolicy: { isolateRenderFailure: true, onRegistrationFailure: 'disable' },
+  graphBearing: {
+    defaultGraphId: 'workflow-graph',
+    sourceId: 'workflow',
+    surfaces: ['center', 'left', 'bottom'],
+  },
+  host: WorkflowDialogHost,
+  headerActions: WorkflowHeaderActions,
+  headerMenu: WorkflowMenuItems,
+  icon: WorkflowIcon,
+  id: 'workflow',
+  headerLabel: WorkflowWidgetLabel,
+  label: (t) => t('widgets.labels.workflow'),
+  settingsSection: 'workflow',
+  version: 1,
+  view: WorkflowWidgetView,
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/library/WorkflowLibraryDialog.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/library/WorkflowLibraryDialog.tsx
new file mode 100644
index 00000000000..d187dc9f27c
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/library/WorkflowLibraryDialog.tsx
@@ -0,0 +1,469 @@
+/* eslint-disable react/react-compiler, react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type { ProjectGraphState } from '@workbench/workflows/types';
+
+import { Box, Dialog, HStack, Input, Portal, SegmentGroup, Stack, Tabs, Text } from '@chakra-ui/react';
+import { getApiErrorMessage } from '@workbench/backend/http';
+import { Button, CloseButton, ConfirmDialog, JsonPreview, Scrollable } from '@workbench/components/ui';
+import { documentToPreviewGraph, GraphPreviewFlow } from '@workbench/graph-preview';
+import { useNotify } from '@workbench/useNotify';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import {
+  createLibraryWorkflow,
+  deleteLibraryWorkflow,
+  touchLibraryWorkflowOpenedAt,
+  updateLibraryWorkflow,
+  type WorkflowLibraryCategory,
+  type WorkflowLibraryListItem,
+} from '@workbench/workflows/api';
+import {
+  getCachedWorkflowPage,
+  getLibraryWorkflowCached,
+  invalidateWorkflowLibraryCache,
+  listLibraryWorkflowsCached,
+} from '@workbench/workflows/libraryCache';
+import { parseWorkflowJson, serializeWorkflowJson } from '@workbench/workflows/workflowJson';
+import { useCallback, useEffect, useRef, useState, type ChangeEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Backend workflow library browser: list/search user and default workflows,
+ * preview one (read-only nodes / JSON) before loading it into the project
+ * graph (with an automatic graph-history snapshot of the current graph), and
+ * save the project graph back to the library. Lists serve from the session
+ * cache instantly and revalidate in the background.
+ */
+
+interface WorkflowPreviewState {
+  document: ProjectGraphState;
+  item: WorkflowLibraryListItem;
+  raw: Record<string, unknown>;
+}
+
+const WorkflowPreviewPane = ({
+  isLoadingWorkflow,
+  preview,
+  onBack,
+  onLoad,
+}: {
+  isLoadingWorkflow: boolean;
+  preview: WorkflowPreviewState;
+  onBack: () => void;
+  onLoad: () => void;
+}) => {
+  const [mode, setMode] = useState<'nodes' | 'json'>('nodes');
+  const { t } = useTranslation();
+  const { graph, positionHints } = documentToPreviewGraph(preview.document, t('widgets.labels.workflow'));
+
+  return (
+    <Stack gap="2">
+      <HStack gap="2" justify="space-between">
+        <HStack gap="2" minW="0">
+          <Button size="2xs" variant="ghost" onClick={onBack}>
+            ← Back
+          </Button>
+          <Text fontSize="xs" fontWeight="600" minW="0" truncate>
+            {preview.item.name || 'Untitled Workflow'}
+          </Text>
+        </HStack>
+        <HStack flexShrink={0} gap="2">
+          <SegmentGroup.Root
+            size="xs"
+            value={mode}
+            onValueChange={(event) => setMode(event.value === 'json' ? 'json' : 'nodes')}
+          >
+            <SegmentGroup.Indicator />
+            <SegmentGroup.Items
+              items={[
+                { label: 'Nodes', value: 'nodes' },
+                { label: 'JSON', value: 'json' },
+              ]}
+            />
+          </SegmentGroup.Root>
+          <Button loading={isLoadingWorkflow} size="2xs" onClick={onLoad}>
+            Load
+          </Button>
+        </HStack>
+      </HStack>
+      {mode === 'nodes' ? (
+        <Box h="24rem">
+          <GraphPreviewFlow graph={graph} positionHints={positionHints} />
+        </Box>
+      ) : (
+        <JsonPreview label={`${preview.item.name} JSON`} maxH="24rem" value={preview.raw} />
+      )}
+    </Stack>
+  );
+};
+
+export const WorkflowLibraryDialog = ({
+  isOpen,
+  onOpenChange,
+}: {
+  isOpen: boolean;
+  onOpenChange: (isOpen: boolean) => void;
+}) => {
+  const projectGraph = useActiveProjectSelector((project) => project.projectGraph);
+  const dispatch = useWorkbenchDispatch();
+  const notify = useNotify();
+  const [category, setCategory] = useState<WorkflowLibraryCategory>('user');
+  const [searchTerm, setSearchTerm] = useState('');
+  const [items, setItems] = useState<WorkflowLibraryListItem[]>([]);
+  const [pages, setPages] = useState(0);
+  const [page, setPage] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [loadingWorkflowId, setLoadingWorkflowId] = useState<string | null>(null);
+  const [previewingWorkflowId, setPreviewingWorkflowId] = useState<string | null>(null);
+  const [preview, setPreview] = useState<WorkflowPreviewState | null>(null);
+  const [pendingDelete, setPendingDelete] = useState<WorkflowLibraryListItem | null>(null);
+  const [isSaving, setIsSaving] = useState(false);
+  const hasAutoSwitchedRef = useRef(false);
+  const refreshTokenRef = useRef(0);
+
+  const refresh = useCallback(
+    (nextPage: number) => {
+      const params = { category, page: nextPage, query: searchTerm };
+      const cached = getCachedWorkflowPage(params);
+      const token = (refreshTokenRef.current += 1);
+
+      // A cached page renders instantly; the fetch below only revalidates it.
+      if (cached) {
+        setItems(cached.items);
+        setPage(cached.page);
+        setPages(cached.pages);
+      } else {
+        setIsLoading(true);
+      }
+
+      listLibraryWorkflowsCached(params)
+        .then((result) => {
+          if (token !== refreshTokenRef.current) {
+            return;
+          }
+
+          setItems(result.items);
+          setPage(result.page);
+          setPages(result.pages);
+
+          // A fresh install has no user workflows; land on the bundled
+          // defaults instead of an empty tab. Once per dialog open.
+          if (category === 'user' && result.total === 0 && !searchTerm && !hasAutoSwitchedRef.current) {
+            hasAutoSwitchedRef.current = true;
+            setCategory('default');
+          }
+        })
+        .catch((error: unknown) => {
+          if (cached) {
+            return; // Stale-but-rendered beats an error toast on revalidation.
+          }
+
+          notify.error('Workflow library unavailable', getApiErrorMessage(error, 'Failed to list workflows.'));
+        })
+        .finally(() => {
+          if (token === refreshTokenRef.current) {
+            setIsLoading(false);
+          }
+        });
+    },
+    [category, notify, searchTerm]
+  );
+
+  useEffect(() => {
+    if (isOpen) {
+      refresh(0);
+    } else {
+      hasAutoSwitchedRef.current = false;
+      setPreview(null);
+    }
+  }, [isOpen, refresh]);
+
+  const fetchParsedWorkflow = async (item: WorkflowLibraryListItem) => {
+    const raw = await getLibraryWorkflowCached(item.workflow_id);
+    const { document, warnings } = parseWorkflowJson(raw);
+
+    return { document, raw, warnings };
+  };
+
+  const applyLoadedWorkflow = (item: WorkflowLibraryListItem, document: ProjectGraphState, warnings: string[]) => {
+    dispatch({ document, label: `Loaded "${item.name}" from library`, type: 'replaceProjectGraph' });
+
+    for (const warning of warnings) {
+      notify.info('Workflow load warning', warning);
+    }
+
+    void touchLibraryWorkflowOpenedAt(item.workflow_id).catch(() => {
+      // Recency bookkeeping only; loading already succeeded.
+    });
+    onOpenChange(false);
+  };
+
+  const loadWorkflow = async (item: WorkflowLibraryListItem) => {
+    setLoadingWorkflowId(item.workflow_id);
+
+    try {
+      const { document, warnings } = await fetchParsedWorkflow(item);
+
+      applyLoadedWorkflow(item, document, warnings);
+    } catch (error) {
+      notify.error('Failed to load workflow', getApiErrorMessage(error, `Could not load "${item.name}".`));
+    } finally {
+      setLoadingWorkflowId(null);
+    }
+  };
+
+  const previewWorkflow = async (item: WorkflowLibraryListItem) => {
+    setPreviewingWorkflowId(item.workflow_id);
+
+    try {
+      const { document, raw } = await fetchParsedWorkflow(item);
+
+      setPreview({ document, item, raw });
+    } catch (error) {
+      notify.error('Failed to preview workflow', getApiErrorMessage(error, `Could not preview "${item.name}".`));
+    } finally {
+      setPreviewingWorkflowId(null);
+    }
+  };
+
+  const saveToLibrary = async (asNew: boolean) => {
+    setIsSaving(true);
+
+    try {
+      const serialized = serializeWorkflowJson(projectGraph);
+
+      if (!asNew && projectGraph.libraryWorkflowId) {
+        await updateLibraryWorkflow(projectGraph.libraryWorkflowId, serialized);
+        notify.success('Workflow saved', `Updated "${projectGraph.name || 'Untitled Workflow'}" in the library.`);
+      } else {
+        const workflowId = await createLibraryWorkflow(serialized);
+
+        dispatch({ libraryWorkflowId: workflowId, type: 'setProjectGraphLibraryBinding' });
+        notify.success('Workflow saved', `Saved "${projectGraph.name || 'Untitled Workflow'}" to the library.`);
+      }
+
+      invalidateWorkflowLibraryCache();
+      refresh(page);
+    } catch (error) {
+      notify.error('Failed to save workflow', getApiErrorMessage(error, 'The workflow could not be saved.'));
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  return (
+    <>
+      <Dialog.Root placement="center" open={isOpen} size="lg" onOpenChange={(event) => onOpenChange(event.open)}>
+        <Portal>
+          <Dialog.Backdrop />
+          <Dialog.Positioner>
+            <Dialog.Content bg="bg.subtle" borderColor="border.subtle" borderWidth="1px" color="fg">
+              <Dialog.Header>
+                <Dialog.Title fontSize="sm" fontWeight="700">
+                  Workflow Library
+                </Dialog.Title>
+              </Dialog.Header>
+              <Dialog.Body>
+                {preview ? (
+                  <WorkflowPreviewPane
+                    isLoadingWorkflow={loadingWorkflowId === preview.item.workflow_id}
+                    preview={preview}
+                    onBack={() => setPreview(null)}
+                    onLoad={() => applyLoadedWorkflow(preview.item, preview.document, [])}
+                  />
+                ) : (
+                  <Stack gap="3">
+                    <HStack gap="2">
+                      <Tabs.Root
+                        size="sm"
+                        value={category}
+                        variant="enclosed"
+                        onValueChange={(event) => setCategory(event.value as WorkflowLibraryCategory)}
+                      >
+                        <Tabs.List>
+                          <Tabs.Trigger fontSize="xs" value="user">
+                            Yours
+                          </Tabs.Trigger>
+                          <Tabs.Trigger fontSize="xs" value="default">
+                            Defaults
+                          </Tabs.Trigger>
+                        </Tabs.List>
+                      </Tabs.Root>
+                      <Input
+                        aria-label="Search workflows"
+                        placeholder="Search workflows…"
+                        size="xs"
+                        value={searchTerm}
+                        onChange={(event: ChangeEvent<HTMLInputElement>) => setSearchTerm(event.currentTarget.value)}
+                      />
+                    </HStack>
+                    <Scrollable label="Workflow library results" maxH="20rem" minH="8rem">
+                      <Stack gap="1" minW="0" w="full">
+                        {items.map((item) => (
+                          <Box
+                            key={item.workflow_id}
+                            _hover={{ bg: 'bg.emphasized' }}
+                            alignItems="center"
+                            display="grid"
+                            gap="2"
+                            gridTemplateColumns={
+                              category === 'user' ? 'minmax(0, 1fr) auto auto auto' : 'minmax(0, 1fr) auto auto'
+                            }
+                            minW="0"
+                            overflow="hidden"
+                            px="1"
+                            rounded="md"
+                            transition="background var(--wb-motion-duration-fast) ease"
+                            w="full"
+                          >
+                            <Box
+                              as="button"
+                              _focusVisible={{ outline: '2px solid {colors.accent.solid}', outlineOffset: '-2px' }}
+                              aria-disabled={previewingWorkflowId !== null}
+                              cursor="pointer"
+                              flex="1"
+                              minW="0"
+                              px="1"
+                              py="1.5"
+                              rounded="md"
+                              textAlign="start"
+                              title={`Preview "${item.name || 'Untitled Workflow'}"`}
+                              onClick={() => {
+                                if (previewingWorkflowId === null) {
+                                  void previewWorkflow(item);
+                                }
+                              }}
+                            >
+                              <Stack gap="0" minW="0">
+                                <Text fontSize="xs" fontWeight="600" truncate>
+                                  {item.name || 'Untitled Workflow'}
+                                </Text>
+                                {item.description ? (
+                                  <Text color="fg.subtle" fontSize="2xs" truncate>
+                                    {item.description}
+                                  </Text>
+                                ) : null}
+                              </Stack>
+                            </Box>
+                            <Button
+                              flexShrink={0}
+                              loading={previewingWorkflowId === item.workflow_id}
+                              size="2xs"
+                              variant="outline"
+                              onClick={() => void previewWorkflow(item)}
+                            >
+                              Preview
+                            </Button>
+                            <Button
+                              flexShrink={0}
+                              loading={loadingWorkflowId === item.workflow_id}
+                              size="2xs"
+                              variant="outline"
+                              onClick={() => void loadWorkflow(item)}
+                            >
+                              Load
+                            </Button>
+                            {category === 'user' ? (
+                              <Button
+                                colorPalette="red"
+                                flexShrink={0}
+                                size="2xs"
+                                variant="ghost"
+                                onClick={() => setPendingDelete(item)}
+                              >
+                                Delete
+                              </Button>
+                            ) : null}
+                          </Box>
+                        ))}
+                        {!isLoading && items.length === 0 ? (
+                          <Text color="fg.subtle" fontSize="2xs" px="2" py="4" textAlign="center">
+                            {category === 'user'
+                              ? 'No saved workflows yet. Save the project graph below to start your library.'
+                              : 'No default workflows are installed on this backend.'}
+                          </Text>
+                        ) : null}
+                        {isLoading ? (
+                          <Text color="fg.subtle" fontSize="2xs" px="2" py="1.5">
+                            Loading workflows…
+                          </Text>
+                        ) : null}
+                      </Stack>
+                    </Scrollable>
+                    {pages > 1 ? (
+                      <HStack gap="2" justify="center">
+                        <Button disabled={page === 0} size="2xs" variant="ghost" onClick={() => refresh(page - 1)}>
+                          Previous
+                        </Button>
+                        <Text color="fg.subtle" fontSize="2xs">
+                          Page {page + 1} of {pages}
+                        </Text>
+                        <Button
+                          disabled={page >= pages - 1}
+                          size="2xs"
+                          variant="ghost"
+                          onClick={() => refresh(page + 1)}
+                        >
+                          Next
+                        </Button>
+                      </HStack>
+                    ) : null}
+                    <Box borderColor="border.subtle" borderTopWidth="1px" pt="3">
+                      <HStack gap="2" justify="space-between">
+                        <Text color="fg.muted" fontSize="2xs" minW="0" truncate>
+                          Project graph: {projectGraph.name || 'Untitled Workflow'}
+                          {projectGraph.libraryWorkflowId ? ' (linked to library)' : ''}
+                        </Text>
+                        <HStack flexShrink={0} gap="2">
+                          {projectGraph.libraryWorkflowId ? (
+                            <Button
+                              loading={isSaving}
+                              size="2xs"
+                              variant="outline"
+                              onClick={() => void saveToLibrary(false)}
+                            >
+                              Save
+                            </Button>
+                          ) : null}
+                          <Button
+                            loading={isSaving}
+                            size="2xs"
+                            variant="outline"
+                            onClick={() => void saveToLibrary(true)}
+                          >
+                            Save as new
+                          </Button>
+                        </HStack>
+                      </HStack>
+                    </Box>
+                  </Stack>
+                )}
+              </Dialog.Body>
+              <Dialog.CloseTrigger asChild>
+                <CloseButton color="fg.muted" size="sm" />
+              </Dialog.CloseTrigger>
+            </Dialog.Content>
+          </Dialog.Positioner>
+        </Portal>
+      </Dialog.Root>
+      <ConfirmDialog
+        body={`Delete "${pendingDelete?.name || 'Untitled Workflow'}" from the workflow library? This cannot be undone.`}
+        confirmLabel="Delete"
+        isOpen={pendingDelete !== null}
+        title="Delete workflow"
+        onClose={() => setPendingDelete(null)}
+        onConfirm={async () => {
+          if (!pendingDelete) {
+            return;
+          }
+
+          try {
+            await deleteLibraryWorkflow(pendingDelete.workflow_id);
+            invalidateWorkflowLibraryCache();
+            refresh(page);
+          } catch (error) {
+            notify.error('Failed to delete workflow', getApiErrorMessage(error, 'The workflow could not be deleted.'));
+          }
+        }}
+      />
+    </>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/FormBuilderTab.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/FormBuilderTab.tsx
new file mode 100644
index 00000000000..ae6ab12b948
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/FormBuilderTab.tsx
@@ -0,0 +1,582 @@
+/* oxlint-disable react-perf/jsx-no-new-object-as-prop, react-perf/jsx-no-new-function-as-prop, react-perf/jsx-no-new-array-as-prop, react-perf/jsx-no-jsx-as-prop */
+import type {
+  ContainerFormElement,
+  InvocationTemplates,
+  NodeFieldFormElement,
+  ProjectGraphState,
+  WorkflowFormElement,
+} from '@workbench/workflows/types';
+
+import { Box, HStack, Icon, Input, Menu, Portal, Separator, Stack, Text, Textarea } from '@chakra-ui/react';
+import { Button, IconButton } from '@workbench/components/ui';
+import { getWorkflowNodeChromeProps } from '@workbench/widgets/workflow/editor/nodeChrome';
+import { requestNodeSelection, workflowSelectionStore } from '@workbench/widgets/workflow/editor/selectionStore';
+import { FieldDescriptionPopover } from '@workbench/widgets/workflow/fields/FieldDescriptionPopover';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { getResolvedWorkflowEdges } from '@workbench/workflows/connectors';
+import { getFormChildren } from '@workbench/workflows/document';
+import { getWorkflowFieldInvalidReason } from '@workbench/workflows/fields';
+import { useInvocationTemplatesSelector, type InvocationTemplatesSnapshot } from '@workbench/workflows/templates';
+import { isInvocationNode } from '@workbench/workflows/types';
+import {
+  Columns2Icon,
+  CrosshairIcon,
+  GripVerticalIcon,
+  HeadingIcon,
+  InfoIcon,
+  MinusIcon,
+  PlusIcon,
+  Rows2Icon,
+  TextIcon,
+  XIcon,
+} from 'lucide-react';
+import { createContext, use, useMemo, useState, type ChangeEvent, type DragEvent, type ReactNode } from 'react';
+
+import { NodeFieldControl, useNodeFieldBinding } from './NodeFieldControl';
+
+/**
+ * The form builder: edit mode of the Linear UI. Every element renders as a
+ * card with its own title bar — type label on the left, actions on the right,
+ * content below — mirroring the legacy builder. Cards reorder and reparent by
+ * dragging their title bar (drop indicators above/below, containers accept
+ * drops into their body). All edits go through the project graph document
+ * reducer.
+ */
+
+interface BuilderDndContextValue {
+  draggingElementId: string | null;
+  setDraggingElementId: (elementId: string | null) => void;
+}
+
+const BuilderDndContext = createContext<BuilderDndContextValue>({
+  draggingElementId: null,
+  setDraggingElementId: () => undefined,
+});
+
+type DropEdge = 'above' | 'below';
+
+/** A builder card: typed title bar (drag handle + actions) over the element's content. */
+const BuilderCard = ({
+  children,
+  element,
+  extraActions,
+  index,
+  isHovered,
+  isInvalid,
+  isSelected,
+  parentId,
+  title,
+}: {
+  children: ReactNode;
+  element: WorkflowFormElement;
+  extraActions?: ReactNode;
+  index: number;
+  isHovered?: boolean;
+  isInvalid?: boolean;
+  isSelected?: boolean;
+  parentId: string;
+  title: string;
+}) => {
+  const dispatch = useWorkbenchDispatch();
+  const { draggingElementId, setDraggingElementId } = use(BuilderDndContext);
+  const [isDragArmed, setIsDragArmed] = useState(false);
+  const [dropEdge, setDropEdge] = useState<DropEdge | null>(null);
+  const isDropTarget = draggingElementId !== null && draggingElementId !== element.id;
+
+  const onDragOver = (event: DragEvent<HTMLDivElement>) => {
+    if (!isDropTarget) {
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+
+    const bounds = event.currentTarget.getBoundingClientRect();
+
+    setDropEdge(event.clientY < bounds.top + bounds.height / 2 ? 'above' : 'below');
+  };
+
+  const onDrop = (event: DragEvent<HTMLDivElement>) => {
+    if (!isDropTarget || !draggingElementId || !dropEdge) {
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    dispatch({
+      action: {
+        elementId: draggingElementId,
+        index: dropEdge === 'above' ? index : index + 1,
+        parentId,
+        type: 'moveFormElementTo',
+      },
+      type: 'applyProjectGraphAction',
+    });
+    setDropEdge(null);
+  };
+
+  return (
+    <Box
+      draggable={isDragArmed}
+      flex="1"
+      minW="0"
+      opacity={draggingElementId === element.id ? 0.4 : 1}
+      position="relative"
+      onDragEnd={() => {
+        setDraggingElementId(null);
+        setIsDragArmed(false);
+      }}
+      onDragLeave={() => setDropEdge(null)}
+      onDragOver={onDragOver}
+      onDragStart={(event: DragEvent<HTMLDivElement>) => {
+        event.stopPropagation();
+        event.dataTransfer.effectAllowed = 'move';
+        setDraggingElementId(element.id);
+      }}
+      onDrop={onDrop}
+    >
+      {dropEdge ? (
+        <Box
+          bg="accent.solid"
+          h="2px"
+          left="0"
+          pointerEvents="none"
+          position="absolute"
+          right="0"
+          rounded="full"
+          zIndex="1"
+          {...(dropEdge === 'above' ? { top: '-1px' } : { bottom: '-1px' })}
+        />
+      ) : null}
+      <Box
+        overflow="hidden"
+        position="relative"
+        rounded="md"
+        {...getWorkflowNodeChromeProps({ invalid: Boolean(isInvalid), selected: Boolean(isHovered || isSelected) })}
+      >
+        <HStack
+          bg="bg.muted"
+          borderBottomWidth="1px"
+          borderColor="border.subtle"
+          cursor="grab"
+          gap="1"
+          px="1.5"
+          py="0.5"
+          position="relative"
+          zIndex="2"
+          _active={{ cursor: 'grabbing' }}
+          onPointerDown={() => setIsDragArmed(true)}
+          onPointerUp={() => setIsDragArmed(false)}
+        >
+          <Icon as={GripVerticalIcon} boxSize="3" color="fg.subtle" flexShrink={0} />
+          <Text color="fg.muted" fontSize="2xs" fontWeight="600" minW="0" truncate>
+            {title}
+          </Text>
+          <Box flex="1" />
+          <HStack flexShrink={0} gap="0" onPointerDown={(event) => event.stopPropagation()}>
+            {extraActions}
+            <IconButton
+              aria-label="Remove from form"
+              size="2xs"
+              variant="ghost"
+              onClick={() =>
+                dispatch({
+                  action: { elementId: element.id, type: 'removeFormElement' },
+                  type: 'applyProjectGraphAction',
+                })
+              }
+            >
+              <Icon as={XIcon} boxSize="3" />
+            </IconButton>
+          </HStack>
+        </HStack>
+        <Box p="2" position="relative" zIndex="2">
+          {children}
+        </Box>
+      </Box>
+    </Box>
+  );
+};
+
+/** Drop zone covering a container's body, appending at the end. Doubles as the empty-container hint. */
+const ContainerDropZone = ({ container, isEmpty }: { container: ContainerFormElement; isEmpty: boolean }) => {
+  const dispatch = useWorkbenchDispatch();
+  const { draggingElementId } = use(BuilderDndContext);
+  const [isActive, setIsActive] = useState(false);
+  const canDrop = draggingElementId !== null && draggingElementId !== container.id;
+
+  if (!canDrop && !isEmpty) {
+    return null;
+  }
+
+  return (
+    <Box
+      alignSelf="stretch"
+      borderColor={isActive ? 'accent.solid' : 'border.subtle'}
+      borderStyle="dashed"
+      borderWidth="1px"
+      color="fg.subtle"
+      flex={isEmpty ? '1' : undefined}
+      fontSize="2xs"
+      px="2"
+      py="1.5"
+      rounded="md"
+      textAlign="center"
+      onDragLeave={() => setIsActive(false)}
+      onDragOver={(event: DragEvent<HTMLDivElement>) => {
+        if (canDrop) {
+          event.preventDefault();
+          event.stopPropagation();
+          setIsActive(true);
+        }
+      }}
+      onDrop={(event: DragEvent<HTMLDivElement>) => {
+        if (!canDrop || !draggingElementId) {
+          return;
+        }
+
+        event.preventDefault();
+        event.stopPropagation();
+        dispatch({
+          action: {
+            elementId: draggingElementId,
+            index: container.data.children.length,
+            parentId: container.id,
+            type: 'moveFormElementTo',
+          },
+          type: 'applyProjectGraphAction',
+        });
+        setIsActive(false);
+      }}
+    >
+      {canDrop ? 'Drop here' : 'Empty container — drag elements here'}
+    </Box>
+  );
+};
+
+/** The shared description popover, bound through the form element. */
+const FieldDescriptionAction = ({
+  element,
+  projectGraph,
+}: {
+  element: NodeFieldFormElement;
+  projectGraph: ProjectGraphState;
+}) => {
+  const { fieldName, instance, nodeId, template } = useNodeFieldBinding(element, projectGraph);
+
+  if (!template) {
+    return null;
+  }
+
+  return (
+    <FieldDescriptionPopover
+      description={instance?.description}
+      fieldName={fieldName}
+      nodeId={nodeId}
+      templateDescription={template.description}
+    />
+  );
+};
+
+const BuilderElement = ({
+  element,
+  index,
+  hoveredNodeId,
+  parentId,
+  projectGraph,
+  invalidElementIds,
+  selectedNodeIds,
+}: {
+  element: WorkflowFormElement;
+  index: number;
+  hoveredNodeId: string | null;
+  invalidElementIds: Set<string>;
+  parentId: string;
+  projectGraph: ProjectGraphState;
+  selectedNodeIds: Set<string>;
+}) => {
+  const dispatch = useWorkbenchDispatch();
+
+  switch (element.type) {
+    case 'container': {
+      const isRow = element.data.layout === 'row';
+
+      return (
+        <BuilderCard
+          element={element}
+          extraActions={
+            <IconButton
+              aria-label={isRow ? 'Switch container to column layout' : 'Switch container to row layout'}
+              size="2xs"
+              title={isRow ? 'Switch to column layout' : 'Switch to row layout'}
+              variant="ghost"
+              onClick={() =>
+                dispatch({
+                  action: { elementId: element.id, layout: isRow ? 'column' : 'row', type: 'setContainerLayout' },
+                  type: 'applyProjectGraphAction',
+                })
+              }
+            >
+              <Icon as={isRow ? Rows2Icon : Columns2Icon} boxSize="3" />
+            </IconButton>
+          }
+          index={index}
+          parentId={parentId}
+          title={`Container (${element.data.layout} layout)`}
+        >
+          <Stack align={isRow ? 'stretch' : undefined} direction={isRow ? 'row' : 'column'} gap="2" w="full">
+            {getFormChildren(projectGraph.form, element.id).map((child, childIndex) => (
+              <BuilderElement
+                key={child.id}
+                element={child}
+                hoveredNodeId={hoveredNodeId}
+                invalidElementIds={invalidElementIds}
+                index={childIndex}
+                parentId={element.id}
+                projectGraph={projectGraph}
+                selectedNodeIds={selectedNodeIds}
+              />
+            ))}
+            <ContainerDropZone container={element} isEmpty={element.data.children.length === 0} />
+          </Stack>
+        </BuilderCard>
+      );
+    }
+    case 'node-field': {
+      return (
+        <BuilderCard
+          element={element}
+          extraActions={
+            <>
+              <IconButton
+                aria-label="Zoom to node in editor"
+                size="2xs"
+                title="Zoom to node in the Workflow editor"
+                variant="ghost"
+                onClick={() => {
+                  dispatch({ region: 'center', type: 'selectRegionWidget', widgetId: 'workflow' });
+                  requestNodeSelection([element.data.fieldIdentifier.nodeId]);
+                }}
+              >
+                <Icon as={CrosshairIcon} boxSize="3" />
+              </IconButton>
+              <FieldDescriptionAction element={element} projectGraph={projectGraph} />
+              <IconButton
+                aria-label="Toggle description"
+                color={element.data.showDescription ? 'accent.solid' : undefined}
+                size="2xs"
+                title={element.data.showDescription ? 'Hide field description' : 'Show field description'}
+                variant="ghost"
+                onClick={() =>
+                  dispatch({
+                    action: {
+                      elementId: element.id,
+                      showDescription: !element.data.showDescription,
+                      type: 'setNodeFieldShowDescription',
+                    },
+                    type: 'applyProjectGraphAction',
+                  })
+                }
+              >
+                <Icon as={InfoIcon} boxSize="3" />
+              </IconButton>
+            </>
+          }
+          index={index}
+          isHovered={element.data.fieldIdentifier.nodeId === hoveredNodeId}
+          isInvalid={invalidElementIds.has(element.id)}
+          isSelected={selectedNodeIds.has(element.data.fieldIdentifier.nodeId)}
+          parentId={parentId}
+          title="Node Field"
+        >
+          <NodeFieldControl element={element} isLabelEditable projectGraph={projectGraph} />
+        </BuilderCard>
+      );
+    }
+    case 'heading': {
+      return (
+        <BuilderCard element={element} index={index} parentId={parentId} title="Heading">
+          <Input
+            aria-label="Form heading"
+            fontSize="sm"
+            fontWeight="700"
+            placeholder="Heading"
+            size="xs"
+            value={element.data.content}
+            variant="flushed"
+            onChange={(event: ChangeEvent<HTMLInputElement>) =>
+              dispatch({
+                action: { content: event.currentTarget.value, elementId: element.id, type: 'setFormElementContent' },
+                type: 'applyProjectGraphAction',
+              })
+            }
+          />
+        </BuilderCard>
+      );
+    }
+    case 'text': {
+      return (
+        <BuilderCard element={element} index={index} parentId={parentId} title="Text">
+          <Textarea
+            aria-label="Form text"
+            color="fg.muted"
+            fontSize="2xs"
+            minH="2.5rem"
+            placeholder="Text"
+            resize="vertical"
+            size="xs"
+            value={element.data.content}
+            variant="flushed"
+            onChange={(event: ChangeEvent<HTMLTextAreaElement>) =>
+              dispatch({
+                action: { content: event.currentTarget.value, elementId: element.id, type: 'setFormElementContent' },
+                type: 'applyProjectGraphAction',
+              })
+            }
+          />
+        </BuilderCard>
+      );
+    }
+    case 'divider': {
+      return (
+        <BuilderCard element={element} index={index} parentId={parentId} title="Divider">
+          <Separator borderColor="border.subtle" />
+        </BuilderCard>
+      );
+    }
+  }
+};
+
+const AddElementMenu = () => {
+  const dispatch = useWorkbenchDispatch();
+  const add = (elementType: 'divider' | 'heading' | 'text' | 'container', layout?: 'row' | 'column') =>
+    dispatch({ action: { elementType, layout, type: 'addFormElement' }, type: 'applyProjectGraphAction' });
+
+  return (
+    <Menu.Root positioning={{ placement: 'bottom-start' }}>
+      <Menu.Trigger asChild>
+        <Button size="2xs" variant="ghost">
+          <Icon as={PlusIcon} boxSize="3" />
+          Add form element
+        </Button>
+      </Menu.Trigger>
+      <Portal>
+        <Menu.Positioner>
+          <Menu.Content minW="11rem">
+            <Menu.Item value="heading" onClick={() => add('heading')}>
+              <Icon as={HeadingIcon} boxSize="3" />
+              Heading
+            </Menu.Item>
+            <Menu.Item value="text" onClick={() => add('text')}>
+              <Icon as={TextIcon} boxSize="3" />
+              Text
+            </Menu.Item>
+            <Menu.Item value="divider" onClick={() => add('divider')}>
+              <Icon as={MinusIcon} boxSize="3" />
+              Divider
+            </Menu.Item>
+            <Menu.Item value="container-column" onClick={() => add('container', 'column')}>
+              <Icon as={Columns2Icon} boxSize="3" />
+              Container (column)
+            </Menu.Item>
+            <Menu.Item value="container-row" onClick={() => add('container', 'row')}>
+              <Icon as={Rows2Icon} boxSize="3" />
+              Container (row)
+            </Menu.Item>
+          </Menu.Content>
+        </Menu.Positioner>
+      </Portal>
+    </Menu.Root>
+  );
+};
+
+const getInvalidNodeFieldElementIds = (
+  projectGraph: ProjectGraphState,
+  templatesStatus: InvocationTemplatesSnapshot['status'],
+  templates: InvocationTemplates
+): Set<string> => {
+  const invalidElementIds = new Set<string>();
+
+  if (templatesStatus !== 'loaded') {
+    return invalidElementIds;
+  }
+
+  const connectedInputKeys = new Set(
+    getResolvedWorkflowEdges(projectGraph.nodes, projectGraph.edges).map(
+      (edge) => `${edge.target}:${edge.targetHandle}`
+    )
+  );
+
+  for (const element of Object.values(projectGraph.form.elements)) {
+    if (element.type !== 'node-field') {
+      continue;
+    }
+
+    const { fieldName, nodeId } = element.data.fieldIdentifier;
+    const node = projectGraph.nodes.find((candidate) => candidate.id === nodeId);
+
+    if (!node || !isInvocationNode(node)) {
+      invalidElementIds.add(element.id);
+      continue;
+    }
+
+    const template = templates[node.data.type]?.inputs[fieldName];
+
+    if (!template) {
+      invalidElementIds.add(element.id);
+      continue;
+    }
+
+    const isConnected = connectedInputKeys.has(`${nodeId}:${fieldName}`);
+
+    if (getWorkflowFieldInvalidReason({ isConnected, template, value: node.data.inputs[fieldName]?.value }) !== null) {
+      invalidElementIds.add(element.id);
+    }
+  }
+
+  return invalidElementIds;
+};
+
+export const FormBuilderTab = ({ projectGraph }: { projectGraph: ProjectGraphState }) => {
+  const templatesStatus = useInvocationTemplatesSelector((snapshot) => snapshot.status);
+  const templates = useInvocationTemplatesSelector((snapshot) => snapshot.templates);
+  const hoveredNodeId = workflowSelectionStore.useSelector((snapshot) => snapshot.hoveredNodeId);
+  const selectedNodeIds = workflowSelectionStore.useSelector((snapshot) => snapshot.selectedNodeIds);
+  const [draggingElementId, setDraggingElementId] = useState<string | null>(null);
+  const dndContextValue = useMemo<BuilderDndContextValue>(
+    () => ({ draggingElementId, setDraggingElementId }),
+    [draggingElementId]
+  );
+  const selectedNodeIdSet = useMemo(() => new Set(selectedNodeIds), [selectedNodeIds]);
+  const invalidElementIds = useMemo(
+    () => getInvalidNodeFieldElementIds(projectGraph, templatesStatus, templates),
+    [projectGraph, templatesStatus, templates]
+  );
+  const rootChildren = getFormChildren(projectGraph.form);
+
+  return (
+    <BuilderDndContext value={dndContextValue}>
+      <Stack gap="2" p="3" w="full">
+        {rootChildren.length === 0 ? (
+          <Text color="fg.subtle" fontSize="2xs">
+            The form is empty. Pin fields from the Workflow editor's nodes, then arrange them here — drag card title
+            bars to reorder, drop them into containers, and add headings or dividers below.
+          </Text>
+        ) : null}
+        {rootChildren.map((element, index) => (
+          <BuilderElement
+            key={element.id}
+            element={element}
+            hoveredNodeId={hoveredNodeId}
+            invalidElementIds={invalidElementIds}
+            index={index}
+            parentId={projectGraph.form.rootElementId}
+            projectGraph={projectGraph}
+            selectedNodeIds={selectedNodeIdSet}
+          />
+        ))}
+        <AddElementMenu />
+      </Stack>
+    </BuilderDndContext>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/LinearFormView.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/LinearFormView.tsx
new file mode 100644
index 00000000000..2ad8f9c5c29
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/LinearFormView.tsx
@@ -0,0 +1,74 @@
+import type { ProjectGraphState, WorkflowFormElement } from '@workbench/workflows/types';
+
+import { Separator, Stack, Text } from '@chakra-ui/react';
+import { Button } from '@workbench/components/ui';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { getFormChildren } from '@workbench/workflows/document';
+import { useCallback } from 'react';
+
+import { NodeFieldControl } from './NodeFieldControl';
+
+/**
+ * The Linear UI's view mode: the form rendered as clean, runnable controls —
+ * field values stay editable, the form structure does not.
+ */
+
+const ViewElement = ({ element, projectGraph }: { element: WorkflowFormElement; projectGraph: ProjectGraphState }) => {
+  switch (element.type) {
+    case 'container':
+      return (
+        <Stack direction={element.data.layout === 'row' ? 'row' : 'column'} gap="3">
+          {getFormChildren(projectGraph.form, element.id).map((child) => (
+            <ViewElement key={child.id} element={child} projectGraph={projectGraph} />
+          ))}
+        </Stack>
+      );
+    case 'node-field':
+      return <NodeFieldControl element={element} projectGraph={projectGraph} />;
+    case 'heading':
+      return (
+        <Text fontSize="sm" fontWeight="700">
+          {element.data.content}
+        </Text>
+      );
+    case 'text':
+      return (
+        <Text color="fg.muted" fontSize="2xs" whiteSpace="pre-wrap">
+          {element.data.content}
+        </Text>
+      );
+    case 'divider':
+      return <Separator borderColor="border.subtle" />;
+  }
+};
+
+export const LinearFormView = ({ projectGraph }: { projectGraph: ProjectGraphState }) => {
+  const dispatch = useWorkbenchDispatch();
+  const rootChildren = getFormChildren(projectGraph.form);
+  const onOpenWorkflowEditorClick = useCallback(
+    () => dispatch({ region: 'center', type: 'selectRegionWidget', widgetId: 'workflow' }),
+    [dispatch]
+  );
+
+  if (rootChildren.length === 0) {
+    return (
+      <Stack gap="2" px="1" py="1">
+        <Text color="fg.subtle" fontSize="2xs">
+          No fields are exposed yet. Pin fields in the Workflow editor, or switch to Edit mode to build this form — it
+          maps the project graph to simple controls, like the legacy Linear UI.
+        </Text>
+        <Button size="2xs" variant="outline" w="fit-content" onClick={onOpenWorkflowEditorClick}>
+          Open Workflow Editor
+        </Button>
+      </Stack>
+    );
+  }
+
+  return (
+    <Stack gap="3" p="3">
+      {rootChildren.map((element) => (
+        <ViewElement key={element.id} element={element} projectGraph={projectGraph} />
+      ))}
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/NodeFieldControl.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/NodeFieldControl.tsx
new file mode 100644
index 00000000000..82a1dcc706f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/NodeFieldControl.tsx
@@ -0,0 +1,190 @@
+import type { NodeFieldFormElement, ProjectGraphState } from '@workbench/workflows/types';
+
+import { Alert, Field, HStack, Icon, Input, Stack, Text } from '@chakra-ui/react';
+import { FieldLabel, IconButton, Tooltip } from '@workbench/components/ui';
+import { WorkflowFieldInput } from '@workbench/widgets/workflow/fields/WorkflowFieldInput';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { getResolvedWorkflowEdges } from '@workbench/workflows/connectors';
+import {
+  cloneWorkflowFieldDefault,
+  getWorkflowFieldInvalidReason,
+  isDirectInputField,
+  isWorkflowFieldValueDefault,
+} from '@workbench/workflows/fields';
+import { useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import { isInvocationNode } from '@workbench/workflows/types';
+import { RotateCcwIcon } from 'lucide-react';
+import { useCallback, useMemo, useState, type ChangeEvent } from 'react';
+
+/**
+ * One exposed node field, shared by the Linear UI's view mode and the form
+ * builder: label (optionally editable), optional description, and the live
+ * input — or a note when the field is driven by a graph connection.
+ */
+/** Resolves a form element's node, field instance, and input template against the document. */
+export const useNodeFieldBinding = (element: NodeFieldFormElement, projectGraph: ProjectGraphState) => {
+  const templates = useInvocationTemplatesSelector((snapshot) => snapshot.templates);
+  const { fieldName, nodeId } = element.data.fieldIdentifier;
+  const node = projectGraph.nodes.find((candidate) => candidate.id === nodeId);
+  const invocationNode = node && isInvocationNode(node) ? node : null;
+  const template = invocationNode ? templates[invocationNode.data.type]?.inputs[fieldName] : undefined;
+  const instance = invocationNode?.data.inputs[fieldName];
+  const nodeContext = invocationNode
+    ? invocationNode.data.label || templates[invocationNode.data.type]?.title || invocationNode.data.type
+    : '';
+
+  return { fieldName, instance, invocationNode, nodeContext, nodeId, template };
+};
+
+export const NodeFieldControl = ({
+  element,
+  isLabelEditable = false,
+  projectGraph,
+}: {
+  element: NodeFieldFormElement;
+  /** Builder mode renders the label as an input bound to the field instance label. */
+  isLabelEditable?: boolean;
+  projectGraph: ProjectGraphState;
+}) => {
+  const dispatch = useWorkbenchDispatch();
+  const { fieldName, instance, invocationNode, nodeContext, nodeId, template } = useNodeFieldBinding(
+    element,
+    projectGraph
+  );
+  // While the label input is focused it edits a draft seeded from the
+  // *displayed* label, so an unset override starts from the template title
+  // instead of an empty box.
+  const [draftLabel, setDraftLabel] = useState<string | null>(null);
+
+  const isConnected = getResolvedWorkflowEdges(projectGraph.nodes, projectGraph.edges).some(
+    (edge) => edge.target === nodeId && edge.targetHandle === fieldName
+  );
+  const label = instance?.label || template?.title || '';
+  const description = instance?.description || template?.description;
+  const invalidReason = template
+    ? getWorkflowFieldInvalidReason({ isConnected, template, value: instance?.value })
+    : null;
+  const isInvalid = invalidReason !== null;
+  const canReset =
+    !!template &&
+    !isConnected &&
+    isDirectInputField(template) &&
+    !isWorkflowFieldValueDefault(template, instance?.value);
+  const labelInputId = `${element.id}-label-input`;
+  const valueInputId = `${element.id}-value`;
+  const onResetClick = useCallback(
+    () =>
+      dispatch({
+        action: {
+          fieldName,
+          nodeId,
+          type: 'setFieldValue',
+          value: template ? cloneWorkflowFieldDefault(template) : undefined,
+        },
+        type: 'applyProjectGraphAction',
+      }),
+    [dispatch, fieldName, nodeId, template]
+  );
+  const onLabelBlur = useCallback(() => setDraftLabel(null), []);
+  const onLabelChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      setDraftLabel(event.currentTarget.value);
+      dispatch({
+        action: { fieldName, label: event.currentTarget.value, nodeId, type: 'setFieldLabel' },
+        type: 'applyProjectGraphAction',
+      });
+    },
+    [dispatch, fieldName, nodeId]
+  );
+  const onLabelFocus = useCallback(() => setDraftLabel(label), [label]);
+  const onValueChange = useCallback(
+    (value: unknown) =>
+      dispatch({
+        action: { fieldName, nodeId, type: 'setFieldValue', value },
+        type: 'applyProjectGraphAction',
+      }),
+    [dispatch, fieldName, nodeId]
+  );
+  const resetAriaLabel = useMemo(() => `Reset ${label} to default value`, [label]);
+
+  if (!invocationNode || !template) {
+    return (
+      <Alert.Root status="error" size="sm" variant="surface">
+        <Alert.Indicator />
+        <Alert.Title>This field no longer exists in the project graph.</Alert.Title>
+      </Alert.Root>
+    );
+  }
+  const resetButton = canReset ? (
+    <Tooltip content="Reset to default value">
+      <IconButton
+        aria-label={resetAriaLabel}
+        color="fg.subtle"
+        flexShrink={0}
+        size="2xs"
+        title="Reset to default value"
+        variant="ghost"
+        onClick={onResetClick}
+      >
+        <Icon as={RotateCcwIcon} boxSize="3" />
+      </IconButton>
+    </Tooltip>
+  ) : null;
+
+  return (
+    <Field.Root invalid={isInvalid} minW="0" w="full">
+      <Stack gap="1" minW="0" w="full">
+        {isLabelEditable ? (
+          <HStack gap="1" minW="0" w="full">
+            <Input
+              aria-label="Field label"
+              color={isInvalid ? 'fg.error' : 'fg.muted'}
+              fontSize="2xs"
+              fontWeight="600"
+              h="5"
+              id={labelInputId}
+              placeholder={template.title}
+              size="2xs"
+              textTransform="uppercase"
+              value={draftLabel ?? label}
+              variant="flushed"
+              w="full"
+              onBlur={onLabelBlur}
+              onChange={onLabelChange}
+              onFocus={onLabelFocus}
+            />
+            {resetButton}
+          </HStack>
+        ) : (
+          <HStack gap="1" minW="0" w="full">
+            <Tooltip content={`${nodeContext} → ${template.title}`}>
+              <Stack color={isInvalid ? 'fg.error' : undefined} flex="1" gap="0" minW="0">
+                <FieldLabel>{label}</FieldLabel>
+              </Stack>
+            </Tooltip>
+            {resetButton}
+          </HStack>
+        )}
+        {element.data.showDescription && description ? (
+          <Text color="fg.subtle" fontSize="2xs">
+            {description}
+          </Text>
+        ) : null}
+        {isConnected ? (
+          <Text color="fg.subtle" fontSize="2xs">
+            Driven by a graph connection.
+          </Text>
+        ) : (
+          <WorkflowFieldInput
+            id={valueInputId}
+            invalid={isInvalid}
+            template={template}
+            value={instance?.value}
+            onChange={onValueChange}
+          />
+        )}
+        {invalidReason ? <Field.ErrorText fontSize="2xs">{invalidReason}</Field.ErrorText> : null}
+      </Stack>
+    </Field.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/NodeInspector.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/NodeInspector.tsx
new file mode 100644
index 00000000000..3f0ca9b653b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/NodeInspector.tsx
@@ -0,0 +1,186 @@
+import type {
+  InvocationTemplate,
+  ProjectGraphState,
+  WorkflowInvocationNode,
+  WorkflowNode,
+} from '@workbench/workflows/types';
+import type { ChangeEvent } from 'react';
+
+import { Flex, HStack, Stack, Text, Textarea } from '@chakra-ui/react';
+import { JsonPreview, Scrollable, Tabs } from '@workbench/components/ui';
+import { workflowSelectionStore } from '@workbench/widgets/workflow/editor/selectionStore';
+import { getProjectWidgetValues } from '@workbench/widgetState';
+import { useActiveProjectSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useInvocationTemplatesSelector } from '@workbench/workflows/templates';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Edit-mode inspector for the editor's selected node, with the legacy tab
+ * set: Details (summary + notes), Outputs, Data (raw node data), Template
+ * (the node's backend definition). Sizing is owned by the panel's Splitter.
+ */
+
+type InspectorTab = 'details' | 'outputs' | 'data' | 'template';
+
+const getInspectorTab = (values: Record<string, unknown>): InspectorTab =>
+  values.inspectorTab === 'outputs' || values.inspectorTab === 'data' || values.inspectorTab === 'template'
+    ? values.inspectorTab
+    : 'details';
+
+const DetailRow = ({ label, value }: { label: string; value: string }) => (
+  <HStack align="start" gap="2">
+    <Text color="fg.subtle" flexShrink={0} fontSize="2xs" minW="16">
+      {label}
+    </Text>
+    <Text fontSize="2xs" minW="0" wordBreak="break-word">
+      {value}
+    </Text>
+  </HStack>
+);
+
+const JsonBlock = ({ label, value }: { label: string; value: unknown }) => <JsonPreview label={label} value={value} />;
+
+const DetailsTab = ({ node, template }: { node: WorkflowInvocationNode; template: InvocationTemplate | undefined }) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const onNotesChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) =>
+      dispatch({
+        action: { nodeId: node.id, notes: event.currentTarget.value, type: 'setNodeNotes' },
+        type: 'applyProjectGraphAction',
+      }),
+    [dispatch, node.id]
+  );
+
+  return (
+    <Stack gap="2">
+      <DetailRow label={t('widgets.workflow.title')} value={node.data.label || template?.title || node.data.type} />
+      <DetailRow label={t('widgets.workflow.type')} value={node.data.type} />
+      <DetailRow label={t('widgets.workflow.version')} value={node.data.version} />
+      {template ? <DetailRow label={t('widgets.workflow.class')} value={template.classification} /> : null}
+      {template ? <DetailRow label={t('widgets.workflow.pack')} value={template.nodePack} /> : null}
+      {template?.description ? <DetailRow label={t('widgets.workflow.about')} value={template.description} /> : null}
+      <Stack gap="1">
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('widgets.workflow.notes')}
+        </Text>
+        <Textarea
+          aria-label={t('widgets.workflow.nodeNotes')}
+          fontSize="2xs"
+          minH="3rem"
+          placeholder={t('widgets.workflow.nodeNotesPlaceholder')}
+          resize="vertical"
+          size="xs"
+          value={node.data.notes}
+          onChange={onNotesChange}
+        />
+      </Stack>
+    </Stack>
+  );
+};
+
+const OutputsTab = ({ template }: { template: InvocationTemplate | undefined }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Stack gap="2">
+      <Text color="fg.subtle" fontSize="2xs">
+        {t('widgets.workflow.runOutputsNotRecorded')}
+      </Text>
+      {template ? (
+        <Stack gap="1">
+          <Text color="fg.subtle" fontSize="2xs">
+            {t('widgets.workflow.declaredOutputs')}
+          </Text>
+          {Object.values(template.outputs).map((output) => (
+            <DetailRow key={output.name} label={output.title} value={output.type.name} />
+          ))}
+        </Stack>
+      ) : null}
+    </Stack>
+  );
+};
+
+const InspectorBody = ({ node, tab }: { node: WorkflowNode; tab: InspectorTab }) => {
+  const { t } = useTranslation();
+  const templates = useInvocationTemplatesSelector((snapshot) => snapshot.templates);
+
+  if (node.type === 'notes' || node.type === 'current_image' || node.type === 'connector') {
+    const typeLabel =
+      node.type === 'notes'
+        ? t('widgets.workflow.notesNode')
+        : node.type === 'current_image'
+          ? t('widgets.workflow.currentImageNode')
+          : t('widgets.workflow.connectorNode');
+
+    return tab === 'data' ? (
+      <JsonBlock label={t('widgets.workflow.nodeData')} value={node.data} />
+    ) : (
+      <DetailRow label={t('widgets.workflow.type')} value={typeLabel} />
+    );
+  }
+
+  const template = templates[node.data.type];
+
+  switch (tab) {
+    case 'details':
+      return <DetailsTab node={node} template={template} />;
+    case 'outputs':
+      return <OutputsTab template={template} />;
+    case 'data':
+      return <JsonBlock label={t('widgets.workflow.nodeData')} value={node.data} />;
+    case 'template':
+      return template ? (
+        <JsonBlock label={t('widgets.workflow.nodeTemplate')} value={template} />
+      ) : (
+        <Text color="fg.subtle" fontSize="2xs">
+          {t('widgets.workflow.noTemplateKnown', { type: node.data.type })}
+        </Text>
+      );
+  }
+};
+
+export const NodeInspector = ({ projectGraph }: { projectGraph: ProjectGraphState }) => {
+  const { t } = useTranslation();
+  const workflowWidgetValues = useActiveProjectSelector((project) => getProjectWidgetValues(project, 'workflow'));
+  const dispatch = useWorkbenchDispatch();
+  const selectedNodeIds = workflowSelectionStore.useSelector((snapshot) => snapshot.selectedNodeIds);
+  const tab = getInspectorTab(workflowWidgetValues);
+  const selectedNode = projectGraph.nodes.find((node) => node.id === selectedNodeIds[0]);
+  const onTabValueChange = useCallback(
+    (event: { value: string }) =>
+      dispatch({ type: 'patchWidgetValues', values: { inspectorTab: event.value }, widgetId: 'workflow' }),
+    [dispatch]
+  );
+
+  return (
+    <Flex direction="column" h="full" minH="0">
+      <HStack flexShrink={0} justify="space-between" px="2" h={10} borderBottomWidth={1}>
+        <Text color="fg.muted" fontSize="2xs" fontWeight="600" textTransform="uppercase">
+          {t('widgets.workflow.nodeInspector')}
+        </Text>
+        <Tabs.Root size="sm" value={tab} variant="outline" mb="-1" onValueChange={onTabValueChange}>
+          <Tabs.List>
+            {(['details', 'outputs', 'data', 'template'] as const).map((value) => (
+              <Tabs.Trigger key={value} fontSize="2xs" textTransform="capitalize" value={value}>
+                {t(`widgets.workflow.inspectorTabs.${value}`)}
+              </Tabs.Trigger>
+            ))}
+          </Tabs.List>
+        </Tabs.Root>
+      </HStack>
+      <Scrollable flex="1" label={t('widgets.workflow.selectedNodeInspector')} minH="0">
+        <Stack p="3">
+          {selectedNode ? (
+            <InspectorBody node={selectedNode} tab={tab} />
+          ) : (
+            <Text color="fg.subtle" fontSize="2xs">
+              {t('widgets.workflow.selectNodeToInspect')}
+            </Text>
+          )}
+        </Stack>
+      </Scrollable>
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowDetailsTab.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowDetailsTab.tsx
new file mode 100644
index 00000000000..274e79a48f5
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowDetailsTab.tsx
@@ -0,0 +1,84 @@
+import type { WorkflowMetadata } from '@workbench/workflows/types';
+import type { ChangeEvent } from 'react';
+
+import { HStack, Input, Stack, Textarea } from '@chakra-ui/react';
+import { Field } from '@workbench/components/ui';
+import { useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/** Workflow metadata editing — the legacy "Details" tab. */
+export const WorkflowDetailsTab = ({ metadata }: { metadata: WorkflowMetadata }) => {
+  const { t } = useTranslation();
+  const dispatch = useWorkbenchDispatch();
+  const commit = useCallback(
+    (patch: Partial<WorkflowMetadata>) =>
+      dispatch({ action: { patch, type: 'setMetadata' }, type: 'applyProjectGraphAction' }),
+    [dispatch]
+  );
+
+  const onNameChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => commit({ name: event.currentTarget.value }),
+    [commit]
+  );
+  const onAuthorChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => commit({ author: event.currentTarget.value }),
+    [commit]
+  );
+  const onWorkflowVersionChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => commit({ workflowVersion: event.currentTarget.value }),
+    [commit]
+  );
+  const onTagsChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => commit({ tags: event.currentTarget.value }),
+    [commit]
+  );
+  const onContactChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => commit({ contact: event.currentTarget.value }),
+    [commit]
+  );
+  const onDescriptionChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => commit({ description: event.currentTarget.value }),
+    [commit]
+  );
+  const onNotesChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => commit({ notes: event.currentTarget.value }),
+    [commit]
+  );
+
+  const textField = (
+    label: string,
+    key: keyof WorkflowMetadata,
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void
+  ) => (
+    <Field label={label}>
+      <Input size="xs" value={metadata[key]} onChange={onChange} />
+    </Field>
+  );
+
+  return (
+    <Stack gap="3" p="3">
+      {textField(t('common.name'), 'name', onNameChange)}
+      <Field label={t('widgets.workflow.description')}>
+        <Textarea
+          minH="3.5rem"
+          resize="vertical"
+          size="xs"
+          value={metadata.description}
+          onChange={onDescriptionChange}
+        />
+      </Field>
+      <HStack align="start" gap="2">
+        {textField(t('widgets.workflow.author'), 'author', onAuthorChange)}
+        {textField(t('widgets.workflow.version'), 'workflowVersion', onWorkflowVersionChange)}
+      </HStack>
+      <HStack align="start" gap="2">
+        {textField(t('widgets.workflow.tags'), 'tags', onTagsChange)}
+        {textField(t('widgets.workflow.contact'), 'contact', onContactChange)}
+      </HStack>
+      <Field label={t('widgets.workflow.notes')}>
+        <Textarea minH="3.5rem" resize="vertical" size="xs" value={metadata.notes} onChange={onNotesChange} />
+      </Field>
+    </Stack>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowJsonTab.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowJsonTab.tsx
new file mode 100644
index 00000000000..4195a0e6fbb
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowJsonTab.tsx
@@ -0,0 +1,17 @@
+import type { ProjectGraphState } from '@workbench/workflows/types';
+
+import { Flex } from '@chakra-ui/react';
+import { JsonPreview } from '@workbench/components/ui';
+import { getWorkflowJsonText } from '@workbench/widgets/workflow/workflowTransfer';
+import { useTranslation } from 'react-i18next';
+
+/** Read-only view of the serialized workflow — the legacy "JSON" tab. */
+export const WorkflowJsonTab = ({ projectGraph }: { projectGraph: ProjectGraphState }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Flex h="full" minH="0" minW="0" borderWidth={1} rounded="md" m="1" overflow="hidden">
+      <JsonPreview label={t('widgets.workflow.workflowJson')} maxH="100%" text={getWorkflowJsonText(projectGraph)} />
+    </Flex>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowLinearPanel.tsx b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowLinearPanel.tsx
new file mode 100644
index 00000000000..0dcb4faa544
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/linear/WorkflowLinearPanel.tsx
@@ -0,0 +1,206 @@
+import { Flex, HStack, Icon, SegmentGroup, Splitter } from '@chakra-ui/react';
+import { Scrollable, Tabs } from '@workbench/components/ui';
+import { useActiveProjectSelector, useWidgetValuesSelector, useWorkbenchDispatch } from '@workbench/WorkbenchContext';
+import { ensureInvocationTemplatesLoaded } from '@workbench/workflows/templates';
+import { EyeIcon, PencilIcon } from 'lucide-react';
+import { useCallback, useEffect, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { FormBuilderTab } from './FormBuilderTab';
+import { LinearFormView } from './LinearFormView';
+import { NodeInspector } from './NodeInspector';
+import { WorkflowDetailsTab } from './WorkflowDetailsTab';
+import { WorkflowJsonTab } from './WorkflowJsonTab';
+
+/**
+ * The workflow widget's side panel — the Linear UI. View mode runs the
+ * project graph through its form; Edit mode opens the legacy-style tab set
+ * (Form builder / Details / JSON) with the node inspector pinned below.
+ * Panel mode, tab, and inspector height live in the widget's own state.
+ */
+
+type PanelMode = 'view' | 'edit';
+type EditTab = 'form' | 'details' | 'json';
+type PanelModeItem = {
+  labelKey: string;
+  icon: typeof EyeIcon;
+  mode: PanelMode;
+};
+
+/** Inspector share of the splitter, as a percentage of the panel height. */
+const DEFAULT_INSPECTOR_SIZE_PCT = 35;
+const SPLITTER_PANELS = [
+  { id: 'content', minSize: 25 },
+  { id: 'inspector', minSize: 12 },
+];
+const PANEL_MODES: PanelModeItem[] = [
+  { labelKey: 'common.view', icon: EyeIcon, mode: 'view' },
+  { labelKey: 'common.edit', icon: PencilIcon, mode: 'edit' },
+];
+
+export interface WorkflowPanelState {
+  editTab: EditTab;
+  inspectorSizePct: number;
+  mode: PanelMode;
+}
+
+const getPanelMode = (values: Record<string, unknown>): PanelMode => (values.panelMode === 'edit' ? 'edit' : 'view');
+
+const getEditTab = (values: Record<string, unknown>): EditTab =>
+  values.editTab === 'details' || values.editTab === 'json' ? values.editTab : 'form';
+
+const getInspectorSizePct = (values: Record<string, unknown>): number =>
+  typeof values.inspectorSizePct === 'number' && Number.isFinite(values.inspectorSizePct)
+    ? Math.min(75, Math.max(12, values.inspectorSizePct))
+    : DEFAULT_INSPECTOR_SIZE_PCT;
+
+export const getWorkflowPanelState = (values: Record<string, unknown>): WorkflowPanelState => ({
+  editTab: getEditTab(values),
+  inspectorSizePct: getInspectorSizePct(values),
+  mode: getPanelMode(values),
+});
+
+export const areWorkflowPanelStatesEqual = (left: WorkflowPanelState, right: WorkflowPanelState): boolean =>
+  left.mode === right.mode && left.editTab === right.editTab && left.inspectorSizePct === right.inspectorSizePct;
+
+const PanelModeToggle = ({ mode, onChange }: { mode: PanelMode; onChange: (mode: PanelMode) => void }) => {
+  const { t } = useTranslation();
+  const onValueChange = useCallback(
+    (details: { value: string | null }) => {
+      if (details.value === 'view' || details.value === 'edit') {
+        onChange(details.value);
+      }
+    },
+    [onChange]
+  );
+
+  return (
+    <SegmentGroup.Root value={mode} onValueChange={onValueChange} size="xs">
+      <SegmentGroup.Indicator />
+      {PANEL_MODES.map(({ labelKey, icon, mode }) => (
+        <SegmentGroup.Item key={mode} value={mode}>
+          <SegmentGroup.ItemHiddenInput />
+          <Icon as={icon} boxSize="3" />
+          <SegmentGroup.ItemText>{t(labelKey)}</SegmentGroup.ItemText>
+        </SegmentGroup.Item>
+      ))}
+    </SegmentGroup.Root>
+  );
+};
+
+export const WorkflowLinearPanel = () => {
+  const { t } = useTranslation();
+  const { editTab, inspectorSizePct, mode } = useWidgetValuesSelector(
+    'workflow',
+    getWorkflowPanelState,
+    areWorkflowPanelStatesEqual
+  );
+  const dispatch = useWorkbenchDispatch();
+
+  useEffect(() => {
+    ensureInvocationTemplatesLoaded();
+  }, []);
+
+  const patchValues = useCallback(
+    (values: Record<string, unknown>) => dispatch({ type: 'patchWidgetValues', values, widgetId: 'workflow' }),
+    [dispatch]
+  );
+  const onPanelModeChange = useCallback((panelMode: PanelMode) => patchValues({ panelMode }), [patchValues]);
+  const onEditTabChange = useCallback(
+    (event: { value: string }) => patchValues({ editTab: event.value }),
+    [patchValues]
+  );
+
+  return (
+    <Flex direction="column" flex="1" h="full" minH="0">
+      <HStack flexShrink={0} justify="space-between" px="2" h={10} borderBottomWidth={1}>
+        <PanelModeToggle mode={mode} onChange={onPanelModeChange} />
+        {mode === 'edit' ? (
+          <Tabs.Root size="sm" value={editTab} variant="outline" mb="-1" onValueChange={onEditTabChange}>
+            <Tabs.List>
+              <Tabs.Trigger value="form" fontSize="2xs">
+                {t('widgets.workflow.form')}
+              </Tabs.Trigger>
+              <Tabs.Trigger value="details" fontSize="2xs">
+                {t('widgets.workflow.details')}
+              </Tabs.Trigger>
+              <Tabs.Trigger value="json" fontSize="2xs">
+                {t('common.json')}
+              </Tabs.Trigger>
+            </Tabs.List>
+          </Tabs.Root>
+        ) : null}
+      </HStack>
+      {mode === 'view' ? (
+        <WorkflowLinearViewContent />
+      ) : (
+        <WorkflowLinearEditContent editTab={editTab} inspectorSizePct={inspectorSizePct} patchValues={patchValues} />
+      )}
+    </Flex>
+  );
+};
+
+const WorkflowLinearViewContent = () => {
+  const { t } = useTranslation();
+  const projectGraph = useActiveProjectSelector((project) => project.projectGraph);
+
+  return (
+    <Scrollable flex="1" label={t('widgets.workflow.panelContent')} minH="0">
+      <LinearFormView projectGraph={projectGraph} />
+    </Scrollable>
+  );
+};
+
+const WorkflowLinearEditContent = ({
+  editTab,
+  inspectorSizePct,
+  patchValues,
+}: {
+  editTab: EditTab;
+  inspectorSizePct: number;
+  patchValues: (values: Record<string, unknown>) => void;
+}) => {
+  const { t } = useTranslation();
+  const projectGraph = useActiveProjectSelector((project) => project.projectGraph);
+  const defaultSize = useMemo(() => [100 - inspectorSizePct, inspectorSizePct], [inspectorSizePct]);
+  const onResizeEnd = useCallback(
+    (details: { size: number[] }) => {
+      const inspectorSizePct = details.size[1];
+
+      if (typeof inspectorSizePct === 'number') {
+        patchValues({ inspectorSizePct });
+      }
+    },
+    [patchValues]
+  );
+
+  return (
+    <Splitter.Root
+      defaultSize={defaultSize}
+      flex="1"
+      gap="0"
+      minH="0"
+      orientation="vertical"
+      panels={SPLITTER_PANELS}
+      onResizeEnd={onResizeEnd}
+    >
+      <Splitter.Panel id="content" minH="0" minW="0" overflow="hidden">
+        {editTab === 'json' ? (
+          <WorkflowJsonTab projectGraph={projectGraph} />
+        ) : (
+          <Scrollable flex="1" h="full" label={t('widgets.workflow.panelContent')} minH="0" minW="0" w="full">
+            {editTab === 'form' ? (
+              <FormBuilderTab projectGraph={projectGraph} />
+            ) : (
+              <WorkflowDetailsTab metadata={projectGraph} />
+            )}
+          </Scrollable>
+        )}
+      </Splitter.Panel>
+      <Splitter.ResizeTrigger aria-label={t('widgets.workflow.resizeNodeInspector')} id="content:inspector" />
+      <Splitter.Panel id="inspector" minH="0" overflow="hidden">
+        <NodeInspector projectGraph={projectGraph} />
+      </Splitter.Panel>
+    </Splitter.Root>
+  );
+};
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/workflowTransfer.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/workflowTransfer.ts
new file mode 100644
index 00000000000..bb7b3383dca
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/workflowTransfer.ts
@@ -0,0 +1,22 @@
+import type { ProjectGraphState } from '@workbench/workflows/types';
+
+import { serializeWorkflowJson } from '@workbench/workflows/workflowJson';
+
+/** Export-side helpers shared by the workflow menu items and panels. */
+
+export const downloadWorkflowJson = (document: ProjectGraphState): void => {
+  const blob = new Blob([JSON.stringify(serializeWorkflowJson(document), null, 2)], { type: 'application/json' });
+  const url = URL.createObjectURL(blob);
+  const anchor = window.document.createElement('a');
+
+  anchor.href = url;
+  anchor.download = `${document.name.trim() || 'workflow'}.json`;
+  anchor.click();
+  URL.revokeObjectURL(url);
+};
+
+export const getWorkflowJsonText = (document: ProjectGraphState): string =>
+  JSON.stringify(serializeWorkflowJson(document), null, 2);
+
+export const copyWorkflowJson = (document: ProjectGraphState): Promise<void> =>
+  navigator.clipboard.writeText(getWorkflowJsonText(document));
diff --git a/invokeai/frontend/webv2/src/workbench/widgets/workflow/workflowUiStore.ts b/invokeai/frontend/webv2/src/workbench/widgets/workflow/workflowUiStore.ts
new file mode 100644
index 00000000000..b0f53e52ac7
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/widgets/workflow/workflowUiStore.ts
@@ -0,0 +1,67 @@
+import type { FieldType, XYPosition } from '@workbench/workflows/types';
+
+import { createExternalStore } from '@workbench/externalStore';
+
+export type AddNodeConnectionFilter =
+  | {
+      kind: 'source';
+      sourceHandle: string;
+      sourceNodeId: string;
+      sourceType: FieldType | null;
+    }
+  | {
+      kind: 'target';
+      targetHandle: string;
+      targetNodeId: string;
+      targetType: FieldType | null;
+    };
+
+/**
+ * Session-lived UI coordination for the workflow widget. Menu items live
+ * inside the shared widget actions menu while their dialogs and the import
+ * file input live in the always-mounted header actions — this store is the
+ * bridge between the two.
+ */
+
+export interface WorkflowUiSnapshot {
+  addNodeConnection: AddNodeConnectionFilter | null;
+  addNodePosition: XYPosition | null;
+  isAddNodeOpen: boolean;
+  isLibraryOpen: boolean;
+  isNewWorkflowConfirmOpen: boolean;
+  /** Bumped to ask the dialog host to open the JSON file picker. */
+  importRequestCount: number;
+}
+
+export const workflowUiStore = createExternalStore<WorkflowUiSnapshot>({
+  addNodeConnection: null,
+  addNodePosition: null,
+  importRequestCount: 0,
+  isAddNodeOpen: false,
+  isLibraryOpen: false,
+  isNewWorkflowConfirmOpen: false,
+});
+
+export const setWorkflowLibraryOpen = (isOpen: boolean): void => {
+  workflowUiStore.patchSnapshot({ isLibraryOpen: isOpen });
+};
+
+export const setAddNodeOpen = (
+  isOpen: boolean,
+  position: XYPosition | null = null,
+  connection: AddNodeConnectionFilter | null = null
+): void => {
+  workflowUiStore.patchSnapshot({
+    addNodeConnection: isOpen ? connection : null,
+    addNodePosition: isOpen ? position : null,
+    isAddNodeOpen: isOpen,
+  });
+};
+
+export const setNewWorkflowConfirmOpen = (isOpen: boolean): void => {
+  workflowUiStore.patchSnapshot({ isNewWorkflowConfirmOpen: isOpen });
+};
+
+export const requestWorkflowImport = (): void => {
+  workflowUiStore.patchSnapshot({ importRequestCount: workflowUiStore.getSnapshot().importRequestCount + 1 });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchAutosave.test.ts b/invokeai/frontend/webv2/src/workbench/workbenchAutosave.test.ts
new file mode 100644
index 00000000000..7b9f0a09f90
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchAutosave.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+
+import { getAutosaveScheduleDecision, isAutosaveCompletionCurrent } from './workbenchAutosave';
+
+describe('getAutosaveScheduleDecision', () => {
+  it('does not schedule already-saved or already-scheduled state', () => {
+    expect(
+      getAutosaveScheduleDecision({
+        failedPersistedRevision: null,
+        lastSavedPersistedRevision: 1,
+        persistedRevision: 1,
+        scheduledPersistedRevision: null,
+      })
+    ).toEqual({ failedPersistedRevision: null, shouldSchedule: false });
+
+    expect(
+      getAutosaveScheduleDecision({
+        failedPersistedRevision: null,
+        lastSavedPersistedRevision: 1,
+        persistedRevision: 2,
+        scheduledPersistedRevision: 2,
+      })
+    ).toEqual({ failedPersistedRevision: null, shouldSchedule: false });
+  });
+
+  it('holds a failed state key until a new durable edit happens', () => {
+    expect(
+      getAutosaveScheduleDecision({
+        failedPersistedRevision: 2,
+        lastSavedPersistedRevision: 1,
+        persistedRevision: 2,
+        scheduledPersistedRevision: null,
+      })
+    ).toEqual({ failedPersistedRevision: 2, shouldSchedule: false });
+
+    expect(
+      getAutosaveScheduleDecision({
+        failedPersistedRevision: 2,
+        lastSavedPersistedRevision: 1,
+        persistedRevision: 3,
+        scheduledPersistedRevision: null,
+      })
+    ).toEqual({ failedPersistedRevision: null, shouldSchedule: true });
+  });
+
+  it('clears a failed state key after returning to the last saved state', () => {
+    expect(
+      getAutosaveScheduleDecision({
+        failedPersistedRevision: 2,
+        lastSavedPersistedRevision: 1,
+        persistedRevision: 1,
+        scheduledPersistedRevision: null,
+      })
+    ).toEqual({ failedPersistedRevision: null, shouldSchedule: false });
+
+    expect(
+      getAutosaveScheduleDecision({
+        failedPersistedRevision: null,
+        lastSavedPersistedRevision: 1,
+        persistedRevision: 2,
+        scheduledPersistedRevision: null,
+      })
+    ).toEqual({ failedPersistedRevision: null, shouldSchedule: true });
+  });
+});
+
+describe('isAutosaveCompletionCurrent', () => {
+  it('rejects stale save completions after a newer durable revision exists', () => {
+    expect(
+      isAutosaveCompletionCurrent({
+        completedPersistedRevision: 2,
+        currentPersistedRevision: 3,
+      })
+    ).toBe(false);
+  });
+
+  it('accepts save completions for the current durable revision', () => {
+    expect(
+      isAutosaveCompletionCurrent({
+        completedPersistedRevision: 2,
+        currentPersistedRevision: 2,
+      })
+    ).toBe(true);
+  });
+
+  it('does not require serializing full workbench state to compare completions', () => {
+    expect(
+      isAutosaveCompletionCurrent({
+        completedPersistedRevision: 4,
+        currentPersistedRevision: 4,
+      })
+    ).toBe(true);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchAutosave.ts b/invokeai/frontend/webv2/src/workbench/workbenchAutosave.ts
new file mode 100644
index 00000000000..5d87de9103b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchAutosave.ts
@@ -0,0 +1,40 @@
+interface AutosaveScheduleDecisionInput {
+  failedPersistedRevision: number | null;
+  lastSavedPersistedRevision: number;
+  persistedRevision: number;
+  scheduledPersistedRevision: number | null;
+}
+
+interface AutosaveScheduleDecision {
+  failedPersistedRevision: number | null;
+  shouldSchedule: boolean;
+}
+
+export const getAutosaveScheduleDecision = ({
+  failedPersistedRevision,
+  lastSavedPersistedRevision,
+  persistedRevision,
+  scheduledPersistedRevision,
+}: AutosaveScheduleDecisionInput): AutosaveScheduleDecision => {
+  if (persistedRevision === lastSavedPersistedRevision) {
+    return { failedPersistedRevision: null, shouldSchedule: false };
+  }
+
+  if (persistedRevision === scheduledPersistedRevision) {
+    return { failedPersistedRevision, shouldSchedule: false };
+  }
+
+  if (persistedRevision === failedPersistedRevision) {
+    return { failedPersistedRevision, shouldSchedule: false };
+  }
+
+  return { failedPersistedRevision: null, shouldSchedule: true };
+};
+
+export const isAutosaveCompletionCurrent = ({
+  completedPersistedRevision,
+  currentPersistedRevision,
+}: {
+  completedPersistedRevision: number;
+  currentPersistedRevision: number;
+}): boolean => completedPersistedRevision === currentPersistedRevision;
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchSelectors.test.ts b/invokeai/frontend/webv2/src/workbench/workbenchSelectors.test.ts
new file mode 100644
index 00000000000..f4e5692ec62
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchSelectors.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSelectorCache, createStableSelector } from './workbenchSelectors';
+
+describe('createSelectorCache', () => {
+  it('uses shallow equality by default for derived objects', () => {
+    const cache = createSelectorCache((snapshot: { count: number; label: string }) => ({ count: snapshot.count }));
+
+    const first = cache.read({ count: 1, label: 'idle' });
+    const second = cache.read({ count: 1, label: 'loading' });
+    const third = cache.read({ count: 2, label: 'loading' });
+
+    expect(second).toBe(first);
+    expect(third).not.toBe(first);
+    expect(third).toEqual({ count: 2 });
+  });
+
+  it('compares Set contents by default', () => {
+    const cache = createSelectorCache((snapshot: { ids: string[] }) => new Set(snapshot.ids));
+
+    const first = cache.read({ ids: ['a', 'b'] });
+    const second = cache.read({ ids: ['a', 'b'] });
+    const third = cache.read({ ids: ['a', 'c'] });
+
+    expect(second).toBe(first);
+    expect(third).not.toBe(first);
+  });
+});
+
+describe('createStableSelector', () => {
+  it('reuses the previous result when derived values are equal', () => {
+    const selector = createStableSelector(
+      (value: { ids: string[] }) => value.ids.map((id) => id.toUpperCase()),
+      (left, right) => left.length === right.length && left.every((id, index) => id === right[index])
+    );
+
+    const first = selector({ ids: ['a', 'b'] });
+    const second = selector({ ids: ['a', 'b'] });
+    const third = selector({ ids: ['a', 'c'] });
+
+    expect(second).toBe(first);
+    expect(third).not.toBe(first);
+    expect(third).toEqual(['A', 'C']);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchSelectors.ts b/invokeai/frontend/webv2/src/workbench/workbenchSelectors.ts
new file mode 100644
index 00000000000..cd69af9a32a
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchSelectors.ts
@@ -0,0 +1,93 @@
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector';
+
+export type EqualityFn<T> = (left: T, right: T) => boolean;
+
+export interface SelectorCache<Snapshot, Selected> {
+  read: (snapshot: Snapshot) => Selected;
+  setSelector: (selector: (snapshot: Snapshot) => Selected, isEqual: EqualityFn<Selected>) => void;
+}
+
+export const areArraysEqual = <Value>(left: readonly Value[], right: readonly Value[]): boolean =>
+  left.length === right.length && left.every((value, index) => Object.is(value, right[index]));
+
+export const shallowEqual = <T>(left: T, right: T): boolean => {
+  if (Object.is(left, right)) {
+    return true;
+  }
+
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return areArraysEqual(left, right);
+  }
+
+  if (left instanceof Set && right instanceof Set) {
+    return left.size === right.size && Array.from(left).every((value) => right.has(value));
+  }
+
+  if (left instanceof Map && right instanceof Map) {
+    return (
+      left.size === right.size &&
+      Array.from(left).every(([key, value]) => right.has(key) && Object.is(right.get(key), value))
+    );
+  }
+
+  if (typeof left !== 'object' || left === null || typeof right !== 'object' || right === null) {
+    return false;
+  }
+
+  const leftRecord = left as Record<PropertyKey, unknown>;
+  const rightRecord = right as Record<PropertyKey, unknown>;
+  const leftKeys = Reflect.ownKeys(leftRecord);
+
+  if (leftKeys.length !== Reflect.ownKeys(rightRecord).length) {
+    return false;
+  }
+
+  return leftKeys.every(
+    (key) => Object.prototype.hasOwnProperty.call(rightRecord, key) && Object.is(leftRecord[key], rightRecord[key])
+  );
+};
+
+export const createSelectorCache = <Snapshot, Selected>(
+  initialSelector: (snapshot: Snapshot) => Selected,
+  initialIsEqual: EqualityFn<Selected> = shallowEqual
+): SelectorCache<Snapshot, Selected> => {
+  let hasSelection = false;
+  let isEqual = initialIsEqual;
+  let selection: Selected;
+  let selector = initialSelector;
+
+  return {
+    read: (snapshot) => {
+      const next = selector(snapshot);
+
+      if (hasSelection && isEqual(selection, next)) {
+        return selection;
+      }
+
+      hasSelection = true;
+      selection = next;
+
+      return next;
+    },
+    setSelector: (nextSelector, nextIsEqual) => {
+      selector = nextSelector;
+      isEqual = nextIsEqual;
+    },
+  };
+};
+
+export const useExternalStoreSelector = <Snapshot, Selected>(
+  subscribe: (listener: () => void) => () => void,
+  getSnapshot: () => Snapshot,
+  selector: (snapshot: Snapshot) => Selected,
+  isEqual: EqualityFn<Selected> = shallowEqual
+): Selected => useSyncExternalStoreWithSelector(subscribe, getSnapshot, getSnapshot, selector, isEqual);
+
+export const createStableSelector = <Input, Selected>(
+  selector: (input: Input) => Selected,
+  isEqual: EqualityFn<Selected> = shallowEqual
+): ((input: Input) => Selected) => {
+  const cache = createSelectorCache(selector, isEqual);
+
+  return (input) => cache.read(input);
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchState.test.ts b/invokeai/frontend/webv2/src/workbench/workbenchState.test.ts
new file mode 100644
index 00000000000..410e708bc30
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchState.test.ts
@@ -0,0 +1,3010 @@
+import { describe, expect, it } from 'vitest';
+
+import type { CanvasProjectMutation } from './canvasProjectMutations';
+import type { GenerateWidgetValues, MainModelConfig } from './generation/types';
+import type {
+  CanvasControlLayerContract,
+  CanvasInpaintMaskLayerContract,
+  CanvasLayerContract,
+  CanvasRasterLayerContractV2,
+  CanvasStagingCandidateContract,
+  GeneratedImageContract,
+  GraphContract,
+  Project,
+  WorkbenchState,
+} from './types';
+
+import { createEmptyCanvasDocumentV2 } from './canvasMigration';
+import { getCanvasStagingCandidateFingerprint, getCanvasStagingSlots } from './canvasStagingView';
+import { MAX_PROMPT_HISTORY } from './generation/promptHistory';
+import { DEFAULT_PROJECT_SETTINGS } from './settings/store';
+import { getProjectWidgetValues } from './widgetState';
+import {
+  createInitialWorkbenchState,
+  nextLayerName,
+  type WorkbenchAction,
+  workbenchReducer as reduceWorkbench,
+} from './workbenchState';
+
+type LegacyCanvasMutation = CanvasProjectMutation & { projectId?: string };
+const CANVAS_MUTATION_TYPES = new Set<CanvasProjectMutation['type']>([
+  'commitStagedImage',
+  'addCanvasLayer',
+  'applyCanvasLayerStackMutation',
+  'clearCanvasStaging',
+  'convertCanvasLayer',
+  'cycleStagedImage',
+  'deleteCanvasSnapshot',
+  'discardAllStagedImages',
+  'discardSelectedStagedImage',
+  'duplicateCanvasLayer',
+  'mergeCanvasLayersDown',
+  'removeCanvasLayers',
+  'reorderCanvasLayers',
+  'replaceCanvasDocument',
+  'replaceCanvasLayer',
+  'rollbackStagedImageCommit',
+  'resizeCanvasDocument',
+  'restoreCanvasSnapshot',
+  'saveCanvasSnapshot',
+  'setCanvasBbox',
+  'setCanvasLayersEnabled',
+  'setCanvasSelectedLayer',
+  'setCanvasStagingAutoSwitch',
+  'setStagedImageIndex',
+  'toggleCanvasStagingThumbnailsVisibility',
+  'toggleCanvasStagingVisibility',
+  'updateCanvasLayer',
+  'updateCanvasLayerConfig',
+  'updateCanvasLayerSource',
+]);
+
+const workbenchReducer = (state: WorkbenchState, action: WorkbenchAction | LegacyCanvasMutation): WorkbenchState => {
+  if (CANVAS_MUTATION_TYPES.has(action.type as CanvasProjectMutation['type'])) {
+    const { projectId = state.activeProjectId, ...mutation } = action as LegacyCanvasMutation;
+    return reduceWorkbench(state, {
+      mutation: mutation as CanvasProjectMutation,
+      projectId,
+      type: 'applyCanvasProjectMutation',
+    });
+  }
+  return reduceWorkbench(state, action as WorkbenchAction);
+};
+
+const commitSelectedStagedImage = (state: WorkbenchState, projectId = state.activeProjectId): WorkbenchState => {
+  const project = state.projects.find((candidate) => candidate.id === projectId);
+  const slot = project
+    ? getCanvasStagingSlots(project.canvas, project.queue.items)[project.canvas.stagingArea.selectedImageIndex]
+    : undefined;
+  if (!project || slot?.kind !== 'candidate') {
+    return state;
+  }
+  const candidate = slot.candidate;
+  const { placement } = candidate;
+  const layer: CanvasRasterLayerContractV2 = {
+    blendMode: 'normal',
+    id: `accepted-${candidate.imageName}`,
+    isEnabled: true,
+    isLocked: false,
+    name: `Layer ${project.canvas.document.layers.length + 1}`,
+    opacity: placement.opacity,
+    source: {
+      image: { height: candidate.height, imageName: candidate.imageName, width: candidate.width },
+      type: 'image',
+    },
+    transform: {
+      rotation: 0,
+      scaleX: candidate.width === 0 ? 1 : placement.width / candidate.width,
+      scaleY: candidate.height === 0 ? 1 : placement.height / candidate.height,
+      x: placement.x,
+      y: placement.y,
+    },
+    type: 'raster',
+  };
+  return reduceWorkbench(state, {
+    mutation: {
+      candidateFingerprint: getCanvasStagingCandidateFingerprint(candidate),
+      event: {
+        createdAt: '2026-07-16T00:00:00.000Z',
+        id: `event-${candidate.imageName}`,
+        summary: `Accepted ${candidate.imageName} into a new raster layer`,
+        type: 'canvas-layer-accepted',
+      },
+      layer,
+      selectedImageIndex: project.canvas.stagingArea.selectedImageIndex,
+      type: 'commitStagedImage',
+    },
+    projectId,
+    type: 'applyCanvasProjectMutation',
+  });
+};
+
+const model: MainModelConfig = {
+  base: 'sdxl',
+  key: 'test-model',
+  name: 'Test Model',
+  type: 'main',
+};
+
+const createGenerateValues = (overrides: Partial<GenerateWidgetValues> = {}): GenerateWidgetValues => ({
+  aspectRatioId: '1:1',
+  aspectRatioIsLocked: false,
+  aspectRatioValue: 1,
+  batchCount: 1,
+  cfgRescaleMultiplier: 0,
+  cfgScale: 7,
+  clipEmbedModel: null,
+  clipGEmbedModel: null,
+  clipLEmbedModel: null,
+  clipSkip: 0,
+  colorCompensation: false,
+  componentSourceModel: null,
+  height: 1024,
+  loras: [],
+  model,
+  modelKey: model.key,
+  negativePromptEnabled: true,
+  negativePrompt: '',
+  negativePromptHeightPx: 56,
+  positivePrompt: 'first prompt',
+  positivePromptHeightPx: 96,
+  qwen3EncoderModel: null,
+  qwenVLEncoderModel: null,
+  referenceImages: [],
+  scheduler: 'euler_a',
+  seamlessXAxis: false,
+  seamlessYAxis: false,
+  seed: 123,
+  shouldRandomizeSeed: false,
+  steps: 30,
+  t5EncoderModel: null,
+  vae: null,
+  vaePrecision: 'fp32',
+  width: 1024,
+  ...overrides,
+});
+
+const createImage = (imageName: string, sourceQueueItemId: string): GeneratedImageContract => ({
+  height: 768,
+  imageName,
+  imageUrl: `/api/v1/images/i/${imageName}/full`,
+  queuedAt: '2026-06-09T00:00:00.000Z',
+  sourceQueueItemId,
+  thumbnailUrl: `/api/v1/images/i/${imageName}/thumbnail`,
+  width: 512,
+});
+
+const createStagingCandidate = (
+  imageName: string,
+  sourceQueueItemId: string,
+  placement: CanvasStagingCandidateContract['placement']
+): CanvasStagingCandidateContract => ({
+  ...createImage(imageName, sourceQueueItemId),
+  placement,
+});
+
+const getProject = (state: WorkbenchState, projectId: string): Project => {
+  const project = state.projects.find((candidate) => candidate.id === projectId);
+
+  expect(project).toBeDefined();
+
+  return project as Project;
+};
+
+const getActiveProject = (state: WorkbenchState): Project => getProject(state, state.activeProjectId);
+
+type CanvasLayer = Project['canvas']['document']['layers'][number];
+
+const getRasterLayerImageName = (layer: CanvasLayer | undefined): string | undefined =>
+  layer?.type === 'raster' && layer.source.type === 'image' ? layer.source.image.imageName : undefined;
+
+/** Reconstructs a v1-style `{x,y,width,height,opacity}` placement from a v2 raster layer's transform, mirroring `CanvasWidgetView`'s rendering math. */
+const getRasterLayerPlacement = (layer: CanvasLayer | undefined) => {
+  if (!layer || layer.type !== 'raster' || layer.source.type !== 'image') {
+    return undefined;
+  }
+
+  const { image } = layer.source;
+
+  return {
+    height: image.height * layer.transform.scaleY,
+    opacity: layer.opacity,
+    width: image.width * layer.transform.scaleX,
+    x: layer.transform.x,
+    y: layer.transform.y,
+  };
+};
+
+const createRasterLayer = (id: string, imageName = `${id}.png`): CanvasRasterLayerContractV2 => ({
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { image: { height: 64, imageName, width: 64 }, type: 'image' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'raster',
+});
+
+const createControlLayer = (id: string): CanvasControlLayerContract => ({
+  adapter: { beginEndStepPct: [0, 1], controlMode: 'balanced', kind: 'controlnet', model: null, weight: 1 },
+  blendMode: 'normal',
+  id,
+  isEnabled: true,
+  isLocked: false,
+  name: id,
+  opacity: 1,
+  source: { bitmap: null, type: 'paint' },
+  transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+  type: 'control',
+  withTransparencyEffect: false,
+});
+
+const createInpaintMaskLayer = (id: string): CanvasLayerContract =>
+  ({
+    blendMode: 'normal',
+    id,
+    isEnabled: true,
+    isLocked: false,
+    mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+    name: id,
+    opacity: 1,
+    transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+    type: 'inpaint_mask',
+  }) as CanvasLayerContract;
+
+/** Adds layers top-to-bottom in array order (each `addCanvasLayer` inserts at index 0). */
+// A new project's canvas now seeds one empty inpaint mask (see
+// `createNewCanvasStateV2`). These layer-reducer/staging tests exercise layer
+// mechanics where that default mask is incidental, so they start from an empty
+// canvas document to keep their expectations focused on the layers under test.
+const withEmptyCanvas = (state: WorkbenchState): WorkbenchState =>
+  workbenchReducer(state, { document: createEmptyCanvasDocumentV2(), type: 'replaceCanvasDocument' });
+
+const withCanvasLayers = (state: WorkbenchState, layers: Project['canvas']['document']['layers']): WorkbenchState =>
+  [...layers]
+    .reverse()
+    .reduce((next, layer) => workbenchReducer(next, { layer, type: 'addCanvasLayer' }), withEmptyCanvas(state));
+
+const getCanvas = (state: WorkbenchState) => getActiveProject(state).canvas;
+
+const getLayerIds = (state: WorkbenchState): string[] => getCanvas(state).document.layers.map((layer) => layer.id);
+
+const primeGenerate = (state = createInitialWorkbenchState(), overrides: Partial<GenerateWidgetValues> = {}) =>
+  workbenchReducer(state, { type: 'setGenerateSettings', values: createGenerateValues(overrides) });
+
+const submitGenerate = (state: WorkbenchState) =>
+  workbenchReducer(state, { backendSupportsCancellation: true, type: 'submitInvocationSnapshot' });
+
+describe('workbench widget region defaults', () => {
+  it('enables Diagnostics in the right side panel rail', () => {
+    const state = createInitialWorkbenchState();
+
+    expect(getActiveProject(state).widgetRegions.right.instanceIds).toContain('diagnostics');
+  });
+
+  it('hydrates the old default right rail with Diagnostics while preserving customized rails', () => {
+    const initial = createInitialWorkbenchState();
+    const legacyDefault = {
+      ...initial,
+      projects: initial.projects.map((project) => ({
+        ...project,
+        widgetRegions: {
+          ...project.widgetRegions,
+          right: { ...project.widgetRegions.right, instanceIds: ['queue', 'gallery', 'layers'] },
+        },
+      })),
+    } satisfies WorkbenchState;
+    const customized = {
+      ...initial,
+      projects: initial.projects.map((project) => ({
+        ...project,
+        widgetRegions: {
+          ...project.widgetRegions,
+          right: { ...project.widgetRegions.right, instanceIds: ['gallery', 'layers'] },
+        },
+      })),
+    } satisfies WorkbenchState;
+
+    const hydratedLegacyDefault = workbenchReducer(initial, { state: legacyDefault, type: 'hydrateWorkbench' });
+    const hydratedCustomized = workbenchReducer(initial, { state: customized, type: 'hydrateWorkbench' });
+
+    expect(getActiveProject(hydratedLegacyDefault).widgetRegions.right.instanceIds).toEqual([
+      'gallery',
+      'preview',
+      'queue',
+      'layers',
+      'diagnostics',
+      'project',
+    ]);
+    expect(getActiveProject(hydratedCustomized).widgetRegions.right.instanceIds).toEqual(['gallery', 'layers']);
+  });
+});
+
+describe('workbench widget region opening', () => {
+  it('enables and selects a center widget without toggling it back off', () => {
+    let state = createInitialWorkbenchState();
+    const activeProject = getActiveProject(state);
+    const instanceIds: Project['widgetRegions']['center']['instanceIds'] = ['canvas'];
+
+    state = {
+      ...state,
+      projects: state.projects.map((project) =>
+        project.id === activeProject.id
+          ? {
+              ...project,
+              widgetRegions: {
+                ...project.widgetRegions,
+                center: {
+                  ...project.widgetRegions.center,
+                  activeInstanceId: 'canvas',
+                  instanceIds,
+                },
+              },
+            }
+          : project
+      ),
+    };
+
+    state = workbenchReducer(state, { region: 'center', type: 'openRegionWidget', widgetId: 'preview' });
+
+    expect(getActiveProject(state).widgetRegions.center.activeInstanceId).toBe('preview');
+    expect(getActiveProject(state).widgetRegions.center.instanceIds).toEqual(['canvas', 'preview']);
+
+    state = workbenchReducer(state, { region: 'center', type: 'openRegionWidget', widgetId: 'preview' });
+
+    expect(getActiveProject(state).widgetRegions.center.activeInstanceId).toBe('preview');
+    expect(getActiveProject(state).widgetRegions.center.instanceIds).toEqual(['canvas', 'preview']);
+    expect(getActiveProject(state).widgetRegions.center.isCollapsed).toBe(false);
+  });
+
+  it('opens and uncollapses the target panel region', () => {
+    let state = createInitialWorkbenchState();
+    const activeProject = getActiveProject(state);
+    const instanceIds: Project['widgetRegions']['bottom']['instanceIds'] = ['diagnostics'];
+
+    state = {
+      ...state,
+      projects: state.projects.map((project) =>
+        project.id === activeProject.id
+          ? {
+              ...project,
+              layout: {
+                ...project.layout,
+                panels: { ...project.layout.panels, isBottomOpen: false },
+              },
+              widgetRegions: {
+                ...project.widgetRegions,
+                bottom: {
+                  ...project.widgetRegions.bottom,
+                  activeInstanceId: 'diagnostics',
+                  instanceIds,
+                  isCollapsed: true,
+                },
+              },
+            }
+          : project
+      ),
+    };
+
+    state = workbenchReducer(state, { region: 'bottom', type: 'openRegionWidget', widgetId: 'queue' });
+
+    expect(getActiveProject(state).layout.panels.isBottomOpen).toBe(true);
+    expect(getActiveProject(state).widgetRegions.bottom.activeInstanceId).toBe('queue');
+    expect(getActiveProject(state).widgetRegions.bottom.instanceIds).toEqual(['diagnostics', 'queue']);
+    expect(getActiveProject(state).widgetRegions.bottom.isCollapsed).toBe(false);
+  });
+});
+
+describe('workbench widget state updates', () => {
+  it('patches a missing undefined widget value key as a real state change', () => {
+    const initial = createInitialWorkbenchState();
+    const next = workbenchReducer(initial, {
+      type: 'patchWidgetValues',
+      values: { optionalValue: undefined },
+      widgetId: 'diagnostics',
+    });
+    const values = getProjectWidgetValues(getActiveProject(next), 'diagnostics');
+
+    expect(next).not.toBe(initial);
+    expect(Object.prototype.hasOwnProperty.call(values, 'optionalValue')).toBe(true);
+  });
+
+  it('can patch a widget instance in a non-active project', () => {
+    let state = createInitialWorkbenchState();
+    const firstProjectId = state.activeProjectId;
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    const secondProjectId = state.activeProjectId;
+
+    expect(secondProjectId).not.toBe(firstProjectId);
+
+    state = workbenchReducer(state, {
+      instanceId: 'generate',
+      projectId: firstProjectId,
+      type: 'patchWidgetInstanceValues',
+      values: { projectScoped: true },
+    });
+
+    expect(getProject(state, firstProjectId).widgetInstances.generate?.state.values.projectScoped).toBe(true);
+    expect(getProject(state, secondProjectId).widgetInstances.generate?.state.values.projectScoped).toBeUndefined();
+  });
+
+  it('clones replacement widget instance values before storing them', () => {
+    let state = createInitialWorkbenchState();
+    const values: Record<string, unknown> = { mutable: 'before' };
+
+    state = workbenchReducer(state, { instanceId: 'generate', type: 'setWidgetInstanceValues', values });
+    values.mutable = 'after';
+
+    expect(getActiveProject(state).widgetInstances.generate?.state.values.mutable).toBe('before');
+  });
+
+  it('clones patched widget instance values before storing them', () => {
+    let state = createInitialWorkbenchState();
+    const values: Record<string, unknown> = { nested: { mutable: 'before' } };
+
+    state = workbenchReducer(state, { instanceId: 'generate', type: 'patchWidgetInstanceValues', values });
+    (values.nested as { mutable: string }).mutable = 'after';
+
+    expect(getActiveProject(state).widgetInstances.generate?.state.values.nested).toEqual({ mutable: 'before' });
+  });
+});
+
+describe('workbench layout presets', () => {
+  it('applies the Default preset as a full widget-region layout', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, { presetId: 'canvas-default', type: 'applyPreset' });
+
+    const project = getActiveProject(state);
+
+    expect(project.layout.panels).toEqual({ isBottomOpen: false, isLeftOpen: true, isRightOpen: true });
+    expect(project.widgetRegions.left).toMatchObject({
+      activeInstanceId: 'generate',
+      instanceIds: ['generate', 'workflow'],
+      isCollapsed: false,
+      sizePx: 450,
+    });
+    expect(project.widgetRegions.center).toMatchObject({
+      activeInstanceId: 'preview',
+      instanceIds: ['preview', 'canvas', 'gallery:center', 'workflow:center'],
+      isCollapsed: false,
+      sizePx: 0,
+    });
+    expect(project.widgetRegions.right).toMatchObject({
+      activeInstanceId: 'gallery',
+      instanceIds: ['gallery', 'preview', 'queue', 'layers', 'diagnostics', 'project'],
+      isCollapsed: false,
+      sizePx: 450,
+    });
+    expect(project.widgetRegions.bottom).toMatchObject({
+      activeInstanceId: 'gallery:bottom',
+      instanceIds: [
+        'server-status',
+        'diagnostics:bottom',
+        'gallery:bottom',
+        'notifications',
+        'autosave-status',
+        'version-status',
+        'workflow:bottom',
+      ],
+      isCollapsed: true,
+      sizePx: 180,
+    });
+  });
+
+  it('adds a custom preset from the active project layout and applies it later', () => {
+    let state = createInitialWorkbenchState();
+    const projectId = state.activeProjectId;
+
+    state = workbenchReducer(state, { region: 'right', sizePx: 336, type: 'setRegionWidgetSize' });
+    state = workbenchReducer(state, { region: 'right', type: 'selectRegionWidget', widgetId: 'queue' });
+    state = workbenchReducer(state, { region: 'center', type: 'selectRegionWidget', widgetId: 'preview' });
+    state = workbenchReducer(state, {
+      label: 'Queue review',
+      presetId: 'custom-layout-1',
+      type: 'addLayoutPreset',
+    });
+
+    state = workbenchReducer(state, { presetId: 'canvas', type: 'applyPreset' });
+    state = workbenchReducer(state, { presetId: 'custom-layout-1', type: 'applyPreset' });
+
+    const project = getProject(state, projectId);
+
+    expect(state.account.customLayoutPresets).toHaveLength(1);
+    expect(state.account.customLayoutPresets?.[0]).toMatchObject({ id: 'custom-layout-1', label: 'Queue review' });
+    expect(project.widgetRegions.right).toMatchObject({ activeInstanceId: 'queue', sizePx: 336 });
+    expect(project.widgetRegions.center.activeInstanceId).toBe('preview');
+  });
+
+  it('renames and deletes only custom layout presets', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, {
+      label: 'Original',
+      presetId: 'custom-layout-1',
+      type: 'addLayoutPreset',
+    });
+    state = workbenchReducer(state, {
+      label: 'Renamed',
+      presetId: 'custom-layout-1',
+      type: 'renameLayoutPreset',
+    });
+    state = workbenchReducer(state, { presetId: 'canvas-default', type: 'renameLayoutPreset', label: 'Nope' });
+    state = workbenchReducer(state, { presetId: 'custom-layout-1', type: 'deleteLayoutPreset' });
+
+    expect(state.account.customLayoutPresets).toEqual([]);
+  });
+});
+
+describe('workbenchReducer Phase 5 generation flow', () => {
+  it('does not notify gallery total subscribers for unchanged or non-finite totals', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, { totalImages: 3, type: 'setGalleryPageInfo' });
+
+    const unchanged = workbenchReducer(state, { totalImages: 3, type: 'setGalleryPageInfo' });
+    const nonFinite = workbenchReducer(state, { totalImages: Number.NaN, type: 'setGalleryPageInfo' });
+
+    expect(unchanged).toBe(state);
+    expect(nonFinite).toBe(state);
+  });
+
+  it('routes queue results back to the originating project after the user switches projects', () => {
+    let state = submitGenerate(primeGenerate());
+    const originProject = getActiveProject(state);
+    const queueItem = originProject.queue.items[0];
+
+    expect(queueItem).toBeDefined();
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    state = workbenchReducer(state, { projectId: originProject.id, type: 'switchProject' });
+
+    const otherProjectId = state.projects.find((project) => project.id !== originProject.id)?.id;
+
+    expect(otherProjectId).toBeDefined();
+
+    state = workbenchReducer(state, { projectId: otherProjectId as string, type: 'switchProject' });
+    state = workbenchReducer(state, {
+      backendItemIds: [42],
+      projectId: originProject.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, {
+      images: [createImage('origin-image.png', queueItem.id)],
+      projectId: originProject.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+
+    const updatedOriginProject = getProject(state, originProject.id);
+    const activeProject = getActiveProject(state);
+
+    expect(activeProject.id).toBe(otherProjectId);
+    expect(updatedOriginProject.canvas.stagingArea.pendingImageIds).toEqual(['origin-image.png']);
+    expect(updatedOriginProject.queue.items[0]?.status).toBe('completed');
+    expect(activeProject.canvas.stagingArea.pendingImageIds).toEqual([]);
+    expect(activeProject.queue.items).toEqual([]);
+  });
+
+  it('appends a workflow candidate to its explicit project and selects its resolved staging slot', () => {
+    let state = createInitialWorkbenchState();
+    const originProjectId = state.activeProjectId;
+    const firstCandidate = createStagingCandidate('first.png', 'layer-workflow:first', {
+      height: 100,
+      opacity: 1,
+      width: 200,
+      x: 5,
+      y: 7,
+    });
+    const appendedCandidate = createStagingCandidate('second.png', 'layer-workflow:second', {
+      height: 240,
+      opacity: 0.45,
+      width: 320,
+      x: 11,
+      y: 17,
+    });
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    const activeProjectId = state.activeProjectId;
+    state = workbenchReducer(state, {
+      candidate: firstCandidate,
+      projectId: originProjectId,
+      type: 'appendCanvasStagingCandidate',
+    });
+    state = workbenchReducer(state, {
+      candidate: appendedCandidate,
+      projectId: originProjectId,
+      type: 'appendCanvasStagingCandidate',
+    });
+
+    const originProject = getProject(state, originProjectId);
+    const slots = getCanvasStagingSlots(originProject.canvas, originProject.queue.items);
+
+    expect(state.activeProjectId).toBe(activeProjectId);
+    expect(originProject.canvas.stagingArea.pendingImages).toEqual([firstCandidate, appendedCandidate]);
+    expect(originProject.canvas.stagingArea.pendingImageIds).toEqual(['first.png', 'second.png']);
+    expect(originProject.canvas.stagingArea.isVisible).toBe(true);
+    expect(originProject.canvas.stagingArea.selectedImageIndex).toBe(1);
+    expect(slots[originProject.canvas.stagingArea.selectedImageIndex]).toMatchObject({
+      candidate: { imageName: 'second.png', placement: appendedCandidate.placement },
+      kind: 'candidate',
+    });
+    expect(getProject(state, activeProjectId).canvas.stagingArea.pendingImages).toEqual([]);
+  });
+
+  it('accepts a workflow candidate at its own placement, scale, and opacity', () => {
+    let state = withEmptyCanvas(createInitialWorkbenchState());
+    const projectId = state.activeProjectId;
+    const candidate = createStagingCandidate('dimension-changing-result.png', 'layer-workflow:request-1', {
+      height: 200,
+      opacity: 0.35,
+      width: 300,
+      x: 31,
+      y: 47,
+    });
+
+    state = workbenchReducer(state, { candidate, projectId, type: 'appendCanvasStagingCandidate' });
+    state = commitSelectedStagedImage(state);
+
+    const acceptedLayer = getActiveProject(state).canvas.document.layers[0];
+
+    expect(getRasterLayerImageName(acceptedLayer)).toBe('dimension-changing-result.png');
+    expect(getRasterLayerPlacement(acceptedLayer)).toEqual(candidate.placement);
+  });
+
+  it('accepts a staged candidate in the addressed project after another project becomes active', () => {
+    let state = withEmptyCanvas(createInitialWorkbenchState());
+    const originProjectId = state.activeProjectId;
+    const candidate = createStagingCandidate('origin-result.png', 'layer-workflow:origin', {
+      height: 64,
+      opacity: 0.75,
+      width: 96,
+      x: 13,
+      y: 17,
+    });
+    state = workbenchReducer(state, {
+      candidate,
+      projectId: originProjectId,
+      type: 'appendCanvasStagingCandidate',
+    });
+    state = workbenchReducer(state, { type: 'createProject' });
+    const activeProjectId = state.activeProjectId;
+
+    state = commitSelectedStagedImage(state, originProjectId);
+
+    expect(state.activeProjectId).toBe(activeProjectId);
+    expect(getRasterLayerImageName(getProject(state, originProjectId).canvas.document.layers[0])).toBe(
+      'origin-result.png'
+    );
+    expect(getProject(state, activeProjectId).canvas.document.layers).not.toContainEqual(
+      expect.objectContaining({
+        source: expect.objectContaining({ image: expect.objectContaining({ imageName: 'origin-result.png' }) }),
+      })
+    );
+  });
+
+  it('keeps submitted Generate snapshots immutable after later settings changes', () => {
+    let state = submitGenerate(primeGenerate(undefined, { positivePrompt: 'first prompt', shouldRandomizeSeed: true }));
+    const firstQueueItem = getActiveProject(state).queue.items[0];
+
+    expect(firstQueueItem).toBeDefined();
+
+    state = primeGenerate(state, { positivePrompt: 'second prompt', seed: 999 });
+    state = submitGenerate(state);
+
+    const [secondQueueItem, unchangedFirstQueueItem] = getActiveProject(state).queue.items;
+    const firstValues = unchangedFirstQueueItem?.snapshot.widgetStates.generate
+      .values as unknown as GenerateWidgetValues;
+    const secondValues = secondQueueItem?.snapshot.widgetStates.generate.values as unknown as GenerateWidgetValues;
+
+    expect(firstValues.positivePrompt).toBe('first prompt');
+    expect(firstValues.shouldRandomizeSeed).toBe(true);
+    expect(typeof firstValues.seed).toBe('number');
+    expect(secondValues.positivePrompt).toBe('second prompt');
+    expect(secondValues.seed).toBe(999);
+  });
+
+  it('accepts a staged candidate into a selected raster layer that project undo no longer touches', () => {
+    let state = submitGenerate(primeGenerate(withEmptyCanvas(createInitialWorkbenchState())));
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate.png', queueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = commitSelectedStagedImage(state);
+
+    let project = getActiveProject(state);
+    const acceptedLayerId = project.canvas.document.layers[0]?.id;
+
+    expect(project.canvas.document.layers).toHaveLength(1);
+    expect(getRasterLayerImageName(project.canvas.document.layers[0])).toBe('candidate.png');
+    expect(project.canvas.document.selectedLayerId).toBe(acceptedLayerId);
+    expect(project.canvas.stagingArea.pendingImages).toEqual([]);
+    // Deliberate semantic change (P0.2): canvas is engine-owned, so accepting a
+    // staged image does not create a project-level undo entry.
+    expect(project.undoRedo.past).toHaveLength(0);
+
+    state = commitSelectedStagedImage(state);
+    project = getActiveProject(state);
+
+    expect(project.canvas.document.layers).toHaveLength(1);
+
+    // Project undo neither snapshots nor restores canvas: the accepted layer survives.
+    state = workbenchReducer(state, { type: 'undoProjectChange' });
+    project = getActiveProject(state);
+
+    expect(project.canvas.document.layers).toHaveLength(1);
+    expect(getRasterLayerImageName(project.canvas.document.layers[0])).toBe('candidate.png');
+  });
+
+  it('discards selected and all staged canvas candidates without touching accepted document layers', () => {
+    let state = submitGenerate(primeGenerate(withEmptyCanvas(createInitialWorkbenchState())));
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate-1.png', queueItem.id), createImage('candidate-2.png', queueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = workbenchReducer(state, { imageIndex: 1, type: 'setStagedImageIndex' });
+    state = workbenchReducer(state, { type: 'discardSelectedStagedImage' });
+
+    let project = getActiveProject(state);
+
+    expect(project.canvas.document.layers).toEqual([]);
+    expect(project.canvas.stagingArea.pendingImageIds).toEqual(['candidate-1.png']);
+    expect(project.canvas.stagingArea.selectedImageIndex).toBe(0);
+    expect(project.canvas.stagingArea.isVisible).toBe(true);
+
+    state = workbenchReducer(state, { type: 'discardAllStagedImages' });
+    project = getActiveProject(state);
+
+    expect(project.canvas.stagingArea.pendingImages).toEqual([]);
+    expect(project.canvas.stagingArea.pendingImageIds).toEqual([]);
+    expect(project.canvas.stagingArea.isVisible).toBe(false);
+  });
+
+  it('normalizes ordinary queue results to the queued bbox origin and native image size', () => {
+    let state = submitGenerate(primeGenerate());
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, { bbox: { height: 256, width: 256, x: 40, y: 24 }, type: 'setCanvasBbox' });
+    state = workbenchReducer(state, {
+      images: [createImage('candidate-1.png', queueItem.id), createImage('candidate-2.png', queueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = workbenchReducer(state, { direction: -1, type: 'cycleStagedImage' });
+
+    expect(getActiveProject(state).canvas.stagingArea.selectedImageIndex).toBe(1);
+    expect(getActiveProject(state).canvas.stagingArea.pendingImages[1]?.placement).toEqual({
+      height: 768,
+      opacity: 1,
+      width: 512,
+      x: 0,
+      y: 0,
+    });
+
+    state = commitSelectedStagedImage(state);
+
+    let project = getActiveProject(state);
+    const acceptedLayer = project.canvas.document.layers[0];
+
+    expect(getRasterLayerImageName(acceptedLayer)).toBe('candidate-2.png');
+    expect(getRasterLayerPlacement(acceptedLayer)).toEqual({ height: 768, opacity: 1, width: 512, x: 0, y: 0 });
+
+    // Project undo/redo leaves the engine-owned canvas alone.
+    state = workbenchReducer(state, { type: 'undoProjectChange' });
+    project = getActiveProject(state);
+
+    expect(getRasterLayerImageName(project.canvas.document.layers[0])).toBe('candidate-2.png');
+  });
+
+  it('cycles pending canvas placeholder slots before results complete', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 2 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+
+    expect(
+      getCanvasStagingSlots(getCanvas(state), getActiveProject(state).queue.items).map((slot) => slot.kind)
+    ).toEqual(['placeholder', 'placeholder']);
+
+    state = workbenchReducer(state, { direction: 1, type: 'cycleStagedImage' });
+
+    expect(getActiveProject(state).canvas.stagingArea.selectedImageIndex).toBe(1);
+  });
+
+  it('stages canvas partial results while the rest of the batch keeps placeholders', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 2 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, {
+      backendItemId: 11,
+      images: [createImage('candidate-1.png', queueItem.id)],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemPartialResults',
+    });
+
+    const updatedProject = getActiveProject(state);
+    const slots = getCanvasStagingSlots(updatedProject.canvas, updatedProject.queue.items);
+
+    expect(updatedProject.queue.items[0]).toMatchObject({ completedBackendItemIds: [11], status: 'running' });
+    expect(updatedProject.canvas.stagingArea.pendingImageIds).toEqual(['candidate-1.png']);
+    expect(slots.map((slot) => slot.kind)).toEqual(['candidate', 'placeholder']);
+    expect(slots[0]).toMatchObject({ itemIndex: 1, kind: 'candidate', queueItemId: queueItem.id });
+    expect(updatedProject.canvas.stagingArea.pendingImages[0]).toMatchObject({ sourceBackendItemId: 11 });
+    expect(updatedProject.canvas.stagingArea.pendingImages[0]?.placement).toEqual({
+      height: 768,
+      opacity: 1,
+      width: 512,
+      x: updatedProject.canvas.document.bbox.x,
+      y: updatedProject.canvas.document.bbox.y,
+    });
+    expect(slots[1]).toMatchObject({ itemIndex: 2, queueItemId: queueItem.id });
+  });
+
+  it('preserves the selected staged candidate when final results duplicate partial results', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 2 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+    const firstImage = createImage('candidate-1.png', queueItem.id);
+    const secondImage = createImage('candidate-2.png', queueItem.id);
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, {
+      backendItemId: 11,
+      images: [firstImage],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemPartialResults',
+    });
+    state = workbenchReducer(state, {
+      backendItemId: 12,
+      images: [secondImage],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemPartialResults',
+    });
+    state = workbenchReducer(state, { imageIndex: 1, type: 'setStagedImageIndex' });
+    state = workbenchReducer(state, {
+      images: [firstImage, secondImage],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+
+    expect(getActiveProject(state).canvas.stagingArea.pendingImageIds).toEqual(['candidate-1.png', 'candidate-2.png']);
+    expect(getActiveProject(state).canvas.stagingArea.pendingImages).toMatchObject([
+      { sourceBackendItemId: 11 },
+      { sourceBackendItemId: 12 },
+    ]);
+    expect(getActiveProject(state).canvas.stagingArea.selectedImageIndex).toBe(1);
+  });
+
+  it('clamps the selected staging slot when backend cancellation removes the selected placeholder', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 3 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12, 13],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, { imageIndex: 2, type: 'setStagedImageIndex' });
+    state = workbenchReducer(state, {
+      backendItemId: 13,
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendCancelled',
+    });
+
+    expect(getCanvasStagingSlots(getCanvas(state), getActiveProject(state).queue.items)).toHaveLength(2);
+    expect(getActiveProject(state).canvas.stagingArea.selectedImageIndex).toBe(1);
+  });
+
+  it('accepts the selected candidate when placeholders precede it in the staging strip', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 1 }));
+    const firstProject = getActiveProject(state);
+    const firstQueueItem = firstProject.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11],
+      projectId: firstProject.id,
+      queueItemId: firstQueueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = submitGenerate(primeGenerate(state, { positivePrompt: 'second prompt' }));
+
+    const secondProject = getActiveProject(state);
+    const secondQueueItem = secondProject.queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate-2.png', secondQueueItem.id)],
+      projectId: secondProject.id,
+      queueItemId: secondQueueItem.id,
+      type: 'routeQueueItemResults',
+    });
+
+    expect(
+      getCanvasStagingSlots(getCanvas(state), getActiveProject(state).queue.items).map((slot) => slot.kind)
+    ).toEqual(['placeholder', 'candidate']);
+    expect(getCanvas(state).stagingArea.selectedImageIndex).toBe(1);
+
+    state = commitSelectedStagedImage(state);
+
+    expect(getRasterLayerImageName(getActiveProject(state).canvas.document.layers[0])).toBe('candidate-2.png');
+  });
+
+  it('discards the selected candidate when placeholders precede it in the staging strip', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 1 }));
+    const firstProject = getActiveProject(state);
+    const firstQueueItem = firstProject.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11],
+      projectId: firstProject.id,
+      queueItemId: firstQueueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = submitGenerate(primeGenerate(state, { positivePrompt: 'second prompt' }));
+
+    const secondProject = getActiveProject(state);
+    const secondQueueItem = secondProject.queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate-2.png', secondQueueItem.id)],
+      projectId: secondProject.id,
+      queueItemId: secondQueueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = workbenchReducer(state, { type: 'discardSelectedStagedImage' });
+
+    expect(getActiveProject(state).canvas.stagingArea.pendingImages).toEqual([]);
+    expect(
+      getCanvasStagingSlots(getCanvas(state), getActiveProject(state).queue.items).map((slot) => slot.kind)
+    ).toEqual(['placeholder']);
+    expect(getCanvas(state).stagingArea.isVisible).toBe(true);
+  });
+
+  it('keeps thumbnail strip visibility separate from staged result preview visibility', () => {
+    let state = submitGenerate(primeGenerate());
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate-1.png', queueItem.id), createImage('candidate-2.png', queueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+
+    expect(getActiveProject(state).canvas.stagingArea.pendingImageIds).toEqual(['candidate-1.png', 'candidate-2.png']);
+    expect(getActiveProject(state).canvas.stagingArea.areThumbnailsVisible).toBe(true);
+    expect(getActiveProject(state).canvas.stagingArea.isVisible).toBe(true);
+
+    state = workbenchReducer(state, { type: 'toggleCanvasStagingThumbnailsVisibility' });
+    expect(getActiveProject(state).canvas.stagingArea.areThumbnailsVisible).toBe(false);
+    expect(getActiveProject(state).canvas.stagingArea.isVisible).toBe(true);
+
+    state = workbenchReducer(state, { type: 'toggleCanvasStagingVisibility' });
+    expect(getActiveProject(state).canvas.stagingArea.areThumbnailsVisible).toBe(false);
+    expect(getActiveProject(state).canvas.stagingArea.isVisible).toBe(false);
+  });
+
+  it('appends later canvas results to the active staging session instead of replacing candidates', () => {
+    let state = submitGenerate(primeGenerate());
+    const firstQueueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate-1.png', firstQueueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: firstQueueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = submitGenerate(primeGenerate(state, { positivePrompt: 'second prompt' }));
+
+    const secondQueueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate-2.png', secondQueueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: secondQueueItem.id,
+      type: 'routeQueueItemResults',
+    });
+
+    expect(getActiveProject(state).canvas.stagingArea.pendingImageIds).toEqual(['candidate-1.png', 'candidate-2.png']);
+    expect(getActiveProject(state).canvas.stagingArea.selectedImageIndex).toBe(1);
+  });
+
+  it('keeps staged canvas candidates isolated per project when switching projects', () => {
+    let state = submitGenerate(primeGenerate());
+    const originProject = getActiveProject(state);
+    const queueItem = originProject.queue.items[0];
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    state = workbenchReducer(state, { projectId: originProject.id, type: 'switchProject' });
+
+    const otherProjectId = state.projects.find((project) => project.id !== originProject.id)?.id;
+
+    expect(otherProjectId).toBeDefined();
+
+    state = workbenchReducer(state, {
+      images: [createImage('origin-candidate.png', queueItem.id)],
+      projectId: originProject.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = workbenchReducer(state, { projectId: otherProjectId as string, type: 'switchProject' });
+
+    expect(getActiveProject(state).canvas.stagingArea.pendingImages).toEqual([]);
+
+    state = workbenchReducer(state, { projectId: originProject.id, type: 'switchProject' });
+
+    expect(getActiveProject(state).canvas.stagingArea.pendingImageIds).toEqual(['origin-candidate.png']);
+  });
+
+  it('marks cancellable running queue items cancelled for backend cancellation', () => {
+    let state = submitGenerate(primeGenerate());
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [42],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, { queueItemId: queueItem.id, type: 'cancelQueueItem' });
+
+    expect(getActiveProject(state).queue.items[0]?.status).toBe('cancelled');
+  });
+
+  it('cancels queue items from inactive projects when a project id is provided', () => {
+    let state = submitGenerate(primeGenerate());
+    const originProject = getActiveProject(state);
+    const queueItem = originProject.queue.items[0];
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    expect(getActiveProject(state).id).not.toBe(originProject.id);
+
+    state = workbenchReducer(state, {
+      projectId: originProject.id,
+      queueItemId: queueItem.id,
+      type: 'cancelQueueItem',
+    });
+
+    expect(getProject(state, originProject.id).queue.items[0]?.status).toBe('cancelled');
+  });
+
+  it('cancels all active cancellable queue items from the queue actions menu', () => {
+    let state = submitGenerate(primeGenerate());
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    state = submitGenerate(primeGenerate(state));
+    state = workbenchReducer(state, { type: 'cancelAllQueueItems' });
+
+    expect(state.projects.flatMap((project) => project.queue.items.map((item) => item.status))).toEqual([
+      'cancelled',
+      'cancelled',
+    ]);
+  });
+
+  it('cancels active queue items except the current one', () => {
+    let state = submitGenerate(primeGenerate());
+    const firstQueueItemId = getActiveProject(state).queue.items[0].id;
+
+    state = submitGenerate(primeGenerate(state));
+    state = workbenchReducer(state, {
+      currentQueueItemId: firstQueueItemId,
+      type: 'cancelAllQueueItemsExceptCurrent',
+    });
+
+    expect(getActiveProject(state).queue.items.map((item) => ({ id: item.id, status: item.status }))).toEqual([
+      { id: getActiveProject(state).queue.items[0].id, status: 'cancelled' },
+      { id: firstQueueItemId, status: 'pending' },
+    ]);
+  });
+
+  it('records backend item cancellation without cancelling the whole local batch', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 3 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12, 13],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, {
+      backendItemId: 12,
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendCancelled',
+    });
+
+    expect(getActiveProject(state).queue.items[0]).toMatchObject({
+      cancelledBackendItemIds: [12],
+      status: 'running',
+    });
+  });
+
+  it('marks a local queue item cancelled only when all backend items were cancelled', () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 2 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, {
+      backendItemId: 11,
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendCancelled',
+    });
+    state = workbenchReducer(state, {
+      backendItemId: 12,
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendCancelled',
+    });
+
+    expect(getActiveProject(state).queue.items[0]).toMatchObject({
+      cancelledBackendItemIds: [11, 12],
+      status: 'cancelled',
+    });
+  });
+
+  it('scopes cancel all queue items to a project when requested', () => {
+    let state = submitGenerate(primeGenerate());
+    const originProject = getActiveProject(state);
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    state = submitGenerate(primeGenerate(state));
+    state = workbenchReducer(state, { projectId: originProject.id, type: 'cancelAllQueueItems' });
+
+    expect(getProject(state, originProject.id).queue.items.map((item) => item.status)).toEqual(['cancelled']);
+    expect(getActiveProject(state).queue.items.map((item) => item.status)).toEqual(['pending']);
+  });
+
+  it('clears completed and failed queue items while preserving active and cancelled items', () => {
+    let state = submitGenerate(primeGenerate());
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('completed-result.png', queueItem.id)],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = submitGenerate(primeGenerate(state));
+    const activeQueueItem = getActiveProject(state).queue.items[0];
+    state = workbenchReducer(state, { queueItemId: activeQueueItem.id, type: 'cancelQueueItem' });
+    state = submitGenerate(primeGenerate(state));
+    const failedQueueItem = getActiveProject(state).queue.items[0];
+    state = workbenchReducer(state, {
+      error: 'failed',
+      projectId: project.id,
+      queueItemId: failedQueueItem.id,
+      status: 'failed',
+      type: 'setQueueItemStatus',
+    });
+
+    state = workbenchReducer(state, { type: 'clearCompletedQueueItems' });
+
+    expect(getActiveProject(state).queue.items.map((item) => item.status)).toEqual(['cancelled']);
+  });
+
+  it('can mark stale reconciled queue items failed without creating notifications', () => {
+    let state = submitGenerate(primeGenerate());
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+    const notificationCount = state.notifications.length;
+
+    state = workbenchReducer(state, {
+      error: 'This run is no longer on the backend queue.',
+      notify: false,
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      status: 'failed',
+      type: 'setQueueItemStatus',
+    });
+
+    expect(getActiveProject(state).queue.items[0]?.status).toBe('failed');
+    expect(getActiveProject(state).queue.items[0]?.error).toBe('This run is no longer on the backend queue.');
+    expect(state.notifications).toHaveLength(notificationCount);
+  });
+
+  it('keeps cancellation terminal when backend item ids arrive late', () => {
+    let state = submitGenerate(primeGenerate());
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, { queueItemId: queueItem.id, type: 'cancelQueueItem' });
+    state = workbenchReducer(state, {
+      backendItemIds: [42],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, {
+      images: [createImage('late-result.png', queueItem.id)],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = workbenchReducer(state, {
+      error: 'backend cancellation completed',
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      status: 'failed',
+      type: 'setQueueItemStatus',
+    });
+
+    const cancelledItem = getActiveProject(state).queue.items[0];
+
+    expect(cancelledItem?.status).toBe('cancelled');
+    expect(cancelledItem?.backendItemIds).toEqual([42]);
+    expect(getActiveProject(state).canvas.stagingArea.pendingImages).toEqual([]);
+    expect(state.notifications.map((notification) => notification.title)).toEqual([
+      'Invocation cancellation requested',
+      'Invocation queued',
+    ]);
+  });
+
+  it('does not report cancellation for completed queue items', () => {
+    let state = submitGenerate(primeGenerate());
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('completed-result.png', queueItem.id)],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = workbenchReducer(state, { queueItemId: queueItem.id, type: 'cancelQueueItem' });
+
+    expect(getActiveProject(state).queue.items[0]?.status).toBe('completed');
+    expect(state.notifications.map((notification) => notification.title)).toEqual([
+      'Invocation completed',
+      'Invocation queued',
+    ]);
+  });
+
+  it('records notifications for errors and successful operations', () => {
+    let state = submitGenerate(primeGenerate());
+
+    expect(state.notifications[0]?.title).toBe('Invocation queued');
+
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('candidate.png', queueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = commitSelectedStagedImage(state);
+    state = workbenchReducer(state, { message: 'boom', type: 'recordError' });
+
+    expect(state.notifications.map((notification) => notification.title)).toEqual([
+      'Error',
+      'Invocation completed',
+      'Invocation queued',
+    ]);
+    expect(state.notifications.every((notification) => !notification.isRead)).toBe(true);
+
+    state = workbenchReducer(state, { type: 'markAllNotificationsRead' });
+
+    expect(state.notifications.every((notification) => notification.isRead)).toBe(true);
+
+    state = workbenchReducer(state, { type: 'clearNotifications' });
+
+    expect(state.notifications).toEqual([]);
+
+    expect(state.notifications).toEqual([]);
+  });
+
+  it('accepts the project graph source but does not queue an empty project graph', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, { sourceId: 'workflow', type: 'setInvocationSource' });
+
+    expect(getActiveProject(state).invocation.sourceId).toBe('workflow');
+
+    state = workbenchReducer(state, {
+      backendSupportsCancellation: true,
+      route: { destination: 'canvas', destinationLocked: false, sourceId: 'workflow', sourceLocked: true },
+      type: 'submitResolvedInvocationSnapshot',
+    });
+
+    expect(getActiveProject(state).queue.items).toEqual([]);
+  });
+
+  it('applies workflow edits to the project graph with undo and auto-source', () => {
+    let state = createInitialWorkbenchState();
+
+    expect(getActiveProject(state).invocation.sourceId).toBe('generate');
+
+    state = workbenchReducer(state, {
+      action: {
+        node: {
+          data: {
+            inputs: {},
+            isIntermediate: true,
+            isOpen: true,
+            label: '',
+            nodePack: 'invokeai',
+            notes: '',
+            type: 'add',
+            useCache: true,
+            version: '1.0.0',
+          },
+          id: 'node-1',
+          position: { x: 0, y: 0 },
+          type: 'invocation',
+        },
+        type: 'addNode',
+      },
+      type: 'applyProjectGraphAction',
+    });
+
+    const project = getActiveProject(state);
+
+    // A meaningful graph edit lands in the document, creates an undo entry,
+    // and steers the unlocked invocation source to the project graph.
+    expect(project.projectGraph.nodes).toHaveLength(1);
+    expect(project.undoRedo.past.at(-1)?.label).toBe('Add workflow node');
+    expect(project.invocation.sourceId).toBe('workflow');
+
+    state = workbenchReducer(state, { type: 'undoProjectChange' });
+
+    expect(getActiveProject(state).projectGraph.nodes).toHaveLength(0);
+  });
+
+  it('replaceProjectGraph snapshots the previous document into graph history', () => {
+    let state = createInitialWorkbenchState();
+    const originalGraphId = getActiveProject(state).projectGraph.id;
+
+    state = workbenchReducer(state, {
+      document: { ...getActiveProject(state).projectGraph, id: 'replacement-graph', name: 'Replacement' },
+      label: 'Test replace',
+      type: 'replaceProjectGraph',
+    });
+
+    const project = getActiveProject(state);
+
+    expect(project.projectGraph.id).toBe('replacement-graph');
+    expect(project.graphHistory[0]?.document?.id).toBe(originalGraphId);
+
+    state = workbenchReducer(state, {
+      snapshotId: project.graphHistory[0]?.id ?? '',
+      type: 'restoreProjectGraphSnapshot',
+    });
+
+    expect(getActiveProject(state).projectGraph.id).toBe(originalGraphId);
+  });
+
+  it('does not queue sources that are still unavailable', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, { sourceId: 'upscale', type: 'setInvocationSource' });
+
+    expect(getActiveProject(state).invocation.sourceId).toBe('generate');
+
+    state = workbenchReducer(state, {
+      backendSupportsCancellation: true,
+      route: { destination: 'canvas', destinationLocked: false, sourceId: 'upscale', sourceLocked: true },
+      type: 'submitResolvedInvocationSnapshot',
+    });
+
+    expect(getActiveProject(state).queue.items).toEqual([]);
+  });
+
+  it('does not queue Generate snapshots with non-finite numeric settings', () => {
+    let state = primeGenerate(undefined, { seed: Number.NaN });
+
+    state = submitGenerate(state);
+
+    expect(getActiveProject(state).queue.items).toEqual([]);
+  });
+
+  it('records submitted Generate prompt pairs in project prompt history', () => {
+    let state = primeGenerate(undefined, { negativePrompt: ' blurry ', positivePrompt: ' a cat ' });
+
+    state = submitGenerate(state);
+
+    expect(getActiveProject(state).promptHistory).toEqual([{ negativePrompt: 'blurry', positivePrompt: 'a cat' }]);
+  });
+
+  it('does not record empty Generate prompt pairs', () => {
+    let state = primeGenerate(undefined, { negativePrompt: ' ', positivePrompt: ' ' });
+
+    state = submitGenerate(state);
+
+    expect(getActiveProject(state).promptHistory).toEqual([]);
+  });
+
+  it('stores disabled negative prompts as null in project prompt history', () => {
+    let state = primeGenerate(undefined, {
+      negativePrompt: 'ignored negative prompt',
+      negativePromptEnabled: false,
+      positivePrompt: 'a cat',
+    });
+
+    state = submitGenerate(state);
+
+    expect(getActiveProject(state).promptHistory).toEqual([{ negativePrompt: null, positivePrompt: 'a cat' }]);
+  });
+
+  it('patches Generate settings without replacing unchanged nested values', () => {
+    const loraModel = { base: 'sdxl', key: 'lora-1', name: 'LoRA', type: 'lora' } as const;
+    const state = primeGenerate(undefined, {
+      loras: [{ isEnabled: true, model: loraModel, weight: 0.75 }],
+      positivePrompt: 'before',
+    });
+    const beforeValues = getProjectWidgetValues(getActiveProject(state), 'generate') as unknown as GenerateWidgetValues;
+    const nextState = workbenchReducer(state, {
+      type: 'patchGenerateSettings',
+      values: { positivePrompt: 'after' },
+    });
+    const afterValues = getProjectWidgetValues(
+      getActiveProject(nextState),
+      'generate'
+    ) as unknown as GenerateWidgetValues;
+
+    expect(afterValues.positivePrompt).toBe('after');
+    expect(afterValues.model).toBe(beforeValues.model);
+    expect(afterValues.loras).toBe(beforeValues.loras);
+  });
+
+  it('deduplicates prompt history by prompt pair and moves the newest submission to the top', () => {
+    let state = primeGenerate(undefined, { negativePrompt: 'low quality', positivePrompt: 'a cat' });
+
+    state = submitGenerate(state);
+    state = workbenchReducer(state, {
+      type: 'setGenerateSettings',
+      values: createGenerateValues({ negativePrompt: 'blurry', positivePrompt: 'a dog' }),
+    });
+    state = submitGenerate(state);
+    state = workbenchReducer(state, {
+      type: 'setGenerateSettings',
+      values: createGenerateValues({ negativePrompt: 'low quality', positivePrompt: 'a cat' }),
+    });
+    state = submitGenerate(state);
+
+    expect(getActiveProject(state).promptHistory).toEqual([
+      { negativePrompt: 'low quality', positivePrompt: 'a cat' },
+      { negativePrompt: 'blurry', positivePrompt: 'a dog' },
+    ]);
+  });
+
+  it('caps project prompt history', () => {
+    let state = createInitialWorkbenchState();
+
+    for (let i = 0; i < MAX_PROMPT_HISTORY + 1; i += 1) {
+      state = primeGenerate(state, { positivePrompt: `prompt ${i}` });
+      state = submitGenerate(state);
+    }
+
+    const history = getActiveProject(state).promptHistory;
+
+    expect(history).toHaveLength(MAX_PROMPT_HISTORY);
+    expect(history[0]?.positivePrompt).toBe(`prompt ${MAX_PROMPT_HISTORY}`);
+    expect(history.at(-1)?.positivePrompt).toBe('prompt 1');
+  });
+
+  it('supports explicit prompt history remove and clear actions', () => {
+    let state = primeGenerate(undefined, { negativePrompt: 'low quality', positivePrompt: 'a cat' });
+
+    state = submitGenerate(state);
+    state = workbenchReducer(state, {
+      prompt: { negativePrompt: 'blurry', positivePrompt: 'a dog' },
+      type: 'addPromptToHistory',
+    });
+    state = workbenchReducer(state, {
+      prompt: { negativePrompt: 'low quality', positivePrompt: 'a cat' },
+      type: 'removePromptFromHistory',
+    });
+
+    expect(getActiveProject(state).promptHistory).toEqual([{ negativePrompt: 'blurry', positivePrompt: 'a dog' }]);
+
+    state = workbenchReducer(state, { type: 'clearPromptHistory' });
+
+    expect(getActiveProject(state).promptHistory).toEqual([]);
+  });
+
+  it('does not roll back prompt history during project undo and redo', () => {
+    let state = primeGenerate(undefined, { positivePrompt: 'history prompt' });
+
+    state = submitGenerate(state);
+    state = workbenchReducer(state, { destination: 'gallery', type: 'setInvocationDestination' });
+    state = workbenchReducer(state, { type: 'undoProjectChange' });
+    state = workbenchReducer(state, { type: 'redoProjectChange' });
+
+    expect(getActiveProject(state).promptHistory).toEqual([{ negativePrompt: null, positivePrompt: 'history prompt' }]);
+  });
+
+  it('hydrates older projects with empty prompt history', () => {
+    const initial = createInitialWorkbenchState();
+    const legacyState = {
+      ...initial,
+      projects: initial.projects.map(({ promptHistory: _promptHistory, ...project }) => project),
+    } as unknown as WorkbenchState;
+
+    const hydrated = workbenchReducer(initial, { state: legacyState, type: 'hydrateWorkbench' });
+
+    expect(getActiveProject(hydrated).promptHistory).toEqual([]);
+  });
+
+  it('routes Gallery destination results to Gallery without staging them on Canvas', () => {
+    let state = primeGenerate();
+
+    state = workbenchReducer(state, { destination: 'gallery', type: 'setInvocationDestination' });
+    state = submitGenerate(state);
+
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('gallery-image.png', queueItem.id)],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+
+    const updatedProject = getActiveProject(state);
+    const galleryValues = getProjectWidgetValues(updatedProject, 'gallery');
+
+    expect(updatedProject.canvas.stagingArea.pendingImages).toEqual([]);
+    expect(galleryValues.recentImages).toEqual([createImage('gallery-image.png', queueItem.id)]);
+    expect(galleryValues.selectedImage).toEqual(createImage('gallery-image.png', queueItem.id));
+    expect(galleryValues.selectedImageName).toBe('gallery-image.png');
+  });
+
+  it('appends Gallery destination results for local fallback while backend owns boards', () => {
+    let state = primeGenerate();
+
+    state = workbenchReducer(state, { destination: 'gallery', type: 'setInvocationDestination' });
+    state = submitGenerate(state);
+
+    const firstQueueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('gallery-image-1.png', firstQueueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: firstQueueItem.id,
+      type: 'routeQueueItemResults',
+    });
+    state = submitGenerate(state);
+
+    const secondQueueItem = getActiveProject(state).queue.items[0];
+
+    state = workbenchReducer(state, {
+      images: [createImage('gallery-image-2.png', secondQueueItem.id)],
+      projectId: getActiveProject(state).id,
+      queueItemId: secondQueueItem.id,
+      type: 'routeQueueItemResults',
+    });
+
+    const values = getProjectWidgetValues(getActiveProject(state), 'gallery');
+
+    expect((values.recentImages as GeneratedImageContract[]).map((image) => image.imageName)).toEqual([
+      'gallery-image-2.png',
+      'gallery-image-1.png',
+    ]);
+    expect(values.imageBoards).toBeUndefined();
+  });
+
+  it('routes partial Gallery destination results without completing the local queue item', () => {
+    let state = primeGenerate(undefined, { batchCount: 2 });
+
+    state = workbenchReducer(state, { destination: 'gallery', type: 'setInvocationDestination' });
+    state = submitGenerate(state);
+
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, {
+      backendItemId: 11,
+      images: [createImage('gallery-image-1.png', queueItem.id)],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemPartialResults',
+    });
+
+    const updatedQueueItem = getActiveProject(state).queue.items[0];
+    const galleryValues = getProjectWidgetValues(getActiveProject(state), 'gallery');
+
+    expect(updatedQueueItem.status).toBe('pending');
+    expect(updatedQueueItem.completedBackendItemIds).toEqual([11]);
+    expect(updatedQueueItem.resultImages).toEqual([createImage('gallery-image-1.png', queueItem.id)]);
+    expect((galleryValues.recentImages as GeneratedImageContract[]).map((image) => image.imageName)).toEqual([
+      'gallery-image-1.png',
+    ]);
+  });
+
+  it('stores selected backend board id for gallery submissions', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, { boardId: 'backend-board-id', type: 'selectGalleryBoard' });
+    state = workbenchReducer(state, { destination: 'gallery', type: 'setInvocationDestination' });
+    state = primeGenerate(state);
+    state = submitGenerate(state);
+
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    expect(queueItem.snapshot.widgetStates.gallery.values.selectedBoardId).toBe('backend-board-id');
+  });
+
+  it('stores full selected gallery image data for Preview widget', () => {
+    let state = createInitialWorkbenchState();
+    const image = createImage('backend-selected.png', 'backend-gallery');
+
+    state = workbenchReducer(state, { image, type: 'selectGalleryImage' });
+
+    expect(getProjectWidgetValues(getActiveProject(state), 'gallery').selectedImageName).toBe('backend-selected.png');
+    expect(getProjectWidgetValues(getActiveProject(state), 'gallery').selectedImage).toEqual(image);
+  });
+});
+
+describe('workbench account and project settings', () => {
+  it('starts with the default layout preset and legacy-matching project settings', () => {
+    const state = createInitialWorkbenchState();
+
+    expect(state.account).toEqual({ activeLayoutPresetId: 'canvas-default' });
+    expect(getActiveProject(state).settings).toEqual(DEFAULT_PROJECT_SETTINGS);
+  });
+
+  it('drops legacy preferences carried inside persisted accounts on hydrate', () => {
+    const initial = createInitialWorkbenchState();
+    const legacy = {
+      ...initial,
+      account: { activeLayoutPresetId: 'gallery', preferences: { themeId: 'forest' } },
+    } as unknown as WorkbenchState;
+
+    const state = workbenchReducer(initial, { state: legacy, type: 'hydrateWorkbench' });
+
+    expect(state.account).toEqual({ activeLayoutPresetId: 'gallery', customLayoutPresets: [] });
+  });
+
+  it('heals hydrated accounts that are missing a layout preset', () => {
+    const initial = createInitialWorkbenchState();
+    const legacy = { ...initial, account: {} } as unknown as WorkbenchState;
+
+    const state = workbenchReducer(initial, { state: legacy, type: 'hydrateWorkbench' });
+
+    expect(state.account.activeLayoutPresetId).toBe('canvas-default');
+  });
+
+  it('updates project settings on the active project only', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, {
+      settings: { antialiasProgressImages: true, preferNumericAttentionStyle: true, useCpuNoise: false },
+      type: 'setActiveProjectSettings',
+    });
+
+    expect(getActiveProject(state).settings).toEqual({
+      antialiasProgressImages: true,
+      preferNumericAttentionStyle: true,
+      showProgressDetails: false,
+      showProgressImagesInViewer: true,
+      showPromptSyntaxHighlighting: false,
+      useCpuNoise: false,
+    });
+  });
+});
+
+describe('workbench backend connection recovery', () => {
+  it('tracks backend connection status', () => {
+    let state = createInitialWorkbenchState();
+
+    state = workbenchReducer(state, {
+      status: 'disconnected',
+      type: 'setBackendConnectionStatus',
+      error: 'server down',
+    });
+
+    expect(state.backendConnection.status).toBe('disconnected');
+    expect(state.backendConnection.error).toBe('server down');
+    expect(state.backendConnection.lastDisconnectedAt).toBeDefined();
+
+    state = workbenchReducer(state, { status: 'connected', type: 'setBackendConnectionStatus' });
+
+    expect(state.backendConnection.status).toBe('connected');
+    expect(state.backendConnection.error).toBeUndefined();
+    expect(state.backendConnection.lastConnectedAt).toBeDefined();
+  });
+
+  it('refreshes every project gallery when backend data may have changed', () => {
+    const initial = createInitialWorkbenchState();
+    const previousTokens = initial.projects.map(
+      (project) => getProjectWidgetValues(project, 'gallery').galleryRefreshToken
+    );
+    const previousImageTokens = initial.projects.map(
+      (project) => getProjectWidgetValues(project, 'gallery').galleryImagesRefreshToken
+    );
+    const state = workbenchReducer(initial, { type: 'refreshBackendData' });
+
+    expect(state.projects).toHaveLength(initial.projects.length);
+
+    for (const [index, project] of state.projects.entries()) {
+      const galleryValues = getProjectWidgetValues(project, 'gallery');
+
+      expect(galleryValues.galleryRefreshToken).toBeDefined();
+      expect(galleryValues.galleryRefreshToken).not.toBe(previousTokens[index]);
+      expect(galleryValues.galleryImagesRefreshToken).toBeDefined();
+      expect(galleryValues.galleryImagesRefreshToken).not.toBe(previousImageTokens[index]);
+    }
+  });
+
+  it('can refresh gallery images without invalidating board data', () => {
+    const initial = createInitialWorkbenchState();
+    const state = workbenchReducer(initial, { type: 'touchGalleryImagesRefresh' });
+    const previousValues = getProjectWidgetValues(getActiveProject(initial), 'gallery');
+    const values = getProjectWidgetValues(getActiveProject(state), 'gallery');
+
+    expect(values.galleryRefreshToken).toBe(previousValues.galleryRefreshToken);
+    expect(values.galleryImagesRefreshToken).toBeDefined();
+    expect(values.galleryImagesRefreshToken).not.toBe(previousValues.galleryImagesRefreshToken);
+  });
+
+  it('can refresh gallery images in a non-active project without touching the active project', () => {
+    let state = createInitialWorkbenchState();
+    const firstProjectId = state.activeProjectId;
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    const secondProjectId = state.activeProjectId;
+    const firstPreviousValues = getProjectWidgetValues(getProject(state, firstProjectId), 'gallery');
+    const secondPreviousValues = getProjectWidgetValues(getProject(state, secondProjectId), 'gallery');
+
+    state = workbenchReducer(state, { projectId: firstProjectId, type: 'touchGalleryImagesRefresh' });
+
+    const firstValues = getProjectWidgetValues(getProject(state, firstProjectId), 'gallery');
+    const secondValues = getProjectWidgetValues(getProject(state, secondProjectId), 'gallery');
+
+    expect(firstValues.galleryImagesRefreshToken).not.toBe(firstPreviousValues.galleryImagesRefreshToken);
+    expect(secondValues.galleryImagesRefreshToken).toBe(secondPreviousValues.galleryImagesRefreshToken);
+  });
+
+  it('can remove gallery images from a non-active project without touching the active project', () => {
+    let state = createInitialWorkbenchState();
+    const firstProjectId = state.activeProjectId;
+    const image = createImage('shared.png', 'backend-gallery');
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    const secondProjectId = state.activeProjectId;
+    state = workbenchReducer(state, {
+      projectId: firstProjectId,
+      type: 'patchWidgetValues',
+      values: { recentImages: [image], selectedImage: image, selectedImageName: image.imageName },
+      widgetId: 'gallery',
+    });
+    state = workbenchReducer(state, {
+      projectId: secondProjectId,
+      type: 'patchWidgetValues',
+      values: { recentImages: [image], selectedImage: image, selectedImageName: image.imageName },
+      widgetId: 'gallery',
+    });
+
+    state = workbenchReducer(state, {
+      imageNames: [image.imageName],
+      projectId: firstProjectId,
+      type: 'removeGalleryImages',
+    });
+
+    expect(getProjectWidgetValues(getProject(state, firstProjectId), 'gallery').recentImages).toEqual([]);
+    expect(getProjectWidgetValues(getProject(state, secondProjectId), 'gallery').recentImages).toEqual([image]);
+  });
+
+  it('does not hydrate stale persisted backend connection state', () => {
+    const initial = createInitialWorkbenchState();
+    const persisted = {
+      ...initial,
+      backendConnection: { lastConnectedAt: '2026-06-10T00:00:00.000Z', status: 'connected' },
+    } as WorkbenchState;
+
+    const state = workbenchReducer(initial, { state: persisted, type: 'hydrateWorkbench' });
+
+    expect(state.backendConnection).toEqual({ status: 'connecting' });
+  });
+
+  it('preserves live backend connection state when persistence hydrates late', () => {
+    const initial = createInitialWorkbenchState();
+    const connected = workbenchReducer(initial, { status: 'connected', type: 'setBackendConnectionStatus' });
+    const persisted = {
+      ...initial,
+      backendConnection: { status: 'connecting' },
+    } as WorkbenchState;
+
+    const state = workbenchReducer(connected, { state: persisted, type: 'hydrateWorkbench' });
+
+    expect(state.backendConnection.status).toBe('connected');
+    expect(state.backendConnection.lastConnectedAt).toBe(connected.backendConnection.lastConnectedAt);
+  });
+
+  it('does not hydrate stale notifications that would toast again after reload', () => {
+    const initial = createInitialWorkbenchState();
+    const persisted = workbenchReducer(initial, {
+      kind: 'success',
+      message: 'Old success toast',
+      title: 'Invocation completed',
+      type: 'recordNotice',
+    });
+
+    const state = workbenchReducer(initial, { state: persisted, type: 'hydrateWorkbench' });
+
+    expect(persisted.notifications).toHaveLength(1);
+    expect(state.notifications).toEqual([]);
+  });
+});
+
+describe('nextLayerName', () => {
+  it('starts at Layer 1 with no existing layers', () => {
+    expect(nextLayerName([])).toBe('Layer 1');
+  });
+
+  it('picks the next free number above a contiguous run', () => {
+    expect(nextLayerName(['Layer 1', 'Layer 2'])).toBe('Layer 3');
+  });
+
+  it('fills the lowest gap so names do not collide after a deletion', () => {
+    // Deleting "Layer 2" from [Layer 1, Layer 2, Layer 3] must not re-mint the
+    // count-derived "Layer 3" (which would collide); the lowest free slot is 2.
+    expect(nextLayerName(['Layer 1', 'Layer 3'])).toBe('Layer 2');
+  });
+
+  it('ignores custom names and non-matching patterns', () => {
+    expect(nextLayerName(['Backdrop', 'Layer 10 copy', 'Layer 1'])).toBe('Layer 2');
+    expect(nextLayerName(['Sketch'])).toBe('Layer 1');
+  });
+});
+
+describe('workbenchReducer canvas v2 layer reducers', () => {
+  it('routes a canvas mutation to its bound project after the active project switches', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('origin-layer')]);
+    const originProjectId = state.activeProjectId;
+
+    state = workbenchReducer(state, { type: 'createProject' });
+    const activeProjectId = state.activeProjectId;
+    state = workbenchReducer(state, {
+      mutation: { id: 'origin-layer', patch: { opacity: 0.25 }, type: 'updateCanvasLayer' },
+      projectId: originProjectId,
+      type: 'applyCanvasProjectMutation',
+    } as WorkbenchAction);
+
+    expect(getProject(state, originProjectId).canvas.document.layers[0]?.opacity).toBe(0.25);
+    expect(getProject(state, activeProjectId).canvas.document.layers[0]?.opacity).not.toBe(0.25);
+  });
+
+  it('seeds a new project canvas with a single empty inpaint mask, selected', () => {
+    const state = createInitialWorkbenchState();
+    const { document } = getActiveProject(state).canvas;
+
+    expect(document.layers).toHaveLength(1);
+    const mask = document.layers[0];
+    expect(mask?.type).toBe('inpaint_mask');
+    // Empty: no bitmap (no strokes) — so it never flips generation-mode detection.
+    expect(mask && 'mask' in mask ? mask.mask.bitmap : 'missing').toBeNull();
+    expect(document.selectedLayerId).toBe(mask?.id);
+  });
+
+  it('adds a layer at the top and selects it, honoring an explicit insert index', () => {
+    let state = withEmptyCanvas(createInitialWorkbenchState());
+
+    state = workbenchReducer(state, { layer: createRasterLayer('a'), type: 'addCanvasLayer' });
+    state = workbenchReducer(state, { layer: createRasterLayer('b'), type: 'addCanvasLayer' });
+
+    expect(getLayerIds(state)).toEqual(['b', 'a']);
+    expect(getCanvas(state).document.selectedLayerId).toBe('b');
+
+    state = workbenchReducer(state, { index: 1, layer: createRasterLayer('c'), type: 'addCanvasLayer' });
+
+    expect(getLayerIds(state)).toEqual(['b', 'c', 'a']);
+    expect(getCanvas(state).document.selectedLayerId).toBe('c');
+  });
+
+  it('removes layers and repairs selection to the nearest remaining layer (below, then above)', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [
+      createRasterLayer('a'),
+      createRasterLayer('b'),
+      createRasterLayer('c'),
+    ]);
+
+    state = workbenchReducer(state, { id: 'b', type: 'setCanvasSelectedLayer' });
+    state = workbenchReducer(state, { ids: ['b'], type: 'removeCanvasLayers' });
+
+    // 'b' sat between 'a' and 'c'; the nearest survivor below it is 'c'.
+    expect(getLayerIds(state)).toEqual(['a', 'c']);
+    expect(getCanvas(state).document.selectedLayerId).toBe('c');
+
+    state = workbenchReducer(state, { id: 'c', type: 'setCanvasSelectedLayer' });
+    state = workbenchReducer(state, { ids: ['c'], type: 'removeCanvasLayers' });
+
+    // Nothing remains below 'c', so selection falls back to 'a' above it.
+    expect(getCanvas(state).document.selectedLayerId).toBe('a');
+
+    state = workbenchReducer(state, { ids: ['a'], type: 'removeCanvasLayers' });
+
+    expect(getLayerIds(state)).toEqual([]);
+    expect(getCanvas(state).document.selectedLayerId).toBeNull();
+  });
+
+  it('sets many layers visibility in one bulk action, preserving unlisted layers by identity', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [
+      createRasterLayer('a'),
+      createRasterLayer('b'),
+      createRasterLayer('c'),
+    ]);
+    const before = getCanvas(state).document.layers;
+
+    // Hide 'a' and 'c' in one dispatch; 'b' is unlisted and must keep its object identity.
+    state = workbenchReducer(state, {
+      type: 'setCanvasLayersEnabled',
+      updates: [
+        { id: 'a', isEnabled: false },
+        { id: 'c', isEnabled: false },
+      ],
+    });
+    const after = getCanvas(state).document.layers;
+
+    expect(after.map((layer) => [layer.id, layer.isEnabled])).toEqual([
+      ['a', false],
+      ['b', true],
+      ['c', false],
+    ]);
+    // 'b' unchanged ⇒ same reference; 'a'/'c' replaced.
+    expect(after[1]).toBe(before[1]);
+    expect(after[0]).not.toBe(before[0]);
+  });
+
+  it('returns the same document when a bulk visibility action changes nothing', () => {
+    const state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a'), createRasterLayer('b')]);
+    const before = getCanvas(state).document;
+
+    const next = workbenchReducer(state, {
+      type: 'setCanvasLayersEnabled',
+      updates: [{ id: 'a', isEnabled: true }],
+    });
+
+    // 'a' is already enabled ⇒ no change ⇒ document identity preserved (no selector churn).
+    expect(getCanvas(next).document).toBe(before);
+  });
+
+  it('applies and reverses a layer stack mutation atomically while preserving unrelated layer identity', () => {
+    const upper = createRasterLayer('upper');
+    const below = createRasterLayer('below');
+    const unrelated = { ...createRasterLayer('unrelated'), isEnabled: false };
+    const result = createRasterLayer('result');
+    const initial = workbenchReducer(withCanvasLayers(createInitialWorkbenchState(), [unrelated, upper, below]), {
+      id: unrelated.id,
+      type: 'setCanvasSelectedLayer',
+    });
+    const unrelatedBefore = getCanvas(initial).document.layers[0];
+
+    const applied = workbenchReducer(initial, {
+      add: { index: 1, layers: [result] },
+      enabledUpdates: [
+        { id: upper.id, isEnabled: false },
+        { id: below.id, isEnabled: false },
+      ],
+      selectedLayerId: result.id,
+      type: 'applyCanvasLayerStackMutation',
+    });
+
+    expect(applied).toBeDefined();
+    expect(getCanvas(applied).document.layers.map((layer) => [layer.id, layer.isEnabled])).toEqual([
+      ['unrelated', false],
+      ['result', true],
+      ['upper', false],
+      ['below', false],
+    ]);
+    expect(getCanvas(applied).document.selectedLayerId).toBe(result.id);
+    expect(getCanvas(applied).document.layers[0]).toBe(unrelatedBefore);
+
+    const reverted = workbenchReducer(applied, {
+      enabledUpdates: [
+        { id: upper.id, isEnabled: true },
+        { id: below.id, isEnabled: true },
+      ],
+      removeIds: [result.id],
+      selectedLayerId: unrelated.id,
+      type: 'applyCanvasLayerStackMutation',
+    });
+
+    expect(getCanvas(reverted).document.layers.map((layer) => [layer.id, layer.isEnabled])).toEqual([
+      ['unrelated', false],
+      ['upper', true],
+      ['below', true],
+    ]);
+    expect(getCanvas(reverted).document.selectedLayerId).toBe(unrelated.id);
+    expect(getCanvas(reverted).document.layers[0]).toBe(unrelatedBefore);
+  });
+
+  it('inserts a batch in order and selects the exact requested layer', () => {
+    const existing = createRasterLayer('existing');
+    const layerA = createRasterLayer('a');
+    const layerB = createRasterLayer('b');
+    const initial = withCanvasLayers(createInitialWorkbenchState(), [existing]);
+
+    const next = workbenchReducer(initial, {
+      add: { index: 0, layers: [layerA, layerB] },
+      enabledUpdates: [],
+      selectedLayerId: layerB.id,
+      type: 'applyCanvasLayerStackMutation',
+    });
+
+    expect(getCanvas(next).document.layers).toEqual([layerA, layerB, existing]);
+    expect(getCanvas(next).document.selectedLayerId).toBe(layerB.id);
+  });
+
+  it('targets a non-active project without changing the active project', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('first-existing')]);
+    const firstProjectId = state.activeProjectId;
+    state = workbenchReducer(state, { type: 'createProject' });
+    const secondProjectId = state.activeProjectId;
+    const secondProjectBefore = getProject(state, secondProjectId);
+    const layerA = createRasterLayer('a');
+    const layerB = createRasterLayer('b');
+
+    const next = workbenchReducer(state, {
+      add: { index: 0, layers: [layerA, layerB] },
+      enabledUpdates: [],
+      projectId: firstProjectId,
+      selectedLayerId: layerB.id,
+      type: 'applyCanvasLayerStackMutation',
+    });
+
+    expect(getProject(next, firstProjectId).canvas.document.layers.slice(0, 2)).toEqual([layerA, layerB]);
+    expect(getProject(next, firstProjectId).canvas.document.selectedLayerId).toBe(layerB.id);
+    expect(getProject(next, secondProjectId)).toBe(secondProjectBefore);
+  });
+
+  it('rejects an invalid layer stack mutation without applying any valid fields', () => {
+    const initial = workbenchReducer(
+      withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a'), createRasterLayer('b')]),
+      { id: 'b', type: 'setCanvasSelectedLayer' }
+    );
+    const invalidActions = [
+      {
+        add: { index: 0, layers: [createRasterLayer('a')] },
+        enabledUpdates: [{ id: 'b', isEnabled: false }],
+        selectedLayerId: 'b',
+        type: 'applyCanvasLayerStackMutation',
+      },
+      {
+        enabledUpdates: [{ id: 'a', isEnabled: false }],
+        removeIds: ['missing'],
+        selectedLayerId: 'b',
+        type: 'applyCanvasLayerStackMutation',
+      },
+      {
+        enabledUpdates: [{ id: 'missing', isEnabled: false }],
+        selectedLayerId: 'b',
+        type: 'applyCanvasLayerStackMutation',
+      },
+      {
+        enabledUpdates: [],
+        selectedLayerId: 'missing',
+        type: 'applyCanvasLayerStackMutation',
+      },
+      {
+        enabledUpdates: [{ id: 'a', isEnabled: false }],
+        removeIds: ['a'],
+        selectedLayerId: 'b',
+        type: 'applyCanvasLayerStackMutation',
+      },
+      {
+        add: { index: 0, layers: [createRasterLayer('c')] },
+        enabledUpdates: [],
+        removeIds: ['a'],
+        selectedLayerId: 'b',
+        type: 'applyCanvasLayerStackMutation',
+      },
+      {
+        add: { index: 0, layers: [createRasterLayer('c'), createRasterLayer('c')] },
+        enabledUpdates: [{ id: 'b', isEnabled: false }],
+        selectedLayerId: 'c',
+        type: 'applyCanvasLayerStackMutation',
+      },
+    ] satisfies CanvasProjectMutation[];
+
+    for (const action of invalidActions) {
+      expect(workbenchReducer(initial, action)).toBe(initial);
+    }
+  });
+
+  it('preserves the layers array for a selection-only layer stack mutation', () => {
+    const initial = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a'), createRasterLayer('b')]);
+    const before = getCanvas(initial).document.layers;
+
+    const next = workbenchReducer(initial, {
+      enabledUpdates: [],
+      selectedLayerId: 'b',
+      type: 'applyCanvasLayerStackMutation',
+    });
+
+    expect(getCanvas(next).document.layers).toBe(before);
+    expect(getCanvas(next).document.selectedLayerId).toBe('b');
+  });
+
+  it('duplicates a layer above its source with a copy name and selects the duplicate', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a'), createRasterLayer('b')]);
+
+    state = workbenchReducer(state, { newId: 'b-copy', sourceId: 'b', type: 'duplicateCanvasLayer' });
+
+    expect(getLayerIds(state)).toEqual(['a', 'b-copy', 'b']);
+    expect(getCanvas(state).document.selectedLayerId).toBe('b-copy');
+
+    const [, duplicate, source] = getCanvas(state).document.layers;
+
+    expect(duplicate?.name).toBe('b copy');
+    expect(duplicate).not.toBe(source);
+    expect(getRasterLayerImageName(duplicate)).toBe(getRasterLayerImageName(source));
+  });
+
+  it('reorders layers only when the id set matches, and preserves layer identity', () => {
+    const state = withCanvasLayers(createInitialWorkbenchState(), [
+      createRasterLayer('a'),
+      createRasterLayer('b'),
+      createRasterLayer('c'),
+    ]);
+    const originalLayerA = getCanvas(state).document.layers.find((layer) => layer.id === 'a');
+
+    const reordered = workbenchReducer(state, { orderedIds: ['c', 'a', 'b'], type: 'reorderCanvasLayers' });
+
+    expect(getLayerIds(reordered)).toEqual(['c', 'a', 'b']);
+    // Untouched layer objects are reused, not cloned.
+    expect(getCanvas(reordered).document.layers.find((layer) => layer.id === 'a')).toBe(originalLayerA);
+
+    const ignoredMissing = workbenchReducer(state, { orderedIds: ['c', 'a'], type: 'reorderCanvasLayers' });
+    const ignoredUnknown = workbenchReducer(state, { orderedIds: ['c', 'a', 'z'], type: 'reorderCanvasLayers' });
+
+    expect(getLayerIds(ignoredMissing)).toEqual(['a', 'b', 'c']);
+    expect(getLayerIds(ignoredUnknown)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('updates base props with a field-wise transform merge and leaves other layers untouched', () => {
+    const state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a'), createRasterLayer('b')]);
+    const originalLayerB = getCanvas(state).document.layers.find((layer) => layer.id === 'b');
+
+    const updated = workbenchReducer(state, {
+      id: 'a',
+      patch: { name: 'Renamed', opacity: 0.5, transform: { x: 12 } },
+      type: 'updateCanvasLayer',
+    });
+
+    const layerA = getCanvas(updated).document.layers.find((layer) => layer.id === 'a');
+
+    expect(layerA?.name).toBe('Renamed');
+    expect(layerA?.opacity).toBe(0.5);
+    expect(layerA?.transform).toEqual({ rotation: 0, scaleX: 1, scaleY: 1, x: 12, y: 0 });
+    expect(getCanvas(updated).document.layers.find((layer) => layer.id === 'b')).toBe(originalLayerB);
+  });
+
+  it('replaces one complete layer contract in place and no-ops when the id is missing', () => {
+    const state = withCanvasLayers(createInitialWorkbenchState(), [
+      createRasterLayer('a'),
+      createRasterLayer('b'),
+      createRasterLayer('c'),
+    ]);
+    const beforeDocument = getCanvas(state).document;
+    const replacement: CanvasControlLayerContract = {
+      adapter: {
+        beginEndStepPct: [0.2, 0.8],
+        controlMode: 'more_control',
+        kind: 'control_lora',
+        model: 'control-model',
+        weight: 0.65,
+      },
+      blendMode: 'multiply',
+      filter: { settings: { radius: 3 }, type: 'canny' },
+      id: 'b',
+      isEnabled: false,
+      isLocked: true,
+      name: 'Complete replacement',
+      opacity: 0.4,
+      source: {
+        bitmap: { contentHash: 'hash', height: 23, imageName: 'replacement.png', width: 17 },
+        offset: { x: -4, y: 9 },
+        type: 'paint',
+      },
+      transform: { rotation: 0.75, scaleX: -2, scaleY: 3, x: 12, y: -8 },
+      type: 'control',
+      withTransparencyEffect: true,
+    };
+
+    const replaced = workbenchReducer(state, {
+      layer: replacement,
+      layerId: 'b',
+      type: 'replaceCanvasLayer',
+    });
+    const afterLayers = getCanvas(replaced).document.layers;
+
+    expect(afterLayers.map((layer) => layer.id)).toEqual(['a', 'b', 'c']);
+    expect(afterLayers[1]).toBe(replacement);
+    expect(afterLayers[1]).toEqual(replacement);
+    expect(afterLayers[0]).toBe(beforeDocument.layers[0]);
+    expect(afterLayers[2]).toBe(beforeDocument.layers[2]);
+
+    const missing = workbenchReducer(replaced, {
+      layer: replacement,
+      layerId: 'missing',
+      type: 'replaceCanvasLayer',
+    });
+    expect(missing).toBe(replaced);
+    expect(getCanvas(missing).document).toBe(getCanvas(replaced).document);
+  });
+
+  it('swaps a raster/control layer source but ignores mask-only layer types', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+    const newSource = { image: { height: 10, imageName: 'swapped.png', width: 10 }, type: 'image' } as const;
+
+    state = workbenchReducer(state, { id: 'a', source: newSource, type: 'updateCanvasLayerSource' });
+
+    expect(getRasterLayerImageName(getCanvas(state).document.layers[0])).toBe('swapped.png');
+  });
+
+  it('applies per-type config patches and ignores mismatched layer types', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createControlLayer('ctrl')]);
+
+    state = workbenchReducer(state, {
+      config: { adapter: { weight: 0.25 }, layerType: 'control', withTransparencyEffect: true },
+      id: 'ctrl',
+      type: 'updateCanvasLayerConfig',
+    });
+
+    const controlLayer = getCanvas(state).document.layers[0];
+
+    expect(controlLayer?.type).toBe('control');
+
+    if (controlLayer?.type === 'control') {
+      expect(controlLayer.adapter.weight).toBe(0.25);
+      expect(controlLayer.adapter.kind).toBe('controlnet');
+      expect(controlLayer.withTransparencyEffect).toBe(true);
+    }
+
+    // A raster-shaped config against a control layer is a no-op.
+    const unchanged = workbenchReducer(state, {
+      config: { isTransparencyLocked: true, layerType: 'raster' },
+      id: 'ctrl',
+      type: 'updateCanvasLayerConfig',
+    });
+
+    expect(getCanvas(unchanged).document.layers[0]).toBe(controlLayer);
+  });
+
+  it('persists filter settings on raster layers', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('raster')]);
+
+    state = workbenchReducer(state, {
+      config: { filter: { settings: { radius: 4 }, type: 'content_shuffle' }, layerType: 'raster' },
+      id: 'raster',
+      type: 'updateCanvasLayerConfig',
+    });
+
+    const raster = getCanvas(state).document.layers[0];
+    expect(raster?.type).toBe('raster');
+    if (raster?.type === 'raster') {
+      expect(raster.filter).toEqual({ settings: { radius: 4 }, type: 'content_shuffle' });
+    }
+  });
+
+  it('applies an inpaint-mask config patch: mask bitmap + offset, fill, noise, denoise-limit', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createInpaintMaskLayer('m')]);
+
+    state = workbenchReducer(state, {
+      config: {
+        denoiseLimit: 0.8,
+        layerType: 'inpaint_mask',
+        mask: { bitmap: { contentHash: 'h', height: 20, imageName: 'mask.png', width: 30 }, offset: { x: 4, y: 5 } },
+        noiseLevel: 0.25,
+      },
+      id: 'm',
+      type: 'updateCanvasLayerConfig',
+    });
+
+    const layer = getCanvas(state).document.layers[0];
+    expect(layer?.type).toBe('inpaint_mask');
+    if (layer?.type === 'inpaint_mask') {
+      // Bitmap + content offset persisted; the fill is preserved (merged, not replaced).
+      expect(layer.mask.bitmap).toMatchObject({ imageName: 'mask.png', width: 30, height: 20 });
+      expect(layer.mask.offset).toEqual({ x: 4, y: 5 });
+      expect(layer.mask.fill).toEqual({ color: '#e07575', style: 'diagonal' });
+      expect(layer.noiseLevel).toBe(0.25);
+      expect(layer.denoiseLimit).toBe(0.8);
+    }
+
+    // A fill-only patch replaces the fill while keeping the bitmap.
+    const recolored = workbenchReducer(state, {
+      config: { layerType: 'inpaint_mask', mask: { fill: { color: '#00ff00', style: 'grid' } } },
+      id: 'm',
+      type: 'updateCanvasLayerConfig',
+    });
+    const after = getCanvas(recolored).document.layers[0];
+    if (after?.type === 'inpaint_mask') {
+      expect(after.mask.fill).toEqual({ color: '#00ff00', style: 'grid' });
+      expect(after.mask.bitmap).toMatchObject({ imageName: 'mask.png' });
+    }
+  });
+
+  it('removes optional config fields when a patch explicitly sets them to undefined', () => {
+    const configuredMask: CanvasInpaintMaskLayerContract = {
+      blendMode: 'normal',
+      denoiseLimit: 0.8,
+      id: 'm',
+      isEnabled: true,
+      isLocked: false,
+      mask: { bitmap: null, fill: { color: '#e07575', style: 'diagonal' } },
+      name: 'm',
+      noiseLevel: 0.25,
+      opacity: 1,
+      transform: { rotation: 0, scaleX: 1, scaleY: 1, x: 0, y: 0 },
+      type: 'inpaint_mask',
+    };
+    let state = withCanvasLayers(createInitialWorkbenchState(), [
+      configuredMask,
+      { ...createControlLayer('ctrl'), filter: { settings: {}, type: 'canny' } },
+    ]);
+
+    state = workbenchReducer(state, {
+      config: { denoiseLimit: undefined, layerType: 'inpaint_mask', noiseLevel: undefined },
+      id: 'm',
+      type: 'updateCanvasLayerConfig',
+    });
+    state = workbenchReducer(state, {
+      config: { filter: undefined, layerType: 'control' },
+      id: 'ctrl',
+      type: 'updateCanvasLayerConfig',
+    });
+
+    const mask = getCanvas(state).document.layers[0];
+    const control = getCanvas(state).document.layers[1];
+
+    expect(mask?.type).toBe('inpaint_mask');
+    if (mask?.type === 'inpaint_mask') {
+      expect(mask.noiseLevel).toBeUndefined();
+      expect(mask.denoiseLimit).toBeUndefined();
+    }
+    expect(control?.type).toBe('control');
+    if (control?.type === 'control') {
+      expect(control.filter).toBeUndefined();
+    }
+  });
+
+  it('converts a layer in place, preserving its id and z-order', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a'), createRasterLayer('b')]);
+    const converted = createControlLayer('ignored-id');
+
+    state = workbenchReducer(state, { id: 'b', layer: converted, targetType: 'control', type: 'convertCanvasLayer' });
+
+    expect(getLayerIds(state)).toEqual(['a', 'b']);
+    expect(getCanvas(state).document.layers[1]?.type).toBe('control');
+    expect(getCanvas(state).document.layers[1]?.id).toBe('b');
+  });
+
+  it('merges a layer down: the layer below becomes a raster with the merged paint source', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [
+      createRasterLayer('top'),
+      createControlLayer('bottom'),
+    ]);
+
+    state = workbenchReducer(state, { id: 'bottom', type: 'setCanvasSelectedLayer' });
+    const mergedSource = { bitmap: { height: 8, imageName: 'merged.png', width: 8 }, type: 'paint' } as const;
+
+    state = workbenchReducer(state, { source: mergedSource, type: 'mergeCanvasLayersDown', upperLayerId: 'top' });
+
+    const layers = getCanvas(state).document.layers;
+
+    expect(getLayerIds(state)).toEqual(['bottom']);
+    expect(layers[0]?.type).toBe('raster');
+    expect(layers[0]?.id).toBe('bottom');
+    expect(layers[0]?.type === 'raster' && layers[0].source).toEqual(mergedSource);
+    expect(getCanvas(state).document.selectedLayerId).toBe('bottom');
+  });
+
+  it('clamps and rounds the bbox, and validates the selected layer id', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+
+    state = workbenchReducer(state, { bbox: { height: -4, width: 12.6, x: 3.2, y: 9.8 }, type: 'setCanvasBbox' });
+
+    expect(getCanvas(state).document.bbox).toEqual({ height: 1, width: 13, x: 3, y: 10 });
+
+    // 'a' was selected on insert; selecting a non-existent id is ignored, not applied.
+    expect(getCanvas(state).document.selectedLayerId).toBe('a');
+    state = workbenchReducer(state, { id: 'missing', type: 'setCanvasSelectedLayer' });
+    expect(getCanvas(state).document.selectedLayerId).toBe('a');
+
+    state = workbenchReducer(state, { id: null, type: 'setCanvasSelectedLayer' });
+    expect(getCanvas(state).document.selectedLayerId).toBeNull();
+  });
+
+  it('resizes the document, translating layer transforms and clamping the bbox in-bounds', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+
+    state = workbenchReducer(state, {
+      height: 256,
+      offsetX: 20,
+      offsetY: 10,
+      type: 'resizeCanvasDocument',
+      width: 300,
+    });
+
+    const document = getCanvas(state).document;
+
+    expect(document.width).toBe(300);
+    expect(document.height).toBe(256);
+    expect(document.layers[0]?.transform.x).toBe(20);
+    expect(document.layers[0]?.transform.y).toBe(10);
+    expect(document.bbox.x + document.bbox.width).toBeLessThanOrEqual(300);
+    expect(document.bbox.y + document.bbox.height).toBeLessThanOrEqual(256);
+  });
+
+  it('replaces the whole document with a deep copy', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+    const replacement = {
+      ...createEmptyCanvasDocumentV2(),
+      layers: [createRasterLayer('fresh')],
+      selectedLayerId: 'fresh',
+    };
+
+    state = workbenchReducer(state, { document: replacement, type: 'replaceCanvasDocument' });
+
+    expect(getLayerIds(state)).toEqual(['fresh']);
+    expect(getCanvas(state).document).not.toBe(replacement);
+    expect(getCanvas(state).document.layers[0]).not.toBe(replacement.layers[0]);
+  });
+
+  it('clears the staging area on replaceCanvasDocument (staged candidates belong to the outgoing document)', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+    const staged: Project['canvas']['stagingArea']['pendingImages'][number] = {
+      height: 64,
+      imageName: 'staged-1',
+      imageUrl: 'url',
+      placement: { height: 64, opacity: 1, width: 64, x: 0, y: 0 },
+      queuedAt: 'now',
+      sourceQueueItemId: 'queue-1',
+      thumbnailUrl: 'thumb',
+      width: 64,
+    };
+    state = {
+      ...state,
+      projects: state.projects.map((project) =>
+        project.id === state.activeProjectId
+          ? {
+              ...project,
+              canvas: {
+                ...project.canvas,
+                stagingArea: {
+                  ...project.canvas.stagingArea,
+                  isVisible: true,
+                  pendingImageIds: ['queue-1'],
+                  pendingImages: [staged],
+                  selectedImageIndex: 0,
+                  sourceQueueItemId: 'queue-1',
+                },
+              },
+            }
+          : project
+      ),
+    };
+
+    state = workbenchReducer(state, { document: createEmptyCanvasDocumentV2(), type: 'replaceCanvasDocument' });
+
+    const { stagingArea } = getCanvas(state);
+    expect(stagingArea.pendingImages).toEqual([]);
+    expect(stagingArea.pendingImageIds).toEqual([]);
+    expect(stagingArea.isVisible).toBe(false);
+    expect(stagingArea.sourceQueueItemId).toBeUndefined();
+  });
+
+  it('repairs a dangling selectedLayerId on replaceCanvasDocument (falls back to the top layer)', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+    const replacement = {
+      ...createEmptyCanvasDocumentV2(),
+      layers: [createRasterLayer('top'), createRasterLayer('bottom')],
+      selectedLayerId: 'ghost', // names no layer in the incoming document
+    };
+
+    state = workbenchReducer(state, { document: replacement, type: 'replaceCanvasDocument' });
+
+    expect(getCanvas(state).document.selectedLayerId).toBe('top');
+  });
+
+  it('nulls a dangling selectedLayerId when the replacement document has no layers', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+    const replacement = { ...createEmptyCanvasDocumentV2(), layers: [], selectedLayerId: 'ghost' };
+
+    state = workbenchReducer(state, { document: replacement, type: 'replaceCanvasDocument' });
+
+    expect(getCanvas(state).document.selectedLayerId).toBeNull();
+  });
+
+  it('preserves a valid selectedLayerId on replaceCanvasDocument', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+    const replacement = {
+      ...createEmptyCanvasDocumentV2(),
+      layers: [createRasterLayer('top'), createRasterLayer('bottom')],
+      selectedLayerId: 'bottom',
+    };
+
+    state = workbenchReducer(state, { document: replacement, type: 'replaceCanvasDocument' });
+
+    expect(getCanvas(state).document.selectedLayerId).toBe('bottom');
+  });
+
+  it('repairs a dangling selectedLayerId on restoreCanvasSnapshot (defensive against a corrupt snapshot)', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a'), createRasterLayer('b')]);
+    state = workbenchReducer(state, { createdAt: 'now', id: 'snap-1', name: 'First', type: 'saveCanvasSnapshot' });
+
+    // Corrupt the stored snapshot so its selectedLayerId names no present layer.
+    const snapshot = getCanvas(state).snapshots.find((entry) => entry.id === 'snap-1');
+    expect(snapshot).toBeDefined();
+    snapshot!.document.selectedLayerId = 'ghost';
+
+    state = workbenchReducer(state, { snapshotId: 'snap-1', type: 'restoreCanvasSnapshot' });
+
+    const restored = getCanvas(state).document;
+    expect(restored.selectedLayerId).not.toBe('ghost');
+    expect(restored.selectedLayerId).toBe(restored.layers[0]?.id);
+  });
+
+  it('normalizes a control adapter when restoring a saved canvas snapshot', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createControlLayer('ctrl')]);
+    state = workbenchReducer(state, { createdAt: 'now', id: 'snap-1', name: 'First', type: 'saveCanvasSnapshot' });
+    const snapshotLayer = getCanvas(state).snapshots[0]!.document.layers[0];
+    if (snapshotLayer?.type !== 'control') {
+      throw new Error('expected a control layer');
+    }
+    snapshotLayer.adapter = {
+      beginEndStepPct: [Number.NaN, 2],
+      controlMode: null,
+      kind: 'z_image_control',
+      model: null,
+      weight: Number.POSITIVE_INFINITY,
+    };
+
+    state = workbenchReducer(state, { snapshotId: 'snap-1', type: 'restoreCanvasSnapshot' });
+
+    const restored = getCanvas(state).document.layers[0];
+    expect(restored?.type === 'control' ? restored.adapter : null).toEqual({
+      beginEndStepPct: [0, 1],
+      controlMode: null,
+      kind: 'z_image_control',
+      model: null,
+      weight: 0.75,
+    });
+  });
+
+  it('saves, restores, and deletes canvas snapshots', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+
+    state = workbenchReducer(state, { createdAt: 'now', id: 'snap-1', name: 'First', type: 'saveCanvasSnapshot' });
+
+    expect(getCanvas(state).snapshots).toHaveLength(1);
+    expect(getCanvas(state).snapshots[0]?.document.layers.map((layer) => layer.id)).toEqual(['a']);
+
+    // Mutate the live document, then restore the snapshot back over it.
+    state = workbenchReducer(state, { layer: createRasterLayer('b'), type: 'addCanvasLayer' });
+    expect(getLayerIds(state)).toEqual(['b', 'a']);
+
+    state = workbenchReducer(state, { snapshotId: 'snap-1', type: 'restoreCanvasSnapshot' });
+    expect(getLayerIds(state)).toEqual(['a']);
+
+    state = workbenchReducer(state, { snapshotId: 'snap-1', type: 'deleteCanvasSnapshot' });
+    expect(getCanvas(state).snapshots).toEqual([]);
+  });
+
+  it('bumps documentRevision on wholesale swaps (restore/replace) but not on ordinary edits', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+    const initialRevision = getCanvas(state).documentRevision;
+
+    // Ordinary incremental edits never bump the revision.
+    state = workbenchReducer(state, { id: 'a', patch: { opacity: 0.3 }, type: 'updateCanvasLayer' });
+    state = workbenchReducer(state, { layer: createRasterLayer('b'), type: 'addCanvasLayer' });
+    state = workbenchReducer(state, { bbox: { height: 32, width: 32, x: 0, y: 0 }, type: 'setCanvasBbox' });
+    state = workbenchReducer(state, { height: 256, type: 'resizeCanvasDocument', width: 256 });
+    expect(getCanvas(state).documentRevision).toBe(initialRevision);
+
+    // replaceCanvasDocument is a wholesale swap: bump.
+    state = workbenchReducer(state, { document: createEmptyCanvasDocumentV2(), type: 'replaceCanvasDocument' });
+    expect(getCanvas(state).documentRevision).toBe(initialRevision + 1);
+
+    // restoreCanvasSnapshot is a wholesale swap: bump — even though the restored
+    // document reuses the saved layer ids at the same dimensions.
+    state = workbenchReducer(state, { createdAt: 'now', id: 'snap-1', name: 'First', type: 'saveCanvasSnapshot' });
+    expect(getCanvas(state).documentRevision).toBe(initialRevision + 1);
+    state = workbenchReducer(state, { snapshotId: 'snap-1', type: 'restoreCanvasSnapshot' });
+    expect(getCanvas(state).documentRevision).toBe(initialRevision + 2);
+
+    // Restoring a nonexistent snapshot is a no-op: no bump.
+    state = workbenchReducer(state, { snapshotId: 'missing', type: 'restoreCanvasSnapshot' });
+    expect(getCanvas(state).documentRevision).toBe(initialRevision + 2);
+  });
+
+  it('never records project undo entries for canvas layer edits', () => {
+    let state = withCanvasLayers(createInitialWorkbenchState(), [createRasterLayer('a')]);
+
+    state = workbenchReducer(state, { id: 'a', patch: { opacity: 0.3 }, type: 'updateCanvasLayer' });
+    state = workbenchReducer(state, { layer: createRasterLayer('b'), type: 'addCanvasLayer' });
+    state = workbenchReducer(state, { ids: ['a'], type: 'removeCanvasLayers' });
+
+    expect(getActiveProject(state).undoRedo.past).toEqual([]);
+  });
+});
+
+describe('workbenchReducer canvas staging auto-switch + canvas submission', () => {
+  const stageResults = (state: WorkbenchState, imageNames: string[]): WorkbenchState => {
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    return workbenchReducer(state, {
+      images: imageNames.map((name) => createImage(name, queueItem.id)),
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemResults',
+    });
+  };
+
+  it("'latest' selects the newest pending candidate as results arrive", () => {
+    let state = submitGenerate(primeGenerate());
+
+    state = workbenchReducer(state, { mode: 'latest', type: 'setCanvasStagingAutoSwitch' });
+    state = stageResults(state, ['first.png', 'second.png']);
+
+    expect(getCanvas(state).stagingArea.autoSwitchMode).toBe('latest');
+    expect(getCanvas(state).stagingArea.selectedImageIndex).toBe(1);
+  });
+
+  it("'progress' selects the active in-progress placeholder", () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 3 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, { mode: 'progress', type: 'setCanvasStagingAutoSwitch' });
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12, 13],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+
+    expect(getCanvas(state).stagingArea.autoSwitchMode).toBe('progress');
+    expect(getCanvas(state).stagingArea.selectedImageIndex).toBe(0);
+  });
+
+  it("'progress' advances selection to the next in-progress placeholder as partials land", () => {
+    let state = submitGenerate(primeGenerate(undefined, { batchCount: 3 }));
+    const project = getActiveProject(state);
+    const queueItem = project.queue.items[0];
+
+    state = workbenchReducer(state, { mode: 'progress', type: 'setCanvasStagingAutoSwitch' });
+    state = workbenchReducer(state, {
+      backendItemIds: [11, 12, 13],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'markQueueItemBackendSubmitted',
+    });
+    state = workbenchReducer(state, {
+      backendItemId: 11,
+      images: [createImage('candidate-1.png', queueItem.id)],
+      projectId: project.id,
+      queueItemId: queueItem.id,
+      type: 'routeQueueItemPartialResults',
+    });
+
+    expect(
+      getCanvasStagingSlots(getCanvas(state), getActiveProject(state).queue.items).map((slot) => slot.kind)
+    ).toEqual(['candidate', 'placeholder', 'placeholder']);
+    expect(getCanvas(state).stagingArea.selectedImageIndex).toBe(1);
+  });
+
+  const createCanvasGenerateSnapshot = () => ({
+    negativePromptNodeId: 'negative_prompt',
+    positivePromptNodeId: 'positive_prompt',
+    seedNodeId: 'seed',
+    values: createGenerateValues({ positivePrompt: 'canvas prompt', seed: 101, shouldRandomizeSeed: false }),
+  });
+
+  const submitCanvasGeneration = (state: WorkbenchState): { queueItemId: string; state: WorkbenchState } => {
+    const graph: GraphContract = {
+      edges: [],
+      id: 'canvas-graph',
+      label: 'Canvas',
+      nodes: [],
+      updatedAt: '2026-06-09T00:00:00.000Z',
+      version: 1,
+    };
+    const next = workbenchReducer(state, {
+      backendSupportsCancellation: true,
+      canvas: structuredClone(getCanvas(state)),
+      destination: 'canvas',
+      generate: createCanvasGenerateSnapshot(),
+      graph,
+      projectId: state.activeProjectId,
+      type: 'submitCanvasInvocationSnapshot',
+    });
+
+    return { queueItemId: getActiveProject(next).queue.items[0]!.id, state: next };
+  };
+
+  it('routes canvas results into staging when the session (documentRevision) still matches', () => {
+    const { queueItemId, state: submitted } = submitCanvasGeneration(createInitialWorkbenchState());
+
+    const state = workbenchReducer(submitted, {
+      images: [createImage('fresh.png', queueItemId)],
+      projectId: getActiveProject(submitted).id,
+      queueItemId,
+      type: 'routeQueueItemResults',
+    });
+
+    expect(getCanvas(state).stagingArea.pendingImageIds).toEqual(['fresh.png']);
+    expect(getCanvas(state).stagingArea.isVisible).toBe(true);
+  });
+
+  it('drops mid-flight canvas results after a new-canvas swap so cleared staging is not resurrected (F2)', () => {
+    const { queueItemId, state: submitted } = submitCanvasGeneration(createInitialWorkbenchState());
+
+    // The user confirms a new canvas while the generation is still in flight: a
+    // wholesale swap that clears staging and bumps documentRevision (new session).
+    const swapped = workbenchReducer(submitted, {
+      document: createEmptyCanvasDocumentV2(),
+      type: 'replaceCanvasDocument',
+    });
+
+    // The stale generation's results arrive against the brand-new empty canvas.
+    const state = workbenchReducer(swapped, {
+      images: [createImage('stale.png', queueItemId)],
+      projectId: getActiveProject(swapped).id,
+      queueItemId,
+      type: 'routeQueueItemResults',
+    });
+
+    const { stagingArea } = getCanvas(state);
+    expect(stagingArea.pendingImages).toEqual([]);
+    expect(stagingArea.pendingImageIds).toEqual([]);
+    expect(stagingArea.isVisible).toBe(false);
+    // The item still completes — only its staged candidates are dropped.
+    expect(getActiveProject(state).queue.items[0]?.status).toBe('completed');
+  });
+
+  it('submitCanvasInvocationSnapshot enqueues a pre-compiled graph bound for the canvas', () => {
+    const graph: GraphContract = {
+      edges: [],
+      id: 'canvas-graph',
+      label: 'Canvas',
+      nodes: [],
+      updatedAt: '2026-06-09T00:00:00.000Z',
+      version: 1,
+    };
+
+    const initial = createInitialWorkbenchState();
+    const state = workbenchReducer(initial, {
+      backendSupportsCancellation: true,
+      canvas: structuredClone(getCanvas(initial)),
+      destination: 'canvas',
+      generate: {
+        negativePromptNodeId: 'negative_prompt',
+        positivePromptNodeId: 'positive_prompt',
+        seedNodeId: 'seed',
+        values: createGenerateValues({
+          negativePrompt: 'avoid blur',
+          positivePrompt: 'inpaint prompt',
+          seed: 42,
+          shouldRandomizeSeed: false,
+        }),
+      },
+      graph,
+      projectId: initial.activeProjectId,
+      type: 'submitCanvasInvocationSnapshot',
+    });
+
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    expect(queueItem?.snapshot.sourceId).toBe('canvas');
+    expect(queueItem?.snapshot.destination).toBe('canvas');
+    expect(queueItem?.snapshot.graph.id).toBe('canvas-graph');
+    expect(queueItem?.snapshot.generate).toMatchObject({
+      negativePromptNodeId: 'negative_prompt',
+      positivePromptNodeId: 'positive_prompt',
+      seedNodeId: 'seed',
+      values: { negativePrompt: 'avoid blur', positivePrompt: 'inpaint prompt', seed: 42, shouldRandomizeSeed: false },
+    });
+    expect(queueItem?.snapshot.widgetStates.generate.values).toMatchObject({
+      negativePrompt: 'avoid blur',
+      positivePrompt: 'inpaint prompt',
+      seed: 42,
+      shouldRandomizeSeed: false,
+    });
+    expect(getActiveProject(state).invocation.sourceId).toBe('canvas');
+  });
+
+  it('queues the frozen canvas supplied by an immutable canvas invocation instead of cloning live state', () => {
+    const graph: GraphContract = {
+      edges: [],
+      id: 'frozen-canvas-graph',
+      label: 'Canvas',
+      nodes: [],
+      updatedAt: '2026-06-09T00:00:00.000Z',
+      version: 1,
+    };
+    const initial = createInitialWorkbenchState();
+    const liveCanvas = getCanvas(initial);
+    const frozenCanvas = structuredClone(liveCanvas);
+    frozenCanvas.document.bbox = { height: 48, width: 32, x: 17, y: 23 };
+
+    const state = workbenchReducer(initial, {
+      backendSupportsCancellation: true,
+      canvas: frozenCanvas,
+      destination: 'canvas',
+      generate: createCanvasGenerateSnapshot(),
+      graph,
+      projectId: initial.activeProjectId,
+      type: 'submitCanvasInvocationSnapshot',
+    });
+
+    expect(getActiveProject(state).queue.items[0]?.snapshot.canvas.document.bbox).toEqual(frozenCanvas.document.bbox);
+    expect(getActiveProject(state).queue.items[0]?.snapshot.canvas.document.bbox).not.toEqual(liveCanvas.document.bbox);
+  });
+
+  it('places generated candidates at the frozen queue bbox after the live bbox changes', () => {
+    const graph: GraphContract = {
+      edges: [],
+      id: 'frozen-placement-graph',
+      label: 'Canvas',
+      nodes: [],
+      updatedAt: '2026-06-09T00:00:00.000Z',
+      version: 1,
+    };
+    let state = createInitialWorkbenchState();
+    const frozenCanvas = structuredClone(getCanvas(state));
+    frozenCanvas.document.bbox = { height: 48, width: 32, x: 17, y: 23 };
+    state = workbenchReducer(state, {
+      backendSupportsCancellation: true,
+      canvas: frozenCanvas,
+      destination: 'canvas',
+      generate: createCanvasGenerateSnapshot(),
+      graph,
+      projectId: state.activeProjectId,
+      type: 'submitCanvasInvocationSnapshot',
+    });
+    const queueItemId = getActiveProject(state).queue.items[0]!.id;
+    state = workbenchReducer(state, {
+      bbox: { height: 64, width: 64, x: 101, y: 202 },
+      type: 'setCanvasBbox',
+    });
+
+    state = workbenchReducer(state, {
+      images: [createImage('frozen-placement.png', queueItemId)],
+      projectId: state.activeProjectId,
+      queueItemId,
+      type: 'routeQueueItemResults',
+    });
+
+    expect(getCanvas(state).stagingArea.pendingImages[0]?.placement).toMatchObject({ x: 17, y: 23 });
+  });
+
+  it('submitCanvasInvocationSnapshot honors a Gallery destination instead of hardcoding canvas', () => {
+    const graph: GraphContract = {
+      edges: [],
+      id: 'canvas-graph',
+      label: 'Canvas',
+      nodes: [],
+      updatedAt: '2026-06-09T00:00:00.000Z',
+      version: 1,
+    };
+
+    const initial = createInitialWorkbenchState();
+    const state = workbenchReducer(initial, {
+      backendSupportsCancellation: true,
+      canvas: structuredClone(getCanvas(initial)),
+      destination: 'gallery',
+      generate: createCanvasGenerateSnapshot(),
+      graph,
+      projectId: initial.activeProjectId,
+      type: 'submitCanvasInvocationSnapshot',
+    });
+
+    const queueItem = getActiveProject(state).queue.items[0];
+
+    // A Canvas source still runs, but the resolved Gallery destination rides
+    // through so `routeQueueItemResults` keeps it out of canvas staging.
+    expect(queueItem?.snapshot.sourceId).toBe('canvas');
+    expect(queueItem?.snapshot.destination).toBe('gallery');
+    expect(getActiveProject(state).invocation.destination).toBe('gallery');
+    expect(getActiveProject(state).canvas.stagingArea.pendingImageIds).toHaveLength(0);
+  });
+
+  it('submitCanvasInvocationSnapshot targets the project it names, not the active one', () => {
+    const graph: GraphContract = {
+      edges: [],
+      id: 'canvas-graph',
+      label: 'Canvas',
+      nodes: [],
+      updatedAt: '2026-06-09T00:00:00.000Z',
+      version: 1,
+    };
+
+    let state = createInitialWorkbenchState();
+    const originatingProjectId = state.activeProjectId;
+    state = workbenchReducer(state, { type: 'createProject' });
+    const otherProjectId = state.activeProjectId;
+
+    expect(otherProjectId).not.toBe(originatingProjectId);
+
+    state = workbenchReducer(state, {
+      backendSupportsCancellation: true,
+      canvas: structuredClone(getProject(state, originatingProjectId).canvas),
+      destination: 'canvas',
+      generate: createCanvasGenerateSnapshot(),
+      graph,
+      projectId: originatingProjectId,
+      type: 'submitCanvasInvocationSnapshot',
+    });
+
+    expect(getProject(state, originatingProjectId).queue.items).toHaveLength(1);
+    expect(getProject(state, originatingProjectId).queue.items[0]?.snapshot.graph.id).toBe('canvas-graph');
+    expect(getProject(state, otherProjectId).queue.items).toHaveLength(0);
+  });
+
+  it('submitCanvasInvocationSnapshot with a stale/unknown projectId is a no-op', () => {
+    const graph: GraphContract = {
+      edges: [],
+      id: 'canvas-graph',
+      label: 'Canvas',
+      nodes: [],
+      updatedAt: '2026-06-09T00:00:00.000Z',
+      version: 1,
+    };
+
+    const initial = createInitialWorkbenchState();
+    const state = workbenchReducer(initial, {
+      backendSupportsCancellation: true,
+      canvas: structuredClone(getCanvas(initial)),
+      destination: 'canvas',
+      generate: createCanvasGenerateSnapshot(),
+      graph,
+      projectId: 'not-a-real-project',
+      type: 'submitCanvasInvocationSnapshot',
+    });
+
+    expect(state).toBe(initial);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchState.ts b/invokeai/frontend/webv2/src/workbench/workbenchState.ts
new file mode 100644
index 00000000000..78f89ff7885
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchState.ts
@@ -0,0 +1,2789 @@
+import type { GallerySettings } from './gallery/settings';
+import type { GenerateWidgetValues } from './generation/types';
+import type { ModelConfig } from './models/types';
+import type {
+  CanvasDocumentContractV2,
+  CanvasPlacementContract,
+  CanvasStateContractV2,
+  CenterViewId,
+  CanvasStagingCandidateContract,
+  DeveloperLogNamespace,
+  GeneratedImageContract,
+  GraphContract,
+  GraphHistorySnapshot,
+  InvocationRoute,
+  InvocationSourceId,
+  LayoutPreset,
+  LayoutPresetId,
+  LayoutPresetSnapshot,
+  Project,
+  ProjectLayoutState,
+  ProjectSettings,
+  ProjectUndoSnapshot,
+  PromptHistoryItem,
+  QueueItem,
+  QueueItemStatus,
+  ResultDestination,
+  WidgetFailure,
+  WidgetId,
+  WidgetInstanceContract,
+  WidgetInstanceId,
+  WidgetRegion,
+  WidgetRegionState,
+  WidgetStateContract,
+  WidgetStateMap,
+  WidgetTypeId,
+  WorkbenchNotification,
+  WorkbenchNotificationKind,
+  WorkbenchState,
+} from './types';
+import type { ProjectGraphState } from './workflows/types';
+
+import { createNewCanvasStateV2, migrateCanvasStateToV2 } from './canvasMigration';
+import { applyCanvasProjectMutation, type CanvasProjectMutation } from './canvasProjectMutations';
+export { nextLayerName } from './canvasProjectMutations';
+import {
+  getCanvasStagingSlotCount,
+  getCanvasStagingSlots,
+  getFirstCanvasPlaceholderSlotIndex,
+} from './canvasStagingView';
+import { getGenerationModelAvailabilityReasons } from './generation/baseGenerationPolicies';
+import { sanitizeBatchCount } from './generation/batch';
+import { compileGenerateGraph, resolveGenerateSeed } from './generation/graph';
+import {
+  addPromptHistoryItem,
+  getPromptHistoryItemFromGenerateSettings,
+  removePromptHistoryItem,
+} from './generation/promptHistory';
+import {
+  cloneGenerateWidgetValues,
+  normalizeGenerateSettings,
+  normalizeGenerateWidgetValues,
+  syncGenerateWidgetValuesWithModels,
+} from './generation/settings';
+import {
+  defaultInvocationRoute,
+  isInvocationRouteValid,
+  isInvocationSourceAvailable,
+  resolveInvocationRoute,
+} from './invocation';
+import { defaultLayoutPreset, getLayoutPreset } from './layoutPresets';
+import { cloneLayoutPresetWidgetRegions, createLayoutPresetSnapshot } from './layoutPresetSnapshots';
+import { normalizeProjectSettings } from './settings/store';
+import { compileProjectGraph } from './workflows/buildGraph';
+import {
+  cloneProjectGraph,
+  createProjectGraph,
+  getProjectGraphUndoLabel,
+  isHighConfidenceGraphEdit,
+  normalizeProjectGraph,
+  projectGraphReducer,
+  type ProjectGraphAction,
+} from './workflows/document';
+import { getInvocationTemplatesSnapshot } from './workflows/templates';
+
+type QueueGenerateSnapshot = NonNullable<QueueItem['snapshot']['generate']>;
+
+type WorkbenchReducerAction =
+  | { type: 'createProject' }
+  | { type: 'openProject'; project: Project }
+  | { type: 'closeProject'; projectId: string }
+  | { type: 'renameProject'; projectId: string; name: string }
+  | { type: 'switchProject'; projectId: string }
+  | { type: 'setCenterView'; centerViewId: CenterViewId }
+  | { type: 'applyPreset'; presetId: LayoutPresetId }
+  | { type: 'addLayoutPreset'; presetId: LayoutPresetId; label: string }
+  | { type: 'renameLayoutPreset'; presetId: LayoutPresetId; label: string }
+  | { type: 'deleteLayoutPreset'; presetId: LayoutPresetId }
+  | { type: 'resetActiveLayout' }
+  | { type: 'recoverShellLayout' }
+  | { type: 'setInvocationSource'; sourceId: InvocationSourceId }
+  | { type: 'setInvocationDestination'; destination: ResultDestination }
+  | { type: 'toggleSourceLock' }
+  | { type: 'toggleDestinationLock' }
+  | {
+      type: 'openRegionWidget';
+      region: WidgetRegion;
+      widgetId: WidgetTypeId;
+      createNew?: boolean;
+      initialValues?: Record<string, unknown>;
+      projectId?: string;
+    }
+  | { type: 'selectRegionWidget'; region: WidgetRegion; widgetId: WidgetInstanceId; projectId?: string }
+  | { type: 'toggleRegionWidget'; region: WidgetRegion; widgetId: WidgetInstanceId; projectId?: string }
+  | {
+      type: 'moveWidgetInstance';
+      instanceId: WidgetInstanceId;
+      fromRegion: WidgetRegion;
+      toRegion: WidgetRegion;
+      toIndex: number;
+    }
+  | {
+      type: 'reorderWidgetInstances';
+      region: WidgetRegion;
+      activeInstanceId?: WidgetInstanceId;
+      instanceIds: WidgetInstanceId[];
+    }
+  | { type: 'setRegionWidgetCollapsed'; region: WidgetRegion; isCollapsed: boolean }
+  | { type: 'setRegionWidgetSize'; region: WidgetRegion; sizePx: number }
+  | { type: 'setGenerateSettings'; values: GenerateWidgetValues; projectId?: string }
+  | { type: 'patchGenerateSettings'; values: Partial<GenerateWidgetValues>; projectId?: string }
+  | { type: 'setGenerateBatchCount'; batchCount: number; projectId?: string }
+  | { type: 'addPromptToHistory'; prompt: PromptHistoryItem; projectId?: string }
+  | { type: 'removePromptFromHistory'; prompt: PromptHistoryItem; projectId?: string }
+  | { type: 'clearPromptHistory'; projectId?: string }
+  | { type: 'patchWidgetValues'; widgetId: WidgetTypeId; values: Record<string, unknown>; projectId?: string }
+  | {
+      type: 'patchWidgetInstanceValues';
+      instanceId: WidgetInstanceId;
+      values: Record<string, unknown>;
+      projectId?: string;
+    }
+  | {
+      type: 'setWidgetInstanceValues';
+      instanceId: WidgetInstanceId;
+      values: Record<string, unknown>;
+      projectId?: string;
+    }
+  | { type: 'applyProjectGraphAction'; action: ProjectGraphAction }
+  | { type: 'replaceProjectGraph'; document: ProjectGraphState; label: string }
+  | { type: 'saveProjectGraphSnapshot' }
+  | { type: 'restoreProjectGraphSnapshot'; snapshotId: string }
+  | { type: 'setProjectGraphLibraryBinding'; libraryWorkflowId: string }
+  | { type: 'submitInvocationSnapshot'; backendSupportsCancellation: boolean; models?: readonly ModelConfig[] }
+  | {
+      type: 'submitResolvedInvocationSnapshot';
+      backendSupportsCancellation: boolean;
+      route: InvocationRoute;
+      models?: readonly ModelConfig[];
+    }
+  | {
+      type: 'markQueueItemBackendSubmitted';
+      projectId: string;
+      queueItemId: string;
+      backendItemIds: number[];
+      backendBatchId?: string;
+    }
+  | {
+      type: 'setQueueItemStatus';
+      projectId: string;
+      queueItemId: string;
+      status: QueueItemStatus;
+      error?: string;
+      notify?: boolean;
+    }
+  | {
+      type: 'routeQueueItemPartialResults';
+      projectId: string;
+      queueItemId: string;
+      backendItemId: number;
+      images: GeneratedImageContract[];
+    }
+  | { type: 'markQueueItemBackendCancelled'; projectId: string; queueItemId: string; backendItemId: number }
+  | { type: 'routeQueueItemResults'; projectId: string; queueItemId: string; images: GeneratedImageContract[] }
+  | { type: 'appendCanvasStagingCandidate'; projectId: string; candidate: CanvasStagingCandidateContract }
+  | { type: 'selectGalleryImage'; image: GeneratedImageContract; projectId?: string }
+  | { type: 'toggleGalleryImageInSelection'; image: GeneratedImageContract; projectId?: string }
+  | { type: 'setGalleryMultiSelection'; imageNames: string[]; primaryImage: GeneratedImageContract; projectId?: string }
+  | { type: 'setGalleryCompareImage'; image: GeneratedImageContract | null; projectId?: string }
+  | { type: 'selectGalleryBoard'; boardId: string; projectId?: string }
+  | { type: 'setGalleryView'; galleryView: 'images' | 'assets'; projectId?: string }
+  | { type: 'setGallerySearchTerm'; searchTerm: string; projectId?: string }
+  | { type: 'updateGallerySettings'; settings: Partial<GallerySettings>; projectId?: string }
+  | { type: 'setGalleryPage'; page: number; projectId?: string }
+  | { type: 'setGalleryPageInfo'; totalImages: number; projectId?: string }
+  | { type: 'touchGalleryRefresh'; projectId?: string }
+  | { type: 'touchGalleryImagesRefresh'; projectId?: string }
+  | { type: 'removeGalleryImages'; imageNames: string[]; projectId?: string }
+  | { type: 'setGalleryProjectBoardId'; boardId: string; projectId?: string }
+  | { type: 'applyCanvasProjectMutation'; projectId: string; mutation: CanvasProjectMutation }
+  | {
+      type: 'submitCanvasInvocationSnapshot';
+      backendSupportsCancellation: boolean;
+      canvas: CanvasStateContractV2;
+      destination: ResultDestination;
+      generate: QueueGenerateSnapshot;
+      graph: GraphContract;
+      projectId: string;
+    }
+  | { type: 'cancelQueueItem'; queueItemId: string; projectId?: string }
+  | { type: 'cancelAllQueueItems'; projectId?: string }
+  | { type: 'cancelAllQueueItemsExceptCurrent'; projectId?: string; currentQueueItemId?: string | null }
+  | { type: 'clearCompletedQueueItems' }
+  | { type: 'undoProjectChange' }
+  | { type: 'redoProjectChange' }
+  | { type: 'hydrateWorkbench'; state: WorkbenchState }
+  | { type: 'reconcileProjectConflict'; projectId: string; serverProject: Project; recoveredProject: Project }
+  | { type: 'autosaveStarted' }
+  | { type: 'autosaveSucceeded'; savedAt: string }
+  | { type: 'autosaveFailed'; error: string }
+  | { type: 'markAllNotificationsRead' }
+  | { type: 'clearNotifications' }
+  | { type: 'recordWidgetFailure'; failure: WidgetFailure }
+  | { type: 'setActiveProjectSettings'; settings: Partial<ProjectSettings> }
+  | {
+      type: 'recordError';
+      message: string;
+      area?: string;
+      context?: Record<string, unknown>;
+      namespace?: DeveloperLogNamespace;
+      projectId?: string;
+    }
+  | { type: 'setBackendConnectionStatus'; status: WorkbenchState['backendConnection']['status']; error?: string }
+  | { type: 'refreshBackendData' }
+  | { type: 'recordNotice'; kind: WorkbenchNotificationKind; title: string; message?: string };
+
+const HISTORY_LIMIT = 40;
+const NOTIFICATION_LIMIT = 100;
+const MIN_PANEL_SIZE_PX = 180;
+const MAX_PANEL_SIZE_PX = 520;
+const MIN_STATUS_PANEL_SIZE_PX = 96;
+const MAX_STATUS_PANEL_SIZE_PX = 420;
+
+const now = (): string => new Date().toISOString();
+
+const createId = (prefix: string): string =>
+  `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const createNotification = ({
+  kind,
+  message,
+  projectId,
+  title,
+}: {
+  kind: WorkbenchNotificationKind;
+  message?: string;
+  projectId?: string;
+  title: string;
+}): WorkbenchNotification => ({
+  createdAt: now(),
+  id: createId('notification'),
+  isRead: false,
+  kind,
+  message,
+  projectId,
+  title,
+});
+
+const addNotification = (state: WorkbenchState, notification: WorkbenchNotification): WorkbenchState => ({
+  ...state,
+  notifications: [notification, ...state.notifications].slice(0, NOTIFICATION_LIMIT),
+});
+
+const areRecordsShallowEqual = (left: Record<string, unknown>, right: Record<string, unknown>): boolean => {
+  if (left === right) {
+    return true;
+  }
+
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]))
+  );
+};
+
+const areProjectSettingValuesEqual = (
+  left: ProjectSettings[keyof ProjectSettings],
+  right: ProjectSettings[keyof ProjectSettings]
+): boolean => {
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+  }
+
+  return Object.is(left, right);
+};
+
+const patchRecord = <RecordValue extends Record<string, unknown>>(
+  current: RecordValue,
+  patch: Partial<RecordValue>
+): RecordValue => {
+  let didChange = false;
+
+  for (const [key, value] of Object.entries(patch)) {
+    if (!Object.prototype.hasOwnProperty.call(current, key) || !Object.is(current[key], value)) {
+      didChange = true;
+      break;
+    }
+  }
+
+  return didChange ? ({ ...current, ...patch } as RecordValue) : current;
+};
+
+const cloneRecord = <RecordValue extends Record<string, unknown>>(record: RecordValue): RecordValue =>
+  structuredClone(record) as RecordValue;
+
+const cloneGraph = (graph: GraphContract): GraphContract => ({
+  ...graph,
+  backendGraph: graph.backendGraph
+    ? {
+        ...graph.backendGraph,
+        edges: graph.backendGraph.edges.map((edge) => ({
+          destination: { ...edge.destination },
+          source: { ...edge.source },
+        })),
+        nodes: Object.fromEntries(Object.entries(graph.backendGraph.nodes).map(([id, node]) => [id, { ...node }])),
+      }
+    : undefined,
+  edges: graph.edges.map((edge) => ({ ...edge })),
+  nodes: graph.nodes.map((node) => ({ ...node, inputs: { ...node.inputs } })),
+});
+
+const cloneQueueGenerateSnapshot = (generate: QueueGenerateSnapshot): QueueGenerateSnapshot => ({
+  negativePromptNodeId: generate.negativePromptNodeId,
+  positivePromptNodeId: generate.positivePromptNodeId,
+  seedNodeId: generate.seedNodeId,
+  values: cloneGenerateWidgetValues(generate.values),
+});
+
+const applyQueueGenerateSnapshotToWidgetStates = (
+  widgetStates: WidgetStateMap,
+  generate: QueueGenerateSnapshot | undefined
+): WidgetStateMap => {
+  if (!generate) {
+    return widgetStates;
+  }
+
+  const generateState = widgetStates.generate ?? { id: 'generate', label: 'Generate', values: {}, version: 1 as const };
+
+  return {
+    ...widgetStates,
+    generate: {
+      ...generateState,
+      values: cloneGenerateWidgetValues(generate.values),
+    },
+  };
+};
+
+const clonePlacement = (placement: CanvasPlacementContract): CanvasPlacementContract => ({ ...placement });
+
+const createCenteredPlacement = (
+  image: Pick<GeneratedImageContract, 'height' | 'width'>,
+  document: Pick<CanvasDocumentContractV2, 'height' | 'width'>
+): CanvasPlacementContract => {
+  const imageWidth = image.width > 0 ? image.width : document.width;
+  const imageHeight = image.height > 0 ? image.height : document.height;
+  const scale = Math.min(document.width / imageWidth, document.height / imageHeight);
+  const width = Math.round(imageWidth * scale);
+  const height = Math.round(imageHeight * scale);
+
+  return {
+    height,
+    opacity: 1,
+    width,
+    x: Math.round((document.width - width) / 2),
+    y: Math.round((document.height - height) / 2),
+  };
+};
+
+const normalizeStagingCandidate = (
+  image: CanvasStagingCandidateContract | GeneratedImageContract,
+  document: Pick<CanvasDocumentContractV2, 'height' | 'width'>,
+  sourceBackendItemId?: number
+): CanvasStagingCandidateContract => ({
+  ...image,
+  ...('sourceBackendItemId' in image && image.sourceBackendItemId !== undefined
+    ? { sourceBackendItemId: image.sourceBackendItemId }
+    : sourceBackendItemId === undefined
+      ? {}
+      : { sourceBackendItemId }),
+  placement:
+    'placement' in image && image.placement
+      ? clonePlacement(image.placement)
+      : createCenteredPlacement(image, document),
+});
+
+const clampStagedImageIndex = (imageIndex: number, pendingImageCount: number): number => {
+  const maxIndex = Math.max(0, pendingImageCount - 1);
+
+  return Math.min(maxIndex, Math.max(0, imageIndex));
+};
+
+const getCanvasStagingSlotCountWithPendingImages = (
+  project: Project,
+  pendingImages: CanvasStagingCandidateContract[]
+): number =>
+  getCanvasStagingSlotCount(
+    {
+      ...project.canvas,
+      stagingArea: {
+        ...project.canvas.stagingArea,
+        pendingImages,
+      },
+    },
+    project.queue.items
+  );
+
+const getCanvasWithPendingImages = (
+  canvas: CanvasStateContractV2,
+  pendingImages: CanvasStagingCandidateContract[]
+): CanvasStateContractV2 => ({
+  ...canvas,
+  stagingArea: {
+    ...canvas.stagingArea,
+    pendingImages,
+  },
+});
+
+const getCanvasStagingCandidateSlotIndex = (
+  project: Project,
+  pendingImages: CanvasStagingCandidateContract[],
+  target: CanvasStagingCandidateContract | undefined
+): number => {
+  if (!target) {
+    return -1;
+  }
+
+  return getCanvasStagingSlots(
+    getCanvasWithPendingImages(project.canvas, pendingImages),
+    project.queue.items
+  ).findIndex(
+    (slot) =>
+      slot.kind === 'candidate' &&
+      slot.candidate.sourceQueueItemId === target.sourceQueueItemId &&
+      slot.candidate.imageName === target.imageName
+  );
+};
+
+const resolveStagingSelectionIndexForSlots = ({
+  incomingImages,
+  pendingImages,
+  project,
+  slotCount,
+}: {
+  incomingImages: CanvasStagingCandidateContract[];
+  pendingImages: CanvasStagingCandidateContract[];
+  project: Project;
+  slotCount: number;
+}): number => {
+  if (project.canvas.stagingArea.autoSwitchMode === 'progress') {
+    const placeholderIndex = getFirstCanvasPlaceholderSlotIndex(
+      getCanvasWithPendingImages(project.canvas, pendingImages),
+      project.queue.items
+    );
+
+    if (placeholderIndex !== -1) {
+      return placeholderIndex;
+    }
+
+    const firstIncomingSlotIndex = getCanvasStagingCandidateSlotIndex(project, pendingImages, incomingImages[0]);
+
+    return firstIncomingSlotIndex !== -1
+      ? firstIncomingSlotIndex
+      : clampStagedImageIndex(project.canvas.stagingArea.selectedImageIndex, slotCount);
+  }
+
+  if (incomingImages.length === 0) {
+    return clampStagedImageIndex(project.canvas.stagingArea.selectedImageIndex, slotCount);
+  }
+
+  const selectedImage =
+    project.canvas.stagingArea.autoSwitchMode === 'latest'
+      ? (pendingImages[pendingImages.length - 1] ?? incomingImages[incomingImages.length - 1])
+      : incomingImages[0];
+  const selectedSlotIndex = getCanvasStagingCandidateSlotIndex(project, pendingImages, selectedImage);
+
+  return selectedSlotIndex === -1
+    ? clampStagedImageIndex(project.canvas.stagingArea.selectedImageIndex, slotCount)
+    : selectedSlotIndex;
+};
+
+const stageCanvasResultImages = (
+  project: Project,
+  queueItemId: string,
+  images: GeneratedImageContract[],
+  sourceBackendItemIds?: readonly (number | undefined)[]
+): Project => {
+  const queueItem = project.queue.items.find((item) => item.id === queueItemId);
+
+  if (
+    images.length === 0 ||
+    !queueItem ||
+    queueItem.snapshot.canvas.documentRevision !== project.canvas.documentRevision
+  ) {
+    return project;
+  }
+
+  const queueDocument = queueItem.snapshot.canvas.document;
+  const { bbox } = queueDocument;
+  const incomingImages = images.map((image, index) =>
+    normalizeStagingCandidate(
+      {
+        ...image,
+        placement: { height: image.height, opacity: 1, width: image.width, x: bbox.x, y: bbox.y },
+      },
+      queueDocument,
+      sourceBackendItemIds?.[index]
+    )
+  );
+  const existingImages = project.canvas.stagingArea.pendingImages;
+  const existingImageKeys = new Set(existingImages.map((image) => `${image.sourceQueueItemId}:${image.imageName}`));
+  const newImages = incomingImages.filter(
+    (image) => !existingImageKeys.has(`${image.sourceQueueItemId}:${image.imageName}`)
+  );
+  const pendingImages = [...existingImages, ...newImages];
+  const slotCount = getCanvasStagingSlotCountWithPendingImages(project, pendingImages);
+
+  return {
+    ...project,
+    canvas: {
+      ...project.canvas,
+      stagingArea: {
+        ...project.canvas.stagingArea,
+        areThumbnailsVisible: true,
+        isVisible: slotCount > 0,
+        pendingImageIds: pendingImages.map((image) => image.imageName),
+        pendingImages,
+        selectedImageIndex: resolveStagingSelectionIndexForSlots({
+          incomingImages: newImages,
+          pendingImages,
+          project,
+          slotCount,
+        }),
+        sourceQueueItemId: queueItemId,
+      },
+    },
+  };
+};
+
+const appendCanvasStagingCandidate = (project: Project, candidate: CanvasStagingCandidateContract): Project => {
+  const appendedCandidate = normalizeStagingCandidate(candidate, project.canvas.document);
+  const pendingImages = [...project.canvas.stagingArea.pendingImages, appendedCandidate];
+  const candidateKey = `${appendedCandidate.sourceQueueItemId}:${appendedCandidate.imageName}`;
+  const slots = getCanvasStagingSlots(getCanvasWithPendingImages(project.canvas, pendingImages), project.queue.items);
+  const selectedImageIndex = slots
+    .map((slot) => (slot.kind === 'candidate' ? `${slot.candidate.sourceQueueItemId}:${slot.candidate.imageName}` : ''))
+    .lastIndexOf(candidateKey);
+
+  return {
+    ...project,
+    canvas: {
+      ...project.canvas,
+      stagingArea: {
+        ...project.canvas.stagingArea,
+        areThumbnailsVisible: true,
+        isVisible: true,
+        pendingImageIds: pendingImages.map((image) => image.imageName),
+        pendingImages,
+        selectedImageIndex,
+        sourceQueueItemId: appendedCandidate.sourceQueueItemId,
+      },
+    },
+  };
+};
+
+const clampCanvasStagingSelection = (project: Project): Project => {
+  const slotCount = getCanvasStagingSlotCount(project.canvas, project.queue.items);
+  const placeholderIndex =
+    project.canvas.stagingArea.autoSwitchMode === 'progress'
+      ? getFirstCanvasPlaceholderSlotIndex(project.canvas, project.queue.items)
+      : -1;
+  const selectedImageIndex =
+    placeholderIndex === -1
+      ? clampStagedImageIndex(project.canvas.stagingArea.selectedImageIndex, slotCount)
+      : placeholderIndex;
+  const isVisible = slotCount > 0 ? project.canvas.stagingArea.isVisible : false;
+
+  if (
+    selectedImageIndex === project.canvas.stagingArea.selectedImageIndex &&
+    isVisible === project.canvas.stagingArea.isVisible
+  ) {
+    return project;
+  }
+
+  return {
+    ...project,
+    canvas: {
+      ...project.canvas,
+      stagingArea: {
+        ...project.canvas.stagingArea,
+        isVisible,
+        selectedImageIndex,
+      },
+    },
+  };
+};
+
+const getGalleryImages = (values: Record<string, unknown>): GeneratedImageContract[] =>
+  Array.isArray(values.recentImages) ? (values.recentImages as GeneratedImageContract[]) : [];
+
+const getGallerySelectedImageNames = (values: Record<string, unknown>): string[] => {
+  if (Array.isArray(values.selectedImageNames)) {
+    return (values.selectedImageNames as unknown[]).filter((name): name is string => typeof name === 'string');
+  }
+
+  return typeof values.selectedImageName === 'string' ? [values.selectedImageName] : [];
+};
+
+/**
+ * Deep-clones an already-v2 canvas state and normalizes staging candidate placements. Not a
+ * migration boundary: callers with genuinely unknown/legacy input must run
+ * `migrateCanvasStateToV2` first (see `ensureProjectWidgetContracts`).
+ */
+const cloneCanvas = (canvas: CanvasStateContractV2): CanvasStateContractV2 => {
+  const document = structuredClone(canvas.document);
+
+  return {
+    version: 2,
+    document,
+    documentRevision: canvas.documentRevision,
+    snapshots: canvas.snapshots.map((snapshot) => ({ ...snapshot, document: structuredClone(snapshot.document) })),
+    stagingArea: {
+      ...canvas.stagingArea,
+      pendingImageIds: [...(canvas.stagingArea?.pendingImageIds ?? [])],
+      pendingImages: (canvas.stagingArea?.pendingImages ?? []).map((image) =>
+        normalizeStagingCandidate(image, document)
+      ),
+      areThumbnailsVisible: canvas.stagingArea?.areThumbnailsVisible ?? true,
+      autoSwitchMode: canvas.stagingArea?.autoSwitchMode ?? 'off',
+      isVisible: canvas.stagingArea?.isVisible ?? (canvas.stagingArea?.pendingImages?.length ?? 0) > 0,
+      selectedImageIndex: canvas.stagingArea?.selectedImageIndex ?? 0,
+    },
+  };
+};
+
+const cloneWidgetState = (widgetState: WidgetStateContract): WidgetStateContract => ({
+  ...widgetState,
+  values: { ...widgetState.values },
+});
+
+const cloneWidgetInstance = (widgetInstance: WidgetInstanceContract): WidgetInstanceContract => ({
+  ...widgetInstance,
+  state: cloneWidgetState(widgetInstance.state),
+});
+
+const cloneWidgetInstances = (
+  widgetInstances: Record<WidgetInstanceId, WidgetInstanceContract>
+): Record<WidgetInstanceId, WidgetInstanceContract> =>
+  Object.fromEntries(
+    Object.entries({ ...createWidgetInstances(), ...widgetInstances }).map(([instanceId, widgetInstance]) => [
+      instanceId,
+      cloneWidgetInstance(widgetInstance),
+    ])
+  );
+
+const getWidgetStatesSnapshot = (widgetInstances: Record<WidgetInstanceId, WidgetInstanceContract>): WidgetStateMap => {
+  const widgetStates: WidgetStateMap = {};
+
+  for (const widgetInstance of Object.values(widgetInstances)) {
+    widgetStates[widgetInstance.typeId] ??= cloneWidgetState(widgetInstance.state);
+  }
+
+  return widgetStates;
+};
+
+const getWidgetState = (project: Project, widgetId: WidgetTypeId): WidgetStateContract => {
+  const widgetInstance =
+    project.widgetInstances[widgetId] ??
+    Object.values(project.widgetInstances).find((instance) => instance.typeId === widgetId);
+
+  return widgetInstance?.state ?? createWidgetState(widgetId);
+};
+
+const getWidgetValues = (project: Project, widgetId: WidgetTypeId): Record<string, unknown> =>
+  getWidgetState(project, widgetId).values;
+
+const updateProjectWidgetState = (
+  project: Project,
+  widgetId: WidgetTypeId,
+  getState: (state: WidgetStateContract) => WidgetStateContract
+): Project => {
+  const instance =
+    project.widgetInstances[widgetId] ??
+    Object.values(project.widgetInstances).find((candidate) => candidate.typeId === widgetId);
+  const instanceId = instance?.id ?? widgetId;
+  const currentInstance = instance ?? createWidgetInstance(widgetId, instanceId);
+  const nextState = getState(currentInstance.state);
+
+  if (nextState === currentInstance.state) {
+    return project;
+  }
+
+  return {
+    ...project,
+    widgetInstances: {
+      ...project.widgetInstances,
+      [instanceId]: {
+        ...currentInstance,
+        state: nextState,
+      },
+    },
+  };
+};
+
+const updateProjectWidgetValues = (
+  project: Project,
+  widgetId: WidgetTypeId,
+  getValues: (values: Record<string, unknown>) => Record<string, unknown>
+): Project =>
+  updateProjectWidgetState(project, widgetId, (widgetState) => {
+    const values = getValues(widgetState.values);
+
+    return values === widgetState.values ? widgetState : { ...widgetState, values };
+  });
+
+const updateProjectWidgetInstanceValues = (
+  project: Project,
+  instanceId: WidgetInstanceId,
+  getValues: (values: Record<string, unknown>) => Record<string, unknown>
+): Project => {
+  const instance = project.widgetInstances[instanceId];
+
+  if (!instance) {
+    return project;
+  }
+
+  const values = getValues(instance.state.values);
+
+  if (values === instance.state.values) {
+    return project;
+  }
+
+  return {
+    ...project,
+    widgetInstances: {
+      ...project.widgetInstances,
+      [instanceId]: {
+        ...instance,
+        state: { ...instance.state, values },
+      },
+    },
+  };
+};
+
+const cloneWidgetRegions = (
+  widgetRegions: Record<WidgetRegion, WidgetRegionState>
+): Record<WidgetRegion, WidgetRegionState> => ({
+  center: {
+    ...widgetRegions.center,
+    instanceIds: [...widgetRegions.center.instanceIds],
+  },
+  left: {
+    ...widgetRegions.left,
+    instanceIds: [...widgetRegions.left.instanceIds],
+  },
+  right: {
+    ...widgetRegions.right,
+    instanceIds: [...widgetRegions.right.instanceIds],
+  },
+  bottom: {
+    ...widgetRegions.bottom,
+    instanceIds: [...widgetRegions.bottom.instanceIds],
+  },
+});
+
+const cloneWidgetGraphs = (widgetGraphs: Project['widgetGraphs']): Project['widgetGraphs'] =>
+  Object.fromEntries(Object.entries(widgetGraphs).map(([key, graph]) => [key, graph ? cloneGraph(graph) : graph]));
+
+// Canvas is intentionally absent from undo snapshots: the canvas rendering
+// engine owns its own pixel-patch history, so project-level undo/redo neither
+// snapshots nor restores canvas — `restoreUndoSnapshot` passes the live
+// `project.canvas` straight through via the `...project` spread.
+const createUndoSnapshot = (project: Project): ProjectUndoSnapshot => ({
+  invocation: { ...project.invocation },
+  layout: { ...project.layout, panels: { ...project.layout.panels } },
+  projectGraph: cloneProjectGraph(project.projectGraph),
+  widgetGraphs: cloneWidgetGraphs(project.widgetGraphs),
+  widgetInstances: cloneWidgetInstances(project.widgetInstances),
+  widgetRegions: cloneWidgetRegions(project.widgetRegions),
+});
+
+const restoreUndoSnapshot = (project: Project, snapshot: ProjectUndoSnapshot): Project => ({
+  ...project,
+  invocation: { ...snapshot.invocation },
+  layout: { ...snapshot.layout, panels: { ...snapshot.layout.panels } },
+  projectGraph: cloneProjectGraph(normalizeProjectGraph(snapshot.projectGraph)),
+  widgetGraphs: cloneWidgetGraphs(snapshot.widgetGraphs),
+  widgetInstances: cloneWidgetInstances(snapshot.widgetInstances),
+  widgetRegions: cloneWidgetRegions(snapshot.widgetRegions),
+});
+
+const createGraphHistorySnapshot = (label: string, graph: GraphContract): GraphHistorySnapshot => ({
+  createdAt: now(),
+  graph: cloneGraph(graph),
+  id: createId('graph-history'),
+  label,
+});
+
+/** A restorable history entry carrying the editable workflow document. */
+const createDocumentHistorySnapshot = (label: string, document: ProjectGraphState): GraphHistorySnapshot => ({
+  createdAt: now(),
+  document: cloneProjectGraph(document),
+  id: createId('graph-history'),
+  label,
+});
+
+const pushUndo = (project: Project, label: string): Project => ({
+  ...project,
+  undoRedo: {
+    future: [],
+    past: [
+      ...project.undoRedo.past,
+      {
+        createdAt: now(),
+        id: createId('undo'),
+        label,
+        project: createUndoSnapshot(project),
+      },
+    ].slice(-HISTORY_LIMIT),
+  },
+});
+
+const createWidgetStates = (): WidgetStateMap => ({
+  'autosave-status': { id: 'autosave-status', label: 'Autosave', values: {}, version: 1 },
+  canvas: { id: 'canvas', label: 'Canvas', values: {}, version: 1 },
+  diagnostics: { id: 'diagnostics', label: 'Diagnostics', values: {}, version: 1 },
+  gallery: { id: 'gallery', label: 'Gallery', values: {}, version: 1 },
+  generate: { graphId: 'generate-graph', id: 'generate', label: 'Generate', values: {}, version: 1 },
+  layers: { id: 'layers', label: 'Layers', values: {}, version: 1 },
+  notifications: { id: 'notifications', label: 'Notifications', values: {}, version: 1 },
+  preview: { id: 'preview', label: 'Preview', values: {}, version: 1 },
+  project: { id: 'project', label: 'Project', values: {}, version: 1 },
+  queue: { id: 'queue', label: 'Queue', values: {}, version: 1 },
+  'server-status': { id: 'server-status', label: 'Server Status', values: {}, version: 1 },
+  users: { id: 'users', label: 'Users', values: {}, version: 1 },
+  'version-status': { id: 'version-status', label: 'Version', values: {}, version: 1 },
+  workflow: { graphId: 'workflow-graph', id: 'workflow', label: 'Workflow', values: {}, version: 1 },
+});
+
+const createWidgetState = (widgetId: WidgetTypeId): WidgetStateContract =>
+  cloneWidgetState(
+    createWidgetStates()[widgetId] ?? {
+      id: widgetId,
+      label: widgetId,
+      values: {},
+      version: 1,
+    }
+  );
+
+const createWidgetInstance = (
+  widgetId: WidgetTypeId,
+  instanceId: WidgetInstanceId = widgetId,
+  values?: Record<string, unknown>
+): WidgetInstanceContract => ({
+  createdAt: now(),
+  id: instanceId,
+  state: values ? { ...createWidgetState(widgetId), values } : createWidgetState(widgetId),
+  typeId: widgetId,
+});
+
+const defaultWidgetInstanceTypes: Record<WidgetInstanceId, WidgetTypeId> = {
+  'autosave-status': 'autosave-status',
+  canvas: 'canvas',
+  diagnostics: 'diagnostics',
+  'diagnostics:bottom': 'diagnostics',
+  gallery: 'gallery',
+  'gallery:bottom': 'gallery',
+  'gallery:center': 'gallery',
+  generate: 'generate',
+  layers: 'layers',
+  notifications: 'notifications',
+  preview: 'preview',
+  project: 'project',
+  queue: 'queue',
+  'server-status': 'server-status',
+  'version-status': 'version-status',
+  workflow: 'workflow',
+  'workflow:bottom': 'workflow',
+  'workflow:center': 'workflow',
+};
+
+const createWidgetInstances = (): Record<WidgetInstanceId, WidgetInstanceContract> =>
+  Object.fromEntries(
+    Object.entries(defaultWidgetInstanceTypes).map(([instanceId, widgetId]) => [
+      instanceId,
+      createWidgetInstance(widgetId, instanceId),
+    ])
+  );
+
+const createWidgetRegions = (): Record<WidgetRegion, WidgetRegionState> => ({
+  ...cloneLayoutPresetWidgetRegions(defaultLayoutPreset.snapshot.widgetRegions),
+});
+
+const LEGACY_RIGHT_REGION_WIDGET_IDS: WidgetId[] = ['queue', 'gallery', 'layers'];
+
+const isLegacyDefaultRightRegion = (region: WidgetRegionState): boolean =>
+  region.instanceIds.length === LEGACY_RIGHT_REGION_WIDGET_IDS.length &&
+  region.instanceIds.every((widgetId, index) => widgetId === LEGACY_RIGHT_REGION_WIDGET_IDS[index]);
+
+const ensureRightRegion = (rightRegion: WidgetRegionState | undefined): WidgetRegionState => {
+  const defaultRightRegion = createWidgetRegions().right;
+
+  if (!rightRegion) {
+    return defaultRightRegion;
+  }
+
+  if (isLegacyDefaultRightRegion(rightRegion)) {
+    return { ...rightRegion, instanceIds: defaultRightRegion.instanceIds };
+  }
+
+  return rightRegion;
+};
+
+const getCenterWidgetIdFromViewId = (centerViewId: CenterViewId): WidgetInstanceId => {
+  if (centerViewId === 'gallery') {
+    return 'gallery:center';
+  }
+
+  if (centerViewId === 'workflow') {
+    return 'workflow:center';
+  }
+
+  return centerViewId;
+};
+
+const ensureCenterRegion = (
+  centerRegion: WidgetRegionState | undefined,
+  fallbackCenterViewId: CenterViewId
+): WidgetRegionState => {
+  const defaultCenterRegion = createWidgetRegions().center;
+  const activeInstanceId = centerRegion?.activeInstanceId ?? getCenterWidgetIdFromViewId(fallbackCenterViewId);
+  const instanceIds = centerRegion?.instanceIds.length ? centerRegion.instanceIds : defaultCenterRegion.instanceIds;
+  const normalizedActiveInstanceId = instanceIds.includes(activeInstanceId) ? activeInstanceId : instanceIds[0];
+
+  return {
+    ...defaultCenterRegion,
+    ...centerRegion,
+    activeInstanceId: normalizedActiveInstanceId,
+    instanceIds,
+    isCollapsed: false,
+  };
+};
+
+const normalizePromptHistory = (value: unknown): PromptHistoryItem[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.reduceRight<PromptHistoryItem[]>((history, item) => {
+    if (!item || typeof item !== 'object') {
+      return history;
+    }
+
+    const record = item as Record<string, unknown>;
+
+    if (typeof record.positivePrompt !== 'string') {
+      return history;
+    }
+
+    return addPromptHistoryItem(history, {
+      negativePrompt: typeof record.negativePrompt === 'string' ? record.negativePrompt : null,
+      positivePrompt: record.positivePrompt,
+    });
+  }, []);
+};
+
+const ensureProjectWidgetContracts = (project: Project): Project => {
+  const defaultWidgetRegions = createWidgetRegions();
+  const legacyWidgetRegions = project.widgetRegions as
+    | Partial<Record<WidgetRegion | 'left-panel' | 'right-panel' | 'status-bar', WidgetRegionState>>
+    | undefined;
+  const widgetInstances = project.widgetInstances ?? createWidgetInstances();
+
+  return {
+    ...project,
+    // `project` may come straight from persisted storage (an unsafe cast boundary), so its
+    // canvas can still be v1-shaped, malformed, or missing — migrate before cloning.
+    canvas: cloneCanvas(migrateCanvasStateToV2(project.canvas)),
+    projectGraph: normalizeProjectGraph(project.projectGraph),
+    promptHistory: normalizePromptHistory((project as Partial<Project>).promptHistory),
+    settings: normalizeProjectSettings(project.settings),
+    widgetRegions: {
+      left: legacyWidgetRegions?.left ?? legacyWidgetRegions?.['left-panel'] ?? defaultWidgetRegions.left,
+      right: ensureRightRegion(legacyWidgetRegions?.right ?? legacyWidgetRegions?.['right-panel']),
+      bottom: legacyWidgetRegions?.bottom ?? legacyWidgetRegions?.['status-bar'] ?? defaultWidgetRegions.bottom,
+      center: ensureCenterRegion(legacyWidgetRegions?.center, project.layout.centerViewId),
+    },
+    widgetInstances: cloneWidgetInstances(widgetInstances),
+  };
+};
+
+const clampPanelSize = (region: WidgetRegion, sizePx: number): number => {
+  if (region === 'bottom') {
+    return Math.min(MAX_STATUS_PANEL_SIZE_PX, Math.max(MIN_STATUS_PANEL_SIZE_PX, sizePx));
+  }
+
+  return Math.min(MAX_PANEL_SIZE_PX, Math.max(MIN_PANEL_SIZE_PX, sizePx));
+};
+
+const createCanvasState = (): CanvasStateContractV2 => createNewCanvasStateV2();
+
+const createProject = (index: number, id = `project-${index}`): Project => ({
+  canvas: createCanvasState(),
+  events: [
+    {
+      createdAt: now(),
+      id: createId('event'),
+      summary: `Created Project Name #${index}`,
+      type: 'project-created',
+    },
+  ],
+  graphHistory: [],
+  id,
+  invocation: { ...defaultInvocationRoute },
+  layout: { ...defaultLayoutPreset.snapshot.layout, panels: { ...defaultLayoutPreset.snapshot.layout.panels } },
+  name: `Project Name #${index}`,
+  promptHistory: [],
+  projectGraph: createProjectGraph(`${id}-graph`),
+  queue: { items: [] },
+  settings: normalizeProjectSettings(),
+  undoRedo: { future: [], past: [] },
+  widgetGraphs: {},
+  widgetInstances: createWidgetInstances(),
+  widgetRegions: createWidgetRegions(),
+});
+
+const getNextProjectIndex = (projects: Project[]): number => {
+  const usedIndices = projects.map((project) => Number(project.name.match(/#(\d+)$/)?.[1] ?? 0));
+
+  return Math.max(0, ...usedIndices) + 1;
+};
+
+/**
+ * A fresh, never-saved project. Ids carry entropy rather than an index so a
+ * draft can never collide with a project that already exists on the server
+ * (which an autosave would then silently overwrite).
+ */
+export const createDraftProject = (projects: Project[]): Project =>
+  createProject(getNextProjectIndex(projects), createId('project'));
+
+const updateActiveProject = (state: WorkbenchState, getProject: (project: Project) => Project): WorkbenchState => {
+  let didChange = false;
+  const projects = state.projects.map((project) => {
+    if (project.id !== state.activeProjectId) {
+      return project;
+    }
+
+    const nextProject = getProject(project);
+
+    if (nextProject !== project) {
+      didChange = true;
+    }
+
+    return nextProject;
+  });
+
+  return didChange ? { ...state, projects } : state;
+};
+
+const getNextInstanceId = (region: WidgetRegionState, instanceId: WidgetInstanceId): WidgetInstanceId | null => {
+  if (region.activeInstanceId !== instanceId) {
+    return region.activeInstanceId;
+  }
+
+  return region.instanceIds.find((enabledInstanceId) => enabledInstanceId !== instanceId) ?? null;
+};
+
+const insertAt = <Value>(values: Value[], value: Value, index: number): Value[] => {
+  const nextValues = values.filter((candidate) => candidate !== value);
+  const nextIndex = Math.min(nextValues.length, Math.max(0, index));
+
+  nextValues.splice(nextIndex, 0, value);
+
+  return nextValues;
+};
+
+const updateActiveWidgetRegion = (
+  state: WorkbenchState,
+  region: WidgetRegion,
+  getRegion: (regionState: WidgetRegionState) => WidgetRegionState
+): WorkbenchState => updateActiveProject(state, (project) => updateProjectWidgetRegion(project, region, getRegion));
+
+const updateProjectWidgetRegion = (
+  project: Project,
+  region: WidgetRegion,
+  getRegion: (regionState: WidgetRegionState) => WidgetRegionState
+): Project => {
+  const regionState = project.widgetRegions[region];
+  const nextRegionState = getRegion(regionState);
+
+  return nextRegionState === regionState
+    ? project
+    : {
+        ...project,
+        widgetRegions: {
+          ...project.widgetRegions,
+          [region]: nextRegionState,
+        },
+      };
+};
+
+const openPanelForRegion = (layout: ProjectLayoutState, region: WidgetRegion): ProjectLayoutState => ({
+  ...layout,
+  panels: {
+    ...layout.panels,
+    isBottomOpen: region === 'bottom' ? true : layout.panels.isBottomOpen,
+    isLeftOpen: region === 'left' ? true : layout.panels.isLeftOpen,
+    isRightOpen: region === 'right' ? true : layout.panels.isRightOpen,
+  },
+});
+
+const cloneLayoutPresetSnapshot = (snapshot: LayoutPresetSnapshot): LayoutPresetSnapshot => ({
+  layout: { ...snapshot.layout, panels: { ...snapshot.layout.panels } },
+  widgetInstances: Object.fromEntries(
+    Object.entries(snapshot.widgetInstances).map(([instanceId, instance]) => [instanceId, { ...instance }])
+  ),
+  widgetRegions: cloneLayoutPresetWidgetRegions(snapshot.widgetRegions),
+});
+
+const isWidgetRegionState = (value: unknown): value is WidgetRegionState => {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const record = value as Partial<WidgetRegionState>;
+
+  return (
+    typeof record.activeInstanceId === 'string' &&
+    Array.isArray(record.instanceIds) &&
+    record.instanceIds.every((instanceId) => typeof instanceId === 'string') &&
+    typeof record.isCollapsed === 'boolean' &&
+    typeof record.sizePx === 'number'
+  );
+};
+
+const isLayoutPresetSnapshot = (value: unknown): value is LayoutPresetSnapshot => {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const snapshot = value as Partial<LayoutPresetSnapshot>;
+  const layout = snapshot.layout as Partial<ProjectLayoutState> | undefined;
+
+  return (
+    !!layout &&
+    typeof layout.presetId === 'string' &&
+    typeof layout.centerViewId === 'string' &&
+    !!layout.panels &&
+    typeof layout.panels.isBottomOpen === 'boolean' &&
+    typeof layout.panels.isLeftOpen === 'boolean' &&
+    typeof layout.panels.isRightOpen === 'boolean' &&
+    !!snapshot.widgetInstances &&
+    typeof snapshot.widgetInstances === 'object' &&
+    !!snapshot.widgetRegions &&
+    isWidgetRegionState(snapshot.widgetRegions.left) &&
+    isWidgetRegionState(snapshot.widgetRegions.right) &&
+    isWidgetRegionState(snapshot.widgetRegions.bottom) &&
+    isWidgetRegionState(snapshot.widgetRegions.center)
+  );
+};
+
+const normalizeCustomLayoutPresets = (presets: unknown): LayoutPreset[] => {
+  if (!Array.isArray(presets)) {
+    return [];
+  }
+
+  return presets.flatMap((preset): LayoutPreset[] => {
+    if (!preset || typeof preset !== 'object') {
+      return [];
+    }
+
+    const record = preset as Partial<LayoutPreset>;
+
+    if (typeof record.id !== 'string' || typeof record.label !== 'string' || !isLayoutPresetSnapshot(record.snapshot)) {
+      return [];
+    }
+
+    return [
+      {
+        id: record.id,
+        label: record.label,
+        snapshot: cloneLayoutPresetSnapshot(record.snapshot),
+      },
+    ];
+  });
+};
+
+const normalizeAccount = (account: Partial<WorkbenchState['account']> | undefined): WorkbenchState['account'] => ({
+  activeLayoutPresetId: account?.activeLayoutPresetId ?? defaultLayoutPreset.id,
+  customLayoutPresets: normalizeCustomLayoutPresets(account?.customLayoutPresets),
+});
+
+const normalizeWorkbenchState = (state: WorkbenchState): WorkbenchState => ({
+  ...state,
+  backendConnection: { status: 'connecting' },
+  // Built explicitly: legacy snapshots carried preferences inside the account
+  // (they live in the settings store now) and must not resurface here.
+  account: normalizeAccount(state.account),
+  notifications: [],
+  projects: state.projects.map(ensureProjectWidgetContracts),
+});
+
+const updateActiveLayout = (
+  state: WorkbenchState,
+  getLayout: (layout: ProjectLayoutState) => ProjectLayoutState
+): WorkbenchState =>
+  updateActiveProject(state, (project) => {
+    const nextProject = pushUndo(project, 'Update layout');
+
+    return {
+      ...nextProject,
+      events: [
+        {
+          createdAt: now(),
+          id: createId('event'),
+          summary: 'Updated active layout',
+          type: 'layout-updated',
+        },
+        ...nextProject.events,
+      ],
+      layout: getLayout(project.layout),
+    };
+  });
+
+const getAvailableLayoutPreset = (state: WorkbenchState, presetId: LayoutPresetId): LayoutPreset =>
+  state.account.customLayoutPresets?.find((preset) => preset.id === presetId) ?? getLayoutPreset(presetId);
+
+const applyLayoutPresetToProject = (project: Project, preset: LayoutPreset): Project => {
+  const snapshot = preset.snapshot;
+  const widgetInstances = { ...project.widgetInstances };
+
+  for (const instance of Object.values(snapshot.widgetInstances)) {
+    widgetInstances[instance.id] = widgetInstances[instance.id]
+      ? { ...widgetInstances[instance.id], title: instance.title }
+      : createWidgetInstance(instance.typeId, instance.id);
+  }
+
+  return {
+    ...project,
+    layout: {
+      ...snapshot.layout,
+      panels: { ...snapshot.layout.panels },
+      presetId: preset.id,
+    },
+    widgetInstances,
+    widgetRegions: cloneLayoutPresetWidgetRegions(snapshot.widgetRegions),
+  };
+};
+
+const updateActiveProjectLayoutPreset = (state: WorkbenchState, preset: LayoutPreset): WorkbenchState =>
+  updateActiveProject(state, (project) => {
+    const nextProject = pushUndo(project, 'Update layout');
+
+    return {
+      ...applyLayoutPresetToProject(nextProject, preset),
+      events: [
+        {
+          createdAt: now(),
+          id: createId('event'),
+          summary: 'Updated active layout',
+          type: 'layout-updated',
+        },
+        ...nextProject.events,
+      ],
+    };
+  });
+
+const updateActiveInvocation = (
+  state: WorkbenchState,
+  getInvocation: (invocation: InvocationRoute) => InvocationRoute
+): WorkbenchState =>
+  updateActiveProject(state, (project) => {
+    const nextProject = pushUndo(project, 'Update invocation route');
+
+    return {
+      ...nextProject,
+      events: [
+        {
+          createdAt: now(),
+          id: createId('event'),
+          summary: 'Updated invocation source or destination',
+          type: 'invocation-updated',
+        },
+        ...nextProject.events,
+      ],
+      invocation: getInvocation(project.invocation),
+    };
+  });
+
+const compileInvocationSnapshot = (
+  project: Project,
+  route: InvocationRoute,
+  models?: readonly ModelConfig[]
+): { graph: GraphContract; widgetStates: WidgetStateMap } | null => {
+  const widgetStates = getWidgetStatesSnapshot(project.widgetInstances);
+
+  if (route.sourceId === 'workflow') {
+    // Compiles the workflow document into an immutable snapshot. Templates are
+    // read imperatively; route validation already guaranteed they are loaded.
+    const templatesSnapshot = getInvocationTemplatesSnapshot();
+
+    if (templatesSnapshot.status !== 'loaded') {
+      return null;
+    }
+
+    return { graph: compileProjectGraph(project.projectGraph, templatesSnapshot.templates), widgetStates };
+  }
+
+  if (route.sourceId !== 'generate') {
+    const widgetGraph = project.widgetGraphs[route.sourceId as WidgetTypeId];
+
+    return widgetGraph ? { graph: cloneGraph(widgetGraph), widgetStates } : null;
+  }
+
+  const values = normalizeGenerateWidgetValues(getWidgetValues(project, 'generate'));
+
+  if (!values) {
+    return null;
+  }
+
+  const currentValues = models ? syncGenerateWidgetValuesWithModels(values, models) : values;
+  const availabilityReasons = models
+    ? getGenerationModelAvailabilityReasons(currentValues.model, currentValues, models)
+    : [];
+
+  if (availabilityReasons.length > 0) {
+    return null;
+  }
+
+  const resolvedSettings: GenerateWidgetValues = {
+    ...currentValues,
+    seed: resolveGenerateSeed(currentValues),
+  };
+  const compiledGraph = compileGenerateGraph(
+    resolvedSettings,
+    resolvedSettings.model,
+    route.destination,
+    project.settings
+  ).graph;
+
+  widgetStates.generate = {
+    ...widgetStates.generate,
+    graphId: compiledGraph.id,
+    values: cloneGenerateWidgetValues(resolvedSettings),
+  };
+
+  return { graph: compiledGraph, widgetStates };
+};
+
+const updateProjectById = (
+  state: WorkbenchState,
+  projectId: string,
+  getProject: (project: Project) => Project
+): WorkbenchState => {
+  let didChange = false;
+  const projects = state.projects.map((project) => {
+    if (project.id !== projectId) {
+      return project;
+    }
+
+    const nextProject = getProject(project);
+
+    if (nextProject !== project) {
+      didChange = true;
+    }
+
+    return nextProject;
+  });
+
+  return didChange ? { ...state, projects } : state;
+};
+
+const updateGalleryValues = (
+  state: WorkbenchState,
+  getValues: (values: Record<string, unknown>) => Record<string, unknown>,
+  projectId = state.activeProjectId
+): WorkbenchState => {
+  const targetProject = state.projects.find((project) => project.id === projectId);
+  const values = targetProject ? getWidgetValues(targetProject, 'gallery') : null;
+
+  if (!targetProject || !values) {
+    return state;
+  }
+
+  const nextValues = getValues(values);
+
+  if (nextValues === values) {
+    return state;
+  }
+
+  return updateProjectById(state, projectId, (project) =>
+    updateProjectWidgetValues(project, 'gallery', () => nextValues)
+  );
+};
+
+const refreshProjectBackendData = (project: Project): Project => ({
+  ...updateProjectWidgetValues(project, 'gallery', (values) => ({
+    ...values,
+    galleryImagesRefreshToken: createId('gallery-images-refresh'),
+    galleryRefreshToken: createId('gallery-refresh'),
+  })),
+});
+
+const updateQueueItem = (project: Project, queueItemId: string, getItem: (item: QueueItem) => QueueItem): Project => {
+  let didChange = false;
+  const items = project.queue.items.map((item) => {
+    if (item.id !== queueItemId) {
+      return item;
+    }
+
+    const nextItem = getItem(item);
+
+    if (nextItem !== item) {
+      didChange = true;
+    }
+
+    return nextItem;
+  });
+
+  return didChange ? { ...project, queue: { items } } : project;
+};
+
+const isCancellableQueueItem = (item: QueueItem): boolean =>
+  item.cancellable && (item.status === 'pending' || item.status === 'running');
+
+const isClearableQueueItem = (item: QueueItem): boolean => item.status === 'completed' || item.status === 'failed';
+
+const shouldApplyQueueBulkActionToProject = (project: Project, projectId?: string): boolean =>
+  projectId === undefined || project.id === projectId;
+
+const mergeImageResults = (
+  existingImages: GeneratedImageContract[] | undefined,
+  incomingImages: GeneratedImageContract[]
+): GeneratedImageContract[] => {
+  const existing = existingImages ?? [];
+  const existingNames = new Set(existing.map((image) => image.imageName));
+
+  return [...existing, ...incomingImages.filter((image) => !existingNames.has(image.imageName))];
+};
+
+const mergeBackendItemId = (ids: number[] | undefined, backendItemId: number): number[] =>
+  ids?.includes(backendItemId) ? ids : [...(ids ?? []), backendItemId];
+
+const getQueueItemStatusAfterBackendCancellation = (
+  item: QueueItem,
+  cancelledBackendItemIds: number[]
+): QueueItemStatus => {
+  if (!item.backendItemIds?.length) {
+    return item.status;
+  }
+
+  const completedBackendItemIds = new Set(item.completedBackendItemIds ?? []);
+  const terminalBackendItemIds = new Set([...completedBackendItemIds, ...cancelledBackendItemIds]);
+  const isEveryBackendItemTerminal = item.backendItemIds.every((backendItemId) =>
+    terminalBackendItemIds.has(backendItemId)
+  );
+
+  if (!isEveryBackendItemTerminal) {
+    return item.status;
+  }
+
+  return completedBackendItemIds.size > 0 || (item.resultImages?.length ?? 0) > 0 ? 'completed' : 'cancelled';
+};
+
+const updateGalleryWithResultImages = (project: Project, images: GeneratedImageContract[]): Project => {
+  if (images.length === 0) {
+    return project;
+  }
+
+  const galleryValues = getWidgetValues(project, 'gallery');
+  const existingImages = getGalleryImages(galleryValues).filter(
+    (image) => !images.some((incomingImage) => incomingImage.imageName === image.imageName)
+  );
+
+  return updateProjectWidgetValues(project, 'gallery', () => ({
+    ...galleryValues,
+    recentImages: [...images, ...existingImages],
+    selectedImage: images[0] ?? galleryValues.selectedImage,
+    selectedImageName: images[0]?.imageName ?? galleryValues.selectedImageName,
+    selectedImageNames: images[0] ? [images[0].imageName] : getGallerySelectedImageNames(galleryValues),
+  }));
+};
+
+const routeQueueItemPartialResults = (
+  project: Project,
+  queueItemId: string,
+  backendItemId: number,
+  images: GeneratedImageContract[]
+): Project => {
+  const queueItem = project.queue.items.find((item) => item.id === queueItemId);
+  const destination = queueItem?.snapshot.destination ?? project.invocation.destination;
+  const nextProject = updateQueueItem(project, queueItemId, (item) => ({
+    ...item,
+    completedBackendItemIds: item.completedBackendItemIds?.includes(backendItemId)
+      ? item.completedBackendItemIds
+      : [...(item.completedBackendItemIds ?? []), backendItemId],
+    resultImages: mergeImageResults(item.resultImages, images),
+  }));
+
+  if (destination === 'gallery') {
+    return updateGalleryWithResultImages(nextProject, images);
+  }
+
+  return clampCanvasStagingSelection(
+    stageCanvasResultImages(
+      nextProject,
+      queueItemId,
+      images,
+      images.map(() => backendItemId)
+    )
+  );
+};
+
+const routeQueueItemResults = (project: Project, queueItemId: string, images: GeneratedImageContract[]): Project => {
+  const queueItem = project.queue.items.find((item) => item.id === queueItemId);
+  const destination = queueItem?.snapshot.destination ?? project.invocation.destination;
+  const nextProject = updateQueueItem(project, queueItemId, (item) => ({
+    ...item,
+    completedBackendItemIds: item.backendItemIds
+      ? item.backendItemIds.filter((backendItemId) => !item.cancelledBackendItemIds?.includes(backendItemId))
+      : item.completedBackendItemIds,
+    resultImages: images,
+    status: 'completed',
+  }));
+
+  if (destination === 'gallery') {
+    return updateGalleryWithResultImages(nextProject, images);
+  }
+
+  // A canvas generation belongs to the canvas SESSION it was submitted against,
+  // identified by `documentRevision` (bumped only on wholesale swaps — new canvas,
+  // snapshot restore, project sync — never on ordinary edits, and captured in the
+  // queue item's canvas snapshot at submit time). If a fresh session started while
+  // this generation was in flight, its results belong to a document that no longer
+  // exists; routing them would resurrect staging on the brand-new canvas (F2). Keep
+  // the completed status, but drop the staged candidates.
+  if (queueItem && queueItem.snapshot.canvas.documentRevision !== nextProject.canvas.documentRevision) {
+    return nextProject;
+  }
+
+  const sourceBackendItemIds = queueItem?.backendItemIds?.filter(
+    (backendItemId) => !queueItem.cancelledBackendItemIds?.includes(backendItemId)
+  );
+
+  return stageCanvasResultImages(nextProject, queueItemId, images, sourceBackendItemIds);
+};
+
+/**
+ * Enqueues an already-compiled graph snapshot. Shared by the route-validated
+ * `submitInvocationSnapshot` and the canvas engine's `submitCanvasInvocationSnapshot`,
+ * whose graph is compiled asynchronously outside the reducer.
+ */
+const enqueueCompiledSnapshot = (
+  project: Project,
+  route: InvocationRoute,
+  compiled: { generate?: QueueGenerateSnapshot; graph: GraphContract; widgetStates: WidgetStateMap },
+  backendSupportsCancellation: boolean,
+  canvasSnapshot?: CanvasStateContractV2
+): Project => {
+  const submittedAt = now();
+  const queueItemId = createId('queue-item');
+  const { generate, graph } = compiled;
+  const widgetStates = applyQueueGenerateSnapshotToWidgetStates(compiled.widgetStates, generate);
+  const graphHistorySnapshot = createGraphHistorySnapshot(`Queue snapshot ${queueItemId}`, graph);
+  const generateSettings =
+    route.sourceId === 'generate' ? normalizeGenerateSettings(widgetStates.generate.values) : null;
+  const queueItem: QueueItem = {
+    cancellable: backendSupportsCancellation,
+    id: queueItemId,
+    snapshot: {
+      canvas: canvasSnapshot ? structuredClone(canvasSnapshot) : cloneCanvas(project.canvas),
+      destination: route.destination,
+      ...(generate ? { generate: cloneQueueGenerateSnapshot(generate) } : {}),
+      graph,
+      sourceId: route.sourceId,
+      submittedAt,
+      widgetInstances: cloneWidgetInstances(project.widgetInstances),
+      widgetStates,
+    },
+    status: 'pending',
+  };
+
+  return {
+    ...project,
+    events: [
+      {
+        createdAt: submittedAt,
+        id: createId('event'),
+        runId: queueItemId,
+        summary: `Submitted immutable ${route.sourceId} graph snapshot to ${route.destination}`,
+        type: 'queue-submitted',
+      },
+      ...project.events,
+    ],
+    graphHistory: [graphHistorySnapshot, ...project.graphHistory].slice(0, HISTORY_LIMIT),
+    promptHistory: generateSettings
+      ? addPromptHistoryItem(project.promptHistory, getPromptHistoryItemFromGenerateSettings(generateSettings))
+      : project.promptHistory,
+    invocation: {
+      ...project.invocation,
+      destination: route.destination,
+      lastSubmittedRunId: queueItemId,
+      sourceId: route.sourceId,
+    },
+    queue: { items: [queueItem, ...project.queue.items] },
+    widgetGraphs:
+      route.sourceId === 'generate' ? { ...project.widgetGraphs, generate: cloneGraph(graph) } : project.widgetGraphs,
+  };
+};
+
+const submitInvocationSnapshot = (
+  project: Project,
+  backendSupportsCancellation: boolean,
+  route = resolveInvocationRoute(project),
+  models?: readonly ModelConfig[]
+): Project => {
+  if (!isInvocationRouteValid(route)) {
+    return project;
+  }
+
+  const compiledSnapshot = compileInvocationSnapshot(project, route, models);
+
+  if (!compiledSnapshot) {
+    return project;
+  }
+
+  return enqueueCompiledSnapshot(project, route, compiledSnapshot, backendSupportsCancellation);
+};
+
+export const createInitialWorkbenchState = (): WorkbenchState => {
+  const draft = createDraftProject([]);
+
+  return {
+    account: { activeLayoutPresetId: defaultLayoutPreset.id },
+    activeProjectId: draft.id,
+    autosave: { status: 'idle' },
+    backendConnection: { status: 'connecting' },
+    notifications: [],
+    projects: [draft],
+    widgetFailures: [],
+  };
+};
+
+export const workbenchReducer = (state: WorkbenchState, action: WorkbenchReducerAction): WorkbenchState => {
+  switch (action.type) {
+    case 'createProject': {
+      const project = createDraftProject(state.projects);
+
+      return { ...state, activeProjectId: project.id, projects: [...state.projects, project] };
+    }
+    case 'openProject': {
+      // Hydrated from the library (Open dialog or a deep link). Opening an
+      // already-open project just focuses its tab.
+      if (state.projects.some((project) => project.id === action.project.id)) {
+        return { ...state, activeProjectId: action.project.id };
+      }
+
+      const project = ensureProjectWidgetContracts(action.project);
+
+      return { ...state, activeProjectId: project.id, projects: [...state.projects, project] };
+    }
+    case 'renameProject': {
+      const name = action.name.trim();
+
+      if (!name) {
+        return state;
+      }
+
+      return {
+        ...state,
+        projects: state.projects.map((project) => (project.id === action.projectId ? { ...project, name } : project)),
+      };
+    }
+    case 'closeProject': {
+      if (state.projects.length === 1) {
+        const message = 'At least one project must remain open.';
+
+        return addNotification(state, createNotification({ kind: 'error', message, title: 'Project close blocked' }));
+      }
+
+      const projectIndex = state.projects.findIndex((project) => project.id === action.projectId);
+      const projects = state.projects.filter((project) => project.id !== action.projectId);
+
+      if (action.projectId !== state.activeProjectId) {
+        return { ...state, projects };
+      }
+
+      const fallbackProject = projects[Math.max(0, projectIndex - 1)];
+
+      return { ...state, activeProjectId: fallbackProject.id, projects };
+    }
+    case 'switchProject': {
+      return { ...state, activeProjectId: action.projectId };
+    }
+    case 'setCenterView': {
+      const widgetId = getCenterWidgetIdFromViewId(action.centerViewId);
+
+      return updateActiveWidgetRegion(state, 'center', (region) => ({
+        ...region,
+        activeInstanceId: region.instanceIds.includes(widgetId) ? widgetId : region.activeInstanceId,
+        isCollapsed: false,
+      }));
+    }
+    case 'applyPreset': {
+      const preset = getAvailableLayoutPreset(state, action.presetId);
+      const nextState = updateActiveProjectLayoutPreset(state, preset);
+
+      return {
+        ...nextState,
+        account: { ...state.account, activeLayoutPresetId: preset.id },
+      };
+    }
+    case 'addLayoutPreset': {
+      const activeProject = state.projects.find((project) => project.id === state.activeProjectId);
+
+      if (!activeProject) {
+        return state;
+      }
+
+      const preset: LayoutPreset = {
+        id: action.presetId,
+        label: action.label.trim() || 'Custom layout',
+        snapshot: createLayoutPresetSnapshot(ensureProjectWidgetContracts(activeProject)),
+      };
+      const customLayoutPresets = [
+        ...(state.account.customLayoutPresets ?? []).filter((candidate) => candidate.id !== action.presetId),
+        preset,
+      ];
+
+      return {
+        ...state,
+        account: { ...state.account, activeLayoutPresetId: preset.id, customLayoutPresets },
+      };
+    }
+    case 'renameLayoutPreset': {
+      const label = action.label.trim();
+
+      if (!label) {
+        return state;
+      }
+
+      return {
+        ...state,
+        account: {
+          ...state.account,
+          customLayoutPresets: (state.account.customLayoutPresets ?? []).map((preset) =>
+            preset.id === action.presetId ? { ...preset, label } : preset
+          ),
+        },
+      };
+    }
+    case 'deleteLayoutPreset': {
+      const customLayoutPresets = (state.account.customLayoutPresets ?? []).filter(
+        (preset) => preset.id !== action.presetId
+      );
+
+      return {
+        ...state,
+        account: {
+          ...state.account,
+          activeLayoutPresetId:
+            state.account.activeLayoutPresetId === action.presetId
+              ? defaultLayoutPreset.id
+              : state.account.activeLayoutPresetId,
+          customLayoutPresets,
+        },
+      };
+    }
+    case 'resetActiveLayout': {
+      const preset = getAvailableLayoutPreset(
+        state,
+        state.projects.find((project) => project.id === state.activeProjectId)?.layout.presetId ??
+          state.account.activeLayoutPresetId
+      );
+
+      return updateActiveProjectLayoutPreset(state, preset);
+    }
+    case 'recoverShellLayout': {
+      return updateActiveLayout(state, (layout) => ({
+        ...layout,
+        panels: { isLeftOpen: true, isRightOpen: true, isBottomOpen: true },
+      }));
+    }
+    case 'setInvocationSource': {
+      if (!isInvocationSourceAvailable(action.sourceId)) {
+        return state;
+      }
+
+      return updateActiveInvocation(state, (invocation) => ({ ...invocation, sourceId: action.sourceId }));
+    }
+    case 'setInvocationDestination': {
+      return updateActiveInvocation(state, (invocation) => ({ ...invocation, destination: action.destination }));
+    }
+    case 'toggleSourceLock': {
+      return updateActiveInvocation(state, (invocation) => ({ ...invocation, sourceLocked: !invocation.sourceLocked }));
+    }
+    case 'toggleDestinationLock': {
+      return updateActiveInvocation(state, (invocation) => ({
+        ...invocation,
+        destinationLocked: !invocation.destinationLocked,
+      }));
+    }
+    case 'openRegionWidget': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) => {
+        const region = project.widgetRegions[action.region];
+        const existingInstanceInRegion = region.instanceIds
+          .map((instanceId) => project.widgetInstances[instanceId])
+          .find((instance) => instance?.typeId === action.widgetId);
+        const existingInstance =
+          existingInstanceInRegion ??
+          Object.values(project.widgetInstances).find((instance) => instance.typeId === action.widgetId);
+        const instanceId =
+          action.createNew || !existingInstance ? createId(`widget-${action.widgetId}`) : existingInstance.id;
+        const instanceIds = region.instanceIds.includes(instanceId)
+          ? region.instanceIds
+          : [...region.instanceIds, instanceId];
+        const widgetInstances = project.widgetInstances[instanceId]
+          ? project.widgetInstances
+          : {
+              ...project.widgetInstances,
+              [instanceId]: createWidgetInstance(action.widgetId, instanceId, action.initialValues),
+            };
+
+        return {
+          ...project,
+          layout: openPanelForRegion(project.layout, action.region),
+          widgetInstances,
+          widgetRegions: {
+            ...project.widgetRegions,
+            [action.region]: {
+              ...region,
+              activeInstanceId: instanceId,
+              instanceIds,
+              isCollapsed: false,
+            },
+          },
+        };
+      });
+    }
+    case 'selectRegionWidget': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) => {
+        const region = project.widgetRegions[action.region];
+
+        if (action.region === 'center') {
+          return {
+            ...project,
+            widgetRegions: {
+              ...project.widgetRegions,
+              center: { ...region, activeInstanceId: action.widgetId, isCollapsed: false },
+            },
+          };
+        }
+
+        const widgetRegion =
+          region.activeInstanceId === action.widgetId
+            ? { ...region, isCollapsed: !region.isCollapsed }
+            : { ...region, activeInstanceId: action.widgetId, isCollapsed: false };
+
+        return {
+          ...project,
+          layout: openPanelForRegion(project.layout, action.region),
+          widgetRegions: { ...project.widgetRegions, [action.region]: widgetRegion },
+        };
+      });
+    }
+    case 'toggleRegionWidget': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) =>
+        updateProjectWidgetRegion(project, action.region, (region) => {
+          const isEnabled = region.instanceIds.includes(action.widgetId);
+
+          if (action.region === 'center' && isEnabled && region.instanceIds.length === 1) {
+            return region;
+          }
+
+          const instanceIds = isEnabled
+            ? region.instanceIds.filter((widgetId) => widgetId !== action.widgetId)
+            : [...region.instanceIds, action.widgetId];
+          const fallbackInstanceId = getNextInstanceId(region, action.widgetId);
+
+          return {
+            ...region,
+            activeInstanceId: isEnabled && fallbackInstanceId ? fallbackInstanceId : action.widgetId,
+            instanceIds,
+            isCollapsed: action.region === 'center' ? false : instanceIds.length === 0 ? true : region.isCollapsed,
+          };
+        })
+      );
+    }
+    case 'moveWidgetInstance': {
+      return updateActiveProject(state, (project) => {
+        const fromRegion = project.widgetRegions[action.fromRegion];
+        const toRegion = project.widgetRegions[action.toRegion];
+        const nextFromInstanceIds = fromRegion.instanceIds.filter((instanceId) => instanceId !== action.instanceId);
+        const nextToInstanceIds = insertAt(toRegion.instanceIds, action.instanceId, action.toIndex);
+
+        return {
+          ...project,
+          layout: openPanelForRegion(project.layout, action.toRegion),
+          widgetRegions: {
+            ...project.widgetRegions,
+            [action.fromRegion]: {
+              ...fromRegion,
+              activeInstanceId:
+                fromRegion.activeInstanceId === action.instanceId
+                  ? (nextFromInstanceIds[0] ?? fromRegion.activeInstanceId)
+                  : fromRegion.activeInstanceId,
+              instanceIds: nextFromInstanceIds,
+              isCollapsed:
+                action.fromRegion === 'center' ? false : nextFromInstanceIds.length === 0 || fromRegion.isCollapsed,
+            },
+            [action.toRegion]: {
+              ...toRegion,
+              activeInstanceId: action.instanceId,
+              instanceIds: nextToInstanceIds,
+              isCollapsed: false,
+            },
+          },
+        };
+      });
+    }
+    case 'reorderWidgetInstances': {
+      return updateActiveWidgetRegion(state, action.region, (region) => ({
+        ...region,
+        activeInstanceId: action.activeInstanceId ?? region.activeInstanceId,
+        instanceIds: action.instanceIds,
+      }));
+    }
+    case 'setRegionWidgetCollapsed': {
+      if (action.region === 'center') {
+        return state;
+      }
+
+      return updateActiveWidgetRegion(state, action.region, (region) =>
+        region.isCollapsed === action.isCollapsed ? region : { ...region, isCollapsed: action.isCollapsed }
+      );
+    }
+    case 'setRegionWidgetSize': {
+      const sizePx = clampPanelSize(action.region, action.sizePx);
+
+      return updateActiveWidgetRegion(state, action.region, (region) =>
+        region.sizePx === sizePx ? region : { ...region, sizePx }
+      );
+    }
+    case 'setGenerateSettings': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) =>
+        updateProjectWidgetValues(project, 'generate', () => cloneGenerateWidgetValues(action.values))
+      );
+    }
+    case 'patchGenerateSettings': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) =>
+        updateProjectWidgetValues(project, 'generate', (values) => patchRecord(values, action.values))
+      );
+    }
+    case 'setGenerateBatchCount': {
+      const batchCount = sanitizeBatchCount(action.batchCount);
+
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) =>
+        updateProjectWidgetValues(project, 'generate', (values) =>
+          sanitizeBatchCount(values.batchCount) === batchCount ? values : { ...values, batchCount }
+        )
+      );
+    }
+    case 'addPromptToHistory': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) => ({
+        ...project,
+        promptHistory: addPromptHistoryItem(project.promptHistory, action.prompt),
+      }));
+    }
+    case 'removePromptFromHistory': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) => ({
+        ...project,
+        promptHistory: removePromptHistoryItem(project.promptHistory, action.prompt),
+      }));
+    }
+    case 'clearPromptHistory': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) => ({
+        ...project,
+        promptHistory: [],
+      }));
+    }
+    case 'patchWidgetValues': {
+      // Generic widget-owned UI state (panel modes, tabs, sizes). Not undoable.
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) =>
+        updateProjectWidgetValues(project, action.widgetId, (values) => patchRecord(values, action.values))
+      );
+    }
+    case 'patchWidgetInstanceValues': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) =>
+        updateProjectWidgetInstanceValues(project, action.instanceId, (values) =>
+          patchRecord(values, cloneRecord(action.values))
+        )
+      );
+    }
+    case 'setWidgetInstanceValues': {
+      return updateProjectById(state, action.projectId ?? state.activeProjectId, (project) =>
+        updateProjectWidgetInstanceValues(project, action.instanceId, (currentValues) => {
+          const values = cloneRecord(action.values);
+
+          return areRecordsShallowEqual(currentValues, values) ? currentValues : values;
+        })
+      );
+    }
+    case 'applyProjectGraphAction': {
+      return updateActiveProject(state, (project) => {
+        const projectGraph = projectGraphReducer(project.projectGraph, action.action);
+
+        if (projectGraph === project.projectGraph) {
+          return project;
+        }
+
+        const undoLabel = getProjectGraphUndoLabel(action.action);
+        const nextProject = undoLabel ? pushUndo(project, undoLabel) : project;
+        // Meaningful workflow edits are high-confidence source events: they
+        // steer the global Invoke route to the project graph unless locked.
+        const shouldAutoSetSource =
+          !project.invocation.sourceLocked &&
+          project.invocation.sourceId !== 'workflow' &&
+          isHighConfidenceGraphEdit(action.action) &&
+          isInvocationSourceAvailable('workflow');
+
+        return {
+          ...nextProject,
+          invocation: shouldAutoSetSource
+            ? { ...nextProject.invocation, sourceId: 'workflow' }
+            : nextProject.invocation,
+          projectGraph,
+        };
+      });
+    }
+    case 'replaceProjectGraph': {
+      const nextState = updateActiveProject(state, (project) => {
+        const nextProject = pushUndo(project, 'Replace project graph');
+
+        return {
+          ...nextProject,
+          events: [
+            {
+              createdAt: now(),
+              id: createId('event'),
+              summary: `Replaced the project graph with "${action.document.name || 'Untitled Workflow'}" (${action.label})`,
+              type: 'graph-replaced',
+            },
+            ...nextProject.events,
+          ],
+          graphHistory: [
+            createDocumentHistorySnapshot(`Before: ${action.label}`, project.projectGraph),
+            ...nextProject.graphHistory,
+          ].slice(0, HISTORY_LIMIT),
+          projectGraph: cloneProjectGraph(action.document),
+        };
+      });
+      const activeProject = nextState.projects.find((project) => project.id === nextState.activeProjectId);
+
+      return addNotification(
+        nextState,
+        createNotification({
+          kind: 'info',
+          message: `The previous project graph was saved to graph history.`,
+          projectId: activeProject?.id,
+          title: `Project graph replaced (${action.label})`,
+        })
+      );
+    }
+    case 'saveProjectGraphSnapshot': {
+      return updateActiveProject(state, (project) => ({
+        ...project,
+        events: [
+          {
+            createdAt: now(),
+            id: createId('event'),
+            summary: `Saved a graph history snapshot of "${project.projectGraph.name || 'Untitled Workflow'}"`,
+            type: 'graph-snapshot-saved',
+          },
+          ...project.events,
+        ],
+        graphHistory: [
+          createDocumentHistorySnapshot(
+            `Manual save: ${project.projectGraph.name || 'Untitled Workflow'}`,
+            project.projectGraph
+          ),
+          ...project.graphHistory,
+        ].slice(0, HISTORY_LIMIT),
+      }));
+    }
+    case 'restoreProjectGraphSnapshot': {
+      return updateActiveProject(state, (project) => {
+        const snapshot = project.graphHistory.find((entry) => entry.id === action.snapshotId);
+
+        if (!snapshot?.document) {
+          return project;
+        }
+
+        const nextProject = pushUndo(project, 'Restore graph history snapshot');
+
+        return {
+          ...nextProject,
+          graphHistory: [
+            createDocumentHistorySnapshot('Before restore', project.projectGraph),
+            ...nextProject.graphHistory,
+          ].slice(0, HISTORY_LIMIT),
+          projectGraph: cloneProjectGraph(normalizeProjectGraph(snapshot.document)),
+        };
+      });
+    }
+    case 'setProjectGraphLibraryBinding': {
+      return updateActiveProject(state, (project) => ({
+        ...project,
+        projectGraph: { ...project.projectGraph, libraryWorkflowId: action.libraryWorkflowId },
+      }));
+    }
+    case 'submitInvocationSnapshot': {
+      const beforeProject = state.projects.find((project) => project.id === state.activeProjectId);
+      const nextState = updateActiveProject(state, (project) =>
+        submitInvocationSnapshot(project, action.backendSupportsCancellation, undefined, action.models)
+      );
+      const afterProject = nextState.projects.find((project) => project.id === nextState.activeProjectId);
+
+      if (!beforeProject || !afterProject || beforeProject.queue.items.length === afterProject.queue.items.length) {
+        return nextState;
+      }
+
+      const queueItem = afterProject.queue.items[0];
+
+      return addNotification(
+        nextState,
+        createNotification({
+          kind: 'info',
+          message: `${afterProject.name}: ${queueItem.snapshot.sourceId} to ${queueItem.snapshot.destination}`,
+          projectId: afterProject.id,
+          title: 'Invocation queued',
+        })
+      );
+    }
+    case 'submitResolvedInvocationSnapshot': {
+      return updateActiveProject(state, (project) =>
+        submitInvocationSnapshot(
+          project,
+          action.backendSupportsCancellation,
+          resolveInvocationRoute(project, 'global', action.route, action.models),
+          action.models
+        )
+      );
+    }
+    case 'markQueueItemBackendSubmitted': {
+      return updateProjectById(state, action.projectId, (project) =>
+        clampCanvasStagingSelection(
+          updateQueueItem(project, action.queueItemId, (item) => {
+            const status = item.status === 'cancelled' ? 'cancelled' : 'running';
+            const hasSameBackendItemIds =
+              item.backendItemIds?.length === action.backendItemIds.length &&
+              item.backendItemIds.every((id, index) => id === action.backendItemIds[index]);
+
+            return item.backendBatchId === action.backendBatchId && hasSameBackendItemIds && item.status === status
+              ? item
+              : { ...item, backendBatchId: action.backendBatchId, backendItemIds: action.backendItemIds, status };
+          })
+        )
+      );
+    }
+    case 'setQueueItemStatus': {
+      const project = state.projects.find((project) => project.id === action.projectId);
+      const queueItem = project?.queue.items.find((item) => item.id === action.queueItemId);
+
+      if (queueItem?.status === 'cancelled' && action.status !== 'cancelled') {
+        return state;
+      }
+
+      if (queueItem?.status === action.status && queueItem.error === action.error) {
+        return state;
+      }
+
+      const nextState = updateProjectById(state, action.projectId, (project) =>
+        clampCanvasStagingSelection(
+          updateQueueItem(project, action.queueItemId, (item) => ({
+            ...item,
+            error: action.error,
+            status: action.status,
+          }))
+        )
+      );
+
+      if (action.notify === false || (action.status !== 'failed' && action.status !== 'cancelled')) {
+        return nextState;
+      }
+
+      return addNotification(
+        nextState,
+        createNotification({
+          kind: action.status === 'failed' ? 'error' : 'info',
+          message: action.error ?? `Queue item ${action.queueItemId} ${action.status}.`,
+          projectId: action.projectId,
+          title: action.status === 'failed' ? 'Invocation failed' : 'Invocation cancelled',
+        })
+      );
+    }
+    case 'routeQueueItemPartialResults': {
+      const project = state.projects.find((project) => project.id === action.projectId);
+      const queueItem = project?.queue.items.find((item) => item.id === action.queueItemId);
+
+      if (queueItem?.status === 'cancelled' || queueItem?.status === 'completed') {
+        return state;
+      }
+
+      return updateProjectById(state, action.projectId, (project) =>
+        routeQueueItemPartialResults(project, action.queueItemId, action.backendItemId, action.images)
+      );
+    }
+    case 'markQueueItemBackendCancelled': {
+      const project = state.projects.find((project) => project.id === action.projectId);
+      const queueItem = project?.queue.items.find((item) => item.id === action.queueItemId);
+
+      if (queueItem?.status === 'cancelled' || queueItem?.status === 'completed') {
+        return state;
+      }
+
+      return updateProjectById(state, action.projectId, (project) => {
+        const nextProject = updateQueueItem(project, action.queueItemId, (item) => {
+          const cancelledBackendItemIds = mergeBackendItemId(item.cancelledBackendItemIds, action.backendItemId);
+
+          return {
+            ...item,
+            cancelledBackendItemIds,
+            status: getQueueItemStatusAfterBackendCancellation(item, cancelledBackendItemIds),
+          };
+        });
+
+        return clampCanvasStagingSelection(nextProject);
+      });
+    }
+    case 'routeQueueItemResults': {
+      const project = state.projects.find((project) => project.id === action.projectId);
+      const queueItem = project?.queue.items.find((item) => item.id === action.queueItemId);
+
+      if (queueItem?.status === 'cancelled') {
+        return state;
+      }
+
+      const nextState = updateProjectById(state, action.projectId, (project) =>
+        routeQueueItemResults(project, action.queueItemId, action.images)
+      );
+
+      if (action.images.length === 0) {
+        return nextState;
+      }
+
+      return addNotification(
+        nextState,
+        createNotification({
+          kind: 'success',
+          message: `${action.images.length} image(s) routed from ${action.queueItemId}.`,
+          projectId: action.projectId,
+          title: 'Invocation completed',
+        })
+      );
+    }
+    case 'appendCanvasStagingCandidate': {
+      return updateProjectById(state, action.projectId, (project) =>
+        appendCanvasStagingCandidate(project, action.candidate)
+      );
+    }
+    case 'selectGalleryImage': {
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          selectedImage: action.image,
+          selectedImageName: action.image.imageName,
+          selectedImageNames: [action.image.imageName],
+        }),
+        action.projectId
+      );
+    }
+    case 'toggleGalleryImageInSelection': {
+      return updateGalleryValues(
+        state,
+        (values) => {
+          const imageName = action.image.imageName;
+          const selectedImageNames = getGallerySelectedImageNames(values);
+
+          if (!selectedImageNames.includes(imageName)) {
+            return {
+              ...values,
+              selectedImage: action.image,
+              selectedImageName: imageName,
+              selectedImageNames: [...selectedImageNames, imageName],
+            };
+          }
+
+          const remainingImageNames = selectedImageNames.filter((name) => name !== imageName);
+          const wasPrimary = values.selectedImageName === imageName;
+
+          return {
+            ...values,
+            selectedImage: wasPrimary ? null : values.selectedImage,
+            selectedImageName: wasPrimary
+              ? (remainingImageNames[remainingImageNames.length - 1] ?? null)
+              : values.selectedImageName,
+            selectedImageNames: remainingImageNames,
+          };
+        },
+        action.projectId
+      );
+    }
+    case 'setGalleryMultiSelection': {
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          selectedImage: action.primaryImage,
+          selectedImageName: action.primaryImage.imageName,
+          selectedImageNames: action.imageNames,
+        }),
+        action.projectId
+      );
+    }
+    case 'setGalleryCompareImage': {
+      return updateGalleryValues(state, (values) => ({ ...values, compareImage: action.image }), action.projectId);
+    }
+    case 'selectGalleryBoard': {
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          galleryPage: 0,
+          selectedBoardId: action.boardId,
+          selectedImageNames: [],
+        }),
+        action.projectId
+      );
+    }
+    case 'setGalleryView': {
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          galleryPage: 0,
+          galleryView: action.galleryView,
+          selectedImageNames: [],
+        }),
+        action.projectId
+      );
+    }
+    case 'setGallerySearchTerm': {
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          galleryPage: 0,
+          searchTerm: action.searchTerm,
+        }),
+        action.projectId
+      );
+    }
+    case 'updateGallerySettings': {
+      const resetsQuery =
+        action.settings.imageOrderDir !== undefined ||
+        action.settings.starredFirst !== undefined ||
+        action.settings.paginationMode !== undefined;
+
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          ...action.settings,
+          ...(resetsQuery ? { galleryPage: 0 } : {}),
+        }),
+        action.projectId
+      );
+    }
+    case 'setGalleryPage': {
+      return updateGalleryValues(
+        state,
+        (values) => ({ ...values, galleryPage: Math.max(0, action.page) }),
+        action.projectId
+      );
+    }
+    case 'setGalleryPageInfo': {
+      if (!Number.isFinite(action.totalImages)) {
+        return state;
+      }
+
+      return updateGalleryValues(
+        state,
+        (values) => {
+          const totalImages = Math.max(0, action.totalImages);
+
+          return values.galleryTotalImages === totalImages ? values : { ...values, galleryTotalImages: totalImages };
+        },
+        action.projectId
+      );
+    }
+    case 'touchGalleryRefresh': {
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          galleryImagesRefreshToken: createId('gallery-images-refresh'),
+          galleryRefreshToken: createId('gallery-refresh'),
+        }),
+        action.projectId
+      );
+    }
+    case 'touchGalleryImagesRefresh': {
+      return updateGalleryValues(
+        state,
+        (values) => ({
+          ...values,
+          galleryImagesRefreshToken: createId('gallery-images-refresh'),
+        }),
+        action.projectId
+      );
+    }
+    case 'removeGalleryImages': {
+      const removedImageNames = new Set(action.imageNames);
+
+      return updateGalleryValues(
+        state,
+        (values) => {
+          const selectedImage = values.selectedImage as GeneratedImageContract | null | undefined;
+          const compareImage = values.compareImage as GeneratedImageContract | null | undefined;
+          const selectedImageName = typeof values.selectedImageName === 'string' ? values.selectedImageName : null;
+
+          return {
+            ...values,
+            compareImage: compareImage && removedImageNames.has(compareImage.imageName) ? null : compareImage,
+            recentImages: getGalleryImages(values).filter((image) => !removedImageNames.has(image.imageName)),
+            selectedImage: selectedImage && removedImageNames.has(selectedImage.imageName) ? null : selectedImage,
+            selectedImageName: selectedImageName && removedImageNames.has(selectedImageName) ? null : selectedImageName,
+            selectedImageNames: getGallerySelectedImageNames(values).filter((name) => !removedImageNames.has(name)),
+          };
+        },
+        action.projectId
+      );
+    }
+    case 'setGalleryProjectBoardId': {
+      return updateGalleryValues(state, (values) => ({ ...values, projectBoardId: action.boardId }), action.projectId);
+    }
+    case 'applyCanvasProjectMutation': {
+      return updateProjectById(state, action.projectId, (project) =>
+        applyCanvasProjectMutation(project, action.mutation)
+      );
+    }
+    case 'submitCanvasInvocationSnapshot': {
+      return updateProjectById(state, action.projectId, (project) =>
+        enqueueCompiledSnapshot(
+          project,
+          { ...project.invocation, destination: action.destination, sourceId: 'canvas' },
+          {
+            generate: action.generate,
+            graph: action.graph,
+            widgetStates: getWidgetStatesSnapshot(project.widgetInstances),
+          },
+          action.backendSupportsCancellation,
+          action.canvas
+        )
+      );
+    }
+    case 'cancelQueueItem': {
+      const targetProjectId = action.projectId ?? state.activeProjectId;
+      const targetProject = state.projects.find((project) => project.id === targetProjectId);
+      const queueItem = targetProject?.queue.items.find((item) => item.id === action.queueItemId);
+      const canCancelQueueItem = queueItem ? isCancellableQueueItem(queueItem) : false;
+      const nextState = updateProjectById(state, targetProjectId, (project) =>
+        clampCanvasStagingSelection({
+          ...project,
+          queue: {
+            items: project.queue.items.map((item) => {
+              if (item.id !== action.queueItemId || !isCancellableQueueItem(item)) {
+                return item;
+              }
+
+              return { ...item, status: 'cancelled' };
+            }),
+          },
+        })
+      );
+
+      if (!targetProject || !queueItem || !canCancelQueueItem) {
+        return nextState;
+      }
+
+      return addNotification(
+        nextState,
+        createNotification({
+          kind: 'info',
+          message: `${targetProject.name}: ${action.queueItemId}`,
+          projectId: targetProject.id,
+          title: 'Invocation cancellation requested',
+        })
+      );
+    }
+    case 'cancelAllQueueItems': {
+      const cancellableCount = state.projects.reduce(
+        (count, project) =>
+          shouldApplyQueueBulkActionToProject(project, action.projectId)
+            ? count + project.queue.items.filter(isCancellableQueueItem).length
+            : count,
+        0
+      );
+
+      if (cancellableCount === 0) {
+        return state;
+      }
+
+      const nextState: WorkbenchState = {
+        ...state,
+        projects: state.projects.map((project) =>
+          clampCanvasStagingSelection({
+            ...project,
+            queue: {
+              items: shouldApplyQueueBulkActionToProject(project, action.projectId)
+                ? project.queue.items.map((item) =>
+                    isCancellableQueueItem(item) ? { ...item, status: 'cancelled' } : item
+                  )
+                : project.queue.items,
+            },
+          })
+        ),
+      };
+
+      return addNotification(
+        nextState,
+        createNotification({
+          kind: 'info',
+          message: `${cancellableCount} queue item${cancellableCount === 1 ? '' : 's'}.`,
+          title: 'Invocation cancellation requested',
+        })
+      );
+    }
+    case 'cancelAllQueueItemsExceptCurrent': {
+      const cancellableCount = state.projects.reduce(
+        (count, project) =>
+          shouldApplyQueueBulkActionToProject(project, action.projectId)
+            ? count +
+              project.queue.items.filter(
+                (item) => isCancellableQueueItem(item) && item.id !== action.currentQueueItemId
+              ).length
+            : count,
+        0
+      );
+
+      if (cancellableCount === 0) {
+        return state;
+      }
+
+      const nextState: WorkbenchState = {
+        ...state,
+        projects: state.projects.map((project) =>
+          clampCanvasStagingSelection({
+            ...project,
+            queue: {
+              items: shouldApplyQueueBulkActionToProject(project, action.projectId)
+                ? project.queue.items.map((item) =>
+                    isCancellableQueueItem(item) && item.id !== action.currentQueueItemId
+                      ? { ...item, status: 'cancelled' }
+                      : item
+                  )
+                : project.queue.items,
+            },
+          })
+        ),
+      };
+
+      return addNotification(
+        nextState,
+        createNotification({
+          kind: 'info',
+          message: `${cancellableCount} queue item${cancellableCount === 1 ? '' : 's'}.`,
+          title: 'Invocation cancellation requested',
+        })
+      );
+    }
+    case 'clearCompletedQueueItems': {
+      return {
+        ...state,
+        projects: state.projects.map((project) => ({
+          ...project,
+          queue: { items: project.queue.items.filter((item) => !isClearableQueueItem(item)) },
+        })),
+      };
+    }
+    case 'undoProjectChange': {
+      return updateActiveProject(state, (project) => {
+        const undoEntry = project.undoRedo.past.at(-1);
+
+        if (!undoEntry) {
+          return project;
+        }
+
+        const restoredProject = restoreUndoSnapshot(project, undoEntry.project);
+
+        return {
+          ...restoredProject,
+          events: project.events,
+          graphHistory: project.graphHistory,
+          promptHistory: project.promptHistory,
+          queue: project.queue,
+          undoRedo: {
+            future: [
+              {
+                createdAt: now(),
+                id: createId('redo'),
+                label: undoEntry.label,
+                project: createUndoSnapshot(project),
+              },
+              ...project.undoRedo.future,
+            ].slice(0, HISTORY_LIMIT),
+            past: project.undoRedo.past.slice(0, -1),
+          },
+        };
+      });
+    }
+    case 'redoProjectChange': {
+      return updateActiveProject(state, (project) => {
+        const redoEntry = project.undoRedo.future[0];
+
+        if (!redoEntry) {
+          return project;
+        }
+
+        const restoredProject = restoreUndoSnapshot(project, redoEntry.project);
+
+        return {
+          ...restoredProject,
+          events: project.events,
+          graphHistory: project.graphHistory,
+          promptHistory: project.promptHistory,
+          queue: project.queue,
+          undoRedo: {
+            future: project.undoRedo.future.slice(1),
+            past: [
+              ...project.undoRedo.past,
+              {
+                createdAt: now(),
+                id: createId('undo'),
+                label: redoEntry.label,
+                project: createUndoSnapshot(project),
+              },
+            ].slice(-HISTORY_LIMIT),
+          },
+        };
+      });
+    }
+    case 'hydrateWorkbench': {
+      return { ...normalizeWorkbenchState(action.state), backendConnection: state.backendConnection };
+    }
+    case 'reconcileProjectConflict': {
+      // A save lost the revision race against another tab/device. The server
+      // version takes over the original project id, and the local edits
+      // continue in the recovered fork — which stays the active project when
+      // the user was looking at it.
+      const normalizedServerProject = ensureProjectWidgetContracts(action.serverProject);
+      const recoveredProject = ensureProjectWidgetContracts(action.recoveredProject);
+      const localProject = state.projects.find((project) => project.id === action.projectId);
+      const hasOriginal = localProject !== undefined;
+      // The server document replaces the local one under the SAME project id, so a
+      // live engine mirroring that id may hold pixel history for the outgoing
+      // document. Bump the revision past both sides so the mirror treats the swap
+      // as a document replacement (clearing that history) even when dims/layer ids
+      // coincide. (The recovered fork gets a fresh project id → a fresh engine.)
+      const serverProject: Project = hasOriginal
+        ? {
+            ...normalizedServerProject,
+            canvas: {
+              ...normalizedServerProject.canvas,
+              documentRevision:
+                Math.max(normalizedServerProject.canvas.documentRevision, localProject.canvas.documentRevision) + 1,
+            },
+          }
+        : normalizedServerProject;
+      const projects = hasOriginal
+        ? state.projects.flatMap((project) =>
+            project.id === action.projectId ? [serverProject, recoveredProject] : [project]
+          )
+        : [...state.projects, serverProject, recoveredProject];
+
+      return addNotification(
+        {
+          ...state,
+          activeProjectId: state.activeProjectId === action.projectId ? recoveredProject.id : state.activeProjectId,
+          projects,
+        },
+        createNotification({
+          kind: 'info',
+          message: `"${serverProject.name}" was changed elsewhere. Your local edits continue in "${recoveredProject.name}" — manage recoveries in the Project panel.`,
+          title: 'Project recovered',
+        })
+      );
+    }
+    case 'autosaveStarted': {
+      return { ...state, autosave: { status: 'saving' } };
+    }
+    case 'autosaveSucceeded': {
+      return { ...state, autosave: { lastSavedAt: action.savedAt, status: 'saved' } };
+    }
+    case 'autosaveFailed': {
+      return addNotification(
+        { ...state, autosave: { error: action.error, status: 'error' } },
+        createNotification({ kind: 'error', message: action.error, title: 'Autosave failed' })
+      );
+    }
+    case 'markAllNotificationsRead': {
+      return {
+        ...state,
+        notifications: state.notifications.map((notification) => ({ ...notification, isRead: true })),
+      };
+    }
+    case 'clearNotifications': {
+      return { ...state, notifications: [] };
+    }
+    case 'recordWidgetFailure': {
+      const hasFailure = state.widgetFailures.some((failure) => failure.widgetId === action.failure.widgetId);
+
+      if (hasFailure) {
+        return state;
+      }
+
+      return addNotification(
+        {
+          ...state,
+          widgetFailures: [action.failure, ...state.widgetFailures],
+        },
+        createNotification({
+          kind: 'error',
+          message: action.failure.details,
+          title: `Widget failed: ${action.failure.widgetId}`,
+        })
+      );
+    }
+    case 'recordError': {
+      return addNotification(state, createNotification({ kind: 'error', message: action.message, title: 'Error' }));
+    }
+    case 'setBackendConnectionStatus': {
+      const timestamp = now();
+
+      if (state.backendConnection.status === action.status && state.backendConnection.error === action.error) {
+        return state;
+      }
+
+      return {
+        ...state,
+        backendConnection: {
+          error: action.error,
+          lastConnectedAt: action.status === 'connected' ? timestamp : state.backendConnection.lastConnectedAt,
+          lastDisconnectedAt: action.status === 'disconnected' ? timestamp : state.backendConnection.lastDisconnectedAt,
+          status: action.status,
+        },
+      };
+    }
+    case 'refreshBackendData': {
+      return { ...state, projects: state.projects.map((project) => refreshProjectBackendData(project)) };
+    }
+    case 'recordNotice': {
+      return addNotification(
+        state,
+        createNotification({ kind: action.kind, message: action.message, title: action.title })
+      );
+    }
+    case 'setActiveProjectSettings': {
+      return updateActiveProject(state, (project) => {
+        const settings = normalizeProjectSettings({ ...project.settings, ...action.settings });
+
+        return Object.entries(settings).every(([key, value]) => {
+          const settingKey = key as keyof ProjectSettings;
+
+          return areProjectSettingValuesEqual(
+            project.settings[settingKey],
+            value as ProjectSettings[typeof settingKey]
+          );
+        })
+          ? project
+          : { ...project, settings };
+      });
+    }
+  }
+};
+
+export type WorkbenchAction = WorkbenchReducerAction;
+export type { WorkbenchReducerAction };
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchStore.test.ts b/invokeai/frontend/webv2/src/workbench/workbenchStore.test.ts
new file mode 100644
index 00000000000..2318864b852
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchStore.test.ts
@@ -0,0 +1,320 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { WorkbenchSnapshot, WorkbenchStore } from './workbenchStore';
+
+import { clearProjectDiagnostics, configureDiagnostics, getProjectDiagnostics } from './diagnostics/logger';
+import { areWidgetPlacementProjectsEqual, getWidgetPlacementProject } from './widgetPlacementMeta';
+import { getProjectWidgetValues } from './widgetState';
+import { createWorkbenchStore } from './workbenchStore';
+
+const watchSelector = <Selected>(
+  store: WorkbenchStore,
+  selector: (snapshot: WorkbenchSnapshot) => Selected,
+  isEqual: (left: Selected, right: Selected) => boolean = Object.is
+) => {
+  let current = selector(store.getSnapshot());
+  let changeCount = 0;
+
+  const unsubscribe = store.subscribe(() => {
+    const next = selector(store.getSnapshot());
+
+    if (!isEqual(current, next)) {
+      current = next;
+      changeCount += 1;
+    }
+  });
+
+  return {
+    get changeCount() {
+      return changeCount;
+    },
+    get current() {
+      return current;
+    },
+    unsubscribe,
+  };
+};
+
+describe('createWorkbenchStore', () => {
+  beforeEach(() => {
+    configureDiagnostics({
+      enabled: true,
+      level: 'trace',
+      namespaces: ['system', 'queue'],
+      performanceTimingsEnabled: false,
+    });
+  });
+
+  it('exposes a stable dispatch and initializes snapshot metadata', () => {
+    const store = createWorkbenchStore();
+    const snapshot = store.getSnapshot();
+
+    expect(store.dispatch).toBe(store.dispatch);
+    expect(snapshot.state.activeProjectId).toBe(snapshot.activeProject.id);
+    expect(snapshot.hasHydrated).toBe(false);
+    expect(snapshot.state.projects).toHaveLength(1);
+  });
+
+  it('notifies subscribers once for reducer changes and not for no-op reducer results', () => {
+    const store = createWorkbenchStore();
+    const listener = vi.fn();
+
+    store.subscribe(listener);
+
+    const projectId = store.getSnapshot().activeProject.id;
+
+    store.dispatch({ name: 'Renamed', projectId, type: 'renameProject' });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(store.getSnapshot().activeProject.name).toBe('Renamed');
+
+    store.dispatch({ name: '   ', projectId, type: 'renameProject' });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(store.getSnapshot().activeProject.name).toBe('Renamed');
+  });
+
+  it('updates hydration metadata without changing durable workbench state', () => {
+    const store = createWorkbenchStore();
+    const initialState = store.getState();
+    const initialPersistedRevision = store.getPersistedRevision();
+    const listener = vi.fn();
+
+    store.subscribe(listener);
+
+    store.setHasHydrated(true);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(store.getSnapshot().hasHydrated).toBe(true);
+    expect(store.getState()).toBe(initialState);
+    expect(store.getPersistedRevision()).toBe(initialPersistedRevision);
+
+    store.setHasHydrated(true);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('bumps persisted revision only for autosaved state changes', () => {
+    const store = createWorkbenchStore();
+    const initialPersistedRevision = store.getPersistedRevision();
+
+    store.dispatch({ status: 'connected', type: 'setBackendConnectionStatus' });
+
+    expect(store.getPersistedRevision()).toBe(initialPersistedRevision);
+
+    store.dispatch({ kind: 'info', title: 'Global notice', type: 'recordNotice' });
+
+    expect(store.getPersistedRevision()).toBe(initialPersistedRevision);
+
+    store.dispatch({
+      name: 'Persisted rename',
+      projectId: store.getSnapshot().activeProject.id,
+      type: 'renameProject',
+    });
+
+    expect(store.getPersistedRevision()).toBe(initialPersistedRevision + 1);
+  });
+
+  it('records recordError actions into project diagnostics', () => {
+    const store = createWorkbenchStore();
+    const projectId = store.getSnapshot().activeProject.id;
+
+    clearProjectDiagnostics(projectId);
+    store.dispatch({ area: 'queue-runtime', message: 'Queue failed', namespace: 'queue', type: 'recordError' });
+
+    expect(getProjectDiagnostics(projectId)).toMatchObject([
+      {
+        level: 'error',
+        message: 'Queue failed',
+        namespace: 'queue',
+        source: { area: 'queue-runtime', kind: 'workbench', projectId },
+      },
+    ]);
+    expect(store.getSnapshot().state.notifications[0]?.title).toBe('Error');
+  });
+
+  it('records accepted widget failures into diagnostics once', () => {
+    const store = createWorkbenchStore();
+    const projectId = store.getSnapshot().activeProject.id;
+    const failure = {
+      details: 'Widget stack',
+      message: 'Widget failed',
+      occurredAt: '2026-06-29T00:00:00.000Z',
+      widgetId: 'workflow' as const,
+    };
+
+    clearProjectDiagnostics(projectId);
+    store.dispatch({ failure, type: 'recordWidgetFailure' });
+    store.dispatch({ failure, type: 'recordWidgetFailure' });
+
+    expect(getProjectDiagnostics(projectId)).toMatchObject([
+      {
+        context: { widgetId: 'workflow' },
+        level: 'error',
+        message: 'Widget stack',
+        namespace: 'system',
+        source: { area: 'widget-failure', kind: 'workbench', projectId },
+      },
+    ]);
+  });
+
+  it('stops notifying unsubscribed listeners', () => {
+    const store = createWorkbenchStore();
+    const listener = vi.fn();
+    const unsubscribe = store.subscribe(listener);
+
+    unsubscribe();
+    store.dispatch({ type: 'createProject' });
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('keeps active-project selectors stable across unrelated global state updates', () => {
+    const store = createWorkbenchStore();
+    const activeProjectWatcher = watchSelector(store, (snapshot) => snapshot.activeProject);
+    const activeProjectIdWatcher = watchSelector(store, (snapshot) => snapshot.activeProject.id);
+    const notificationCountWatcher = watchSelector(store, (snapshot) => snapshot.state.notifications.length);
+
+    store.dispatch({ kind: 'info', title: 'Global notice', type: 'recordNotice' });
+
+    expect(notificationCountWatcher.current).toBe(1);
+    expect(notificationCountWatcher.changeCount).toBe(1);
+    expect(activeProjectWatcher.changeCount).toBe(0);
+    expect(activeProjectIdWatcher.changeCount).toBe(0);
+  });
+
+  it('lets narrow selectors observe only their own state changes', () => {
+    const store = createWorkbenchStore();
+    const backendStatusWatcher = watchSelector(store, (snapshot) => snapshot.state.backendConnection.status);
+    const activeProjectIdWatcher = watchSelector(store, (snapshot) => snapshot.activeProject.id);
+    const projectCountWatcher = watchSelector(store, (snapshot) => snapshot.state.projects.length);
+    const batchCountWatcher = watchSelector(store, (snapshot) =>
+      Number(getProjectWidgetValues(snapshot.activeProject, 'generate').batchCount ?? 1)
+    );
+
+    store.dispatch({ status: 'connected', type: 'setBackendConnectionStatus' });
+
+    expect(backendStatusWatcher.current).toBe('connected');
+    expect(backendStatusWatcher.changeCount).toBe(1);
+    expect(activeProjectIdWatcher.changeCount).toBe(0);
+    expect(projectCountWatcher.changeCount).toBe(0);
+    expect(batchCountWatcher.changeCount).toBe(0);
+
+    store.dispatch({ batchCount: 3, type: 'setGenerateBatchCount' });
+
+    expect(batchCountWatcher.current).toBe(3);
+    expect(batchCountWatcher.changeCount).toBe(1);
+    expect(backendStatusWatcher.changeCount).toBe(1);
+    expect(activeProjectIdWatcher.changeCount).toBe(0);
+    expect(projectCountWatcher.changeCount).toBe(0);
+
+    store.dispatch({ type: 'createProject' });
+
+    expect(projectCountWatcher.current).toBe(2);
+    expect(projectCountWatcher.changeCount).toBe(1);
+    expect(activeProjectIdWatcher.current).toBe(store.getSnapshot().activeProject.id);
+    expect(activeProjectIdWatcher.changeCount).toBe(1);
+    expect(backendStatusWatcher.changeCount).toBe(1);
+  });
+
+  it('supports custom equality for derived selector objects', () => {
+    const store = createWorkbenchStore();
+    const statusObjectWatcher = watchSelector(
+      store,
+      (snapshot) => ({ status: snapshot.state.backendConnection.status }),
+      (left, right) => left.status === right.status
+    );
+
+    store.dispatch({ kind: 'info', title: 'Unrelated notice', type: 'recordNotice' });
+
+    expect(statusObjectWatcher.current).toEqual({ status: 'connecting' });
+    expect(statusObjectWatcher.changeCount).toBe(0);
+
+    store.dispatch({ status: 'connected', type: 'setBackendConnectionStatus' });
+
+    expect(statusObjectWatcher.current).toEqual({ status: 'connected' });
+    expect(statusObjectWatcher.changeCount).toBe(1);
+  });
+
+  it('keeps widget placement metadata stable across widget value updates', () => {
+    const store = createWorkbenchStore();
+    const placementWatcher = watchSelector(
+      store,
+      (snapshot) => getWidgetPlacementProject(snapshot.activeProject),
+      areWidgetPlacementProjectsEqual
+    );
+    const widgetInstancesWatcher = watchSelector(store, (snapshot) => snapshot.activeProject.widgetInstances);
+
+    store.dispatch({ instanceId: 'generate', type: 'patchWidgetInstanceValues', values: { prompt: 'updated' } });
+
+    expect(widgetInstancesWatcher.changeCount).toBe(1);
+    expect(placementWatcher.changeCount).toBe(0);
+  });
+
+  it('treats identical widget placement in a different project as a placement change', () => {
+    const store = createWorkbenchStore();
+    const placementWatcher = watchSelector(
+      store,
+      (snapshot) => getWidgetPlacementProject(snapshot.activeProject),
+      areWidgetPlacementProjectsEqual
+    );
+    const firstProjectId = placementWatcher.current.projectId;
+
+    store.dispatch({ type: 'createProject' });
+
+    expect(placementWatcher.current.projectId).not.toBe(firstProjectId);
+    expect(placementWatcher.changeCount).toBe(1);
+  });
+
+  it('does not notify subscribers for equivalent generate and project settings writes', () => {
+    const store = createWorkbenchStore();
+    const listener = vi.fn();
+
+    store.subscribe(listener);
+
+    store.dispatch({ batchCount: 1, type: 'setGenerateBatchCount' });
+    store.dispatch({ settings: { useCpuNoise: true }, type: 'setActiveProjectSettings' });
+    store.dispatch({ isCollapsed: false, region: 'left', type: 'setRegionWidgetCollapsed' });
+    store.dispatch({
+      region: 'left',
+      sizePx: store.getSnapshot().activeProject.widgetRegions.left.sizePx,
+      type: 'setRegionWidgetSize',
+    });
+    store.dispatch({ type: 'patchWidgetValues', values: {}, widgetId: 'generate' });
+    store.dispatch({ status: 'connecting', type: 'setBackendConnectionStatus' });
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('does not notify subscribers for equivalent queue status writes', () => {
+    const store = createWorkbenchStore();
+    const project = store.getSnapshot().activeProject;
+    const listener = vi.fn();
+
+    store.subscribe(listener);
+
+    store.dispatch({
+      projectId: project.id,
+      queueItemId: 'missing-queue-item',
+      status: 'pending',
+      type: 'setQueueItemStatus',
+    });
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('keeps placement selectors stable across generate, queue, and settings changes', () => {
+    const store = createWorkbenchStore();
+    const placementWatcher = watchSelector(
+      store,
+      (snapshot) => getWidgetPlacementProject(snapshot.activeProject),
+      areWidgetPlacementProjectsEqual
+    );
+
+    store.dispatch({ batchCount: 2, type: 'setGenerateBatchCount' });
+    store.dispatch({ backendSupportsCancellation: true, type: 'submitInvocationSnapshot' });
+    store.dispatch({ settings: { useCpuNoise: false }, type: 'setActiveProjectSettings' });
+
+    expect(placementWatcher.changeCount).toBe(0);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workbenchStore.ts b/invokeai/frontend/webv2/src/workbench/workbenchStore.ts
new file mode 100644
index 00000000000..467e293476f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workbenchStore.ts
@@ -0,0 +1,144 @@
+import type { Dispatch } from 'react';
+
+import type { Project, WorkbenchState } from './types';
+
+import { recordDiagnosticEntry } from './diagnostics/logger';
+import { createExternalStore } from './externalStore';
+import { createInitialWorkbenchState, workbenchReducer, type WorkbenchReducerAction } from './workbenchState';
+
+type WorkbenchAction = WorkbenchReducerAction;
+
+export interface WorkbenchSnapshot {
+  state: WorkbenchState;
+  activeProject: Project;
+  hasHydrated: boolean;
+}
+
+export interface WorkbenchStore {
+  dispatch: Dispatch<WorkbenchAction>;
+  getPersistedRevision: () => number;
+  getSnapshot: () => WorkbenchSnapshot;
+  getState: () => WorkbenchState;
+  setHasHydrated: (hasHydrated: boolean) => void;
+  subscribe: (listener: () => void) => () => void;
+}
+
+const getActiveProject = (state: WorkbenchState): Project =>
+  state.projects.find((project) => project.id === state.activeProjectId) ?? state.projects[0];
+
+const createSnapshot = (state: WorkbenchState, hasHydrated: boolean): WorkbenchSnapshot => ({
+  activeProject: getActiveProject(state),
+  hasHydrated,
+  state,
+});
+
+const hasPersistedStateChanged = (previous: WorkbenchState, next: WorkbenchState): boolean =>
+  !Object.is(previous.account, next.account) ||
+  previous.activeProjectId !== next.activeProjectId ||
+  !Object.is(previous.projects, next.projects) ||
+  !Object.is(previous.widgetFailures, next.widgetFailures);
+
+const getDiagnosticProjectId = (state: WorkbenchState, projectId?: string): string | undefined =>
+  projectId ?? getActiveProject(state)?.id;
+
+const recordDiagnosticForAction = (
+  action: WorkbenchAction,
+  previousState: WorkbenchState,
+  nextState: WorkbenchState
+): void => {
+  switch (action.type) {
+    case 'recordError': {
+      const projectId = getDiagnosticProjectId(nextState, action.projectId);
+
+      if (!projectId) {
+        return;
+      }
+
+      recordDiagnosticEntry({
+        context: action.context,
+        level: 'error',
+        message: action.message,
+        namespace: action.namespace ?? 'system',
+        source: { area: action.area ?? 'runtime', kind: 'workbench', projectId },
+      });
+      break;
+    }
+    case 'recordWidgetFailure': {
+      if (Object.is(previousState, nextState)) {
+        return;
+      }
+
+      const projectId = getDiagnosticProjectId(nextState);
+
+      if (!projectId) {
+        return;
+      }
+
+      recordDiagnosticEntry({
+        context: { widgetId: action.failure.widgetId },
+        level: 'error',
+        message: action.failure.details,
+        namespace: 'system',
+        source: { area: 'widget-failure', kind: 'workbench', projectId },
+      });
+      break;
+    }
+    case 'closeProject': {
+      if (previousState.projects.length !== 1) {
+        return;
+      }
+
+      const projectId = getDiagnosticProjectId(nextState, action.projectId);
+
+      if (!projectId) {
+        return;
+      }
+
+      recordDiagnosticEntry({
+        level: 'error',
+        message: 'At least one project must remain open.',
+        namespace: 'system',
+        source: { area: 'project-lifecycle', kind: 'workbench', projectId },
+      });
+      break;
+    }
+  }
+};
+
+export const createWorkbenchStore = (initialState = createInitialWorkbenchState()): WorkbenchStore => {
+  let state = initialState;
+  let hasHydrated = false;
+  let persistedRevision = 0;
+  const snapshotStore = createExternalStore(createSnapshot(state, hasHydrated));
+
+  const setSnapshotState = (nextState: WorkbenchState, nextHasHydrated = hasHydrated): void => {
+    if (Object.is(nextState, state) && nextHasHydrated === hasHydrated) {
+      return;
+    }
+
+    if (!Object.is(nextState, state) && hasPersistedStateChanged(state, nextState)) {
+      persistedRevision += 1;
+    }
+
+    state = nextState;
+    hasHydrated = nextHasHydrated;
+    snapshotStore.setSnapshot(createSnapshot(state, hasHydrated));
+  };
+
+  return {
+    dispatch(action) {
+      const previousState = state;
+      const nextState = workbenchReducer(state, action);
+
+      setSnapshotState(nextState);
+      recordDiagnosticForAction(action, previousState, nextState);
+    },
+    getPersistedRevision: () => persistedRevision,
+    getSnapshot: snapshotStore.getSnapshot,
+    getState: () => state,
+    setHasHydrated: (nextHasHydrated) => setSnapshotState(state, nextHasHydrated),
+    subscribe: snapshotStore.subscribe,
+  };
+};
+
+export type { WorkbenchAction };
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/api.ts b/invokeai/frontend/webv2/src/workbench/workflows/api.ts
new file mode 100644
index 00000000000..ee7be74b942
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/api.ts
@@ -0,0 +1,95 @@
+import { apiFetch, apiFetchJson } from '@workbench/backend/http';
+
+/**
+ * Client for the backend workflow library (`/api/v1/workflows`). The library
+ * stores legacy-format WorkflowV3 JSON, so payloads round-trip through
+ * `workflowJson.ts` on their way in and out of the project graph document.
+ */
+
+export type WorkflowLibraryCategory = 'user' | 'default';
+
+export interface WorkflowLibraryListItem {
+  workflow_id: string;
+  name: string;
+  description: string;
+  category: WorkflowLibraryCategory;
+  tags?: string | null;
+  created_at?: string;
+  updated_at?: string;
+  opened_at?: string | null;
+  thumbnail_url?: string | null;
+}
+
+export interface WorkflowLibraryPage {
+  items: WorkflowLibraryListItem[];
+  page: number;
+  pages: number;
+  total: number;
+}
+
+export interface ListWorkflowsParams {
+  category: WorkflowLibraryCategory;
+  page: number;
+  perPage?: number;
+  query?: string;
+}
+
+export const listLibraryWorkflows = ({
+  category,
+  page,
+  perPage = 20,
+  query,
+}: ListWorkflowsParams): Promise<WorkflowLibraryPage> => {
+  const params = new URLSearchParams({
+    direction: 'DESC',
+    order_by: 'updated_at',
+    page: String(page),
+    per_page: String(perPage),
+  });
+
+  params.append('categories', category);
+
+  if (query?.trim()) {
+    params.set('query', query.trim());
+  }
+
+  return apiFetchJson<WorkflowLibraryPage>(`/api/v1/workflows/?${params.toString()}`);
+};
+
+interface WorkflowRecordDTO {
+  workflow_id: string;
+  name: string;
+  workflow: Record<string, unknown>;
+}
+
+/** Returns the stored workflow JSON, with the record id stamped in. */
+export const getLibraryWorkflow = async (workflowId: string): Promise<Record<string, unknown>> => {
+  const record = await apiFetchJson<WorkflowRecordDTO>(`/api/v1/workflows/i/${encodeURIComponent(workflowId)}`);
+
+  return { ...record.workflow, id: record.workflow_id };
+};
+
+export const createLibraryWorkflow = async (workflow: Record<string, unknown>): Promise<string> => {
+  const { id: _id, ...workflowWithoutId } = workflow;
+  const record = await apiFetchJson<WorkflowRecordDTO>('/api/v1/workflows/', {
+    body: JSON.stringify({ workflow: workflowWithoutId }),
+    method: 'POST',
+  });
+
+  return record.workflow_id;
+};
+
+export const updateLibraryWorkflow = async (workflowId: string, workflow: Record<string, unknown>): Promise<void> => {
+  await apiFetchJson(`/api/v1/workflows/i/${encodeURIComponent(workflowId)}`, {
+    body: JSON.stringify({ workflow: { ...workflow, id: workflowId } }),
+    method: 'PATCH',
+  });
+};
+
+export const deleteLibraryWorkflow = async (workflowId: string): Promise<void> => {
+  await apiFetch(`/api/v1/workflows/i/${encodeURIComponent(workflowId)}`, { method: 'DELETE' });
+};
+
+export const touchLibraryWorkflowOpenedAt = async (workflowId: string): Promise<void> => {
+  await apiFetch(`/api/v1/workflows/i/${encodeURIComponent(workflowId)}/opened_at`, { method: 'PUT' });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/buildGraph.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/buildGraph.test.ts
new file mode 100644
index 00000000000..84e931fc469
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/buildGraph.test.ts
@@ -0,0 +1,370 @@
+import { describe, expect, it } from 'vitest';
+
+import type { InvocationTemplatesSnapshot } from './templates';
+import type { FieldInputTemplate, InvocationTemplate, ProjectGraphState } from './types';
+
+import { compileProjectGraph, getProjectGraphReadiness } from './buildGraph';
+import {
+  buildConnectorNode,
+  buildInvocationNode,
+  buildNotesNode,
+  createProjectGraph,
+  projectGraphReducer,
+} from './document';
+
+const input = (name: string, overrides: Partial<FieldInputTemplate> = {}): FieldInputTemplate => ({
+  default: undefined,
+  description: '',
+  exclusiveMaximum: null,
+  exclusiveMinimum: null,
+  input: 'any',
+  maximum: null,
+  minimum: null,
+  multipleOf: null,
+  name,
+  options: null,
+  required: false,
+  title: name,
+  type: { batch: false, cardinality: 'SINGLE', name: 'StringField' },
+  uiChoiceLabels: null,
+  uiComponent: null,
+  uiHidden: false,
+  uiModelBase: null,
+  uiModelType: null,
+  uiOrder: null,
+  ...overrides,
+});
+
+const template = (type: string, inputs: Record<string, FieldInputTemplate>): InvocationTemplate => ({
+  category: 'test',
+  classification: 'stable',
+  description: '',
+  inputs,
+  nodePack: 'invokeai',
+  outputs: {
+    out: {
+      description: '',
+      name: 'out',
+      title: 'Out',
+      type: { batch: false, cardinality: 'SINGLE', name: 'StringField' },
+    },
+  },
+  outputType: `${type}_output`,
+  tags: [],
+  title: type,
+  type,
+  useCache: true,
+  version: '1.0.0',
+});
+
+const templates = {
+  sink: template('sink', {
+    board: input('board', { type: { batch: false, cardinality: 'SINGLE', name: 'BoardField' } }),
+    text: input('text', { required: true }),
+  }),
+  source: template('source', { value: input('value', { default: 'hello', required: true }) }),
+};
+
+const loadedSnapshot: InvocationTemplatesSnapshot = { error: null, status: 'loaded', templates };
+
+const buildDocument = (): { doc: ProjectGraphState; sinkId: string; sourceId: string } => {
+  const sourceNode = buildInvocationNode(templates.source, { x: 0, y: 0 });
+  const sinkNode = buildInvocationNode(templates.sink, { x: 10, y: 0 });
+  let doc = createProjectGraph('compile-test');
+
+  doc = projectGraphReducer(doc, { node: sourceNode, type: 'addNode' });
+  doc = projectGraphReducer(doc, { node: sinkNode, type: 'addNode' });
+  doc = projectGraphReducer(doc, { node: buildNotesNode({ x: 0, y: 100 }), type: 'addNode' });
+  doc = projectGraphReducer(doc, {
+    edge: {
+      id: 'e1',
+      source: sourceNode.id,
+      sourceHandle: 'out',
+      target: sinkNode.id,
+      targetHandle: 'text',
+      type: 'default',
+    },
+    type: 'addEdge',
+  });
+
+  return { doc, sinkId: sinkNode.id, sourceId: sourceNode.id };
+};
+
+describe('getProjectGraphReadiness', () => {
+  it('requires loaded templates and at least one node', () => {
+    const empty = createProjectGraph('empty');
+
+    expect(getProjectGraphReadiness(empty, { error: null, status: 'loading', templates: {} }).reasons[0]).toMatch(
+      /still loading/
+    );
+    expect(getProjectGraphReadiness(empty, loadedSnapshot).reasons[0]).toMatch(/no nodes/);
+  });
+
+  it('is ready when required inputs are connected or filled', () => {
+    const { doc } = buildDocument();
+
+    expect(getProjectGraphReadiness(doc, loadedSnapshot)).toEqual({ canInvoke: true, reasons: [] });
+  });
+
+  it('treats resolved connector output edges as connected required inputs', () => {
+    const sourceNode = buildInvocationNode(templates.source, { x: 0, y: 0 });
+    const sinkNode = buildInvocationNode(templates.sink, { x: 10, y: 0 });
+    const connector = buildConnectorNode({ x: 5, y: 0 });
+    let doc = createProjectGraph('connector-readiness');
+
+    doc = projectGraphReducer(doc, { node: sourceNode, type: 'addNode' });
+    doc = projectGraphReducer(doc, { node: sinkNode, type: 'addNode' });
+    doc = projectGraphReducer(doc, { node: connector, type: 'addNode' });
+    doc = projectGraphReducer(doc, {
+      edge: {
+        id: 'connector-in',
+        source: sourceNode.id,
+        sourceHandle: 'out',
+        target: connector.id,
+        targetHandle: 'in',
+        type: 'default',
+      },
+      type: 'addEdge',
+    });
+    doc = projectGraphReducer(doc, {
+      edge: {
+        id: 'connector-out',
+        source: connector.id,
+        sourceHandle: 'out',
+        target: sinkNode.id,
+        targetHandle: 'text',
+        type: 'default',
+      },
+      type: 'addEdge',
+    });
+
+    expect(getProjectGraphReadiness(doc, loadedSnapshot)).toEqual({ canInvoke: true, reasons: [] });
+  });
+
+  it('reports missing required inputs and unknown node types', () => {
+    const { doc, sourceId } = buildDocument();
+    const withEmptyValue = projectGraphReducer(doc, {
+      fieldName: 'value',
+      nodeId: sourceId,
+      type: 'setFieldValue',
+      value: '',
+    });
+
+    expect(getProjectGraphReadiness(withEmptyValue, loadedSnapshot).reasons[0]).toMatch(/missing required input/);
+
+    const unknownTemplates: InvocationTemplatesSnapshot = {
+      error: null,
+      status: 'loaded',
+      templates: { source: templates.source },
+    };
+
+    expect(getProjectGraphReadiness(doc, unknownTemplates).reasons[0]).toMatch(/Unknown node type "sink"/);
+  });
+
+  it('reports invalid required direct values', () => {
+    const constrainedTemplate = template('constrained', {
+      choice: input('choice', {
+        options: ['a', 'b'],
+        required: true,
+        type: { batch: false, cardinality: 'SINGLE', name: 'EnumField' },
+      }),
+      count: input('count', {
+        maximum: 4,
+        minimum: 1,
+        required: true,
+        type: { batch: false, cardinality: 'SINGLE', name: 'IntegerField' },
+      }),
+    });
+    const node = buildInvocationNode(constrainedTemplate, { x: 0, y: 0 });
+    let doc = createProjectGraph('invalid-values');
+
+    doc = projectGraphReducer(doc, { node, type: 'addNode' });
+    doc = projectGraphReducer(doc, { fieldName: 'choice', nodeId: node.id, type: 'setFieldValue', value: 'z' });
+    doc = projectGraphReducer(doc, { fieldName: 'count', nodeId: node.id, type: 'setFieldValue', value: 10 });
+
+    const readiness = getProjectGraphReadiness(doc, {
+      error: null,
+      status: 'loaded',
+      templates: { constrained: constrainedTemplate },
+    });
+
+    expect(readiness.canInvoke).toBe(false);
+    expect(readiness.reasons).toEqual([
+      '"constrained" has invalid input "choice".',
+      '"constrained" has invalid input "count".',
+    ]);
+  });
+
+  it('reports invalid optional direct values when they are populated', () => {
+    const constrainedTemplate = template('optional-constrained', {
+      count: input('count', {
+        maximum: 4,
+        minimum: 1,
+        required: false,
+        type: { batch: false, cardinality: 'SINGLE', name: 'IntegerField' },
+      }),
+    });
+    const node = buildInvocationNode(constrainedTemplate, { x: 0, y: 0 });
+    let doc = createProjectGraph('invalid-optional-values');
+
+    doc = projectGraphReducer(doc, { node, type: 'addNode' });
+
+    expect(
+      getProjectGraphReadiness(doc, {
+        error: null,
+        status: 'loaded',
+        templates: { 'optional-constrained': constrainedTemplate },
+      })
+    ).toEqual({ canInvoke: true, reasons: [] });
+
+    doc = projectGraphReducer(doc, { fieldName: 'count', nodeId: node.id, type: 'setFieldValue', value: 10 });
+
+    expect(
+      getProjectGraphReadiness(doc, {
+        error: null,
+        status: 'loaded',
+        templates: { 'optional-constrained': constrainedTemplate },
+      })
+    ).toEqual({ canInvoke: false, reasons: ['"optional-constrained" has invalid input "count".'] });
+  });
+
+  it('treats only explicitly externally satisfied connection inputs as ready', () => {
+    const connectionTemplate = template('connection-sink', {
+      image: input('image', {
+        input: 'connection',
+        required: true,
+        title: 'Layer image',
+        type: { batch: false, cardinality: 'SINGLE', name: 'ImageField' },
+      }),
+      mask: input('mask', {
+        input: 'connection',
+        required: true,
+        title: 'Mask image',
+        type: { batch: false, cardinality: 'SINGLE', name: 'ImageField' },
+      }),
+    });
+    const node = buildInvocationNode(connectionTemplate, { x: 0, y: 0 });
+    const doc = { ...createProjectGraph('external-input'), nodes: [{ ...node, id: 'sink' }] };
+    const snapshot: InvocationTemplatesSnapshot = {
+      error: null,
+      status: 'loaded',
+      templates: { 'connection-sink': connectionTemplate },
+    };
+
+    expect(getProjectGraphReadiness(doc, snapshot, { externallySatisfiedInputs: new Set(['sink:image']) })).toEqual({
+      canInvoke: false,
+      reasons: ['"connection-sink" is missing a connection for "Mask image".'],
+    });
+    expect(
+      getProjectGraphReadiness(doc, snapshot, {
+        externallySatisfiedInputs: new Set(['sink:image', 'sink:mask']),
+      })
+    ).toEqual({ canInvoke: true, reasons: [] });
+  });
+
+  it('does not let external satisfaction bypass a required direct value', () => {
+    const directTemplate = template('direct-sink', {
+      image: input('image', {
+        input: 'direct',
+        required: true,
+        title: 'Layer image',
+        type: { batch: false, cardinality: 'SINGLE', name: 'ImageField' },
+      }),
+    });
+    const node = buildInvocationNode(directTemplate, { x: 0, y: 0 });
+    const doc = { ...createProjectGraph('external-direct'), nodes: [{ ...node, id: 'sink' }] };
+    const snapshot: InvocationTemplatesSnapshot = {
+      error: null,
+      status: 'loaded',
+      templates: { 'direct-sink': directTemplate },
+    };
+
+    expect(getProjectGraphReadiness(doc, snapshot, { externallySatisfiedInputs: new Set(['sink:image']) })).toEqual({
+      canInvoke: false,
+      reasons: ['"direct-sink" is missing required input "Layer image".'],
+    });
+  });
+});
+
+describe('compileProjectGraph', () => {
+  it('compiles nodes and edges, omitting notes nodes and connected direct values', () => {
+    const { doc, sinkId, sourceId } = buildDocument();
+    const withStaleValue = projectGraphReducer(doc, {
+      fieldName: 'text',
+      nodeId: sinkId,
+      type: 'setFieldValue',
+      value: 'stale direct value',
+    });
+    const compiled = compileProjectGraph(withStaleValue, templates);
+    const backendGraph = compiled.backendGraph;
+
+    expect(backendGraph).toBeDefined();
+    expect(Object.keys(backendGraph?.nodes ?? {}).sort()).toEqual([sinkId, sourceId].sort());
+    expect(backendGraph?.nodes[sourceId]).toMatchObject({ type: 'source', use_cache: true, value: 'hello' });
+    // The connected input's direct value must not be sent alongside the edge.
+    expect(backendGraph?.nodes[sinkId]).not.toHaveProperty('text');
+    expect(backendGraph?.edges).toEqual([
+      { destination: { field: 'text', node_id: sinkId }, source: { field: 'out', node_id: sourceId } },
+    ]);
+  });
+
+  it('omits auto/none board sentinels and keeps explicit boards', () => {
+    const { doc, sinkId } = buildDocument();
+    const withAutoBoard = projectGraphReducer(doc, {
+      fieldName: 'board',
+      nodeId: sinkId,
+      type: 'setFieldValue',
+      value: 'auto',
+    });
+
+    expect(compileProjectGraph(withAutoBoard, templates).backendGraph?.nodes[sinkId]).not.toHaveProperty('board');
+
+    const withExplicitBoard = projectGraphReducer(doc, {
+      fieldName: 'board',
+      nodeId: sinkId,
+      type: 'setFieldValue',
+      value: { board_id: 'board-1' },
+    });
+
+    expect(compileProjectGraph(withExplicitBoard, templates).backendGraph?.nodes[sinkId]).toMatchObject({
+      board: { board_id: 'board-1' },
+    });
+  });
+
+  it('resolves connector chains into executable backend edges', () => {
+    const sourceNode = buildInvocationNode(templates.source, { x: 0, y: 0 });
+    const sinkNode = buildInvocationNode(templates.sink, { x: 10, y: 0 });
+    const connector = buildConnectorNode({ x: 5, y: 0 });
+    let doc = createProjectGraph('connector-compile');
+
+    doc = projectGraphReducer(doc, { node: sourceNode, type: 'addNode' });
+    doc = projectGraphReducer(doc, { node: sinkNode, type: 'addNode' });
+    doc = projectGraphReducer(doc, { node: connector, type: 'addNode' });
+    doc = projectGraphReducer(doc, {
+      edge: {
+        id: 'connector-in',
+        source: sourceNode.id,
+        sourceHandle: 'out',
+        target: connector.id,
+        targetHandle: 'in',
+        type: 'default',
+      },
+      type: 'addEdge',
+    });
+    doc = projectGraphReducer(doc, {
+      edge: {
+        id: 'connector-out',
+        source: connector.id,
+        sourceHandle: 'out',
+        target: sinkNode.id,
+        targetHandle: 'text',
+        type: 'default',
+      },
+      type: 'addEdge',
+    });
+
+    expect(compileProjectGraph(doc, templates).backendGraph?.edges).toEqual([
+      { destination: { field: 'text', node_id: sinkNode.id }, source: { field: 'out', node_id: sourceNode.id } },
+    ]);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/buildGraph.ts b/invokeai/frontend/webv2/src/workbench/workflows/buildGraph.ts
new file mode 100644
index 00000000000..7da1cbeb7f9
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/buildGraph.ts
@@ -0,0 +1,232 @@
+import type { BackendGraphContract, GraphContract } from '@workbench/types';
+
+import type { InvocationTemplatesSnapshot } from './templates';
+import type { FieldInputTemplate, InvocationTemplates, ProjectGraphState, WorkflowInvocationNode } from './types';
+
+import { getResolvedWorkflowEdgesIndexed } from './connectors';
+import { createWorkflowId } from './document';
+import { getWorkflowFieldInvalidReason } from './fields';
+import { createWorkflowGraphIndex } from './graphIndex';
+import { isInvocationNode } from './types';
+import { hasAnyCycle } from './validation';
+
+/**
+ * Compiles the project graph document into the immutable, queue-facing
+ * `GraphContract`. Ported from the legacy `buildNodesGraph`, with connector
+ * resolution and without batch handling (batch/generator nodes are rejected by
+ * readiness until batching lands).
+ */
+
+/** Client-resolved batch/generator nodes from the legacy editor; executing them server-side is meaningless. */
+const UNSUPPORTED_NODE_TYPES = new Set([
+  'float_batch',
+  'float_generator',
+  'image_batch',
+  'image_generator',
+  'integer_batch',
+  'integer_generator',
+  'string_batch',
+  'string_generator',
+]);
+
+export const isExecutableInvocationType = (type: string): boolean => !UNSUPPORTED_NODE_TYPES.has(type);
+
+const getExecutableNodes = (document: ProjectGraphState): WorkflowInvocationNode[] =>
+  document.nodes.filter(isInvocationNode);
+
+const isEmptyValue = (value: unknown): boolean =>
+  value === undefined || value === null || (typeof value === 'string' && value.trim() === '');
+
+const getNodeDisplayName = (node: WorkflowInvocationNode, templates: InvocationTemplates): string =>
+  node.data.label || templates[node.data.type]?.title || node.data.type;
+
+/**
+ * Translates a board field value to the backend shape: `auto` and `none`
+ * sentinels are omitted so the backend applies its default board behavior.
+ */
+const toBoardGraphValue = (value: unknown): unknown => {
+  if (value === 'auto' || value === 'none' || isEmptyValue(value)) {
+    return undefined;
+  }
+
+  return value;
+};
+
+export interface ProjectGraphReadiness {
+  canInvoke: boolean;
+  reasons: string[];
+}
+
+export interface ProjectGraphReadinessOptions {
+  /** Required connection inputs supplied by an ephemeral caller after document compilation. */
+  externallySatisfiedInputs?: ReadonlySet<string>;
+}
+
+export const getProjectGraphReadiness = (
+  document: ProjectGraphState,
+  templatesSnapshot: InvocationTemplatesSnapshot,
+  options: ProjectGraphReadinessOptions = {}
+): ProjectGraphReadiness => {
+  if (templatesSnapshot.status === 'error') {
+    return { canInvoke: false, reasons: ['Node definitions failed to load from the backend.'] };
+  }
+
+  if (templatesSnapshot.status !== 'loaded') {
+    return { canInvoke: false, reasons: ['Node definitions are still loading.'] };
+  }
+
+  const templates = templatesSnapshot.templates;
+  const executableNodes = getExecutableNodes(document);
+  const index = createWorkflowGraphIndex(document.nodes, document.edges);
+
+  if (executableNodes.length === 0) {
+    return { canInvoke: false, reasons: ['The project graph has no nodes. Add nodes in the Workflow view.'] };
+  }
+
+  const reasons: string[] = [];
+  const connectedInputs = new Set(
+    getResolvedWorkflowEdgesIndexed(document.edges, index, templates)
+      .filter((edge) => executableNodes.some((node) => node.id === edge.target))
+      .map((edge) => `${edge.target}:${edge.targetHandle}`)
+  );
+
+  for (const node of executableNodes) {
+    const template = templates[node.data.type];
+
+    if (!template) {
+      reasons.push(`Unknown node type "${node.data.type}".`);
+      continue;
+    }
+
+    if (!isExecutableInvocationType(node.data.type)) {
+      reasons.push(`Batch/generator node "${getNodeDisplayName(node, templates)}" is not supported yet.`);
+      continue;
+    }
+
+    for (const inputTemplate of Object.values(template.inputs)) {
+      if (connectedInputs.has(`${node.id}:${inputTemplate.name}`)) {
+        continue;
+      }
+
+      if (inputTemplate.input === 'connection') {
+        if (inputTemplate.required && !options.externallySatisfiedInputs?.has(`${node.id}:${inputTemplate.name}`)) {
+          reasons.push(
+            `"${getNodeDisplayName(node, templates)}" is missing a connection for "${inputTemplate.title}".`
+          );
+        }
+        continue;
+      }
+
+      const invalidReason = getWorkflowFieldInvalidReason({
+        isConnected: false,
+        template: inputTemplate,
+        value: node.data.inputs[inputTemplate.name]?.value,
+      });
+
+      if (inputTemplate.required && isEmptyValue(node.data.inputs[inputTemplate.name]?.value)) {
+        reasons.push(`"${getNodeDisplayName(node, templates)}" is missing required input "${inputTemplate.title}".`);
+      } else if (invalidReason) {
+        reasons.push(`"${getNodeDisplayName(node, templates)}" has invalid input "${inputTemplate.title}".`);
+      }
+    }
+  }
+
+  if (hasAnyCycle(document.nodes, document.edges)) {
+    reasons.push('The project graph contains a cycle.');
+  }
+
+  return { canInvoke: reasons.length === 0, reasons };
+};
+
+const toGraphInputValue = (inputTemplate: FieldInputTemplate, value: unknown): unknown => {
+  if (inputTemplate.type.name === 'BoardField') {
+    return toBoardGraphValue(value);
+  }
+
+  return value;
+};
+
+/** Compiles the document into a `GraphContract` carrying the executable backend graph. */
+export const compileProjectGraph = (document: ProjectGraphState, templates: InvocationTemplates): GraphContract => {
+  const executableNodes = getExecutableNodes(document).filter((node) => templates[node.data.type] !== undefined);
+  const executableNodeIds = new Set(executableNodes.map((node) => node.id));
+  const backendGraph: BackendGraphContract = { edges: [], id: createWorkflowId('workflow-graph'), nodes: {} };
+  const index = createWorkflowGraphIndex(document.nodes, document.edges);
+  const resolvedEdges = getResolvedWorkflowEdgesIndexed(document.edges, index, templates);
+
+  for (const node of executableNodes) {
+    const template = templates[node.data.type] as NonNullable<(typeof templates)[string]>;
+    const graphNode: Record<string, unknown> = {
+      id: node.id,
+      is_intermediate: node.data.isIntermediate,
+      type: node.data.type,
+      use_cache: node.data.useCache,
+    };
+
+    for (const instance of Object.values(node.data.inputs)) {
+      const inputTemplate = template.inputs[instance.name];
+
+      if (!inputTemplate || instance.value === undefined) {
+        continue;
+      }
+
+      const value = toGraphInputValue(inputTemplate, instance.value);
+
+      if (value !== undefined) {
+        graphNode[instance.name] = value;
+      }
+    }
+
+    backendGraph.nodes[node.id] = graphNode as BackendGraphContract['nodes'][string];
+  }
+
+  const seenEdgeKeys = new Set<string>();
+
+  for (const edge of resolvedEdges) {
+    if (!executableNodeIds.has(edge.source) || !executableNodeIds.has(edge.target)) {
+      continue;
+    }
+
+    const key = `${edge.source}:${edge.sourceHandle}->${edge.target}:${edge.targetHandle}`;
+
+    if (seenEdgeKeys.has(key)) {
+      continue;
+    }
+
+    seenEdgeKeys.add(key);
+    backendGraph.edges.push({
+      destination: { field: edge.targetHandle, node_id: edge.target },
+      source: { field: edge.sourceHandle, node_id: edge.source },
+    });
+
+    // A connected input always wins over a stale direct value; sending both
+    // would let pydantic reject the node on the ignored direct value.
+    const targetNode = backendGraph.nodes[edge.target];
+
+    if (targetNode) {
+      delete targetNode[edge.targetHandle];
+    }
+  }
+
+  return {
+    backendGraph,
+    edges: resolvedEdges
+      .filter((edge) => executableNodeIds.has(edge.source) && executableNodeIds.has(edge.target))
+      .map((edge) => ({
+        id: edge.id,
+        sourceField: edge.sourceHandle,
+        sourceNodeId: edge.source,
+        targetField: edge.targetHandle,
+        targetNodeId: edge.target,
+      })),
+    id: backendGraph.id,
+    label: document.name || 'Workflow',
+    nodes: executableNodes.map((node) => ({
+      id: node.id,
+      inputs: Object.fromEntries(Object.values(node.data.inputs).map((instance) => [instance.name, instance.value])),
+      type: node.data.type,
+    })),
+    updatedAt: new Date().toISOString(),
+    version: 1,
+  };
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/connectorHandles.ts b/invokeai/frontend/webv2/src/workbench/workflows/connectorHandles.ts
new file mode 100644
index 00000000000..b03e2347bb6
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/connectorHandles.ts
@@ -0,0 +1,2 @@
+export const CONNECTOR_INPUT_HANDLE = 'in';
+export const CONNECTOR_OUTPUT_HANDLE = 'out';
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/connectors.ts b/invokeai/frontend/webv2/src/workbench/workflows/connectors.ts
new file mode 100644
index 00000000000..c542800e2e0
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/connectors.ts
@@ -0,0 +1,250 @@
+import type { FieldType, InvocationTemplates, WorkflowEdge, WorkflowNode } from './types';
+
+import { CONNECTOR_INPUT_HANDLE, CONNECTOR_OUTPUT_HANDLE } from './connectorHandles';
+import { createWorkflowGraphIndex, type WorkflowGraphIndex } from './graphIndex';
+import { isConnectorNode, isInvocationNode } from './types';
+
+export { CONNECTOR_INPUT_HANDLE, CONNECTOR_OUTPUT_HANDLE } from './connectorHandles';
+
+export interface ResolvedConnectorSource {
+  fieldName: string;
+  nodeId: string;
+  type: FieldType | null;
+}
+
+export interface ResolvedConnectorTarget {
+  fieldName: string;
+  nodeId: string;
+  type: FieldType | null;
+}
+
+export interface ResolvedWorkflowEdge extends WorkflowEdge {
+  source: string;
+  sourceHandle: string;
+}
+
+export const getConnectorInputEdge = (connectorId: string, edges: WorkflowEdge[]): WorkflowEdge | undefined =>
+  edges.find(
+    (edge) => edge.type === 'default' && edge.target === connectorId && edge.targetHandle === CONNECTOR_INPUT_HANDLE
+  );
+
+export const getConnectorInputEdgeIndexed = (
+  connectorId: string,
+  index: WorkflowGraphIndex
+): WorkflowEdge | undefined => index.connectorInputById.get(connectorId);
+
+export const getConnectorOutputEdges = (connectorId: string, edges: WorkflowEdge[]): WorkflowEdge[] =>
+  edges.filter(
+    (edge) => edge.type === 'default' && edge.source === connectorId && edge.sourceHandle === CONNECTOR_OUTPUT_HANDLE
+  );
+
+export const getConnectorOutputEdgesIndexed = (connectorId: string, index: WorkflowGraphIndex): WorkflowEdge[] =>
+  index.connectorOutputsById.get(connectorId) ?? [];
+
+export const resolveConnectorSource = (
+  connectorId: string,
+  nodes: WorkflowNode[],
+  edges: WorkflowEdge[],
+  templates?: InvocationTemplates
+): ResolvedConnectorSource | null =>
+  resolveConnectorSourceIndexed(connectorId, createWorkflowGraphIndex(nodes, edges), templates);
+
+export const resolveConnectorSourceIndexed = (
+  connectorId: string,
+  index: WorkflowGraphIndex,
+  templates?: InvocationTemplates
+): ResolvedConnectorSource | null => resolveConnectorSourceWithCache(connectorId, index, templates, new Map());
+
+const resolveConnectorSourceWithCache = (
+  connectorId: string,
+  index: WorkflowGraphIndex,
+  templates: InvocationTemplates | undefined,
+  cache: Map<string, ResolvedConnectorSource | null>
+): ResolvedConnectorSource | null => {
+  const visited = new Set<string>();
+
+  const resolve = (nodeId: string): ResolvedConnectorSource | null => {
+    if (cache.has(nodeId)) {
+      return cache.get(nodeId) ?? null;
+    }
+
+    if (visited.has(nodeId)) {
+      return null;
+    }
+
+    visited.add(nodeId);
+
+    const inboundEdge = getConnectorInputEdgeIndexed(nodeId, index);
+
+    if (!inboundEdge) {
+      cache.set(nodeId, null);
+      return null;
+    }
+
+    const sourceNode = index.nodesById.get(inboundEdge.source);
+
+    if (!sourceNode) {
+      cache.set(nodeId, null);
+      return null;
+    }
+
+    if (isInvocationNode(sourceNode)) {
+      const source = {
+        fieldName: inboundEdge.sourceHandle,
+        nodeId: sourceNode.id,
+        type: templates?.[sourceNode.data.type]?.outputs[inboundEdge.sourceHandle]?.type ?? null,
+      };
+
+      cache.set(nodeId, source);
+      return source;
+    }
+
+    if (isConnectorNode(sourceNode) && inboundEdge.sourceHandle === CONNECTOR_OUTPUT_HANDLE) {
+      const source = resolve(sourceNode.id);
+
+      cache.set(nodeId, source);
+      return source;
+    }
+
+    cache.set(nodeId, null);
+    return null;
+  };
+
+  return resolve(connectorId);
+};
+
+export const resolveConnectorTarget = (
+  connectorId: string,
+  nodes: WorkflowNode[],
+  edges: WorkflowEdge[],
+  templates?: InvocationTemplates
+): ResolvedConnectorTarget | null => {
+  return resolveConnectorTargets(connectorId, nodes, edges, templates)[0] ?? null;
+};
+
+export const resolveConnectorTargets = (
+  connectorId: string,
+  nodes: WorkflowNode[],
+  edges: WorkflowEdge[],
+  templates?: InvocationTemplates
+): ResolvedConnectorTarget[] =>
+  resolveConnectorTargetsIndexed(connectorId, createWorkflowGraphIndex(nodes, edges), templates);
+
+export const resolveConnectorTargetsIndexed = (
+  connectorId: string,
+  index: WorkflowGraphIndex,
+  templates?: InvocationTemplates
+): ResolvedConnectorTarget[] => resolveConnectorTargetsWithCache(connectorId, index, templates, new Map());
+
+const resolveConnectorTargetsWithCache = (
+  connectorId: string,
+  index: WorkflowGraphIndex,
+  templates: InvocationTemplates | undefined,
+  cache: Map<string, ResolvedConnectorTarget[]>
+): ResolvedConnectorTarget[] => {
+  const visited = new Set<string>();
+
+  const resolve = (nodeId: string): ResolvedConnectorTarget[] => {
+    const cached = cache.get(nodeId);
+
+    if (cached) {
+      return cached;
+    }
+
+    if (visited.has(nodeId)) {
+      return [];
+    }
+
+    visited.add(nodeId);
+
+    const targets: ResolvedConnectorTarget[] = [];
+
+    for (const outboundEdge of getConnectorOutputEdgesIndexed(nodeId, index)) {
+      const targetNode = index.nodesById.get(outboundEdge.target);
+
+      if (!targetNode) {
+        continue;
+      }
+
+      if (isInvocationNode(targetNode)) {
+        targets.push({
+          fieldName: outboundEdge.targetHandle,
+          nodeId: targetNode.id,
+          type: templates?.[targetNode.data.type]?.inputs[outboundEdge.targetHandle]?.type ?? null,
+        });
+        continue;
+      }
+
+      if (isConnectorNode(targetNode) && outboundEdge.targetHandle === CONNECTOR_INPUT_HANDLE) {
+        targets.push(...resolve(targetNode.id));
+      }
+    }
+
+    cache.set(nodeId, targets);
+    return targets;
+  };
+
+  return resolve(connectorId);
+};
+
+export const resolveWorkflowEdgeSource = (
+  edge: WorkflowEdge,
+  nodes: WorkflowNode[],
+  edges: WorkflowEdge[],
+  templates?: InvocationTemplates
+): ResolvedConnectorSource | null =>
+  resolveWorkflowEdgeSourceIndexed(edge, createWorkflowGraphIndex(nodes, edges), templates);
+
+export const resolveWorkflowEdgeSourceIndexed = (
+  edge: WorkflowEdge,
+  index: WorkflowGraphIndex,
+  templates?: InvocationTemplates,
+  connectorSourceCache = new Map<string, ResolvedConnectorSource | null>()
+): ResolvedConnectorSource | null => {
+  const sourceNode = index.nodesById.get(edge.source);
+
+  if (!sourceNode) {
+    return null;
+  }
+
+  if (isInvocationNode(sourceNode)) {
+    return {
+      fieldName: edge.sourceHandle,
+      nodeId: sourceNode.id,
+      type: templates?.[sourceNode.data.type]?.outputs[edge.sourceHandle]?.type ?? null,
+    };
+  }
+
+  if (isConnectorNode(sourceNode) && edge.sourceHandle === CONNECTOR_OUTPUT_HANDLE) {
+    return resolveConnectorSourceWithCache(sourceNode.id, index, templates, connectorSourceCache);
+  }
+
+  return null;
+};
+
+export const getResolvedWorkflowEdges = (
+  nodes: WorkflowNode[],
+  edges: WorkflowEdge[],
+  templates?: InvocationTemplates
+): ResolvedWorkflowEdge[] => getResolvedWorkflowEdgesIndexed(edges, createWorkflowGraphIndex(nodes, edges), templates);
+
+export const getResolvedWorkflowEdgesIndexed = (
+  edges: WorkflowEdge[],
+  index: WorkflowGraphIndex,
+  templates?: InvocationTemplates
+): ResolvedWorkflowEdge[] => {
+  const resolved: ResolvedWorkflowEdge[] = [];
+  const connectorSourceCache = new Map<string, ResolvedConnectorSource | null>();
+
+  for (const edge of edges) {
+    const source = resolveWorkflowEdgeSourceIndexed(edge, index, templates, connectorSourceCache);
+
+    if (!source) {
+      continue;
+    }
+
+    resolved.push({ ...edge, source: source.nodeId, sourceHandle: source.fieldName });
+  }
+
+  return resolved;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/document.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/document.test.ts
new file mode 100644
index 00000000000..6f6f30edbea
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/document.test.ts
@@ -0,0 +1,306 @@
+import { describe, expect, it } from 'vitest';
+
+import type { InvocationTemplate, ProjectGraphState, WorkflowEdge } from './types';
+
+import {
+  buildInvocationNode,
+  createProjectGraph,
+  getFormChildren,
+  isFieldExposed,
+  normalizeProjectGraph,
+  projectGraphReducer,
+} from './document';
+
+const template: InvocationTemplate = {
+  category: 'math',
+  classification: 'stable',
+  description: '',
+  inputs: {
+    a: {
+      default: 1,
+      description: '',
+      exclusiveMaximum: null,
+      exclusiveMinimum: null,
+      input: 'any',
+      maximum: null,
+      minimum: null,
+      multipleOf: null,
+      name: 'a',
+      options: null,
+      required: false,
+      title: 'A',
+      type: { batch: false, cardinality: 'SINGLE', name: 'IntegerField' },
+      uiChoiceLabels: null,
+      uiComponent: null,
+      uiHidden: false,
+      uiModelBase: null,
+      uiModelType: null,
+      uiOrder: null,
+    },
+  },
+  nodePack: 'invokeai',
+  outputs: {
+    value: {
+      description: '',
+      name: 'value',
+      title: 'Value',
+      type: { batch: false, cardinality: 'SINGLE', name: 'IntegerField' },
+    },
+  },
+  outputType: 'integer_output',
+  tags: [],
+  title: 'Add',
+  type: 'add',
+  useCache: true,
+  version: '1.0.0',
+};
+
+const createDocWithNodes = (): { doc: ProjectGraphState; nodeAId: string; nodeBId: string } => {
+  const nodeA = buildInvocationNode(template, { x: 0, y: 0 });
+  const nodeB = buildInvocationNode(template, { x: 100, y: 0 });
+  let doc = createProjectGraph('test-graph');
+
+  doc = projectGraphReducer(doc, { node: nodeA, type: 'addNode' });
+  doc = projectGraphReducer(doc, { node: nodeB, type: 'addNode' });
+
+  return { doc, nodeAId: nodeA.id, nodeBId: nodeB.id };
+};
+
+const createEdge = (source: string, target: string): WorkflowEdge => ({
+  id: `edge-${source}-${target}`,
+  source,
+  sourceHandle: 'value',
+  target,
+  targetHandle: 'a',
+  type: 'default',
+});
+
+describe('projectGraphReducer', () => {
+  it('builds nodes from templates with default input values', () => {
+    const node = buildInvocationNode(template, { x: 5, y: 6 });
+
+    expect(node.data.inputs.a?.value).toBe(1);
+    expect(node.data.useCache).toBe(true);
+    expect(node.position).toEqual({ x: 5, y: 6 });
+  });
+
+  it('removing nodes drops their edges and exposed form fields', () => {
+    const { doc, nodeAId, nodeBId } = createDocWithNodes();
+    let next = projectGraphReducer(doc, { edge: createEdge(nodeAId, nodeBId), type: 'addEdge' });
+
+    next = projectGraphReducer(next, { fieldIdentifier: { fieldName: 'a', nodeId: nodeBId }, type: 'exposeField' });
+
+    expect(next.edges).toHaveLength(1);
+    expect(isFieldExposed(next.form, { fieldName: 'a', nodeId: nodeBId })).toBe(true);
+
+    next = projectGraphReducer(next, { nodeIds: [nodeBId], type: 'removeNodes' });
+
+    expect(next.nodes.map((node) => node.id)).toEqual([nodeAId]);
+    expect(next.edges).toEqual([]);
+    expect(isFieldExposed(next.form, { fieldName: 'a', nodeId: nodeBId })).toBe(false);
+  });
+
+  it('adds pasted nodes and their internal edges in one action', () => {
+    const { doc, nodeAId, nodeBId } = createDocWithNodes();
+    const pastedA = buildInvocationNode(template, { x: 32, y: 32 });
+    const pastedB = buildInvocationNode(template, { x: 132, y: 32 });
+    const next = projectGraphReducer(doc, {
+      edges: [createEdge(pastedA.id, pastedB.id)],
+      nodes: [pastedA, pastedB],
+      type: 'addGraphElements',
+    });
+
+    expect(next.nodes.map((node) => node.id)).toEqual([nodeAId, nodeBId, pastedA.id, pastedB.id]);
+    expect(next.edges).toHaveLength(1);
+  });
+
+  it('adds a new node connected to an existing node in one action', () => {
+    const { doc, nodeAId, nodeBId } = createDocWithNodes();
+    const insertedNode = buildInvocationNode(template, { x: 200, y: 0 });
+    const next = projectGraphReducer(doc, {
+      edge: createEdge(nodeAId, insertedNode.id),
+      node: insertedNode,
+      type: 'addNodeAndEdge',
+    });
+
+    expect(next.nodes.map((node) => node.id)).toEqual([nodeAId, nodeBId, insertedNode.id]);
+    expect(next.edges).toEqual([createEdge(nodeAId, insertedNode.id)]);
+  });
+
+  it('addGraphElements drops colliding node ids and their edges', () => {
+    const { doc, nodeAId, nodeBId } = createDocWithNodes();
+    const existingNode = doc.nodes[0];
+    const freshNode = buildInvocationNode(template, { x: 64, y: 64 });
+    const next = projectGraphReducer(doc, {
+      edges: [createEdge(nodeAId, freshNode.id)],
+      nodes: [existingNode!, freshNode],
+      type: 'addGraphElements',
+    });
+
+    expect(next.nodes.map((node) => node.id)).toEqual([nodeAId, nodeBId, freshNode.id]);
+    // The edge referenced a dropped duplicate, so it is dropped too.
+    expect(next.edges).toEqual([]);
+  });
+
+  it('connecting an already-connected input replaces the existing edge', () => {
+    const { doc, nodeAId, nodeBId } = createDocWithNodes();
+    let next = projectGraphReducer(doc, { edge: createEdge(nodeAId, nodeBId), type: 'addEdge' });
+    const replacement = { ...createEdge(nodeAId, nodeBId), id: 'edge-replacement' };
+
+    next = projectGraphReducer(next, { edge: replacement, type: 'addEdge' });
+
+    expect(next.edges).toHaveLength(1);
+    expect(next.edges[0]?.id).toBe('edge-replacement');
+  });
+
+  it('sets field values without disturbing other inputs', () => {
+    const { doc, nodeAId } = createDocWithNodes();
+    const next = projectGraphReducer(doc, { fieldName: 'a', nodeId: nodeAId, type: 'setFieldValue', value: 42 });
+    const node = next.nodes.find((candidate) => candidate.id === nodeAId);
+
+    expect(node?.type === 'invocation' && node.data.inputs.a?.value).toBe(42);
+  });
+
+  it('sets invocation cache preference', () => {
+    const { doc, nodeAId } = createDocWithNodes();
+    const next = projectGraphReducer(doc, { nodeId: nodeAId, type: 'setNodeUseCache', useCache: false });
+    const node = next.nodes.find((candidate) => candidate.id === nodeAId);
+
+    expect(node?.type === 'invocation' && node.data.useCache).toBe(false);
+  });
+
+  it('sets and clears field description overrides', () => {
+    const { doc, nodeAId } = createDocWithNodes();
+    let next = projectGraphReducer(doc, {
+      description: 'Custom help text',
+      fieldName: 'a',
+      nodeId: nodeAId,
+      type: 'setFieldDescription',
+    });
+    const getInstance = (document: typeof next) => {
+      const node = document.nodes.find((candidate) => candidate.id === nodeAId);
+
+      return node?.type === 'invocation' ? node.data.inputs.a : undefined;
+    };
+
+    expect(getInstance(next)?.description).toBe('Custom help text');
+
+    next = projectGraphReducer(next, { description: '', fieldName: 'a', nodeId: nodeAId, type: 'setFieldDescription' });
+
+    expect(getInstance(next)?.description).toBeUndefined();
+  });
+
+  it('exposing a field twice is a no-op, and form elements reorder', () => {
+    const { doc, nodeAId, nodeBId } = createDocWithNodes();
+    let next = projectGraphReducer(doc, { fieldIdentifier: { fieldName: 'a', nodeId: nodeAId }, type: 'exposeField' });
+
+    next = projectGraphReducer(next, { fieldIdentifier: { fieldName: 'a', nodeId: nodeAId }, type: 'exposeField' });
+    next = projectGraphReducer(next, { fieldIdentifier: { fieldName: 'a', nodeId: nodeBId }, type: 'exposeField' });
+
+    const childrenBefore = getFormChildren(next.form).map((element) => element.id);
+
+    expect(childrenBefore).toHaveLength(2);
+
+    const lastElementId = childrenBefore[1] as string;
+
+    next = projectGraphReducer(next, { direction: -1, elementId: lastElementId, type: 'moveFormElement' });
+
+    expect(getFormChildren(next.form).map((element) => element.id)).toEqual([lastElementId, childrenBefore[0]]);
+  });
+
+  it('reparents form elements via moveFormElementTo with index adjustment and cycle guards', () => {
+    const { doc, nodeAId, nodeBId } = createDocWithNodes();
+    let next = projectGraphReducer(doc, { fieldIdentifier: { fieldName: 'a', nodeId: nodeAId }, type: 'exposeField' });
+
+    next = projectGraphReducer(next, { fieldIdentifier: { fieldName: 'a', nodeId: nodeBId }, type: 'exposeField' });
+    next = projectGraphReducer(next, { elementType: 'container', layout: 'row', type: 'addFormElement' });
+
+    const rootId = next.form.rootElementId;
+    const [fieldA, fieldB, container] = getFormChildren(next.form);
+
+    expect(container?.type).toBe('container');
+
+    // Reorder within the root: move fieldA after fieldB (index adjusts for removal).
+    next = projectGraphReducer(next, {
+      elementId: fieldA?.id ?? '',
+      index: 2,
+      parentId: rootId,
+      type: 'moveFormElementTo',
+    });
+
+    expect(getFormChildren(next.form).map((element) => element.id)).toEqual([fieldB?.id, fieldA?.id, container?.id]);
+
+    // Reparent fieldB into the container.
+    next = projectGraphReducer(next, {
+      elementId: fieldB?.id ?? '',
+      index: 0,
+      parentId: container?.id ?? '',
+      type: 'moveFormElementTo',
+    });
+
+    const containerElement = next.form.elements[container?.id ?? ''];
+
+    expect(containerElement?.type === 'container' && containerElement.data.children).toEqual([fieldB?.id]);
+    expect(next.form.elements[fieldB?.id ?? '']?.parentId).toBe(container?.id);
+
+    // A container cannot be dropped into its own subtree.
+    const guarded = projectGraphReducer(next, {
+      elementId: container?.id ?? '',
+      index: 0,
+      parentId: container?.id ?? '',
+      type: 'moveFormElementTo',
+    });
+
+    expect(guarded).toBe(next);
+  });
+
+  it('toggles container layout and node-field descriptions', () => {
+    const { doc, nodeAId } = createDocWithNodes();
+    let next = projectGraphReducer(doc, { elementType: 'container', layout: 'column', type: 'addFormElement' });
+
+    next = projectGraphReducer(next, { fieldIdentifier: { fieldName: 'a', nodeId: nodeAId }, type: 'exposeField' });
+
+    const [container, field] = getFormChildren(next.form);
+
+    next = projectGraphReducer(next, { elementId: container?.id ?? '', layout: 'row', type: 'setContainerLayout' });
+
+    const updatedContainer = next.form.elements[container?.id ?? ''];
+
+    expect(updatedContainer?.type === 'container' && updatedContainer.data.layout).toBe('row');
+
+    next = projectGraphReducer(next, {
+      elementId: field?.id ?? '',
+      showDescription: true,
+      type: 'setNodeFieldShowDescription',
+    });
+
+    const updatedField = next.form.elements[field?.id ?? ''];
+
+    expect(updatedField?.type === 'node-field' && updatedField.data.showDescription).toBe(true);
+  });
+
+  it('updates metadata via patch', () => {
+    const { doc } = createDocWithNodes();
+    const next = projectGraphReducer(doc, { patch: { author: 'josh', name: 'My Flow' }, type: 'setMetadata' });
+
+    expect(next.name).toBe('My Flow');
+    expect(next.author).toBe('josh');
+  });
+});
+
+describe('normalizeProjectGraph', () => {
+  it('passes through current documents', () => {
+    const doc = createProjectGraph('keep-me');
+
+    expect(normalizeProjectGraph(doc)).toBe(doc);
+  });
+
+  it('replaces the Phase-1 placeholder graph with an empty document, preserving the id', () => {
+    const normalized = normalizeProjectGraph({ edges: [], id: 'legacy-id', label: 'Old', nodes: [], version: 1 });
+
+    expect(normalized.version).toBe(2);
+    expect(normalized.id).toBe('legacy-id');
+    expect(normalized.nodes).toEqual([]);
+    expect(normalized.form.elements[normalized.form.rootElementId]?.type).toBe('container');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/document.ts b/invokeai/frontend/webv2/src/workbench/workflows/document.ts
new file mode 100644
index 00000000000..ff2b3b2112e
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/document.ts
@@ -0,0 +1,652 @@
+import type {
+  ContainerFormElement,
+  FieldIdentifier,
+  InvocationTemplate,
+  ProjectGraphState,
+  WorkflowCurrentImageNode,
+  WorkflowConnectorNode,
+  WorkflowEdge,
+  WorkflowFieldInstance,
+  WorkflowForm,
+  WorkflowFormElement,
+  WorkflowInvocationNode,
+  WorkflowMetadata,
+  WorkflowNode,
+  WorkflowNotesNode,
+  XYPosition,
+} from './types';
+
+import { isInvocationNode, isNotesNode } from './types';
+
+/**
+ * Pure operations on the project graph document. The workbench reducer
+ * delegates all workflow edits to `projectGraphReducer` so the document logic
+ * stays testable and `workbenchState.ts` only grows one action case.
+ */
+
+const now = (): string => new Date().toISOString();
+
+export const createWorkflowId = (prefix: string): string =>
+  `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+export const createWorkflowForm = (): WorkflowForm => {
+  const rootElementId = createWorkflowId('container');
+  const root: ContainerFormElement = {
+    data: { children: [], layout: 'column' },
+    id: rootElementId,
+    type: 'container',
+  };
+
+  return { elements: { [rootElementId]: root }, rootElementId };
+};
+
+export const createProjectGraph = (id: string, name = 'Untitled Workflow'): ProjectGraphState => ({
+  author: '',
+  contact: '',
+  description: '',
+  edges: [],
+  form: createWorkflowForm(),
+  id,
+  name,
+  nodes: [],
+  notes: '',
+  tags: '',
+  updatedAt: now(),
+  version: 2,
+  workflowVersion: '1.0.0',
+});
+
+export const cloneProjectGraph = (document: ProjectGraphState): ProjectGraphState => structuredClone(document);
+
+/** Accepts any persisted `projectGraph` shape and yields a current document, preserving the id. */
+export const normalizeProjectGraph = (candidate: unknown): ProjectGraphState => {
+  if (typeof candidate === 'object' && candidate !== null && (candidate as ProjectGraphState).version === 2) {
+    return candidate as ProjectGraphState;
+  }
+
+  const legacyId =
+    typeof (candidate as { id?: unknown } | null)?.id === 'string' ? (candidate as { id: string }).id : null;
+
+  return createProjectGraph(legacyId ?? createWorkflowId('workflow'));
+};
+
+export const buildInvocationNode = (template: InvocationTemplate, position: XYPosition): WorkflowInvocationNode => {
+  const inputs: Record<string, WorkflowFieldInstance> = {};
+
+  for (const inputTemplate of Object.values(template.inputs)) {
+    inputs[inputTemplate.name] = {
+      label: '',
+      name: inputTemplate.name,
+      value: inputTemplate.default === undefined ? undefined : structuredClone(inputTemplate.default),
+    };
+  }
+
+  return {
+    data: {
+      inputs,
+      isIntermediate: true,
+      isOpen: true,
+      label: '',
+      nodePack: template.nodePack,
+      notes: '',
+      type: template.type,
+      useCache: template.useCache,
+      version: template.version,
+    },
+    id: createWorkflowId(template.type),
+    position,
+    type: 'invocation',
+  };
+};
+
+export const buildNotesNode = (position: XYPosition): WorkflowNotesNode => ({
+  data: { label: 'Notes', notes: '' },
+  id: createWorkflowId('notes'),
+  position,
+  type: 'notes',
+});
+
+export const buildCurrentImageNode = (position: XYPosition): WorkflowCurrentImageNode => ({
+  data: { label: 'Current Image' },
+  id: createWorkflowId('current-image'),
+  position,
+  type: 'current_image',
+});
+
+export const buildConnectorNode = (position: XYPosition): WorkflowConnectorNode => ({
+  data: { label: '' },
+  id: createWorkflowId('connector'),
+  position,
+  type: 'connector',
+});
+
+// #region Form manipulation
+
+const getRootContainer = (form: WorkflowForm): ContainerFormElement => {
+  const root = form.elements[form.rootElementId];
+
+  if (root?.type === 'container') {
+    return root;
+  }
+
+  // A malformed form (bad import, old persistence) recovers as an empty root.
+  const recovered = createWorkflowForm();
+
+  return recovered.elements[recovered.rootElementId] as ContainerFormElement;
+};
+
+const collectDescendantIds = (form: WorkflowForm, elementId: string): string[] => {
+  const element = form.elements[elementId];
+
+  if (!element || element.type !== 'container') {
+    return [elementId];
+  }
+
+  return [elementId, ...element.data.children.flatMap((childId) => collectDescendantIds(form, childId))];
+};
+
+const appendToRoot = (form: WorkflowForm, element: WorkflowFormElement): WorkflowForm => {
+  const root = getRootContainer(form);
+  const rooted = { ...element, parentId: root.id };
+
+  return {
+    elements: {
+      ...form.elements,
+      [root.id]: { ...root, data: { ...root.data, children: [...root.data.children, rooted.id] } },
+      [rooted.id]: rooted,
+    },
+    rootElementId: root.id,
+  };
+};
+
+const removeFormElement = (form: WorkflowForm, elementId: string): WorkflowForm => {
+  if (elementId === form.rootElementId || !form.elements[elementId]) {
+    return form;
+  }
+
+  const removedIds = new Set(collectDescendantIds(form, elementId));
+  const elements: Record<string, WorkflowFormElement> = {};
+
+  for (const [id, element] of Object.entries(form.elements)) {
+    if (removedIds.has(id)) {
+      continue;
+    }
+
+    elements[id] =
+      element.type === 'container'
+        ? {
+            ...element,
+            data: { ...element.data, children: element.data.children.filter((childId) => !removedIds.has(childId)) },
+          }
+        : element;
+  }
+
+  return { ...form, elements };
+};
+
+/**
+ * Reparents an element to `parentId` at `index` (the drag-and-drop primitive).
+ * No-ops when the move is impossible: unknown ids, non-container targets, or
+ * dropping a container into its own subtree.
+ */
+const moveFormElementTo = (form: WorkflowForm, elementId: string, parentId: string, index: number): WorkflowForm => {
+  const element = form.elements[elementId];
+  const nextParent = form.elements[parentId];
+
+  if (
+    !element ||
+    elementId === form.rootElementId ||
+    !nextParent ||
+    nextParent.type !== 'container' ||
+    collectDescendantIds(form, elementId).includes(parentId)
+  ) {
+    return form;
+  }
+
+  const previousParent = element.parentId ? form.elements[element.parentId] : undefined;
+
+  if (!previousParent || previousParent.type !== 'container') {
+    return form;
+  }
+
+  const previousIndex = previousParent.data.children.indexOf(elementId);
+  const withoutElement = previousParent.data.children.filter((childId) => childId !== elementId);
+  // Removing the element above the drop point shifts the target index back one.
+  const adjustedIndex =
+    previousParent.id === nextParent.id && previousIndex !== -1 && previousIndex < index ? index - 1 : index;
+  const targetChildren = previousParent.id === nextParent.id ? withoutElement : [...nextParent.data.children];
+  const clampedIndex = Math.min(Math.max(0, adjustedIndex), targetChildren.length);
+
+  targetChildren.splice(clampedIndex, 0, elementId);
+
+  const elements: Record<string, WorkflowFormElement> = {
+    ...form.elements,
+    [elementId]: { ...element, parentId: nextParent.id },
+    [previousParent.id]: { ...previousParent, data: { ...previousParent.data, children: withoutElement } },
+  };
+
+  elements[nextParent.id] = {
+    ...(elements[nextParent.id] as ContainerFormElement),
+    data: { ...(elements[nextParent.id] as ContainerFormElement).data, children: targetChildren },
+  };
+
+  return { ...form, elements };
+};
+
+const moveFormElement = (form: WorkflowForm, elementId: string, direction: -1 | 1): WorkflowForm => {
+  const element = form.elements[elementId];
+  const parent = element?.parentId ? form.elements[element.parentId] : getRootContainer(form);
+
+  if (!element || !parent || parent.type !== 'container') {
+    return form;
+  }
+
+  const index = parent.data.children.indexOf(elementId);
+  const nextIndex = index + direction;
+
+  if (index === -1 || nextIndex < 0 || nextIndex >= parent.data.children.length) {
+    return form;
+  }
+
+  const children = [...parent.data.children];
+
+  children[index] = children[nextIndex] as string;
+  children[nextIndex] = elementId;
+
+  return {
+    ...form,
+    elements: { ...form.elements, [parent.id]: { ...parent, data: { ...parent.data, children } } },
+  };
+};
+
+export const findNodeFieldElement = (
+  form: WorkflowForm,
+  fieldIdentifier: FieldIdentifier
+): WorkflowFormElement | undefined =>
+  Object.values(form.elements).find(
+    (element) =>
+      element.type === 'node-field' &&
+      element.data.fieldIdentifier.nodeId === fieldIdentifier.nodeId &&
+      element.data.fieldIdentifier.fieldName === fieldIdentifier.fieldName
+  );
+
+export const isFieldExposed = (form: WorkflowForm, fieldIdentifier: FieldIdentifier): boolean =>
+  findNodeFieldElement(form, fieldIdentifier) !== undefined;
+
+const removeNodeFieldElements = (form: WorkflowForm, removedNodeIds: Set<string>): WorkflowForm =>
+  Object.values(form.elements)
+    .filter((element) => element.type === 'node-field' && removedNodeIds.has(element.data.fieldIdentifier.nodeId))
+    .reduce((nextForm, element) => removeFormElement(nextForm, element.id), form);
+
+// #endregion
+
+// #region Document reducer
+
+export type ProjectGraphAction =
+  | { type: 'addNode'; node: WorkflowNode }
+  | { type: 'addNodeAndEdge'; node: WorkflowNode; edge: WorkflowEdge }
+  | { type: 'addGraphElements'; nodes: WorkflowNode[]; edges: WorkflowEdge[] }
+  | { type: 'removeNodes'; nodeIds: string[] }
+  | { type: 'setNodePosition'; nodeId: string; position: XYPosition }
+  | { type: 'setNodeLabel'; nodeId: string; label: string }
+  | { type: 'setNodeNotes'; nodeId: string; notes: string }
+  | { type: 'setNodeIsOpen'; nodeId: string; isOpen: boolean }
+  | { type: 'setNodeIsIntermediate'; nodeId: string; isIntermediate: boolean }
+  | { type: 'setNodeUseCache'; nodeId: string; useCache: boolean }
+  | { type: 'setFieldValue'; nodeId: string; fieldName: string; value: unknown }
+  | { type: 'setFieldLabel'; nodeId: string; fieldName: string; label: string }
+  | { type: 'setFieldDescription'; nodeId: string; fieldName: string; description: string }
+  | { type: 'addEdge'; edge: WorkflowEdge }
+  | { type: 'removeEdges'; edgeIds: string[] }
+  | { type: 'exposeField'; fieldIdentifier: FieldIdentifier }
+  | { type: 'unexposeField'; fieldIdentifier: FieldIdentifier }
+  | { type: 'removeFormElement'; elementId: string }
+  | { type: 'moveFormElement'; elementId: string; direction: -1 | 1 }
+  | { type: 'moveFormElementTo'; elementId: string; parentId: string; index: number }
+  | {
+      type: 'addFormElement';
+      elementType: 'heading' | 'text' | 'divider' | 'container';
+      content?: string;
+      layout?: 'row' | 'column';
+    }
+  | { type: 'setFormElementContent'; elementId: string; content: string }
+  | { type: 'setNodeFieldShowDescription'; elementId: string; showDescription: boolean }
+  | { type: 'setContainerLayout'; elementId: string; layout: 'row' | 'column' }
+  | { type: 'setMetadata'; patch: Partial<WorkflowMetadata> };
+
+const undoLabels: Partial<Record<ProjectGraphAction['type'], string>> = {
+  addEdge: 'Connect workflow fields',
+  addFormElement: 'Edit workflow form',
+  addGraphElements: 'Paste workflow nodes',
+  addNode: 'Add workflow node',
+  addNodeAndEdge: 'Add workflow node',
+  exposeField: 'Expose workflow field',
+  moveFormElement: 'Edit workflow form',
+  moveFormElementTo: 'Edit workflow form',
+  removeEdges: 'Disconnect workflow fields',
+  removeFormElement: 'Edit workflow form',
+  removeNodes: 'Delete workflow nodes',
+  setContainerLayout: 'Edit workflow form',
+  setNodeFieldShowDescription: 'Edit workflow form',
+  unexposeField: 'Remove workflow field from form',
+};
+
+/** Returns the project-undo label for an action, or null when the edit should not create an undo entry. */
+export const getProjectGraphUndoLabel = (action: ProjectGraphAction): string | null => undoLabels[action.type] ?? null;
+
+/** Edits meaningful enough to auto-select the project graph as the invocation source. */
+export const isHighConfidenceGraphEdit = (action: ProjectGraphAction): boolean =>
+  action.type === 'addNode' ||
+  action.type === 'addNodeAndEdge' ||
+  action.type === 'addGraphElements' ||
+  action.type === 'removeNodes' ||
+  action.type === 'addEdge' ||
+  action.type === 'removeEdges' ||
+  action.type === 'setFieldValue';
+
+const updateNode = (
+  document: ProjectGraphState,
+  nodeId: string,
+  getNode: (node: WorkflowNode) => WorkflowNode
+): ProjectGraphState => ({
+  ...document,
+  nodes: document.nodes.map((node) => (node.id === nodeId ? getNode(node) : node)),
+});
+
+const updateInvocationNode = (
+  document: ProjectGraphState,
+  nodeId: string,
+  getNode: (node: WorkflowInvocationNode) => WorkflowInvocationNode
+): ProjectGraphState => updateNode(document, nodeId, (node) => (isInvocationNode(node) ? getNode(node) : node));
+
+const setFieldInstance = (
+  document: ProjectGraphState,
+  nodeId: string,
+  fieldName: string,
+  getInstance: (instance: WorkflowFieldInstance) => WorkflowFieldInstance
+): ProjectGraphState =>
+  updateInvocationNode(document, nodeId, (node) => {
+    const instance = node.data.inputs[fieldName] ?? { label: '', name: fieldName };
+
+    return {
+      ...node,
+      data: { ...node.data, inputs: { ...node.data.inputs, [fieldName]: getInstance(instance) } },
+    };
+  });
+
+const addEdgeToDocument = (document: ProjectGraphState, edge: WorkflowEdge): ProjectGraphState => {
+  // A non-collect input holds at most one connection; connecting replaces it.
+  const targetNode = document.nodes.find((node) => node.id === edge.target);
+  const keepsExisting =
+    targetNode && isInvocationNode(targetNode) && targetNode.data.type === 'collect' && edge.targetHandle === 'item';
+  const edges = keepsExisting
+    ? document.edges
+    : document.edges.filter(
+        (existingEdge) => !(existingEdge.target === edge.target && existingEdge.targetHandle === edge.targetHandle)
+      );
+
+  return { ...document, edges: [...edges, edge] };
+};
+
+export const projectGraphReducer = (document: ProjectGraphState, action: ProjectGraphAction): ProjectGraphState => {
+  const next = applyProjectGraphAction(document, action);
+
+  return next === document ? document : { ...next, updatedAt: now() };
+};
+
+const applyProjectGraphAction = (document: ProjectGraphState, action: ProjectGraphAction): ProjectGraphState => {
+  switch (action.type) {
+    case 'addNode': {
+      return { ...document, nodes: [...document.nodes, action.node] };
+    }
+    case 'addNodeAndEdge': {
+      if (document.nodes.some((node) => node.id === action.node.id)) {
+        return document;
+      }
+
+      return addEdgeToDocument({ ...document, nodes: [...document.nodes, action.node] }, action.edge);
+    }
+    case 'addGraphElements': {
+      if (action.nodes.length === 0 && action.edges.length === 0) {
+        return document;
+      }
+
+      // Guard against id collisions (a stale paste after an undo): existing
+      // ids win, incoming duplicates are dropped along with their edges.
+      const existingNodeIds = new Set(document.nodes.map((node) => node.id));
+      const nodes = action.nodes.filter((node) => !existingNodeIds.has(node.id));
+      const acceptedNodeIds = new Set(nodes.map((node) => node.id));
+      const existingEdgeIds = new Set(document.edges.map((edge) => edge.id));
+      const edges = action.edges.filter(
+        (edge) => !existingEdgeIds.has(edge.id) && acceptedNodeIds.has(edge.source) && acceptedNodeIds.has(edge.target)
+      );
+
+      if (nodes.length === 0) {
+        return document;
+      }
+
+      return { ...document, edges: [...document.edges, ...edges], nodes: [...document.nodes, ...nodes] };
+    }
+    case 'removeNodes': {
+      const removedNodeIds = new Set(action.nodeIds);
+
+      if (removedNodeIds.size === 0) {
+        return document;
+      }
+
+      return {
+        ...document,
+        edges: document.edges.filter((edge) => !removedNodeIds.has(edge.source) && !removedNodeIds.has(edge.target)),
+        form: removeNodeFieldElements(document.form, removedNodeIds),
+        nodes: document.nodes.filter((node) => !removedNodeIds.has(node.id)),
+      };
+    }
+    case 'setNodePosition': {
+      return updateNode(document, action.nodeId, (node) => ({ ...node, position: { ...action.position } }));
+    }
+    case 'setNodeLabel': {
+      // Narrowed per branch so TS keeps the node type / data correlation through the spread.
+      return updateNode(document, action.nodeId, (node) => {
+        if (isInvocationNode(node)) {
+          return { ...node, data: { ...node.data, label: action.label } };
+        }
+
+        if (isNotesNode(node)) {
+          return { ...node, data: { ...node.data, label: action.label } };
+        }
+
+        return { ...node, data: { ...node.data, label: action.label } };
+      });
+    }
+    case 'setNodeNotes': {
+      return updateNode(document, action.nodeId, (node) => {
+        if (isInvocationNode(node)) {
+          return { ...node, data: { ...node.data, notes: action.notes } };
+        }
+
+        if (isNotesNode(node)) {
+          return { ...node, data: { ...node.data, notes: action.notes } };
+        }
+
+        return node;
+      });
+    }
+    case 'setNodeIsOpen': {
+      return updateInvocationNode(document, action.nodeId, (node) => ({
+        ...node,
+        data: { ...node.data, isOpen: action.isOpen },
+      }));
+    }
+    case 'setNodeIsIntermediate': {
+      return updateInvocationNode(document, action.nodeId, (node) => ({
+        ...node,
+        data: { ...node.data, isIntermediate: action.isIntermediate },
+      }));
+    }
+    case 'setNodeUseCache': {
+      return updateInvocationNode(document, action.nodeId, (node) => ({
+        ...node,
+        data: { ...node.data, useCache: action.useCache },
+      }));
+    }
+    case 'setFieldValue': {
+      return setFieldInstance(document, action.nodeId, action.fieldName, (instance) => ({
+        ...instance,
+        value: action.value,
+      }));
+    }
+    case 'setFieldLabel': {
+      return setFieldInstance(document, action.nodeId, action.fieldName, (instance) => ({
+        ...instance,
+        label: action.label,
+      }));
+    }
+    case 'setFieldDescription': {
+      // An emptied override falls back to the template description.
+      return setFieldInstance(document, action.nodeId, action.fieldName, (instance) => ({
+        ...instance,
+        description: action.description || undefined,
+      }));
+    }
+    case 'addEdge': {
+      return addEdgeToDocument(document, action.edge);
+    }
+    case 'removeEdges': {
+      const removedEdgeIds = new Set(action.edgeIds);
+
+      if (removedEdgeIds.size === 0) {
+        return document;
+      }
+
+      return { ...document, edges: document.edges.filter((edge) => !removedEdgeIds.has(edge.id)) };
+    }
+    case 'exposeField': {
+      if (isFieldExposed(document.form, action.fieldIdentifier)) {
+        return document;
+      }
+
+      return {
+        ...document,
+        form: appendToRoot(document.form, {
+          data: { fieldIdentifier: { ...action.fieldIdentifier }, showDescription: false },
+          id: createWorkflowId('node-field'),
+          type: 'node-field',
+        }),
+      };
+    }
+    case 'unexposeField': {
+      const element = findNodeFieldElement(document.form, action.fieldIdentifier);
+
+      if (!element) {
+        return document;
+      }
+
+      return { ...document, form: removeFormElement(document.form, element.id) };
+    }
+    case 'removeFormElement': {
+      return { ...document, form: removeFormElement(document.form, action.elementId) };
+    }
+    case 'moveFormElement': {
+      const form = moveFormElement(document.form, action.elementId, action.direction);
+
+      return form === document.form ? document : { ...document, form };
+    }
+    case 'moveFormElementTo': {
+      const form = moveFormElementTo(document.form, action.elementId, action.parentId, action.index);
+
+      return form === document.form ? document : { ...document, form };
+    }
+    case 'addFormElement': {
+      const element: WorkflowFormElement =
+        action.elementType === 'divider'
+          ? { id: createWorkflowId('divider'), type: 'divider' }
+          : action.elementType === 'container'
+            ? {
+                data: { children: [], layout: action.layout ?? 'column' },
+                id: createWorkflowId('container'),
+                type: 'container',
+              }
+            : {
+                data: { content: action.content ?? '' },
+                id: createWorkflowId(action.elementType),
+                type: action.elementType,
+              };
+
+      return { ...document, form: appendToRoot(document.form, element) };
+    }
+    case 'setFormElementContent': {
+      const element = document.form.elements[action.elementId];
+
+      if (!element || (element.type !== 'heading' && element.type !== 'text')) {
+        return document;
+      }
+
+      return {
+        ...document,
+        form: {
+          ...document.form,
+          elements: {
+            ...document.form.elements,
+            [element.id]: { ...element, data: { ...element.data, content: action.content } },
+          },
+        },
+      };
+    }
+    case 'setContainerLayout': {
+      const element = document.form.elements[action.elementId];
+
+      if (!element || element.type !== 'container') {
+        return document;
+      }
+
+      return {
+        ...document,
+        form: {
+          ...document.form,
+          elements: {
+            ...document.form.elements,
+            [element.id]: { ...element, data: { ...element.data, layout: action.layout } },
+          },
+        },
+      };
+    }
+    case 'setNodeFieldShowDescription': {
+      const element = document.form.elements[action.elementId];
+
+      if (!element || element.type !== 'node-field') {
+        return document;
+      }
+
+      return {
+        ...document,
+        form: {
+          ...document.form,
+          elements: {
+            ...document.form.elements,
+            [element.id]: { ...element, data: { ...element.data, showDescription: action.showDescription } },
+          },
+        },
+      };
+    }
+    case 'setMetadata': {
+      return { ...document, ...action.patch };
+    }
+  }
+};
+
+// #endregion
+
+/** Ordered, render-ready view of the form tree starting at the root. */
+export const getFormChildren = (form: WorkflowForm, containerId?: string): WorkflowFormElement[] => {
+  const container = form.elements[containerId ?? form.rootElementId];
+
+  if (!container || container.type !== 'container') {
+    return [];
+  }
+
+  return container.data.children.flatMap((childId) => {
+    const child = form.elements[childId];
+
+    return child ? [child] : [];
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/fields.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/fields.test.ts
new file mode 100644
index 00000000000..b1d9ac52709
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/fields.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+
+import type { FieldInputTemplate, FieldType } from './types';
+
+import { getWorkflowFieldInvalidReason, isModelFieldType, isWorkflowFieldValueValid } from './fields';
+
+const single = (name: string): FieldType => ({ batch: false, cardinality: 'SINGLE', name });
+
+const input = (overrides: Partial<FieldInputTemplate> = {}): FieldInputTemplate => ({
+  default: undefined,
+  description: '',
+  exclusiveMaximum: null,
+  exclusiveMinimum: null,
+  input: 'any',
+  maximum: null,
+  minimum: null,
+  multipleOf: null,
+  name: 'value',
+  options: null,
+  required: true,
+  title: 'Value',
+  type: single('StringField'),
+  uiChoiceLabels: null,
+  uiComponent: null,
+  uiHidden: false,
+  uiModelBase: null,
+  uiModelType: null,
+  uiOrder: null,
+  ...overrides,
+});
+
+describe('workflow field validation', () => {
+  it('flags empty required direct values and ignores optional fields', () => {
+    expect(getWorkflowFieldInvalidReason({ isConnected: false, template: input(), value: '' })).toBe('Required value.');
+    expect(getWorkflowFieldInvalidReason({ isConnected: false, template: input({ required: false }), value: '' })).toBe(
+      null
+    );
+  });
+
+  it('treats connected required fields as valid', () => {
+    expect(
+      getWorkflowFieldInvalidReason({ isConnected: true, template: input({ input: 'connection' }), value: '' })
+    ).toBe(null);
+  });
+
+  it('flags missing required connections', () => {
+    expect(
+      getWorkflowFieldInvalidReason({ isConnected: false, template: input({ input: 'connection' }), value: undefined })
+    ).toBe('Required connection.');
+    expect(
+      getWorkflowFieldInvalidReason({ isConnected: false, template: input({ input: 'connection' }), value: 'value' })
+    ).toBe('Required connection.');
+  });
+
+  it('accepts persisted values for unsupported direct controls', () => {
+    const template = input({ type: single('AnyField') });
+
+    expect(getWorkflowFieldInvalidReason({ isConnected: false, template, value: { value: true } })).toBe(null);
+    expect(getWorkflowFieldInvalidReason({ isConnected: false, template, value: undefined })).toBe(
+      'Required connection.'
+    );
+  });
+
+  it('validates numeric constraints', () => {
+    const template = input({ maximum: 10, minimum: 1, type: single('IntegerField') });
+
+    expect(isWorkflowFieldValueValid(template, 5)).toBe(true);
+    expect(isWorkflowFieldValueValid(template, 0)).toBe(false);
+    expect(isWorkflowFieldValueValid(template, 5.5)).toBe(false);
+  });
+
+  it('allows empty optional direct values but flags populated invalid optional values', () => {
+    const template = input({ maximum: 10, minimum: 1, required: false, type: single('IntegerField') });
+
+    expect(getWorkflowFieldInvalidReason({ isConnected: false, template, value: undefined })).toBe(null);
+    expect(getWorkflowFieldInvalidReason({ isConnected: false, template, value: 20 })).toBe('Invalid value.');
+  });
+
+  it('validates object-backed model and image fields', () => {
+    expect(isWorkflowFieldValueValid(input({ type: single('ModelIdentifierField') }), { key: 'model-key' })).toBe(true);
+    expect(isWorkflowFieldValueValid(input({ type: single('ModelIdentifierField') }), {})).toBe(false);
+    expect(isWorkflowFieldValueValid(input({ type: single('ImageField') }), { image_name: 'image.png' })).toBe(true);
+    expect(isWorkflowFieldValueValid(input({ type: single('ImageField') }), { image_name: '' })).toBe(false);
+  });
+
+  it('treats empty board values as the Auto sentinel', () => {
+    expect(isWorkflowFieldValueValid(input({ type: single('BoardField') }), undefined)).toBe(true);
+    expect(isWorkflowFieldValueValid(input({ type: single('BoardField') }), { board_id: 'board-id' })).toBe(true);
+    expect(isWorkflowFieldValueValid(input({ type: single('BoardField') }), {})).toBe(false);
+  });
+});
+
+describe('workflow field type helpers', () => {
+  it('matches legacy model field shape classification', () => {
+    expect(isModelFieldType(single('ModelIdentifierField'))).toBe(true);
+    expect(isModelFieldType(single('UNetField'))).toBe(true);
+    expect(isModelFieldType(single('CLIPField'))).toBe(true);
+    expect(isModelFieldType(single('ImageField'))).toBe(false);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/fields.ts b/invokeai/frontend/webv2/src/workbench/workflows/fields.ts
new file mode 100644
index 00000000000..0d2430b85ad
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/fields.ts
@@ -0,0 +1,238 @@
+import type { FieldInputTemplate, FieldType } from './types';
+
+/**
+ * Field-kind helpers shared by the node editor and the Linear UI panel:
+ * which field types render direct-input controls, and how handles/edges are
+ * tinted by type so connections stay readable.
+ */
+
+/** Field types with a direct-input widget. Everything else is connection-only. */
+const STATEFUL_FIELD_TYPE_NAMES = new Set([
+  'BoardField',
+  'BooleanField',
+  'ColorField',
+  'EnumField',
+  'FloatField',
+  'ImageField',
+  'IntegerField',
+  'ModelIdentifierField',
+  'SchedulerField',
+  'StringField',
+]);
+
+export const isStatefulFieldType = (type: FieldType): boolean => STATEFUL_FIELD_TYPE_NAMES.has(type.name);
+
+const MODEL_FIELD_TYPE_NAMES = new Set([
+  'CLIPField',
+  'ControlLoRAField',
+  'ModelIdentifierField',
+  'T5EncoderField',
+  'TransformerField',
+  'UNetField',
+  'VAEField',
+]);
+
+export const isModelFieldType = (type: FieldType): boolean => MODEL_FIELD_TYPE_NAMES.has(type.name);
+
+/** True when the field renders an editable control on the node / linear form. */
+export const isDirectInputField = (template: FieldInputTemplate): boolean =>
+  template.input !== 'connection' && isStatefulFieldType(template.type) && template.type.cardinality !== 'COLLECTION';
+
+/** A field can be exposed to the Linear UI when it can be edited directly. */
+export const isExposableField = (template: FieldInputTemplate): boolean => isDirectInputField(template);
+
+export const cloneWorkflowFieldDefault = (template: FieldInputTemplate): unknown =>
+  template.default === undefined ? undefined : structuredClone(template.default);
+
+export const isWorkflowFieldValueDefault = (template: FieldInputTemplate, value: unknown): boolean => {
+  if (value === template.default) {
+    return true;
+  }
+
+  if (value === undefined || template.default === undefined) {
+    return false;
+  }
+
+  try {
+    return JSON.stringify(value) === JSON.stringify(template.default);
+  } catch {
+    return false;
+  }
+};
+
+const isNonEmptyString = (value: unknown): value is string => typeof value === 'string' && value.trim().length > 0;
+
+const hasNonEmptyStringProp = (value: unknown, prop: string): boolean =>
+  typeof value === 'object' && value !== null && isNonEmptyString((value as Record<string, unknown>)[prop]);
+
+const isNumberFieldValueValid = (template: FieldInputTemplate, value: unknown): boolean => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return false;
+  }
+
+  if (template.type.name === 'IntegerField' && !Number.isInteger(value)) {
+    return false;
+  }
+
+  if (template.minimum !== null && value < template.minimum) {
+    return false;
+  }
+
+  if (template.maximum !== null && value > template.maximum) {
+    return false;
+  }
+
+  if (template.exclusiveMinimum !== null && value <= template.exclusiveMinimum) {
+    return false;
+  }
+
+  if (template.exclusiveMaximum !== null && value >= template.exclusiveMaximum) {
+    return false;
+  }
+
+  if (template.multipleOf !== null) {
+    const quotient = value / template.multipleOf;
+
+    if (Math.abs(quotient - Math.round(quotient)) > Number.EPSILON * 100) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+const isColorValueValid = (value: unknown): boolean => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const channels = value as Record<string, unknown>;
+
+  return ['r', 'g', 'b', 'a'].every((channel) => {
+    const channelValue = channels[channel];
+
+    return typeof channelValue === 'number' && channelValue >= 0 && channelValue <= 255;
+  });
+};
+
+export const isWorkflowFieldValueValid = (template: FieldInputTemplate, value: unknown): boolean => {
+  switch (template.type.name) {
+    case 'StringField':
+      return isNonEmptyString(value);
+    case 'IntegerField':
+    case 'FloatField':
+      return isNumberFieldValueValid(template, value);
+    case 'BooleanField':
+      return typeof value === 'boolean';
+    case 'EnumField':
+      return isNonEmptyString(value) && (template.options === null || template.options.includes(value));
+    case 'ModelIdentifierField':
+      return hasNonEmptyStringProp(value, 'key');
+    case 'SchedulerField':
+      return isNonEmptyString(value);
+    case 'BoardField':
+      return (
+        value === undefined ||
+        value === null ||
+        value === 'auto' ||
+        value === 'none' ||
+        hasNonEmptyStringProp(value, 'board_id')
+      );
+    case 'ImageField':
+      return hasNonEmptyStringProp(value, 'image_name');
+    case 'ColorField':
+      return isColorValueValid(value);
+    default:
+      return value !== undefined && value !== null;
+  }
+};
+
+const isEmptyOptionalValue = (value: unknown): boolean => value === undefined || value === null || value === '';
+
+export const getWorkflowFieldInvalidReason = ({
+  isConnected,
+  template,
+  value,
+}: {
+  isConnected: boolean;
+  template: FieldInputTemplate;
+  value: unknown;
+}): string | null => {
+  if (isConnected) {
+    return null;
+  }
+
+  if (!template.required && isEmptyOptionalValue(value)) {
+    return null;
+  }
+
+  if (!template.required) {
+    return isDirectInputField(template) && !isWorkflowFieldValueValid(template, value) ? 'Invalid value.' : null;
+  }
+
+  if (template.input === 'connection') {
+    return 'Required connection.';
+  }
+
+  if (isWorkflowFieldValueValid(template, value)) {
+    return null;
+  }
+
+  return isDirectInputField(template) ? 'Required value.' : 'Required connection.';
+};
+
+// Raw hex (not Chakra tokens) because xyflow handles are styled inline.
+const FIELD_TYPE_COLORS: Record<string, string> = {
+  AnyField: '#9ca3af',
+  BoardField: '#a78bfa',
+  BooleanField: '#4ade80',
+  CLIPField: '#2dd4bf',
+  ColorField: '#f472b6',
+  ConditioningField: '#22d3ee',
+  ControlField: '#5eead4',
+  DenoiseMaskField: '#93c5fd',
+  EnumField: '#60a5fa',
+  FloatField: '#fb923c',
+  ImageField: '#c4b5fd',
+  IntegerField: '#f87171',
+  LatentsField: '#f9a8d4',
+  ModelIdentifierField: '#14b8a6',
+  SchedulerField: '#3b82f6',
+  StringField: '#facc15',
+  UNetField: '#fca5a5',
+  VAEField: '#2563eb',
+};
+
+const FALLBACK_COLORS = ['#06b6d4', '#a855f7', '#22c55e', '#f97316', '#ec4899', '#0d9488'];
+
+/** Stable tint for a field type: known types get fixed colors, the rest hash into a small palette. */
+export const getFieldTypeColor = (type: FieldType): string => {
+  const known = FIELD_TYPE_COLORS[type.name];
+
+  if (known) {
+    return known;
+  }
+
+  let hash = 0;
+
+  for (const char of type.name) {
+    hash = (hash * 31 + char.charCodeAt(0)) % FALLBACK_COLORS.length;
+  }
+
+  return FALLBACK_COLORS[hash] as string;
+};
+
+/** Display label for a field type, e.g. `ImageField (Collection)`. */
+export const getFieldTypeLabel = (type: FieldType): string => {
+  const base = type.name.replace(/Field$/, '');
+
+  if (type.cardinality === 'COLLECTION') {
+    return `${base} Collection`;
+  }
+
+  if (type.cardinality === 'SINGLE_OR_COLLECTION') {
+    return `${base} (single or collection)`;
+  }
+
+  return base;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/graphIndex.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/graphIndex.test.ts
new file mode 100644
index 00000000000..c86fa3475e1
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/graphIndex.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import type { WorkflowConnectorNode, WorkflowEdge, WorkflowInvocationNode } from './types';
+
+import { createWorkflowGraphIndex } from './graphIndex';
+
+const makeNode = (id: string): WorkflowInvocationNode => ({
+  data: {
+    inputs: {},
+    isIntermediate: true,
+    isOpen: true,
+    label: '',
+    nodePack: 'invokeai',
+    notes: '',
+    type: 'number',
+    useCache: true,
+    version: '1.0.0',
+  },
+  id,
+  position: { x: 0, y: 0 },
+  type: 'invocation',
+});
+
+const makeConnector = (id: string): WorkflowConnectorNode => ({
+  data: { label: '' },
+  id,
+  position: { x: 0, y: 0 },
+  type: 'connector',
+});
+
+const edge = (
+  id: string,
+  source: string,
+  sourceHandle: string,
+  target: string,
+  targetHandle: string
+): WorkflowEdge => ({
+  id,
+  source,
+  sourceHandle,
+  target,
+  targetHandle,
+  type: 'default',
+});
+
+describe('createWorkflowGraphIndex', () => {
+  it('indexes nodes and connector edges for repeated lookup', () => {
+    const source = makeNode('source');
+    const target = makeNode('target');
+    const connector = makeConnector('connector');
+    const connectorInput = edge('connector-input', 'source', 'value', 'connector', 'in');
+    const connectorOutput = edge('connector-output', 'connector', 'out', 'target', 'value');
+    const index = createWorkflowGraphIndex([source, connector, target], [connectorInput, connectorOutput]);
+
+    expect(index.nodesById.get('source')).toBe(source);
+    expect(index.edgesBySource.get('connector')).toEqual([connectorOutput]);
+    expect(index.edgesByTarget.get('connector')).toEqual([connectorInput]);
+    expect(index.connectorInputById.get('connector')).toBe(connectorInput);
+    expect(index.connectorOutputsById.get('connector')).toEqual([connectorOutput]);
+  });
+
+  it('preserves first-match connector input semantics for invalid duplicate inputs', () => {
+    const sourceA = makeNode('source-a');
+    const sourceB = makeNode('source-b');
+    const connector = makeConnector('connector');
+    const firstInput = edge('first-input', 'source-a', 'value', 'connector', 'in');
+    const secondInput = edge('second-input', 'source-b', 'value', 'connector', 'in');
+    const index = createWorkflowGraphIndex([sourceA, sourceB, connector], [firstInput, secondInput]);
+
+    expect(index.connectorInputById.get('connector')).toBe(firstInput);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/graphIndex.ts b/invokeai/frontend/webv2/src/workbench/workflows/graphIndex.ts
new file mode 100644
index 00000000000..e7954742a9f
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/graphIndex.ts
@@ -0,0 +1,57 @@
+import type { WorkflowEdge, WorkflowNode } from './types';
+
+import { CONNECTOR_INPUT_HANDLE, CONNECTOR_OUTPUT_HANDLE } from './connectorHandles';
+
+export interface WorkflowGraphIndex {
+  connectorInputById: Map<string, WorkflowEdge>;
+  connectorOutputsById: Map<string, WorkflowEdge[]>;
+  edgesBySource: Map<string, WorkflowEdge[]>;
+  edgesByTarget: Map<string, WorkflowEdge[]>;
+  nodesById: Map<string, WorkflowNode>;
+}
+
+const append = <K, V>(map: Map<K, V[]>, key: K, value: V): void => {
+  const values = map.get(key);
+
+  if (values) {
+    values.push(value);
+    return;
+  }
+
+  map.set(key, [value]);
+};
+
+export const createWorkflowGraphIndex = (nodes: WorkflowNode[], edges: WorkflowEdge[]): WorkflowGraphIndex => {
+  const index: WorkflowGraphIndex = {
+    connectorInputById: new Map(),
+    connectorOutputsById: new Map(),
+    edgesBySource: new Map(),
+    edgesByTarget: new Map(),
+    nodesById: new Map(),
+  };
+
+  for (const node of nodes) {
+    index.nodesById.set(node.id, node);
+  }
+
+  for (const edge of edges) {
+    append(index.edgesBySource, edge.source, edge);
+    append(index.edgesByTarget, edge.target, edge);
+
+    if (edge.type !== 'default') {
+      continue;
+    }
+
+    if (edge.targetHandle === CONNECTOR_INPUT_HANDLE) {
+      if (!index.connectorInputById.has(edge.target)) {
+        index.connectorInputById.set(edge.target, edge);
+      }
+    }
+
+    if (edge.sourceHandle === CONNECTOR_OUTPUT_HANDLE) {
+      append(index.connectorOutputsById, edge.source, edge);
+    }
+  }
+
+  return index;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/layerWorkflow.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/layerWorkflow.test.ts
new file mode 100644
index 00000000000..5e5b45d8e4b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/layerWorkflow.test.ts
@@ -0,0 +1,433 @@
+import { describe, expect, it } from 'vitest';
+
+import type { InvocationTemplatesSnapshot } from './templates';
+import type {
+  FieldInputTemplate,
+  FieldOutputTemplate,
+  InvocationTemplate,
+  InvocationTemplates,
+  ProjectGraphState,
+  WorkflowEdge,
+  WorkflowInvocationNode,
+} from './types';
+
+import { buildConnectorNode, buildInvocationNode, createProjectGraph } from './document';
+import {
+  buildLayerWorkflowGraph,
+  getDefaultLayerWorkflowSelection,
+  getLayerWorkflowInputs,
+  getLayerWorkflowOutputs,
+  getRunnableLayerWorkflowInputs,
+  reconcileLayerWorkflowSelection,
+  type WorkflowImageBinding,
+} from './layerWorkflow';
+
+const imageType = { batch: false, cardinality: 'SINGLE' as const, name: 'ImageField' };
+
+const input = (name: string, overrides: Partial<FieldInputTemplate> = {}): FieldInputTemplate => ({
+  default: undefined,
+  description: '',
+  exclusiveMaximum: null,
+  exclusiveMinimum: null,
+  input: 'any',
+  maximum: null,
+  minimum: null,
+  multipleOf: null,
+  name,
+  options: null,
+  required: false,
+  title: name,
+  type: imageType,
+  uiChoiceLabels: null,
+  uiComponent: null,
+  uiHidden: false,
+  uiModelBase: null,
+  uiModelType: null,
+  uiOrder: null,
+  ...overrides,
+});
+
+const output = (name: string, overrides: Partial<FieldOutputTemplate> = {}): FieldOutputTemplate => ({
+  description: '',
+  name,
+  title: name,
+  type: imageType,
+  ...overrides,
+});
+
+const template = (
+  type: string,
+  inputs: Record<string, FieldInputTemplate> = {},
+  outputs: Record<string, FieldOutputTemplate> = {}
+): InvocationTemplate => ({
+  category: 'test',
+  classification: 'stable',
+  description: '',
+  inputs,
+  nodePack: 'invokeai',
+  outputs,
+  outputType: `${type}_output`,
+  tags: [],
+  title: type,
+  type,
+  useCache: true,
+  version: '1.0.0',
+});
+
+const node = (
+  id: string,
+  invocationTemplate: InvocationTemplate,
+  options: { fieldLabels?: Record<string, string>; label?: string } = {}
+): WorkflowInvocationNode => {
+  const built = buildInvocationNode(invocationTemplate, { x: 0, y: 0 });
+
+  for (const [fieldName, label] of Object.entries(options.fieldLabels ?? {})) {
+    const instance = built.data.inputs[fieldName];
+
+    if (instance) {
+      instance.label = label;
+    }
+  }
+
+  return { ...built, data: { ...built.data, label: options.label ?? '' }, id };
+};
+
+const document = (nodes: WorkflowInvocationNode[], edges: WorkflowEdge[] = []): ProjectGraphState => ({
+  ...createProjectGraph('layer-workflow-test', 'Layer Workflow'),
+  edges,
+  nodes,
+});
+
+const loaded = (templates: InvocationTemplates): InvocationTemplatesSnapshot => ({
+  error: null,
+  status: 'loaded',
+  templates,
+});
+
+const binding = (nodeId: string, fieldName: string, label = ''): WorkflowImageBinding => ({
+  fieldName,
+  label,
+  nodeId,
+});
+
+describe('layer workflow binding discovery', () => {
+  it('finds unconnected image inputs across all input modes in document and UI order', () => {
+    const sourceTemplate = template('source', {}, { image: output('image', { title: 'Image' }) });
+    const sinkTemplate = template('sink', {
+      directEdgeTarget: input('directEdgeTarget', { input: 'any', title: 'Connected directly', uiOrder: 0 }),
+      directOptional: input('directOptional', { input: 'direct', title: 'Optional image', uiOrder: 1 }),
+      directRequired: input('directRequired', { input: 'direct', required: true, title: 'Required image', uiOrder: 2 }),
+      anyAvailable: input('anyAvailable', { input: 'any', title: 'Any image', uiOrder: 3 }),
+      connectionOnly: input('connectionOnly', {
+        input: 'connection',
+        required: true,
+        title: 'Connection image',
+        uiOrder: 4,
+      }),
+      connectorTarget: input('connectorTarget', {
+        input: 'connection',
+        title: 'Connected through connector',
+        uiOrder: 5,
+      }),
+      collection: input('collection', {
+        title: 'Image collection',
+        type: { batch: false, cardinality: 'COLLECTION', name: 'ImageField' },
+        uiOrder: 6,
+      }),
+      batch: input('batch', {
+        title: 'Image batch',
+        type: { batch: true, cardinality: 'SINGLE', name: 'ImageField' },
+        uiOrder: 7,
+      }),
+      text: input('text', {
+        title: 'Text',
+        type: { batch: false, cardinality: 'SINGLE', name: 'StringField' },
+        uiOrder: 8,
+      }),
+    });
+    const otherTemplate = template('other', {
+      image: input('image', { input: 'direct', title: 'Other image', uiOrder: 0 }),
+    });
+    const unknownTemplate = template('unknown', { image: input('image', { title: 'Unknown image' }) });
+    const source = node('source', sourceTemplate);
+    const sink = node('sink', sinkTemplate, {
+      fieldLabels: { directOptional: 'Custom image field' },
+      label: 'Custom sink',
+    });
+    const unknown = node('unknown', unknownTemplate);
+    const other = node('other', otherTemplate);
+    const connector = { ...buildConnectorNode({ x: 0, y: 0 }), id: 'connector' };
+    const doc = {
+      ...document([sink, unknown, other, source]),
+      nodes: [sink, connector, unknown, other, source],
+      edges: [
+        {
+          id: 'direct',
+          source: 'source',
+          sourceHandle: 'image',
+          target: 'sink',
+          targetHandle: 'directEdgeTarget',
+          type: 'default',
+        },
+        {
+          id: 'connector-in',
+          source: 'source',
+          sourceHandle: 'image',
+          target: 'connector',
+          targetHandle: 'in',
+          type: 'default',
+        },
+        {
+          id: 'connector-out',
+          source: 'connector',
+          sourceHandle: 'out',
+          target: 'sink',
+          targetHandle: 'connectorTarget',
+          type: 'default',
+        },
+      ],
+    } satisfies ProjectGraphState;
+    const templates = { other: otherTemplate, sink: sinkTemplate, source: sourceTemplate };
+
+    expect(getLayerWorkflowInputs(doc, templates)).toEqual([
+      binding('sink', 'directOptional', 'Custom sink → Custom image field'),
+      binding('sink', 'directRequired', 'Custom sink → Required image'),
+      binding('sink', 'anyAvailable', 'Custom sink → Any image'),
+      binding('sink', 'connectionOnly', 'Custom sink → Connection image'),
+      binding('other', 'image', 'other → Other image'),
+    ]);
+  });
+
+  it('finds only single non-batch image outputs and skips image primitive nodes', () => {
+    const processorTemplate = template(
+      'processor',
+      {},
+      {
+        first: output('first', { title: 'First image' }),
+        collection: output('collection', {
+          title: 'Image collection',
+          type: { batch: false, cardinality: 'COLLECTION', name: 'ImageField' },
+        }),
+        second: output('second', { title: 'Second image' }),
+        batch: output('batch', {
+          title: 'Image batch',
+          type: { batch: true, cardinality: 'SINGLE', name: 'ImageField' },
+        }),
+        text: output('text', {
+          title: 'Text',
+          type: { batch: false, cardinality: 'SINGLE', name: 'StringField' },
+        }),
+      }
+    );
+    const otherTemplate = template('other', {}, { image: output('image', { title: 'Other image' }) });
+    const primitiveTemplate = template('image', {}, { image: output('image', { title: 'Primitive image' }) });
+    const unknownTemplate = template('unknown', {}, { image: output('image') });
+    const doc = document([
+      node('processor', processorTemplate, { label: 'Custom processor' }),
+      node('primitive', primitiveTemplate),
+      node('unknown', unknownTemplate),
+      node('other', otherTemplate),
+    ]);
+    const templates = { image: primitiveTemplate, other: otherTemplate, processor: processorTemplate };
+
+    expect(getLayerWorkflowOutputs(doc, templates)).toEqual([
+      binding('processor', 'first', 'Custom processor → First image'),
+      binding('processor', 'second', 'Custom processor → Second image'),
+      binding('other', 'image', 'other → Other image'),
+    ]);
+  });
+
+  it('probes every candidate after sentinel injection and keeps a valid candidate after an invalid first one', () => {
+    const processorTemplate = template(
+      'processor',
+      {
+        optionalFirst: input('optionalFirst', { input: 'direct', title: 'Optional first', uiOrder: 0 }),
+        requiredSecond: input('requiredSecond', {
+          input: 'direct',
+          required: true,
+          title: 'Required second',
+          uiOrder: 1,
+        }),
+      },
+      { image: output('image', { title: 'Result' }) }
+    );
+    const doc = document([node('processor', processorTemplate)]);
+    const outputBinding = getLayerWorkflowOutputs(doc, { processor: processorTemplate })[0]!;
+
+    expect(getRunnableLayerWorkflowInputs(doc, loaded({ processor: processorTemplate }), outputBinding)).toEqual([
+      binding('processor', 'requiredSecond', 'processor → Required second'),
+    ]);
+  });
+});
+
+describe('layer workflow dialog selection', () => {
+  it('defaults to Gallery and the first output that has a runnable input', () => {
+    const firstOutput = binding('first-output', 'image', 'First output');
+    const secondOutput = binding('second-output', 'image', 'Second output');
+    const secondInput = binding('second-input', 'image', 'Second input');
+
+    expect(
+      getDefaultLayerWorkflowSelection([firstOutput, secondOutput], (candidate) =>
+        candidate.nodeId === secondOutput.nodeId ? [secondInput] : []
+      )
+    ).toEqual({ destination: 'gallery', input: secondInput, output: secondOutput });
+  });
+
+  it('returns an empty Gallery selection when no output has a runnable input', () => {
+    expect(getDefaultLayerWorkflowSelection([binding('output', 'image')], () => [])).toEqual({
+      destination: 'gallery',
+      input: null,
+      output: null,
+    });
+  });
+
+  it('preserves the current input by identity when it remains runnable for a changed output', () => {
+    const currentInput = binding('input', 'image', 'Old label');
+    const changedOutput = binding('changed-output', 'image', 'Changed output');
+    const refreshedInput = binding('input', 'image', 'Refreshed label');
+
+    expect(
+      reconcileLayerWorkflowSelection(
+        { destination: 'staging', input: currentInput, output: binding('old-output', 'image') },
+        changedOutput,
+        [refreshedInput, binding('fallback', 'image')]
+      )
+    ).toEqual({ destination: 'staging', input: refreshedInput, output: changedOutput });
+  });
+
+  it('falls back to the first runnable input for a changed output', () => {
+    const changedOutput = binding('changed-output', 'image', 'Changed output');
+    const firstRunnable = binding('first-input', 'image', 'First input');
+
+    expect(
+      reconcileLayerWorkflowSelection(
+        { destination: 'copy-raster', input: binding('old-input', 'image'), output: binding('old-output', 'image') },
+        changedOutput,
+        [firstRunnable, binding('second-input', 'image')]
+      )
+    ).toEqual({ destination: 'copy-raster', input: firstRunnable, output: changedOutput });
+  });
+});
+
+describe('buildLayerWorkflowGraph', () => {
+  it('injects a direct-capable input before readiness without mutating the document', () => {
+    const processorTemplate = template(
+      'processor',
+      {
+        image: input('image', { input: 'direct', required: true, title: 'Layer image' }),
+      },
+      { result: output('result', { title: 'Result image' }) }
+    );
+    const processor = node('processor', processorTemplate);
+    delete processor.data.inputs.image;
+    const doc = document([processor]);
+    const before = structuredClone(doc);
+    const built = buildLayerWorkflowGraph({
+      document: doc,
+      imageName: 'layer.png',
+      input: binding('processor', 'image'),
+      output: binding('processor', 'result'),
+      templatesSnapshot: loaded({ processor: processorTemplate }),
+    });
+
+    expect(doc).toEqual(before);
+    expect(built.graph.nodes.processor).toMatchObject({
+      image: { image_name: 'layer.png' },
+      is_intermediate: true,
+      type: 'processor',
+    });
+    expect(built.graph.nodes[built.outputNodeId]).toMatchObject({
+      id: built.outputNodeId,
+      is_intermediate: true,
+      type: 'image',
+    });
+    expect(built.graph.edges).toContainEqual({
+      destination: { field: 'image', node_id: built.outputNodeId },
+      source: { field: 'result', node_id: 'processor' },
+    });
+    expect(Object.values(built.graph.nodes).every((graphNode) => graphNode.is_intermediate === true)).toBe(true);
+  });
+
+  it('externally satisfies only the selected connection input and appends collision-safe source and capture nodes', () => {
+    const sinkTemplate = template('sink', {
+      image: input('image', { input: 'connection', required: true, title: 'Layer image' }),
+    });
+    const resultTemplate = template('result', {}, { image: output('image', { title: 'Result image' }) });
+    const doc = document([node('layer-workflow-source', sinkTemplate), node('layer-workflow-output', resultTemplate)]);
+    const built = buildLayerWorkflowGraph({
+      document: doc,
+      imageName: 'layer.png',
+      input: binding('layer-workflow-source', 'image'),
+      output: binding('layer-workflow-output', 'image'),
+      templatesSnapshot: loaded({ result: resultTemplate, sink: sinkTemplate }),
+    });
+
+    expect(built.outputNodeId).toBe('layer-workflow-output-1');
+    expect(built.graph.nodes['layer-workflow-source-1']).toMatchObject({
+      id: 'layer-workflow-source-1',
+      image: { image_name: 'layer.png' },
+      is_intermediate: true,
+      type: 'image',
+    });
+    expect(built.graph.edges).toContainEqual({
+      destination: { field: 'image', node_id: 'layer-workflow-source' },
+      source: { field: 'image', node_id: 'layer-workflow-source-1' },
+    });
+    expect(built.graph.edges).toContainEqual({
+      destination: { field: 'image', node_id: 'layer-workflow-output-1' },
+      source: { field: 'image', node_id: 'layer-workflow-output' },
+    });
+  });
+
+  it('reports readiness errors that remain after image injection and preserves the document', () => {
+    const processorTemplate = template(
+      'processor',
+      {
+        image: input('image', { input: 'direct', required: true, title: 'Layer image' }),
+        prompt: input('prompt', {
+          input: 'direct',
+          required: true,
+          title: 'Prompt',
+          type: { batch: false, cardinality: 'SINGLE', name: 'StringField' },
+        }),
+      },
+      { result: output('result') }
+    );
+    const doc = document([node('processor', processorTemplate)]);
+    const before = structuredClone(doc);
+
+    expect(() =>
+      buildLayerWorkflowGraph({
+        document: doc,
+        imageName: 'layer.png',
+        input: binding('processor', 'image'),
+        output: binding('processor', 'result'),
+        templatesSnapshot: loaded({ processor: processorTemplate }),
+      })
+    ).toThrow(/missing required input "Prompt"/);
+    expect(doc).toEqual(before);
+  });
+
+  it('rejects stale input and output bindings', () => {
+    const processorTemplate = template(
+      'processor',
+      { image: input('image', { input: 'direct', required: true }) },
+      { result: output('result') }
+    );
+    const doc = document([node('processor', processorTemplate)]);
+    const options = {
+      document: doc,
+      imageName: 'layer.png',
+      input: binding('processor', 'image'),
+      output: binding('processor', 'result'),
+      templatesSnapshot: loaded({ processor: processorTemplate }),
+    };
+
+    expect(() => buildLayerWorkflowGraph({ ...options, input: binding('processor', 'removed') })).toThrow(
+      /input binding is no longer available/i
+    );
+    expect(() => buildLayerWorkflowGraph({ ...options, output: binding('processor', 'removed') })).toThrow(
+      /output binding is no longer available/i
+    );
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/layerWorkflow.ts b/invokeai/frontend/webv2/src/workbench/workflows/layerWorkflow.ts
new file mode 100644
index 00000000000..825b9ac6d75
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/layerWorkflow.ts
@@ -0,0 +1,331 @@
+import type { BackendGraphContract } from '@workbench/types';
+
+import type { InvocationTemplatesSnapshot } from './templates';
+import type {
+  FieldInputTemplate,
+  FieldOutputTemplate,
+  InvocationTemplates,
+  ProjectGraphState,
+  WorkflowInvocationNode,
+} from './types';
+
+import { compileProjectGraph, getProjectGraphReadiness } from './buildGraph';
+import { getResolvedWorkflowEdgesIndexed } from './connectors';
+import { createWorkflowGraphIndex } from './graphIndex';
+import { isInvocationNode } from './types';
+
+const READINESS_IMAGE_NAME = 'layer-action-readiness.png';
+const SOURCE_NODE_ID = 'layer-workflow-source';
+const CAPTURE_NODE_ID = 'layer-workflow-output';
+
+export interface WorkflowImageBinding {
+  nodeId: string;
+  fieldName: string;
+  label: string;
+}
+
+export type LayerWorkflowDestination = 'gallery' | 'staging' | 'replace' | 'copy-raster';
+
+export interface LayerWorkflowSelection {
+  destination: LayerWorkflowDestination;
+  input: WorkflowImageBinding | null;
+  output: WorkflowImageBinding | null;
+}
+
+export type GetRunnableLayerWorkflowInputs = (output: WorkflowImageBinding) => readonly WorkflowImageBinding[];
+
+export interface BuildLayerWorkflowGraphOptions {
+  document: ProjectGraphState;
+  templatesSnapshot: InvocationTemplatesSnapshot;
+  input: WorkflowImageBinding;
+  output: WorkflowImageBinding;
+  imageName: string;
+}
+
+export interface BuiltLayerWorkflowGraph {
+  graph: BackendGraphContract;
+  outputNodeId: string;
+}
+
+const isSingleImageField = (field: FieldInputTemplate | FieldOutputTemplate): boolean =>
+  field.type.name === 'ImageField' && field.type.cardinality === 'SINGLE' && !field.type.batch;
+
+const getNodeLabel = (node: WorkflowInvocationNode, templates: InvocationTemplates): string =>
+  node.data.label || templates[node.data.type]?.title || node.data.type;
+
+const getInputLabel = (node: WorkflowInvocationNode, field: FieldInputTemplate): string =>
+  node.data.inputs[field.name]?.label || field.title || field.name;
+
+const toBinding = (node: WorkflowInvocationNode, fieldName: string, fieldLabel: string, nodeLabel: string) => ({
+  fieldName,
+  label: `${nodeLabel} → ${fieldLabel}`,
+  nodeId: node.id,
+});
+
+const isSameBinding = (left: WorkflowImageBinding, right: WorkflowImageBinding): boolean =>
+  left.nodeId === right.nodeId && left.fieldName === right.fieldName;
+
+/** Chooses the first output that can actually run, rather than assuming the first output is runnable. */
+export const getDefaultLayerWorkflowSelection = (
+  outputs: readonly WorkflowImageBinding[],
+  getRunnableInputs: GetRunnableLayerWorkflowInputs
+): LayerWorkflowSelection => {
+  for (const output of outputs) {
+    const input = getRunnableInputs(output)[0];
+
+    if (input) {
+      return { destination: 'gallery', input, output };
+    }
+  }
+
+  return { destination: 'gallery', input: null, output: null };
+};
+
+/** Reconciles a changed output while preserving a still-runnable input by field identity. */
+export const reconcileLayerWorkflowSelection = (
+  current: LayerWorkflowSelection,
+  output: WorkflowImageBinding,
+  runnableInputs: readonly WorkflowImageBinding[]
+): LayerWorkflowSelection => {
+  const currentInput = current.input;
+  const preservedInput = currentInput
+    ? runnableInputs.find((candidate) => isSameBinding(candidate, currentInput))
+    : undefined;
+
+  return {
+    destination: current.destination,
+    input: preservedInput ?? runnableInputs[0] ?? null,
+    output,
+  };
+};
+
+const sortInputFields = (fields: FieldInputTemplate[]): FieldInputTemplate[] =>
+  fields
+    .map((field, index) => ({ field, index }))
+    .sort(
+      (left, right) =>
+        (left.field.uiOrder ?? Number.MAX_SAFE_INTEGER) - (right.field.uiOrder ?? Number.MAX_SAFE_INTEGER) ||
+        left.index - right.index
+    )
+    .map(({ field }) => field);
+
+/** Returns all unconnected, scalar ImageField inputs in document/UI order. */
+export const getLayerWorkflowInputs = (
+  document: ProjectGraphState,
+  templates: InvocationTemplates
+): WorkflowImageBinding[] => {
+  const index = createWorkflowGraphIndex(document.nodes, document.edges);
+  const connectedInputs = new Set(
+    getResolvedWorkflowEdgesIndexed(document.edges, index, templates).map(
+      (edge) => `${edge.target}:${edge.targetHandle}`
+    )
+  );
+  const bindings: WorkflowImageBinding[] = [];
+
+  for (const candidate of document.nodes) {
+    if (!isInvocationNode(candidate)) {
+      continue;
+    }
+
+    const template = templates[candidate.data.type];
+
+    if (!template) {
+      continue;
+    }
+
+    for (const field of sortInputFields(Object.values(template.inputs))) {
+      if (!isSingleImageField(field) || connectedInputs.has(`${candidate.id}:${field.name}`)) {
+        continue;
+      }
+
+      bindings.push(
+        toBinding(candidate, field.name, getInputLabel(candidate, field), getNodeLabel(candidate, templates))
+      );
+    }
+  }
+
+  return bindings;
+};
+
+/** Returns scalar ImageField outputs in document/field order, excluding the image echo primitive. */
+export const getLayerWorkflowOutputs = (
+  document: ProjectGraphState,
+  templates: InvocationTemplates
+): WorkflowImageBinding[] => {
+  const bindings: WorkflowImageBinding[] = [];
+
+  for (const candidate of document.nodes) {
+    if (!isInvocationNode(candidate) || candidate.data.type === 'image') {
+      continue;
+    }
+
+    const template = templates[candidate.data.type];
+
+    if (!template) {
+      continue;
+    }
+
+    for (const field of Object.values(template.outputs)) {
+      if (!isSingleImageField(field)) {
+        continue;
+      }
+
+      bindings.push(toBinding(candidate, field.name, field.title || field.name, getNodeLabel(candidate, templates)));
+    }
+  }
+
+  return bindings;
+};
+
+const getAvailableBinding = (
+  bindings: WorkflowImageBinding[],
+  selected: WorkflowImageBinding
+): WorkflowImageBinding | undefined => bindings.find((candidate) => isSameBinding(candidate, selected));
+
+const allocateNodeId = (graph: BackendGraphContract, base: string): string => {
+  if (!graph.nodes[base]) {
+    return base;
+  }
+
+  let suffix = 1;
+
+  while (graph.nodes[`${base}-${suffix}`]) {
+    suffix += 1;
+  }
+
+  return `${base}-${suffix}`;
+};
+
+/**
+ * Builds a throwaway backend graph that feeds one workflow image input and
+ * captures one workflow image output. The editable workflow document is never
+ * mutated.
+ */
+export const buildLayerWorkflowGraph = (options: BuildLayerWorkflowGraphOptions): BuiltLayerWorkflowGraph => {
+  const { document, imageName, input, output, templatesSnapshot } = options;
+
+  if (templatesSnapshot.status !== 'loaded') {
+    throw new Error('Workflow node definitions are not loaded.');
+  }
+
+  const templates = templatesSnapshot.templates;
+  const cloned = structuredClone(document);
+  const availableInput = getAvailableBinding(getLayerWorkflowInputs(cloned, templates), input);
+
+  if (!availableInput) {
+    throw new Error('The selected workflow input binding is no longer available.');
+  }
+
+  const availableOutput = getAvailableBinding(getLayerWorkflowOutputs(cloned, templates), output);
+
+  if (!availableOutput) {
+    throw new Error('The selected workflow output binding is no longer available.');
+  }
+
+  const inputNode = cloned.nodes.find(
+    (candidate): candidate is WorkflowInvocationNode => candidate.id === input.nodeId && isInvocationNode(candidate)
+  );
+  const inputTemplate = inputNode ? templates[inputNode.data.type]?.inputs[input.fieldName] : undefined;
+
+  if (!inputNode || !inputTemplate) {
+    throw new Error('The selected workflow input binding is no longer available.');
+  }
+
+  const isConnectionOnly = inputTemplate.input === 'connection';
+  const externallySatisfiedInputs = isConnectionOnly ? new Set([`${input.nodeId}:${input.fieldName}`]) : undefined;
+
+  if (!isConnectionOnly) {
+    const instance = inputNode.data.inputs[input.fieldName];
+
+    inputNode.data.inputs[input.fieldName] = {
+      label: instance?.label ?? '',
+      name: input.fieldName,
+      ...(instance?.description === undefined ? {} : { description: instance.description }),
+      value: { image_name: imageName },
+    };
+  }
+
+  const readiness = getProjectGraphReadiness(cloned, templatesSnapshot, { externallySatisfiedInputs });
+
+  if (!readiness.canInvoke) {
+    throw new Error(`Workflow is not ready: ${readiness.reasons.join(' ')}`);
+  }
+
+  const compiled = compileProjectGraph(cloned, templates);
+  const graph = compiled.backendGraph;
+
+  if (!graph) {
+    throw new Error('Workflow compilation did not produce a backend graph.');
+  }
+
+  for (const graphNode of Object.values(graph.nodes)) {
+    graphNode.is_intermediate = true;
+  }
+
+  if (isConnectionOnly) {
+    const sourceNodeId = allocateNodeId(graph, SOURCE_NODE_ID);
+    const targetNode = graph.nodes[input.nodeId];
+
+    if (!targetNode) {
+      throw new Error('The selected workflow input node was not compiled.');
+    }
+
+    delete targetNode[input.fieldName];
+    graph.nodes[sourceNodeId] = {
+      id: sourceNodeId,
+      image: { image_name: imageName },
+      is_intermediate: true,
+      type: 'image',
+      use_cache: false,
+    };
+    graph.edges.push({
+      destination: { field: input.fieldName, node_id: input.nodeId },
+      source: { field: 'image', node_id: sourceNodeId },
+    });
+  }
+
+  if (!graph.nodes[output.nodeId]) {
+    throw new Error('The selected workflow output node was not compiled.');
+  }
+
+  const outputNodeId = allocateNodeId(graph, CAPTURE_NODE_ID);
+
+  graph.nodes[outputNodeId] = {
+    id: outputNodeId,
+    is_intermediate: true,
+    type: 'image',
+    use_cache: false,
+  };
+  graph.edges.push({
+    destination: { field: 'image', node_id: outputNodeId },
+    source: { field: output.fieldName, node_id: output.nodeId },
+  });
+
+  return { graph, outputNodeId };
+};
+
+/** Keeps only inputs that produce a fully runnable graph after sentinel injection. */
+export const getRunnableLayerWorkflowInputs = (
+  document: ProjectGraphState,
+  templatesSnapshot: InvocationTemplatesSnapshot,
+  output: WorkflowImageBinding
+): WorkflowImageBinding[] => {
+  if (templatesSnapshot.status !== 'loaded') {
+    return [];
+  }
+
+  return getLayerWorkflowInputs(document, templatesSnapshot.templates).filter((input) => {
+    try {
+      buildLayerWorkflowGraph({
+        document,
+        imageName: READINESS_IMAGE_NAME,
+        input,
+        output,
+        templatesSnapshot,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  });
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/libraryCache.ts b/invokeai/frontend/webv2/src/workbench/workflows/libraryCache.ts
new file mode 100644
index 00000000000..ce69eaec0dd
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/libraryCache.ts
@@ -0,0 +1,46 @@
+import { getLibraryWorkflow, listLibraryWorkflows, type ListWorkflowsParams, type WorkflowLibraryPage } from './api';
+
+/**
+ * Session-lived cache in front of the workflow library API. The library
+ * dialog opens instantly on cached pages and revalidates in the background;
+ * any local mutation (save/delete) invalidates everything since it shifts
+ * ordering and pagination.
+ */
+
+const pageCache = new Map<string, WorkflowLibraryPage>();
+const workflowCache = new Map<string, Record<string, unknown>>();
+
+const getPageKey = (params: ListWorkflowsParams): string =>
+  `${params.category}|${params.page}|${params.perPage ?? 20}|${params.query?.trim() ?? ''}`;
+
+export const getCachedWorkflowPage = (params: ListWorkflowsParams): WorkflowLibraryPage | null =>
+  pageCache.get(getPageKey(params)) ?? null;
+
+/** Fetches a page and stores it; callers show `getCachedWorkflowPage` while this resolves. */
+export const listLibraryWorkflowsCached = async (params: ListWorkflowsParams): Promise<WorkflowLibraryPage> => {
+  const result = await listLibraryWorkflows(params);
+
+  pageCache.set(getPageKey(params), result);
+
+  return result;
+};
+
+/** Workflow payloads are immutable per save; cache hits skip the fetch entirely. */
+export const getLibraryWorkflowCached = async (workflowId: string): Promise<Record<string, unknown>> => {
+  const cached = workflowCache.get(workflowId);
+
+  if (cached) {
+    return cached;
+  }
+
+  const result = await getLibraryWorkflow(workflowId);
+
+  workflowCache.set(workflowId, result);
+
+  return result;
+};
+
+export const invalidateWorkflowLibraryCache = (): void => {
+  pageCache.clear();
+  workflowCache.clear();
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/templates.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/templates.test.ts
new file mode 100644
index 00000000000..29ae6b8e6aa
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/templates.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseFieldType, parseOpenApiToTemplates } from './templates';
+
+const openApiFixture = {
+  components: {
+    schemas: {
+      AddInvocation: {
+        category: 'math',
+        class: 'invocation',
+        classification: 'stable',
+        description: 'Adds two numbers',
+        node_pack: 'invokeai',
+        output: { $ref: '#/components/schemas/IntegerOutput' },
+        properties: {
+          a: {
+            default: 0,
+            field_kind: 'input',
+            input: 'any',
+            orig_required: false,
+            title: 'A',
+            type: 'integer',
+            ui_hidden: false,
+          },
+          b: {
+            default: 0,
+            field_kind: 'input',
+            input: 'any',
+            minimum: 0,
+            orig_required: false,
+            title: 'B',
+            type: 'integer',
+            ui_hidden: false,
+          },
+          id: { field_kind: 'internal', title: 'Id', type: 'string' },
+          is_intermediate: { default: false, field_kind: 'internal', type: 'boolean' },
+          type: { const: 'add', default: 'add', title: 'type' },
+          use_cache: { default: true, field_kind: 'internal', type: 'boolean' },
+        },
+        tags: ['math'],
+        title: 'Add Integers',
+        type: 'object',
+        version: '1.0.1',
+      },
+      DenoiseInvocation: {
+        class: 'invocation',
+        output: { $ref: '#/components/schemas/LatentsOutput' },
+        properties: {
+          latents: {
+            anyOf: [{ $ref: '#/components/schemas/LatentsField' }, { type: 'null' }],
+            field_kind: 'input',
+            input: 'connection',
+            orig_required: true,
+            title: 'Latents',
+          },
+          prompts: {
+            anyOf: [{ items: { type: 'string' }, type: 'array' }, { type: 'string' }],
+            field_kind: 'input',
+            orig_required: true,
+            title: 'Prompts',
+          },
+          scheduler: {
+            default: 'euler',
+            enum: ['euler', 'ddim'],
+            field_kind: 'input',
+            orig_required: false,
+            title: 'Scheduler',
+            type: 'string',
+          },
+          type: { const: 'denoise', default: 'denoise', title: 'type' },
+          use_cache: { default: true, field_kind: 'internal', type: 'boolean' },
+        },
+        title: 'DenoiseInvocation',
+        type: 'object',
+      },
+      GraphInvocation: {
+        class: 'invocation',
+        output: { $ref: '#/components/schemas/IntegerOutput' },
+        properties: {
+          type: { const: 'graph', default: 'graph', title: 'type' },
+        },
+        title: 'Graph',
+        type: 'object',
+      },
+      IntegerOutput: {
+        class: 'output',
+        properties: {
+          type: { const: 'integer_output', default: 'integer_output' },
+          value: { field_kind: 'output', title: 'Value', type: 'integer' },
+        },
+        type: 'object',
+      },
+      LatentsOutput: {
+        class: 'output',
+        properties: {
+          latents: {
+            allOf: [{ $ref: '#/components/schemas/LatentsField' }],
+            field_kind: 'output',
+            title: 'Latents',
+          },
+          type: { const: 'latents_output', default: 'latents_output' },
+        },
+        type: 'object',
+      },
+    },
+  },
+};
+
+describe('parseOpenApiToTemplates', () => {
+  const templates = parseOpenApiToTemplates(openApiFixture);
+
+  it('parses invocation schemas into templates, skipping the denylist', () => {
+    expect(Object.keys(templates).sort()).toEqual(['add', 'denoise']);
+
+    const add = templates.add;
+
+    expect(add?.title).toBe('Add Integers');
+    expect(add?.version).toBe('1.0.1');
+    expect(add?.category).toBe('math');
+    expect(add?.outputType).toBe('integer_output');
+  });
+
+  it('parses input templates with constraints and skips reserved fields', () => {
+    const add = templates.add;
+
+    expect(Object.keys(add?.inputs ?? {}).sort()).toEqual(['a', 'b']);
+    expect(add?.inputs.b?.minimum).toBe(0);
+    expect(add?.inputs.a?.type).toEqual({ batch: false, cardinality: 'SINGLE', name: 'IntegerField' });
+  });
+
+  it('parses ref, nullable-anyOf, single-or-collection, and enum field types', () => {
+    const denoise = templates.denoise;
+
+    expect(denoise?.inputs.latents?.type).toEqual({ batch: false, cardinality: 'SINGLE', name: 'LatentsField' });
+    expect(denoise?.inputs.latents?.input).toBe('connection');
+    expect(denoise?.inputs.latents?.required).toBe(true);
+    expect(denoise?.inputs.prompts?.type).toEqual({
+      batch: false,
+      cardinality: 'SINGLE_OR_COLLECTION',
+      name: 'StringField',
+    });
+    expect(denoise?.inputs.scheduler?.type.name).toBe('EnumField');
+    expect(denoise?.inputs.scheduler?.options).toEqual(['euler', 'ddim']);
+  });
+
+  it('parses output templates', () => {
+    expect(templates.denoise?.outputs.latents?.type.name).toBe('LatentsField');
+    expect(templates.add?.outputs.value?.type.name).toBe('IntegerField');
+  });
+});
+
+describe('parseFieldType', () => {
+  it('parses collections of refs and primitives', () => {
+    expect(parseFieldType({ items: { $ref: '#/components/schemas/ImageField' }, type: 'array' })).toEqual({
+      batch: false,
+      cardinality: 'COLLECTION',
+      name: 'ImageField',
+    });
+    expect(parseFieldType({ items: { type: 'integer' }, type: 'array' })).toEqual({
+      batch: false,
+      cardinality: 'COLLECTION',
+      name: 'IntegerField',
+    });
+  });
+
+  it('returns null for unparseable shapes instead of throwing', () => {
+    expect(parseFieldType({ anyOf: [{ type: 'string' }, { type: 'integer' }, { type: 'boolean' }] })).toBeNull();
+    expect(parseFieldType('nonsense')).toBeNull();
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/templates.ts b/invokeai/frontend/webv2/src/workbench/workflows/templates.ts
new file mode 100644
index 00000000000..fbe8cc841c2
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/templates.ts
@@ -0,0 +1,386 @@
+import { apiFetchJson, getApiErrorMessage } from '@workbench/backend/http';
+import { createExternalStore } from '@workbench/externalStore';
+
+import type {
+  FieldInputTemplate,
+  FieldOutputTemplate,
+  FieldType,
+  InvocationTemplate,
+  InvocationTemplates,
+} from './types';
+
+/**
+ * Invocation templates parsed from the backend OpenAPI schema. They are
+ * session-lived, backend-owned data shared by every workflow surface, so they
+ * live in an external store (the same pattern as the models library) rather
+ * than in project state.
+ */
+
+export interface InvocationTemplatesSnapshot {
+  status: 'idle' | 'loading' | 'loaded' | 'error';
+  error: string | null;
+  templates: InvocationTemplates;
+}
+
+const store = createExternalStore<InvocationTemplatesSnapshot>({ error: null, status: 'idle', templates: {} });
+
+type JsonObject = Record<string, unknown>;
+
+const isJsonObject = (value: unknown): value is JsonObject => typeof value === 'object' && value !== null;
+
+/** Invocations that exist in the schema but are not user-placeable nodes. */
+const INVOCATION_DENYLIST = new Set(['graph', 'linear_ui_output']);
+
+const RESERVED_INPUT_FIELD_NAMES = new Set(['id', 'type', 'use_cache', 'is_intermediate']);
+const RESERVED_FIELD_TYPE_NAMES = new Set(['IsIntermediate']);
+
+const OPENAPI_TO_FIELD_TYPE_MAP: Record<string, string> = {
+  boolean: 'BooleanField',
+  integer: 'IntegerField',
+  number: 'FloatField',
+  string: 'StringField',
+};
+
+const COLLECTION_OVERRIDE_TYPE_NAMES = new Set(['CollectionField']);
+
+const refToSchemaName = (ref: unknown): string | null => {
+  if (typeof ref !== 'string') {
+    return null;
+  }
+
+  return ref.split('/').at(-1) ?? null;
+};
+
+const getRef = (schema: JsonObject): string | null => refToSchemaName(schema.$ref);
+
+/**
+ * Derives the field type from an OpenAPI property schema. Ported from the
+ * legacy `parseFieldType`; returns null instead of throwing so unparseable
+ * fields are skipped rather than failing the whole template.
+ */
+export const parseFieldType = (schema: unknown): FieldType | null => {
+  if (!isJsonObject(schema)) {
+    return null;
+  }
+
+  const ref = getRef(schema);
+
+  if (ref) {
+    return { batch: false, cardinality: 'SINGLE', name: ref };
+  }
+
+  // `Literal["value"]` pydantic fields arrive as `const` — treated as an enum.
+  if (schema.const !== undefined || schema.enum !== undefined) {
+    return { batch: false, cardinality: 'SINGLE', name: 'EnumField' };
+  }
+
+  if (schema.type === undefined) {
+    if (Array.isArray(schema.allOf) && isJsonObject(schema.allOf[0])) {
+      const name = getRef(schema.allOf[0]);
+
+      return name ? { batch: false, cardinality: 'SINGLE', name } : null;
+    }
+
+    if (Array.isArray(schema.anyOf)) {
+      const variants = schema.anyOf.filter(
+        (variant): variant is JsonObject => isJsonObject(variant) && variant.type !== 'null'
+      );
+
+      if (variants.length === 1) {
+        return parseFieldType(variants[0]);
+      }
+
+      // `T | list[T]` unions become SINGLE_OR_COLLECTION of the base type.
+      if (variants.length === 2) {
+        const arrayVariant = variants.find((variant) => variant.type === 'array');
+        const itemVariant = variants.find((variant) => variant.type !== 'array');
+
+        if (arrayVariant && itemVariant && isJsonObject(arrayVariant.items)) {
+          const arrayItemName =
+            getRef(arrayVariant.items) ??
+            (typeof arrayVariant.items.type === 'string' ? arrayVariant.items.type : null);
+          const itemName = getRef(itemVariant) ?? (typeof itemVariant.type === 'string' ? itemVariant.type : null);
+
+          if (arrayItemName && arrayItemName === itemName) {
+            return {
+              batch: false,
+              cardinality: 'SINGLE_OR_COLLECTION',
+              name: OPENAPI_TO_FIELD_TYPE_MAP[itemName] ?? itemName,
+            };
+          }
+        }
+      }
+
+      return null;
+    }
+
+    return null;
+  }
+
+  if (schema.type === 'array') {
+    if (!isJsonObject(schema.items)) {
+      return null;
+    }
+
+    const itemRef = getRef(schema.items);
+
+    if (itemRef) {
+      return { batch: false, cardinality: 'COLLECTION', name: itemRef };
+    }
+
+    const itemType = typeof schema.items.type === 'string' ? OPENAPI_TO_FIELD_TYPE_MAP[schema.items.type] : undefined;
+
+    return itemType ? { batch: false, cardinality: 'COLLECTION', name: itemType } : null;
+  }
+
+  if (typeof schema.type === 'string') {
+    const name = OPENAPI_TO_FIELD_TYPE_MAP[schema.type];
+
+    return name ? { batch: false, cardinality: 'SINGLE', name } : null;
+  }
+
+  return null;
+};
+
+const getUiTypeOverride = (property: JsonObject): FieldType | null => {
+  if (typeof property.ui_type !== 'string') {
+    return null;
+  }
+
+  return {
+    batch: false,
+    cardinality: COLLECTION_OVERRIDE_TYPE_NAMES.has(property.ui_type) ? 'COLLECTION' : 'SINGLE',
+    name: property.ui_type,
+  };
+};
+
+const startCase = (value: string): string =>
+  value
+    .replace(/[_-]+/g, ' ')
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+    .trim();
+
+const getNumberOrNull = (value: unknown): number | null => (typeof value === 'number' ? value : null);
+
+const getStringArrayOrNull = (value: unknown): string[] | null =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : null;
+
+const getDefaultValueForType = (type: FieldType, options: string[] | null): unknown => {
+  if (type.cardinality === 'COLLECTION') {
+    return undefined;
+  }
+
+  switch (type.name) {
+    case 'StringField':
+      return '';
+    case 'IntegerField':
+    case 'FloatField':
+      return 0;
+    case 'BooleanField':
+      return false;
+    case 'EnumField':
+      return options?.[0];
+    default:
+      return undefined;
+  }
+};
+
+const buildInputTemplate = (name: string, property: JsonObject, type: FieldType): FieldInputTemplate => {
+  const enumValues = Array.isArray(property.enum)
+    ? property.enum
+    : property.const !== undefined
+      ? [property.const]
+      : null;
+  const options = enumValues ? enumValues.filter((value): value is string => typeof value === 'string') : null;
+  const input = property.input === 'connection' || property.input === 'direct' ? property.input : 'any';
+  const uiChoiceLabels = isJsonObject(property.ui_choice_labels)
+    ? Object.fromEntries(
+        Object.entries(property.ui_choice_labels).filter(
+          (entry): entry is [string, string] => typeof entry[1] === 'string'
+        )
+      )
+    : null;
+
+  return {
+    default: property.default ?? getDefaultValueForType(type, options),
+    description: typeof property.description === 'string' ? property.description : '',
+    exclusiveMaximum: getNumberOrNull(property.exclusiveMaximum),
+    exclusiveMinimum: getNumberOrNull(property.exclusiveMinimum),
+    input,
+    maximum: getNumberOrNull(property.maximum),
+    minimum: getNumberOrNull(property.minimum),
+    multipleOf: getNumberOrNull(property.multipleOf),
+    name,
+    options,
+    required: property.orig_required === true,
+    title: typeof property.title === 'string' ? property.title : startCase(name),
+    type,
+    uiChoiceLabels,
+    uiComponent:
+      property.ui_component === 'slider' || property.ui_component === 'textarea' ? property.ui_component : null,
+    uiHidden: property.ui_hidden === true,
+    uiModelBase: getStringArrayOrNull(property.ui_model_base),
+    uiModelType: getStringArrayOrNull(property.ui_model_type),
+    uiOrder: getNumberOrNull(property.ui_order),
+  };
+};
+
+const parseFieldProperty = (property: JsonObject): FieldType | null => {
+  const override = getUiTypeOverride(property);
+  const parsed = parseFieldType(property);
+
+  if (override) {
+    if (parsed && (parsed.name !== override.name || parsed.cardinality !== override.cardinality)) {
+      override.originalType = parsed;
+    }
+
+    return override;
+  }
+
+  return parsed;
+};
+
+const parseInvocationSchema = (schema: JsonObject, schemas: JsonObject): InvocationTemplate | null => {
+  const properties = isJsonObject(schema.properties) ? schema.properties : null;
+  const typeProperty = properties && isJsonObject(properties.type) ? properties.type : null;
+  const type = typeProperty && typeof typeProperty.default === 'string' ? typeProperty.default : null;
+
+  if (!properties || !type || INVOCATION_DENYLIST.has(type)) {
+    return null;
+  }
+
+  const inputs: Record<string, FieldInputTemplate> = {};
+
+  for (const [name, rawProperty] of Object.entries(properties)) {
+    if (
+      RESERVED_INPUT_FIELD_NAMES.has(name) ||
+      (type === 'iterate' && name === 'index') ||
+      !isJsonObject(rawProperty)
+    ) {
+      continue;
+    }
+
+    if (rawProperty.field_kind !== 'input') {
+      continue;
+    }
+
+    const fieldType = parseFieldProperty(rawProperty);
+
+    if (!fieldType || RESERVED_FIELD_TYPE_NAMES.has(fieldType.name)) {
+      continue;
+    }
+
+    inputs[name] = buildInputTemplate(name, rawProperty, fieldType);
+  }
+
+  const outputRefName = isJsonObject(schema.output) ? getRef(schema.output) : null;
+  const outputSchema =
+    outputRefName && isJsonObject(schemas[outputRefName]) ? (schemas[outputRefName] as JsonObject) : null;
+  const outputProperties = outputSchema && isJsonObject(outputSchema.properties) ? outputSchema.properties : null;
+
+  if (!outputProperties) {
+    return null;
+  }
+
+  const outputTypeProperty = isJsonObject(outputProperties.type) ? outputProperties.type : null;
+  const outputType =
+    outputTypeProperty && typeof outputTypeProperty.default === 'string' ? outputTypeProperty.default : '';
+  const outputs: Record<string, FieldOutputTemplate> = {};
+
+  for (const [name, rawProperty] of Object.entries(outputProperties)) {
+    if (name === 'type' || !isJsonObject(rawProperty) || rawProperty.field_kind !== 'output') {
+      continue;
+    }
+
+    const fieldType = parseFieldProperty(rawProperty);
+
+    if (!fieldType) {
+      continue;
+    }
+
+    outputs[name] = {
+      description: typeof rawProperty.description === 'string' ? rawProperty.description : '',
+      name,
+      title: typeof rawProperty.title === 'string' ? rawProperty.title : startCase(name),
+      type: fieldType,
+    };
+  }
+
+  const useCacheProperty = isJsonObject(properties.use_cache) ? properties.use_cache : null;
+
+  return {
+    category: typeof schema.category === 'string' ? schema.category : 'other',
+    classification: typeof schema.classification === 'string' ? schema.classification : 'stable',
+    description: typeof schema.description === 'string' ? schema.description : '',
+    inputs,
+    nodePack: typeof schema.node_pack === 'string' ? schema.node_pack : 'invokeai',
+    outputs,
+    outputType,
+    tags: getStringArrayOrNull(schema.tags) ?? [],
+    title: typeof schema.title === 'string' ? schema.title.replace('Invocation', '').trim() : type,
+    type,
+    useCache: useCacheProperty?.default !== false,
+    version: typeof schema.version === 'string' ? schema.version : '1.0.0',
+  };
+};
+
+/** Parses a full OpenAPI document into invocation templates. Exported for tests. */
+export const parseOpenApiToTemplates = (openApiDocument: unknown): InvocationTemplates => {
+  if (!isJsonObject(openApiDocument)) {
+    return {};
+  }
+
+  const components = isJsonObject(openApiDocument.components) ? openApiDocument.components : null;
+  const schemas = components && isJsonObject(components.schemas) ? components.schemas : null;
+
+  if (!schemas) {
+    return {};
+  }
+
+  const templates: InvocationTemplates = {};
+
+  for (const schema of Object.values(schemas)) {
+    if (!isJsonObject(schema) || schema.class !== 'invocation') {
+      continue;
+    }
+
+    const template = parseInvocationSchema(schema, schemas);
+
+    if (template) {
+      templates[template.type] = template;
+    }
+  }
+
+  return templates;
+};
+
+export const refreshInvocationTemplates = async (): Promise<void> => {
+  store.patchSnapshot({ error: null, status: 'loading' });
+
+  try {
+    // FastAPI serves the schema at the app root (proxied in dev), not under /api.
+    const openApiDocument = await apiFetchJson<unknown>('/openapi.json');
+
+    store.setSnapshot({ error: null, status: 'loaded', templates: parseOpenApiToTemplates(openApiDocument) });
+  } catch (error) {
+    store.patchSnapshot({
+      error: getApiErrorMessage(error, 'Failed to load node definitions from the backend.'),
+      status: 'error',
+    });
+  }
+};
+
+export const ensureInvocationTemplatesLoaded = (): void => {
+  const { status } = store.getSnapshot();
+
+  if (status === 'idle' || status === 'error') {
+    void refreshInvocationTemplates();
+  }
+};
+
+export const useInvocationTemplatesSnapshot = (): InvocationTemplatesSnapshot => store.useSnapshot();
+
+export const useInvocationTemplatesSelector = store.useSelector;
+
+/** Imperative read for the workbench reducer and route validation. */
+export const getInvocationTemplatesSnapshot = (): InvocationTemplatesSnapshot => store.getSnapshot();
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/types.ts b/invokeai/frontend/webv2/src/workbench/workflows/types.ts
new file mode 100644
index 00000000000..a2164a1963b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/types.ts
@@ -0,0 +1,239 @@
+/**
+ * Workflow domain types.
+ *
+ * The project graph is a *document*: an editable node-and-edge workflow plus a
+ * form describing its Linear UI. It compiles into the queue-facing
+ * `GraphContract` only at invocation time, so queued snapshots stay immutable
+ * while the document keeps evolving. The serialized shape stays compatible
+ * with the legacy WorkflowV3 format so workflows round-trip between the v6
+ * editor, the workflow library backend, and this workbench.
+ */
+
+export type FieldCardinality = 'SINGLE' | 'COLLECTION' | 'SINGLE_OR_COLLECTION';
+
+export interface FieldType {
+  name: string;
+  cardinality: FieldCardinality;
+  batch: boolean;
+  /** Set when a `ui_type` override replaced the parsed type; both sides count for connection equality. */
+  originalType?: FieldType;
+}
+
+export interface FieldInputTemplate {
+  name: string;
+  title: string;
+  description: string;
+  type: FieldType;
+  required: boolean;
+  /** How the field receives data: only via edge, only direct value, or either. */
+  input: 'connection' | 'direct' | 'any';
+  default?: unknown;
+  uiHidden: boolean;
+  uiOrder: number | null;
+  uiComponent: 'slider' | 'textarea' | null;
+  uiChoiceLabels: Record<string, string> | null;
+  /** Enum choices when the field is an EnumField. */
+  options: string[] | null;
+  minimum: number | null;
+  maximum: number | null;
+  exclusiveMinimum: number | null;
+  exclusiveMaximum: number | null;
+  multipleOf: number | null;
+  uiModelBase: string[] | null;
+  uiModelType: string[] | null;
+}
+
+export interface FieldOutputTemplate {
+  name: string;
+  title: string;
+  description: string;
+  type: FieldType;
+}
+
+export interface InvocationTemplate {
+  type: string;
+  title: string;
+  description: string;
+  tags: string[];
+  category: string;
+  version: string;
+  useCache: boolean;
+  nodePack: string;
+  classification: string;
+  inputs: Record<string, FieldInputTemplate>;
+  outputs: Record<string, FieldOutputTemplate>;
+  outputType: string;
+}
+
+export type InvocationTemplates = Record<string, InvocationTemplate>;
+
+export interface XYPosition {
+  x: number;
+  y: number;
+}
+
+/** A direct input value on a node. Connection-only fields keep `value` undefined. */
+export interface WorkflowFieldInstance {
+  name: string;
+  label: string;
+  /** User override of the template's field description (shown in the Linear UI). */
+  description?: string;
+  value?: unknown;
+}
+
+export interface WorkflowInvocationNodeData {
+  type: string;
+  version: string;
+  label: string;
+  notes: string;
+  isOpen: boolean;
+  isIntermediate: boolean;
+  useCache: boolean;
+  nodePack: string;
+  inputs: Record<string, WorkflowFieldInstance>;
+}
+
+export interface WorkflowInvocationNode {
+  id: string;
+  type: 'invocation';
+  position: XYPosition;
+  data: WorkflowInvocationNodeData;
+}
+
+export interface WorkflowNotesNode {
+  id: string;
+  type: 'notes';
+  position: XYPosition;
+  data: {
+    label: string;
+    notes: string;
+  };
+}
+
+/** UI-only node mirroring the legacy `current_image` node: shows the latest run output / progress image. */
+export interface WorkflowCurrentImageNode {
+  id: string;
+  type: 'current_image';
+  position: XYPosition;
+  data: {
+    label: string;
+  };
+}
+
+export interface WorkflowConnectorNode {
+  id: string;
+  type: 'connector';
+  position: XYPosition;
+  data: {
+    label: string;
+  };
+}
+
+export type WorkflowNode =
+  | WorkflowInvocationNode
+  | WorkflowNotesNode
+  | WorkflowCurrentImageNode
+  | WorkflowConnectorNode;
+
+export interface WorkflowEdge {
+  id: string;
+  type: 'default';
+  source: string;
+  target: string;
+  sourceHandle: string;
+  targetHandle: string;
+}
+
+export interface FieldIdentifier {
+  nodeId: string;
+  fieldName: string;
+}
+
+export interface ContainerFormElement {
+  id: string;
+  type: 'container';
+  parentId?: string;
+  data: {
+    layout: 'row' | 'column';
+    children: string[];
+  };
+}
+
+export interface NodeFieldFormElement {
+  id: string;
+  type: 'node-field';
+  parentId?: string;
+  data: {
+    fieldIdentifier: FieldIdentifier;
+    showDescription: boolean;
+  };
+}
+
+export interface HeadingFormElement {
+  id: string;
+  type: 'heading';
+  parentId?: string;
+  data: {
+    content: string;
+  };
+}
+
+export interface TextFormElement {
+  id: string;
+  type: 'text';
+  parentId?: string;
+  data: {
+    content: string;
+  };
+}
+
+export interface DividerFormElement {
+  id: string;
+  type: 'divider';
+  parentId?: string;
+}
+
+export type WorkflowFormElement =
+  | ContainerFormElement
+  | NodeFieldFormElement
+  | HeadingFormElement
+  | TextFormElement
+  | DividerFormElement;
+
+/** The Linear UI description: a tree of form elements rooted in a column container. */
+export interface WorkflowForm {
+  rootElementId: string;
+  elements: Record<string, WorkflowFormElement>;
+}
+
+export interface WorkflowMetadata {
+  name: string;
+  description: string;
+  author: string;
+  contact: string;
+  tags: string;
+  notes: string;
+  /** The workflow's own semver, distinct from the document schema version. */
+  workflowVersion: string;
+}
+
+/** The project-owned workflow document. `version: 2` distinguishes it from the Phase-1 placeholder graph. */
+export interface ProjectGraphState extends WorkflowMetadata {
+  id: string;
+  version: 2;
+  /** Backend workflow-library binding when the document was loaded from or saved to the library. */
+  libraryWorkflowId?: string;
+  nodes: WorkflowNode[];
+  edges: WorkflowEdge[];
+  form: WorkflowForm;
+  updatedAt: string;
+}
+
+export const isInvocationNode = (node: WorkflowNode): node is WorkflowInvocationNode => node.type === 'invocation';
+
+export const isNotesNode = (node: WorkflowNode): node is WorkflowNotesNode => node.type === 'notes';
+
+export const isCurrentImageNode = (node: WorkflowNode): node is WorkflowCurrentImageNode =>
+  node.type === 'current_image';
+
+export const isConnectorNode = (node: WorkflowNode): node is WorkflowConnectorNode => node.type === 'connector';
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/validation.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/validation.test.ts
new file mode 100644
index 00000000000..912ddcda684
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/validation.test.ts
@@ -0,0 +1,571 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  FieldType,
+  InvocationTemplates,
+  ProjectGraphState,
+  WorkflowConnectorNode,
+  WorkflowEdge,
+  WorkflowInvocationNode,
+} from './types';
+
+import {
+  getCompatibleInputTemplate,
+  getCompatibleOutputTemplate,
+  getWorkflowSourceFieldType,
+  getWorkflowTargetFieldType,
+  hasAnyCycle,
+  validateConnection,
+  validateConnectionTypes,
+  wouldCreateCycle,
+} from './validation';
+
+const single = (name: string): FieldType => ({ batch: false, cardinality: 'SINGLE', name });
+const collection = (name: string): FieldType => ({ batch: false, cardinality: 'COLLECTION', name });
+const singleOrCollection = (name: string): FieldType => ({ batch: false, cardinality: 'SINGLE_OR_COLLECTION', name });
+
+describe('validateConnectionTypes', () => {
+  it('accepts equal types and rejects mismatched names', () => {
+    expect(validateConnectionTypes(single('ImageField'), single('ImageField'))).toBe(true);
+    expect(validateConnectionTypes(single('ImageField'), single('LatentsField'))).toBe(false);
+  });
+
+  it('applies numeric/string subtype promotions with matching cardinality', () => {
+    expect(validateConnectionTypes(single('IntegerField'), single('FloatField'))).toBe(true);
+    expect(validateConnectionTypes(single('FloatField'), single('StringField'))).toBe(true);
+    expect(validateConnectionTypes(single('FloatField'), single('IntegerField'))).toBe(false);
+    expect(validateConnectionTypes(collection('IntegerField'), single('FloatField'))).toBe(false);
+  });
+
+  it('handles SINGLE_OR_COLLECTION targets and generic collections', () => {
+    expect(validateConnectionTypes(single('StringField'), singleOrCollection('StringField'))).toBe(true);
+    expect(validateConnectionTypes(collection('StringField'), singleOrCollection('StringField'))).toBe(true);
+    expect(validateConnectionTypes(collection('StringField'), collection('CollectionField'))).toBe(true);
+    expect(validateConnectionTypes(single('CollectionField'), collection('ImageField'))).toBe(true);
+  });
+
+  it('handles CollectionItemField and AnyField wildcards', () => {
+    expect(validateConnectionTypes(single('CollectionItemField'), single('ImageField'))).toBe(true);
+    expect(validateConnectionTypes(single('ImageField'), single('CollectionItemField'))).toBe(true);
+    expect(validateConnectionTypes(single('ImageField'), single('AnyField'))).toBe(true);
+    expect(validateConnectionTypes(single('AnyField'), single('ImageField'))).toBe(true);
+  });
+
+  it('rejects batch/non-batch mixes', () => {
+    expect(validateConnectionTypes({ ...single('IntegerField'), batch: true }, single('IntegerField'))).toBe(false);
+  });
+});
+
+describe('cycle detection', () => {
+  const edges: WorkflowEdge[] = [
+    { id: 'e1', source: 'a', sourceHandle: 'out', target: 'b', targetHandle: 'in', type: 'default' },
+    { id: 'e2', source: 'b', sourceHandle: 'out', target: 'c', targetHandle: 'in', type: 'default' },
+  ];
+
+  it('detects when a new connection would close a loop', () => {
+    expect(wouldCreateCycle('c', 'a', edges)).toBe(true);
+    expect(wouldCreateCycle('a', 'c', edges)).toBe(false);
+  });
+
+  it('detects existing cycles in a whole graph', () => {
+    const nodes = ['a', 'b', 'c'].map((id) => ({ id }) as { id: string });
+    const cyclic = [
+      ...edges,
+      { id: 'e3', source: 'c', sourceHandle: 'out', target: 'a', targetHandle: 'in', type: 'default' as const },
+    ];
+
+    expect(hasAnyCycle(nodes as never, edges)).toBe(false);
+    expect(hasAnyCycle(nodes as never, cyclic)).toBe(true);
+  });
+});
+
+const makeNode = (id: string, type: string): WorkflowInvocationNode => ({
+  data: {
+    inputs: {},
+    isIntermediate: true,
+    isOpen: true,
+    label: '',
+    nodePack: 'invokeai',
+    notes: '',
+    type,
+    useCache: true,
+    version: '1.0.0',
+  },
+  id,
+  position: { x: 0, y: 0 },
+  type: 'invocation',
+});
+
+const makeConnector = (id: string): WorkflowConnectorNode => ({
+  data: { label: 'Connector' },
+  id,
+  position: { x: 0, y: 0 },
+  type: 'connector',
+});
+
+const templates: InvocationTemplates = {
+  collect: {
+    category: 'util',
+    classification: 'stable',
+    description: '',
+    inputs: {
+      item: {
+        default: undefined,
+        description: '',
+        exclusiveMaximum: null,
+        exclusiveMinimum: null,
+        input: 'connection',
+        maximum: null,
+        minimum: null,
+        multipleOf: null,
+        name: 'item',
+        options: null,
+        required: true,
+        title: 'Item',
+        type: { batch: false, cardinality: 'SINGLE', name: 'CollectionItemField' },
+        uiChoiceLabels: null,
+        uiComponent: null,
+        uiHidden: false,
+        uiModelBase: null,
+        uiModelType: null,
+        uiOrder: null,
+      },
+    },
+    nodePack: 'invokeai',
+    outputs: {},
+    outputType: 'collect_output',
+    tags: [],
+    title: 'Collect',
+    type: 'collect',
+    useCache: true,
+    version: '1.0.0',
+  },
+  number: {
+    category: 'math',
+    classification: 'stable',
+    description: '',
+    inputs: {
+      value: {
+        default: 0,
+        description: '',
+        exclusiveMaximum: null,
+        exclusiveMinimum: null,
+        input: 'any',
+        maximum: null,
+        minimum: null,
+        multipleOf: null,
+        name: 'value',
+        options: null,
+        required: false,
+        title: 'Value',
+        type: { batch: false, cardinality: 'SINGLE', name: 'IntegerField' },
+        uiChoiceLabels: null,
+        uiComponent: null,
+        uiHidden: false,
+        uiModelBase: null,
+        uiModelType: null,
+        uiOrder: null,
+      },
+    },
+    nodePack: 'invokeai',
+    outputs: {
+      value: {
+        description: '',
+        name: 'value',
+        title: 'Value',
+        type: { batch: false, cardinality: 'SINGLE', name: 'IntegerField' },
+      },
+    },
+    outputType: 'integer_output',
+    tags: [],
+    title: 'Number',
+    type: 'number',
+    useCache: true,
+    version: '1.0.0',
+  },
+};
+
+describe('getCompatibleInputTemplate', () => {
+  it('returns the first visible connectable input by UI order', () => {
+    const baseInput = templates.number.inputs.value;
+    const template = {
+      ...templates.number,
+      inputs: {
+        direct: { ...baseInput, input: 'direct' as const, name: 'direct', title: 'Direct', uiOrder: 0 },
+        hidden: { ...baseInput, name: 'hidden', title: 'Hidden', uiHidden: true, uiOrder: 1 },
+        late: { ...baseInput, name: 'late', title: 'Late', uiOrder: 3 },
+        early: { ...baseInput, name: 'early', title: 'Early', uiOrder: 2 },
+      },
+    };
+
+    expect(getCompatibleInputTemplate(template, single('IntegerField'))?.name).toBe('early');
+    expect(getCompatibleInputTemplate(template, single('ImageField'))).toBeNull();
+    expect(getCompatibleInputTemplate(template, null)?.name).toBe('early');
+  });
+});
+
+describe('getWorkflowSourceFieldType', () => {
+  it('resolves typed and untyped connector outputs', () => {
+    const document: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [],
+      nodes: [makeConnector('connector')],
+    };
+
+    expect(getWorkflowSourceFieldType(document, templates, 'connector', 'out')).toBeNull();
+
+    const upstreamDocument: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'e1',
+          source: 'n1',
+          sourceHandle: 'value',
+          target: 'connector',
+          targetHandle: 'in',
+          type: 'default',
+        },
+      ],
+      nodes: [makeNode('n1', 'number'), makeConnector('connector')],
+    };
+
+    expect(getWorkflowSourceFieldType(upstreamDocument, templates, 'connector', 'out')).toEqual(single('IntegerField'));
+  });
+
+  it('resolves connector outputs from downstream targets when no input is connected', () => {
+    const document: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'connector-out',
+          source: 'connector',
+          sourceHandle: 'out',
+          target: 'n1',
+          targetHandle: 'value',
+          type: 'default',
+        },
+      ],
+      nodes: [makeConnector('connector'), makeNode('n1', 'number')],
+    };
+
+    expect(getWorkflowSourceFieldType(document, templates, 'connector', 'out')).toEqual(single('IntegerField'));
+  });
+
+  it('leaves fan-out connector outputs untyped when downstream targets disagree', () => {
+    const mixedTemplates: InvocationTemplates = {
+      ...templates,
+      text: {
+        ...templates.number,
+        inputs: {
+          value: { ...templates.number.inputs.value, type: single('StringField') },
+        },
+        outputs: {
+          value: { ...templates.number.outputs.value, type: single('StringField') },
+        },
+        type: 'text',
+      },
+    };
+    const document: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'connector-out-string',
+          source: 'connector',
+          sourceHandle: 'out',
+          target: 'text-1',
+          targetHandle: 'value',
+          type: 'default',
+        },
+        {
+          id: 'connector-out-number',
+          source: 'connector',
+          sourceHandle: 'out',
+          target: 'number-1',
+          targetHandle: 'value',
+          type: 'default',
+        },
+      ],
+      nodes: [makeConnector('connector'), makeNode('text-1', 'text'), makeNode('number-1', 'number')],
+    };
+
+    expect(getWorkflowSourceFieldType(document, mixedTemplates, 'connector', 'out')).toBeNull();
+  });
+});
+
+describe('getCompatibleOutputTemplate', () => {
+  it('returns the first output compatible with the target type', () => {
+    expect(getCompatibleOutputTemplate(templates.number, single('IntegerField'))?.name).toBe('value');
+    expect(getCompatibleOutputTemplate(templates.number, single('ImageField'))).toBeNull();
+  });
+
+  it('accepts any output for untyped connector targets', () => {
+    expect(getCompatibleOutputTemplate(templates.number, null)?.name).toBe('value');
+    expect(getCompatibleOutputTemplate(templates.collect, null)).toBeNull();
+  });
+});
+
+describe('getWorkflowTargetFieldType', () => {
+  it('resolves connectable invocation inputs and connector inputs', () => {
+    const document: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [],
+      nodes: [makeNode('n1', 'number'), makeConnector('connector')],
+    };
+
+    expect(getWorkflowTargetFieldType(document, templates, 'n1', 'value')).toEqual(single('IntegerField'));
+    expect(getWorkflowTargetFieldType(document, templates, 'connector', 'in')).toBeNull();
+  });
+
+  it('rejects direct-only inputs', () => {
+    const directTemplates: InvocationTemplates = {
+      number: {
+        ...templates.number,
+        inputs: {
+          value: { ...templates.number.inputs.value, input: 'direct' },
+        },
+      },
+    };
+
+    expect(
+      getWorkflowTargetFieldType({ edges: [], nodes: [makeNode('n1', 'number')] }, directTemplates, 'n1', 'value')
+    ).toBe(undefined);
+  });
+
+  it('resolves connector inputs from downstream targets', () => {
+    const document: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'connector-out',
+          source: 'connector',
+          sourceHandle: 'out',
+          target: 'n1',
+          targetHandle: 'value',
+          type: 'default',
+        },
+      ],
+      nodes: [makeConnector('connector'), makeNode('n1', 'number')],
+    };
+
+    expect(getWorkflowTargetFieldType(document, templates, 'connector', 'in')).toEqual(single('IntegerField'));
+  });
+});
+
+describe('validateConnection', () => {
+  const baseDocument: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+    edges: [],
+    nodes: [makeNode('n1', 'number'), makeNode('n2', 'number'), makeNode('c1', 'collect')],
+  };
+
+  it('accepts a valid connection', () => {
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'n1', targetHandle: 'value', targetNodeId: 'n2' },
+        baseDocument,
+        templates
+      )
+    ).toBeNull();
+  });
+
+  it('rejects self-connections and unknown fields', () => {
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'n1', targetHandle: 'value', targetNodeId: 'n1' },
+        baseDocument,
+        templates
+      )
+    ).toMatch(/itself/);
+    expect(
+      validateConnection(
+        { sourceHandle: 'nope', sourceNodeId: 'n1', targetHandle: 'value', targetNodeId: 'n2' },
+        baseDocument,
+        templates
+      )
+    ).toMatch(/no known definition/);
+  });
+
+  it('rejects a second edge into an occupied input, except for collect item', () => {
+    const document = {
+      ...baseDocument,
+      edges: [
+        {
+          id: 'e1',
+          source: 'n1',
+          sourceHandle: 'value',
+          target: 'n2',
+          targetHandle: 'value',
+          type: 'default' as const,
+        },
+        { id: 'e2', source: 'n1', sourceHandle: 'value', target: 'c1', targetHandle: 'item', type: 'default' as const },
+      ],
+    };
+
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'n2', targetHandle: 'value', targetNodeId: 'n2' },
+        document,
+        templates
+      )
+    ).not.toBeNull();
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'n2', targetHandle: 'item', targetNodeId: 'c1' },
+        document,
+        templates
+      )
+    ).toBeNull();
+  });
+
+  it('rejects connections that would create a cycle', () => {
+    const document = {
+      ...baseDocument,
+      edges: [
+        {
+          id: 'e1',
+          source: 'n1',
+          sourceHandle: 'value',
+          target: 'n2',
+          targetHandle: 'value',
+          type: 'default' as const,
+        },
+      ],
+    };
+
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'n2', targetHandle: 'value', targetNodeId: 'n1' },
+        document,
+        templates
+      )
+    ).toMatch(/cycle/);
+  });
+
+  it('accepts connectors as pass-through routing nodes', () => {
+    const connectorDocument: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'connector-in',
+          source: 'n1',
+          sourceHandle: 'value',
+          target: 'connector-1',
+          targetHandle: 'in',
+          type: 'default',
+        },
+      ],
+      nodes: [makeNode('n1', 'number'), makeNode('n2', 'number'), makeConnector('connector-1')],
+    };
+
+    expect(
+      validateConnection(
+        { sourceHandle: 'out', sourceNodeId: 'connector-1', targetHandle: 'value', targetNodeId: 'n2' },
+        connectorDocument,
+        templates
+      )
+    ).toBeNull();
+  });
+
+  it('rejects a second connector input', () => {
+    const connectorDocument: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'connector-in',
+          source: 'n1',
+          sourceHandle: 'value',
+          target: 'connector-1',
+          targetHandle: 'in',
+          type: 'default',
+        },
+      ],
+      nodes: [makeNode('n1', 'number'), makeNode('n2', 'number'), makeConnector('connector-1')],
+    };
+
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'n2', targetHandle: 'in', targetNodeId: 'connector-1' },
+        connectorDocument,
+        templates
+      )
+    ).toMatch(/already has an input/);
+  });
+
+  it('rejects connector input sources incompatible with an existing downstream target', () => {
+    const stringTemplates: InvocationTemplates = {
+      ...templates,
+      text: {
+        ...templates.number,
+        inputs: {
+          value: { ...templates.number.inputs.value, type: single('StringField') },
+        },
+        outputs: {
+          value: { ...templates.number.outputs.value, type: single('StringField') },
+        },
+        type: 'text',
+      },
+    };
+    const connectorDocument: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'connector-out',
+          source: 'connector-1',
+          sourceHandle: 'out',
+          target: 'n1',
+          targetHandle: 'value',
+          type: 'default',
+        },
+      ],
+      nodes: [makeNode('n1', 'number'), makeNode('text-1', 'text'), makeConnector('connector-1')],
+    };
+
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'text-1', targetHandle: 'in', targetNodeId: 'connector-1' },
+        connectorDocument,
+        stringTemplates
+      )
+    ).toMatch(/StringField cannot connect to IntegerField/);
+  });
+
+  it('rejects connector input sources incompatible with any downstream fan-out target', () => {
+    const stringTemplates: InvocationTemplates = {
+      ...templates,
+      text: {
+        ...templates.number,
+        inputs: {
+          value: { ...templates.number.inputs.value, type: single('StringField') },
+        },
+        outputs: {
+          value: { ...templates.number.outputs.value, type: single('StringField') },
+        },
+        type: 'text',
+      },
+    };
+    const connectorDocument: Pick<ProjectGraphState, 'edges' | 'nodes'> = {
+      edges: [
+        {
+          id: 'connector-out-string',
+          source: 'connector-1',
+          sourceHandle: 'out',
+          target: 'text-target',
+          targetHandle: 'value',
+          type: 'default',
+        },
+        {
+          id: 'connector-out-number',
+          source: 'connector-1',
+          sourceHandle: 'out',
+          target: 'number-target',
+          targetHandle: 'value',
+          type: 'default',
+        },
+      ],
+      nodes: [
+        makeNode('number-target', 'number'),
+        makeNode('text-source', 'text'),
+        makeNode('text-target', 'text'),
+        makeConnector('connector-1'),
+      ],
+    };
+
+    expect(
+      validateConnection(
+        { sourceHandle: 'value', sourceNodeId: 'text-source', targetHandle: 'in', targetNodeId: 'connector-1' },
+        connectorDocument,
+        stringTemplates
+      )
+    ).toMatch(/StringField cannot connect to IntegerField/);
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/validation.ts b/invokeai/frontend/webv2/src/workbench/workflows/validation.ts
new file mode 100644
index 00000000000..012ad26754b
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/validation.ts
@@ -0,0 +1,391 @@
+import type {
+  FieldInputTemplate,
+  FieldOutputTemplate,
+  FieldType,
+  InvocationTemplate,
+  InvocationTemplates,
+  ProjectGraphState,
+  WorkflowEdge,
+  WorkflowNode,
+} from './types';
+
+import {
+  CONNECTOR_INPUT_HANDLE,
+  CONNECTOR_OUTPUT_HANDLE,
+  resolveConnectorSourceIndexed,
+  resolveConnectorTargetsIndexed,
+} from './connectors';
+import { createWorkflowGraphIndex, type WorkflowGraphIndex } from './graphIndex';
+import { isConnectorNode, isInvocationNode } from './types';
+
+/**
+ * Connection validation, ported from the legacy editor's
+ * `validateConnectionTypes` / `validateConnection`. Connector nodes are
+ * pass-through routing nodes: their source type is resolved from the first
+ * upstream invocation output when one exists.
+ */
+
+const isSingle = (type: FieldType): boolean => type.cardinality === 'SINGLE';
+const isCollection = (type: FieldType): boolean => type.cardinality === 'COLLECTION';
+const isSingleOrCollection = (type: FieldType): boolean => type.cardinality === 'SINGLE_OR_COLLECTION';
+
+const isSameShape = (a: FieldType, b: FieldType): boolean =>
+  a.name === b.name && a.cardinality === b.cardinality && a.batch === b.batch;
+
+/** Types are equal when either declared or `ui_type`-original sides match. */
+export const areFieldTypesEqual = (a: FieldType, b: FieldType): boolean =>
+  isSameShape(a, b) ||
+  (b.originalType !== undefined && isSameShape(a, b.originalType)) ||
+  (a.originalType !== undefined && isSameShape(a.originalType, b)) ||
+  (a.originalType !== undefined && b.originalType !== undefined && isSameShape(a.originalType, b.originalType));
+
+export const validateConnectionTypes = (sourceType: FieldType, targetType: FieldType): boolean => {
+  if (areFieldTypesEqual(sourceType, targetType)) {
+    return true;
+  }
+
+  if (sourceType.batch !== targetType.batch) {
+    return false;
+  }
+
+  const isCollectionItemToNonCollection = sourceType.name === 'CollectionItemField' && !isCollection(targetType);
+  const isNonCollectionToCollectionItem = isSingle(sourceType) && targetType.name === 'CollectionItemField';
+  const isAnythingToSingleOrCollectionOfSameBaseType =
+    isSingleOrCollection(targetType) && sourceType.name === targetType.name;
+  const isGenericCollectionToAnyCollectionOrSingleOrCollection =
+    sourceType.name === 'CollectionField' && !isSingle(targetType);
+  const isCollectionToGenericCollection = targetType.name === 'CollectionField' && isCollection(sourceType);
+
+  const doesCardinalityMatch =
+    (isSingle(sourceType) && isSingle(targetType)) ||
+    (isCollection(sourceType) && isCollection(targetType)) ||
+    (isCollection(sourceType) && isSingleOrCollection(targetType)) ||
+    (isSingleOrCollection(sourceType) && isSingleOrCollection(targetType)) ||
+    (isSingle(sourceType) && isSingleOrCollection(targetType));
+
+  const isIntToFloat = sourceType.name === 'IntegerField' && targetType.name === 'FloatField';
+  const isIntToString = sourceType.name === 'IntegerField' && targetType.name === 'StringField';
+  const isFloatToString = sourceType.name === 'FloatField' && targetType.name === 'StringField';
+  const isSubTypeMatch = doesCardinalityMatch && (isIntToFloat || isIntToString || isFloatToString);
+
+  const isTargetAnyType = targetType.name === 'AnyField';
+  const isSourceAnyType = sourceType.name === 'AnyField' && doesCardinalityMatch;
+
+  return (
+    isCollectionItemToNonCollection ||
+    isNonCollectionToCollectionItem ||
+    isAnythingToSingleOrCollectionOfSameBaseType ||
+    isGenericCollectionToAnyCollectionOrSingleOrCollection ||
+    isCollectionToGenericCollection ||
+    isSubTypeMatch ||
+    isTargetAnyType ||
+    isSourceAnyType
+  );
+};
+
+/** True if adding source→target would close a cycle: target must not already reach source. */
+export const wouldCreateCycle = (sourceNodeId: string, targetNodeId: string, edges: WorkflowEdge[]): boolean => {
+  if (sourceNodeId === targetNodeId) {
+    return true;
+  }
+
+  const visited = new Set<string>();
+  const stack = [targetNodeId];
+
+  while (stack.length > 0) {
+    const nodeId = stack.pop() as string;
+
+    if (nodeId === sourceNodeId) {
+      return true;
+    }
+
+    if (visited.has(nodeId)) {
+      continue;
+    }
+
+    visited.add(nodeId);
+
+    for (const edge of edges) {
+      if (edge.source === nodeId) {
+        stack.push(edge.target);
+      }
+    }
+  }
+
+  return false;
+};
+
+/** True if the graph already contains a cycle anywhere. */
+export const hasAnyCycle = (nodes: WorkflowNode[], edges: WorkflowEdge[]): boolean => {
+  const adjacency = new Map<string, string[]>();
+
+  for (const edge of edges) {
+    adjacency.set(edge.source, [...(adjacency.get(edge.source) ?? []), edge.target]);
+  }
+
+  const state = new Map<string, 'visiting' | 'done'>();
+
+  const visit = (nodeId: string): boolean => {
+    const nodeState = state.get(nodeId);
+
+    if (nodeState === 'visiting') {
+      return true;
+    }
+
+    if (nodeState === 'done') {
+      return false;
+    }
+
+    state.set(nodeId, 'visiting');
+
+    for (const nextNodeId of adjacency.get(nodeId) ?? []) {
+      if (visit(nextNodeId)) {
+        return true;
+      }
+    }
+
+    state.set(nodeId, 'done');
+
+    return false;
+  };
+
+  return nodes.some((node) => visit(node.id));
+};
+
+export interface ConnectionCandidate {
+  sourceNodeId: string;
+  sourceHandle: string;
+  targetNodeId: string;
+  targetHandle: string;
+}
+
+/** Multiple inbound edges are only meaningful for the collect node's `item` input. */
+const allowsMultipleInboundEdges = (node: WorkflowNode, fieldName: string): boolean =>
+  isInvocationNode(node) && node.data.type === 'collect' && fieldName === 'item';
+
+export const getCompatibleInputTemplate = (
+  template: InvocationTemplate,
+  sourceType: FieldType | null
+): FieldInputTemplate | null => {
+  const inputTemplates = Object.values(template.inputs).sort(
+    (a, b) => (a.uiOrder ?? Number.MAX_SAFE_INTEGER) - (b.uiOrder ?? Number.MAX_SAFE_INTEGER)
+  );
+
+  return (
+    inputTemplates.find(
+      (inputTemplate) =>
+        !inputTemplate.uiHidden &&
+        inputTemplate.input !== 'direct' &&
+        (sourceType === null || validateConnectionTypes(sourceType, inputTemplate.type))
+    ) ?? null
+  );
+};
+
+export const getCompatibleOutputTemplate = (
+  template: InvocationTemplate,
+  targetType: FieldType | null
+): FieldOutputTemplate | null => {
+  return (
+    Object.values(template.outputs).find(
+      (outputTemplate) => targetType === null || validateConnectionTypes(outputTemplate.type, targetType)
+    ) ?? null
+  );
+};
+
+const isSameFieldType = (left: FieldType, right: FieldType): boolean =>
+  left.name === right.name && left.cardinality === right.cardinality && left.batch === right.batch;
+
+const getCommonConnectorTargetType = (
+  connectorId: string,
+  document: Pick<ProjectGraphState, 'edges' | 'nodes'>,
+  templates: InvocationTemplates,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges)
+): FieldType | null => {
+  const targets = resolveConnectorTargetsIndexed(connectorId, index, templates);
+
+  if (targets.length === 0 || targets.some((target) => target.type === null)) {
+    return null;
+  }
+
+  const firstType = targets[0]?.type;
+
+  return firstType && targets.every((target) => target.type !== null && isSameFieldType(firstType, target.type))
+    ? firstType
+    : null;
+};
+
+const getSourceFieldType = (
+  node: WorkflowNode,
+  handle: string,
+  document: Pick<ProjectGraphState, 'edges' | 'nodes'>,
+  templates: InvocationTemplates,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges)
+): FieldType | null | undefined => {
+  if (isInvocationNode(node)) {
+    return templates[node.data.type]?.outputs[handle]?.type;
+  }
+
+  if (isConnectorNode(node) && handle === CONNECTOR_OUTPUT_HANDLE) {
+    const source = resolveConnectorSourceIndexed(node.id, index, templates);
+
+    return source ? source.type : getCommonConnectorTargetType(node.id, document, templates, index);
+  }
+
+  return undefined;
+};
+
+export const getWorkflowSourceFieldType = (
+  document: Pick<ProjectGraphState, 'edges' | 'nodes'>,
+  templates: InvocationTemplates,
+  sourceNodeId: string,
+  sourceHandle: string,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges)
+): FieldType | null | undefined => {
+  const sourceNode = index.nodesById.get(sourceNodeId);
+
+  return sourceNode ? getSourceFieldType(sourceNode, sourceHandle, document, templates, index) : undefined;
+};
+
+const getTargetFieldType = (
+  node: WorkflowNode,
+  handle: string,
+  document: Pick<ProjectGraphState, 'edges' | 'nodes'>,
+  templates: InvocationTemplates,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges)
+): FieldType | null | undefined => {
+  if (isInvocationNode(node)) {
+    const inputTemplate = templates[node.data.type]?.inputs[handle];
+
+    return inputTemplate && inputTemplate.input !== 'direct' ? inputTemplate.type : undefined;
+  }
+
+  if (isConnectorNode(node) && handle === CONNECTOR_INPUT_HANDLE) {
+    const targetType = getCommonConnectorTargetType(node.id, document, templates, index);
+
+    if (targetType) {
+      return targetType;
+    }
+
+    return resolveConnectorSourceIndexed(node.id, index, templates)?.type ?? null;
+  }
+
+  return undefined;
+};
+
+export const getWorkflowTargetFieldType = (
+  document: Pick<ProjectGraphState, 'edges' | 'nodes'>,
+  templates: InvocationTemplates,
+  targetNodeId: string,
+  targetHandle: string,
+  index: WorkflowGraphIndex = createWorkflowGraphIndex(document.nodes, document.edges)
+): FieldType | null | undefined => {
+  const targetNode = index.nodesById.get(targetNodeId);
+
+  return targetNode ? getTargetFieldType(targetNode, targetHandle, document, templates, index) : undefined;
+};
+
+const hasValidSourceHandle = (node: WorkflowNode, handle: string, templates: InvocationTemplates): boolean => {
+  if (isInvocationNode(node)) {
+    return templates[node.data.type]?.outputs[handle] !== undefined;
+  }
+
+  return isConnectorNode(node) && handle === CONNECTOR_OUTPUT_HANDLE;
+};
+
+/** Returns a human-readable rejection reason, or null when the connection is valid. */
+export const validateConnection = (
+  candidate: ConnectionCandidate,
+  document: Pick<ProjectGraphState, 'edges' | 'nodes'>,
+  templates: InvocationTemplates
+): string | null => {
+  const { sourceHandle, sourceNodeId, targetHandle, targetNodeId } = candidate;
+  const index = createWorkflowGraphIndex(document.nodes, document.edges);
+
+  if (sourceNodeId === targetNodeId) {
+    return 'A node cannot connect to itself.';
+  }
+
+  const sourceNode = index.nodesById.get(sourceNodeId);
+  const targetNode = index.nodesById.get(targetNodeId);
+
+  if (!sourceNode || !targetNode) {
+    return 'Both ends of a connection must be workflow nodes.';
+  }
+
+  if (!hasValidSourceHandle(sourceNode, sourceHandle, templates)) {
+    return 'One of the fields has no known definition.';
+  }
+
+  if (isConnectorNode(targetNode)) {
+    if (targetHandle !== CONNECTOR_INPUT_HANDLE) {
+      return 'Connectors only accept input on their left handle.';
+    }
+
+    if (index.edgesByTarget.get(targetNodeId)?.some((edge) => edge.targetHandle === targetHandle)) {
+      return 'Connector already has an input.';
+    }
+
+    const sourceFieldType = getSourceFieldType(sourceNode, sourceHandle, document, templates, index);
+    const targetFieldTypes = resolveConnectorTargetsIndexed(targetNodeId, index, templates)
+      .map((target) => target.type)
+      .filter((type): type is FieldType => type !== null);
+
+    for (const targetFieldType of targetFieldTypes) {
+      if (sourceFieldType && !validateConnectionTypes(sourceFieldType, targetFieldType)) {
+        return `${sourceFieldType.name} cannot connect to ${targetFieldType.name}.`;
+      }
+    }
+
+    if (wouldCreateCycle(sourceNodeId, targetNodeId, document.edges)) {
+      return 'This connection would create a cycle.';
+    }
+
+    return null;
+  }
+
+  if (!isInvocationNode(targetNode)) {
+    return 'The target node cannot receive connections.';
+  }
+
+  const targetTemplate = templates[targetNode.data.type];
+  const sourceFieldType = getSourceFieldType(sourceNode, sourceHandle, document, templates, index);
+  const targetField = targetTemplate?.inputs[targetHandle];
+
+  if (sourceFieldType === undefined || !targetField) {
+    return 'One of the fields has no known definition.';
+  }
+
+  if (targetField.input === 'direct') {
+    return `${targetField.title} only accepts direct values, not connections.`;
+  }
+
+  const isDuplicate = index.edgesBySource
+    .get(sourceNodeId)
+    ?.some(
+      (edge) =>
+        edge.source === sourceNodeId &&
+        edge.sourceHandle === sourceHandle &&
+        edge.target === targetNodeId &&
+        edge.targetHandle === targetHandle
+    );
+
+  if (isDuplicate) {
+    return 'This connection already exists.';
+  }
+
+  const hasInboundEdge = index.edgesByTarget.get(targetNodeId)?.some((edge) => edge.targetHandle === targetHandle);
+
+  if (hasInboundEdge && !allowsMultipleInboundEdges(targetNode, targetHandle)) {
+    return `${targetField.title} already has a connection.`;
+  }
+
+  if (sourceFieldType && !validateConnectionTypes(sourceFieldType, targetField.type)) {
+    return `${sourceFieldType.name} cannot connect to ${targetField.type.name}.`;
+  }
+
+  if (wouldCreateCycle(sourceNodeId, targetNodeId, document.edges)) {
+    return 'This connection would create a cycle.';
+  }
+
+  return null;
+};
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/workflowJson.test.ts b/invokeai/frontend/webv2/src/workbench/workflows/workflowJson.test.ts
new file mode 100644
index 00000000000..a7f9130b527
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/workflowJson.test.ts
@@ -0,0 +1,204 @@
+import { describe, expect, it } from 'vitest';
+
+import type { InvocationTemplate } from './types';
+
+import {
+  buildCurrentImageNode,
+  buildConnectorNode,
+  buildInvocationNode,
+  buildNotesNode,
+  createProjectGraph,
+  getFormChildren,
+  projectGraphReducer,
+} from './document';
+import { parseWorkflowJson, serializeWorkflowJson } from './workflowJson';
+
+const template: InvocationTemplate = {
+  category: 'test',
+  classification: 'stable',
+  description: '',
+  inputs: {
+    prompt: {
+      default: 'a cat',
+      description: '',
+      exclusiveMaximum: null,
+      exclusiveMinimum: null,
+      input: 'any',
+      maximum: null,
+      minimum: null,
+      multipleOf: null,
+      name: 'prompt',
+      options: null,
+      required: true,
+      title: 'Prompt',
+      type: { batch: false, cardinality: 'SINGLE', name: 'StringField' },
+      uiChoiceLabels: null,
+      uiComponent: 'textarea',
+      uiHidden: false,
+      uiModelBase: null,
+      uiModelType: null,
+      uiOrder: null,
+    },
+  },
+  nodePack: 'invokeai',
+  outputs: {},
+  outputType: 'string_output',
+  tags: [],
+  title: 'Prompt',
+  type: 'prompt',
+  useCache: true,
+  version: '1.2.0',
+};
+
+describe('workflow JSON round-trip', () => {
+  it('serializes and re-parses a document, preserving nodes, edges, form, and metadata', () => {
+    const node = buildInvocationNode(template, { x: 10, y: 20 });
+    let doc = createProjectGraph('roundtrip');
+
+    doc = projectGraphReducer(doc, { node, type: 'addNode' });
+    doc = projectGraphReducer(doc, {
+      description: 'Custom description',
+      fieldName: 'prompt',
+      nodeId: node.id,
+      type: 'setFieldDescription',
+    });
+    doc = projectGraphReducer(doc, { fieldIdentifier: { fieldName: 'prompt', nodeId: node.id }, type: 'exposeField' });
+    doc = projectGraphReducer(doc, {
+      patch: { author: 'josh', description: 'desc', name: 'Round Trip', tags: 'a,b' },
+      type: 'setMetadata',
+    });
+
+    const serialized = serializeWorkflowJson(doc);
+    const { document: parsed, warnings } = parseWorkflowJson(serialized);
+
+    expect(warnings).toEqual([]);
+    expect(parsed.name).toBe('Round Trip');
+    expect(parsed.author).toBe('josh');
+    expect(parsed.nodes).toHaveLength(1);
+
+    const parsedNode = parsed.nodes[0];
+
+    expect(parsedNode?.id).toBe(node.id);
+    expect(parsedNode?.position).toEqual({ x: 10, y: 20 });
+    expect(parsedNode?.type === 'invocation' && parsedNode.data.inputs.prompt?.value).toBe('a cat');
+    expect(parsedNode?.type === 'invocation' && parsedNode.data.inputs.prompt?.description).toBe('Custom description');
+
+    const formChildren = getFormChildren(parsed.form);
+
+    expect(formChildren).toHaveLength(1);
+    expect(formChildren[0]?.type).toBe('node-field');
+  });
+
+  it('keeps the serialized shape legacy-compatible', () => {
+    const doc = createProjectGraph('legacy-shape');
+    const serialized = serializeWorkflowJson(doc);
+
+    expect(serialized.meta).toEqual({ category: 'user', version: '3.0.0' });
+    expect(serialized.exposedFields).toEqual([]);
+    expect(serialized).toHaveProperty('form');
+  });
+
+  it('round-trips notes, current_image, and connector UI nodes', () => {
+    let doc = createProjectGraph('ui-nodes');
+
+    doc = projectGraphReducer(doc, { node: buildNotesNode({ x: 1, y: 2 }), type: 'addNode' });
+    doc = projectGraphReducer(doc, { node: buildCurrentImageNode({ x: 3, y: 4 }), type: 'addNode' });
+    doc = projectGraphReducer(doc, { node: buildConnectorNode({ x: 5, y: 6 }), type: 'addNode' });
+
+    const { document: parsed, warnings } = parseWorkflowJson(serializeWorkflowJson(doc));
+
+    expect(warnings).toEqual([]);
+    expect(parsed.nodes.map((node) => node.type).sort()).toEqual(['connector', 'current_image', 'notes']);
+
+    const currentImage = parsed.nodes.find((node) => node.type === 'current_image');
+
+    expect(currentImage?.position).toEqual({ x: 3, y: 4 });
+    expect(currentImage?.type === 'current_image' && currentImage.data.label).toBe('Current Image');
+
+    const connector = parsed.nodes.find((node) => node.type === 'connector');
+
+    expect(connector?.position).toEqual({ x: 5, y: 6 });
+    expect(connector?.type === 'connector' && connector.data.label).toBe('');
+  });
+});
+
+describe('parseWorkflowJson tolerance', () => {
+  it('migrates pre-form exposedFields into form elements', () => {
+    const { document, warnings } = parseWorkflowJson({
+      edges: [],
+      exposedFields: [{ fieldName: 'prompt', nodeId: 'n1' }],
+      name: 'Old Workflow',
+      nodes: [
+        {
+          data: { id: 'n1', inputs: { prompt: { label: '', name: 'prompt', value: 'hi' } }, type: 'prompt' },
+          id: 'n1',
+          position: { x: 0, y: 0 },
+          type: 'invocation',
+        },
+      ],
+      version: '1.0.0',
+    });
+
+    expect(warnings).toEqual([]);
+
+    const children = getFormChildren(document.form);
+
+    expect(children).toHaveLength(1);
+    expect(children[0]?.type === 'node-field' && children[0].data.fieldIdentifier).toEqual({
+      fieldName: 'prompt',
+      nodeId: 'n1',
+    });
+  });
+
+  it('preserves connector nodes and edges', () => {
+    const { document, warnings } = parseWorkflowJson({
+      edges: [
+        { id: 'e1', source: 'n1', sourceHandle: 'out', target: 'conn1', targetHandle: 'in', type: 'default' },
+        { id: 'e2', source: 'conn1', sourceHandle: 'out', target: 'n2', targetHandle: 'text', type: 'default' },
+      ],
+      name: 'Connectors',
+      nodes: [
+        { data: { id: 'n1', inputs: {}, type: 'a' }, id: 'n1', position: { x: 0, y: 0 }, type: 'invocation' },
+        { data: { id: 'n2', inputs: {}, type: 'b' }, id: 'n2', position: { x: 0, y: 0 }, type: 'invocation' },
+        { data: { label: 'Connector' }, id: 'conn1', position: { x: 4, y: 5 }, type: 'connector' },
+      ],
+    });
+
+    expect(warnings).toEqual([]);
+    expect(document.nodes.map((node) => node.type).sort()).toEqual(['connector', 'invocation', 'invocation']);
+    expect(document.nodes.find((node) => node.type === 'connector')?.position).toEqual({ x: 4, y: 5 });
+    expect(document.edges).toEqual([
+      { id: 'e1', source: 'n1', sourceHandle: 'out', target: 'conn1', targetHandle: 'in', type: 'default' },
+      { id: 'e2', source: 'conn1', sourceHandle: 'out', target: 'n2', targetHandle: 'text', type: 'default' },
+    ]);
+  });
+
+  it('drops dangling edges and unknown form elements with warnings', () => {
+    const { document, warnings } = parseWorkflowJson({
+      edges: [{ id: 'e1', source: 'missing', sourceHandle: 'out', target: 'n1', targetHandle: 'in', type: 'default' }],
+      form: { elements: { weird: { id: 'weird', type: 'mystery' } }, rootElementId: 'missing-root' },
+      name: 'Broken',
+      nodes: [{ data: { id: 'n1', inputs: {}, type: 'a' }, id: 'n1', position: { x: 0, y: 0 }, type: 'invocation' }],
+    });
+
+    expect(document.edges).toEqual([]);
+    expect(document.form.elements[document.form.rootElementId]?.type).toBe('container');
+    expect(warnings.length).toBeGreaterThan(0);
+  });
+
+  it('rejects non-workflow payloads', () => {
+    expect(() => parseWorkflowJson('not a workflow')).toThrow(/not a recognizable/);
+  });
+
+  it('accepts form: null, as stored by pre-form-builder library workflows', () => {
+    const { document, warnings } = parseWorkflowJson({
+      edges: [],
+      form: null,
+      name: 'No Form',
+      nodes: [{ data: { id: 'n1', inputs: {}, type: 'a' }, id: 'n1', position: { x: 0, y: 0 }, type: 'invocation' }],
+    });
+
+    expect(warnings).toEqual([]);
+    expect(document.form.elements[document.form.rootElementId]?.type).toBe('container');
+  });
+});
diff --git a/invokeai/frontend/webv2/src/workbench/workflows/workflowJson.ts b/invokeai/frontend/webv2/src/workbench/workflows/workflowJson.ts
new file mode 100644
index 00000000000..c64ea1afe22
--- /dev/null
+++ b/invokeai/frontend/webv2/src/workbench/workflows/workflowJson.ts
@@ -0,0 +1,390 @@
+import { z } from 'zod';
+
+import type {
+  ProjectGraphState,
+  WorkflowEdge,
+  WorkflowFieldInstance,
+  WorkflowForm,
+  WorkflowFormElement,
+  WorkflowNode,
+} from './types';
+
+import { createWorkflowForm, createWorkflowId } from './document';
+
+/**
+ * Import/export between the project graph document and the legacy WorkflowV3
+ * JSON format — the format used by workflow files, image-embedded workflows,
+ * and the backend workflow library. Parsing is tolerant: recoverable problems
+ * (unknown elements and dangling edges) become warnings instead of failures.
+ */
+
+const zXYPosition = z.object({ x: z.number().catch(0), y: z.number().catch(0) }).catch({ x: 0, y: 0 });
+
+const zFieldInstance = z.object({
+  description: z.string().optional().catch(undefined),
+  label: z.string().catch(''),
+  name: z.string(),
+  value: z.unknown().optional(),
+});
+
+const zInvocationNode = z.object({
+  data: z.looseObject({
+    inputs: z.record(z.string(), zFieldInstance).catch({}),
+    isIntermediate: z.boolean().catch(true),
+    isOpen: z.boolean().catch(true),
+    label: z.string().catch(''),
+    nodePack: z.string().catch('invokeai'),
+    notes: z.string().catch(''),
+    type: z.string(),
+    useCache: z.boolean().catch(true),
+    version: z.string().catch('1.0.0'),
+  }),
+  id: z.string().min(1),
+  position: zXYPosition,
+  type: z.literal('invocation'),
+});
+
+const zNotesNode = z.object({
+  data: z.looseObject({
+    label: z.string().catch('Notes'),
+    notes: z.string().catch(''),
+  }),
+  id: z.string().min(1),
+  position: zXYPosition,
+  type: z.literal('notes'),
+});
+
+const zCurrentImageNode = z.object({
+  data: z.looseObject({
+    label: z.string().catch('Current Image'),
+  }),
+  id: z.string().min(1),
+  position: zXYPosition,
+  type: z.literal('current_image'),
+});
+
+const zConnectorNode = z.object({
+  data: z
+    .looseObject({
+      label: z.string().catch('Connector'),
+    })
+    .catch({ label: 'Connector' }),
+  id: z.string().min(1),
+  position: zXYPosition,
+  type: z.literal('connector'),
+});
+
+const zAnyNode = z.union([zInvocationNode, zNotesNode, zCurrentImageNode, zConnectorNode]);
+
+const zDefaultEdge = z.object({
+  id: z.string().catch(''),
+  source: z.string().min(1),
+  sourceHandle: z.string().min(1),
+  target: z.string().min(1),
+  targetHandle: z.string().min(1),
+  type: z.literal('default').catch('default'),
+});
+
+const zFieldIdentifier = z.object({ fieldName: z.string(), nodeId: z.string() });
+
+const zFormElement = z.discriminatedUnion('type', [
+  z.object({
+    data: z.looseObject({
+      children: z.array(z.string()).catch([]),
+      layout: z.enum(['column', 'row']).catch('column'),
+    }),
+    id: z.string(),
+    parentId: z.string().optional(),
+    type: z.literal('container'),
+  }),
+  z.object({
+    data: z.looseObject({
+      fieldIdentifier: zFieldIdentifier,
+      showDescription: z.boolean().catch(false),
+    }),
+    id: z.string(),
+    parentId: z.string().optional(),
+    type: z.literal('node-field'),
+  }),
+  z.object({
+    data: z.looseObject({ content: z.string().catch('') }),
+    id: z.string(),
+    parentId: z.string().optional(),
+    type: z.literal('heading'),
+  }),
+  z.object({
+    data: z.looseObject({ content: z.string().catch('') }),
+    id: z.string(),
+    parentId: z.string().optional(),
+    type: z.literal('text'),
+  }),
+  z.object({
+    id: z.string(),
+    parentId: z.string().optional(),
+    type: z.literal('divider'),
+  }),
+]);
+
+const zWorkflowJson = z.looseObject({
+  author: z.string().catch(''),
+  contact: z.string().catch(''),
+  description: z.string().catch(''),
+  edges: z.array(z.unknown()).catch([]),
+  exposedFields: z.array(zFieldIdentifier).catch([]),
+  // Workflows that predate the form builder store `form: null`; a malformed
+  // form also degrades to "absent" rather than failing the whole parse.
+  form: z
+    .object({
+      elements: z.record(z.string(), z.unknown()),
+      rootElementId: z.string(),
+    })
+    .nullish()
+    .catch(null),
+  id: z.string().optional(),
+  name: z.string().catch(''),
+  nodes: z.array(z.unknown()).catch([]),
+  notes: z.string().catch(''),
+  tags: z.string().catch(''),
+  version: z.string().catch('1.0.0'),
+});
+
+export interface ParsedWorkflow {
+  document: ProjectGraphState;
+  warnings: string[];
+}
+
+const parseForm = (
+  rawForm: z.infer<typeof zWorkflowJson>['form'],
+  exposedFields: Array<z.infer<typeof zFieldIdentifier>>,
+  nodeIds: Set<string>,
+  warnings: string[]
+): WorkflowForm => {
+  let form: WorkflowForm | null = null;
+
+  if (rawForm) {
+    const elements: Record<string, WorkflowFormElement> = {};
+
+    for (const [id, rawElement] of Object.entries(rawForm.elements)) {
+      const parsed = zFormElement.safeParse(rawElement);
+
+      if (parsed.success) {
+        elements[id] = parsed.data as WorkflowFormElement;
+      } else {
+        warnings.push(`Skipped an unrecognized form element (${id}).`);
+      }
+    }
+
+    const root = elements[rawForm.rootElementId];
+
+    if (root?.type === 'container') {
+      form = { elements, rootElementId: rawForm.rootElementId };
+    } else if (Object.keys(rawForm.elements).length > 0) {
+      warnings.push('The workflow form was malformed and has been reset.');
+    }
+  }
+
+  if (!form) {
+    form = createWorkflowForm();
+
+    // Pre-form workflows list exposed fields instead; migrate them into form elements.
+    const root = form.elements[form.rootElementId];
+
+    if (root?.type === 'container') {
+      for (const fieldIdentifier of exposedFields) {
+        const element: WorkflowFormElement = {
+          data: { fieldIdentifier, showDescription: false },
+          id: createWorkflowId('node-field'),
+          parentId: root.id,
+          type: 'node-field',
+        };
+
+        form.elements[element.id] = element;
+        root.data.children.push(element.id);
+      }
+    }
+  }
+
+  // Drop node-field elements that point at nodes which did not survive parsing.
+  for (const element of Object.values(form.elements)) {
+    if (element.type !== 'node-field' || nodeIds.has(element.data.fieldIdentifier.nodeId)) {
+      continue;
+    }
+
+    delete form.elements[element.id];
+
+    const parent = element.parentId ? form.elements[element.parentId] : undefined;
+
+    if (parent?.type === 'container') {
+      parent.data.children = parent.data.children.filter((childId) => childId !== element.id);
+    }
+
+    warnings.push('Removed a form field that referenced a missing node.');
+  }
+
+  return form;
+};
+
+export const parseWorkflowJson = (raw: unknown): ParsedWorkflow => {
+  const parsed = zWorkflowJson.safeParse(raw);
+
+  if (!parsed.success) {
+    throw new Error('This file is not a recognizable InvokeAI workflow.');
+  }
+
+  const warnings: string[] = [];
+  const nodes: WorkflowNode[] = [];
+
+  for (const rawNode of parsed.data.nodes) {
+    const nodeResult = zAnyNode.safeParse(rawNode);
+
+    if (!nodeResult.success) {
+      warnings.push('Skipped an unrecognized node.');
+      continue;
+    }
+
+    const node = nodeResult.data;
+
+    if (node.type === 'connector') {
+      nodes.push({
+        data: { label: node.data.label },
+        id: node.id,
+        position: node.position,
+        type: 'connector',
+      });
+      continue;
+    }
+
+    if (node.type === 'notes') {
+      nodes.push({
+        data: { label: node.data.label, notes: node.data.notes },
+        id: node.id,
+        position: node.position,
+        type: 'notes',
+      });
+      continue;
+    }
+
+    if (node.type === 'current_image') {
+      nodes.push({
+        data: { label: node.data.label },
+        id: node.id,
+        position: node.position,
+        type: 'current_image',
+      });
+      continue;
+    }
+
+    const inputs: Record<string, WorkflowFieldInstance> = {};
+
+    for (const [name, instance] of Object.entries(node.data.inputs)) {
+      inputs[name] = {
+        description: instance.description,
+        label: instance.label,
+        name: instance.name || name,
+        value: instance.value,
+      };
+    }
+
+    nodes.push({
+      data: {
+        inputs,
+        isIntermediate: node.data.isIntermediate,
+        isOpen: node.data.isOpen,
+        label: node.data.label,
+        nodePack: node.data.nodePack,
+        notes: node.data.notes,
+        type: node.data.type,
+        useCache: node.data.useCache,
+        version: node.data.version,
+      },
+      id: node.id,
+      position: node.position,
+      type: 'invocation',
+    });
+  }
+
+  const rawEdges = parsed.data.edges.flatMap((rawEdge) => {
+    const edgeResult = zDefaultEdge.safeParse(rawEdge);
+
+    return edgeResult.success ? [edgeResult.data] : [];
+  });
+
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const edges: WorkflowEdge[] = [];
+
+  for (const edge of rawEdges) {
+    if (!nodeIds.has(edge.source) || !nodeIds.has(edge.target)) {
+      warnings.push('Dropped a connection that referenced a missing node.');
+      continue;
+    }
+
+    edges.push({
+      id: edge.id || createWorkflowId('edge'),
+      source: edge.source,
+      sourceHandle: edge.sourceHandle,
+      target: edge.target,
+      targetHandle: edge.targetHandle,
+      type: 'default',
+    });
+  }
+
+  const document: ProjectGraphState = {
+    author: parsed.data.author,
+    contact: parsed.data.contact,
+    description: parsed.data.description,
+    edges,
+    form: parseForm(parsed.data.form, parsed.data.exposedFields, nodeIds, warnings),
+    id: createWorkflowId('workflow'),
+    libraryWorkflowId: parsed.data.id,
+    name: parsed.data.name,
+    nodes,
+    notes: parsed.data.notes,
+    tags: parsed.data.tags,
+    updatedAt: new Date().toISOString(),
+    version: 2,
+    workflowVersion: parsed.data.version,
+  };
+
+  return { document, warnings };
+};
+
+/** Serializes the document to legacy WorkflowV3 JSON (loadable by the v6 editor and the library backend). */
+export const serializeWorkflowJson = (document: ProjectGraphState): Record<string, unknown> => ({
+  author: document.author,
+  contact: document.contact,
+  description: document.description,
+  edges: document.edges.map((edge) => ({ ...edge })),
+  exposedFields: [],
+  form: {
+    elements: structuredClone(document.form.elements),
+    rootElementId: document.form.rootElementId,
+  },
+  ...(document.libraryWorkflowId ? { id: document.libraryWorkflowId } : {}),
+  meta: { category: 'user', version: '3.0.0' },
+  name: document.name,
+  nodes: document.nodes.map((node) =>
+    node.type === 'connector'
+      ? {
+          data: { ...node.data, id: node.id, isOpen: true, type: 'connector' },
+          id: node.id,
+          position: { ...node.position },
+          type: node.type,
+        }
+      : node.type === 'notes' || node.type === 'current_image'
+        ? {
+            data: { ...node.data, id: node.id, isOpen: true },
+            id: node.id,
+            position: { ...node.position },
+            type: node.type,
+          }
+        : {
+            data: { ...structuredClone(node.data), id: node.id },
+            id: node.id,
+            position: { ...node.position },
+            type: node.type,
+          }
+  ),
+  notes: document.notes,
+  tags: document.tags,
+  version: document.workflowVersion,
+});
diff --git a/invokeai/frontend/webv2/tsconfig.json b/invokeai/frontend/webv2/tsconfig.json
new file mode 100644
index 00000000000..48f8b3974af
--- /dev/null
+++ b/invokeai/frontend/webv2/tsconfig.json
@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "paths": {
+      "@": ["./src"],
+      "@/*": ["./src/*"],
+      "@assets": ["./src/assets"],
+      "@assets/*": ["./src/assets/*"],
+      "@theme": ["./src/theme"],
+      "@theme/*": ["./src/theme/*"],
+      "@workbench": ["./src/workbench"],
+      "@workbench/*": ["./src/workbench/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
diff --git a/invokeai/frontend/webv2/tsconfig.node.json b/invokeai/frontend/webv2/tsconfig.node.json
new file mode 100644
index 00000000000..9a861f6a437
--- /dev/null
+++ b/invokeai/frontend/webv2/tsconfig.node.json
@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "include": ["vite.config.mts"]
+}
diff --git a/invokeai/frontend/webv2/vite.config.mts b/invokeai/frontend/webv2/vite.config.mts
new file mode 100644
index 00000000000..8cab295849c
--- /dev/null
+++ b/invokeai/frontend/webv2/vite.config.mts
@@ -0,0 +1,80 @@
+import babel from '@rolldown/plugin-babel';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
+import { fileURLToPath, URL } from 'node:url';
+import { defineConfig } from 'vite';
+
+// Override with e.g. INVOKEAI_DEV_BACKEND=http://127.0.0.1:9091 when the
+// backend dev server runs on a non-default port.
+const BACKEND_URL = process.env.INVOKEAI_DEV_BACKEND ?? 'http://127.0.0.1:9090';
+const BACKEND_WS_URL = BACKEND_URL.replace(/^http/, 'ws');
+
+export default defineConfig({
+  base: './',
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks(id) {
+          if (!id.includes('/node_modules/')) {
+            return undefined;
+          }
+
+          // ag-psd (+ its only dependents pako/base64-js) is loaded LAZILY via a
+          // dynamic `import('ag-psd')` at PSD-export time. Keep it in its own chunk
+          // so it never lands in the eagerly-preloaded `vendor` bundle — otherwise
+          // the manualChunks catch-all below would pull it into the initial load.
+          if (
+            id.includes('/node_modules/ag-psd/') ||
+            id.includes('/node_modules/pako/') ||
+            id.includes('/node_modules/base64-js/')
+          ) {
+            return 'ag-psd';
+          }
+
+          if (id.includes('/node_modules/react-icons/')) {
+            return 'react-icons';
+          }
+
+          if (id.includes('/node_modules/@chakra-ui/') || id.includes('/node_modules/@emotion/')) {
+            return 'chakra';
+          }
+
+          return 'vendor';
+        },
+      },
+    },
+  },
+  plugins: [
+    react(),
+    babel({
+      presets: [reactCompilerPreset()],
+    }),
+  ],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+      '@assets': fileURLToPath(new URL('./src/assets', import.meta.url)),
+      '@theme': fileURLToPath(new URL('./src/theme', import.meta.url)),
+      '@workbench': fileURLToPath(new URL('./src/workbench', import.meta.url)),
+    },
+  },
+  server: {
+    host: '0.0.0.0',
+    port: 5174,
+    proxy: {
+      '/api/': {
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+        target: `${BACKEND_URL}/api/`,
+      },
+      '/openapi.json': {
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/openapi.json/, ''),
+        target: `${BACKEND_URL}/openapi.json`,
+      },
+      '/ws/socket.io': {
+        target: BACKEND_WS_URL,
+        ws: true,
+      },
+    },
+  },
+});
diff --git a/invokeai/frontend/webv2/vitest.browser.config.mts b/invokeai/frontend/webv2/vitest.browser.config.mts
new file mode 100644
index 00000000000..bb14e561e32
--- /dev/null
+++ b/invokeai/frontend/webv2/vitest.browser.config.mts
@@ -0,0 +1,20 @@
+import { playwright } from '@vitest/browser-playwright';
+import { mergeConfig } from 'vite';
+import { defineConfig } from 'vitest/config';
+
+import viteConfig from './vite.config.mts';
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      browser: {
+        enabled: true,
+        headless: true,
+        instances: [{ browser: 'chromium' }],
+        provider: playwright(),
+      },
+      include: ['src/**/*.browser.test.{ts,tsx}'],
+    },
+  })
+);
diff --git a/invokeai/frontend/webv2/vitest.config.mts b/invokeai/frontend/webv2/vitest.config.mts
new file mode 100644
index 00000000000..acfb52c53a3
--- /dev/null
+++ b/invokeai/frontend/webv2/vitest.config.mts
@@ -0,0 +1,14 @@
+import { mergeConfig } from 'vite';
+import { defineConfig } from 'vitest/config';
+
+import viteConfig from './vite.config.mts';
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      exclude: ['src/**/*.browser.test.{ts,tsx}'],
+      include: ['src/**/*.test.{ts,tsx}'],
+    },
+  })
+);
diff --git a/tests/app/routers/test_app_info.py b/tests/app/routers/test_app_info.py
index da493cee457..94b46b2f2ee 100644
--- a/tests/app/routers/test_app_info.py
+++ b/tests/app/routers/test_app_info.py
@@ -38,6 +38,7 @@ def test_get_external_provider_statuses(monkeypatch: Any, mock_invoker: Invoker,
     }
 
     monkeypatch.setattr("invokeai.app.api.routers.app_info.ApiDependencies", MockApiDependencies(mock_invoker))
+    monkeypatch.setattr("invokeai.app.api.auth_dependencies.ApiDependencies", MockApiDependencies(mock_invoker))
     monkeypatch.setattr(mock_invoker.services.external_generation, "get_provider_statuses", lambda: statuses)
 
     response = client.get("/api/v1/app/external_providers/status")
diff --git a/tests/app/routers/test_image_moves.py b/tests/app/routers/test_image_moves.py
index 697447269c3..9d93b6ad248 100644
--- a/tests/app/routers/test_image_moves.py
+++ b/tests/app/routers/test_image_moves.py
@@ -21,6 +21,7 @@
 from invokeai.app.services.invocation_services import InvocationServices
 from invokeai.app.services.invocation_stats.invocation_stats_default import InvocationStatsService
 from invokeai.app.services.invoker import Invoker
+from invokeai.app.services.project_records.project_records_sqlite import ProjectRecordsSqlite
 from invokeai.app.services.users.users_common import UserCreateRequest
 from invokeai.app.services.users.users_default import UserService
 from invokeai.app.services.workflow_records.workflow_records_sqlite import SqliteWorkflowRecordsStorage
@@ -78,6 +79,7 @@ def mock_services() -> InvocationServices:
         model_relationship_records=None,  # type: ignore
         model_relationships=None,  # type: ignore
         client_state_persistence=ClientStatePersistenceSqlite(db=db),
+        project_records=ProjectRecordsSqlite(db=db),
         users=UserService(db),
         image_moves=image_moves,
     )
diff --git a/tests/app/routers/test_images.py b/tests/app/routers/test_images.py
index 1e4270abff7..f533369a925 100644
--- a/tests/app/routers/test_images.py
+++ b/tests/app/routers/test_images.py
@@ -73,6 +73,7 @@ def prepare_image_maintenance_test(monkeypatch: Any, mock_invoker: Invoker) -> N
     mock_deps = MockApiDependencies(mock_invoker)
     mock_invoker.services.image_moves = MagicMock()
     mock_invoker.services.image_moves.is_maintenance_active.return_value = True
+    monkeypatch.setattr(mock_invoker.services.image_records, "exists", MagicMock(return_value=True))
     monkeypatch.setattr(mock_invoker.services.image_records, "get_user_id", MagicMock(return_value="system"))
     monkeypatch.setattr(mock_invoker.services.board_image_records, "get_board_for_image", MagicMock(return_value=None))
     monkeypatch.setattr("invokeai.app.api.routers.images.ApiDependencies", mock_deps)
diff --git a/tests/app/routers/test_multiuser_authorization.py b/tests/app/routers/test_multiuser_authorization.py
index 5a7e673b18f..10d42829d4e 100644
--- a/tests/app/routers/test_multiuser_authorization.py
+++ b/tests/app/routers/test_multiuser_authorization.py
@@ -21,6 +21,7 @@
 from invokeai.app.services.config.config_default import InvokeAIAppConfig
 from invokeai.app.services.invocation_services import InvocationServices
 from invokeai.app.services.invoker import Invoker
+from invokeai.app.services.project_records.project_records_sqlite import ProjectRecordsSqlite
 from invokeai.app.services.session_queue.session_queue_common import SessionQueueItem
 from invokeai.app.services.users.users_common import UserCreateRequest
 from invokeai.app.services.workflow_records.workflow_records_sqlite import SqliteWorkflowRecordsStorage
@@ -114,6 +115,7 @@ def mock_services() -> InvocationServices:
         model_relationship_records=None,  # type: ignore
         model_relationships=None,  # type: ignore
         client_state_persistence=ClientStatePersistenceSqlite(db=db),
+        project_records=ProjectRecordsSqlite(db=db),
         users=UserService(db),
         external_generation=None,  # type: ignore
     )
@@ -2226,15 +2228,13 @@ def test_install_allows_admin(self, client: TestClient, admin_token: str, monkey
         monkeypatch.setattr("invokeai.app.api.routers.custom_nodes._get_custom_nodes_path", lambda: tmp_path)
 
         # Simulate a successful git clone by creating the target dir with __init__.py
-        def fake_git_clone(cmd: list[str], **kwargs: Any) -> MagicMock:
+        async def fake_clone_node_pack(source: str, target_dir: Any) -> tuple[int, str]:
             target_dir = tmp_path / "test-pack"
             target_dir.mkdir(parents=True, exist_ok=True)
             (target_dir / "__init__.py").touch()
-            result = MagicMock()
-            result.returncode = 0
-            return result
+            return 0, ""
 
-        monkeypatch.setattr("invokeai.app.api.routers.custom_nodes.subprocess.run", fake_git_clone)
+        monkeypatch.setattr("invokeai.app.api.routers.custom_nodes._clone_node_pack", fake_clone_node_pack)
         monkeypatch.setattr("invokeai.app.api.routers.custom_nodes._load_node_pack", lambda *a, **kw: None)
         monkeypatch.setattr("invokeai.app.api.routers.custom_nodes._import_workflows_from_pack", lambda *a, **kw: [])
         monkeypatch.setattr("invokeai.app.api.routers.custom_nodes._write_pack_manifest", lambda *a, **kw: None)
diff --git a/tests/app/routers/test_session_queue_sanitization.py b/tests/app/routers/test_session_queue_sanitization.py
index 9fe15510589..c63cd8aa74a 100644
--- a/tests/app/routers/test_session_queue_sanitization.py
+++ b/tests/app/routers/test_session_queue_sanitization.py
@@ -4,9 +4,10 @@
 
 import pytest
 
-from invokeai.app.api.routers.session_queue import sanitize_queue_item_for_user
+from invokeai.app.api.routers.session_queue import sanitize_queue_item_for_user, strip_missing_image_results
 from invokeai.app.invocations.baseinvocation import BaseInvocation, BaseInvocationOutput, invocation, invocation_output
-from invokeai.app.invocations.fields import InputField, OutputField
+from invokeai.app.invocations.fields import ImageField, InputField, OutputField
+from invokeai.app.invocations.primitives import ImageCollectionOutput, ImageOutput
 from invokeai.app.services.session_queue.session_queue_common import NodeFieldValue, SessionQueueItem
 from invokeai.app.services.shared.graph import Graph, GraphExecutionState
 from invokeai.app.services.shared.invocation_context import InvocationContext
@@ -189,3 +190,55 @@ def test_sanitize_system_user_item_for_admin(sample_session_queue_item):
     assert result.field_values is not None
     assert len(result.field_values) == 1
     assert len(result.session.graph.nodes) == 1
+
+
+def test_sanitize_owner_strips_missing_image_results(monkeypatch, sample_session_queue_item):
+    sample_session_queue_item.session.results = {
+        "missing_node": ImageOutput(image=ImageField(image_name="missing.png"), width=64, height=64),
+        "kept_node": ImageOutput(image=ImageField(image_name="kept.png"), width=64, height=64),
+    }
+    monkeypatch.setattr(
+        "invokeai.app.api.routers.session_queue._image_record_exists",
+        lambda name: name == "kept.png",
+    )
+
+    result = sanitize_queue_item_for_user(
+        queue_item=sample_session_queue_item,
+        current_user_id="user_123",
+        is_admin=False,
+    )
+
+    assert "missing_node" not in result.session.results
+    assert "kept_node" in result.session.results
+
+
+def test_strip_missing_image_results_removes_deleted_single_image_output(sample_session_queue_item):
+    sample_session_queue_item.session.results = {
+        "missing_node": ImageOutput(image=ImageField(image_name="missing.png"), width=64, height=64),
+        "kept_node": ImageOutput(image=ImageField(image_name="kept.png"), width=64, height=64),
+    }
+
+    result = strip_missing_image_results(sample_session_queue_item, image_exists=lambda name: name == "kept.png")
+
+    assert "missing_node" not in result.session.results
+    assert "kept_node" in result.session.results
+    # The original queue item is not mutated; only the API response copy is sanitized.
+    assert "missing_node" in sample_session_queue_item.session.results
+
+
+def test_strip_missing_image_results_filters_deleted_collection_items(sample_session_queue_item):
+    sample_session_queue_item.session.results = {
+        "collection_node": ImageCollectionOutput(
+            collection=[ImageField(image_name="missing.png"), ImageField(image_name="kept.png")]
+        )
+    }
+
+    result = strip_missing_image_results(sample_session_queue_item, image_exists=lambda name: name == "kept.png")
+
+    output = result.session.results["collection_node"]
+    assert isinstance(output, ImageCollectionOutput)
+    assert output.collection == [ImageField(image_name="kept.png")]
+    assert sample_session_queue_item.session.results["collection_node"].collection == [
+        ImageField(image_name="missing.png"),
+        ImageField(image_name="kept.png"),
+    ]
diff --git a/tests/app/routers/test_session_queue_workflow_call.py b/tests/app/routers/test_session_queue_workflow_call.py
index d8fd465d8d3..2db412291aa 100644
--- a/tests/app/routers/test_session_queue_workflow_call.py
+++ b/tests/app/routers/test_session_queue_workflow_call.py
@@ -54,6 +54,7 @@ def mock_services() -> InvocationServices:
     from invokeai.app.services.images.images_default import ImageService
     from invokeai.app.services.invocation_cache.invocation_cache_memory import MemoryInvocationCache
     from invokeai.app.services.invocation_stats.invocation_stats_default import InvocationStatsService
+    from invokeai.app.services.project_records.project_records_sqlite import ProjectRecordsSqlite
     from invokeai.app.services.users.users_default import UserService
     from tests.test_nodes import TestEventService
 
@@ -91,6 +92,7 @@ def mock_services() -> InvocationServices:
         model_relationship_records=None,  # type: ignore
         model_relationships=None,  # type: ignore
         client_state_persistence=ClientStatePersistenceSqlite(db=db),
+        project_records=ProjectRecordsSqlite(db=db),
         users=UserService(db),
         external_generation=None,  # type: ignore
     )
diff --git a/tests/app/routers/test_workflows_multiuser.py b/tests/app/routers/test_workflows_multiuser.py
index 10c9fde17e7..0dd92388ff2 100644
--- a/tests/app/routers/test_workflows_multiuser.py
+++ b/tests/app/routers/test_workflows_multiuser.py
@@ -13,6 +13,7 @@
 from invokeai.app.services.config.config_default import InvokeAIAppConfig
 from invokeai.app.services.invocation_services import InvocationServices
 from invokeai.app.services.invoker import Invoker
+from invokeai.app.services.project_records.project_records_sqlite import ProjectRecordsSqlite
 from invokeai.app.services.users.users_common import UserCreateRequest
 from invokeai.app.services.workflow_records.workflow_records_sqlite import SqliteWorkflowRecordsStorage
 from invokeai.backend.util.logging import InvokeAILogger
@@ -105,6 +106,7 @@ def mock_services() -> InvocationServices:
         model_relationship_records=None,  # type: ignore
         model_relationships=None,  # type: ignore
         client_state_persistence=ClientStatePersistenceSqlite(db=db),
+        project_records=ProjectRecordsSqlite(db=db),
         users=UserService(db),
         external_generation=None,  # type: ignore
     )
diff --git a/tests/app/services/image_records/test_image_records_sqlite.py b/tests/app/services/image_records/test_image_records_sqlite.py
index 6b262d3414f..6512197e595 100644
--- a/tests/app/services/image_records/test_image_records_sqlite.py
+++ b/tests/app/services/image_records/test_image_records_sqlite.py
@@ -70,6 +70,16 @@ def test_get_many_returns_subfolders(self, store: SqliteImageRecordStorage) -> N
         assert by_name["hashed.png"] == "ab"
 
 
+class TestImageRecordExists:
+    def test_exists_returns_true_for_saved_image(self, store: SqliteImageRecordStorage) -> None:
+        _save(store, "exists.png")
+
+        assert store.exists("exists.png") is True
+
+    def test_exists_returns_false_for_missing_image(self, store: SqliteImageRecordStorage) -> None:
+        assert store.exists("missing.png") is False
+
+
 class TestDeleteIntermediatesSubfolder:
     """delete_intermediates() returns (name, subfolder) pairs and removes rows."""
 
diff --git a/tests/app/services/project_records/test_project_records.py b/tests/app/services/project_records/test_project_records.py
new file mode 100644
index 00000000000..55c2ae8f87e
--- /dev/null
+++ b/tests/app/services/project_records/test_project_records.py
@@ -0,0 +1,139 @@
+"""Tests for the project records service: CRUD, optimistic concurrency, and user isolation."""
+
+import pytest
+
+from invokeai.app.services.config.config_default import InvokeAIAppConfig
+from invokeai.app.services.project_records.project_records_common import (
+    ProjectRecordConflictError,
+    ProjectRecordExistsError,
+    ProjectRecordNotFoundError,
+)
+from invokeai.app.services.project_records.project_records_sqlite import ProjectRecordsSqlite
+from invokeai.app.services.shared.sqlite.sqlite_database import SqliteDatabase
+from invokeai.app.services.users.users_common import UserCreateRequest
+from invokeai.app.services.users.users_default import UserService
+from invokeai.backend.util.logging import InvokeAILogger
+from tests.fixtures.sqlite_database import create_mock_sqlite_database
+
+SYSTEM_USER_ID = "system"
+
+
+@pytest.fixture
+def db() -> SqliteDatabase:
+    config = InvokeAIAppConfig(use_memory_db=True)
+    return create_mock_sqlite_database(config=config, logger=InvokeAILogger.get_logger())
+
+
+@pytest.fixture
+def project_records(db: SqliteDatabase) -> ProjectRecordsSqlite:
+    return ProjectRecordsSqlite(db=db)
+
+
+@pytest.fixture
+def other_user_id(db: SqliteDatabase) -> str:
+    users = UserService(db=db)
+    user = users.create(
+        UserCreateRequest(email="other@example.com", display_name="Other", password="TestPass123", is_admin=False)
+    )
+    return user.user_id
+
+
+def test_create_and_get_roundtrip(project_records: ProjectRecordsSqlite) -> None:
+    data = {"layout": {"centerViewId": "canvas"}, "widgets": [1, 2, 3], "nested": {"a": None, "b": True}}
+
+    created = project_records.create(SYSTEM_USER_ID, "My Project", data)
+
+    assert created.name == "My Project"
+    assert created.revision == 1
+    assert created.data == data
+
+    fetched = project_records.get(SYSTEM_USER_ID, created.project_id)
+    assert fetched == created
+
+
+def test_create_with_client_id_and_duplicate_rejected(project_records: ProjectRecordsSqlite) -> None:
+    created = project_records.create(SYSTEM_USER_ID, "Imported", {"x": 1}, project_id="project-abc")
+    assert created.project_id == "project-abc"
+
+    with pytest.raises(ProjectRecordExistsError):
+        project_records.create(SYSTEM_USER_ID, "Imported again", {"x": 2}, project_id="project-abc")
+
+
+def test_same_project_id_allowed_for_different_users(project_records: ProjectRecordsSqlite, other_user_id: str) -> None:
+    project_records.create(SYSTEM_USER_ID, "Mine", {"owner": "system"}, project_id="project-shared-id")
+    other = project_records.create(other_user_id, "Theirs", {"owner": "other"}, project_id="project-shared-id")
+
+    assert project_records.get(SYSTEM_USER_ID, "project-shared-id").data == {"owner": "system"}
+    assert project_records.get(other_user_id, other.project_id).data == {"owner": "other"}
+
+
+def test_list_returns_summaries_for_own_projects_only(
+    project_records: ProjectRecordsSqlite, other_user_id: str
+) -> None:
+    first = project_records.create(SYSTEM_USER_ID, "First", {"n": 1})
+    second = project_records.create(SYSTEM_USER_ID, "Second", {"n": 2})
+    project_records.create(other_user_id, "Not mine", {"n": 3})
+
+    summaries = project_records.list(SYSTEM_USER_ID)
+
+    assert [summary.project_id for summary in summaries] == [first.project_id, second.project_id]
+    assert all(not hasattr(summary, "data") for summary in summaries)
+
+
+def test_update_increments_revision(project_records: ProjectRecordsSqlite) -> None:
+    created = project_records.create(SYSTEM_USER_ID, "Project", {"v": 1})
+
+    updated = project_records.update(
+        SYSTEM_USER_ID, created.project_id, expected_revision=1, name="Renamed", data={"v": 2}
+    )
+
+    assert updated.revision == 2
+    assert updated.name == "Renamed"
+    assert updated.data == {"v": 2}
+
+
+def test_update_with_stale_revision_raises_conflict(project_records: ProjectRecordsSqlite) -> None:
+    created = project_records.create(SYSTEM_USER_ID, "Project", {"v": 1})
+    project_records.update(SYSTEM_USER_ID, created.project_id, expected_revision=1, name="Project", data={"v": 2})
+
+    with pytest.raises(ProjectRecordConflictError) as exc_info:
+        project_records.update(SYSTEM_USER_ID, created.project_id, expected_revision=1, name="Project", data={"v": 3})
+
+    assert exc_info.value.current_revision == 2
+    # The conflicting save must not have been applied.
+    assert project_records.get(SYSTEM_USER_ID, created.project_id).data == {"v": 2}
+
+
+def test_update_missing_project_raises_not_found(project_records: ProjectRecordsSqlite) -> None:
+    with pytest.raises(ProjectRecordNotFoundError):
+        project_records.update(SYSTEM_USER_ID, "does-not-exist", expected_revision=1, name="x", data={})
+
+
+def test_get_missing_project_raises_not_found(project_records: ProjectRecordsSqlite) -> None:
+    with pytest.raises(ProjectRecordNotFoundError):
+        project_records.get(SYSTEM_USER_ID, "does-not-exist")
+
+
+def test_delete_is_idempotent(project_records: ProjectRecordsSqlite) -> None:
+    created = project_records.create(SYSTEM_USER_ID, "Doomed", {})
+
+    project_records.delete(SYSTEM_USER_ID, created.project_id)
+    project_records.delete(SYSTEM_USER_ID, created.project_id)
+
+    with pytest.raises(ProjectRecordNotFoundError):
+        project_records.get(SYSTEM_USER_ID, created.project_id)
+
+
+def test_users_cannot_touch_each_others_projects(project_records: ProjectRecordsSqlite, other_user_id: str) -> None:
+    created = project_records.create(SYSTEM_USER_ID, "Private", {"secret": True})
+
+    with pytest.raises(ProjectRecordNotFoundError):
+        project_records.get(other_user_id, created.project_id)
+
+    with pytest.raises(ProjectRecordNotFoundError):
+        project_records.update(other_user_id, created.project_id, expected_revision=1, name="Stolen", data={})
+
+    # Deleting someone else's project is a silent no-op for the other user...
+    project_records.delete(other_user_id, created.project_id)
+    # ...and the owner's project is untouched.
+    assert project_records.get(SYSTEM_USER_ID, created.project_id).data == {"secret": True}
diff --git a/tests/app/services/session_queue/test_session_queue_status_event_isolation.py b/tests/app/services/session_queue/test_session_queue_status_event_isolation.py
index ecef76f1eb3..14f2cbec1ec 100644
--- a/tests/app/services/session_queue/test_session_queue_status_event_isolation.py
+++ b/tests/app/services/session_queue/test_session_queue_status_event_isolation.py
@@ -200,7 +200,7 @@ def test_event_redacts_when_current_item_disappears_between_reads(
     # item; the redaction read returns None as if B finished in between.
     call_count = {"n": 0}
 
-    def racey_get_current(queue_id: str) -> Optional[SessionQueueItem]:
+    def racey_get_current(queue_id: str, origin_prefix: Optional[str] = None) -> Optional[SessionQueueItem]:
         call_count["n"] += 1
         if call_count["n"] == 1:
             return b_snapshot
diff --git a/tests/app/services/test_image_move_startup_safety.py b/tests/app/services/test_image_move_startup_safety.py
index f7f673322ea..a72661bf665 100644
--- a/tests/app/services/test_image_move_startup_safety.py
+++ b/tests/app/services/test_image_move_startup_safety.py
@@ -37,6 +37,7 @@ def _services(**overrides):
         "style_preset_image_files": object(),
         "workflow_thumbnails": object(),
         "client_state_persistence": object(),
+        "project_records": object(),
         "users": object(),
         "image_moves": None,
     }
diff --git a/tests/backend/image_util/segment_anything/test_segment_anything_2_pipeline.py b/tests/backend/image_util/segment_anything/test_segment_anything_2_pipeline.py
new file mode 100644
index 00000000000..0c6587abf98
--- /dev/null
+++ b/tests/backend/image_util/segment_anything/test_segment_anything_2_pipeline.py
@@ -0,0 +1,104 @@
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+import torch
+from PIL import Image
+
+from invokeai.backend.image_util.segment_anything.segment_anything_2_pipeline import SegmentAnything2Pipeline
+from invokeai.backend.image_util.segment_anything.shared import BoundingBox, SAMInput, SAMPoint, SAMPointLabel
+
+
+class FakeProcessedInputs(dict[str, torch.Tensor]):
+    def __init__(self) -> None:
+        original_sizes = torch.tensor([[5, 4]])
+        super().__init__(pixel_values=torch.ones(1, 3, 5, 4), original_sizes=original_sizes)
+        self.original_sizes = original_sizes
+        self.to_device: torch.device | None = None
+
+    def to(self, device: torch.device) -> "FakeProcessedInputs":
+        self.to_device = device
+        return self
+
+
+class FakeProcessor:
+    def __init__(self, processed_inputs: FakeProcessedInputs, masks: torch.Tensor) -> None:
+        self.processed_inputs = processed_inputs
+        self.masks = masks
+        self.input_kwargs: dict[str, Any] | None = None
+        self.post_process_kwargs: dict[str, Any] | None = None
+
+    def __call__(self, **kwargs: Any) -> FakeProcessedInputs:
+        self.input_kwargs = kwargs
+        return self.processed_inputs
+
+    def post_process_masks(self, *, masks: torch.Tensor, original_sizes: torch.Tensor) -> list[torch.Tensor]:
+        self.post_process_kwargs = {"masks": masks, "original_sizes": original_sizes}
+        return [self.masks]
+
+
+class FakeModel:
+    def __init__(self, pred_masks: torch.Tensor) -> None:
+        self.device = torch.device("cpu")
+        self.pred_masks = pred_masks
+        self.call_kwargs: dict[str, Any] | None = None
+
+    def __call__(self, **kwargs: Any) -> SimpleNamespace:
+        self.call_kwargs = kwargs
+        return SimpleNamespace(pred_masks=self.pred_masks)
+
+
+@pytest.mark.parametrize(
+    ("sam_input", "expected_points", "expected_labels", "expected_boxes"),
+    [
+        (
+            SAMInput(
+                points=[
+                    SAMPoint(x=1, y=2, label=SAMPointLabel.positive),
+                    SAMPoint(x=3, y=4, label=SAMPointLabel.negative),
+                ]
+            ),
+            [[[[1, 2], [3, 4]]]],
+            [[[1, -1]]],
+            None,
+        ),
+        (
+            SAMInput(bounding_box=BoundingBox(x_min=1, y_min=2, x_max=3, y_max=4)),
+            None,
+            None,
+            [[[1, 2, 3, 4]]],
+        ),
+    ],
+)
+def test_segment_uses_current_sam2_processor_contract(
+    sam_input: SAMInput,
+    expected_points: list[list[list[list[int]]]] | None,
+    expected_labels: list[list[list[int]]] | None,
+    expected_boxes: list[list[list[int]]] | None,
+) -> None:
+    processed_inputs = FakeProcessedInputs()
+    pred_masks = torch.rand(1, 2, 3, 2, 2)
+    expected_masks = torch.ones(2, 3, 5, 4, dtype=torch.bool)
+    processor = FakeProcessor(processed_inputs, expected_masks)
+    model = FakeModel(pred_masks)
+    pipeline = SegmentAnything2Pipeline(model, processor)  # type: ignore[arg-type]
+    image = Image.new("RGB", (4, 5))
+
+    masks = pipeline.segment(image, [sam_input])
+
+    assert processor.input_kwargs == {
+        "images": image,
+        "input_boxes": expected_boxes,
+        "input_points": expected_points,
+        "input_labels": expected_labels,
+        "return_tensors": "pt",
+    }
+    assert processed_inputs.to_device == model.device
+    assert model.call_kwargs == dict(processed_inputs)
+    assert processor.post_process_kwargs == {
+        "masks": pred_masks,
+        "original_sizes": processed_inputs.original_sizes,
+    }
+    assert masks is expected_masks
+    assert masks.dtype == torch.bool
+    assert masks.shape == (2, 3, 5, 4)
diff --git a/tests/backend/model_manager/load/model_cache/test_model_cache_drop_model.py b/tests/backend/model_manager/load/model_cache/test_model_cache_drop_model.py
index 1a2ba34c011..17c674c235c 100644
--- a/tests/backend/model_manager/load/model_cache/test_model_cache_drop_model.py
+++ b/tests/backend/model_manager/load/model_cache/test_model_cache_drop_model.py
@@ -169,6 +169,34 @@ def test_drop_model_updates_stats_and_fires_callbacks(cache: ModelCache):
     assert kwargs["bytes_freed"] > 0
 
 
+def test_make_room_returns_clear_result_and_updates_current_cache_usage(cache: ModelCache):
+    cache.put("model-a", torch.nn.Linear(4, 4))
+    cache.put("model-b", torch.nn.Linear(4, 4))
+    cache.stats = CacheStats()
+    before_bytes = cache._get_ram_in_use()
+
+    result = cache.make_room(1000 * 2**30)
+
+    assert result.models_cleared == 2
+    assert result.bytes_freed == before_bytes
+    assert cache.stats.in_cache == 0
+    assert cache.stats.cache_used == 0
+
+
+def test_make_room_reports_noop_when_all_models_are_locked(cache: ModelCache):
+    cache.put("model-a", torch.nn.Linear(4, 4))
+    entry = cache._cached_models["model-a"]
+    entry.lock()
+    cache.stats = CacheStats()
+
+    result = cache.make_room(1000 * 2**30)
+
+    assert result.models_cleared == 0
+    assert result.bytes_freed == 0
+    assert cache.stats.in_cache == 1
+    assert cache.stats.cache_used > 0
+
+
 def test_unlock_stale_eviction_updates_stats_and_fires_callbacks(cache: ModelCache):
     """Stale-entry eviction is also a cache change observers care about."""
     model_key = "abc123"
diff --git a/tests/conftest.py b/tests/conftest.py
index 80df0aa93e9..a65c0cd483d 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -23,6 +23,7 @@
 from invokeai.app.services.invocation_services import InvocationServices
 from invokeai.app.services.invocation_stats.invocation_stats_default import InvocationStatsService
 from invokeai.app.services.invoker import Invoker
+from invokeai.app.services.project_records.project_records_sqlite import ProjectRecordsSqlite
 from invokeai.app.services.users.users_default import UserService
 from invokeai.app.services.workflow_records.workflow_records_sqlite import SqliteWorkflowRecordsStorage
 from invokeai.backend.util.logging import InvokeAILogger
@@ -69,6 +70,7 @@ def mock_services() -> InvocationServices:
         model_relationship_records=None,  # type: ignore
         model_relationships=None,  # type: ignore
         client_state_persistence=ClientStatePersistenceSqlite(db=db),
+        project_records=ProjectRecordsSqlite(db=db),
         users=UserService(db),
     )